feat(agent): asistente RAG con function calling + memoria (Fase 5)

- backend/services/tools.py: 3 herramientas tipadas (tendencia NDVI, contexto
climático, densidad [en desarrollo]) + TOOLS_SCHEMA + dispatch.
- backend/services/agent.py: orquestación Groq/Llama 3 (OpenAI-compatible vía httpx),
bucle de tool-calling y memoria en chat_messages.
- backend/api/chat.py: POST /api/chat (no-streaming; SSE diferido).
- repositories.get_field_by_name (con centroide para el clima).
- Tests: unit (schema, _describe_trend) + integración en vivo (Groq llama la
herramienta NDVI end-to-end). 58 passed, ruff limpio.

backend/api/chat.py

@@ -0,0 +1,57 @@
+"""
+Archivo: chat.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Router del Asistente Agéntico (RAG). `POST /api/chat` recibe un turno del usuario, lo
+procesa con el agente (function calling sobre las parcelas) y devuelve la respuesta más
+la traza de herramientas usadas. La memoria vive en `chat_messages`. La llave de Groq es
+efímera (cabecera `X-User-Groq-Key` o `DEV_GROQ_API_KEY` en local).
+
+Nota: versión **no-streaming** (request/response). El streaming SSE queda como mejora
+futura; la respuesta sincrónica encaja bien con la UI Shiny.
+
+Estructura Interna:
+    - `POST /api/chat`.
+
+Entradas / Dependencias:
+    - `backend.services.agent`, `backend.db.repositories`, `backend.api.deps`.
+
+Ejemplo de Integración:
+    from backend.api.chat import router
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.api.deps import UserKeys, get_db, get_user_keys
+from backend.db import repositories as repo
+from backend.services import agent
+
+router = APIRouter(prefix="/api/chat", tags=["asistente"])
+
+
+class ChatRequest(BaseModel):
+    """Turno del usuario hacia el agente."""
+
+    session_id: str = Field(min_length=1, description="Hilo conversacional")
+    message: str = Field(min_length=1, description="Mensaje del usuario")
+
+
+@router.post("")
+async def chat(
+    body: ChatRequest,
+    keys: UserKeys = Depends(get_user_keys),
+    session: AsyncSession = Depends(get_db),
+) -> dict:
+    """Procesa un turno con el agente RAG y devuelve respuesta + traza de herramientas."""
+    if not keys.groq:
+        raise HTTPException(
+            status_code=400, detail="Falta la llave de Groq (pestaña Credenciales)."
+        )
+    field_names = [row.name for row in await repo.list_fields(session)]
+    return await agent.run_agent(session, body.message, body.session_id, keys.groq, field_names)

backend/db/repositories.py

@@ -88,6 +88,24 @@ async def get_field(session: AsyncSession, field_id: Any) -> Row | None:
     return result.first()
 
 
+async def get_field_by_name(session: AsyncSession, name: str) -> Row | None:
+    """
+    Busca una parcela por nombre (case-insensitive) y devuelve id, nombre, área y centroide.
+
+    Returns:
+        Row | None: Fila con `id`, `name`, `area_ha`, `lon`, `lat` (centroide), o None.
+    """
+    result = await session.execute(
+        text(
+            "select id, name, (ST_Area(geom::geography) / 10000.0) as area_ha, "
+            "ST_X(ST_Centroid(geom)) as lon, ST_Y(ST_Centroid(geom)) as lat "
+            "from fields where lower(name) = lower(:name) order by created_at desc limit 1"
+        ),
+        {"name": name},
+    )
+    return result.first()
+
+
 async def list_fields(session: AsyncSession, user_id: str | None = None) -> list[Row]:
     """Lista las parcelas (filtradas por usuario si se indica), ordenadas por nombre."""
     if user_id is None:

backend/main.py

@@ -39,6 +39,7 @@ from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
+from backend.api.chat import router as chat_router
 from backend.api.count import router as count_router
 from backend.api.fields import router as fields_router
 from backend.api.ndvi import router as ndvi_router
@@ -103,6 +104,7 @@ def create_app() -> FastAPI:
     app.include_router(fields_router)  # Creación de Parcelas
     app.include_router(ndvi_router)  # Teledetección NDVI
     app.include_router(weather_router)  # Clima
+    app.include_router(chat_router)  # Asistente Agéntico (RAG)
     app.include_router(count_router)  # Conteo (en desarrollo / standby)
     return app
 

backend/services/agent.py

@@ -0,0 +1,131 @@
+"""
+Archivo: agent.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Orquestador del agente conversacional (RAG con function calling) sobre Groq/Llama 3.
+Construye la conversación (sistema + memoria + turno), deja que el modelo decida qué
+herramienta tipada invocar, ejecuta las herramientas reales (NDVI/clima/densidad) y
+devuelve la respuesta final con la traza de herramientas usadas. Persiste los turnos
+(user/assistant) en `chat_messages`. Usa la API OpenAI-compatible de Groq vía httpx
+(async) — sin SDK extra.
+
+Acciones Principales:
+    - `run_agent`: ciclo de tool-calling + memoria + respuesta final.
+
+Estructura Interna:
+    - `_system_prompt`: instrucciones + parcelas disponibles.
+    - `_groq_chat`: llamada HTTP a Groq (con/sin herramientas).
+    - `run_agent`: bucle de orquestación.
+
+Entradas / Dependencias:
+    - `httpx`; `backend.services.tools`, `backend.db.repositories`.
+
+Salidas / Efectos:
+    - Lecturas/escrituras en `chat_messages`; llamadas a Groq y a las herramientas.
+
+Ejemplo de Integración:
+    from backend.services.agent import run_agent
+    out = await run_agent(session, "¿cómo va el NDVI de Lote A?", "sess-1", keys, ["Lote A"])
+"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.db import repositories as repo
+from backend.services.tools import TOOL_DISPATCH, TOOLS_SCHEMA
+
+_GROQ_URL = "https://api.groq.com/openai/v1/chat/completions"
+_MODEL = "llama-3.3-70b-versatile"
+_MAX_TOOL_ROUNDS = 4
+
+
+def _system_prompt(field_names: list[str]) -> str:
+    """Construye el prompt de sistema con las parcelas disponibles."""
+    parcelas = ", ".join(field_names) if field_names else "(ninguna registrada todavía)"
+    return (
+        "Eres el asistente agronómico de AgroVisión. Respondes en español, de forma "
+        "concisa y técnica. Dispones de herramientas para consultar el NDVI, el clima y "
+        "la densidad de las parcelas del usuario; úsalas en vez de inventar datos. Si una "
+        "herramienta indica que algo está 'en desarrollo', acláralo. "
+        f"Parcelas disponibles: {parcelas}."
+    )
+
+
+async def _groq_chat(api_key: str, messages: list[dict], use_tools: bool) -> dict:
+    """Llama al endpoint de chat de Groq (con herramientas si `use_tools`)."""
+    payload: dict = {"model": _MODEL, "messages": messages, "temperature": 0.2}
+    if use_tools:
+        payload["tools"] = TOOLS_SCHEMA
+        payload["tool_choice"] = "auto"
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            _GROQ_URL, headers={"Authorization": f"Bearer {api_key}"}, json=payload, timeout=60
+        )
+    response.raise_for_status()
+    return response.json()
+
+
+async def run_agent(
+    session: AsyncSession,
+    message: str,
+    session_id: str,
+    api_key: str,
+    field_names: list[str],
+) -> dict:
+    """
+    Ejecuta el agente: memoria + tool-calling + respuesta, y persiste los turnos.
+
+    Args:
+        session (AsyncSession): Sesión de BD.
+        message (str): Mensaje del usuario.
+        session_id (str): Hilo conversacional.
+        api_key (str): Llave de Groq (efímera).
+        field_names (list[str]): Parcelas disponibles (para el prompt de sistema).
+
+    Returns:
+        dict: {reply, tool_logs, session_id}.
+    """
+    await repo.save_chat_message(session, session_id=session_id, role="user", content=message)
+    history = await repo.get_chat_history(session, session_id)
+    messages: list[dict] = [{"role": "system", "content": _system_prompt(field_names)}]
+    messages += [{"role": row.role, "content": row.content} for row in history]
+
+    tool_logs: list[dict] = []
+    for _ in range(_MAX_TOOL_ROUNDS):
+        data = await _groq_chat(api_key, messages, use_tools=True)
+        choice = data["choices"][0]["message"]
+        tool_calls = choice.get("tool_calls")
+        if not tool_calls:
+            reply = choice.get("content") or ""
+            await repo.save_chat_message(
+                session, session_id=session_id, role="assistant", content=reply
+            )
+            return {"reply": reply, "tool_logs": tool_logs, "session_id": session_id}
+
+        messages.append(choice)  # mensaje del asistente con las tool_calls
+        for call in tool_calls:
+            name = call["function"]["name"]
+            try:
+                args = json.loads(call["function"].get("arguments") or "{}")
+            except json.JSONDecodeError:
+                args = {}
+            tool = TOOL_DISPATCH.get(name)
+            result = (
+                await tool(session, **args)
+                if tool
+                else f"Herramienta desconocida: {name}."
+            )
+            tool_logs.append({"tool": name, "args": args})
+            messages.append({"role": "tool", "tool_call_id": call["id"], "content": result})
+
+    # Si se agotaron las rondas de herramientas, pide una respuesta final sin tools.
+    data = await _groq_chat(api_key, messages, use_tools=False)
+    reply = data["choices"][0]["message"].get("content") or "(sin respuesta)"
+    await repo.save_chat_message(session, session_id=session_id, role="assistant", content=reply)
+    return {"reply": reply, "tool_logs": tool_logs, "session_id": session_id}

backend/services/tools.py

@@ -0,0 +1,178 @@
+"""
+Archivo: tools.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Herramientas tipadas del agente RAG (function calling). El LLM no inventa datos: decide
+qué función llamar y nuestro código la ejecuta contra la BD / clima real y devuelve el
+resultado para que redacte. Tres herramientas: tendencia NDVI, contexto climático y
+densidad de siembra (esta última, en desarrollo mientras el Conteo esté inactivo).
+
+Acciones Principales:
+    - Define `TOOLS_SCHEMA` (JSON-Schema) y `TOOL_DISPATCH` (name -> coroutine).
+
+Estructura Interna:
+    - `_describe_trend`: formateo puro de la tendencia NDVI (testeable sin BD).
+    - `get_vegetation_index_trend` / `get_weather_context` / `get_field_planting_density`.
+
+Entradas / Dependencias:
+    - `backend.db.repositories`, `backend.services.weather`.
+
+Salidas / Efectos:
+    - Lecturas a la BD del usuario y a Open-Meteo.
+
+Ejemplo de Integración:
+    from backend.services.tools import TOOLS_SCHEMA, TOOL_DISPATCH
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+
+from dateutil.relativedelta import relativedelta
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.db import repositories as repo
+from backend.services import weather
+
+
+def _in_range(date_value: object, start: str | None, end: str | None) -> bool:
+    """Indica si una fecha (date o str) cae dentro de [start, end] (ISO) si se dan."""
+    day = str(date_value)[:10]
+    if start and day < start[:10]:
+        return False
+    return not (end and day > end[:10])
+
+
+def _describe_trend(field_name: str, series: list[dict]) -> str:
+    """
+    Redacta la tendencia NDVI de una serie (función pura).
+
+    Args:
+        field_name (str): Nombre de la parcela.
+        series (list[dict]): Puntos con 'date' y 'mean_ndvi' ordenados por fecha.
+
+    Returns:
+        str: Texto con la tendencia (descenso/incremento/estable) y los extremos.
+    """
+    valid = [p for p in series if p.get("mean_ndvi") is not None]
+    if len(valid) < 2:
+        return f"Datos insuficientes de NDVI para '{field_name}' (se necesitan ≥2 observaciones)."
+    first, last = valid[0], valid[-1]
+    delta = last["mean_ndvi"] - first["mean_ndvi"]
+    trend = "estable" if abs(delta) < 0.02 else ("descenso" if delta < 0 else "incremento")
+    return (
+        f"NDVI de '{field_name}': {trend} de {delta:+.2f} entre {str(first['date'])[:10]} "
+        f"({first['mean_ndvi']:.2f}) y {str(last['date'])[:10]} ({last['mean_ndvi']:.2f}). "
+        f"Observaciones: {len(valid)}."
+    )
+
+
+async def get_vegetation_index_trend(
+    session: AsyncSession,
+    field_name: str,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> str:
+    """Tendencia de NDVI de una parcela entre dos fechas (usa la serie persistida)."""
+    field = await repo.get_field_by_name(session, field_name)
+    if field is None:
+        return f"No encontré la parcela '{field_name}'."
+    series = await repo.get_ndvi_series(session, field.id)
+    in_range = [p for p in series if _in_range(p["date"], start_date, end_date)]
+    return _describe_trend(field_name, in_range)
+
+
+async def get_weather_context(
+    session: AsyncSession,
+    field_name: str,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> str:
+    """Resumen agroclimático de una parcela (clima de Open-Meteo en su centroide)."""
+    field = await repo.get_field_by_name(session, field_name)
+    if field is None:
+        return f"No encontré la parcela '{field_name}'."
+    if not start_date or not end_date:
+        end = dt.date.today()
+        start = end - relativedelta(months=12)
+        start_date, end_date = start.isoformat(), end.isoformat()
+    series = await weather.weather_series(field.lat, field.lon, start_date, end_date)
+    if not series:
+        return f"Sin datos climáticos para '{field_name}' en el rango."
+    total_precip = round(sum(p["precip_mm"] for p in series), 1)
+    temps = [p["temp_mean_c"] for p in series if p["temp_mean_c"] is not None]
+    avg_temp = round(sum(temps) / len(temps), 1) if temps else None
+    return (
+        f"Clima de '{field_name}' ({start_date} a {end_date}): precipitación acumulada "
+        f"{total_precip} mm, temperatura media {avg_temp} °C sobre {len(series)} meses."
+    )
+
+
+async def get_field_planting_density(session: AsyncSession, field_name: str) -> str:
+    """Densidad de siembra de una parcela (en desarrollo: depende del módulo de Conteo)."""
+    field = await repo.get_field_by_name(session, field_name)
+    if field is None:
+        return f"No encontré la parcela '{field_name}'."
+    area = f"{field.area_ha:.2f} ha" if field.area_ha else "área desconocida"
+    return (
+        f"La parcela '{field_name}' mide {area}. La densidad de plantas aún no está "
+        "disponible: el módulo de conteo por dron está en desarrollo."
+    )
+
+
+TOOLS_SCHEMA: list[dict] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_vegetation_index_trend",
+            "description": "Tendencia del NDVI (vigor vegetal) de una parcela entre dos fechas.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "field_name": {"type": "string", "description": "Nombre de la parcela"},
+                    "start_date": {"type": "string", "description": "Inicio YYYY-MM-DD (opcional)"},
+                    "end_date": {"type": "string", "description": "Fin YYYY-MM-DD (opcional)"},
+                },
+                "required": ["field_name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather_context",
+            "description": "Resumen agroclimático (precipitación y temperatura) de una parcela.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "field_name": {"type": "string", "description": "Nombre de la parcela"},
+                    "start_date": {"type": "string", "description": "Inicio YYYY-MM-DD (opcional)"},
+                    "end_date": {"type": "string", "description": "Fin YYYY-MM-DD (opcional)"},
+                },
+                "required": ["field_name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_field_planting_density",
+            "description": "Densidad de siembra (pl/Ha) de una parcela. En desarrollo.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "field_name": {"type": "string", "description": "Nombre de la parcela"},
+                },
+                "required": ["field_name"],
+            },
+        },
+    },
+]
+
+TOOL_DISPATCH = {
+    "get_vegetation_index_trend": get_vegetation_index_trend,
+    "get_weather_context": get_weather_context,
+    "get_field_planting_density": get_field_planting_density,
+}

tests/integration/test_agent.py

@@ -0,0 +1,90 @@
+"""
+Archivo: test_agent.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Prueba de integración del agente RAG (Fase 5): con una parcela y serie NDVI sembradas,
+una consulta de tendencia debe disparar la herramienta `get_vegetation_index_trend` y
+producir una respuesta. Verifica function calling + memoria end-to-end. Se omite si
+faltan la llave de Groq o `DATABASE_URL`.
+
+Ejecución:
+    uv run python -m pytest tests/integration/test_agent.py -v
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import uuid
+
+import pytest
+from dotenv import load_dotenv
+
+load_dotenv()
+
+_HAS_GROQ = bool(os.getenv("DEV_GROQ_API_KEY"))
+_HAS_DB = bool(os.getenv("DATABASE_URL"))
+
+from backend.db import repositories as repo  # noqa: E402
+from backend.db.session import get_engine, get_sessionmaker  # noqa: E402
+from backend.services.agent import run_agent  # noqa: E402
+
+_SQUARE = {
+    "type": "Polygon",
+    "coordinates": [
+        [[-58.0, -34.0], [-58.0, -34.1], [-57.9, -34.1], [-57.9, -34.0], [-58.0, -34.0]]
+    ],
+}
+
+
+@contextlib.asynccontextmanager
+async def _engine_scope():
+    get_engine.cache_clear()
+    get_sessionmaker.cache_clear()
+    try:
+        yield get_sessionmaker()
+    finally:
+        await get_engine().dispose()
+        get_engine.cache_clear()
+        get_sessionmaker.cache_clear()
+
+
+@pytest.mark.skipif(not (_HAS_GROQ and _HAS_DB), reason="Faltan Groq o DATABASE_URL")
+def test_agente_llama_herramienta_ndvi() -> None:
+    """Una consulta de NDVI dispara la herramienta de tendencia y devuelve respuesta."""
+    user_id = str(uuid.uuid4())
+    field_name = f"Lote Test {uuid.uuid4().hex[:6]}"
+    session_id = f"sess-{uuid.uuid4()}"
+
+    async def _run() -> None:
+        async with _engine_scope() as sm, sm() as session:
+            try:
+                field = await repo.create_field(
+                    session, name=field_name, geojson=_SQUARE, user_id=user_id
+                )
+                await repo.upsert_ndvi_points(
+                    session,
+                    field.id,
+                    [
+                        {"date": "2026-01-01", "mean_ndvi": 0.80, "cloud_cover": 5},
+                        {"date": "2026-03-01", "mean_ndvi": 0.68, "cloud_cover": 7},
+                    ],
+                )
+                out = await run_agent(
+                    session,
+                    f"¿Cómo evolucionó el NDVI de {field_name}?",
+                    session_id,
+                    os.environ["DEV_GROQ_API_KEY"],
+                    [field_name],
+                )
+                assert out["reply"]
+                tools_used = {log["tool"] for log in out["tool_logs"]}
+                assert "get_vegetation_index_trend" in tools_used
+            finally:
+                await repo.delete_chat_for_session(session, session_id)
+                await repo.delete_fields_for_user(session, user_id)
+
+    asyncio.run(_run())

tests/unit/test_tools.py

@@ -0,0 +1,61 @@
+"""
+Archivo: test_tools.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Pruebas unitarias de las herramientas del agente: el esquema de function calling y el
+formateo puro de la tendencia NDVI.
+
+Ejecución:
+    uv run python -m pytest tests/unit/test_tools.py
+"""
+
+from __future__ import annotations
+
+from backend.services.tools import TOOLS_SCHEMA, _describe_trend, _in_range
+
+
+def test_tools_schema_define_tres_herramientas() -> None:
+    """El esquema declara las 3 herramientas con `field_name` requerido."""
+    names = {t["function"]["name"] for t in TOOLS_SCHEMA}
+    assert names == {
+        "get_vegetation_index_trend",
+        "get_weather_context",
+        "get_field_planting_density",
+    }
+    for tool in TOOLS_SCHEMA:
+        assert "field_name" in tool["function"]["parameters"]["required"]
+
+
+def test_describe_trend_descenso() -> None:
+    """Una serie que baja se describe como 'descenso' con el delta correcto."""
+    series = [
+        {"date": "2026-01-01", "mean_ndvi": 0.80},
+        {"date": "2026-03-01", "mean_ndvi": 0.70},
+    ]
+    out = _describe_trend("Lote A", series)
+    assert "descenso" in out
+    assert "Lote A" in out
+    assert "-0.10" in out
+
+
+def test_describe_trend_estable() -> None:
+    """Un cambio menor a 0.02 se considera 'estable'."""
+    series = [
+        {"date": "2026-01-01", "mean_ndvi": 0.70},
+        {"date": "2026-03-01", "mean_ndvi": 0.71},
+    ]
+    assert "estable" in _describe_trend("Lote A", series)
+
+
+def test_describe_trend_insuficiente() -> None:
+    """Con menos de 2 observaciones se reporta datos insuficientes."""
+    assert "insuficientes" in _describe_trend("Lote A", [{"date": "2026-01-01", "mean_ndvi": 0.7}])
+
+
+def test_in_range() -> None:
+    """El filtro de rango respeta los límites ISO."""
+    assert _in_range("2026-03-01", "2026-01-01", "2026-12-31")
+    assert not _in_range("2025-12-01", "2026-01-01", None)
+    assert _in_range("2026-03-01", None, None)