mirror of
https://github.com/marcogll/telegram_expenses_controller.git
synced 2026-01-13 13:25:15 +00:00
Actualizar README con detalles del proyecto
El README se ha actualizado para reflejar el propósito y las características del sistema de gestión de gastos personalizable construido con Python y Telegram. Se han añadido secciones sobre objetivos, características principales, arquitectura de datos, tecnologías utilizadas y principios de diseño.
This commit is contained in:
Marco Gallegos
233
README.md
233
README.md
@@ -1 +1,232 @@
|
||||
# telegram_expenses_controller
|
||||
# Sistema de Gestión de Gastos Personalizable con Python y Telegram
|
||||
|
||||
Este proyecto implementa un **sistema de gestión de gastos modular, auditable y altamente personalizable**, construido en Python y operado a través de un bot de Telegram. El objetivo no es solo registrar gastos, sino **entenderlos, clasificarlos y validarlos** con un equilibrio deliberado entre reglas explícitas (configuración humana) e inferencia asistida por IA.
|
||||
|
||||
El sistema permite registrar gastos usando **texto, notas de voz, imágenes (tickets) y documentos PDF (facturas)**. La IA se utiliza únicamente para interpretar datos no estructurados (OCR, transcripción, extracción semántica), mientras que **la lógica de negocio vive fuera del código**, en archivos CSV y JSON que el usuario controla.
|
||||
|
||||
La filosofía central es simple pero potente:
|
||||
|
||||
> *La IA sugiere, las reglas deciden, el usuario confirma.*
|
||||
|
||||
---
|
||||
|
||||
## Objetivos del Sistema
|
||||
|
||||
* Eliminar fricción en el registro diario de gastos.
|
||||
* Evitar dependencias rígidas de lógica hardcodeada.
|
||||
* Mantener trazabilidad y control fiscal (especialmente en México).
|
||||
* Permitir adaptación rápida a cualquier negocio o uso personal.
|
||||
* Diseñar una base sólida para automatización contable posterior.
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
### Personalización Total (Config-Driven)
|
||||
|
||||
La clasificación de gastos **no está en el código**. Proveedores, categorías, subcategorías, palabras clave y reglas fiscales se gestionan mediante archivos CSV y JSON editables.
|
||||
|
||||
Esto permite:
|
||||
|
||||
* Ajustes sin despliegues.
|
||||
* Uso por personas no técnicas.
|
||||
* Reglas distintas por usuario o empresa.
|
||||
|
||||
### Entrada Multimodal
|
||||
|
||||
El bot acepta gastos mediante:
|
||||
|
||||
* Texto libre.
|
||||
* Notas de voz (transcripción automática).
|
||||
* Fotos de tickets (OCR).
|
||||
* Facturas PDF (extracción estructurada).
|
||||
|
||||
Todo converge en un modelo de gasto unificado.
|
||||
|
||||
### Procesamiento Inteligente con IA (Controlada)
|
||||
|
||||
La IA se utiliza para:
|
||||
|
||||
* Leer y transcribir información no estructurada.
|
||||
* Extraer proveedor, fecha, monto y conceptos.
|
||||
* Inferir contexto **solo cuando las reglas no aplican**.
|
||||
|
||||
La decisión final prioriza reglas explícitas antes que inferencia probabilística.
|
||||
|
||||
### Validación Fiscal (CFDI)
|
||||
|
||||
Si el sistema detecta una factura:
|
||||
|
||||
* Verifica que el RFC receptor coincida con el configurado.
|
||||
* Considera el régimen fiscal del usuario.
|
||||
* Marca inconsistencias como observaciones (no bloquea, pero alerta).
|
||||
|
||||
### Flujo de Confirmación y Auditoría
|
||||
|
||||
Ningún gasto entra al registro final sin pasar por confirmación.
|
||||
|
||||
El sistema:
|
||||
|
||||
* Presenta un resumen al usuario.
|
||||
* Permite correcciones naturales por chat.
|
||||
* Registra **qué cambió, quién lo cambió y por qué**.
|
||||
|
||||
Esto garantiza integridad y auditabilidad.
|
||||
|
||||
---
|
||||
|
||||
## Arquitectura de Datos: El Cerebro Configurable
|
||||
|
||||
El núcleo del sistema es la carpeta `config/`. Aquí se define **cómo piensa el bot**.
|
||||
|
||||
### 1. Configuración del Usuario
|
||||
|
||||
**Archivo:** `config/user_config.json`
|
||||
|
||||
Define la identidad fiscal y preferencias base del usuario.
|
||||
|
||||
```json
|
||||
{
|
||||
"user_name": "Marco Gallegos",
|
||||
"rfc": "GAMM910513CW6",
|
||||
"regimen_fiscal_default": "612 - Persona Física con Actividad Empresarial y Profesional",
|
||||
"moneda_default": "MXN",
|
||||
"pais": "MX",
|
||||
"timezone": "America/Mexico_City"
|
||||
}
|
||||
```
|
||||
|
||||
Este archivo es crítico para validación CFDI y normalización de datos.
|
||||
|
||||
---
|
||||
|
||||
### 2. Base de Proveedores
|
||||
|
||||
**Archivo:** `config/providers.csv`
|
||||
|
||||
Es la regla de clasificación **más fuerte del sistema**.
|
||||
|
||||
```csv
|
||||
provider_name,aliases,categoria_principal,subcategoria,tipo_gasto_default
|
||||
Amazon,"amazon,amzn,amazon mx",Por Determinar,Compras en Línea,
|
||||
Office Depot,"officedepot,office",Administración,Suministros de oficina,negocio
|
||||
Uber Eats,"ubereats,uber",Personal,Comida a domicilio,personal
|
||||
GoDaddy,"godaddy",Tecnología,Dominios y Hosting,negocio
|
||||
Cinepolis,"cinepolis",Personal,Entretenimiento,personal
|
||||
```
|
||||
|
||||
Si un proveedor coincide aquí, **no se consulta a la IA**.
|
||||
|
||||
---
|
||||
|
||||
### 3. Palabras Clave de Artículos
|
||||
|
||||
**Archivo:** `config/keywords.csv`
|
||||
|
||||
Se usa principalmente para proveedores genéricos.
|
||||
|
||||
```csv
|
||||
keyword,categoria_principal,subcategoria,tipo_gasto_default
|
||||
monitor,Tecnología,Equipo de Cómputo,negocio
|
||||
croquetas,Personal,Mascotas,personal
|
||||
hosting,Tecnología,Dominios y Hosting,negocio
|
||||
libro,Educación,Libros y Material,negocio
|
||||
```
|
||||
|
||||
Permite clasificación por contenido del ticket, no solo por tienda.
|
||||
|
||||
---
|
||||
|
||||
## Agentes de IA: Roles Claros, Responsabilidades Limitadas
|
||||
|
||||
El sistema usa dos agentes conceptuales, cada uno con límites estrictos.
|
||||
|
||||
### 1. The Analyst (Procesamiento Inicial)
|
||||
|
||||
Responsable de convertir una entrada cruda en un gasto estructurado.
|
||||
|
||||
Flujo lógico:
|
||||
|
||||
1. **Extracción de datos** (OCR, transcripción, parsing).
|
||||
2. **Matching contra providers.csv** (prioridad máxima).
|
||||
3. **Matching contra keywords.csv** si el proveedor es genérico.
|
||||
4. **Inferencia con IA** solo si no hubo coincidencias.
|
||||
5. **Validación fiscal básica** (RFC y régimen).
|
||||
6. **Cálculo de confianza** (reglas > IA).
|
||||
|
||||
El resultado es un gasto provisional, nunca definitivo.
|
||||
|
||||
---
|
||||
|
||||
### 2. The Auditor (Confirmación y Correcciones)
|
||||
|
||||
Se activa tras la respuesta del usuario.
|
||||
|
||||
Funciones:
|
||||
|
||||
* Confirmar registros sin cambios.
|
||||
* Aplicar correcciones explícitas.
|
||||
* Registrar trazabilidad completa.
|
||||
|
||||
Ejemplo de auditoría:
|
||||
|
||||
```
|
||||
AUDITORÍA: Usuario cambió monto de 150.00 a 180.00 (2025-01-14)
|
||||
```
|
||||
|
||||
Nada se sobrescribe silenciosamente.
|
||||
|
||||
---
|
||||
|
||||
## Tecnologías Utilizadas
|
||||
|
||||
* **Lenguaje:** Python 3.10+
|
||||
* **API Web:** FastAPI (webhook Telegram)
|
||||
* **Bot:** python-telegram-bot
|
||||
* **IA:** OpenAI API
|
||||
* **OCR / Parsing:** vía IA
|
||||
* **Almacenamiento:** Google Sheets (vía google-api-python-client)
|
||||
* **Datos locales:** CSV / JSON
|
||||
* **Validación:** Pydantic
|
||||
|
||||
---
|
||||
|
||||
## Estructura del Proyecto
|
||||
|
||||
```
|
||||
/expense-tracker-python
|
||||
│── .env
|
||||
│── requirements.txt
|
||||
│
|
||||
│── /config
|
||||
│ ├── user_config.json
|
||||
│ ├── providers.csv
|
||||
│ ├── keywords.csv
|
||||
│ └── google_credentials.json
|
||||
│
|
||||
│── /src
|
||||
│ ├── main.py # FastAPI + webhook Telegram
|
||||
│ ├── data_models.py # Modelos Pydantic
|
||||
│ │
|
||||
│ ├── /modules
|
||||
│ │ ├── ai_agents.py # Analyst & Auditor
|
||||
│ │ ├── config_loader.py # Carga y validación de CSV/JSON
|
||||
│ │ ├── input_handler.py # Texto, voz, imagen, PDF
|
||||
│ │ └── data_manager.py # Google Sheets / storage
|
||||
│ │
|
||||
│ └── /prompts
|
||||
│ ├── analyst_prompt.txt
|
||||
│ └── auditor_prompt.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Principios de Diseño
|
||||
|
||||
* Configuración > Código
|
||||
* Reglas explícitas > Inferencia probabilística
|
||||
* Confirmación humana obligatoria
|
||||
* Auditoría antes que automatismo ciego
|
||||
* IA como herramienta, no como autoridad
|
||||
|
||||
Este proyecto está diseñado para crecer hacia contabilidad automática, reportes fiscales y automatización financiera sin perder control humano.
|
||||
|
||||
Reference in New Issue
Block a user