Avril RAG

Pipeline RAG para detectar noticias y señales sobre negocios agénticos, convertirlas en ideas estructuradas y guardarlas en Supabase para revisión humana. Incluye una API FastAPI para el consumo de las ideas (frontend público + integración con el sistema Launch).

Qué hace

• Recolecta noticias desde fuentes externas con Scrapy (paralelo).
• Normaliza cada fuente al mismo esquema de noticia.
• Evalúa y destila las noticias con un LLM para producir ideas de negocio agénticas.
• Valida la salida contra un contrato Pydantic (ContratoEmpresaAgentica).
• Genera un documento de identidad empresarial en Markdown para cada idea viable.
• Inserta las ideas en Supabase (PostgreSQL + pgvector) con deduplicación por hash de URL.
• Mantiene el estado de cada idea como borrador, revisada o publicada.
• Expone una API REST (FastAPI) con endpoints públicos y protegidos (JWT RS256).

Estructura del proyecto

├── main.py                        # Orquestador del pipeline (scraping paralelo + destilación)
├── src/
│   ├── llm/
│   │   ├── llm_config.py          # Configuración modular del LLM (NVIDIA/OpenAI/Gemini/Groq)
│   │   └── distilador.py          # Evaluación, destilación y documento de identidad
│   ├── prompts/                   # Prompts del sistema (evaluación, destilación, identidad)
│   ├── contracts/models.py        # Contrato Pydantic de salida (Inf-RAG-000)
│   ├── embeddings/nvidia_embedder.py  # Embeddings semánticos modulares
│   ├── vectordb/
│   │   ├── client.py              # Inserción y conteo de ideas en Supabase
│   │   └── setup.py               # Creación de la tabla ideas_negocio
│   ├── retrieval/retriever.py     # Búsqueda por similitud (pgvector)
│   ├── ingestion/scrapers/        # Proyecto Scrapy con 4 spiders
│   ├── api/                       # API FastAPI (server, database, security, schemas, routers)
│   └── utils/                     # Utilidades de operación (monitoreo, vault)
├── data/urls_fuentes.json         # Banco de URLs base para el spider genérico
├── docs/                          # Documentación técnica y de integración
├── deploy/                        # systemd (timer + service)
└── tests/                         # Scripts de verificación de configuración

Spiders

1. Hacker News — API Algolia Search, filtrado por keywords (agentic, ai agent, autonomous agent).
2. TechCrunch — RSS feed oficial de la categoría AI.
3. Product Hunt — API GraphQL oficial, lanzamientos recientes (requiere PRODUCTHUNT_TOKEN).
4. Generic — link discovery sobre 24 URLs de blogs de VCs y frameworks AI.

Total: 27 URLs configuradas en data/urls_fuentes.json.

Requisitos

• Python 3.12 o superior.
• Una cuenta de Supabase (PostgreSQL + pgvector).
• Una API key de LLM según el proveedor elegido (LLM_PROVIDER).
• (Opcional) Docker y Docker Compose para despliegue con contenedores.

Ejecución local (desarrollo)

1. Instalación

# Clonar el repositorio
git clone <url-del-repositorio>
cd rag_avril

# Crear y activar el entorno virtual
python3 -m venv .venv
source .venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt

2. Configuración

# Crear el archivo .env a partir del ejemplo
cp .env.example .env

# Editar .env con tus credenciales (editor a tu elección)
nano .env

Variables mínimas obligatorias en .env:

• LLM_PROVIDER + la API key del proveedor correspondiente (GOOGLE_API_KEY, NVIDIA_API_KEY, etc.).
• LLM_MODEL
• EMBEDDINGS_PROVIDER + modelo + dimensiones.
• SUPABASE_URL, SUPABASE_KEY, SUPABASE_CONN

3. Crear la tabla en Supabase

python3 src/vectordb/setup.py

4. Ejecutar

# Pipeline completo (scraping paralelo automático)
python3 main.py

# Pipeline con límite de noticias (testing)
python3 main.py --limite 5

# Spiders individuales (desarrollo)
scrapy crawl hackernews
scrapy crawl techcrunch
scrapy crawl producthunt
scrapy crawl generic -a urls_file=data/urls_fuentes.json

# API FastAPI (http://localhost:8000)
uvicorn src.api.server:app --host 0.0.0.0 --port 8000

Ejecución en VPS (producción)

Opción A: con Docker (recomendado)

# Clonar el repositorio en el servidor
git clone <url-del-repositorio>
cd rag_avril

# Crear y completar el archivo .env
cp .env.example .env
nano .env

# Construir e iniciar el contenedor de la API
docker compose up -d --build

# Ver logs
docker compose logs -f

# Detener
docker compose down

La API quedará disponible en http://<ip-del-vps>:8000. Para ejecutar el pipeline dentro del contenedor:

docker compose exec avril-api python3 main.py

Opción B: sin Docker

# Instalar Python 3.12+ si no está disponible
sudo apt update && sudo apt install -y python3.12 python3.12-venv git

# Clonar y preparar el proyecto
git clone <url-del-repositorio>
cd rag_avril

# Entorno virtual y dependencias
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Configurar credenciales
cp .env.example .env
nano .env

# Crear la tabla en Supabase
python3 src/vectordb/setup.py

# Ejecutar la API en segundo plano
nohup uvicorn src.api.server:app --host 0.0.0.0 --port 8000 > api.log 2>&1 &

Si el VPS tiene firewall activo (ej. ufw), expón el puerto de la API:

sudo ufw allow 8000/tcp

Endpoints públicos

• GET /api/blueprints/random — 3 ideas aleatorias publicadas formateadas como tarjetas.
• GET /api/blueprints/{uuid}/documento_identidad — documento de identidad de una idea publicada.

Endpoints internos (protegidos con JWT RS256)

• GET /api/blueprints/{uuid}/contrato — reserva la idea y devuelve su contrato completo.
• PATCH /api/blueprints/{uuid}/status — actualiza el estado de una idea.

Para la integración con el sistema Launch ver docs/INTEGRACION_LAUNCH.md.

Salidas del proceso

• data/noticias.json — salida del scraping (ignorada por git).
• data/ideas_borrador.json — ideas validadas antes de Supabase (ignorada por git).
• documentos_identidad/ — documentos de identidad en Markdown por idea (ignorada por git).

Ejecución automática (systemd)

En producción sin Docker, el pipeline se ejecuta cada viernes a las 11:00 (UTC) mediante un timer de systemd. El servicio espera el código en /srv/avril (según deploy/avril-rag.service); si usas otra ruta, edítala antes de copiar los archivos:

sudo cp deploy/avril-rag.service deploy/avril-rag.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable avril-rag.timer
sudo systemctl start avril-rag.timer

# Verificar estado y próxima ejecución
systemctl status avril-rag.timer
systemctl list-timers avril-rag.timer

Logs:

sudo journalctl -u avril-rag.service -f

Documentación

• docs/Documentacion.md — arquitectura completa del sistema.
• docs/INTEGRACION_LAUNCH.md — guía de integración con el sistema Launch.