---
name: build_guide_prompt
kind: function
lang: py
domain: core
version: "1.0.0"
purity: pure
signature: "def build_guide_prompt(location: dict, pois: list[dict], interests: list[dict], user_query: str = \"\", lang: str = \"es\") -> list[dict]"
description: "Construye un prompt contextual para el LLM combinando ubicación actual, POIs cercanos rankeados e intereses del usuario. Retorna mensajes en formato OpenAI/Ollama."
tags: [prompt, llm, guide, location, pois, interests, openai, ollama, context]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: location
    desc: "Dict con info de ubicación de nominatim_reverse_geocode. Campos esperados: display_name, street, neighbourhood, city, country. Los campos vacíos se omiten del prompt."
  - name: pois
    desc: "Lista de POIs rankeados por relevancia (ya filtrados por match_pois_to_interests). Cada POI tiene: name, category, score, matched_interests, lat, lon, tags. Se usan como máximo los primeros 5."
  - name: interests
    desc: "Lista de intereses del usuario. Cada interés tiene: name (str), keywords (list[str]), weight (float). Se usan los names para el system prompt."
  - name: user_query
    desc: "Pregunta opcional del usuario. Si está vacía o no se proporciona, se usa '¿Qué me puedes contar de esta zona?' como default."
  - name: lang
    desc: "Código de idioma para la respuesta del LLM (ej: 'es', 'en', 'fr'). Por defecto 'es'."
output: "Lista de dos mensajes en formato OpenAI/Ollama: [{'role': 'system', 'content': '...'}, {'role': 'user', 'content': '...'}]. El system message define el rol de guía local con los intereses y el idioma. El user message incluye la ubicación, los POIs relevantes y la query."
tested: true
tests:
  - "con ubicacion completa pois y query"
  - "sin pois solo ubicacion"
  - "sin query usa default"
  - "max 5 pois"
  - "lang aparece en system"
  - "location sin neighbourhood"
test_file_path: "python/functions/core/build_guide_prompt_test.py"
file_path: "python/functions/core/build_guide_prompt.py"
---

## Ejemplo

```python
messages = build_guide_prompt(
    location={
        "display_name": "Puerta del Sol, Madrid",
        "city": "Madrid",
        "neighbourhood": "Sol",
        "street": "Puerta del Sol",
        "country": "España",
    },
    pois=[
        {
            "name": "Museo del Prado",
            "category": "museum",
            "score": 1.0,
            "matched_interests": ["arte"],
            "lat": 40.41,
            "lon": -3.70,
            "tags": {},
        }
    ],
    interests=[{"name": "arte", "keywords": ["museo"], "weight": 1.0}],
    user_query="¿Qué hay interesante por aquí?",
)
# [
#   {"role": "system", "content": "Eres un guía local experto y amigable. El usuario está caminando por Madrid y le interesan: arte..."},
#   {"role": "user", "content": "📍 Estoy en: Puerta del Sol, Madrid\nBarrio: Sol, Madrid\n\nLugares cercanos que me pueden interesar:\n- Museo del Prado (museum) — relevante para: arte\n\n¿Qué hay interesante por aquí?"}
# ]
```

## Notas

Función pura — no hace I/O, no muta los inputs, determinista.

El system message establece el rol del LLM como guía local con conocimiento de los intereses del usuario y el idioma de respuesta. Incluye instrucción de ser conciso (3-4 frases) y conversacional.

El user message combina:
- Ubicación completa del usuario (solo campos no vacíos)
- Lista de hasta 5 POIs con nombre, categoría y los intereses que satisfacen
- La query del usuario o un fallback genérico

Los campos de `location` vacíos o ausentes se omiten automáticamente del prompt para no generar ruido. Compatible con el formato de salida de `nominatim_reverse_geocode_py_infra` y `match_pois_to_interests`.
