README.md

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