Spaces:
Sleeping
Sleeping
| title: Clara - Seguros Colsubsidio | |
| emoji: 🛡️ | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| short_description: Agente conversacional de venta de seguros (Reto 2 - 30X) | |
| # Clara — Venta automatizada de seguros 🛡️ | |
| **Reto 2 · Venta automatizada de seguros** — [Hackathon Colsubsidio × 30X](https://innovacion.colsubsidio.com/) | |
| · 22–26 de julio de 2026 · Club La Colina, Bogotá. | |
| Repositorio: [github.com/Mariana-Codebase/AgenteSeguros](https://github.com/Mariana-Codebase/AgenteSeguros) | |
| > **El reto:** hoy adquirir un seguro en Colsubsidio depende de un asesor que | |
| > identifique la necesidad, cotice, explique y cierre. Ese modelo no escala, no | |
| > opera 24/7 y depende del equipo comercial. **Clara lleva al afiliado desde | |
| > _"no sé qué seguro necesito"_ hasta _"ya quedé asegurado"_ sin un solo humano | |
| > en el medio.** | |
| --- | |
| ## Qué es Clara | |
| Clara es una **asesora digital de seguros** que conversa en lenguaje natural, en | |
| español colombiano. En una sola conversación: | |
| 1. **Diagnostica** la vida del afiliado con preguntas abiertas (con quién vive, si | |
| tiene carro, moto, mascota, viajes, dependientes…). | |
| 2. **Recomienda** el mejor producto de **todo el portafolio Colsubsidio** (14 | |
| productos), explicando por qué encaja, qué cubre y **qué NO cubre**. | |
| 3. **Contrata**: reúne los datos, genera el **contrato en PDF**, captura la | |
| **firma electrónica** y entrega un **enlace de pago** (checkout tipo Wompi). | |
| 4. **Emite** la **póliza en PDF** en el instante en que el pago se aprueba y hace | |
| post-venta (número de póliza, cómo usarla, encuesta de satisfacción). | |
| Todo el recorrido queda en un **registro de auditoría** persistente. La demo web | |
| muestra, en vivo y al lado del chat, **cada decisión, herramienta y escritura en | |
| base de datos** que ocurre detrás — para que un juez vea que no hay magia: hay | |
| arquitectura. | |
| --- | |
| ## Por qué Clara gana: una arquitectura en la que se puede confiar | |
| Vender seguros con un LLM tiene un riesgo mortal: **que el modelo alucine una | |
| cobertura, un precio o una condición**. En seguros eso no es un bug, es una | |
| **responsabilidad legal y financiera**. Clara está diseñada, de raíz, para que | |
| eso **no pueda pasar**: | |
| | Principio | Cómo lo garantiza Clara | | |
| |-----------|-------------------------| | |
| | **El LLM solo conversa** | Gemini nunca calcula ni inventa. Solo dialoga y **llama herramientas** (function-calling). Toda la lógica dura vive en el backend. | | |
| | **Coberturas ⇒ base de conocimiento (RAG)** | Cada afirmación de amparo/exclusión/condición sale de `consultar_coberturas`, **con cita de la fuente** (cláusula de las condiciones). | | |
| | **Precios ⇒ motor de reglas determinístico** | Ninguna cifra la produce el modelo: salen de un motor auditable (`cotizar`) con factores por edad y dependientes. | | |
| | **Emisión ⇒ backend, no el modelo** | Contrato, firma, pago y póliza los ejecuta el código de forma determinística; el modelo solo confirma en lenguaje natural. | | |
| | **Guardrail de salida** | Una capa basada en reglas revisa cada respuesta: si menciona cobertura o precio sin respaldo en el turno, lo marca en la auditoría. | | |
| | **Cumplimiento por diseño** | Aviso de tratamiento de datos (**Ley 1581 de 2012**) desde el saludo; el prompt rechaza temas fuera de alcance y resiste intentos de jailbreak. | | |
| | **Trazabilidad total** | Cada perfil, cotización, contrato, pago y póliza se registra en SQLite y se muestra en vivo en la interfaz. | | |
| > En una frase: **el modelo pone las palabras, el sistema pone la verdad.** | |
| --- | |
| ## El recorrido del afiliado | |
| ``` | |
| Afiliado Clara (Gemini) Backend determinístico | |
| │ │ │ | |
| │ "no sé qué necesito" │ │ | |
| ├────────────────────────▶│ diagnóstico (preguntas │ | |
| │ │ abiertas, escucha activa) │ | |
| │ ├─ registrar_perfil ──────────▶│ SQLite (perfil) | |
| │ │ │ | |
| │ ├─ recomendar ────────────────▶│ RAG + motor de reglas | |
| │◀── opciones con precio │◀─ coberturas + precio real ──┤ | |
| │ y exclusiones reales │ │ | |
| │ ├─ consultar_coberturas ──────▶│ RAG (cita fuente) | |
| │ "quiero ese" │ │ | |
| │ ├─ registrar_datos ───────────▶│ SQLite (contratante) | |
| │ ├─ generar_contrato ──────────▶│ PDF contrato | |
| │ [ firma con botón ] ───┼─────────────────────────────▶│ firma + enlace de pago | |
| │ [ paga en checkout ] ──┼─────────────────────────────▶│ webhook aprobado | |
| │◀── "ya quedaste │◀─ emisión determinística ────┤ PDF póliza + auditoría | |
| │ asegurado 🎉" │ │ | |
| ``` | |
| Estados de la sesión: `DIAGNOSTICO → RECOMENDACION → DUDAS → CIERRE → EMITIDA`. | |
| La conversación soporta un **atajo**: si el afiliado ya sabe lo que quiere | |
| ("solo quiero seguro de viaje"), Clara no lo interroga — va directo al producto. | |
| --- | |
| ## Portafolio cubierto (14 productos reales de Colsubsidio) | |
| Vida · Vida y Ahorro · Plan Complementario de Salud · Asistencias Médicas | |
| Familiares · Accidentes Personales · Exequial · Accidentes + Exequial · Asesorías | |
| Jurídicas · Asistencias Múltiples (hogar, vehículo, salud y mascotas 24/7) · | |
| Asistencia Médica en Viajes · Hogar · Autos · Moto · Mascotas. | |
| Cada uno con sus amparos, exclusiones, condiciones, fuente citable y prima base | |
| en `app/knowledge.py`. El recomendador **rankea por ajuste al perfil, no por | |
| precio**, y no se limita a vida o mascotas: considera todo el portafolio. | |
| --- | |
| ## Probar la demo en 2 minutos | |
| ```powershell | |
| python -m pip install -r requirements.txt | |
| copy .env.example .env # y pega tu GEMINI_API_KEY (gratis, sin tarjeta) | |
| python server.py | |
| ``` | |
| → Abre **http://localhost:8000** y entra a la pestaña **Demo interactiva**. | |
| Guion sugerido para el jurado: | |
| 1. *"Hola, no sé qué seguro necesito."* → deja que Clara diagnostique. | |
| 2. Cuéntale algo real: *"vivo con mi pareja y tengo un gato"* → mira cómo aparece | |
| el seguro de mascotas en la recomendación. | |
| 3. Elige un producto, da tus datos, **firma** con el botón y **paga** con la | |
| tarjeta de prueba `4242 4242 4242 4242` (la `4111…` simula rechazo). | |
| 4. Observa cómo se **emite la póliza en PDF** y todo queda en el panel de auditoría. | |
| > **Clave Gemini:** usa una de **Google AI Studio** (`AIza...`, | |
| > [aistudio.google.com/apikey](https://aistudio.google.com/apikey)), gratis y sin | |
| > tarjeta. Evita claves Vertex (`AQ.`) salvo que tengas facturación en Google Cloud. | |
| --- | |
| ## Estado de ejecución (honestidad de ingeniería) | |
| Esto es un **MVP demostrable** para la hackathon, no un producto en producción. | |
| El flujo principal se recorre completo en local; algunas piezas son | |
| **simulaciones** conscientes que se dejan listas para evolucionar. | |
| | Área | Estado | Notas | | |
| |------|--------|-------| | |
| | **Conversación con Gemini** | ✅ Funcional | Function-calling, escucha activa, manejo de peticiones directas. | | |
| | **Flujo end-to-end** | ✅ Funcional | Diagnóstico → recomendación → contrato → firma → pago → emisión, cableado y recorrible. | | |
| | **Frontend (chat + paneles)** | ✅ Funcional | Chat, estado, perfil y auditoría en vivo. | | |
| | **PDFs (resumen/contrato/póliza)** | ✅ Funcional | Generación real con `fpdf2`, descarga por `/docs/{archivo}`. | | |
| | **Persistencia** | ✅ Funcional | Sesiones y auditoría en SQLite; sobrevive reinicios. | | |
| | **Pago (Wompi)** | 🟡 Simulación | Checkout con tarjetas de prueba y validación Luhn. **No** es la API real de Wompi (webhooks firmados, producción). | | |
| | **Correo / WhatsApp** | 🟡 Simulación | Sin `SMTP_*`/Twilio, la entrega se registra como `[SIMULADO]`. Con credenciales, envía de verdad. | | |
| | **Despliegue** | 🟡 Preparado | Dockerfile + variables de entorno listos; falta hardening cloud. | | |
| --- | |
| ## Roadmap corto | |
| - **Agente:** pulir tono, consistencia de fases y edge cases de peticiones directas. | |
| - **Pago:** integración real con Wompi (referencias, estados, reintentos, webhook firmado). | |
| - **Entrega:** envío real de PDF por SMTP y WhatsApp (Twilio) con pruebas end-to-end. | |
| - **RAG / catálogo:** enriquecer condiciones desde fuentes oficiales (`data/reference/`). | |
| - **Calidad:** tests automatizados + CI, y observabilidad (métricas de sesión, errores LLM, latencias). | |
| --- | |
| ## Arquitectura y estructura | |
| ``` | |
| ├── server.py # Punto de entrada (python server.py) | |
| ├── app/ # Backend (paquete Python) | |
| │ ├── main.py # API FastAPI + checkout de pago | |
| │ ├── config.py # Configuración central (.env) | |
| │ ├── agent.py # Sesión, herramientas y bucle de tool-calling + guardrail | |
| │ ├── llm.py # Cliente Gemini (AI Studio + Vertex Express) | |
| │ ├── extraction.py # Captura de datos: regex + responseSchema (Gemini) | |
| │ ├── knowledge.py # Catálogo, RAG y motor de cotización (fuente de verdad) | |
| │ ├── payments.py # Pasarela simulada (tarjetas de prueba, Luhn) | |
| │ ├── pdfgen.py # PDFs de resumen, contrato y póliza (fpdf2) | |
| │ ├── notify.py # Entrega por correo SMTP / WhatsApp Twilio (opcional) | |
| │ └── store.py # SQLite (sesiones + auditoría) | |
| ├── static/ # Frontend (chat + paneles de estado/perfil/auditoría) | |
| │ ├── index.html · css/styles.css · js/app.js · img/ | |
| ├── data/reference/ # Documentos de referencia del reto (política de datos, workflow) | |
| ├── var/ # Runtime: PDFs y DB (ignorado en git) | |
| ├── Dockerfile · requirements.txt | |
| ``` | |
| **Stack:** Python · FastAPI · Gemini (function-calling) · fpdf2 · SQLite · Docker. | |
| --- | |
| ## Desplegar (Docker / Hugging Face Space) | |
| ```powershell | |
| docker build -t clara . | |
| docker run -p 7860:7860 -e GEMINI_API_KEY=AIza... clara | |
| ``` | |
| En un **Space** (SDK Docker): define `GEMINI_API_KEY` como *secret*. **Nunca** | |
| subas el `.env` real al repo ni al hosting. | |
| ### Variables de entorno | |
| | Variable | Por defecto | Descripción | | |
| |----------|-------------|-------------| | |
| | `GEMINI_API_KEY` | — | **Obligatoria.** Preferir clave AI Studio (`AIza...`). | | |
| | `GEMINI_MODEL` | `gemini-2.0-flash` | Modelo Gemini. | | |
| | `APP_ENV` | `development` | `production` desactiva docs OpenAPI y autoreload. | | |
| | `PORT` | `8000` / `7860` (Docker) | Puerto HTTP. | | |
| | `PUBLIC_BASE_URL` | auto | Base para enlaces de pago y PDFs (en Spaces se autodetecta). | | |
| | `SMTP_*` | — | Correo real con PDF adjunto (opcional). | | |
| | `TWILIO_*` | — | WhatsApp/SMS (opcional). | | |
| --- | |
| ## Autora | |
| **Mariana Sinisterra** · [@MarianaCodebase](https://github.com/MarianaCodebase) | |
| Prototipo para el **Reto 2 · Venta automatizada de seguros** — | |
| Hackathon [Colsubsidio × 30X](https://innovacion.colsubsidio.com/). | |
| </content> | |