Add TF-IDF ranking and Llama recommendations

README.md

@@ -7,7 +7,7 @@ pinned: false
 
 # Frimeet API NLP
 
-Servicio NLP independiente para busqueda semantica, recomendaciones, ranking, embeddings y redaccion conversacional con Llama via Groq.
+Servicio NLP independiente para recuperacion de candidatos con pgvector, ranking TF-IDF, recomendaciones, embeddings y redaccion conversacional con Llama via Groq.
 
 La API principal sigue siendo la fuente de verdad de lugares, posts, usuarios, sesiones, permisos y reportes. Este servicio NLP solo trabaja con datos derivados para busqueda semantica.
 
@@ -22,7 +22,8 @@ Hugging Face API NLP
   |-- usa credenciales nlp_reader
   |-- consulta RDS PostgreSQL + pgvector
   |-- genera embedding solo del query del usuario
-  `-- usa Groq/Llama solo para embellecer chat
+  |-- ordena candidatos con TF-IDF y similitud coseno
+  `-- usa Groq/Llama para embellecer recomendaciones y chat
 
 Hugging Face Jobs
   |-- usan credenciales nlp_writer
@@ -180,9 +181,11 @@ docs/pgvector_post_embeddings_schema.md
 
 Ese SQL debe ejecutarse una vez con un rol administrador/DBA fuera de Hugging Face. La API NLP usa solo `nlp_reader`; los jobs usan solo `nlp_writer`.
 
-## Llama Via Groq
+## Ranking TF-IDF Y Llama Via Groq
 
-Groq/Llama solo se usa en `/places/chat` para redactar una respuesta conversacional. No decide que lugares recomendar, no hace busqueda y no inventa lugares.
+`/places/search` y `/places/recommendations` recuperan candidatos filtrados desde pgvector y aplican el flujo TF-IDF de `Lab2_Motor_de_busqueda.ipynb`: TF, IDF, vectorizacion de consulta y similitud coseno. Las etiquetas se ponderan `x6` y la categoria `x2` antes de construir los vectores.
+
+Groq/Llama se usa en `/places/recommendations` y `/places/chat` para redactar una respuesta conversacional. No decide que lugares recomendar, no hace busqueda y no inventa lugares.
 
 El arreglo estructurado `places` viene desde RDS/pgvector mediante embeddings, filtros y ranking. La app debe renderizar cards desde ese arreglo, no parseando texto libre del LLM.
 

app/main.py

@@ -1,4 +1,5 @@
 from fastapi import FastAPI
+from fastapi.responses import JSONResponse
 
 from app.modules.places.api.router import router as places_router
 from app.modules.posts.api.router import router as posts_router
@@ -7,6 +8,7 @@ from app.shared.errors.exceptions import AppError
 from app.shared.errors.handlers import app_error_handler
 from app.shared.logging.config import configure_logging
 from app.shared.security.request_limits import RequestSizeLimitMiddleware
+from app.shared.vector_store.aws_pgvector import AwsPgvectorClient
 
 
 def create_app() -> FastAPI:
@@ -38,25 +40,43 @@ def create_app() -> FastAPI:
     async def health() -> dict[str, str]:
         return {"status": "ok"}
 
-    @app.get("/ready", tags=["system"])
-    async def ready() -> dict[str, object]:
-        return {
-            "status": "ready",
+    @app.get("/ready", tags=["system"], response_model=None)
+    async def ready() -> dict[str, object] | JSONResponse:
+        vector_store = {
+            "provider": settings.vector_store_provider,
+            "host": settings.pgvector_host,
+            "port": settings.pgvector_port,
+            "database": settings.pgvector_database,
+            "ssl_mode": settings.pgvector_ssl_mode,
+        }
+        is_ready = True
+
+        if settings.vector_store_provider == "aws_pgvector":
+            try:
+                contract = await AwsPgvectorClient(settings, role="reader").check_read_contract()
+            except Exception as exc:
+                contract = {
+                    "ready": False,
+                    "error": type(exc).__name__,
+                    "message": str(exc),
+                }
+            vector_store["contract"] = contract
+            is_ready = bool(contract.get("ready"))
+
+        payload = {
+            "status": "ready" if is_ready else "not_ready",
             "environment": settings.env,
             "dependencies": {
-                "vector_store": {
-                    "provider": settings.vector_store_provider,
-                    "host": settings.pgvector_host,
-                    "port": settings.pgvector_port,
-                    "database": settings.pgvector_database,
-                    "ssl_mode": settings.pgvector_ssl_mode,
-                },
+                "vector_store": vector_store,
                 "llm": {
                     "provider": "groq" if settings.groq_api_key else "mock",
                     "model": settings.groq_model,
                 },
             },
         }
+        if not is_ready:
+            return JSONResponse(status_code=503, content=payload)
+        return payload
 
     app.include_router(places_router)
     app.include_router(posts_router)

app/modules/places/api/dependencies.py

@@ -7,7 +7,7 @@ from app.modules.places.infrastructure.aws_pgvector_place_repository import (
     AwsPgvectorPlaceRepository,
 )
 from app.modules.places.infrastructure.mock_place_repository import MockPlaceVectorRepository
-from app.modules.places.infrastructure.simple_place_ranker import SimplePlaceRanker
+from app.modules.places.infrastructure.tfidf_place_ranker import TfidfPlaceRanker
 from app.shared.cache.memory import SimpleTTLCache
 from app.shared.config.settings import get_settings
 from app.shared.dependencies import get_embedding_provider, get_llm_provider
@@ -24,8 +24,8 @@ def get_place_repository() -> MockPlaceVectorRepository | AwsPgvectorPlaceReposi
 
 
 @lru_cache
-def get_place_ranker() -> SimplePlaceRanker:
-    return SimplePlaceRanker()
+def get_place_ranker() -> TfidfPlaceRanker:
+    return TfidfPlaceRanker()
 
 
 @lru_cache
@@ -46,7 +46,11 @@ def get_search_places_use_case() -> SearchPlacesUseCase:
 
 @lru_cache
 def get_recommend_places_use_case() -> RecommendPlacesUseCase:
-    return RecommendPlacesUseCase(search_use_case=get_search_places_use_case())
+    return RecommendPlacesUseCase(
+        search_use_case=get_search_places_use_case(),
+        llm_provider=get_llm_provider(),
+        output_guard=PlaceChatOutputGuard(),
+    )
 
 
 @lru_cache

app/modules/places/api/router.py

@@ -54,6 +54,7 @@ async def recommend_places(
     )
     return PlaceRecommendationResponse(
         query=result.query,
+        message=result.message,
         places=[place_to_schema(place) for place in result.places],
         metadata=result.metadata,
     )

app/modules/places/api/schemas.py

@@ -77,6 +77,7 @@ class PlaceSearchResponse(BaseModel):
 
 class PlaceRecommendationResponse(BaseModel):
     query: str
+    message: str
     places: list[PlaceResultSchema]
     metadata: dict[str, Any] = Field(default_factory=dict)
 

app/modules/places/application/ports/ranker.py

@@ -6,8 +6,9 @@ from app.modules.places.domain.models import PlaceCandidate, PlaceFilters
 class PlaceRanker(Protocol):
     def rank(
         self,
+        query: str,
         places: Sequence[PlaceCandidate],
         filters: PlaceFilters,
         limit: int,
     ) -> list[PlaceCandidate]:
-        """Rank candidates returned by the vector store."""
+        """Rank place candidates for a normalized user query."""

app/modules/places/application/use_cases/recommend_places.py

@@ -1,20 +1,31 @@
 from dataclasses import dataclass, field
+from datetime import UTC, datetime
 from typing import Any
 
 from app.modules.places.application.use_cases.search_places import SearchPlacesUseCase
 from app.modules.places.domain.models import PlaceCandidate, PlaceFilters
+from app.shared.nlp.llm.base import LLMProvider
+from app.shared.nlp.llm.output_guard import PlaceChatOutputGuard
 
 
 @dataclass(frozen=True)
 class RecommendPlacesResult:
     query: str
+    message: str
     places: list[PlaceCandidate]
     metadata: dict[str, Any] = field(default_factory=dict)
 
 
 class RecommendPlacesUseCase:
-    def __init__(self, search_use_case: SearchPlacesUseCase) -> None:
+    def __init__(
+        self,
+        search_use_case: SearchPlacesUseCase,
+        llm_provider: LLMProvider,
+        output_guard: PlaceChatOutputGuard,
+    ) -> None:
         self._search_use_case = search_use_case
+        self._llm_provider = llm_provider
+        self._output_guard = output_guard
 
     async def execute(
         self,
@@ -27,11 +38,44 @@ class RecommendPlacesUseCase:
             filters=filters,
             limit=limit,
         )
+        places = search_result.places
+        llm_provider = self._llm_provider.provider_name
+        llm_model = self._llm_provider.model_name
+        used_llm = False
+        guard_reason = None
+
+        try:
+            llm_result = await self._llm_provider.generate_place_chat_response(
+                user_intent=search_result.normalized_query,
+                region=filters.city or filters.state,
+                places=[place.to_llm_context() for place in places],
+            )
+            llm_provider = llm_result.provider
+            llm_model = llm_result.model
+            guarded = self._output_guard.validate(
+                message=llm_result.message,
+                allowed_place_names=[place.name for place in places],
+            )
+            message = guarded.message
+            used_llm = not guarded.used_fallback
+            guard_reason = guarded.reason
+        except Exception as exc:
+            guarded = self._output_guard.fallback(reason=exc.__class__.__name__)
+            message = guarded.message
+            guard_reason = guarded.reason
+
         return RecommendPlacesResult(
             query=search_result.query,
-            places=search_result.places,
+            message=message,
+            places=places,
             metadata={
-                "strategy": "semantic_search_plus_ranking",
-                "used_llm": False,
+                "strategy": "pgvector_candidates_plus_tfidf_ranking",
+                "ranking": "tfidf_cosine",
+                "llm_provider": llm_provider,
+                "llm_model": llm_model,
+                "used_llm": used_llm,
+                "guard_reason": guard_reason,
+                "places_used_as_context": [place.id for place in places],
+                "timestamp": datetime.now(UTC).isoformat(),
             },
         )

app/modules/places/application/use_cases/search_places.py

@@ -49,7 +49,12 @@ class SearchPlacesUseCase:
             filters=filters,
             limit=max(limit * 3, limit),
         )
-        ranked_places = self._ranker.rank(candidates, filters, limit)
+        ranked_places = self._ranker.rank(
+            query=normalized_query,
+            places=candidates,
+            filters=filters,
+            limit=limit,
+        )
         result = SearchPlacesResult(
             query=query,
             normalized_query=normalized_query,

app/modules/places/domain/models.py

@@ -36,6 +36,7 @@ class PlaceCandidate:
     state: str | None = None
     price_range: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
+    document: str | None = None
 
     def to_llm_context(self) -> dict[str, Any]:
         context = {

app/modules/places/infrastructure/aws_pgvector_place_repository.py

@@ -27,7 +27,7 @@ class AwsPgvectorPlaceRepository(PlaceVectorRepository):
 
 
 def _match_to_candidate(match: VectorMatch) -> PlaceCandidate:
-    metadata = match.metadata
+    metadata = dict(match.metadata)
     return PlaceCandidate(
         id=match.id,
         name=str(metadata.get("name") or match.id),
@@ -37,4 +37,5 @@ def _match_to_candidate(match: VectorMatch) -> PlaceCandidate:
         state=metadata.get("state"),
         price_range=metadata.get("price_range"),
         metadata=metadata,
+        document=match.document,
     )

app/modules/places/infrastructure/mock_place_repository.py

@@ -78,6 +78,7 @@ class MockPlaceVectorRepository(PlaceVectorRepository):
             self._records.append(
                 {
                     "place": place,
+                    "document": searchable_text,
                     "embedding": embedding_provider.embed_text(
                         prepare_for_embedding(searchable_text)
                     ),
@@ -111,6 +112,7 @@ class MockPlaceVectorRepository(PlaceVectorRepository):
                         "tags": place["tags"],
                         "short_description": place["short_description"],
                     },
+                    document=record["document"],
                 )
             )
         return sorted(candidates, key=lambda item: item.score, reverse=True)[:limit]

app/modules/places/infrastructure/simple_place_ranker.py

@@ -7,10 +7,12 @@ from app.modules.places.domain.models import PlaceCandidate, PlaceFilters
 class SimplePlaceRanker(PlaceRanker):
     def rank(
         self,
+        query: str,
         places: Sequence[PlaceCandidate],
         filters: PlaceFilters,
         limit: int,
     ) -> list[PlaceCandidate]:
+        del query
         ranked = sorted(
             places,
             key=lambda place: (

app/modules/places/infrastructure/tfidf_place_ranker.py

@@ -0,0 +1,119 @@
+from collections import Counter
+from dataclasses import replace
+import math
+import re
+from typing import Any, Sequence
+
+from app.modules.places.application.ports.ranker import PlaceRanker
+from app.modules.places.domain.models import PlaceCandidate, PlaceFilters
+from app.shared.nlp.preprocessing.text import prepare_for_embedding
+
+
+TAG_WEIGHT = 6
+CATEGORY_WEIGHT = 2
+TOKEN_PATTERN = re.compile(r"[a-z0-9]+")
+
+
+class TfidfPlaceRanker(PlaceRanker):
+    """Rerank retrieved candidates with the TF-IDF flow from Lab 2."""
+
+    def rank(
+        self,
+        query: str,
+        places: Sequence[PlaceCandidate],
+        filters: PlaceFilters,
+        limit: int,
+    ) -> list[PlaceCandidate]:
+        del filters
+        candidates = list(places)
+        if not candidates:
+            return []
+
+        corpus = [_place_tokens(place) for place in candidates]
+        idf_index = idf(corpus)
+        query_vector = tfidf(_tokenize(query), idf_index)
+
+        scored = [
+            (cosine_similarity(query_vector, tfidf(document, idf_index)), place)
+            for place, document in zip(candidates, corpus)
+        ]
+        scored.sort(key=lambda item: (item[0], item[1].score), reverse=True)
+
+        return [
+            replace(place, score=score)
+            for score, place in scored[:limit]
+        ]
+
+
+def tf(document: Sequence[str]) -> dict[str, float]:
+    total = len(document)
+    if total == 0:
+        return {}
+    counts = Counter(document)
+    return {term: count / total for term, count in counts.items()}
+
+
+def idf(corpus: Sequence[Sequence[str]]) -> dict[str, float]:
+    document_count = len(corpus)
+    if document_count == 0:
+        return {}
+
+    document_frequency: Counter[str] = Counter()
+    for document in corpus:
+        document_frequency.update(set(document))
+    return {
+        term: math.log(document_count / frequency)
+        for term, frequency in document_frequency.items()
+    }
+
+
+def tfidf(document: Sequence[str], idf_index: dict[str, float]) -> dict[str, float]:
+    return {
+        term: frequency * idf_index.get(term, 0.0)
+        for term, frequency in tf(document).items()
+    }
+
+
+def cosine_similarity(left: dict[str, float], right: dict[str, float]) -> float:
+    dot_product = sum(weight * right.get(term, 0.0) for term, weight in left.items())
+    left_norm = math.sqrt(sum(weight**2 for weight in left.values()))
+    right_norm = math.sqrt(sum(weight**2 for weight in right.values()))
+    if left_norm == 0 or right_norm == 0:
+        return 0.0
+    return dot_product / (left_norm * right_norm)
+
+
+def _place_tokens(place: PlaceCandidate) -> list[str]:
+    tags = _as_text(place.metadata.get("tags"))
+    category = place.category or ""
+    base_document = place.document or " ".join(
+        value
+        for value in [
+            place.name,
+            category,
+            place.city or "",
+            place.state or "",
+            tags,
+            _as_text(place.metadata.get("occasion")),
+            _as_text(place.metadata.get("short_description")),
+        ]
+        if value
+    )
+
+    weighted_fields = [base_document]
+    weighted_fields.extend([category] * (CATEGORY_WEIGHT - 1))
+    weighted_fields.extend([tags] * (TAG_WEIGHT - 1))
+    return _tokenize(" ".join(value for value in weighted_fields if value))
+
+
+def _tokenize(text: str) -> list[str]:
+    normalized = prepare_for_embedding(text)
+    return TOKEN_PATTERN.findall(normalized)
+
+
+def _as_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (list, tuple, set)):
+        return " ".join(str(item) for item in value)
+    return str(value)

app/shared/vector_store/aws_pgvector.py

@@ -7,10 +7,17 @@ from typing import Any, AsyncIterator
 import asyncpg
 
 from app.shared.config.settings import Settings
+from app.shared.errors.exceptions import AppError
 from app.shared.vector_store.models import VectorMatch, VectorUpsertRecord
 from app.shared.vector_store.sql import quote_identifier, vector_literal
 
 
+READ_CONTRACT_SIGNATURES = {
+    "match_places": "match_places(vector, integer, jsonb)",
+    "match_posts": "match_posts(vector, integer, jsonb)",
+}
+
+
 class AwsPgvectorClient:
     """PostgreSQL + pgvector access for RDS/Aurora using controlled SQL functions."""
 
@@ -54,6 +61,58 @@ class AwsPgvectorClient:
             limit=limit,
         )
 
+    async def check_read_contract(self) -> dict[str, Any]:
+        """Check that read-only pgvector functions are visible and executable."""
+        try:
+            async with self.connection() as connection:
+                vector_row = await connection.fetchrow(
+                    "SELECT to_regtype('vector') IS NOT NULL AS available"
+                )
+                vector_available = bool(vector_row["available"]) if vector_row else False
+                functions: dict[str, dict[str, Any]] = {
+                    function_name: {
+                        "signature": signature,
+                        "exists": False,
+                        "executable": False,
+                    }
+                    for function_name, signature in READ_CONTRACT_SIGNATURES.items()
+                }
+                if vector_available:
+                    for function_name, signature in READ_CONTRACT_SIGNATURES.items():
+                        row = await connection.fetchrow(
+                            """
+                            SELECT
+                                to_regprocedure($1) IS NOT NULL AS exists,
+                                COALESCE(
+                                    has_function_privilege(to_regprocedure($1), 'EXECUTE'),
+                                    false
+                                ) AS executable
+                            """,
+                            signature,
+                        )
+                        functions[function_name].update(
+                            {
+                                "exists": bool(row["exists"]) if row else False,
+                                "executable": bool(row["executable"]) if row else False,
+                            }
+                        )
+        except Exception as exc:
+            return {
+                "ready": False,
+                "error": type(exc).__name__,
+                "message": str(exc),
+            }
+
+        ready = vector_available and all(
+            details["exists"] and details["executable"]
+            for details in functions.values()
+        )
+        return {
+            "ready": ready,
+            "vector_extension": vector_available,
+            "functions": functions,
+        }
+
     async def fetch_place_content_hashes(self, ids: Iterable[str]) -> dict[str, str]:
         return await self._fetch_content_hashes(
             function_name="get_place_content_hashes",
@@ -92,13 +151,22 @@ class AwsPgvectorClient:
         limit: int,
     ) -> list[VectorMatch]:
         query = f"SELECT * FROM {quote_identifier(function_name)}($1::vector, $2::integer, $3::jsonb)"
-        async with self.connection() as connection:
-            rows = await connection.fetch(
-                query,
-                vector_literal(embedding),
-                limit,
-                json.dumps(filters, ensure_ascii=False),
-            )
+        try:
+            async with self.connection() as connection:
+                rows = await connection.fetch(
+                    query,
+                    vector_literal(embedding),
+                    limit,
+                    json.dumps(filters, ensure_ascii=False),
+                )
+        except asyncpg.exceptions.UndefinedFunctionError as exc:
+            raise AppError(
+                "Pgvector SQL contract is missing or not visible to this role. "
+                "Run sql/aws_pgvector_contract.sql in the configured database and "
+                "grant EXECUTE to the reader role.",
+                code="pgvector_contract_missing",
+                status_code=503,
+            ) from exc
         return [_row_to_vector_match(row) for row in rows]
 
     async def _fetch_content_hashes(

sql/aws_pgvector_contract.sql

@@ -53,20 +53,21 @@ RETURNS TABLE (
 LANGUAGE sql
 STABLE
 SECURITY DEFINER
+SET search_path = public
 AS $$
     SELECT
         p.external_id,
         p.document,
         p.metadata,
         1 - (p.embedding <=> query_embedding) AS score
-    FROM place_embeddings p
+    FROM public.place_embeddings p
     WHERE p.is_active = true
       AND COALESCE((filters->>'is_active')::boolean, true) = true
       AND ((filters ? 'city') IS FALSE OR lower(p.metadata->>'city') = lower(filters->>'city'))
       AND ((filters ? 'state') IS FALSE OR lower(p.metadata->>'state') = lower(filters->>'state'))
       AND ((filters ? 'category') IS FALSE OR lower(p.metadata->>'category') = lower(filters->>'category'))
       AND ((filters ? 'price_range') IS FALSE OR p.metadata->>'price_range' = filters->>'price_range')
-      AND ((filters ? 'occasion') IS FALSE OR p.metadata->>'occasion' ILIKE '%' || filters->>'occasion' || '%')
+      AND ((filters ? 'occasion') IS FALSE OR p.metadata->>'occasion' ILIKE ('%' || (filters->>'occasion') || '%'))
     ORDER BY p.embedding <=> query_embedding
     LIMIT match_count;
 $$;
@@ -85,13 +86,14 @@ RETURNS TABLE (
 LANGUAGE sql
 STABLE
 SECURITY DEFINER
+SET search_path = public
 AS $$
     SELECT
         p.external_id,
         p.document,
         p.metadata,
         1 - (p.embedding <=> query_embedding) AS score
-    FROM post_embeddings p
+    FROM public.post_embeddings p
     WHERE p.is_active = true
       AND COALESCE((filters->>'is_active')::boolean, true) = true
       AND ((filters ? 'city') IS FALSE OR lower(p.metadata->>'city') = lower(filters->>'city'))
@@ -112,8 +114,9 @@ CREATE OR REPLACE FUNCTION upsert_place_embedding(
 RETURNS VOID
 LANGUAGE sql
 SECURITY DEFINER
+SET search_path = public
 AS $$
-    INSERT INTO place_embeddings (
+    INSERT INTO public.place_embeddings (
         external_id,
         document,
         metadata,
@@ -159,8 +162,9 @@ CREATE OR REPLACE FUNCTION upsert_post_embedding(
 RETURNS VOID
 LANGUAGE sql
 SECURITY DEFINER
+SET search_path = public
 AS $$
-    INSERT INTO post_embeddings (
+    INSERT INTO public.post_embeddings (
         external_id,
         document,
         metadata,
@@ -201,9 +205,10 @@ RETURNS TABLE (
 LANGUAGE sql
 STABLE
 SECURITY DEFINER
+SET search_path = public
 AS $$
     SELECT p.external_id, p.content_hash
-    FROM place_embeddings p
+    FROM public.place_embeddings p
     WHERE p.external_id = ANY(p_external_ids);
 $$;
 
@@ -215,9 +220,10 @@ RETURNS TABLE (
 LANGUAGE sql
 STABLE
 SECURITY DEFINER
+SET search_path = public
 AS $$
     SELECT p.external_id, p.content_hash
-    FROM post_embeddings p
+    FROM public.post_embeddings p
     WHERE p.external_id = ANY(p_external_ids);
 $$;
 

sql/aws_pgvector_full_setup.psql.sql

@@ -0,0 +1,294 @@
+-- Full setup for Frimeet API NLP pgvector storage.
+-- Run with psql using an admin/RDS master role:
+-- psql "host=<host> port=5432 dbname=postgres user=<admin> sslmode=require" -f sql/aws_pgvector_full_setup.psql.sql
+--
+-- Replace the passwords before running.
+-- VECTOR(16) must match EMBEDDING_DIMENSION=16 in the API environment.
+
+\set ON_ERROR_STOP on
+
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'nlp_owner') THEN
+        CREATE ROLE nlp_owner LOGIN PASSWORD 'CAMBIA_OWNER_PASSWORD';
+    END IF;
+
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'nlp_reader') THEN
+        CREATE ROLE nlp_reader LOGIN PASSWORD 'CAMBIA_READER_PASSWORD';
+    END IF;
+
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'nlp_writer') THEN
+        CREATE ROLE nlp_writer LOGIN PASSWORD 'CAMBIA_WRITER_PASSWORD';
+    END IF;
+END $$;
+
+SELECT 'CREATE DATABASE nlp_vectors OWNER nlp_owner'
+WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname = 'nlp_vectors')
+\gexec
+
+GRANT CONNECT ON DATABASE nlp_vectors TO nlp_reader, nlp_writer;
+ALTER ROLE nlp_reader SET search_path = public;
+ALTER ROLE nlp_writer SET search_path = public;
+
+\connect nlp_vectors
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+REVOKE CREATE ON SCHEMA public FROM PUBLIC;
+GRANT USAGE ON SCHEMA public TO nlp_owner, nlp_reader, nlp_writer;
+
+CREATE TABLE IF NOT EXISTS public.place_embeddings (
+    external_id TEXT PRIMARY KEY,
+    document TEXT NOT NULL,
+    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+    embedding VECTOR(16) NOT NULL,
+    content_hash TEXT NOT NULL,
+    embedding_model TEXT NOT NULL,
+    embedding_version TEXT NOT NULL,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.post_embeddings (
+    external_id TEXT PRIMARY KEY,
+    document TEXT NOT NULL,
+    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+    embedding VECTOR(16) NOT NULL,
+    content_hash TEXT NOT NULL,
+    embedding_model TEXT NOT NULL,
+    embedding_version TEXT NOT NULL,
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS place_embeddings_embedding_hnsw_idx
+ON public.place_embeddings USING hnsw (embedding vector_cosine_ops);
+
+CREATE INDEX IF NOT EXISTS post_embeddings_embedding_hnsw_idx
+ON public.post_embeddings USING hnsw (embedding vector_cosine_ops);
+
+CREATE INDEX IF NOT EXISTS place_embeddings_metadata_gin_idx
+ON public.place_embeddings USING gin (metadata);
+
+CREATE INDEX IF NOT EXISTS post_embeddings_metadata_gin_idx
+ON public.post_embeddings USING gin (metadata);
+
+CREATE OR REPLACE FUNCTION public.match_places(
+    query_embedding VECTOR(16),
+    match_count INTEGER,
+    filters JSONB DEFAULT '{}'::jsonb
+)
+RETURNS TABLE (
+    external_id TEXT,
+    document TEXT,
+    metadata JSONB,
+    score DOUBLE PRECISION
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+    SELECT
+        p.external_id,
+        p.document,
+        p.metadata,
+        1 - (p.embedding <=> query_embedding) AS score
+    FROM public.place_embeddings p
+    WHERE p.is_active = true
+      AND COALESCE((filters->>'is_active')::boolean, true) = true
+      AND ((filters ? 'city') IS FALSE OR lower(p.metadata->>'city') = lower(filters->>'city'))
+      AND ((filters ? 'state') IS FALSE OR lower(p.metadata->>'state') = lower(filters->>'state'))
+      AND ((filters ? 'category') IS FALSE OR lower(p.metadata->>'category') = lower(filters->>'category'))
+      AND ((filters ? 'price_range') IS FALSE OR p.metadata->>'price_range' = filters->>'price_range')
+      AND ((filters ? 'occasion') IS FALSE OR p.metadata->>'occasion' ILIKE ('%' || (filters->>'occasion') || '%'))
+    ORDER BY p.embedding <=> query_embedding
+    LIMIT match_count;
+$$;
+
+CREATE OR REPLACE FUNCTION public.match_posts(
+    query_embedding VECTOR(16),
+    match_count INTEGER,
+    filters JSONB DEFAULT '{}'::jsonb
+)
+RETURNS TABLE (
+    external_id TEXT,
+    document TEXT,
+    metadata JSONB,
+    score DOUBLE PRECISION
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+    SELECT
+        p.external_id,
+        p.document,
+        p.metadata,
+        1 - (p.embedding <=> query_embedding) AS score
+    FROM public.post_embeddings p
+    WHERE p.is_active = true
+      AND COALESCE((filters->>'is_active')::boolean, true) = true
+      AND ((filters ? 'city') IS FALSE OR lower(p.metadata->>'city') = lower(filters->>'city'))
+    ORDER BY p.embedding <=> query_embedding
+    LIMIT match_count;
+$$;
+
+CREATE OR REPLACE FUNCTION public.upsert_place_embedding(
+    p_external_id TEXT,
+    p_document TEXT,
+    p_metadata JSONB,
+    p_embedding VECTOR(16),
+    p_content_hash TEXT,
+    p_embedding_model TEXT,
+    p_embedding_version TEXT,
+    p_is_active BOOLEAN
+)
+RETURNS VOID
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+    INSERT INTO public.place_embeddings (
+        external_id,
+        document,
+        metadata,
+        embedding,
+        content_hash,
+        embedding_model,
+        embedding_version,
+        is_active,
+        updated_at
+    )
+    VALUES (
+        p_external_id,
+        p_document,
+        p_metadata,
+        p_embedding,
+        p_content_hash,
+        p_embedding_model,
+        p_embedding_version,
+        p_is_active,
+        now()
+    )
+    ON CONFLICT (external_id) DO UPDATE SET
+        document = EXCLUDED.document,
+        metadata = EXCLUDED.metadata,
+        embedding = EXCLUDED.embedding,
+        content_hash = EXCLUDED.content_hash,
+        embedding_model = EXCLUDED.embedding_model,
+        embedding_version = EXCLUDED.embedding_version,
+        is_active = EXCLUDED.is_active,
+        updated_at = now();
+$$;
+
+CREATE OR REPLACE FUNCTION public.upsert_post_embedding(
+    p_external_id TEXT,
+    p_document TEXT,
+    p_metadata JSONB,
+    p_embedding VECTOR(16),
+    p_content_hash TEXT,
+    p_embedding_model TEXT,
+    p_embedding_version TEXT,
+    p_is_active BOOLEAN
+)
+RETURNS VOID
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+    INSERT INTO public.post_embeddings (
+        external_id,
+        document,
+        metadata,
+        embedding,
+        content_hash,
+        embedding_model,
+        embedding_version,
+        is_active,
+        updated_at
+    )
+    VALUES (
+        p_external_id,
+        p_document,
+        p_metadata,
+        p_embedding,
+        p_content_hash,
+        p_embedding_model,
+        p_embedding_version,
+        p_is_active,
+        now()
+    )
+    ON CONFLICT (external_id) DO UPDATE SET
+        document = EXCLUDED.document,
+        metadata = EXCLUDED.metadata,
+        embedding = EXCLUDED.embedding,
+        content_hash = EXCLUDED.content_hash,
+        embedding_model = EXCLUDED.embedding_model,
+        embedding_version = EXCLUDED.embedding_version,
+        is_active = EXCLUDED.is_active,
+        updated_at = now();
+$$;
+
+CREATE OR REPLACE FUNCTION public.get_place_content_hashes(p_external_ids TEXT[])
+RETURNS TABLE (
+    external_id TEXT,
+    content_hash TEXT
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+    SELECT p.external_id, p.content_hash
+    FROM public.place_embeddings p
+    WHERE p.external_id = ANY(p_external_ids);
+$$;
+
+CREATE OR REPLACE FUNCTION public.get_post_content_hashes(p_external_ids TEXT[])
+RETURNS TABLE (
+    external_id TEXT,
+    content_hash TEXT
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+    SELECT p.external_id, p.content_hash
+    FROM public.post_embeddings p
+    WHERE p.external_id = ANY(p_external_ids);
+$$;
+
+ALTER TABLE public.place_embeddings OWNER TO nlp_owner;
+ALTER TABLE public.post_embeddings OWNER TO nlp_owner;
+
+ALTER FUNCTION public.match_places(vector, integer, jsonb) OWNER TO nlp_owner;
+ALTER FUNCTION public.match_posts(vector, integer, jsonb) OWNER TO nlp_owner;
+ALTER FUNCTION public.upsert_place_embedding(text, text, jsonb, vector, text, text, text, boolean) OWNER TO nlp_owner;
+ALTER FUNCTION public.upsert_post_embedding(text, text, jsonb, vector, text, text, text, boolean) OWNER TO nlp_owner;
+ALTER FUNCTION public.get_place_content_hashes(text[]) OWNER TO nlp_owner;
+ALTER FUNCTION public.get_post_content_hashes(text[]) OWNER TO nlp_owner;
+
+REVOKE ALL ON public.place_embeddings FROM PUBLIC;
+REVOKE ALL ON public.post_embeddings FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.match_places(vector, integer, jsonb) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.match_posts(vector, integer, jsonb) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.upsert_place_embedding(text, text, jsonb, vector, text, text, text, boolean) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.upsert_post_embedding(text, text, jsonb, vector, text, text, text, boolean) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.get_place_content_hashes(text[]) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.get_post_content_hashes(text[]) FROM PUBLIC;
+
+GRANT EXECUTE ON FUNCTION public.match_places(vector, integer, jsonb) TO nlp_reader;
+GRANT EXECUTE ON FUNCTION public.match_posts(vector, integer, jsonb) TO nlp_reader;
+
+GRANT EXECUTE ON FUNCTION public.upsert_place_embedding(text, text, jsonb, vector, text, text, text, boolean) TO nlp_writer;
+GRANT EXECUTE ON FUNCTION public.upsert_post_embedding(text, text, jsonb, vector, text, text, text, boolean) TO nlp_writer;
+GRANT EXECUTE ON FUNCTION public.get_place_content_hashes(text[]) TO nlp_writer;
+GRANT EXECUTE ON FUNCTION public.get_post_content_hashes(text[]) TO nlp_writer;
+
+SELECT to_regprocedure('public.match_places(vector, integer, jsonb)') AS match_places_signature;
+SELECT to_regprocedure('public.match_posts(vector, integer, jsonb)') AS match_posts_signature;
+SELECT has_function_privilege('nlp_reader', 'public.match_places(vector, integer, jsonb)', 'EXECUTE') AS reader_can_match_places;
+SELECT has_function_privilege('nlp_reader', 'public.match_posts(vector, integer, jsonb)', 'EXECUTE') AS reader_can_match_posts;

tests/conftest.py

@@ -1,3 +1,4 @@
 import os
 
 os.environ["VECTOR_STORE_PROVIDER"] = "mock"
+os.environ["GROQ_API_KEY"] = ""

tests/test_api_endpoints.py

@@ -44,6 +44,27 @@ def test_places_chat_endpoint_returns_trace_and_structured_places() -> None:
     assert payload["metadata"]["places_used_as_context"]
 
 
+def test_places_recommendations_returns_llm_message_and_tfidf_metadata() -> None:
+    client = TestClient(create_app())
+
+    response = client.post(
+        "/places/recommendations",
+        json={
+            "query": "quiero ver el atardecer y tomar fotos",
+            "city": "Tuxtla Gutierrez",
+            "filters": {"is_active": True},
+            "limit": 3,
+        },
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["message"]
+    assert payload["places"]
+    assert payload["metadata"]["ranking"] == "tfidf_cosine"
+    assert payload["metadata"]["used_llm"] is True
+
+
 def test_posts_recommendations_endpoint() -> None:
     client = TestClient(create_app())
 

tests/test_places_use_cases.py

@@ -3,10 +3,11 @@ from typing import Any, Sequence
 import pytest
 
 from app.modules.places.application.use_cases.chat_places import ChatPlacesUseCase
+from app.modules.places.application.use_cases.recommend_places import RecommendPlacesUseCase
 from app.modules.places.application.use_cases.search_places import SearchPlacesUseCase
 from app.modules.places.domain.models import PlaceFilters
 from app.modules.places.infrastructure.mock_place_repository import MockPlaceVectorRepository
-from app.modules.places.infrastructure.simple_place_ranker import SimplePlaceRanker
+from app.modules.places.infrastructure.tfidf_place_ranker import TfidfPlaceRanker
 from app.shared.nlp.embeddings.mock import MockEmbeddingProvider
 from app.shared.nlp.llm.base import LLMProvider, LLMResult
 from app.shared.nlp.llm.mock import MockLLMProvider
@@ -19,7 +20,7 @@ async def test_search_places_use_case_with_mock_providers() -> None:
     use_case = SearchPlacesUseCase(
         embedding_provider=embedding_provider,
         place_repository=MockPlaceVectorRepository(embedding_provider),
-        ranker=SimplePlaceRanker(),
+        ranker=TfidfPlaceRanker(),
     )
 
     result = await use_case.execute(
@@ -32,13 +33,32 @@ async def test_search_places_use_case_with_mock_providers() -> None:
     assert all(place.city == "Tuxtla Gutierrez" for place in result.places)
 
 
+@pytest.mark.asyncio
+async def test_search_places_ranks_with_tfidf_cosine_similarity() -> None:
+    embedding_provider = MockEmbeddingProvider()
+    use_case = SearchPlacesUseCase(
+        embedding_provider=embedding_provider,
+        place_repository=MockPlaceVectorRepository(embedding_provider),
+        ranker=TfidfPlaceRanker(),
+    )
+
+    result = await use_case.execute(
+        query="atardecer fotos paseo",
+        filters=PlaceFilters(is_active=True),
+        limit=3,
+    )
+
+    assert result.places[0].id == "place_2"
+    assert result.places[0].score > 0
+
+
 @pytest.mark.asyncio
 async def test_chat_places_returns_structured_places_with_llm_mock() -> None:
     embedding_provider = MockEmbeddingProvider()
     search_use_case = SearchPlacesUseCase(
         embedding_provider=embedding_provider,
         place_repository=MockPlaceVectorRepository(embedding_provider),
-        ranker=SimplePlaceRanker(),
+        ranker=TfidfPlaceRanker(),
     )
     chat_use_case = ChatPlacesUseCase(
         search_use_case=search_use_case,
@@ -59,13 +79,41 @@ async def test_chat_places_returns_structured_places_with_llm_mock() -> None:
     assert result.metadata["used_llm"] is True
 
 
+@pytest.mark.asyncio
+async def test_recommend_places_calls_llm_and_returns_message() -> None:
+    embedding_provider = MockEmbeddingProvider()
+    search_use_case = SearchPlacesUseCase(
+        embedding_provider=embedding_provider,
+        place_repository=MockPlaceVectorRepository(embedding_provider),
+        ranker=TfidfPlaceRanker(),
+    )
+    llm_provider = SpyLLMProvider()
+    use_case = RecommendPlacesUseCase(
+        search_use_case=search_use_case,
+        llm_provider=llm_provider,
+        output_guard=PlaceChatOutputGuard(),
+    )
+
+    result = await use_case.execute(
+        query="quiero una cena tranquila",
+        filters=PlaceFilters(city="Tuxtla Gutierrez", is_active=True),
+        limit=3,
+    )
+
+    assert llm_provider.calls == 1
+    assert result.message
+    assert result.places
+    assert result.metadata["used_llm"] is True
+    assert result.metadata["ranking"] == "tfidf_cosine"
+
+
 @pytest.mark.asyncio
 async def test_chat_places_falls_back_when_llm_fails() -> None:
     embedding_provider = MockEmbeddingProvider()
     search_use_case = SearchPlacesUseCase(
         embedding_provider=embedding_provider,
         place_repository=MockPlaceVectorRepository(embedding_provider),
-        ranker=SimplePlaceRanker(),
+        ranker=TfidfPlaceRanker(),
     )
     chat_use_case = ChatPlacesUseCase(
         search_use_case=search_use_case,
@@ -95,3 +143,25 @@ class FailingLLMProvider(LLMProvider):
         places: Sequence[dict[str, Any]],
     ) -> LLMResult:
         raise RuntimeError("LLM failed")
+
+
+class SpyLLMProvider(LLMProvider):
+    provider_name = "spy-llama"
+    model_name = "spy-model"
+
+    def __init__(self) -> None:
+        self.calls = 0
+
+    async def generate_place_chat_response(
+        self,
+        user_intent: str,
+        region: str | None,
+        places: Sequence[dict[str, Any]],
+    ) -> LLMResult:
+        self.calls += 1
+        place_names = ", ".join(str(place["name"]) for place in places[:2])
+        return LLMResult(
+            message=f"Estas opciones pueden encajar con tu plan: {place_names}.",
+            provider=self.provider_name,
+            model=self.model_name,
+        )