FacturaGPT: Sistema Avanzado de Q&A sobre Facturas

FacturaGPT es un sistema de IA diseñado para responder preguntas complejas sobre un conjunto de documentos PDF (en este caso, facturas). A diferencia de un sistema de búsqueda simple, utiliza una arquitectura de Agente Inteligente para comprender, planificar y sintetizar información de múltiples fuentes para dar respuestas precisas.

El proyecto está completamente encapsulado en Docker, garantizando una instalación y ejecución sencillas y reproducibles con un solo comando.

Características Principales

• Procesamiento Inteligente de PDFs: Utiliza unstructured para analizar la estructura de los PDFs, extrayendo tablas como HTML y agrupando la información de manera coherente.
• Arquitectura de Agente: En lugar de una simple búsqueda, el sistema planifica cómo responder a preguntas complejas, dividiéndolas en sub-preguntas más sencillas.
• Búsqueda Híbrida: Combina la búsqueda semántica (para encontrar conceptos relevantes) con el filtrado por metadatos (para acotar la búsqueda a ficheros específicos), logrando una alta precisión.
• Capacidad de Síntesis y Cálculo: Puede comparar datos entre diferentes documentos, realizar cálculos y generar una respuesta final coherente.
• API Robusta: Construido con FastAPI, ofrece un endpoint para las preguntas y una documentación interactiva autogenerada.
• 100% Dockerizado: Sin complicadas instalaciones locales. Si tienes Docker, puedes ejecutarlo.

Arquitectura y Flujo de Datos

El sistema funciona en dos fases: una ingesta inicial de los documentos y una fase de pregunta-respuesta en tiempo real.

graph TD
    subgraph "Fase de Ingesta (Offline)"
        A["<fa:fa-file-pdf> Facturas en PDF"]
        B["scripts/ingest.py"]
        C["Chunks de Texto/HTML"]
        D[("<fa:fa-database> ChromaDB")]

        A --> B
        B --> C
        C --> D
    end

    subgraph "Fase de Pregunta-Respuesta (Online)"
        E["<fa:fa-user> Usuario"]
        F["<fa:fa-server> FastAPI / Agente"]
        G["<fa:fa-brain> Gemini Planner"]
        H["<fa:fa-brain> Gemini Synthesizer"]

        E --> F
        F --> G
        G --> F
        F --> D
        D --> F
        F --> H
        H --> F
        F --> E
    end

Loading

Stack Tecnológico

• Backend: Python 3.12, FastAPI
• IA & LLMs: Google Gemini 1.5 Flash
• Procesamiento de Documentos: Unstructured
• Base de Datos Vectorial: ChromaDB
• Contenerización: Docker & Docker Compose

Cómo Ejecutar el Proyecto

Prerrequisitos

• Tener instalado Docker y Docker Compose.

Pasos de Instalación

1. Clonar el repositorio

   git clone <URL_DEL_REPOSITORIO>
   cd <NOMBRE_DEL_DIRECTORIO>

2. Configurar las variables de entorno Crea un fichero llamado .env en la raíz del proyecto. Puedes copiar el ejemplo:

   cp .env.example .env

   Abre el fichero .env y añade tu clave de la API de Google:

   GOOGLE_API_KEY="AIzaSy...tu...clave...aqui"

3. Colocar las facturas Asegúrate de que los ficheros PDF que quieres consultar están dentro del directorio dataset/.

4. Construir y ejecutar con Docker Este comando construirá la imagen de Docker, descargará las dependencias, procesará los PDFs en dataset/ y arrancará la API.

   docker compose up --build

   La primera vez puede tardar varios minutos mientras se descargan los modelos de unstructured. Las siguientes veces será mucho más rápido.

   Si todo ha ido bien, verás un mensaje indicando que el servidor Uvicorn está corriendo en http://0.0.0.0:8000.

Uso de la API

La API está disponible en http://localhost:8000.

1. Endpoint /ask

Puedes enviar preguntas al sistema haciendo una petición POST a /ask.

Ejemplo con curl:

curl -X 'POST' \
  'http://localhost:8000/ask' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "Compara la factura de Enero de 2024 con la de Julio de 2025. ¿En cuál de las dos se pagó un importe mayor por el concepto Impuestos y cuál fue la diferencia exacta en euros entre ambas?"
}'

2. Documentación Interactiva (Swagger UI)

Para probar la API de forma más cómoda, abre tu navegador y ve a: http://localhost:8000/docs

Encontrarás una interfaz interactiva donde podrás probar los endpoints directamente.