ExpenseWise: Agente Inteligente de Gestión de Gastos

Un agente inteligente desarrollado con LangGraph y Python que ayuda a gestionar gastos personales y proporciona recomendaciones financieras personalizadas.

🌟 Características

• Seguimiento de Gastos: Registra y categoriza automáticamente tus gastos diarios
• Análisis de Patrones: Identifica patrones de gasto y tendencias a lo largo del tiempo
• Recomendaciones Personalizadas: Recibe sugerencias para optimizar tu presupuesto
• Planificación Financiera: Establece metas de ahorro y recibe planes para alcanzarlas
• Interfaz Conversacional: Interactúa con el agente a través de lenguaje natural

🛠️ Tecnologías

• LangGraph: Framework para crear agentes con memoria y razonamiento
• Python: Lenguaje base de programación
• LangChain: Integración con modelos de lenguaje
• FastAPI (opcional): API para la interfaz web
• SQLite/PostgreSQL: Almacenamiento persistente de datos financieros

📋 Requisitos Previos

• Python 3.11 o superior
• Pip (gestor de paquetes de Python)
• Poetry Gestión y empaquetado de dependencias de Python simplificados
• Una clave API para el LLM seleccionado (OpenAI, Anthropic, etc.)

🚀 Instalación

1. Clona este repositorio:

git clone https://github.com/ecaminero/expense-wise.git
cd expense-wise

2. Instala las dependencias:

poetry install

3. Configura tus variables de entorno:

cp .env.example .env
# Edita el archivo .env con tu clave API y otras configuraciones

🔍 Estructura del Proyecto

expense-wise/
├── agents/                 # Definición de agentes
│   ├── .py                 
├── graph/                  # Flujos de trabajo en LangGraph
│   └── nodes.py            # Nodos funcionales del grafo
├── models/                 # Modelos de datos
│   ├── .py          
├── tools/                  # Herramientas del agente
│   ├── .py      
├── data/                   # Almacenamiento de datos
├── utils/                  # Utilidades varias
├── config.py               # Configuración general
├── app.py                  # Punto de entrada principal
└── README.md               # Este archivo

🧩 Componentes Principales

Agente de Gastos

El agente principal que coordina todas las funciones de gestión de gastos. Utiliza LangGraph para mantener un flujo de trabajo estructurado y una memoria persistente de las interacciones del usuario.

Grafo de Decisión

Un flujo de trabajo basado en grafos que define las transiciones entre diferentes estados:

• Ingreso de Gastos: Procesa y valida nuevos gastos
• Categorización: Asigna categorías automáticamente
• Análisis: Examina patrones y tendencias
• Recomendación: Genera sugerencias personalizadas

Herramientas Especializadas

Conjunto de funciones que el agente puede utilizar para realizar tareas específicas:

• Categorización automática de gastos
• Análisis de tendencias financieras
• Cálculo de presupuestos óptimos
• Generación de recomendaciones de ahorro

🔄 Flujo de Trabajo

1. Entrada del Usuario: El usuario proporciona información sobre sus gastos o hace una consulta
2. Procesamiento: El agente analiza la entrada y determina el siguiente paso en el grafo
3. Ejecución: Se ejecutan las herramientas necesarias según el estado actual
4. Memoria: Se actualiza la memoria del agente con nueva información
5. Respuesta: El agente proporciona información, análisis o recomendaciones

📝 Ejemplos de Uso

Registro de un Gasto

from expensewise import ExpenseAgent

agent = ExpenseAgent()
response = agent.run("Gasté 45.99€ en un restaurante ayer por la noche")
print(response)
# "He registrado tu gasto de 45.99€ en la categoría 'Restaurantes' con fecha 2023-03-12."

Análisis de Gastos

response = agent.run("¿Cuáles fueron mis mayores gastos este mes?")
print(response)
# "Tus mayores gastos este mes han sido: 
# 1. Alquiler: 850€
# 2. Supermercado: 320€
# 3. Restaurantes: 215€"

Obtener Recomendaciones

response = agent.run("Dame recomendaciones para ahorrar en alimentación")
print(response)
# "Basado en tus gastos, aquí tienes algunas recomendaciones para reducir gastos en alimentación:
# 1. Tus compras en supermercados de fin de semana son un 20% más caras. Considera hacer compras más grandes entre semana.
# 2. Has gastado 135€ en comida para llevar este mes. Podrías ahorrar preparando más comidas en casa.
# 3. Hay un patrón de compras impulsivas en pequeñas tiendas. Procura hacer una lista antes de comprar."

🧪 Tests

Para ejecutar las pruebas:

pytest

📊 Dashboard (En desarrollo)

Una interfaz web está en desarrollo para visualizar gastos, tendencias y recomendaciones de forma gráfica.

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor, sigue estos pasos:

1. Haz fork del repositorio
2. Crea una rama para tu característica (git checkout -b feature/nueva-caracteristica)
3. Haz commit de tus cambios (git commit -m 'Añadir nueva característica')
4. Sube tu rama (git push origin feature/nueva-caracteristica)
5. Abre un Pull Request

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

---

Desarrollado por Edwin