Expense Tracker Agent 💰

Agente conversacional con Google ADK para gestionar gastos e ingresos. Analiza fotos de tickets/facturas y registra automáticamente en Google Sheets.

Características

• 📸 Análisis de imágenes: Envía una foto de un ticket y el agente extrae fecha, importe, tipo y categoría
• 💬 Registro manual: Dicta tus gastos/ingresos por texto
• 📊 Integración con Google Sheets: Todos los registros se guardan automáticamente
• 🏷️ Categorización automática: El agente clasifica en sectores (Alimentación, Transporte, Salud, etc.)

Estructura del Proyecto

expense_tracker/
├── __init__.py
├── agent.py              # Definición del agente principal
└── tools/
    ├── __init__.py
    └── google_sheets.py  # Herramienta para Google Sheets

Configuración

1. Instalar dependencias

pip install -r requirements.txt

2. Configurar Google AI API Key

Obtén tu API Key de Google AI Studio y configúrala:

export GOOGLE_API_KEY="tu_api_key"

3. Configurar Google Sheets

Paso 1: Crear credenciales de Service Account

1. Ve a Google Cloud Console
2. Crea un nuevo proyecto o selecciona uno existente
3. Habilita la Google Sheets API y Google Drive API
4. Ve a Credenciales → Crear credenciales → Cuenta de servicio
5. Descarga el archivo JSON de credenciales
6. Guárdalo como credentials.json en la raíz del proyecto

Paso 2: Compartir el Spreadsheet

1. Abre tu Google Sheet
2. Copia el email de la cuenta de servicio (está en el JSON, campo client_email)
3. Comparte el documento con ese email (permisos de Editor)

Paso 3: Configurar el Spreadsheet

Asegúrate de que tu Google Sheet tenga esta estructura en la primera fila (cabeceras):

Fecha	Tipo	Importe	Sector	Descripción

4. Variables de entorno

Copia el archivo de ejemplo y configura tus valores:

cp .env.example .env

Edita .env con tus configuraciones:

GOOGLE_API_KEY=tu_api_key
GOOGLE_SPREADSHEET_ID=tu_spreadsheet_id
GOOGLE_APPLICATION_CREDENTIALS=credentials.json

Uso

Ejecutar con ADK Web UI

adk web expense_tracker

Esto abrirá una interfaz web donde puedes:

• Enviar mensajes de texto
• Subir imágenes de tickets/facturas
• Ver el historial de conversación

Ejemplos de uso

Enviar una foto de un ticket:

El agente analizará la imagen y extraerá los datos automáticamente

Registro manual:

"Gasté 45€ en el gimnasio ayer"

Consultar transacciones:

"¿Cuáles son mis últimos gastos?"

Sectores disponibles

• 🍕 Alimentación: Supermercado, restaurantes, delivery
• 🚗 Transporte: Gasolina, transporte público, taxi
• 🏥 Salud: Farmacia, médico, gimnasio
• 🏠 Hogar: Alquiler, luz, agua, internet
• 🎬 Ocio: Cine, viajes, suscripciones
• 👕 Ropa: Tiendas de ropa, calzado
• 💻 Tecnología: Electrónica, software
• 📚 Educación: Cursos, libros
• 💼 Nómina: Salario
• 🔧 Freelance: Ingresos independientes
• ❓ Otros: Todo lo demás

Configurar tu Google Sheet

Configura tu propio spreadsheet en .env con la variable GOOGLE_SPREADSHEET_ID. El ID lo encuentras en la URL del documento:

https://docs.google.com/spreadsheets/d/TU_SPREADSHEET_ID/edit