🤖 Alura Agente — Asistente interno de NovaDesk

Agente de IA corporativo (challenge final de Alura) que responde preguntas en lenguaje natural sobre los documentos internos de NovaDesk, un SaaS ficticio de mesa de ayuda. Procesa 5 formatos de documento (PDF, Markdown, CSV, JSON y HTML) y está desplegado públicamente en la nube.

Demo en vivo: https://agentup-382104851468.us-central1.run.app

Arquitectura

          INGESTA (offline)                      SERVICIO (online)
data/ (pdf, md, csv, json, html)          Usuario → GET /  (chat UI)
   │  loaders por extensión                        POST /ask {"question"}
   ▼                                                  │
chunks (1000 chars, solape 200)                       ▼
   │  embeddings Gemini                    FAISS retriever (top-4 chunks)
   ▼   (gemini-embedding-001)                         │
índice FAISS → vectorstore/  ──────────►  prompt con contexto → Gemini
                                           (gemini-3.6-flash)
                                                      │
                                                      ▼
                                        {"answer": ..., "sources": [...]}

• Ingesta (src/ingest.py): carga los documentos según su extensión, los trocea y construye un índice vectorial FAISS que se persiste en disco.
• Cadena RAG (src/rag_chain.py): busca los 4 fragmentos más relevantes y se los pasa a Gemini con un prompt que le prohíbe inventar: si la respuesta no está en los documentos, lo dice explícitamente.
• API (src/app.py): FastAPI con POST /ask, GET /health y una chat UI mínima. El índice viaja dentro de la imagen Docker, por lo que el servicio no depende de ninguna base de datos externa.

Ejemplos de preguntas y respuestas

Pregunta	Respuesta del agente
¿Cuánto cuesta el plan Pro y qué incluye?	El plan Pro cuesta 29 USD al mes. Incluye: 20 usuarios, 50 GB de almacenamiento, soporte por email 24/7, todo lo del plan Starter, chat en vivo, 5 buzones de correo, informes avanzados y automatizaciones. (fuentes: base_conocimiento.pdf, planes_precios.json, terminos_de_uso.md)
¿Qué integraciones están disponibles en el plan Starter?	Las integraciones disponibles en el plan Starter son Zapier y Slack. (fuentes: base_conocimiento.pdf, integraciones.csv)
¿Cuál es la política de reembolso?	El cliente puede solicitar un reembolso completo dentro de los primeros 30 días posteriores al primer pago, escribiendo a facturacion@novadesk.example. Pasado ese plazo, no se emiten reembolsos por períodos ya facturados. (fuentes: faq_soporte.html, terminos_de_uso.md)
¿Cuál es la capital de Francia?	No encuentro esa información en los documentos.

Ejecución local

Requisitos: Python 3.12+ y una API key gratuita de Google AI Studio.

git clone https://github.com/MathiasTL/AgentUP.git && cd AgentUP
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # y coloca tu GOOGLE_API_KEY
python -m src.ingest        # (re)construye el índice FAISS
uvicorn src.app:app --port 8000
# abre http://localhost:8000

También funciona con un entorno conda/mamba en lugar de venv, por ejemplo mamba create -n agentup python=3.12.

Tests: pip install -r requirements-dev.txt && pytest

Deploy en la nube (GCP Cloud Run)

Nota IAM: en proyectos GCP nuevos hay que otorgar los roles roles/cloudbuild.builds.builder y roles/storage.objectViewer a la service account de Compute (NNN-compute@developer.gserviceaccount.com) antes de ejecutar el primer gcloud run deploy --source ., o el build fallará por permisos.

gcloud run deploy agentup --source . --region us-central1 \
  --allow-unauthenticated --set-env-vars "GOOGLE_API_KEY=<tu-clave>" --memory 1Gi

Nota sobre OCI: el challenge sugiere Oracle Cloud (OCI). Este proyecto usa GCP Cloud Run por disponibilidad de cuenta free tier; el reto permite usar la herramienta que tenga más sentido para el proyecto. El servicio está containerizado, por lo que el mismo Dockerfile puede desplegarse en OCI Compute sin cambios de código.

Estructura del repositorio

data/           documentos ficticios de NovaDesk (5 formatos)
scripts/        generador del PDF de la base de conocimiento
src/            ingesta, cadena RAG y API
static/         chat UI (HTML + JS vanilla)
tests/          tests unitarios (sin llamadas a APIs externas)
vectorstore/    índice FAISS generado