README.md

---
title: Agent API
emoji: 🤖
colorFrom: green
colorTo: green
sdk: docker
pinned: false
---

# Modelos principales
ollama pull llama3.2:3b
ollama pull llava:7b
ollama pull nomic-embed-text    

## Modelo Qwen3-4B-Instruct GGUF local

Al construir la imagen, Docker descarga el GGUF desde
`AlbertiTechnology/qwen3-4b-instruct-gguf` y deja una copia local dentro de la
imagen. Docker ejecuta automaticamente:

```powershell
python download_model.py --download-only --repo AlbertiTechnology/qwen3-4b-instruct-gguf --local-dir MODELS/qwen3-4b-instruct-gguf
```

El modelo queda almacenado en
`/home/user/app/MODELS/qwen3-4b-instruct-gguf/model.gguf` dentro de la imagen y
la app lo ejecuta localmente mediante llama.cpp.

Esta descarga no requiere un token durante el build porque el repositorio es
publico.

## Contexto documental (Chroma)

El agente consulta la coleccion `document_context` de `chroma_db_docs`. Durante
el build de Docker, la base se reconstruye automaticamente usando solamente los
PDF y archivos de metadata ubicados en `documentos/ASTM`.

Para reconstruirla manualmente fuera de Docker, ejecute:

```powershell
venv\Scripts\python.exe index_documents_to_chroma.py --documents-dir "documentos/ASTM" --reset-collection
```

## Despliegue en Hugging Face Spaces

El contenedor ejecuta automaticamente `start_hf.py`. En cada arranque:

1. valida `DATABASE_URL`;
2. valida el modelo local `MODELS/qwen3-4b-instruct-gguf/model.gguf`;
3. valida la base Chroma y comprueba que `document_context` no este vacia;
4. inicia FastAPI/Uvicorn en el puerto `7860`.

Los reinicios del contenedor reutilizan la base creada dentro de la imagen. Cada
nuevo build vuelve a generarla desde `documentos/ASTM`.

Configure en **Settings > Variables and secrets** del Space:

- `DATABASE_URL`: conexion PostgreSQL usada para conversaciones y mensajes.

Los logs del Space muestran el proceso completo sin imprimir secrets:

```text
[2026-07-10T12:00:00Z] [BOOT:START] Starting Hugging Face Space initialization.
[2026-07-10T12:00:00Z] [BOOT:ENV] Required secrets are present (values are not printed).
[2026-07-10T12:00:00Z] [BOOT:CHROMA] Using build-generated document_context collection (119 chunks).
[2026-07-10T12:00:00Z] [BOOT:MODEL] Local Qwen model is available at /home/user/app/MODELS/qwen3-4b-instruct-gguf.
[2026-07-10T12:01:00Z] [BOOT:API] Starting Agent API on 0.0.0.0:7860...
```

Si falta un secret o la base Chroma empaquetada no es valida, el despliegue se
detiene con un mensaje `[BOOT:ERROR]` visible en **Logs**. La API no arranca con
una base incompleta.

## Lanzar el chat del agente

Inicie la API desde la raiz del proyecto:

```powershell
venv\Scripts\python.exe -m uvicorn main:app --host 0.0.0.0 --port 8011 --reload
```

Abra el frontend de chat en `http://127.0.0.1:8011/` (o en
`http://127.0.0.1:8011/ui`). Se usa el puerto 8011 porque en este entorno los
puertos 8000 y 8010 ya estan ocupados por otras instancias.

La API queda disponible mediante `POST http://127.0.0.1:8011/chat` y por
WebSocket en `ws://127.0.0.1:8011/ws/chat`. La documentacion interactiva se
abre en `http://127.0.0.1:8011/docs`.