Skip to content

ucudal/reto-summer-2026-ithaka-ia

BranchesTags

Repository files navigation

reto-winter-2025-ithaka-backend

Opciones de Ejecución

Puedes ejecutar esta aplicación de dos formas:

1. Docker (Recomendado para producción)

# Opción A: Usar imagen del registry
docker pull crretoxmas2024.azurecr.io/ithaka-backend:latest
docker run -p 8000:8000 crretoxmas2024.azurecr.io/ithaka-backend:latest

# Opción B: Construir localmente
docker build -t ithaka-backend .
docker run -p 8000:8000 ithaka-backend

# Opción C: Docker Compose (desarrollo)
docker-compose up

2. Desarrollo Local (Python)

Requisitos

  • Python 3.12+
  • uv (gestor de paquetes compatible con pip)
  • PostgreSQL con extensión PGVector

Instalación

1. Crear entorno virtual

python3 -m venv .venv
source .venv/bin/activate

2. Instalar uv

Si no lo tenés instalado, escribí en la terminal:

pip install uv

3. Instalar dependencias

uv pip install -r requirements.txt

4. Configurar variables de entorno

Copia config/env.example a .env y configura las variables necesarias:

# Base de Datos
DATABASE_URL=postgresql+asyncpg://user:password@host:port/database

# OpenAI (requerido para agentes IA)
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Configuración de agentes
EMBEDDING_DIMENSION=1536
MAX_FAQ_RESULTS=5
WIZARD_SESSION_TIMEOUT=3600

# Email y Twilio (existentes)
[email protected]
EMAIL_PASS=your-app-password
TWILIO_ACCOUNT_SID=your-sid
TWILIO_AUTH_TOKEN=your-token

Guardrails para el Wizard

El wizard ahora usa el validador DetectJailbreak para bloquear intentos de prompt injection.

  1. Instalá las dependencias (el requirements.txt ya incluye guardrails-ai>=0.5.10).
  2. Descargá el recurso desde Guardrails Hub una sola vez: 
    guardrails hub install hub://guardrails/detect_jailbreak
  3. Configurá (o dejá por defecto) las variables: 
    WIZARD_DETECT_JAILBREAK_ENABLED=true
WIZARD_DETECT_JAILBREAK_THRESHOLD=0.9
  4. (Opcional) Para imágenes Docker, pasá el token del Guardrails Hub como build-arg para que el validador quede horneado: 
    docker compose build --build-arg GUARDRAILS_HUB_TOKEN=tu_token
    También podés definir GUARDRAILS_HUB_TOKEN en tu archivo .env (no lo comitees) y docker compose lo inyectará automáticamente gracias a build.args.

Si el validador no está disponible, el sistema seguirá usando el filtro de patrones, pero se recomienda mantener ambos mecanismos activos.

5. Configurar base de datos

Crear usuario y base de datos (si no existen):

CREATE USER <USUARIO> WITH PASSWORD '<PASSWORD>';
CREATE DATABASE <NOMBRE_DB> OWNER <USUARIO>;
GRANT ALL PRIVILEGES ON DATABASE <NOMBRE_DB> TO <USUARIO>;

Habilitar extensión PGVector:

CREATE EXTENSION IF NOT EXISTS vector;

Crear tablas:

python -m app.db.config.create_tables

6. Poblar FAQs (opcional)

python scripts/populate_faqs.py

7. Ejecución

Para ejecutarlo ir a la raíz del proyecto y ejecutar:

uvicorn app.main:app --reload

Documentación

Podes revisar la doc en http://127.0.0.1:8000/docs

🤖 Sistema de Agentes IA

Agentes Disponibles

  1. 🎯 Supervisor - Router inteligente que analiza intenciones del usuario
  2. ❓ FAQ - Responde consultas usando búsqueda vectorial (PGVector)
  3. ✅ Validator - Detecta correos, teléfonos y cédulas dentro de la conversación, valida su formato y guía al usuario para corregirlos antes de guardarlos.
  4. 📝 Wizard - Formulario conversacional (próximamente)

Uso del Sistema

WebSocket Endpoint

URL: ws://localhost:8000/api/v1/ws/

Ejemplos de Mensajes

FAQ (Preguntas Frecuentes):

{"content": "¿Qué es el programa Fellows?"}
{"content": "¿Cuánto cuestan los cursos?"}
{"content": "¿Cómo me entero de las convocatorias?"}

API REST:

curl -X POST "http://localhost:8000/api/v1/chat" \
     -H "Content-Type: application/json" \
     -d '{"message": "¿Qué es el programa Fellows?"}'

Respuesta típica:

{
  "response": "Aquí va la respuesta generada por el agente.",
  "agent_used": "faq",
  "wizard_session_id": null,
  "wizard_state": "INACTIVE",
  "current_question": 1,
  "wizard_responses": {},
  "awaiting_answer": false
}

Validator (Validación de datos):

{"message": "Podés validar este email: [email protected]?"}
{"message": "Mi teléfono es +598 9876 5432, confirmá si está correcto."}
{"message": "La cédula 48903345 es válida?"}

Tecnologías Utilizadas

  • LangGraph - Orquestación de agentes
  • LangChain - Framework de IA
  • OpenAI - LLM y embeddings
  • PGVector - Búsqueda semántica de FAQs
  • PostgreSQL - Persistencia

Validación en Tiempo Real

  • El Supervisor detecta cuando una intención incluye revisar o enviar datos personales (correo, teléfono, cédula) y enrutará el mensaje al agente validator automáticamente.
  • El Validator normaliza el dato, ejecuta las reglas de utils/validators.py y responde en la misma conversación indicando si es válido.
  • Ante errores, devuelve el motivo exacto y pide el dato corregido antes de permitir que continúe el flujo (ideal para evitar guardar información inconsistente).

🗄️ Base de Datos

Tablas Existentes

  • conversations - Conversaciones
  • messages - Historial de mensajes
  • postulations - Postulaciones completadas

Nuevas Tablas

-- FAQs con embeddings vectoriales
CREATE TABLE faq_embeddings (
    id SERIAL PRIMARY KEY,
    question VARCHAR NOT NULL,
    answer TEXT NOT NULL,
    embedding VECTOR(1536),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Sesiones del wizard (próximamente)
CREATE TABLE wizard_sessions (
    id SERIAL PRIMARY KEY,
    conv_id INTEGER REFERENCES conversations(id),
    current_question INTEGER DEFAULT 1,
    responses JSON DEFAULT '{}',
    state VARCHAR(50) DEFAULT 'ACTIVE',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

🔧 Debugging y Logs

Activar Logs Detallados

import logging
logging.basicConfig(level=logging.INFO)

Test de Componentes

# Test FAQ
from app.services.chat_service import chat_service

result = await chat_service.process_message("¿Qué es el programa Fellows?")
print(result)

🚨 Troubleshooting

Error: "No module named 'langchain'"

uv pip install -r requirements.txt

Error: "Extension vector does not exist"

CREATE EXTENSION vector;

Error: "OpenAI API key not found"

export OPENAI_API_KEY="sk-your-key-here"

Error: "Database connection failed"

Verificar DATABASE_URL en .env

📈 Próximas Integraciones

Wizard Agent

  • Formulario conversacional de 20 preguntas
  • Human-in-the-loop para mejoras
  • Evaluación IA con rúbrica
  • Persistencia de sesiones

Cómo Integrar Nuevos Agentes

  1. Crear el agente en app/agents/
  2. Agregar al workflow en app/graph/workflow.py
  3. Actualizar supervisor en app/agents/supervisor.py
  4. Agregar tests y documentación

Instrucciones para usar la base de datos y el ORM

1. Instalar dependencias

Asegúrate de tener las dependencias necesarias:

uv pip install -r requirements.txt

2. Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto con el siguiente contenido (ajusta los valores según tu entorno):

DATABASE_URL=postgresql+asyncpg://<USUARIO>:<PASSWORD>@<HOST>:<PUERTO>/<NOMBRE_DB>

3. Crear la base de datos y usuario en PostgreSQL

Solo ejecuta este bloque si el usuario y la base de datos NO existen:

CREATE USER <USUARIO> WITH PASSWORD '<PASSWORD>';
CREATE DATABASE <NOMBRE_DB> OWNER <USUARIO>;
GRANT ALL PRIVILEGES ON DATABASE <NOMBRE_DB> TO <USUARIO>;

Nota: Si el usuario o la base de datos ya existen, puedes omitir estos comandos y solo asegurarte de que el usuario tiene permisos sobre la base de datos.

4. Crear las tablas en la base de datos

Ejecuta el siguiente comando desde la raíz del proyecto:

python -m app.db.config.create_tables

Esto creará las tablas conversations, messages, postulations, faq_embeddings y wizard_sessions.

5. Correr la API

Inicia el servidor de desarrollo:

uvicorn app.main:app --reload

Cómo usar ruff

  • Analizar el código: 
    ruff check .

CI/CD y Docker

Pipeline Automático

  • Trigger: Push a ramas DevOps o main
  • Registry: crretoxmas2024.azurecr.io/ithaka-backend
  • Tags: Automático por rama y commit SHA

Usar imagen de producción

# Pull de la imagen del registry
docker pull crretoxmas2024.azurecr.io/ithaka-backend:latest

# Ejecutar contenedor
docker run -p 8000:8000 -e DATABASE_URL=sqlite+aiosqlite:///./app.db crretoxmas2024.azurecr.io/ithaka-backend:latest

Variables de entorno para Docker

DATABASE_URL=sqlite+aiosqlite:///./app.db  # Para desarrollo con SQLite
# O para PostgreSQL:
# DATABASE_URL=postgresql+asyncpg://user:password@host:5432/database

Funcionamiento de notificación por WhatsApp

CI/CD Pipeline Test - Wed Jul 30 11:49:28 -03 2025

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages