🤖 Universal RAG Assistant Engine

Motor de asistencia conversacional con arquitectura RAG (Retrieval-Augmented Generation) desacoplada, modular y lista para producción. Diseñado para adaptarse a cualquier dominio o empresa mediante configuración declarativa, con soporte de almacenamiento dual (Local JSON / Google Cloud Firestore) y doble interfaz de interacción (FastAPI REST y CLI enriquecido con Rich).

---

🏛️ Arquitectura del Sistema

El proyecto implementa principios de Clean Architecture e Inyección de Dependencias, separando estrictamente la lógica de dominio de los proveedores de LLM y motores de almacenamiento:

graph TD
    CLI["💻 Rich Interactive CLI"] --> Core["🧠 Assistant Core Engine"]
    API["⚡ FastAPI REST Endpoints"] --> Core
    
    subgraph Core ["Core Domain & Services"]
        Assistant["UniversalAssistant"]
        ContextBuilder["Context Retriever & Formatter"]
        Config["Pydantic Settings"]
    end
    
    Core --> StorageFactory["Knowledge Store Factory"]
    Core --> LLMFactory["LLM Provider Factory"]
    
    StorageFactory --> LocalStore["📁 LocalJSONKnowledgeStore<br/>(Zero-Config / Offline)"]
    StorageFactory --> FirestoreStore["☁️ FirestoreKnowledgeStore<br/>(Google Cloud)"]
    
    LLMFactory --> GeminiClient["✨ Google Gemini API<br/>(1.5-Flash / Pro)"]
    LLMFactory --> MockClient["🧪 MockLLMClient<br/>(Hermetic CI / Testing)"]

Loading

---

✨ Características Principales

• 🔄 Desacoplamiento Total de Dominio: Configurable para clínicas veterinarias, e-commerce, soporte técnico o mesas de ayuda cambiando únicamente un archivo JSON y variables de entorno.
• 🚀 Almacenamiento Dual:
  • Modo Local (Default): Motor de búsqueda léxica y por relevancia en memoria sin dependencias externas ni costes cloud.
  • Modo Firestore: Conexión escalable con Google Cloud Firestore para entornos productivos.
• 🤖 Proveedores LLM Flexibles:
  • Google Gemini: Integración con modelos de última generación (gemini-1.5-flash).
  • Mock LLM Provider: Simulación offline determinista para pruebas unitarias herméticas y pipelines de CI/CD con coste cero.
• ⚡ Doble Interfaz de Presentación:
  • FastAPI REST API: Documentación interactiva OpenAPI/Swagger (/docs), chequeos de salud (/health) y métricas de latencia.
  • Terminal CLI con Rich: Renderizado con Markdown dinámico, tablas, spinners y comandos interactivos.
• 🐳 Contenedorización y DevOps: Dockerfile multi-stage seguro (non-root) y docker-compose.yml listos para desplegar.
• 🧪 Testing y CI Automatizado: Suite de pruebas con pytest y pipeline de GitHub Actions integrado.

---

🚀 Inicio Rápido

1. Clonar el Repositorio

git clone https://github.com/Pacoaldev/Universal-RAG-assistant-engine.git
cd Universal-RAG-assistant-engine

2. Crear Entorno Virtual e Instalar Dependencias

python -m venv venv

# Windows
.\venv\Scripts\activate
# Linux / macOS
source venv/bin/activate

pip install -r requirements.txt

3. Configurar Variables de Entorno

Copia la plantilla de entorno:

cp .env.example .env

Edita .env con tu clave de Gemini:

GOOGLE_API_KEY=tu_api_key_aqui
LLM_PROVIDER=gemini
STORAGE_TYPE=local

(Nota: Para probarlo inmediatamente sin API key, define LLM_PROVIDER=mock).

---

💻 Modos de Ejecución

Opción A: Interfaz CLI Enriquecida

Inicia el asistente en la consola con renderizado Markdown y soporte interactivo:

python -m src.cli.main
# O directamente:
python chatbot.py

Opción B: Servidor API REST (FastAPI)

Inicia el servidor uvicorn:

python -m src.api.app

Accede a la documentación interactiva en el navegador:

• Swagger UI: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Ejemplo de consulta HTTP:

curl -X POST "http://localhost:8000/api/chat" \
     -H "Content-Type: application/json" \
     -d '{"query": "¿Cuáles son los horarios de atención y qué vacunas ofrecen?"}'

---

🐳 Ejecución con Docker

Levanta el servicio completo en un contenedor aislado con un solo comando:

docker-compose up --build

---

🎯 Adaptar a Cualquier Dominio (Universalidad)

Para adaptar el asistente a un nuevo negocio o contexto (por ejemplo, una tienda de tecnología):

1. Edita o reemplaza la base de datos de conocimiento (knowledge_base.json):

   {
     "productos": [
       {"id": "laptop-01", "nombre": "MacBook Air", "precio": "1199€", "stock": 5}
     ],
     "politicas": [
       {"tema": "envios", "detalle": "Envíos gratuitos en 24h a toda la península."}
     ]
   }

2. Ajusta las variables de entorno en .env:

   ASSISTANT_NAME="TechBot"
   ORGANIZATION_NAME="TechStore"
   KNOWLEDGE_BASE_PATH="knowledge_base.json"

---

🧪 Pruebas y Calidad de Código

Ejecuta la suite de pruebas unitarias herméticas (100% independientes de credenciales externas):

# Ejecutar tests
python -m pytest tests/ -v

# Validar linting y formato
ruff check .

---

📂 Estructura del Proyecto

├── .github/workflows/ci.yml    # Pipeline CI de GitHub Actions
├── src/
│   ├── api/app.py              # Endpoints FastAPI y schemas Pydantic
│   ├── cli/main.py             # CLI interactivo con Rich
│   ├── core/
│   │   ├── assistant.py        # Motor RAG desacoplado
│   │   └── config.py           # Configuración tipada con Pydantic Settings
│   ├── llm/                    # Adaptadores LLM (Gemini, Mock, Factory)
│   └── storage/                # Adaptadores de datos (Local JSON, Firestore, Factory)
├── tests/                      # Suite de pruebas unitarias
├── Dockerfile                  # Dockerfile multi-stage de producción
├── docker-compose.yml          # Orquestación de contenedores
├── pyproject.toml              # Definición moderna del paquete Python
├── requirements.txt            # Dependencias fijadas
└── maskotas_knowledge_base.json # Base de conocimientos por defecto (Veterinaria)

---

📄 Licencia

MIT — Copyright (c) 2026 Pacoaldev

---

👤 Autor

Paco López Alarte

• GitHub: @Pacoaldev | Email: [email protected]