Agente inteligente de cobranza

Contexto

Este es mi Trabajo de Fin de Máster del Máster en Big Data y Data Engineering de la Universidad Complutense de Madrid (con Ntic Master), 2024–2025. El repositorio es público. Es un sistema de demostración, no un despliegue bancario ni de cliente.

El dominio — cobranza digital, promesas de pago, desenlace de conversaciones — se solapa con trabajo posterior en analítica de servicios financieros. El TFM es independiente de cualquier empleador.

Problema

Las conversaciones de cobranza son desordenadas: la persona ya pagó, necesita tiempo, rechaza, promete. Un sistema útil tiene que (1) hablar con contexto, (2) persistir lo ocurrido y (3) convertir esas trazas en métricas que se puedan inspeccionar. Chat sin Gold deja a operaciones a ciegas. Un dashboard sin conversación deja los números sin suelo.

Arquitectura

La corrida local recuperada sigue este bucle:

1. Una UI tipo WhatsApp habla con FastAPI.
2. El agente usa Azure OpenAI si está configurado; si no, un fallback determinístico / heurístico (así se produjo esta captura — sin API de pago).
3. Los eventos caen en Bronze (JSONL). Los scripts de demo también llenan CSV de Silver / Gold para que Streamlit tenga superficie.
4. Streamlit sirve KPIs desde Gold.

El serving está partido: HTTP en :8000 (chat, /agent/reply, /docs, /health) y dashboard en :8501.

Datos / entradas

Nada de esto es una cartera real. scripts/generate_demo_data.py construye 200 conversaciones sintéticas (semilla 42) para Silver/Gold. scripts/generate_synthetic.py siembra un catálogo mínimo de deudores. Un turno de chat vivo se añade a data/bronze/events.jsonl.

PostgreSQL está en el stack documentado; la demo recuperada no lo exige. La persistencia a Postgres es best-effort y se ignora si la base no está.

Demo environment · synthetic data

Decisiones de ingeniería

• Procesamiento por capas, no un notebook único. Bronze se puede recuperar; Gold es lo que un humano debería mirar.
• API como superficie de producto. FastAPI posee etapas e intenciones; el LLM es opcional. La corrida recuperada demuestra que el producto sigue hablando sin Azure.
• PySpark está documentado; el Gold de estas capturas es CSV con pandas. Eso es honesto respecto a lo que se ejecutó.
• Docker + GitHub Actions existen en el repo. Compose hoy publica la imagen de la API, no el stack completo chat + Streamlit + Postgres.
• Sin integración bancaria ni CRM en v1.

Implementación

Paquete Python 3.11: app/core, app/llm, app/routers, app/services, más dashboard/ y scripts/. La recuperación local usó Python 3.12, requirements.txt, scripts de demo, uvicorn y Streamlit — sin cambios de código.

Retos

• Mantener estado de conversación sin fingir un core bancario.
• Generar datos de demo que aún ejerciten Bronze → Gold sin cuentas confidenciales.
• Separar definiciones de KPI de números que no voy a vender como lift de producción.

Resultados

Lo que sí respaldo:

• Demo RUNNING recuperada: UI de chat, FastAPI, Streamlit, eventos Bronze de un turno real, CSV Gold del generador.
• Diseño de datos por capas y un vocabulario de KPIs (conversaciones, tasa de promesa, monto prometido, deuda).
• CI, Docker, tests y un nombre de paquete distribuible en el repo.

Lo que no afirmo: lift de recaudo, efectivo cobrado, ni que esto haya corrido sobre cartera real. Las respuestas GPT de Azure no se usaron en estas capturas.

Qué aprendí

Un agente de cobranza que no se puede inspeccionar en Gold es solo una ventana de chat. El bucle interesante es conversación entra → desenlace estructurado → métrica que alguien puede desconfiar.

También aprendí a mantener trabajo de empleador y TFM en frases distintas. Misma intuición de industria; artefactos distintos.

Stack

Python, FastAPI, Azure OpenAI opcional, pandas (Gold de demo), PySpark (documentado), Streamlit, Docker, GitHub Actions.

Repositorio

github.com/carlosdcorona/tfm-cobranza-agent