bgustscraper 🚀

Ingesta Robusta, Legal, Semántica y Segura para Ecosistemas de NLP y RAG.

bgustscraper es una herramienta de scraping y extracción estructurada de nivel empresarial diseñada para alimentar canales de datos RAG (Retrieval-Augmented Generation) de forma ética, eficiente y completamente autónoma. Integra un núcleo de IA local y telemetría avanzada para validar el cumplimiento legal, resumir semánticamente y servir información en formato seguro y estructurado.

🌟 Características Clave

Arquitectura Híbrida Multi-Motor (Rust + Node.js):
- Core (Rust): Gestión de concurrencia de alto rendimiento bajo el runtime asíncrono Tokio.
- Stealth Worker (Node.js/Playwright): Navegación dinámica con evasión de bloqueos (playwright-extra + plugins de stealth) y scroll inteligente.
- Motor Red de Respuesto (Cloudscraper): Bypass a nivel TLS para sortear firewalls estrictos.
IA y NLP 100% Local y Offline (Hugging Face ONNX):
- Representación Semántica: Generación local de embeddings con all-MiniLM-L6-v2 en CPU.
- Extracción de JSON Estructurado: Inferencia local con el modelo Qwen2.5-0.5B-Instruct cuantizado en Q4 (ONNX Runtime), logrando estructuración en JSON sin conexiones externas ni APIs de pago.
Compresión Extractiva por Clustering K-Means (linfa-clustering):
- Rust segmenta el Markdown de la página y vectoriza las oraciones.
- Aplica el algoritmo K-Means de la librería nativa de Machine Learning linfa.
- Filtra y selecciona las oraciones más cercanas a los centroides de cada cluster, comprimiendo textos masivos a resúmenes ultra-densos libres de redundancia antes de la inferencia.
Caché Transaccional Embebida (redb):
- Base de datos clave-valor embebida en Rust puro (downloads/cache.db).
- Evita consultas de red y cargas innecesarias de Playwright en URLs ya indexadas, reduciendo el tiempo de raspado en más de un 50% y la huella en memoria en ~23 GB.
Servidor Web HTTP API Seguro (Axum + JWT):
- Levanta un servidor web asíncrono de alto rendimiento usando Axum.
- Seguridad empresarial robusta protegida rigurosamente con JSON Web Tokens (JWT) (jsonwebtoken).
Daemon Planificador de Agenda (Scheduling):
- Controla ejecuciones en ventanas horarias asíncronas complejas (ej. capturar tasas del BCV de lunes a viernes, una vez AM y una vez PM).
- Mantiene estado en redb para tolerar reinicios del sistema sin duplicar ejecuciones.

🏗️ Arquitectura del Ecosistema

                         [ bgustscraper CLI ]
                                  │
      ┌───────────────────────────┴───────────────────────────┐
      ▼ (Modo Interactivo / CLI)                              ▼ (Modo Daemon / Server)
 [ Ingesta de Documentos ]                           [ Servidor Web API Seguro (Axum) ]
      │                                                       ├─ POST /api/auth (JWT Sign)
      ├─► Sintáctica (HTML tags)                              ├─ GET /api/bcv (Protected)
      └─► Semántica (Inferencia Qwen)                         └─ GET /api/cache (Protected)
              │                                                       ▲
              ▼                                                       │
  ┌───────────────────────────────────────────────────────────────────┴──┐
  │                   Base de Datos Embebida (redb)                      │
  │    - Caché Persistente local de páginas y embeddings                 │
  │    - Tabla de estado e historial de Daemon Scheduler                 │
  └──────────────────────────────────┬───────────────────────────────────┘
                                     ▼
                  ┌─────────────────────────────────────┐
                  │      Stealth Playwright Worker      │
                  │   - all-MiniLM-L6-v2 (Embeddings)   │
                  │   - Qwen2.5-0.5B ONNX Q4 (JSON)     │
                  └─────────────────────────────────────┘

🚀 Instalación y Requisitos

Requisitos Previos

Rust (Edición 2021, v1.75+)
Node.js (v18+)

Pasos

Clonar el repositorio:

git clone https://github.com/tu-usuario/bgustscraper.git
cd bgustscraper

Instalar dependencias del Worker:

cd worker
npm install
npx playwright install chromium
cd ..

Compilar el proyecto:
```
cargo build --release
```

🛠️ Modos de Uso

1. Modo Interactivo (CLI)

Ejecuta el binario interactivo para buscar fuentes y descargar documentos de forma asistida:

cargo run --release -p bgustscraper

2. Modo Extractor Semántico Genérico

Extrae cualquier estructura de datos en JSON a partir del Markdown de una página web usando prompts de lenguaje natural:

cargo run --release -p bgustscraper -- --extract "Extrae los precios de los productos y sus nombres" https://pagina-de-ejemplo.com

Los resultados se guardan en JSON estructurado en la carpeta downloads/.

3. Modo Daemon de Agenda + Servidor Web API Seguro

Arranca el programador asíncrono de tareas y levanta el servidor seguro de Axum en el puerto 8080 de forma desatendida:

cargo run --release -p bgustscraper -- --daemon

Endpoints de la API Segura:

POST /api/auth: Recibe { "username": "admin", "password": "bgust2026" } y retorna un token JWT firmado.
GET /api/bcv: Consulta protegida (Header Authorization: Bearer <token>) que devuelve la última captura de divisas del BCV.
GET /api/cache: Consulta protegida que devuelve los metadatos de estado del almacenamiento embebido redb.

4. Suite de Benchmark Integrada

Mide y compara de forma automatizada y científica la huella de tiempo, red, y memoria RAM física total sumada (Rust + Node + Playwright Chromium) en cada modalidad de scraping:

cargo run --release -p bgustscraper -- --benchmark

🐳 Despliegue Aislado con Docker

El proyecto incluye un Dockerfile optimizado para benchmarking y despliegue local de producción que pre-descarga y almacena en caché los modelos de Hugging Face en la imagen para ejecuciones 100% offline.

Construir la imagen:

docker build -t bgustscraper .

Ejecutar el contenedor:

docker run -p 8080:8080 bgustscraper

📖 Documentación Detallada (Estilo Docusaurus)

Hemos estructurado una documentación completa y modular del sistema en formato Docusaurus simplificado dentro de la carpeta docs/. Te invitamos a leer los módulos individuales para profundizar en el funcionamiento del CLI:

📜 Licencia y Créditos

Este proyecto se distribuye bajo la licencia MIT. Consulta el archivo CREDITS.md para ver la lista completa de atribuciones, licencias y créditos correspondientes a todas las librerías de terceros (Rust crates, Node.js packages) y modelos de IA locales utilizados para garantizar un uso 100% libre de infracciones.

bgustscraper 0.2.0