feat: translate comments, docstrings, and log messages to Spanish.

README.md

@@ -1,81 +1,81 @@
-# Telegram Expenses Bot
+# Bot de Gastos de Telegram
 
-A modular, AI-powered bot to track and manage expenses via Telegram. It uses LLMs to extract structured data from text, images, and audio, and persists them for easy reporting.
+Un bot modular impulsado por IA para rastrear y gestionar gastos a través de Telegram. Utiliza LLMs para extraer datos estructurados de texto, imágenes y audio, y los persiste para facilitar la generación de informes.
 
-## Key Features
+## Características Clave
 
-- 🤖 **AI Extraction**: Automatically parses amount, currency, description, and date from natural language.
-- 🖼️ **Multimodal**: Supports text, images (receipts), and audio (voice notes) - *in progress*.
-- 📊 **Structured Storage**: Saves data to a database with support for exporting to CSV/Google Sheets.
-- 🛡️ **Audit Trail**: Keeps track of raw inputs and AI confidence scores for reliability.
-- 🐳 **Dockerized**: Easy deployment using Docker and Docker Compose.
+- 🤖 **Extracción por IA**: Analiza automáticamente el monto, la moneda, la descripción y la fecha a partir del lenguaje natural.
+- 🖼️ **Multimodal**: Soporta texto, imágenes (recibos) y audio (notas de voz) - *en progreso*.
+- 📊 **Almacenamiento Estructurado**: Guarda los datos en una base de datos con soporte para exportar a CSV/Google Sheets.
+- 🛡️ **Pista de Auditoría**: Realiza un seguimiento de las entradas sin procesar y las puntuaciones de confianza de la IA para mayor fiabilidad.
+- 🐳 **Dockerizado**: Despliegue sencillo utilizando Docker y Docker Compose.
 
-## Project Structure
+## Estructura del Proyecto
 
-The project has transitioned to a more robust, service-oriented architecture located in the `/app` directory.
+El proyecto ha transicionado a una arquitectura más robusta y orientada a servicios ubicada en el directorio `/app`.
 
-- **/app**: Core application logic.
-  - **/ai**: LLM integration, prompts, and extraction logic.
-  - **/audit**: Logging and raw data storage for traceability.
-  - **/ingestion**: Handlers for different input types (text, image, audio, document).
-  - **/integrations**: External services (e.g., exporters, webhook clients).
-  - **/modules**: Telegram bot command handlers (`/start`, `/status`, etc.).
-  - **/persistence**: Database models and repositories (SQLAlchemy).
-  - **/preprocessing**: Data cleaning, validation, and language detection.
-  - **/schema**: Pydantic models for data validation and API documentation.
-  - **main.py**: FastAPI entry point and webhook handlers.
-  - **router.py**: Orchestrates the processing pipeline.
-- **/config**: Static configuration files (keywords, providers).
-- **/src**: Legacy/Initial implementation (Phase 1 & 2).
-- **tasks.md**: Detailed project roadmap and progress tracker.
+- **/app**: Lógica central de la aplicación.
+  - **/ai**: Integración con LLM, prompts y lógica de extracción.
+  - **/audit**: Registro y almacenamiento de datos sin procesar para trazabilidad.
+  - **/ingestion**: Manejadores para diferentes tipos de entrada (texto, imagen, audio, documento).
+  - **/integrations**: Servicios externos (ej. exportadores, clientes de webhook).
+  - **/modules**: Manejadores de comandos del bot de Telegram (`/start`, `/status`, etc.).
+  - **/persistence**: Modelos de base de datos y repositorios (SQLAlchemy).
+  - **/preprocessing**: Limpieza de datos, validación y detección de idioma.
+  - **/schema**: Modelos Pydantic para validación de datos y documentación de la API.
+  - **main.py**: Punto de entrada de FastAPI y manejadores de webhooks.
+  - **router.py**: Orquesta el pipeline de procesamiento.
+- **/config**: Archivos de configuración estática (palabras clave, proveedores).
+- **/src**: Implementación heredada/inicial (Fases 1 y 2).
+- **tasks.md**: Hoja de ruta detallada del proyecto y seguidor de progreso.
 
-## How It Works (Workflow)
+## Cómo Funciona (Flujo de Trabajo)
 
-1.  **Input**: The user sends a message to the Telegram bot (text, image, or voice).
-2.  **Ingestion**: The bot receives the update and passes it to the `/app/ingestion` layer to extract raw text.
-3.  **Routing**: `router.py` takes the raw text and coordinates the next steps.
-4.  **Extraction**: The `/app/ai/extractor.py` uses OpenAI's GPT models to parse the text into a structured `ExtractedExpense`.
-5.  **Audit & Classify**: The `/app/ai/classifier.py` assigns categories and a confidence score.
-6.  **Persistence**: If confidence is high, the expense is automatically saved via `/app/persistence/repositories.py`. If low, it awaits manual confirmation.
+1.  **Entrada**: El usuario envía un mensaje al bot de Telegram (texto, imagen o voz).
+2.  **Ingestión**: El bot recibe la actualización y la pasa a la capa `/app/ingestion` para extraer el texto sin procesar.
+3.  **Enrutamiento**: `router.py` toma el texto sin procesar y coordina los siguientes pasos.
+4.  **Extracción**: `/app/ai/extractor.py` utiliza los modelos GPT de OpenAI para analizar el texto en un `ExtractedExpense` estructurado.
+5.  **Auditoría y Clasificación**: `/app/ai/classifier.py` asigna categorías y una puntuación de confianza.
+6.  **Persistencia**: Si la confianza es alta, el gasto se guarda automáticamente a través de `/app/persistence/repositories.py`. Si es baja, espera confirmación manual.
 
-## Project Status
+## Estado del Proyecto
 
-Current Phase: **Phase 3/4 - Intelligence & Processing**
+Fase Actual: **Fase 3/4 - Inteligencia y Procesamiento**
 
-- [x] **Phase 1: Infrastructure**: FastAPI, Docker, and basic input handling.
-- [x] **Phase 2: Data Models**: Explicit expense states and Pydantic schemas.
-- [/] **Phase 3: Logic**: Configuration loaders and provider matching (In Progress).
-- [/] **Phase 4: AI Analyst**: Multimodal extraction and confidence scoring (In Progress).
+- [x] **Fase 1: Infraestructura**: FastAPI, Docker y manejo básico de entradas.
+- [x] **Fase 2: Modelos de Datos**: Estados de gastos explícitos y esquemas Pydantic.
+- [x] **Fase 3: Lógica**: Cargadores de configuración y coincidencia de proveedores (Completado).
+- [/] **Fase 4: Analista de IA**: Extracción multimodal y puntuación de confianza (En Progreso).
 
-## Setup & Development
+## Configuración y Desarrollo
 
-### 1. Environment Variables
-Copy `.env.example` to `.env` and fill in your credentials:
+### 1. Variables de Entorno
+Copia `.env.example` a `.env` y completa tus credenciales:
 ```bash
-TELEGRAM_TOKEN=your_bot_token
-OPENAI_API_KEY=your_openai_key
-DATABASE_URL=mysql+pymysql://user:password@db:3306/expenses
+TELEGRAM_TOKEN=tu_token_de_bot
+OPENAI_API_KEY=tu_clave_de_openai
+DATABASE_URL=mysql+pymysql://usuario:contraseña@db:3306/expenses
 
-# MySQL specific (for Docker)
-MYSQL_ROOT_PASSWORD=root_password
+# Específico de MySQL (para Docker)
+MYSQL_ROOT_PASSWORD=contraseña_root
 MYSQL_DATABASE=expenses
-MYSQL_USER=user
-MYSQL_PASSWORD=password
+MYSQL_USER=usuario
+MYSQL_PASSWORD=contraseña
 ```
 
-### 2. Run with Docker
+### 2. Ejecutar con Docker
 ```bash
 docker-compose up --build
 ```
 
-### 3. Local Development (FastAPI)
+### 3. Desarrollo Local (FastAPI)
 ```bash
 pip install -r requirements.txt
 uvicorn app.main:app --reload
 ```
 
-### 4. Running the Bot (Polling)
-For local testing without webhooks, you can run a polling script that uses the handlers in `app/modules`.
+### 4. Ejecutar el Bot (Polling)
+Para pruebas locales sin webhooks, puedes ejecutar un script de polling que utilice los manejadores en `app/modules`.
 
 ---
-*Maintained by Marco Gallegos*
+*Mantenido por Marco Gallegos*