Upload 24 files

routers/__init__.py

@@ -0,0 +1,3 @@
+# Paquete de routers para PetAlert API
+
+

routers/ai_search.py

@@ -0,0 +1,578 @@
+"""
+Router de Búsqueda con IA
+==========================
+
+Este router maneja búsquedas inteligentes de mascotas usando inteligencia artificial.
+Utiliza MegaDescriptor para generar embeddings de imágenes y busca coincidencias
+visuales entre reportes de mascotas perdidas y encontradas.
+
+Funcionalidades principales:
+- Búsqueda por imagen usando embeddings de MegaDescriptor
+- Cálculo de similitud visual entre imágenes
+- Filtrado por ubicación geográfica (Haversine)
+- Cálculo de scores combinados (visual, color, ubicación, tiempo)
+- Búsqueda de matches automáticos entre reportes
+
+Flujo de búsqueda:
+1. Usuario sube una imagen de una mascota
+2. Se genera embedding usando MegaDescriptor
+3. Se buscan reportes similares usando búsqueda vectorial (pgvector)
+4. Se calculan scores de similitud (visual, color, ubicación, tiempo)
+5. Se ordenan y filtran los resultados
+6. Se retornan los mejores matches
+
+El sistema usa embeddings de 1536 dimensiones generados por MegaDescriptor-L-384.
+"""
+
+# =========================
+# Imports de FastAPI
+# =========================
+from fastapi import APIRouter, File, HTTPException, Query, UploadFile
+
+# =========================
+# Imports de Python estándar
+# =========================
+import math  # Para cálculos matemáticos (Haversine)
+import os  # Para variables de entorno
+import sys  # Para manipular el path de Python
+import traceback  # Para debugging
+
+# =========================
+# Imports de pathlib
+# =========================
+from pathlib import Path  # Para trabajar con rutas de forma multiplataforma
+
+# =========================
+# Imports de tipos
+# =========================
+from typing import Any, Dict, List, Optional  # Para type hints
+
+# =========================
+# Imports de Supabase
+# =========================
+from supabase import Client  # Cliente de Supabase
+
+# Agregar la carpeta parent al path para poder importar utils
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# =========================
+# Imports de servicios
+# =========================
+from services.embeddings import image_bytes_to_vec  # Generar embeddings con MegaDescriptor
+
+# Crear el router con prefijo /ai-search
+router = APIRouter(prefix="/ai-search", tags=["ai-search"])
+
+def _sb() -> Client:
+    """Crea un cliente de Supabase con configuración optimizada de timeouts"""
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+def _coords(loc: Optional[dict]) -> Optional[tuple]:
+    """
+    Extrae coordenadas de un objeto de ubicación en formato GeoJSON.
+    
+    GeoJSON usa el formato: {"type": "Point", "coordinates": [longitud, latitud]}
+    Esta función extrae las coordenadas y las retorna como tupla (lat, lon).
+    
+    Args:
+        loc: Objeto de ubicación GeoJSON o None
+        
+    Returns:
+        Tupla (latitud, longitud) o None si no se pueden extraer
+        
+    Ejemplo:
+        >>> _coords({"type": "Point", "coordinates": [-58.3816, -34.6037]})
+        (-34.6037, -58.3816)  # (lat, lon)
+    """
+    # Verificar que sea un diccionario con la clave "coordinates"
+    if isinstance(loc, dict) and "coordinates" in loc:
+        # GeoJSON usa [lon, lat], pero retornamos (lat, lon) para consistencia
+        lon, lat = loc["coordinates"]
+        return (lat, lon)  # Retornar como (latitud, longitud)
+    return None  # Si no es un formato válido, retornar None
+
+def haversine_km(lat1, lon1, lat2, lon2):
+    """
+    Calcula la distancia en kilómetros entre dos puntos geográficos usando la fórmula de Haversine.
+    
+    La fórmula de Haversine calcula la distancia del círculo máximo (great circle distance)
+    entre dos puntos en una esfera, considerando que la Tierra es una esfera perfecta.
+    Es más precisa que calcular distancia euclidiana simple para coordenadas geográficas.
+    
+    Args:
+        lat1, lon1: Latitud y longitud del primer punto (en grados)
+        lat2, lon2: Latitud y longitud del segundo punto (en grados)
+        
+    Returns:
+        Distancia en kilómetros entre los dos puntos
+        
+    Ejemplo:
+        >>> # Distancia entre Buenos Aires y Córdoba (Argentina)
+        >>> haversine_km(-34.6037, -58.3816, -31.4201, -64.1888)
+        ~700 km
+    """
+    R = 6371.0  # Radio de la Tierra en kilómetros
+    # Convertir diferencias de latitud y longitud a radianes
+    dlat = math.radians(lat2 - lat1)  # Diferencia de latitud en radianes
+    dlon = math.radians(lon2 - lon1)  # Diferencia de longitud en radianes
+    # Aplicar la fórmula de Haversine
+    # a = sin²(Δlat/2) + cos(lat1) * cos(lat2) * sin²(Δlon/2)
+    a = math.sin(dlat/2)**2 + math.cos(math.radians(lat1)) * math.cos(math.radians(lat2)) * math.sin(dlon/2)**2
+    # Distancia = 2 * R * arcsin(√a)
+    return 2 * R * math.asin(math.sqrt(a))
+
+def label_set(labels_json) -> set:
+    """
+    Convierte etiquetas JSON a un conjunto de strings normalizados.
+    
+    Las etiquetas pueden venir en diferentes formatos JSON.
+    Esta función normaliza y extrae las etiquetas como un set de strings en minúsculas.
+    
+    Args:
+        labels_json: Objeto JSON con etiquetas (puede ser dict con "labels" o lista)
+        
+    Returns:
+        Set de strings en minúsculas con las etiquetas
+        
+    Ejemplo:
+        >>> label_set({"labels": [{"label": "Perro"}, {"description": "Golden Retriever"}]})
+        {"perro", "golden retriever"}
+    """
+    # Si no hay etiquetas, retornar set vacío
+    if not labels_json:
+        return set()
+    
+    # Intentar obtener la lista de etiquetas del objeto JSON
+    # Puede venir como {"labels": [...]} o directamente como lista
+    items = labels_json.get("labels") if isinstance(labels_json, dict) else None
+    
+    # Si no es una lista válida, retornar set vacío
+    if not isinstance(items, list):
+        return set()
+    
+    # Extraer etiquetas: buscar "label" o "description" en cada item
+    # Convertir a minúsculas para comparaciones case-insensitive
+    # Filtrar items vacíos o None
+    return {(it.get("label") or it.get("description") or "").lower() for it in items if it}
+
+def color_set(colors_json) -> set:
+    """Convierte colores JSON a un conjunto de strings."""
+    if not colors_json:
+        return set()
+    if isinstance(colors_json, list):
+        return set(color.lower() for color in colors_json if color)
+    return set()
+
+def calculate_visual_similarity(analysis_labels, candidate_labels):
+    """
+    Calcula similitud visual entre dos conjuntos de etiquetas usando el coeficiente de Jaccard.
+    
+    El coeficiente de Jaccard mide la similitud entre dos conjuntos:
+    J(A,B) = |A ∩ B| / |A ∪ B|
+    
+    Esto da un valor entre 0 (sin similitud) y 1 (idénticos).
+    Se multiplica por 100 para obtener un porcentaje.
+    
+    Args:
+        analysis_labels: Etiquetas de la imagen de búsqueda (JSON)
+        candidate_labels: Etiquetas del reporte candidato (JSON)
+        
+    Returns:
+        Porcentaje de similitud (0-100)
+        
+    Ejemplo:
+        >>> calculate_visual_similarity(
+        ...     {"labels": [{"label": "Perro"}, {"label": "Dorado"}]},
+        ...     {"labels": [{"label": "Perro"}, {"label": "Labrador"}]}
+        ... )
+        33.33  # 1 etiqueta en común de 3 totales (perro, dorado, labrador)
+    """
+    # Si alguno de los conjuntos está vacío, no hay similitud
+    if not analysis_labels or not candidate_labels:
+        return 0
+    
+    # Convertir a sets de strings normalizados
+    set1 = label_set(analysis_labels)  # Etiquetas de la imagen de búsqueda
+    set2 = label_set(candidate_labels)  # Etiquetas del candidato
+    
+    # Si alguno de los sets está vacío después de la conversión, no hay similitud
+    if not set1 or not set2:
+        return 0
+    
+    # Calcular intersección (etiquetas en común) y unión (todas las etiquetas)
+    intersection = len(set1 & set2)  # Etiquetas que aparecen en ambos
+    union = len(set1 | set2)  # Todas las etiquetas únicas (sin duplicados)
+    
+    # Evitar división por cero
+    if union == 0:
+        return 0
+    
+    # Coeficiente de Jaccard multiplicado por 100 para obtener porcentaje
+    return (intersection / union) * 100
+
+def calculate_color_similarity(analysis_colors, candidate_colors):
+    """Calcula similitud de colores entre dos conjuntos."""
+    if not analysis_colors or not candidate_colors:
+        return 0
+    
+    set1 = color_set(analysis_colors)
+    set2 = color_set(candidate_colors)
+    
+    if not set1 or not set2:
+        return 0
+    
+    intersection = len(set1 & set2)
+    union = len(set1 | set2)
+    
+    if union == 0:
+        return 0
+    
+    return (intersection / union) * 100
+
+def calculate_location_score(distance_km, max_distance_km=50):
+    """Calcula puntuación de ubicación basada en distancia."""
+    if distance_km <= 0:
+        return 100
+    if distance_km >= max_distance_km:
+        return 0
+    
+    # Puntuación decrece linealmente con la distancia
+    return max(0, 100 - (distance_km / max_distance_km) * 100)
+
+def calculate_time_score(created_at):
+    """Calcula puntuación basada en la antigüedad del reporte."""
+    from datetime import datetime, timezone
+    
+    try:
+        if isinstance(created_at, str):
+            report_date = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+        else:
+            report_date = created_at
+        
+        now = datetime.now(timezone.utc)
+        days_old = (now - report_date).days
+        
+        # Reportes más recientes tienen mayor puntuación
+        if days_old <= 1:
+            return 100
+        elif days_old <= 7:
+            return 80
+        elif days_old <= 30:
+            return 60
+        else:
+            return 40
+    except:
+        return 50  # Puntuación neutral si hay error
+
+@router.post("/")
+async def ai_search(
+    file: UploadFile = File(...),  # Archivo de imagen subido por el usuario
+    user_lat: float = Query(...),  # Latitud del usuario (requerida)
+    user_lng: float = Query(...),  # Longitud del usuario (requerida)
+    radius_km: float = Query(10.0),  # Radio de búsqueda en kilómetros (default: 10km)
+    search_type: str = Query("both")  # Tipo de búsqueda: 'lost', 'found', o 'both' (default: 'both')
+):
+    """
+    Endpoint principal de búsqueda con IA.
+    
+    Este endpoint permite buscar mascotas similares subiendo una imagen.
+    El proceso es:
+    1. Recibe una imagen del usuario
+    2. Genera un embedding usando MegaDescriptor
+    3. Busca reportes similares usando búsqueda vectorial en Supabase
+    4. Calcula scores de similitud (visual, ubicación, tiempo)
+    5. Filtra por radio geográfico
+    6. Retorna los mejores matches ordenados por score total
+    
+    Args:
+        file: Imagen de la mascota a buscar (JPEG, PNG, etc.)
+        user_lat: Latitud del usuario (para filtrar por distancia)
+        user_lng: Longitud del usuario (para filtrar por distancia)
+        radius_km: Radio máximo de búsqueda en kilómetros (default: 10km)
+        search_type: Tipo de reportes a buscar:
+            - 'lost': Solo reportes de mascotas perdidas
+            - 'found': Solo reportes de mascotas encontradas
+            - 'both': Ambos tipos (default)
+    
+    Returns:
+        JSON con:
+        - analysis: Datos del análisis de la imagen
+        - matches: Lista de reportes similares ordenados por score
+        - total_matches: Número total de matches encontrados
+    
+    Raises:
+        HTTPException 400: Si los parámetros son inválidos
+        HTTPException 500: Si hay error procesando la imagen o buscando
+    """
+    try:
+        # =========================
+        # Validación de parámetros
+        # =========================
+        # Validar que el tipo de búsqueda sea uno de los valores permitidos
+        if search_type not in ['lost', 'found', 'both']:
+            raise HTTPException(400, "search_type debe ser 'lost', 'found' o 'both'")
+        
+        # =========================
+        # Procesar la imagen
+        # =========================
+        # Leer el contenido del archivo subido
+        # UploadFile.read() retorna los bytes de la imagen
+        content = await file.read()
+        
+        # Validar que el archivo no esté vacío
+        if not content:
+            raise HTTPException(400, "Archivo vacío o no leído")
+        
+        # =========================
+        # Generar embedding con MegaDescriptor
+        # =========================
+        # Importar la función para generar embeddings
+        # MegaDescriptor convierte la imagen en un vector numérico de 1536 dimensiones
+        from services.embeddings import image_bytes_to_vec
+        
+        # Generar el embedding de la imagen de búsqueda
+        # Esto puede tardar 1-3 segundos dependiendo del hardware
+        query_embedding = image_bytes_to_vec(content)
+        
+        # =========================
+        # Buscar reportes similares
+        # =========================
+        # Obtener cliente de Supabase
+        sb = _sb()
+        
+        # Convertir el embedding de numpy array a lista de Python
+        # Supabase RPC requiere una lista, no un numpy array
+        query_vector = query_embedding.tolist()
+        
+        # Buscar reportes similares usando la función RPC de Supabase
+        # search_similar_reports es una función PostgreSQL que usa pgvector
+        # para buscar vectores similares usando distancia coseno
+        try:
+            similar_reports = sb.rpc(
+                'search_similar_reports',  # Nombre de la función RPC en Supabase
+                {
+                    'query_embedding': query_vector,  # Embedding de la imagen de búsqueda
+                    'match_threshold': 0.6,  # Umbral mínimo de similitud (60%)
+                    'match_count': 50  # Máximo de candidatos a retornar
+                }
+            ).execute()
+            
+            # Extraer los datos de la respuesta
+            # Si no hay datos, usar lista vacía
+            candidates = similar_reports.data if similar_reports.data else []
+        except Exception as e:
+            # Si falla la búsqueda por embedding (error en RPC, base de datos, etc.)
+            # Hacer una búsqueda simple sin embeddings como fallback
+            # Esto asegura que siempre haya resultados, aunque sean menos precisos
+            candidates = []
+        
+        # =========================
+        # Preparar datos de análisis
+        # =========================
+        # Crear objeto con información del análisis
+        # Nota: Ya no usamos Google Vision, así que labels y colors están vacíos
+        analysis_data = {
+            "labels": [],  # Etiquetas detectadas (vacío, ya no usamos Google Vision)
+            "colors": [],  # Colores detectados (vacío, ya no usamos Google Vision)
+            "species": "other",  # Especie detectada (se actualizará con los candidatos)
+            "file_name": file.filename,  # Nombre del archivo subido
+            "file_size": len(content),  # Tamaño del archivo en bytes
+            "method": "embedding_similarity"  # Método usado: búsqueda por embeddings
+        }
+        
+        # =========================
+        # Filtrar candidatos
+        # =========================
+        # Filtrar candidatos por tipo de búsqueda si no es "both"
+        # Si el usuario busca solo "lost", excluir reportes "found" y viceversa
+        if search_type != "both":
+            candidates = [c for c in candidates if c.get("type") == search_type]
+        
+        # =========================
+        # Fallback: búsqueda simple
+        # =========================
+        # Si no hay candidatos por embedding (falló la búsqueda vectorial o no hay matches)
+        # Hacer una búsqueda simple por tipo de reporte
+        # Esto asegura que siempre haya resultados para mostrar
+        if not candidates:
+            # Construir query para obtener reportes activos
+            query = sb.table("reports").select("*").eq("status", "active")
+            
+            # Si el tipo de búsqueda no es "both", filtrar por tipo
+            if search_type != "both":
+                query = query.eq("type", search_type)
+            
+            # Ejecutar la query y obtener los resultados
+            candidates = query.execute().data
+        
+        # =========================
+        # Detectar especie
+        # =========================
+        # Intentar detectar la especie del primer candidato más similar
+        # Esto ayuda a mejorar los filtros posteriores
+        detected_species = None
+        if candidates:
+            # Obtener la especie del primer candidato (el más similar)
+            # Si no tiene especie, usar "other" por defecto
+            detected_species = candidates[0].get("species", "other")
+        
+        # Actualizar análisis con la especie detectada
+        analysis_data["species"] = detected_species or "other"
+        
+        # Filtrar por distancia y calcular puntuaciones
+        results = []
+        for candidate in candidates:
+            candidate_coords = _coords(candidate.get("location"))
+            if not candidate_coords:
+                continue
+            
+            cand_lat, cand_lng = candidate_coords
+            distance_km = haversine_km(user_lat, user_lng, cand_lat, cand_lng)
+            
+            if distance_km > radius_km:
+                continue
+            
+            # Calcular puntuaciones basadas en similitud de embedding
+            # Si el candidato viene de la búsqueda por embedding, ya tiene similitud
+            if "similarity" in candidate:
+                visual_score = candidate["similarity"] * 100
+            else:
+                # Calcular similitud de embedding si está disponible
+                visual_score = 50  # Puntuación neutral si no hay embedding
+            
+            # Similitud de colores (usar colores guardados en el reporte si existen)
+            candidate_colors = candidate.get("colors", [])
+            color_score = calculate_color_similarity(
+                [],  # No tenemos colores de la imagen de búsqueda
+                candidate_colors
+            ) if candidate_colors else 0
+            
+            location_score = calculate_location_score(distance_km, radius_km)
+            time_score = calculate_time_score(candidate.get("created_at"))
+            
+            # Puntuación total ponderada
+            total_score = (
+                visual_score * 0.4 +      # 40% similitud visual
+                color_score * 0.3 +       # 30% similitud de colores
+                location_score * 0.2 +    # 20% proximidad geográfica
+                time_score * 0.1          # 10% relevancia temporal
+            )
+            
+            # Solo incluir resultados con puntuación mínima
+            if total_score >= 30:  # Umbral mínimo de relevancia
+                results.append({
+                    "candidate": {
+                        "id": candidate["id"],
+                        "pet_name": candidate.get("pet_name"),
+                        "species": candidate.get("species"),
+                        "breed": candidate.get("breed"),
+                        "color": candidate.get("color"),
+                        "size": candidate.get("size"),
+                        "description": candidate.get("description"),
+                        "location": candidate.get("location"),
+                        "photos": candidate.get("photos", []),
+                        "labels": candidate.get("labels"),
+                        "reporter_id": candidate.get("reporter_id"),
+                        "created_at": candidate.get("created_at"),
+                    },
+                    "distance_km": round(distance_km, 2),
+                    "visual_similarity": round(visual_score, 1),
+                    "color_similarity": round(color_score, 1),
+                    "location_score": round(location_score, 1),
+                    "time_score": round(time_score, 1),
+                    "total_score": round(total_score, 1),
+                    "match_confidence": "Alta" if total_score >= 70 else "Media" if total_score >= 50 else "Baja"
+                })
+        
+        # Ordenar por puntuación total
+        results.sort(key=lambda x: x["total_score"], reverse=True)
+        
+        # Limitar resultados a los mejores 20
+        top_results = results[:20]
+        
+        return {
+            "analysis": analysis_data,
+            "matches": top_results,
+            "search_metadata": {
+                "total_candidates": len(candidates),
+                "filtered_results": len(results),
+                "returned_results": len(top_results),
+                "search_type": search_type,
+                "radius_km": radius_km,
+                "user_location": {"lat": user_lat, "lng": user_lng},
+                "detected_species": detected_species,
+                "analysis_confidence": "Alta" if len(candidates) > 0 else "Baja"
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        traceback.print_exc()
+        raise HTTPException(500, f"Error en búsqueda IA: {str(e)}")
+
+@router.get("/health")
+async def ai_search_health():
+    """Verifica el estado del servicio de búsqueda IA."""
+    try:
+        # Verificar conexión a Supabase
+        sb = _sb()
+        test_query = sb.table("reports").select("id").limit(1).execute()
+        
+        return {
+            "status": "ok",
+            "message": "Servicio de búsqueda IA funcionando",
+            "supabase": "conectado" if test_query.data is not None else "error",
+            "method": "embedding_similarity",
+            "endpoints": {
+                "ai_search": "/ai-search/",
+                "health": "/ai-search/health"
+            }
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Error en servicio IA: {str(e)}",
+            "supabase": "error"
+        }
+
+@router.post("/similarity")
+async def calculate_similarity(
+    labels1: List[Dict[str, Any]] = None,
+    labels2: List[Dict[str, Any]] = None,
+    colors1: List[str] = None,
+    colors2: List[str] = None
+):
+    """
+    Calcula similitud entre dos conjuntos de etiquetas y colores.
+    Útil para testing y debugging.
+    """
+    try:
+        visual_similarity = calculate_visual_similarity(
+            {"labels": labels1 or []}, 
+            {"labels": labels2 or []}
+        )
+        
+        color_similarity = calculate_color_similarity(
+            colors1 or [], 
+            colors2 or []
+        )
+        
+        return {
+            "visual_similarity": round(visual_similarity, 1),
+            "color_similarity": round(color_similarity, 1),
+            "combined_score": round((visual_similarity + color_similarity) / 2, 1),
+            "inputs": {
+                "labels1": labels1,
+                "labels2": labels2,
+                "colors1": colors1,
+                "colors2": colors2
+            }
+        }
+    except Exception as e:
+        raise HTTPException(500, f"Error calculando similitud: {str(e)}")
+

routers/direct_matches.py

@@ -0,0 +1,300 @@
+"""
+Router para Búsqueda Directa de Coincidencias usando Embeddings
+================================================================
+
+Este router permite buscar coincidencias directamente usando los embeddings
+ya almacenados en Supabase, sin necesidad de generar nuevos embeddings.
+
+A diferencia de /ai-search que genera embeddings de una imagen nueva,
+este router usa embeddings pre-existentes para buscar matches más rápido.
+
+Funcionalidades:
+- Buscar matches para un reporte usando su embedding existente
+- Búsqueda vectorial usando distancia coseno
+- Filtrado por tipo (lost/found) y especie
+- Configuración de umbral de similitud y número de resultados
+"""
+
+from fastapi import APIRouter, HTTPException, Query
+from typing import Optional, List, Dict, Any
+import os
+from supabase import Client
+import numpy as np  # Para operaciones con vectores
+import sys
+from pathlib import Path
+
+# Agregar la carpeta parent al path para poder importar utils
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# Crear el router con prefijo /direct-matches
+router = APIRouter(prefix="/direct-matches", tags=["direct-matches"])
+
+def _sb() -> Client:
+    """
+    Crea un cliente de Supabase con configuración optimizada de timeouts.
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        HTTPException: Si no se puede conectar a Supabase
+    """
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+@router.post("/find/{report_id}")
+async def find_matches_for_report(
+    report_id: str,  # ID del reporte para buscar matches
+    match_threshold: float = Query(0.1, ge=0.0, le=1.0, description="Umbral mínimo de similitud (0.0-1.0)"),
+    top_k: int = Query(10, ge=1, le=50, description="Número máximo de resultados a retornar")
+):
+    """
+    Busca coincidencias para un reporte específico usando su embedding existente.
+    
+    Este endpoint es más rápido que /ai-search porque usa embeddings ya generados
+    en lugar de generar uno nuevo desde una imagen.
+    
+    El proceso es:
+    1. Obtiene el embedding del reporte base
+    2. Busca reportes del tipo opuesto (lost/found) con embeddings
+    3. Calcula similitud usando distancia coseno
+    4. Filtra por umbral de similitud y especie
+    5. Retorna los mejores matches ordenados por similitud
+    
+    Args:
+        report_id: ID del reporte para buscar matches
+        match_threshold: Umbral mínimo de similitud (0.0 = cualquier similitud, 1.0 = idéntico)
+        top_k: Número máximo de matches a retornar
+        
+    Returns:
+        JSON con:
+        - report_id: ID del reporte base
+        - matches: Lista de matches encontrados ordenados por similitud
+        - total_candidates: Número total de candidatos evaluados
+        - message: Mensaje informativo
+    """
+    try:
+        sb = _sb()
+        
+        # =========================
+        # Obtener reporte base
+        # =========================
+        # Obtener el reporte base con su embedding y datos relevantes
+        base_result = sb.table("reports")\
+            .select("id, embedding, type, species, photos, pet_name, description, color")\
+            .eq("id", report_id)\
+            .single()\
+            .execute()
+        
+        # Verificar que el reporte existe
+        if not base_result.data:
+            raise HTTPException(404, f"Reporte {report_id} no encontrado")
+        
+        base_report = base_result.data
+        base_embedding = base_report.get("embedding")
+        
+        # Verificar que el reporte tiene embedding
+        if not base_embedding:
+            raise HTTPException(400, f"El reporte {report_id} no tiene embedding generado")
+        
+        # =========================
+        # Parsear embedding
+        # =========================
+        # Postgrest devuelve vectores como strings JSON, necesitamos parsearlos
+        # Esto es necesario porque pgvector almacena los vectores como JSON en Supabase
+        if isinstance(base_embedding, str):
+            import json
+            try:
+                base_embedding = json.loads(base_embedding)
+            except:
+                raise HTTPException(400, f"El reporte {report_id} tiene un embedding inválido")
+        
+        # Extraer datos del reporte base
+        base_type = base_report.get("type")  # "lost" o "found"
+        base_species = base_report.get("species")  # "dog", "cat", etc.
+        
+        # Determinar el tipo opuesto para buscar
+        # Si el reporte base es "lost", buscar "found" y viceversa
+        target_type = "found" if base_type == "lost" else "lost"
+        
+        # Log para debugging
+        print(f"🔍 [direct-match] Buscando coincidencias para reporte {report_id}")
+        print(f"   Tipo base: {base_type}, buscando: {target_type}")
+        print(f"   Especie: {base_species}")
+        print(f"   Dimensiones embedding: {len(base_embedding)}")
+        
+        # =========================
+        # Buscar candidatos
+        # =========================
+        # Obtener todos los reportes del tipo opuesto que tengan embeddings
+        candidates_result = sb.table("reports")\
+            .select("id, embedding, species, type, photos, pet_name, description, color, created_at")\
+            .eq("type", target_type)\
+            .eq("status", "active")\
+            .not_.is_("embedding", "null")\
+            .execute()
+        
+        # Si no hay candidatos, retornar respuesta vacía
+        if not candidates_result.data:
+            return {
+                "report_id": report_id,
+                "matches": [],
+                "total_candidates": 0,
+                "message": f"No hay reportes de tipo '{target_type}' con embeddings"
+            }
+        
+        candidates = candidates_result.data
+        print(f"   Candidatos encontrados: {len(candidates)}")
+        
+        # =========================
+        # Filtrar por especie
+        # =========================
+        # Filtrar candidatos por especie si el reporte base tiene especie
+        # Esto mejora la precisión de los matches
+        if base_species:
+            candidates = [c for c in candidates if c.get("species") == base_species]
+            print(f"   Candidatos después de filtrar por especie: {len(candidates)}")
+        
+        # =========================
+        # Calcular similitudes
+        # =========================
+        # Convertir embedding base a numpy array para cálculos vectoriales
+        base_vec = np.array(base_embedding, dtype=np.float32)
+        base_norm = np.linalg.norm(base_vec)  # Norma del vector (para normalización)
+        
+        # Calcular similitud con cada candidato
+        matches = []
+        for candidate in candidates:
+            # Evitar comparar consigo mismo
+            if candidate["id"] == report_id:
+                continue
+            
+            candidate_embedding = candidate.get("embedding")
+            if not candidate_embedding:
+                continue
+            
+            # Parsear si es string JSON
+            if isinstance(candidate_embedding, str):
+                import json
+                try:
+                    candidate_embedding = json.loads(candidate_embedding)
+                except:
+                    continue
+            
+            try:
+                # Convertir embedding del candidato a numpy
+                candidate_vec = np.array(candidate_embedding, dtype=np.float32)
+                
+                # Verificar que las dimensiones coincidan
+                if len(candidate_vec) != len(base_vec):
+                    print(f"   ⚠️ Dimensiones no coinciden: {len(candidate_vec)} vs {len(base_vec)}")
+                    continue
+                
+                # Calcular similitud coseno
+                candidate_norm = np.linalg.norm(candidate_vec)
+                similarity = float(np.dot(base_vec, candidate_vec) / (base_norm * candidate_norm))
+                
+                # Filtrar por umbral
+                if similarity >= match_threshold:
+                    matches.append({
+                        "report_id": candidate["id"],
+                        "similarity_score": round(similarity, 4),
+                        "pet_name": candidate.get("pet_name"),
+                        "species": candidate.get("species"),
+                        "color": candidate.get("color"),
+                        "type": candidate.get("type"),
+                        "photo": (candidate.get("photos") or [None])[0] if isinstance(candidate.get("photos"), list) else None,
+                        "description": candidate.get("description"),
+                        "created_at": candidate.get("created_at")
+                    })
+            except Exception as e:
+                print(f"   ⚠️ Error calculando similitud con {candidate['id']}: {str(e)}")
+                continue
+        
+        # Ordenar por similitud descendente
+        matches.sort(key=lambda x: x["similarity_score"], reverse=True)
+        
+        # Limitar resultados
+        top_matches = matches[:top_k]
+        
+        print(f"   ✅ Encontradas {len(top_matches)} coincidencias (de {len(matches)} sobre umbral)")
+        
+        # Guardar matches en la tabla matches
+        if top_matches:
+            await _save_matches_to_db(sb, report_id, base_type, top_matches)
+        
+        return {
+            "report_id": report_id,
+            "matches": top_matches,
+            "total_candidates": len(candidates),
+            "total_above_threshold": len(matches),
+            "returned": len(top_matches),
+            "search_params": {
+                "match_threshold": match_threshold,
+                "top_k": top_k,
+                "base_type": base_type,
+                "target_type": target_type,
+                "species_filter": base_species
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"❌ [direct-match] Error: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(500, f"Error buscando coincidencias: {str(e)}")
+
+async def _save_matches_to_db(sb: Client, report_id: str, report_type: str, matches: List[Dict[str, Any]]):
+    """Guarda los matches en la tabla matches"""
+    try:
+        saved_count = 0
+        for match in matches:
+            match_report_id = match["report_id"]
+            similarity_score = match["similarity_score"]
+            
+            # Determinar qué es lost y qué es found
+            if report_type == "lost":
+                lost_report_id = report_id
+                found_report_id = match_report_id
+            else:
+                lost_report_id = match_report_id
+                found_report_id = report_id
+            
+            # Verificar si ya existe este match
+            existing = sb.table("matches")\
+                .select("id, similarity_score")\
+                .eq("lost_report_id", lost_report_id)\
+                .eq("found_report_id", found_report_id)\
+                .execute()
+            
+            if existing.data:
+                # Actualizar si la similitud es mayor
+                existing_match = existing.data[0]
+                if similarity_score > existing_match.get("similarity_score", 0):
+                    sb.table("matches").update({
+                        "similarity_score": similarity_score,
+                        "matched_by": "ai_visual",
+                        "status": "pending"
+                    }).eq("id", existing_match["id"]).execute()
+                    saved_count += 1
+            else:
+                # Crear nuevo match
+                sb.table("matches").insert({
+                    "lost_report_id": lost_report_id,
+                    "found_report_id": found_report_id,
+                    "similarity_score": similarity_score,
+                    "matched_by": "ai_visual",
+                    "status": "pending"
+                }).execute()
+                saved_count += 1
+        
+        print(f"   💾 Guardados {saved_count} matches en la base de datos")
+    except Exception as e:
+        print(f"   ⚠️ Error guardando matches: {str(e)}")
+        # No lanzar excepción, solo loguear
+

routers/embeddings.py

@@ -0,0 +1,212 @@
+"""
+Router de Embeddings (Legacy)
+=============================
+
+Este router maneja operaciones de embeddings usando conexión directa a PostgreSQL.
+NOTA: Este router es legacy y puede estar en desuso. La funcionalidad principal
+de embeddings está en embeddings_supabase.py que usa Supabase.
+
+Funcionalidades:
+- Indexar embeddings de reportes directamente en PostgreSQL
+- Buscar imágenes similares usando búsqueda vectorial con pgvector
+- Filtrar por ubicación geográfica (opcional)
+- Crear matches automáticamente cuando se encuentra una coincidencia
+
+Este router usa psycopg para conexión directa a PostgreSQL en lugar de Supabase.
+"""
+
+# =========================
+# Imports de FastAPI
+# =========================
+from fastapi import APIRouter, File, HTTPException, Query, UploadFile
+
+# =========================
+# Imports de Python estándar
+# =========================
+import os  # Para variables de entorno
+import psycopg  # Cliente PostgreSQL directo
+
+# =========================
+# Imports de tipos
+# =========================
+from typing import Optional  # Para tipos opcionales
+
+# =========================
+# Imports de servicios
+# =========================
+from services.embeddings import image_bytes_to_vec  # Generar embeddings de imágenes
+from supabase import Client, create_client  # Cliente de Supabase (no usado en este router)
+
+# Crear el router con prefijo /embeddings
+router = APIRouter(prefix="/embeddings", tags=["embeddings"])
+
+def get_conn():
+    """
+    Obtiene una conexión directa a PostgreSQL usando psycopg.
+    
+    Returns:
+        psycopg.Connection: Conexión a PostgreSQL con autocommit habilitado
+        
+    Raises:
+        RuntimeError: Si DATABASE_URL no está configurada
+        
+    Esta función usa conexión directa a PostgreSQL en lugar de Supabase.
+    Útil para operaciones que requieren acceso directo a pgvector.
+    """
+    dsn = os.getenv("DATABASE_URL")
+    if not dsn:
+        raise RuntimeError("DATABASE_URL no configurada")
+    return psycopg.connect(dsn, autocommit=True)
+
+def get_supabase():
+    """
+    Obtiene un cliente de Supabase (no usado en este router, pero disponible).
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        RuntimeError: Si SUPABASE_URL o SUPABASE_SERVICE_KEY no están configuradas
+    """
+    url = os.getenv("SUPABASE_URL")
+    key = os.getenv("SUPABASE_SERVICE_KEY")
+    if not url or not key:
+        raise RuntimeError("SUPABASE_URL o SUPABASE_SERVICE_KEY no configuradas")
+    return create_client(url, key)
+
+@router.post("/index/{report_id}")
+async def index_report_embedding(report_id: str, file: UploadFile = File(...)):
+    """
+    Indexa un embedding para un reporte específico.
+    
+    Este endpoint:
+    1. Recibe una imagen del reporte
+    2. Genera el embedding usando MegaDescriptor
+    3. Actualiza el campo embedding en la tabla reports
+    
+    Args:
+        report_id: ID del reporte (UUID)
+        file: Archivo de imagen a procesar
+        
+    Returns:
+        dict: Estado de la operación con report_id y dimensiones del embedding
+        
+    Raises:
+        HTTPException 400: Si no se puede procesar la imagen
+        HTTPException 404: Si el report_id no existe
+    """
+    try:
+        # Generar embedding de la imagen usando MegaDescriptor
+        vec = image_bytes_to_vec(await file.read())
+    except Exception as e:
+        raise HTTPException(400, f"No se pudo procesar la imagen: {e}")
+    
+    # Actualizar el embedding en PostgreSQL directamente
+    with get_conn() as conn, conn.cursor() as cur:
+        cur.execute("""
+            update public.reports
+               set embedding = %s
+             where id = %s::uuid
+        """, (vec, report_id))
+        if cur.rowcount == 0:
+            raise HTTPException(404, "report_id no encontrado")
+    return {"status": "ok", "report_id": report_id, "dims": len(vec)}
+
+@router.post("/search_image")
+async def search_image(
+    file: UploadFile = File(...),
+    top_k: int = Query(10, ge=1, le=50),
+    lost_id: Optional[str] = Query(None),
+    lat: Optional[float] = Query(None),
+    lng: Optional[float] = Query(None),
+    max_km: Optional[float] = Query(None, description="Radio máximo en km")
+):
+    """
+    Busca reportes similares usando búsqueda vectorial por imagen.
+    
+    Este endpoint:
+    1. Genera un embedding de la imagen de búsqueda
+    2. Busca reportes similares usando pgvector (operador <#> para cosine distance)
+    3. Filtra por ubicación geográfica si se proporciona (opcional)
+    4. Crea un match automático si se encuentra una coincidencia y se proporciona lost_id
+    
+    Args:
+        file: Imagen de búsqueda
+        top_k: Número máximo de resultados (1-50, por defecto 10)
+        lost_id: ID del reporte perdido (opcional, para crear match automático)
+        lat: Latitud para filtrar por ubicación (opcional)
+        lng: Longitud para filtrar por ubicación (opcional)
+        max_km: Radio máximo en kilómetros para filtrar (opcional)
+        
+    Returns:
+        dict: Lista de resultados con report_id, similarity_score, species, color, photo, labels
+        
+    Raises:
+        HTTPException 400: Si no se puede procesar la imagen
+    """
+    try:
+        # Generar embedding de la imagen de búsqueda
+        qvec = image_bytes_to_vec(await file.read())
+    except Exception as e:
+        raise HTTPException(400, f"No se pudo procesar la imagen: {e}")
+
+    # Construir consulta SQL base para búsqueda vectorial
+    # Usa el operador <#> de pgvector para cosine distance
+    # (1 - cosine_distance) = similarity_score
+    base_sql = """
+        select r.id,
+               (1 - (r.embedding <#> %(qvec)s)) as similarity_score,
+               r.species, r.color, r.photos, r.labels
+         from public.reports r
+    """
+    where = ["r.embedding is not null"]  # Solo reportes con embeddings
+    params = {"qvec": qvec, "qvec2": qvec, "top_k": top_k}
+
+    # Si se proporciona ubicación, agregar filtro geográfico usando Haversine
+    if lat is not None and lng is not None and max_km and max_km > 0:
+        base_sql += """
+          join public.reports_with_coords rc on rc.id = r.id
+        """
+        # Fórmula de Haversine en SQL para calcular distancia en kilómetros
+        # 6371 es el radio de la Tierra en km
+        where.append("""
+          ( 6371 * acos(
+              cos(radians(%(lat)s)) * cos(radians(rc.latitude))
+              * cos(radians(rc.longitude) - radians(%(lng)s))
+              + sin(radians(%(lat)s)) * sin(radians(rc.latitude))
+            ) ) <= %(max_km)s
+        """)
+        params.update({"lat": lat, "lng": lng, "max_km": max_km})
+
+    # Construir SQL final con ordenamiento por similitud
+    sql = f"""
+      {base_sql}
+      {" where " + " and ".join(where) if where else ""}
+      order by r.embedding <#> %(qvec2)s  -- Ordenar por cosine distance (menor = más similar)
+      limit %(top_k)s
+    """
+
+    # Ejecutar búsqueda y procesar resultados
+    results = []
+    with get_conn() as conn, conn.cursor() as cur:
+        cur.execute(sql, params)
+        for rid, sim, species, color, photos, labels in cur.fetchall():
+            results.append({
+                "report_id": rid,
+                "similarity_score": float(sim) if sim is not None else None,
+                "species": species,
+                "color": color,
+                "photo": (photos or [None])[0] if isinstance(photos, list) else None,  # Primera foto
+                "labels": labels
+            })
+        
+        # Si hay resultados y se proporcionó lost_id, crear match automático
+        if results:
+            top1 = results[0]
+            cur.execute("""
+                insert into public.matches
+                    (lost_report_id, found_report_id, similarity_score, matched_by, status)
+                values (%s::uuid, %s::uuid, %s, 'ai_visual', 'pending')
+            """, (lost_id if lost_id else None, top1["report_id"],
+                  round(top1["similarity_score"], 4) if top1["similarity_score"] is not None else None))
+    return {"results": results}

routers/embeddings_supabase.py

@@ -0,0 +1,279 @@
+"""
+Router de Embeddings para Supabase
+===================================
+
+Este router maneja la generación y gestión de embeddings de imágenes
+usando MegaDescriptor y almacenándolos en Supabase.
+
+Funcionalidades:
+- Generar embeddings de imágenes
+- Indexar embeddings en reportes (guardar en base de datos)
+- Buscar imágenes similares usando embeddings
+- Filtrar por ubicación y otros criterios
+
+Los embeddings se generan usando MegaDescriptor y se almacenan
+en Supabase usando pgvector para búsquedas vectoriales eficientes.
+"""
+
+# =========================
+# Imports de FastAPI
+# =========================
+from fastapi import APIRouter, File, HTTPException, Query, UploadFile
+
+# =========================
+# Imports de Python estándar
+# =========================
+import os  # Para variables de entorno
+
+# =========================
+# Imports de tipos
+# =========================
+from typing import Optional  # Para tipos opcionales
+
+# =========================
+# Imports de servicios
+# =========================
+from services.embeddings import image_bytes_to_vec  # Generar embeddings con MegaDescriptor
+
+# =========================
+# Imports de Supabase
+# =========================
+from supabase import Client, create_client  # Cliente de Supabase
+
+# Crear el router con prefijo /embeddings
+router = APIRouter(prefix="/embeddings", tags=["embeddings"])
+
+def get_supabase():
+    """
+    Crea un cliente de Supabase básico.
+    
+    Returns:
+        Client: Cliente de Supabase
+        
+    Raises:
+        RuntimeError: Si no se encuentran las credenciales en variables de entorno
+    """
+    url = os.getenv("SUPABASE_URL")
+    key = os.getenv("SUPABASE_SERVICE_KEY")
+    if not url or not key:
+        raise RuntimeError("SUPABASE_URL o SUPABASE_SERVICE_KEY no configuradas")
+    return create_client(url, key)
+
+@router.post("/generate")
+async def generate_embedding(file: UploadFile = File(...)):
+    """
+    Genera un embedding para una imagen usando MegaDescriptor.
+    
+    Este endpoint:
+    1. Recibe una imagen
+    2. Genera el embedding usando MegaDescriptor-L-384
+    3. Retorna el embedding como lista de números
+    
+    Args:
+        file: Archivo de imagen a procesar
+        
+    Returns:
+        dict: Embedding, dimensiones, modelo usado, nombre y tamaño del archivo
+        
+    Raises:
+        HTTPException 400: Si el archivo está vacío
+        HTTPException 500: Si hay error generando el embedding
+    """
+    try:
+        image_bytes = await file.read()
+        if not image_bytes:
+            raise HTTPException(400, "Archivo vacío o no leído")
+        
+        vec = image_bytes_to_vec(image_bytes)
+        
+        return {
+            "embedding": vec.tolist(),
+            "dimensions": len(vec),
+            "model": "MegaDescriptor-L-384",
+            "file_name": file.filename,
+            "file_size": len(image_bytes)
+        }
+    except Exception as e:
+        raise HTTPException(500, f"Error generando embedding: {str(e)}")
+
+@router.post("/index/{report_id}")
+async def index_report_embedding(report_id: str, file: UploadFile = File(...)):
+    """
+    Indexa un embedding para un reporte específico en Supabase.
+    
+    Este endpoint:
+    1. Genera el embedding de la imagen usando MegaDescriptor
+    2. Guarda el embedding en la tabla reports usando pgvector
+    3. Actualiza el campo embedding del reporte
+    
+    Args:
+        report_id: ID del reporte (UUID)
+        file: Archivo de imagen a procesar
+        
+    Returns:
+        dict: Estado de la operación con report_id y dimensiones
+        
+    Raises:
+        HTTPException 400: Si no se puede procesar la imagen
+        HTTPException 404: Si el report_id no existe
+        HTTPException 500: Si hay error actualizando el embedding
+    """
+    try:
+        # Generar embedding de la imagen usando MegaDescriptor
+        vec = image_bytes_to_vec(await file.read())
+    except Exception as e:
+        raise HTTPException(400, f"No se pudo procesar la imagen: {e}")
+    
+    sb = get_supabase()
+    try:
+        # Convertir vector numpy a lista para Supabase
+        # Supabase necesita una lista de Python, no un numpy array
+        vec_list = vec.tolist()
+        
+        # Usar función RPC de Supabase para actualizar el embedding
+        # Esta función SQL maneja la conversión correcta a tipo vector de pgvector
+        result = sb.rpc('update_report_embedding', {
+            'report_id': report_id,
+            'embedding_vector': vec_list
+        }).execute()
+        
+        if not result.data:
+            raise HTTPException(404, "report_id no encontrado")
+            
+        return {"status": "ok", "report_id": report_id, "dims": len(vec)}
+    except Exception as e:
+        raise HTTPException(500, f"Error actualizando embedding: {e}")
+
+@router.post("/search_image")
+async def search_image(
+    file: UploadFile = File(...),
+    top_k: int = Query(10, ge=1, le=50),
+    lost_id: Optional[str] = Query(None),
+    lat: Optional[float] = Query(None),
+    lng: Optional[float] = Query(None),
+    max_km: Optional[float] = Query(None, description="Radio máximo en km")
+):
+    """
+    Busca reportes similares usando búsqueda vectorial por imagen.
+    
+    Este endpoint:
+    1. Genera un embedding de la imagen de búsqueda usando MegaDescriptor
+    2. Busca reportes con embeddings similares en Supabase
+    3. Calcula similitud coseno entre embeddings
+    4. Filtra por ubicación geográfica si se proporciona (opcional)
+    5. Crea un match automático si se encuentra una coincidencia y se proporciona lost_id
+    
+    Args:
+        file: Imagen de búsqueda
+        top_k: Número máximo de resultados (1-50, por defecto 10)
+        lost_id: ID del reporte perdido (opcional, para crear match automático)
+        lat: Latitud para filtrar por ubicación (opcional)
+        lng: Longitud para filtrar por ubicación (opcional)
+        max_km: Radio máximo en kilómetros para filtrar (opcional)
+        
+    Returns:
+        dict: Lista de resultados con report_id, similarity_score, species, color, photo, labels
+        
+    Raises:
+        HTTPException 400: Si no se puede procesar la imagen
+        HTTPException 500: Si hay error en la búsqueda
+    """
+    try:
+        # Generar embedding de la imagen de búsqueda usando MegaDescriptor
+        qvec = image_bytes_to_vec(await file.read())
+    except Exception as e:
+        raise HTTPException(400, f"No se pudo procesar la imagen: {e}")
+
+    sb = get_supabase()
+    
+    # =========================
+    # Construir query base
+    # =========================
+    # Obtener todos los reportes que tengan embedding
+    query = sb.table("reports").select("id, species, color, photos, labels, embedding")
+    
+    # Filtrar por embedding no nulo (solo reportes con embeddings)
+    query = query.not_.is_("embedding", "null")
+    
+    # Aplicar filtro geográfico si se proporciona
+    # NOTA: El filtro geográfico completo requeriría una función RPC en Supabase
+    # Por ahora, obtenemos todos y podríamos filtrar después si es necesario
+    if lat is not None and lng is not None and max_km and max_km > 0:
+        # Para Supabase, necesitaríamos usar una función RPC o filtrar después
+        # Por ahora, obtenemos todos y filtramos después
+        pass
+    
+    try:
+        result = query.execute()
+        reports = result.data
+        
+        # =========================
+        # Calcular similitud para cada reporte
+        # =========================
+        results = []
+        import numpy as np  # Para operaciones con vectores
+        
+        for report in reports:
+            if not report.get("embedding"):
+                continue
+                
+            # Convertir embedding de Supabase a numpy array
+            # Los embeddings vienen como listas desde Supabase/pgvector
+            report_vec = report["embedding"]
+            if isinstance(report_vec, list):
+                # Asegurar que todos los elementos son números válidos
+                try:
+                    report_vec = np.array([float(x) for x in report_vec], dtype=np.float32)
+                except (ValueError, TypeError):
+                    continue  # Si hay error, saltar este reporte
+            else:
+                continue  # Si no es una lista, saltar
+            
+            # Calcular similitud coseno entre embeddings
+            # Similitud coseno = (A · B) / (||A|| * ||B||)
+            # Valores cercanos a 1 = muy similares, valores cercanos a 0 = diferentes
+            try:
+                similarity = np.dot(qvec, report_vec) / (np.linalg.norm(qvec) * np.linalg.norm(report_vec))
+            except:
+                continue  # Si hay error en el cálculo, saltar este reporte
+            
+            # Aplicar filtro geográfico si es necesario
+            # NOTA: Para filtrar por ubicación, necesitaríamos las coordenadas del reporte
+            # Por ahora, este filtro no está implementado completamente
+            if lat is not None and lng is not None and max_km and max_km > 0:
+                # Aquí necesitarías las coordenadas del reporte
+                # Por ahora, saltamos el filtro geográfico
+                pass
+            
+            results.append({
+                "report_id": report["id"],
+                "similarity_score": float(similarity),  # Convertir a float nativo de Python
+                "species": report.get("species"),
+                "color": report.get("color"),
+                "photo": (report.get("photos") or [None])[0] if isinstance(report.get("photos"), list) else None,  # Primera foto
+                "labels": report.get("labels")
+            })
+        
+        # Ordenar por similitud (mayor a menor) y tomar top_k
+        results.sort(key=lambda x: x["similarity_score"], reverse=True)
+        results = results[:top_k]
+        
+        # Guardar top-1 en matches si hay resultados y se proporcionó lost_id
+        # Esto crea un match automático entre el reporte perdido y el encontrado más similar
+        if results and lost_id:
+            top1 = results[0]
+            try:
+                sb.table("matches").insert({
+                    "lost_report_id": lost_id,
+                    "found_report_id": top1["report_id"],
+                    "similarity_score": round(top1["similarity_score"], 4),  # Redondear a 4 decimales
+                    "matched_by": "ai_visual",  # Indica que fue encontrado usando embeddings de imágenes (MegaDescriptor)
+                    "status": "pending"  # Match pendiente de confirmación
+                }).execute()
+            except Exception as e:
+                print(f"Error guardando match: {e}")  # Log del error pero no fallar la búsqueda
+        
+        return {"results": results}
+        
+    except Exception as e:
+        raise HTTPException(500, f"Error en búsqueda: {e}")

routers/fix_embeddings.py

@@ -0,0 +1,237 @@
+"""
+Router para Regenerar Embeddings
+=================================
+
+Este router proporciona herramientas administrativas para regenerar embeddings
+de reportes que no los tienen o que tienen embeddings incorrectos.
+
+Funcionalidades:
+- Regenerar embedding para un reporte específico
+- Regenerar embeddings para múltiples reportes
+- Regenerar embeddings para todos los reportes sin embedding
+- Verificar estado de embeddings
+
+Útil para:
+- Migración de reportes antiguos que no tienen embeddings
+- Corrección de embeddings corruptos
+- Regeneración masiva después de actualizar el modelo
+"""
+
+from fastapi import APIRouter, HTTPException
+from typing import List, Dict
+import os, sys
+from pathlib import Path
+from supabase import Client
+import httpx  # Para descargar imágenes desde URLs
+from services.embeddings import image_bytes_to_vec  # Función para generar embeddings
+
+# Agregar la carpeta parent al path para poder importar utils
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# Crear el router con prefijo /fix-embeddings
+router = APIRouter(prefix="/fix-embeddings", tags=["fix-embeddings"])
+
+def _sb() -> Client:
+    """
+    Crea un cliente de Supabase con configuración optimizada de timeouts.
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        HTTPException: Si no se puede conectar a Supabase
+    """
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+@router.post("/regenerate/{report_id}")
+async def regenerate_embedding_for_report(report_id: str):
+    """
+    Regenera el embedding para un reporte específico que tiene foto pero no embedding.
+    """
+    try:
+        sb = _sb()
+        
+        # Obtener el reporte
+        result = sb.table("reports")\
+            .select("id, photos, embedding")\
+            .eq("id", report_id)\
+            .single()\
+            .execute()
+        
+        if not result.data:
+            raise HTTPException(404, f"Reporte {report_id} no encontrado")
+        
+        report = result.data
+        photos = report.get("photos", [])
+        
+        if not photos or len(photos) == 0:
+            raise HTTPException(400, f"El reporte {report_id} no tiene fotos")
+        
+        first_photo = photos[0]
+        
+        print(f"🔄 Generando embedding para reporte {report_id}")
+        print(f"   Foto: {first_photo}")
+        
+        # Descargar la imagen
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.get(first_photo)
+            response.raise_for_status()
+            image_bytes = response.content
+        
+        # Generar embedding
+        vec = image_bytes_to_vec(image_bytes)
+        vec_list = vec.tolist()
+        
+        print(f"   Dimensiones del embedding: {len(vec_list)}")
+        
+        # Guardar en Supabase
+        update_result = sb.table('reports').update({
+            'embedding': vec_list
+        }).eq('id', report_id).execute()
+        
+        if update_result.data:
+            print(f"✅ Embedding regenerado exitosamente para reporte {report_id}")
+            return {
+                "success": True,
+                "report_id": report_id,
+                "message": "Embedding regenerado exitosamente",
+                "embedding_dimensions": len(vec_list)
+            }
+        else:
+            raise HTTPException(500, "No se pudo guardar el embedding")
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"❌ Error regenerando embedding: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(500, f"Error regenerando embedding: {str(e)}")
+
+@router.post("/regenerate-all")
+async def regenerate_all_missing_embeddings():
+    """
+    Regenera embeddings para todos los reportes que tienen fotos pero no tienen embedding.
+    """
+    try:
+        sb = _sb()
+        
+        # Obtener reportes sin embedding pero con fotos
+        result = sb.table("reports")\
+            .select("id, photos")\
+            .is_("embedding", "null")\
+            .execute()
+        
+        if not result.data:
+            return {
+                "success": True,
+                "message": "No hay reportes sin embeddings",
+                "processed": 0
+            }
+        
+        reports = result.data
+        reports_with_photos = [r for r in reports if r.get("photos") and len(r.get("photos", [])) > 0]
+        
+        if not reports_with_photos:
+            return {
+                "success": True,
+                "message": "No hay reportes con fotos sin embeddings",
+                "processed": 0
+            }
+        
+        print(f"🔄 Regenerando embeddings para {len(reports_with_photos)} reportes...")
+        
+        success_count = 0
+        errors: List[Dict] = []
+        
+        for report in reports_with_photos:
+            report_id = report["id"]
+            photos = report["photos"]
+            first_photo = photos[0]
+            
+            try:
+                # Descargar la imagen
+                async with httpx.AsyncClient(timeout=30.0) as client:
+                    response = await client.get(first_photo)
+                    response.raise_for_status()
+                    image_bytes = response.content
+                
+                # Generar embedding
+                vec = image_bytes_to_vec(image_bytes)
+                vec_list = vec.tolist()
+                
+                # Guardar en Supabase
+                sb.table('reports').update({
+                    'embedding': vec_list
+                }).eq('id', report_id).execute()
+                
+                success_count += 1
+                print(f"   ✅ {success_count}/{len(reports_with_photos)}: {report_id}")
+                
+            except Exception as e:
+                error_msg = str(e)
+                errors.append({"report_id": report_id, "error": error_msg})
+                print(f"   ❌ Error con {report_id}: {error_msg}")
+        
+        return {
+            "success": True,
+            "message": f"Procesados {success_count} reportes exitosamente",
+            "total_processed": success_count,
+            "total_errors": len(errors),
+            "errors": errors[:10]  # Mostrar solo los primeros 10 errores
+        }
+        
+    except Exception as e:
+        print(f"❌ Error en regeneración masiva: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(500, f"Error en regeneración masiva: {str(e)}")
+
+@router.get("/check-missing")
+async def check_missing_embeddings():
+    """
+    Verifica cuántos reportes no tienen embeddings.
+    """
+    try:
+        sb = _sb()
+        
+        # Total de reportes
+        all_result = sb.table("reports")\
+            .select("id", count="exact")\
+            .execute()
+        total_reports = all_result.count or 0
+        
+        # Reportes sin embedding
+        no_embedding_result = sb.table("reports")\
+            .select("id", count="exact")\
+            .is_("embedding", "null")\
+            .execute()
+        no_embedding_count = no_embedding_result.count or 0
+        
+        # Reportes sin embedding pero con fotos
+        with_photos_result = sb.table("reports")\
+            .select("id, photos")\
+            .is_("embedding", "null")\
+            .execute()
+        
+        reports_with_photos = 0
+        if with_photos_result.data:
+            reports_with_photos = len([
+                r for r in with_photos_result.data 
+                if r.get("photos") and len(r.get("photos", [])) > 0
+            ])
+        
+        return {
+            "total_reports": total_reports,
+            "reports_without_embedding": no_embedding_count,
+            "reports_with_photos_without_embedding": reports_with_photos,
+            "percentage_missing": round((no_embedding_count / total_reports * 100), 2) if total_reports > 0 else 0
+        }
+        
+    except Exception as e:
+        raise HTTPException(500, f"Error verificando embeddings: {str(e)}")
+

routers/matches.py

@@ -0,0 +1,409 @@
+"""
+Router de Matches (Coincidencias)
+==================================
+
+Este router maneja todas las operaciones relacionadas con matches (coincidencias)
+entre reportes de mascotas perdidas y encontradas.
+
+Un match es una posible coincidencia entre:
+- Un reporte de mascota perdida y un reporte de mascota encontrada, o viceversa
+- Se calculan usando similitud visual (embeddings), ubicación geográfica, y etiquetas
+
+Funcionalidades principales:
+- Búsqueda automática de matches para un reporte
+- Obtener matches pendientes de un usuario o reporte
+- Aceptar o rechazar matches
+- Calcular scores de similitud entre reportes
+"""
+
+from fastapi import APIRouter, HTTPException, Query
+from typing import List, Dict, Any, Optional
+import os, math, sys
+from pathlib import Path
+from supabase import Client
+
+# Agregar la carpeta parent al path para poder importar utils
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# Crear el router con prefijo /matches
+router = APIRouter(prefix="/matches", tags=["matches"])
+
+def _sb() -> Client:
+    """
+    Crea un cliente de Supabase con configuración optimizada de timeouts.
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        HTTPException: Si no se puede conectar a Supabase
+    """
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+def _coords(loc: Optional[dict]) -> Optional[tuple]:
+    """
+    Extrae coordenadas de un objeto de ubicación en formato GeoJSON.
+    
+    Args:
+        loc: Objeto GeoJSON con formato {"type":"Point","coordinates":[lon,lat]}
+        
+    Returns:
+        Tupla (latitud, longitud) o None si no se pueden extraer
+    """
+    # GeoJSON usa formato {"type":"Point","coordinates":[lon,lat]}
+    if isinstance(loc, dict) and "coordinates" in loc:
+        lon, lat = loc["coordinates"]
+        return (lat, lon)  # Retornar como (lat, lon) para consistencia
+    return None
+
+def haversine_km(lat1, lon1, lat2, lon2):
+    """
+    Calcula la distancia en kilómetros entre dos puntos geográficos usando la fórmula de Haversine.
+    
+    Args:
+        lat1, lon1: Latitud y longitud del primer punto (en grados)
+        lat2, lon2: Latitud y longitud del segundo punto (en grados)
+        
+    Returns:
+        Distancia en kilómetros entre los dos puntos
+    """
+    R = 6371.0  # Radio de la Tierra en kilómetros
+    # Convertir diferencias a radianes
+    dlat = math.radians(lat2 - lat1)
+    dlon = math.radians(lon2 - lon1)
+    # Aplicar fórmula de Haversine
+    a = math.sin(dlat/2)**2 + math.cos(math.radians(lat1)) * math.cos(math.radians(lat2)) * math.sin(dlon/2)**2
+    return 2 * R * math.asin(math.sqrt(a))
+
+def label_set(labels_json) -> set:
+    """
+    Convierte etiquetas JSON a un conjunto de strings normalizados.
+    
+    Args:
+        labels_json: Objeto JSON con etiquetas (puede ser dict con "labels" o lista)
+        
+    Returns:
+        Set de strings en minúsculas con las etiquetas
+    """
+    # Si no hay etiquetas, retornar set vacío
+    if not labels_json:
+        return set()
+    
+    # Intentar obtener la lista de etiquetas
+    items = labels_json.get("labels") if isinstance(labels_json, dict) else None
+    
+    # Si no es una lista válida, retornar set vacío
+    if not isinstance(items, list):
+        return set()
+    
+    # Extraer etiquetas y normalizar a minúsculas
+    return {(it.get("label") or it.get("description") or "").lower() for it in items if it}
+
+@router.get("/auto-match")
+def auto_match(
+    report_id: str = Query(..., description="ID del reporte base para buscar matches"),
+    radius_km: float = Query(10.0, description="Radio de búsqueda en kilómetros"),
+    top_k: int = Query(5, description="Número máximo de matches a retornar")
+):
+    """
+    Busca automáticamente matches (coincidencias) para un reporte.
+    
+    Este endpoint busca reportes del tipo opuesto (si es "lost" busca "found" y viceversa)
+    que estén dentro del radio especificado y tengan la misma especie.
+    
+    El algoritmo de scoring considera:
+    - Overlap de etiquetas (más etiquetas en común = mayor score)
+    - Distancia geográfica (más cerca = mayor score)
+    
+    Args:
+        report_id: ID del reporte base (debe existir en la base de datos)
+        radius_km: Radio máximo de búsqueda en kilómetros (default: 10km)
+        top_k: Número máximo de matches a retornar (default: 5)
+    
+    Returns:
+        JSON con:
+        - report_id: ID del reporte base
+        - radius_km: Radio usado
+        - total_candidates: Total de candidatos encontrados
+        - top_k: Lista de los mejores matches ordenados por score
+    """
+    sb = _sb()
+    
+    # =========================
+    # Obtener reporte base
+    # =========================
+    # Buscar el reporte base en la base de datos
+    base = sb.table("reports").select("*").eq("id", report_id).single().execute().data
+    
+    # Verificar que el reporte existe
+    if not base:
+        raise HTTPException(404, "Reporte base no encontrado")
+    
+    # =========================
+    # Extraer datos del reporte base
+    # =========================
+    # Extraer coordenadas de la ubicación
+    base_pt = _coords(base.get("location"))
+    if not base_pt:
+        raise HTTPException(400, "El reporte base no tiene location válido (GeoJSON Point)")
+    
+    base_lat, base_lon = base_pt  # Desempaquetar coordenadas
+    base_labels = label_set(base.get("labels"))  # Extraer etiquetas como set
+    
+    # Determinar el tipo opuesto de reporte a buscar
+    # Si el reporte base es "lost", buscar "found" y viceversa
+    target_type = "found" if base.get("type") == "lost" else "lost"
+    
+    # =========================
+    # Buscar candidatos
+    # =========================
+    # Buscar reportes que:
+    # - Sean del tipo opuesto (lost/found)
+    # - Estén activos (status = "active")
+    # - Tengan la misma especie
+    candidates = sb.table("reports").select("*") \
+        .eq("type", target_type) \
+        .eq("status", "active") \
+        .eq("species", base.get("species")) \
+        .execute().data
+    
+    # =========================
+    # Filtrar y calcular scores
+    # =========================
+    results: List[Dict[str, Any]] = []
+    
+    # Aproximación rápida: 1 grado ≈ 111 km
+    # Usar esto para un filtro rápido antes de calcular la distancia exacta
+    lat_pad = radius_km / 111.0  # Padding en latitud
+    lon_pad = radius_km / 111.0  # Padding en longitud
+    
+    # Iterar sobre cada candidato
+    for c in candidates:
+        # Extraer coordenadas del candidato
+        pt = _coords(c.get("location"))
+        if not pt:
+            continue  # Saltar si no tiene coordenadas válidas
+        
+        lat, lon = pt
+        
+        # Filtro rápido: verificar si está dentro del rectángulo aproximado
+        # Esto evita calcular la distancia exacta para candidatos muy lejanos
+        if not (base_lat - lat_pad <= lat <= base_lat + lat_pad and 
+                base_lon - lon_pad <= lon <= base_lon + lon_pad):
+            continue  # Está fuera del área aproximada, saltar
+        
+        # Calcular distancia exacta usando Haversine
+        d = haversine_km(base_lat, base_lon, lat, lon)
+        
+        # Filtrar por radio exacto
+        if d > radius_km:
+            continue  # Está fuera del radio, saltar
+        
+        # =========================
+        # Calcular score
+        # =========================
+        # Calcular overlap de etiquetas (intersección de sets)
+        # Más etiquetas en común = mayor score
+        overlap = len(base_labels & label_set(c.get("labels")))
+        
+        # Score = (overlap * 10) - (distancia * 0.2)
+        # - Cada etiqueta en común suma 10 puntos
+        # - Cada kilómetro resta 0.2 puntos
+        # Esto prioriza matches cercanos con muchas etiquetas en común
+        score = overlap * 10 - d * 0.2
+        
+        # Agregar a resultados
+        results.append({
+            "candidate": {
+                "id": c["id"],  # ID del candidato
+                "pet_name": c.get("pet_name"),  # Nombre de la mascota
+                "species": c.get("species"),  # Especie
+                "color": c.get("color"),  # Color
+                "location": c.get("location"),  # Ubicación
+                # Primera foto del array, o None si no hay fotos
+                "photo": (c.get("photos") or [None])[0] if isinstance(c.get("photos"), list) else None,
+                "labels": c.get("labels"),  # Etiquetas
+            },
+            "distance_km": round(d, 2),  # Distancia redondeada a 2 decimales
+            "label_overlap": overlap,  # Número de etiquetas en común
+            "score": round(score, 3)  # Score redondeado a 3 decimales
+        })
+    
+    # =========================
+    # Ordenar y retornar
+    # =========================
+    # Ordenar por score descendente (mejores matches primero)
+    results.sort(key=lambda x: x["score"], reverse=True)
+    
+    # Retornar solo los top_k mejores matches
+    return {
+        "report_id": report_id,
+        "radius_km": radius_km,
+        "total_candidates": len(results),
+        "top_k": results[:top_k]  # Retornar solo los mejores
+    }
+
+
+@router.get("/pending")
+async def get_pending_matches(
+    user_id: Optional[str] = Query(None, description="ID del usuario para filtrar matches de sus reportes"),
+    report_id: Optional[str] = Query(None, description="ID del reporte específico para obtener sus matches"),
+    status: str = Query("pending", description="Estado de los matches (pending, accepted, rejected)")
+):
+    """
+    Obtiene matches pendientes (o con otro estado) para un usuario o un reporte específico.
+    
+    Este endpoint permite obtener matches de dos formas:
+    1. Por usuario: Retorna todos los matches de todos los reportes del usuario
+    2. Por reporte: Retorna todos los matches de un reporte específico
+    
+    Un match puede estar en tres estados:
+    - pending: Match encontrado pero aún no aceptado/rechazado
+    - accepted: Match aceptado por el usuario
+    - rejected: Match rechazado por el usuario
+    
+    Args:
+        user_id: ID del usuario (opcional, filtra por reportes del usuario)
+        report_id: ID del reporte (opcional, filtra por matches de ese reporte)
+        status: Estado de los matches a buscar (default: "pending")
+    
+    Returns:
+        Lista de matches con información completa de ambos reportes
+    """
+    try:
+        sb = _sb()
+        
+        if report_id:
+            # =========================
+            # Obtener matches de un reporte específico
+            # =========================
+            # Un match puede tener el reporte como lost_report_id o found_report_id
+            # Necesitamos buscar en ambas columnas
+            matches_lost = sb.table("matches").select("*").eq("lost_report_id", report_id).eq("status", status).execute()
+            matches_found = sb.table("matches").select("*").eq("found_report_id", report_id).eq("status", status).execute()
+            
+            all_matches = (matches_lost.data or []) + (matches_found.data or [])
+            
+            # Enriquecer con información de los reportes relacionados
+            enriched_matches = []
+            for match in all_matches:
+                lost_id = match.get("lost_report_id")
+                found_id = match.get("found_report_id")
+                
+                # Obtener reporte perdido
+                lost_report = None
+                if lost_id:
+                    lost_result = sb.table("reports").select("id, type, pet_name, species, photos, description, location, created_at").eq("id", lost_id).single().execute()
+                    lost_report = lost_result.data if lost_result.data else None
+                
+                # Obtener reporte encontrado
+                found_report = None
+                if found_id:
+                    found_result = sb.table("reports").select("id, type, pet_name, species, photos, description, location, created_at").eq("id", found_id).single().execute()
+                    found_report = found_result.data if found_result.data else None
+                
+                enriched_matches.append({
+                    "match_id": match.get("id"),
+                    "similarity_score": match.get("similarity_score"),
+                    "matched_by": match.get("matched_by"),
+                    "status": match.get("status"),
+                    "created_at": match.get("created_at"),
+                    "lost_report": lost_report,
+                    "found_report": found_report
+                })
+            
+            return {
+                "matches": enriched_matches,
+                "count": len(enriched_matches),
+                "report_id": report_id
+            }
+        
+        elif user_id:
+            # Obtener matches de todos los reportes del usuario
+            # Primero obtener todos los reportes del usuario
+            user_reports = sb.table("reports").select("id").eq("reporter_id", user_id).execute()
+            report_ids = [r["id"] for r in (user_reports.data or [])]
+            
+            if not report_ids:
+                return {"matches": [], "count": 0, "user_id": user_id}
+            
+            # Obtener matches donde los reportes del usuario están involucrados
+            matches_lost = sb.table("matches").select("*").in_("lost_report_id", report_ids).eq("status", status).execute()
+            matches_found = sb.table("matches").select("*").in_("found_report_id", report_ids).eq("status", status).execute()
+            
+            all_matches = (matches_lost.data or []) + (matches_found.data or [])
+            
+            # Enriquecer con información de los reportes (similar al caso anterior)
+            enriched_matches = []
+            for match in all_matches:
+                lost_id = match.get("lost_report_id")
+                found_id = match.get("found_report_id")
+                
+                lost_report = None
+                if lost_id:
+                    lost_result = sb.table("reports").select("id, type, pet_name, species, photos, description, location, created_at").eq("id", lost_id).single().execute()
+                    lost_report = lost_result.data if lost_result.data else None
+                
+                found_report = None
+                if found_id:
+                    found_result = sb.table("reports").select("id, type, pet_name, species, photos, description, location, created_at").eq("id", found_id).single().execute()
+                    found_report = found_result.data if found_result.data else None
+                
+                enriched_matches.append({
+                    "match_id": match.get("id"),
+                    "similarity_score": match.get("similarity_score"),
+                    "matched_by": match.get("matched_by"),
+                    "status": match.get("status"),
+                    "created_at": match.get("created_at"),
+                    "lost_report": lost_report,
+                    "found_report": found_report
+                })
+            
+            return {
+                "matches": enriched_matches,
+                "count": len(enriched_matches),
+                "user_id": user_id
+            }
+        else:
+            raise HTTPException(400, "Debe proporcionar user_id o report_id")
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo matches pendientes: {str(e)}")
+
+
+@router.put("/{match_id}/status")
+async def update_match_status(
+    match_id: str,
+    status: str = Query(..., description="Nuevo estado del match (accepted, rejected)")
+):
+    """
+    Actualiza el estado de un match (aceptado o rechazado).
+    """
+    try:
+        if status not in ["accepted", "rejected"]:
+            raise HTTPException(400, "El estado debe ser 'accepted' o 'rejected'")
+        
+        sb = _sb()
+        
+        result = sb.table("matches").update({"status": status}).eq("id", match_id).execute()
+        
+        if not result.data or len(result.data) == 0:
+            raise HTTPException(404, f"Match {match_id} no encontrado")
+        
+        return {
+            "success": True,
+            "match_id": match_id,
+            "status": status,
+            "message": f"Match {status} exitosamente"
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error actualizando estado del match: {str(e)}")

routers/pets.py

@@ -0,0 +1,578 @@
+"""
+Router de Mascotas
+==================
+
+Este router maneja todas las operaciones relacionadas con las mascotas de los usuarios.
+Permite gestionar el perfil de las mascotas, incluyendo información de salud,
+vacunaciones, medicamentos, recordatorios y eventos de salud.
+
+Funcionalidades principales:
+- CRUD de mascotas (crear, leer, actualizar, eliminar)
+- Gestión de salud (vacunaciones, medicamentos, recordatorios)
+- Eventos de salud (wellness, health events)
+- Resumen de salud de la mascota
+"""
+
+from fastapi import APIRouter, HTTPException, Query, Body
+from typing import List, Dict, Any, Optional
+from datetime import date, datetime
+import sys
+from pathlib import Path
+
+# Agregar la carpeta parent al path para poder importar utils
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# Crear el router con prefijo /pets
+router = APIRouter(prefix="/pets", tags=["pets"])
+
+def _sb():
+    """
+    Crea un cliente de Supabase con configuración optimizada.
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        HTTPException: Si no se puede conectar a Supabase
+    """
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+# ==============================================
+# ENDPOINTS BÁSICOS DE MASCOTAS
+# ==============================================
+
+@router.get("/")
+async def get_user_pets(owner_id: str = Query(..., description="ID del dueño")):
+    """
+    Obtiene todas las mascotas de un usuario.
+    
+    Args:
+        owner_id: ID del usuario dueño de las mascotas
+        
+    Returns:
+        JSON con:
+        - pets: Lista de mascotas del usuario
+        - count: Número total de mascotas
+        
+    Las mascotas se ordenan por fecha de creación (más recientes primero).
+    """
+    try:
+        sb = _sb()
+        # Consultar todas las mascotas del usuario
+        result = sb.table("pets")\
+            .select("*")\
+            .eq("owner_id", owner_id)\
+            .order("created_at", desc=True)\
+            .execute()
+        return {"pets": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo mascotas: {str(e)}")
+
+@router.get("/{pet_id}")
+async def get_pet_by_id(pet_id: str):
+    """Obtiene una mascota por ID con su resumen de salud"""
+    try:
+        sb = _sb()
+        
+        # Obtener la mascota
+        pet_result = sb.table("pets").select("*").eq("id", pet_id).execute()
+        if not pet_result.data:
+            raise HTTPException(404, "Mascota no encontrada")
+        
+        pet = pet_result.data[0]
+        
+        # Obtener resumen de salud usando la función SQL
+        try:
+            health_summary = sb.rpc("obtener_resumen_salud_mascota", {"pet_id": pet_id}).execute()
+            pet["health_summary"] = health_summary.data[0] if health_summary.data else {}
+        except:
+            pet["health_summary"] = {}
+        
+        return {"pet": pet}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo mascota: {str(e)}")
+
+@router.post("/")
+async def create_pet(pet_data: Dict[str, Any] = Body(...)):
+    """Crea una nueva mascota"""
+    try:
+        sb = _sb()
+        
+        required_fields = ["owner_id", "name", "species"]
+        for field in required_fields:
+            if field not in pet_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        result = sb.table("pets").insert(pet_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando mascota")
+        
+        return {"pet": result.data[0], "message": "Mascota creada exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error creando mascota: {str(e)}")
+
+@router.put("/{pet_id}")
+async def update_pet(pet_id: str, updates: Dict[str, Any] = Body(...)):
+    """Actualiza una mascota existente"""
+    try:
+        sb = _sb()
+        result = sb.table("pets").update(updates).eq("id", pet_id).execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Mascota no encontrada")
+        
+        return {"pet": result.data[0], "message": "Mascota actualizada exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error actualizando mascota: {str(e)}")
+
+@router.delete("/{pet_id}")
+async def delete_pet(pet_id: str):
+    """Elimina una mascota (y todos sus datos relacionados por CASCADE)"""
+    try:
+        sb = _sb()
+        result = sb.table("pets").delete().eq("id", pet_id).execute()
+        return {"message": "Mascota eliminada exitosamente"}
+    except Exception as e:
+        raise HTTPException(500, f"Error eliminando mascota: {str(e)}")
+
+# ==============================================
+# ENDPOINTS DE HISTORIAL DE SALUD
+# ==============================================
+
+@router.get("/{pet_id}/health-history")
+async def get_health_history(
+    pet_id: str,
+    limit: int = Query(50, description="Límite de resultados"),
+    offset: int = Query(0, description="Offset para paginación")
+):
+    """Obtiene el historial de salud de una mascota"""
+    try:
+        sb = _sb()
+        result = sb.table("historial_salud")\
+            .select("*")\
+            .eq("id_mascota", pet_id)\
+            .order("fecha", desc=True)\
+            .limit(limit)\
+            .offset(offset)\
+            .execute()
+        return {"history": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo historial: {str(e)}")
+
+@router.post("/{pet_id}/health-history")
+async def add_health_event(
+    pet_id: str,
+    event_data: Dict[str, Any] = Body(...)
+):
+    """Agrega un evento al historial de salud"""
+    try:
+        sb = _sb()
+        event_data["id_mascota"] = pet_id
+        
+        required_fields = ["tipo_evento", "descripcion"]
+        for field in required_fields:
+            if field not in event_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        result = sb.table("historial_salud").insert(event_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando evento de salud")
+        
+        return {"event": result.data[0], "message": "Evento agregado exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error agregando evento: {str(e)}")
+
+# ==============================================
+# ENDPOINTS DE VACUNACIONES Y TRATAMIENTOS
+# ==============================================
+
+@router.get("/{pet_id}/vaccinations")
+async def get_vaccinations(pet_id: str):
+    """Obtiene todas las vacunaciones y tratamientos de una mascota"""
+    try:
+        sb = _sb()
+        result = sb.table("vacunacion_tratamiento")\
+            .select("*")\
+            .eq("id_mascota", pet_id)\
+            .order("fecha_inicio", desc=True)\
+            .execute()
+        return {"vaccinations": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo vacunaciones: {str(e)}")
+
+@router.post("/{pet_id}/vaccinations")
+async def add_vaccination(
+    pet_id: str,
+    vaccination_data: Dict[str, Any] = Body(...)
+):
+    """Agrega una vacunación o tratamiento"""
+    try:
+        sb = _sb()
+        vaccination_data["id_mascota"] = pet_id
+        
+        required_fields = ["tipo", "nombre", "fecha_inicio"]
+        for field in required_fields:
+            if field not in vaccination_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        result = sb.table("vacunacion_tratamiento").insert(vaccination_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando vacunación")
+        
+        return {"vaccination": result.data[0], "message": "Vacunación agregada exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error agregando vacunación: {str(e)}")
+
+@router.put("/vaccinations/{vaccination_id}")
+async def update_vaccination(
+    vaccination_id: str,
+    updates: Dict[str, Any] = Body(...)
+):
+    """Actualiza una vacunación existente"""
+    try:
+        sb = _sb()
+        result = sb.table("vacunacion_tratamiento")\
+            .update(updates)\
+            .eq("id", vaccination_id)\
+            .execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Vacunación no encontrada")
+        
+        return {"vaccination": result.data[0], "message": "Vacunación actualizada exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error actualizando vacunación: {str(e)}")
+
+# ==============================================
+# ENDPOINTS DE MEDICAMENTOS
+# ==============================================
+
+@router.get("/{pet_id}/medications")
+async def get_medications(pet_id: str, active_only: bool = Query(False)):
+    """Obtiene los medicamentos de una mascota"""
+    try:
+        sb = _sb()
+        query = sb.table("medicamentos_activos")\
+            .select("*")\
+            .eq("id_mascota", pet_id)
+        
+        if active_only:
+            query = query.eq("activo", True)
+        
+        result = query.order("fecha_inicio", desc=True).execute()
+        return {"medications": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo medicamentos: {str(e)}")
+
+@router.post("/{pet_id}/medications")
+async def add_medication(
+    pet_id: str,
+    medication_data: Dict[str, Any] = Body(...)
+):
+    """Agrega un medicamento activo"""
+    try:
+        sb = _sb()
+        medication_data["id_mascota"] = pet_id
+        
+        required_fields = ["nombre", "dosis", "frecuencia", "fecha_inicio"]
+        for field in required_fields:
+            if field not in medication_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        result = sb.table("medicamentos_activos").insert(medication_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando medicamento")
+        
+        return {"medication": result.data[0], "message": "Medicamento agregado exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error agregando medicamento: {str(e)}")
+
+@router.put("/medications/{medication_id}")
+async def update_medication(
+    medication_id: str,
+    updates: Dict[str, Any] = Body(...)
+):
+    """Actualiza un medicamento (puede desactivarlo)"""
+    try:
+        sb = _sb()
+        result = sb.table("medicamentos_activos")\
+            .update(updates)\
+            .eq("id", medication_id)\
+            .execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Medicamento no encontrado")
+        
+        return {"medication": result.data[0], "message": "Medicamento actualizado exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error actualizando medicamento: {str(e)}")
+
+# ==============================================
+# ENDPOINTS DE INDICADORES DE BIENESTAR
+# ==============================================
+
+@router.get("/{pet_id}/wellness")
+async def get_wellness_indicators(
+    pet_id: str,
+    limit: int = Query(30, description="Límite de resultados (últimos N registros)")
+):
+    """Obtiene los indicadores de bienestar de una mascota"""
+    try:
+        sb = _sb()
+        result = sb.table("indicador_bienestar")\
+            .select("*")\
+            .eq("id_mascota", pet_id)\
+            .order("fecha", desc=True)\
+            .limit(limit)\
+            .execute()
+        return {"indicators": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo indicadores: {str(e)}")
+
+@router.post("/{pet_id}/wellness")
+async def add_wellness_indicator(
+    pet_id: str,
+    indicator_data: Dict[str, Any] = Body(...)
+):
+    """Agrega un indicador de bienestar (peso, actividad, etc.)"""
+    try:
+        sb = _sb()
+        indicator_data["id_mascota"] = pet_id
+        
+        result = sb.table("indicador_bienestar").insert(indicator_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando indicador")
+        
+        return {"indicator": result.data[0], "message": "Indicador agregado exitosamente"}
+    except Exception as e:
+        raise HTTPException(500, f"Error agregando indicador: {str(e)}")
+
+# ==============================================
+# ENDPOINTS DE RECORDATORIOS
+# ==============================================
+
+@router.get("/{pet_id}/reminders")
+async def get_reminders(
+    pet_id: str,
+    active_only: bool = Query(True),
+    upcoming_only: bool = Query(False)
+):
+    """Obtiene los recordatorios de una mascota"""
+    try:
+        sb = _sb()
+        query = sb.table("recordatorio")\
+            .select("*")\
+            .eq("id_mascota", pet_id)
+        
+        if active_only:
+            query = query.eq("activo", True)
+        
+        if upcoming_only:
+            query = query.gte("fecha_programada", date.today().isoformat())
+        
+        result = query.order("fecha_programada", desc=False).execute()
+        return {"reminders": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo recordatorios: {str(e)}")
+
+@router.post("/{pet_id}/reminders")
+async def create_reminder(
+    pet_id: str,
+    reminder_data: Dict[str, Any] = Body(...)
+):
+    """Crea un nuevo recordatorio"""
+    try:
+        sb = _sb()
+        reminder_data["id_mascota"] = pet_id
+        
+        required_fields = ["tipo", "titulo", "fecha_programada"]
+        for field in required_fields:
+            if field not in reminder_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        result = sb.table("recordatorio").insert(reminder_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando recordatorio")
+        
+        return {"reminder": result.data[0], "message": "Recordatorio creado exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error creando recordatorio: {str(e)}")
+
+@router.put("/reminders/{reminder_id}/complete")
+async def complete_reminder(reminder_id: str):
+    """Marca un recordatorio como cumplido"""
+    try:
+        sb = _sb()
+        result = sb.table("recordatorio")\
+            .update({
+                "cumplido": True,
+                "fecha_cumplido": datetime.now().isoformat()
+            })\
+            .eq("id", reminder_id)\
+            .execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Recordatorio no encontrado")
+        
+        return {"reminder": result.data[0], "message": "Recordatorio marcado como cumplido"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error actualizando recordatorio: {str(e)}")
+
+# ==============================================
+# ENDPOINTS DE DOCUMENTOS MÉDICOS
+# ==============================================
+
+@router.get("/{pet_id}/documents")
+async def get_medical_documents(pet_id: str):
+    """Obtiene todos los documentos médicos de una mascota"""
+    try:
+        sb = _sb()
+        result = sb.table("documento_medico")\
+            .select("*")\
+            .eq("id_mascota", pet_id)\
+            .order("fecha_documento", desc=True)\
+            .execute()
+        return {"documents": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo documentos: {str(e)}")
+
+@router.post("/{pet_id}/documents")
+async def add_medical_document(
+    pet_id: str,
+    document_data: Dict[str, Any] = Body(...)
+):
+    """Agrega un documento médico"""
+    try:
+        sb = _sb()
+        document_data["id_mascota"] = pet_id
+        
+        required_fields = ["tipo_documento", "nombre", "archivo_url"]
+        for field in required_fields:
+            if field not in document_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        result = sb.table("documento_medico").insert(document_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando documento")
+        
+        return {"document": result.data[0], "message": "Documento agregado exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error agregando documento: {str(e)}")
+
+# ==============================================
+# ENDPOINTS DE PLANES DE CUIDADO
+# ==============================================
+
+@router.get("/{pet_id}/care-plans")
+async def get_care_plans(pet_id: str, active_only: bool = Query(False)):
+    """Obtiene los planes de cuidado de una mascota"""
+    try:
+        sb = _sb()
+        query = sb.table("plan_cuidado")\
+            .select("*, checklist_cuidado(*)")\
+            .eq("id_mascota", pet_id)
+        
+        if active_only:
+            query = query.eq("activo", True)
+        
+        result = query.order("fecha_inicio", desc=True).execute()
+        return {"care_plans": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo planes de cuidado: {str(e)}")
+
+@router.post("/{pet_id}/care-plans")
+async def create_care_plan(
+    pet_id: str,
+    plan_data: Dict[str, Any] = Body(...)
+):
+    """Crea un nuevo plan de cuidado"""
+    try:
+        sb = _sb()
+        plan_data["id_mascota"] = pet_id
+        
+        required_fields = ["nombre", "fecha_inicio"]
+        for field in required_fields:
+            if field not in plan_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        # Extraer checklist si existe
+        checklist_items = plan_data.pop("checklist", [])
+        
+        result = sb.table("plan_cuidado").insert(plan_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando plan de cuidado")
+        
+        plan_id = result.data[0]["id"]
+        
+        # Agregar items del checklist si existen
+        if checklist_items:
+            checklist_data = [
+                {**item, "id_plan": plan_id} for item in checklist_items
+            ]
+            sb.table("checklist_cuidado").insert(checklist_data).execute()
+        
+        return {"care_plan": result.data[0], "message": "Plan de cuidado creado exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error creando plan de cuidado: {str(e)}")
+
+@router.put("/care-plans/{plan_id}/checklist/{item_id}")
+async def update_checklist_item(
+    plan_id: str,
+    item_id: str,
+    updates: Dict[str, Any] = Body(...)
+):
+    """Actualiza un item del checklist (marcar como completado, etc.)"""
+    try:
+        sb = _sb()
+        result = sb.table("checklist_cuidado")\
+            .update(updates)\
+            .eq("id", item_id)\
+            .eq("id_plan", plan_id)\
+            .execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Item del checklist no encontrado")
+        
+        return {"item": result.data[0], "message": "Item actualizado exitosamente"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error actualizando item: {str(e)}")
+
+

routers/rag_search.py

@@ -0,0 +1,385 @@
+"""
+Router de Búsqueda RAG (Retrieval Augmented Generation)
+=======================================================
+
+Este router implementa búsqueda semántica usando RAG (Retrieval Augmented Generation).
+RAG combina búsqueda vectorial con embeddings para encontrar información relevante.
+
+Funcionalidades:
+- Búsqueda de reportes similares usando embeddings
+- Búsqueda con filtros de ubicación
+- Guardar y recuperar embeddings de reportes
+- Estadísticas de embeddings
+
+Los embeddings se almacenan en Supabase usando pgvector para búsquedas eficientes.
+"""
+
+# =========================
+# Imports de FastAPI
+# =========================
+from fastapi import APIRouter, Body, HTTPException, Query
+
+# =========================
+# Imports de Python estándar
+# =========================
+import os  # Para variables de entorno
+import sys  # Para manipular el path de Python
+
+# =========================
+# Imports de pathlib
+# =========================
+from pathlib import Path  # Para trabajar con rutas de forma multiplataforma
+
+# =========================
+# Imports de tipos
+# =========================
+from typing import Any, Dict, List, Optional  # Para type hints
+
+# =========================
+# Imports de NumPy
+# =========================
+import numpy as np  # Para operaciones con vectores
+
+# =========================
+# Imports de Supabase
+# =========================
+from supabase import Client  # Cliente de Supabase
+
+# Agregar la carpeta parent al path para poder importar utils
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# Crear el router con prefijo /rag
+router = APIRouter(prefix="/rag", tags=["rag-search"])
+
+def _sb() -> Client:
+    """
+    Crea un cliente de Supabase con configuración optimizada de timeouts.
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        HTTPException: Si no se puede conectar a Supabase
+    """
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+@router.post("/search")
+async def rag_search(
+    embedding: List[float] = Body(..., description="Vector de embedding (512 dimensiones)"),
+    match_threshold: float = Query(0.7, ge=0.0, le=1.0, description="Umbral mínimo de similitud"),
+    match_count: int = Query(10, ge=1, le=50, description="Número máximo de resultados"),
+    filter_species: Optional[str] = Query(None, description="Filtrar por especie"),
+    filter_type: Optional[str] = Query(None, description="Filtrar por tipo (lost/found)")
+):
+    """
+    Búsqueda RAG usando embeddings almacenados en Supabase.
+    
+    Este endpoint busca reportes similares basándose en similitud de embeddings.
+    Usa la función SQL search_similar_reports que utiliza pgvector para búsqueda
+    vectorial eficiente.
+    
+    Args:
+        embedding: Vector de embedding de 512 dimensiones (debe ser exactamente 512)
+        match_threshold: Umbral mínimo de similitud (0.0-1.0, default 0.7)
+        match_count: Número máximo de resultados (1-50, default 10)
+        filter_species: Filtrar por especie (opcional, ej: 'dog', 'cat')
+        filter_type: Filtrar por tipo de reporte (opcional, 'lost' o 'found')
+        
+    Returns:
+        dict: Resultados con lista de reportes similares, conteo y parámetros de búsqueda
+        
+    Raises:
+        HTTPException 400: Si el embedding no tiene 512 dimensiones
+        HTTPException 500: Si hay error en la búsqueda
+    """
+    try:
+        # Validar que el embedding tenga 512 dimensiones
+        if len(embedding) != 512:
+            raise HTTPException(400, f"El embedding debe tener 512 dimensiones, se recibieron {len(embedding)}")
+        
+        sb = _sb()
+        
+        # Llamar a la función SQL de búsqueda
+        result = sb.rpc('search_similar_reports', {
+            'query_embedding': embedding,
+            'match_threshold': match_threshold,
+            'match_count': match_count,
+            'filter_species': filter_species,
+            'filter_type': filter_type
+        }).execute()
+        
+        if not result.data:
+            return {
+                "results": [],
+                "count": 0,
+                "message": "No se encontraron reportes similares"
+            }
+        
+        return {
+            "results": result.data,
+            "count": len(result.data),
+            "search_params": {
+                "match_threshold": match_threshold,
+                "match_count": match_count,
+                "filter_species": filter_species,
+                "filter_type": filter_type
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error en búsqueda RAG: {str(e)}")
+
+@router.post("/search-with-location")
+async def rag_search_with_location(
+    embedding: List[float] = Body(..., description="Vector de embedding (512 dimensiones)"),
+    user_lat: float = Query(..., description="Latitud del usuario"),
+    user_lng: float = Query(..., description="Longitud del usuario"),
+    max_distance_km: float = Query(10.0, ge=0.1, le=100.0, description="Distancia máxima en km"),
+    match_threshold: float = Query(0.7, ge=0.0, le=1.0, description="Umbral mínimo de similitud"),
+    match_count: int = Query(10, ge=1, le=50, description="Número máximo de resultados"),
+    filter_species: Optional[str] = Query(None, description="Filtrar por especie"),
+    filter_type: Optional[str] = Query(None, description="Filtrar por tipo (lost/found)")
+):
+    """
+    Búsqueda RAG con filtro geográfico.
+    
+    Este endpoint combina similitud de embeddings con proximidad geográfica.
+    Busca reportes que sean visualmente similares Y estén dentro del radio especificado.
+    
+    Args:
+        embedding: Vector de embedding de 512 dimensiones
+        user_lat: Latitud del usuario (requerida)
+        user_lng: Longitud del usuario (requerida)
+        max_distance_km: Distancia máxima en kilómetros (0.1-100, default 10.0)
+        match_threshold: Umbral mínimo de similitud (0.0-1.0, default 0.7)
+        match_count: Número máximo de resultados (1-50, default 10)
+        filter_species: Filtrar por especie (opcional)
+        filter_type: Filtrar por tipo de reporte (opcional)
+        
+    Returns:
+        dict: Resultados con lista de reportes similares dentro del radio, conteo y parámetros
+        
+    Raises:
+        HTTPException 400: Si el embedding no tiene 512 dimensiones
+        HTTPException 500: Si hay error en la búsqueda
+    """
+    try:
+        # Validar que el embedding tenga 512 dimensiones
+        if len(embedding) != 512:
+            raise HTTPException(400, f"El embedding debe tener 512 dimensiones, se recibieron {len(embedding)}")
+        
+        sb = _sb()
+        
+        # Llamar a la función SQL de búsqueda con ubicación
+        result = sb.rpc('search_similar_reports_with_location', {
+            'query_embedding': embedding,
+            'user_lat': user_lat,
+            'user_lng': user_lng,
+            'max_distance_km': max_distance_km,
+            'match_threshold': match_threshold,
+            'match_count': match_count,
+            'filter_species': filter_species,
+            'filter_type': filter_type
+        }).execute()
+        
+        if not result.data:
+            return {
+                "results": [],
+                "count": 0,
+                "message": "No se encontraron reportes similares en el área especificada"
+            }
+        
+        return {
+            "results": result.data,
+            "count": len(result.data),
+            "search_params": {
+                "user_location": {"lat": user_lat, "lng": user_lng},
+                "max_distance_km": max_distance_km,
+                "match_threshold": match_threshold,
+                "match_count": match_count,
+                "filter_species": filter_species,
+                "filter_type": filter_type
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error en búsqueda RAG con ubicación: {str(e)}")
+
+@router.post("/save-embedding/{report_id}")
+async def save_embedding(
+    report_id: str,
+    embedding: List[float] = Body(..., description="Vector de embedding (512 dimensiones)")
+):
+    """
+    Guarda un embedding en Supabase para un reporte específico.
+    
+    Este endpoint actualiza el campo embedding de un reporte en la base de datos.
+    El embedding se almacena usando pgvector para permitir búsquedas vectoriales eficientes.
+    
+    Args:
+        report_id: ID del reporte (UUID)
+        embedding: Vector de embedding de 512 dimensiones
+        
+    Returns:
+        dict: Confirmación de éxito con report_id y dimensiones
+        
+    Raises:
+        HTTPException 400: Si el embedding no tiene 512 dimensiones
+        HTTPException 404: Si el reporte no existe
+        HTTPException 500: Si hay error guardando el embedding
+    """
+    try:
+        # Validar que el embedding tenga 512 dimensiones
+        if len(embedding) != 512:
+            raise HTTPException(400, f"El embedding debe tener 512 dimensiones, se recibieron {len(embedding)}")
+        
+        sb = _sb()
+        
+        # Usar la función RPC para actualizar el embedding
+        result = sb.rpc('update_report_embedding', {
+            'report_id': report_id,
+            'embedding_vector': embedding
+        }).execute()
+        
+        if not result.data:
+            raise HTTPException(404, f"Reporte {report_id} no encontrado")
+        
+        return {
+            "success": True,
+            "report_id": report_id,
+            "message": "Embedding guardado exitosamente",
+            "embedding_dimensions": len(embedding)
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error guardando embedding: {str(e)}")
+
+@router.get("/embedding/{report_id}")
+async def get_embedding(report_id: str):
+    """
+    Obtiene el embedding de un reporte específico.
+    
+    Este endpoint recupera el embedding almacenado de un reporte desde Supabase.
+    Útil para verificar si un reporte tiene embedding o para análisis.
+    
+    Args:
+        report_id: ID del reporte (UUID)
+        
+    Returns:
+        dict: Embedding del reporte con dimensiones
+        
+    Raises:
+        HTTPException 404: Si el reporte no tiene embedding o no existe
+        HTTPException 500: Si hay error obteniendo el embedding
+    """
+    try:
+        sb = _sb()
+        
+        result = sb.rpc('get_report_embedding', {
+            'report_id': report_id
+        }).execute()
+        
+        if not result.data or result.data is None:
+            raise HTTPException(404, f"Reporte {report_id} no tiene embedding o no existe")
+        
+        # El embedding viene como vector de pgvector
+        embedding = result.data
+        
+        return {
+            "report_id": report_id,
+            "embedding": embedding if isinstance(embedding, list) else embedding.tolist() if hasattr(embedding, 'tolist') else list(embedding),
+            "dimensions": len(embedding) if isinstance(embedding, (list, np.ndarray)) else 512
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo embedding: {str(e)}")
+
+@router.get("/has-embedding/{report_id}")
+async def check_has_embedding(report_id: str):
+    """
+    Verifica si un reporte tiene embedding.
+    
+    Este endpoint verifica rápidamente si un reporte tiene un embedding almacenado.
+    Útil para determinar si se necesita generar un embedding para un reporte.
+    
+    Args:
+        report_id: ID del reporte (UUID)
+        
+    Returns:
+        dict: report_id y has_embedding (boolean)
+        
+    Raises:
+        HTTPException 500: Si hay error verificando el embedding
+    """
+    try:
+        sb = _sb()
+        
+        result = sb.rpc('has_embedding', {
+            'report_id': report_id
+        }).execute()
+        
+        return {
+            "report_id": report_id,
+            "has_embedding": result.data if isinstance(result.data, bool) else bool(result.data)
+        }
+        
+    except Exception as e:
+        raise HTTPException(500, f"Error verificando embedding: {str(e)}")
+
+@router.get("/stats")
+async def get_rag_stats():
+    """
+    Obtiene estadísticas sobre los embeddings en la base de datos.
+    
+    Este endpoint proporciona información sobre:
+    - Total de reportes
+    - Reportes con embedding
+    - Reportes activos con embedding
+    - Porcentaje de cobertura (reportes con embedding / total)
+    
+    Returns:
+        dict: Estadísticas de embeddings con conteos y porcentajes
+        
+    Raises:
+        HTTPException 500: Si hay error obteniendo las estadísticas
+    """
+    try:
+        sb = _sb()
+        
+        # Contar total de reportes
+        total_result = sb.table("reports").select("id", count="exact").execute()
+        total_count = total_result.count if hasattr(total_result, 'count') else len(total_result.data)
+        
+        # Contar reportes con embedding
+        with_embedding_result = sb.table("reports").select("id", count="exact").not_.is_("embedding", "null").execute()
+        with_embedding_count = with_embedding_result.count if hasattr(with_embedding_result, 'count') else len(with_embedding_result.data)
+        
+        # Contar reportes activos con embedding
+        active_with_embedding_result = sb.table("reports").select("id", count="exact").eq("status", "active").not_.is_("embedding", "null").execute()
+        active_with_embedding_count = active_with_embedding_result.count if hasattr(active_with_embedding_result, 'count') else len(active_with_embedding_result.data)
+        
+        return {
+            "total_reports": total_count,
+            "reports_with_embedding": with_embedding_count,
+            "active_reports_with_embedding": active_with_embedding_count,
+            "coverage_percentage": round((with_embedding_count / total_count * 100) if total_count > 0 else 0, 2),
+            "embedding_dimensions": 512
+        }
+        
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo estadísticas: {str(e)}")
+
+
+

routers/reports.py

@@ -0,0 +1,594 @@
+"""
+Router de Reportes
+==================
+
+Este router maneja todas las operaciones CRUD (Create, Read, Update, Delete) 
+relacionadas con reportes de mascotas perdidas y encontradas.
+
+Funcionalidades principales:
+- Crear reportes nuevos (con generación automática de embeddings)
+- Obtener reportes (todos, por usuario, por ID, cercanos)
+- Actualizar reportes existentes
+- Eliminar/cancelar reportes
+- Subir fotos de mascotas
+- Generar embeddings de imágenes en segundo plano
+
+Los embeddings se generan automáticamente cuando se crea un reporte con fotos,
+permitiendo búsquedas visuales inteligentes más adelante.
+"""
+
+from fastapi import APIRouter, HTTPException, Query, Body, BackgroundTasks
+from typing import List, Dict, Any, Optional
+import os, math, sys
+from pathlib import Path
+from supabase import Client
+import httpx  # Para hacer peticiones HTTP (descargar imágenes)
+import asyncio  # Para operaciones asíncronas
+from services.embeddings import image_bytes_to_vec  # Función para generar embeddings
+
+# Agregar la carpeta parent al path para poder importar utils
+# Esto permite usar imports como "from utils.supabase_client import ..."
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# =========================
+# Configuración
+# =========================
+# Verificar si la generación local de embeddings está habilitada
+# Si está habilitada, los embeddings se generan en el servidor usando MegaDescriptor
+# Si no, se espera que se generen externamente
+GENERATE_EMBEDDINGS_LOCALLY = (
+    os.getenv("GENERATE_EMBEDDINGS_LOCALLY", "false").lower() in ("1", "true", "yes")
+)
+
+# Crear el router con prefijo /reports
+# Todas las rutas de este archivo empezarán con /reports
+router = APIRouter(prefix="/reports", tags=["reports"])
+
+def _sb() -> Client:
+    """
+    Crea un cliente de Supabase con configuración optimizada de timeouts.
+    
+    Esta función es un helper que crea y retorna un cliente de Supabase.
+    Si falla la conexión, lanza una excepción HTTP 500.
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        HTTPException: Si no se puede conectar a Supabase
+    """
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+def _extract_coords(location_data) -> Optional[tuple]:
+    """
+    Extrae coordenadas de diferentes formatos de ubicación.
+    
+    Esta función maneja múltiples formatos de datos geográficos:
+    - PostGIS: String con formato "SRID=4326;POINT(lon lat)"
+    - GeoJSON: Objeto con formato {"type":"Point","coordinates":[lon,lat]}
+    
+    Args:
+        location_data: Datos de ubicación en cualquier formato soportado
+        
+    Returns:
+        Tupla (latitud, longitud) o None si no se pueden extraer
+        
+    Ejemplo:
+        >>> _extract_coords("SRID=4326;POINT(-58.3816 -34.6037)")
+        (-34.6037, -58.3816)
+        >>> _extract_coords({"type":"Point","coordinates":[-58.3816, -34.6037]})
+        (-34.6037, -58.3816)
+    """
+    # Si no hay datos, retornar None
+    if not location_data:
+        return None
+    
+    # =========================
+    # Formato PostGIS
+    # =========================
+    # PostGIS es una extensión de PostgreSQL para datos geográficos
+    # Formato: "SRID=4326;POINT(lon lat)"
+    # SRID 4326 es el sistema de coordenadas WGS84 (lat/lon estándar)
+    if isinstance(location_data, str) and "POINT(" in location_data:
+        try:
+            # Extraer la parte del string que contiene las coordenadas
+            # Ejemplo: "SRID=4326;POINT(-58.3816 -34.6037)" -> "-58.3816 -34.6037"
+            coords_str = location_data.split("POINT(")[1].split(")")[0]
+            # Convertir a float y extraer lon y lat
+            lon, lat = map(float, coords_str.split())
+            # Retornar como (lat, lon) para consistencia
+            return (lat, lon)
+        except:
+            # Si falla el parsing, retornar None
+            return None
+    
+    # =========================
+    # Formato GeoJSON
+    # =========================
+    # GeoJSON es un formato estándar para datos geográficos
+    # Formato: {"type":"Point","coordinates":[lon,lat]}
+    # Nota: GeoJSON usa [lon, lat] pero retornamos (lat, lon) para consistencia
+    if isinstance(location_data, dict) and "coordinates" in location_data:
+        try:
+            # Extraer coordenadas del array
+            lon, lat = location_data["coordinates"]
+            # Retornar como (lat, lon) para consistencia
+            return (lat, lon)
+        except:
+            # Si falla el parsing, retornar None
+            return None
+    
+    # Si no coincide con ningún formato conocido, retornar None
+    return None
+
+def haversine_km(lat1, lon1, lat2, lon2):
+    """
+    Calcula la distancia en kilómetros entre dos puntos geográficos usando la fórmula de Haversine.
+    
+    La fórmula de Haversine calcula la distancia del círculo máximo entre dos puntos
+    en una esfera (la Tierra), considerando que es una esfera perfecta.
+    
+    Args:
+        lat1, lon1: Latitud y longitud del primer punto (en grados)
+        lat2, lon2: Latitud y longitud del segundo punto (en grados)
+    
+    Returns:
+        Distancia en kilómetros entre los dos puntos
+    """
+    R = 6371.0  # Radio de la Tierra en kilómetros
+    # Convertir diferencias de latitud y longitud a radianes
+    dlat = math.radians(lat2 - lat1)
+    dlon = math.radians(lon2 - lon1)
+    # Aplicar la fórmula de Haversine
+    a = math.sin(dlat/2)**2 + math.cos(math.radians(lat1)) * math.cos(math.radians(lat2)) * math.sin(dlon/2)**2
+    return 2 * R * math.asin(math.sqrt(a))
+
+async def generate_and_save_embedding(report_id: str, photo_url: str):
+    """
+    Genera y guarda el embedding de una imagen para un reporte.
+    
+    Esta función se ejecuta en segundo plano (background task) para no bloquear
+    la respuesta HTTP al crear un reporte. El proceso completo es:
+    1. Descarga la imagen desde Supabase Storage
+    2. Genera un embedding usando MegaDescriptor (vector numérico de 1536 dimensiones)
+    3. Guarda el embedding en la columna 'embedding' de la tabla 'reports'
+    4. Opcionalmente busca automáticamente matches (coincidencias) con otros reportes
+    
+    Los embeddings permiten búsquedas visuales inteligentes: cuando un usuario
+    sube una foto de una mascota, el sistema puede encontrar reportes con fotos
+    visualmente similares usando búsqueda vectorial.
+    
+    Args:
+        report_id: ID del reporte en la base de datos (UUID)
+        photo_url: URL completa de la imagen en Supabase Storage
+                  Ejemplo: https://xxxxx.supabase.co/storage/v1/object/public/photos/xxx.jpg
+    
+    Nota: 
+    - Si falla, no lanza excepción para no afectar la creación del reporte
+    - Usa reintentos automáticos (hasta 3 intentos) para manejar errores temporales
+    - Si la generación local de embeddings está desactivada, esta función no hace nada
+    """
+    max_retries = 3  # Número máximo de intentos si falla (para manejar errores temporales de red)
+    
+    # Intentar hasta max_retries veces
+    for attempt in range(max_retries):
+        try:
+            # Log del intento (diferente mensaje si es reintento)
+            if attempt > 0:
+                print(f"🔄 [embedding] Reintento {attempt + 1}/{max_retries} para reporte {report_id}")
+            else:
+                print(f"🔄 [embedding] Generando embedding para reporte {report_id} desde {photo_url}")
+            
+            # =========================
+            # Descargar la imagen
+            # =========================
+            # Descargar la imagen desde Supabase Storage usando httpx
+            # Timeout aumentado para Windows que puede tener problemas de red
+            timeout = httpx.Timeout(60.0, connect=60.0)  # 60 segundos total y para conectar
+            async with httpx.AsyncClient(timeout=timeout, follow_redirects=True) as client:
+                response = await client.get(photo_url)
+                response.raise_for_status()  # Lanza error si el status code no es 2xx
+                image_bytes = response.content  # Obtener los bytes de la imagen
+            
+            print(f"🔍 Imagen descargada: {len(image_bytes)} bytes")
+            
+            # Generar embedding usando MegaDescriptor
+            # image_bytes_to_vec convierte la imagen en un vector numérico
+            vec = image_bytes_to_vec(image_bytes)
+            vec_list = vec.tolist()  # Convertir numpy array a lista de Python
+            
+            print(f"🔍 Embedding generado: {len(vec_list)} dimensiones")
+            
+            # Guardar el embedding en la columna 'embedding' del reporte
+            # pgvector (extensión de PostgreSQL) acepta arrays de Python directamente
+            sb = _sb()
+            result = sb.table('reports').update({
+                'embedding': vec_list
+            }).eq('id', report_id).execute()
+            
+            if result.data:
+                print(f"✅ [embedding] Embedding guardado exitosamente para reporte {report_id}")
+                
+                # Buscar matches automáticamente después de generar el embedding
+                # Esto permite encontrar coincidencias inmediatamente sin esperar
+                try:
+                    await find_and_save_matches(report_id)
+                except Exception as match_error:
+                    # Si falla la búsqueda de matches, no es crítico, solo logueamos
+                    print(f"⚠️ [matches] Error buscando matches (no crítico): {str(match_error)}")
+                
+                return  # Éxito, salir de la función
+            else:
+                print(f"⚠️ [embedding] No se pudo guardar embedding para reporte {report_id}")
+                
+        except httpx.TimeoutException as e:
+            # Si hay timeout (la descarga tarda mucho), reintentamos
+            print(f"⏱️ [embedding] Timeout al procesar imagen (intento {attempt + 1}/{max_retries})")
+            if attempt == max_retries - 1:
+                print(f"❌ [embedding] Error después de {max_retries} intentos: Timeout")
+            else:
+                # Backoff exponencial: esperamos 1s, 2s, 4s entre intentos
+                await asyncio.sleep(2 ** attempt)
+                
+        except Exception as e:
+            # Cualquier otro error, logueamos y reintentamos
+            print(f"❌ [embedding] Error generando embedding para reporte {report_id}: {str(e)}")
+            if attempt < max_retries - 1:
+                await asyncio.sleep(2 ** attempt)  # Backoff exponencial
+            # No lanzar excepción para no afectar la creación del reporte
+
+
+async def find_and_save_matches(report_id: str, threshold: float = 0.1, max_matches: int = 10):
+    """
+    Busca matches (coincidencias) similares para un reporte y los guarda automáticamente.
+    
+    Esta función:
+    1. Obtiene el embedding del reporte base
+    2. Busca reportes del tipo opuesto (lost ↔ found) con embeddings
+    3. Calcula la similitud coseno entre embeddings
+    4. Filtra por umbral de similitud (threshold)
+    5. Guarda los matches en la tabla 'matches' de la base de datos
+    
+    Args:
+        report_id: ID del reporte para el cual buscar matches
+        threshold: Umbral mínimo de similitud (0.0 a 1.0). Default: 0.1 (10% de similitud)
+        max_matches: Número máximo de matches a guardar. Default: 10
+    
+    Nota: Si el reporte no tiene embedding, la función retorna sin hacer nada.
+    """
+    try:
+        print(f"🔍 [matches] Buscando coincidencias para reporte {report_id}...")
+        
+        sb = _sb()
+        
+        # Obtener el reporte con su embedding
+        report_result = sb.table("reports")\
+            .select("id, embedding, type, species")\
+            .eq("id", report_id)\
+            .execute()
+        
+        if not report_result.data:
+            print(f"⚠️ [matches] Reporte {report_id} no encontrado")
+            return
+        
+        report = report_result.data[0]
+        report_embedding = report.get("embedding")
+        report_type = report.get("type")
+        
+        if not report_embedding:
+            print(f"⚠️ [matches] Reporte {report_id} no tiene embedding")
+            return
+        
+        # Postgrest devuelve vectores como strings JSON, parsearlos
+        if isinstance(report_embedding, str):
+            import json
+            try:
+                report_embedding = json.loads(report_embedding)
+            except Exception as e:
+                print(f"⚠️ [matches] Error parseando embedding: {e}")
+                return
+        
+        # Determinar tipo opuesto para buscar matches
+        opposite_type = "found" if report_type == "lost" else "lost"
+        
+        # Buscar reportes del tipo opuesto con embeddings
+        candidates = sb.table("reports")\
+            .select("id, embedding, species")\
+            .eq("type", opposite_type)\
+            .eq("status", "active")\
+            .not_.is_("embedding", "null")\
+            .execute()
+        
+        if not candidates.data:
+            print(f"ℹ️ [matches] No hay reportes de tipo '{opposite_type}' para comparar")
+            return
+        
+        # Calcular similitud con todos los candidatos
+        import numpy as np
+        base_vec = np.array(report_embedding, dtype=np.float32)
+        
+        matches_found = []
+        for candidate in candidates.data:
+            try:
+                candidate_embedding = candidate.get("embedding")
+                if not candidate_embedding:
+                    continue
+                
+                # Parsear si es string JSON
+                if isinstance(candidate_embedding, str):
+                    try:
+                        candidate_embedding = json.loads(candidate_embedding)
+                    except:
+                        continue
+                
+                candidate_vec = np.array(candidate_embedding, dtype=np.float32)
+                
+                # Similitud coseno (embeddings ya están normalizados)
+                similarity = float(np.dot(base_vec, candidate_vec))
+                
+                if similarity >= threshold:
+                    matches_found.append({
+                        "candidate_id": candidate["id"],
+                        "similarity": similarity,
+                        "species": candidate.get("species")
+                    })
+            except Exception as e:
+                print(f"⚠️ [matches] Error procesando candidato: {e}")
+                continue
+        
+        # Ordenar por similitud descendente y tomar los mejores
+        matches_found.sort(key=lambda x: x["similarity"], reverse=True)
+        matches_found = matches_found[:max_matches]
+        
+        if not matches_found:
+            print(f"ℹ️ [matches] No se encontraron coincidencias con similitud >= {threshold}")
+            return
+        
+        # Guardar matches en la base de datos
+        matches_saved = 0
+        for match in matches_found:
+            try:
+                match_data = {
+                    "similarity_score": round(match["similarity"], 4),
+                    "matched_by": "ai_visual",
+                    "status": "pending"
+                }
+                
+                # Configurar IDs según el tipo de reporte
+                if report_type == "lost":
+                    match_data["lost_report_id"] = report_id
+                    match_data["found_report_id"] = match["candidate_id"]
+                else:
+                    match_data["lost_report_id"] = match["candidate_id"]
+                    match_data["found_report_id"] = report_id
+                
+                # Verificar si ya existe el match
+                if report_type == "lost":
+                    existing = sb.table("matches")\
+                        .select("id, similarity_score")\
+                        .eq("lost_report_id", report_id)\
+                        .eq("found_report_id", match["candidate_id"])\
+                        .execute()
+                else:
+                    existing = sb.table("matches")\
+                        .select("id, similarity_score")\
+                        .eq("lost_report_id", match["candidate_id"])\
+                        .eq("found_report_id", report_id)\
+                        .execute()
+                
+                if existing.data:
+                    # Actualizar si la nueva similitud es mejor
+                    existing_match = existing.data[0]
+                    if match["similarity"] > (existing_match.get("similarity_score") or 0):
+                        sb.table("matches")\
+                            .update(match_data)\
+                            .eq("id", existing_match["id"])\
+                            .execute()
+                        matches_saved += 1
+                        print(f"  ✅ [matches] Match actualizado: {match['candidate_id']} (similitud: {match['similarity']:.3f})")
+                else:
+                    # Crear nuevo match
+                    sb.table("matches").insert(match_data).execute()
+                    matches_saved += 1
+                    print(f"  ✅ [matches] Match creado: {match['candidate_id']} (similitud: {match['similarity']:.3f})")
+                    
+            except Exception as e:
+                print(f"⚠️ [matches] Error guardando match: {e}")
+                continue
+        
+        print(f"✅ [matches] {matches_saved} coincidencias guardadas para reporte {report_id}")
+        
+    except Exception as e:
+        print(f"❌ [matches] Error en búsqueda de matches: {str(e)}")
+        # No lanzar excepción, solo loguear el error
+
+@router.get("/")
+async def get_all_reports():
+    """Obtiene todos los reportes activos"""
+    try:
+        sb = _sb()
+        result = sb.table("reports").select("*").eq("status", "active").order("created_at", desc=True).execute()
+        return {"reports": result.data, "count": len(result.data)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo reportes: {str(e)}")
+
+@router.get("/nearby")
+async def get_nearby_reports(
+    lat: float = Query(..., description="Latitud"),
+    lng: float = Query(..., description="Longitud"),
+    radius_km: float = Query(10.0, description="Radio en kilómetros")
+):
+    """Obtiene reportes cercanos a una ubicación"""
+    try:
+        sb = _sb()
+        result = sb.table("reports").select("*").eq("status", "active").execute()
+        
+        nearby_reports = []
+        for report in result.data:
+            coords = _extract_coords(report.get("location"))
+            if coords:
+                report_lat, report_lon = coords
+                distance = haversine_km(lat, lng, report_lat, report_lon)
+                if distance <= radius_km:
+                    report["distance_km"] = round(distance, 2)
+                    nearby_reports.append(report)
+        
+        # Ordenar por distancia
+        nearby_reports.sort(key=lambda x: x["distance_km"])
+        
+        return {"reports": nearby_reports, "count": len(nearby_reports)}
+    except Exception as e:
+        raise HTTPException(500, f"Error obteniendo reportes cercanos: {str(e)}")
+
+@router.get("/{report_id}")
+async def get_report_by_id(report_id: str):
+    """Obtiene un reporte por ID"""
+    try:
+        sb = _sb()
+        result = sb.table("reports").select("*").eq("id", report_id).execute()
+        report_data = result.data[0] if result.data else None
+        
+        if not report_data:
+            raise HTTPException(404, "Reporte no encontrado")
+        
+        return {"report": report_data}
+    except Exception as e:
+        if "404" in str(e):
+            raise e
+        raise HTTPException(500, f"Error obteniendo reporte: {str(e)}")
+
+@router.post("/")
+async def create_report(
+    report_data: Dict[str, Any] = Body(...),
+    background_tasks: BackgroundTasks = None
+):
+    """Crea un nuevo reporte y genera embeddings automáticamente si hay fotos"""
+    try:
+        sb = _sb()
+        
+        # Validar datos requeridos
+        required_fields = ["type", "reporter_id", "species", "description", "location"]
+        for field in required_fields:
+            if field not in report_data:
+                raise HTTPException(400, f"Campo requerido faltante: {field}")
+        
+        # Crear reporte
+        result = sb.table("reports").insert(report_data).execute()
+        
+        if not result.data:
+            raise HTTPException(500, "Error creando reporte")
+        
+        created_report = result.data[0]
+        report_id = created_report.get("id")
+        
+        # Generar embedding automáticamente si hay fotos (de forma síncrona para asegurar que se guarde)
+        photos = created_report.get("photos") or report_data.get("photos", [])
+        if GENERATE_EMBEDDINGS_LOCALLY and photos and isinstance(photos, list) and len(photos) > 0:
+            first_photo = photos[0]
+            if first_photo:
+                print(f"📸 [embedding] Reporte creado con fotos. Generando embedding para reporte {report_id}...")
+                # Generar embedding de forma síncrona para asegurar que se guarde antes de retornar
+                try:
+                    await generate_and_save_embedding(report_id, first_photo)
+                    print(f"✅ [embedding] Embedding generado y guardado para reporte {report_id}")
+                except Exception as e:
+                    print(f"⚠️ [embedding] Error generando embedding (no crítico): {str(e)}")
+                    # No fallar la creación del reporte si falla el embedding
+        elif photos and isinstance(photos, list) and len(photos) > 0:
+            print("ℹ️ [embedding] Generación local desactivada. La IA externa se encargará del embedding.")
+        
+        return {"report": created_report, "message": "Reporte creado exitosamente"}
+    except Exception as e:
+        if "400" in str(e) or "500" in str(e):
+            raise e
+        raise HTTPException(500, f"Error creando reporte: {str(e)}")
+
+@router.put("/{report_id}")
+async def update_report(
+    report_id: str,
+    updates: Dict[str, Any] = Body(...),
+    background_tasks: BackgroundTasks = None
+):
+    """Actualiza un reporte existente y genera embeddings si hay nuevas fotos"""
+    try:
+        sb = _sb()
+        
+        # Obtener el reporte actual para verificar si tiene embedding
+        current_result = sb.table("reports").select("id, photos, embedding").eq("id", report_id).execute()
+        current_report = current_result.data[0] if current_result.data else None
+        
+        if not current_report:
+            raise HTTPException(404, "Reporte no encontrado")
+        
+        # Actualizar reporte
+        result = sb.table("reports").update(updates).eq("id", report_id).execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Reporte no encontrado")
+        
+        updated_report = result.data[0]
+        
+        # Generar embedding si:
+        # 1. Hay fotos nuevas o actualizadas
+        # 2. El reporte no tiene embedding aún
+        photos = updated_report.get("photos") or updates.get("photos", [])
+        has_embedding = current_report.get("embedding") is not None
+        
+        if GENERATE_EMBEDDINGS_LOCALLY and photos and isinstance(photos, list) and len(photos) > 0:
+            first_photo = photos[0]
+            if first_photo and (not has_embedding or "photos" in updates):
+                print(f"📸 [embedding] Reporte actualizado con fotos. Generando embedding para reporte {report_id}...")
+                # Generar embedding de forma síncrona para asegurar que se guarde
+                try:
+                    await generate_and_save_embedding(report_id, first_photo)
+                    print(f"✅ [embedding] Embedding generado y guardado para reporte {report_id}")
+                except Exception as e:
+                    print(f"⚠️ [embedding] Error generando embedding (no crítico): {str(e)}")
+                    # No fallar la actualización del reporte si falla el embedding
+        elif photos and isinstance(photos, list) and len(photos) > 0 and (not has_embedding or "photos" in updates):
+            print("ℹ️ [embedding] Generación local desactivada. La IA externa actualizará el embedding si corresponde.")
+        
+        return {"report": updated_report, "message": "Reporte actualizado exitosamente"}
+    except Exception as e:
+        if "404" in str(e):
+            raise e
+        raise HTTPException(500, f"Error actualizando reporte: {str(e)}")
+
+@router.delete("/{report_id}")
+async def delete_report(report_id: str):
+    """Elimina un reporte (soft delete cambiando status a cancelled)"""
+    try:
+        sb = _sb()
+        result = sb.table("reports").update({"status": "cancelled"}).eq("id", report_id).execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Reporte no encontrado")
+        
+        return {"message": "Reporte eliminado exitosamente"}
+    except Exception as e:
+        if "404" in str(e):
+            raise e
+        raise HTTPException(500, f"Error eliminando reporte: {str(e)}")
+
+@router.post("/{report_id}/resolve")
+async def resolve_report(report_id: str):
+    """Marca un reporte como resuelto"""
+    try:
+        sb = _sb()
+        result = sb.table("reports").update({
+            "status": "resolved",
+            "resolved_at": "now()"
+        }).eq("id", report_id).execute()
+        
+        if not result.data:
+            raise HTTPException(404, "Reporte no encontrado")
+        
+        return {"report": result.data[0], "message": "Reporte marcado como resuelto"}
+    except Exception as e:
+        if "404" in str(e):
+            raise e
+        raise HTTPException(500, f"Error resolviendo reporte: {str(e)}")

routers/reports_labels.py

@@ -0,0 +1,53 @@
+"""
+Router de Etiquetas de Reportes
+================================
+
+Este router maneja la gestión de etiquetas (labels) de los reportes.
+Las etiquetas son metadatos adicionales que se pueden asociar a un reporte
+para mejorar la búsqueda y categorización.
+
+Funcionalidades:
+- Guardar etiquetas para un reporte
+- Actualizar etiquetas existentes
+
+Las etiquetas se almacenan como JSON en la columna 'labels' de la tabla 'reports'.
+"""
+
+from fastapi import APIRouter, HTTPException, Path, Body
+from typing import Any, Dict
+import os, sys
+from pathlib import Path as PathLib
+from supabase import Client
+
+# Agregar la carpeta parent al path para poder importar utils
+sys.path.insert(0, str(PathLib(__file__).parent.parent))
+from utils.supabase_client import get_supabase_client
+
+# Crear el router con prefijo /reports (comparte el mismo prefijo que reports.py)
+router = APIRouter(prefix="/reports", tags=["reports"])
+
+def _sb() -> Client:
+    """
+    Crea un cliente de Supabase con configuración optimizada de timeouts.
+    
+    Returns:
+        Client: Cliente de Supabase configurado
+        
+    Raises:
+        HTTPException: Si no se puede conectar a Supabase
+    """
+    try:
+        return get_supabase_client()
+    except Exception as e:
+        raise HTTPException(500, f"Error conectando a Supabase: {str(e)}")
+
+@router.post("/{report_id}/labels")
+def save_labels(report_id: str = Path(...), payload: Dict[str, Any] = Body(...)):
+    if "labels" not in payload or not isinstance(payload["labels"], list):
+        raise HTTPException(400, "Se espera {'labels': [...]}")
+
+    sb = _sb()
+    res = sb.table("reports").update({"labels": payload}).eq("id", report_id).execute()
+    if not res.data:
+        raise HTTPException(404, "Reporte no encontrado")
+    return {"ok": True, "updated": res.data[0]["id"]}

services/__init__.py

@@ -0,0 +1 @@
+# services/__init__.py

services/embeddings.py

@@ -0,0 +1,235 @@
+"""
+Servicio de Generación de Embeddings con MegaDescriptor
+=======================================================
+
+Este módulo se encarga de generar embeddings (vectores numéricos) de imágenes
+usando el modelo MegaDescriptor, especializado en reconocimiento de animales.
+
+MegaDescriptor es un modelo de deep learning que convierte imágenes en vectores
+de alta dimensión (1536 dimensiones) que capturan características visuales.
+Estos vectores se usan para buscar coincidencias visuales entre reportes de
+mascotas perdidas y encontradas.
+
+Flujo:
+1. Recibe bytes de una imagen
+2. Preprocesa la imagen (redimensiona a 384x384, normaliza)
+3. Pasa la imagen por el modelo MegaDescriptor
+4. Obtiene el embedding (vector de características)
+5. Normaliza el vector (L2 normalization)
+6. Retorna el vector como numpy array
+
+El modelo se carga una sola vez y se reutiliza para todas las peticiones.
+"""
+
+# backend/services/embeddings.py
+import io  # Para trabajar con bytes en memoria
+import asyncio  # Para operaciones asíncronas
+from typing import Optional  # Para type hints
+import numpy as np  # Para arrays numéricos
+from PIL import Image  # Para procesar imágenes
+import torch  # PyTorch para deep learning
+import torchvision.transforms as T  # Transformaciones de imágenes
+import timm  # Biblioteca para cargar modelos pre-entrenados
+
+# =========================
+# Configuración del Modelo MegaDescriptor
+# =========================
+# Detectar si hay GPU disponible (CUDA), si no usa CPU
+# GPU es mucho más rápido pero CPU también funciona
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+
+# Nombre del modelo en Hugging Face Hub
+# MegaDescriptor-L-384 es la versión Large que procesa imágenes de 384x384 píxeles
+MODEL_NAME = "hf-hub:BVRA/MegaDescriptor-L-384"
+
+# La dimensión del embedding se detectará automáticamente al cargar el modelo
+# MegaDescriptor-L-384 genera embeddings de 1536 dimensiones
+EMBEDDING_DIM = None
+
+# Variables globales para cachear el modelo cargado
+# Esto evita cargar el modelo múltiples veces (es costoso en tiempo y memoria)
+_model = None  # El modelo de PyTorch
+_transforms = None  # Las transformaciones de preprocesamiento
+_actual_dim = None  # La dimensión real del embedding (se detecta al cargar)
+
+# Semáforo para limitar concurrencia
+# Permite máximo 2 inferencias simultáneas para evitar saturar la GPU/memoria
+# Si hay más peticiones, esperan su turno
+_inference_semaphore = asyncio.Semaphore(2)
+
+def _load_model():
+    """
+    Carga el modelo MegaDescriptor y sus transformaciones de preprocesamiento.
+    
+    Esta función usa el patrón "lazy loading" - solo carga el modelo la primera vez
+    que se llama. Las siguientes llamadas retornan el modelo ya cargado (cacheado).
+    
+    El modelo se descarga automáticamente desde Hugging Face Hub la primera vez.
+    Puede tardar varios minutos dependiendo de la conexión a internet.
+    
+    Returns:
+        Tupla con (modelo, transformaciones, dimensión_del_embedding)
+    """
+    global _model, _transforms, _actual_dim
+    
+    # Solo cargar si no está cargado ya (singleton pattern)
+    if _model is None:
+        print(f"🔄 Cargando MegaDescriptor en {DEVICE}...")
+        
+        # Cargar modelo desde Hugging Face Hub usando timm
+        # num_classes=0 significa que queremos solo las features (sin capa de clasificación)
+        # Esto nos da el embedding directamente sin pasar por una capa de salida
+        _model = timm.create_model(MODEL_NAME, pretrained=True, num_classes=0)
+        
+        # Mover el modelo a la GPU si está disponible, si no queda en CPU
+        _model = _model.to(DEVICE)
+        
+        # Poner el modelo en modo evaluación (desactiva dropout, batch norm, etc.)
+        # Esto es importante para obtener resultados consistentes
+        _model.eval()
+        
+        # Verificar la dimensión real del embedding haciendo una inferencia de prueba
+        # Creamos una imagen dummy (aleatoria) y vemos qué tamaño de vector produce
+        with torch.no_grad():  # No calcular gradientes (ahorra memoria)
+            # Crear imagen dummy: 1 batch, 3 canales RGB, 384x384 píxeles
+            dummy_input = torch.randn(1, 3, 384, 384).to(DEVICE)
+            dummy_output = _model(dummy_input)  # Pasar por el modelo
+            _actual_dim = dummy_output.shape[-1]  # Obtener la última dimensión (tamaño del vector)
+            print(f"📊 Dimensión del modelo: {_actual_dim}")
+        
+        # Configurar transformaciones de preprocesamiento para las imágenes
+        # Estas transformaciones deben coincidir EXACTAMENTE con las que usó el modelo durante el entrenamiento
+        # MegaDescriptor-L-384 usa normalización [0.5, 0.5, 0.5] que convierte [0, 1] a [-1, 1]
+        _transforms = T.Compose([
+            T.Resize(size=(384, 384)),  # Redimensionar a 384x384 (tamaño que espera MegaDescriptor)
+            T.ToTensor(),  # Convertir PIL Image a tensor de PyTorch (0-255 -> 0-1)
+            # Normalizar: mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5]
+            # Esto convierte el rango de [0, 1] a [-1, 1] (estándar para MegaDescriptor)
+            T.Normalize([0.5, 0.5, 0.5], [0.5, 0.5, 0.5])
+        ])
+        print(f"✅ MegaDescriptor cargado exitosamente")
+    
+    # Retornar el modelo, transformaciones y dimensión (ya cargados o recién cargados)
+    return _model, _transforms, _actual_dim
+
+async def image_bytes_to_vec_async(image_bytes: bytes) -> np.ndarray:
+    """
+    Genera embedding de forma asíncrona con control de concurrencia.
+    
+    Esta es la versión asíncrona recomendada para usar en endpoints FastAPI.
+    Usa un semáforo para limitar cuántas inferencias se ejecutan simultáneamente,
+    evitando saturar la GPU o la memoria del sistema.
+    
+    Args:
+        image_bytes: Bytes de la imagen (formato JPEG, PNG, etc.)
+        
+    Returns:
+        numpy array float32 normalizado con el embedding (vector de características)
+        
+    Nota: La inferencia se ejecuta en un thread pool para no bloquear el event loop
+    de asyncio, permitiendo que el servidor siga procesando otras peticiones.
+    """
+    # Adquirir el semáforo (espera si ya hay 2 inferencias en curso)
+    async with _inference_semaphore:
+        # Ejecutar la generación del embedding en un thread separado
+        # Esto evita bloquear el event loop de asyncio mientras se procesa la imagen
+        return await asyncio.to_thread(_generate_embedding, image_bytes)
+
+def _generate_embedding(image_bytes: bytes) -> np.ndarray:
+    """
+    Genera el embedding de una imagen (función interna, no usar directamente).
+    
+    Esta función hace el trabajo real de generar el embedding:
+    1. Carga el modelo si no está cargado
+    2. Convierte los bytes de la imagen a un objeto PIL Image
+    3. Aplica las transformaciones de preprocesamiento
+    4. Pasa la imagen por el modelo MegaDescriptor
+    5. Normaliza el vector resultante (L2 normalization)
+    6. Convierte a numpy array y limpia la memoria
+    
+    Args:
+        image_bytes: Bytes de la imagen en cualquier formato (JPEG, PNG, etc.)
+        
+    Returns:
+        numpy array float32 normalizado con el embedding
+        
+    Nota: Esta función es síncrona. Para uso asíncrono, usar image_bytes_to_vec_async.
+    """
+    # Cargar el modelo (o obtener el ya cargado)
+    model, transforms, actual_dim = _load_model()
+    
+    # Convertir bytes a imagen PIL
+    # io.BytesIO crea un objeto file-like en memoria desde los bytes
+    # Image.open() lee la imagen desde ese objeto
+    # .convert("RGB") asegura que la imagen tenga 3 canales (rojo, verde, azul)
+    # incluso si originalmente era escala de grises o tenía transparencia
+    img = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    
+    # Aplicar transformaciones y generar embedding
+    # torch.inference_mode() es más eficiente que torch.no_grad() para inferencia
+    # Desactiva el cálculo de gradientes completamente (ahorra memoria y tiempo)
+    with torch.inference_mode():
+        # Aplicar transformaciones: resize, to tensor, normalize
+        # unsqueeze(0) agrega una dimensión de batch al inicio: [3, 384, 384] -> [1, 3, 384, 384]
+        # .to(DEVICE) mueve el tensor a GPU si está disponible
+        img_tensor = transforms(img).unsqueeze(0).to(DEVICE)
+        
+        # Pasar la imagen por el modelo para obtener el embedding
+        # El modelo procesa la imagen y extrae características visuales
+        feats = model(img_tensor)
+        
+        # Normalización L2: divide cada elemento por la norma del vector
+        # Esto hace que todos los embeddings tengan la misma "magnitud"
+        # Es importante para comparar embeddings usando producto punto o coseno
+        # feats.norm(dim=-1, keepdim=True) calcula la norma de cada vector en el batch
+        feats = feats / feats.norm(dim=-1, keepdim=True)
+        
+        # Convertir de tensor de PyTorch a numpy array
+        # squeeze(0) elimina la dimensión de batch: [1, 1536] -> [1536]
+        # detach() desvincula del grafo computacional
+        # cpu() mueve a CPU (necesario antes de convertir a numpy)
+        # numpy() convierte a numpy array
+        # astype("float32") asegura que sea float32 (más eficiente que float64)
+        vec = feats.squeeze(0).detach().cpu().numpy().astype("float32")
+    
+    # Limpiar memoria explícitamente para liberar RAM/VRAM
+    # Esto es importante cuando se procesan muchas imágenes
+    del img, img_tensor, feats
+    
+    # Si estamos usando GPU, limpiar la caché de CUDA
+    # Esto libera memoria de GPU que PyTorch puede haber reservado
+    if DEVICE == "cuda":
+        torch.cuda.empty_cache()
+    
+    print(f"🔍 Embedding generado: {vec.shape[-1]} dimensiones")
+    
+    return vec
+
+def image_bytes_to_vec(image_bytes: bytes) -> np.ndarray:
+    """
+    Genera embedding L2-normalizado usando MegaDescriptor (versión síncrona).
+    
+    Esta es la función principal para generar embeddings de forma síncrona.
+    Es un wrapper simple de _generate_embedding() para mantener compatibilidad
+    con código existente que no usa asyncio.
+    
+    Para nuevos código, preferir image_bytes_to_vec_async() que es más eficiente
+    en servidores asíncronos como FastAPI.
+    
+    Args:
+        image_bytes: Bytes de la imagen en cualquier formato (JPEG, PNG, etc.)
+        
+    Returns:
+        numpy array float32 normalizado con el embedding
+        La dimensión depende del modelo (MegaDescriptor-L-384 genera 1536 dimensiones)
+        
+    Ejemplo:
+        >>> with open("foto_perro.jpg", "rb") as f:
+        ...     image_bytes = f.read()
+        >>> embedding = image_bytes_to_vec(image_bytes)
+        >>> print(embedding.shape)  # (1536,)
+        >>> print(embedding.dtype)  # float32
+    """
+    # Versión síncrona simple para mantener compatibilidad con código existente
+    # Llama directamente a la función interna que hace el trabajo
+    return _generate_embedding(image_bytes)

utils/__init__.py

@@ -0,0 +1,9 @@
+"""Utilidades para el backend de PetFind"""
+from .supabase_client import create_supabase_client, get_supabase_client
+
+__all__ = ['create_supabase_client', 'get_supabase_client']
+
+
+
+
+

utils/supabase_client.py

@@ -0,0 +1,130 @@
+"""
+Utility para Crear Clientes de Supabase con Configuración Optimizada
+=====================================================================
+
+Este módulo proporciona funciones para crear clientes de Supabase con
+configuración optimizada de timeouts y manejo de conexiones.
+
+Problemas que resuelve:
+- WinError 10060 en Windows (timeout de conexión)
+- Conexiones lentas o con firewall
+- Timeouts prematuros en operaciones largas
+- Manejo de reintentos automáticos
+
+La configuración incluye:
+- Timeouts aumentados para conexiones lentas
+- Límites de conexiones concurrentes
+- Reintentos automáticos
+- Keep-alive para conexiones persistentes
+"""
+
+import os
+from supabase import create_client, Client, ClientOptions
+import httpx  # Cliente HTTP con mejor control de timeouts
+from typing import Optional
+
+def create_supabase_client(
+    url: Optional[str] = None,
+    key: Optional[str] = None,
+    timeout: float = 30.0,
+    max_retries: int = 3
+) -> Client:
+    """
+    Crea un cliente de Supabase con configuración optimizada de timeouts.
+    
+    Args:
+        url: URL de Supabase (por defecto: SUPABASE_URL del .env)
+        key: Service key (por defecto: SUPABASE_SERVICE_KEY del .env)
+        timeout: Timeout en segundos para las peticiones (default: 30s)
+        max_retries: Número máximo de reintentos (default: 3)
+    
+    Returns:
+        Cliente de Supabase configurado
+    
+    Raises:
+        ValueError: Si no se encuentran las credenciales
+    """
+    # Obtener credenciales del entorno si no se proporcionan
+    supabase_url = url or os.getenv("SUPABASE_URL")
+    supabase_key = key or os.getenv("SUPABASE_SERVICE_KEY")
+    
+    if not supabase_url or not supabase_key:
+        raise ValueError("SUPABASE_URL y SUPABASE_SERVICE_KEY son requeridos")
+    
+    # Configurar httpx con timeouts apropiados y retry logic
+    # Timeouts aumentados para conexiones lentas/firewalls de Windows
+    timeout_config = httpx.Timeout(
+        connect=60.0,      # Tiempo para establecer la conexión (aumentado para Windows)
+        read=timeout,      # Tiempo para leer la respuesta
+        write=timeout,     # Tiempo para escribir la petición
+        pool=10.0          # Tiempo para obtener una conexión del pool
+    )
+    
+    # Configurar límites de conexión
+    limits = httpx.Limits(
+        max_connections=100,
+        max_keepalive_connections=20,
+        keepalive_expiry=30.0
+    )
+    
+    # Crear transporte con retry logic
+    transport = httpx.HTTPTransport(
+        retries=max_retries,
+        limits=limits
+    )
+    
+    # Crear httpx client personalizado
+    http_client = httpx.Client(
+        timeout=timeout_config,
+        transport=transport,
+        follow_redirects=True
+    )
+    
+    # Crear cliente de Supabase con httpx client personalizado
+    try:
+        # Crear opciones del cliente correctamente
+        options = ClientOptions(
+            schema="public",
+            headers={},
+            auto_refresh_token=True,
+            persist_session=False
+        )
+        
+        client = create_client(
+            supabase_url,
+            supabase_key,
+            options=options
+        )
+        
+        # Reemplazar el cliente HTTP interno con nuestra configuración
+        # El cliente de supabase-py usa httpx internamente
+        if hasattr(client, '_postgrest_client'):
+            if hasattr(client._postgrest_client, 'session'):
+                # Actualizar la sesión con nuestro cliente configurado
+                client._postgrest_client.session = http_client
+        
+        # También actualizar el cliente de storage si existe
+        if hasattr(client, '_storage_client'):
+            if hasattr(client._storage_client, 'session'):
+                client._storage_client.session = http_client
+        
+        return client
+        
+    except Exception as e:
+        http_client.close()
+        raise RuntimeError(f"Error creando cliente de Supabase: {str(e)}") from e
+
+
+def get_supabase_client() -> Client:
+    """
+    Obtiene un cliente de Supabase con configuración por defecto.
+    Útil para uso rápido sin configuración personalizada.
+    
+    Returns:
+        Cliente de Supabase configurado
+        
+    Raises:
+        ValueError: Si no se encuentran las credenciales
+    """
+    return create_supabase_client()
+