README.md

metadata

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:

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:

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:

[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:

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.