# 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](https://rustup.rs/) (Edición 2021, v1.75+)
* [Node.js](https://nodejs.org/) (v18+)
### Pasos
1. **Clonar el repositorio:**
```bash
git clone https://github.com/tu-usuario/bgustscraper.git
cd bgustscraper
```
2. **Instalar dependencias del Worker:**
```bash
cd worker
npm install
npx playwright install chromium
cd ..
```
3. **Compilar el proyecto:**
```bash
cargo build --release
```
---
## 🛠️ Modos de Uso
### 1. Modo Interactivo (CLI)
Ejecuta el binario interactivo para buscar fuentes y descargar documentos de forma asistida:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
docker build -t bgustscraper .
```
### Ejecutar el contenedor:
```bash
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/](./docs). Te invitamos a leer los módulos individuales para profundizar en el funcionamiento del CLI:
* **[Portal de Documentación Principal (TOC)](./docs/README.md)**
* **[Arquitectura Completa del Ecosistema](./docs/architecture.md)**
* **[Guía de Instalación y Primeros Pasos](./docs/installation.md)**
* **[Evaluación de Configuraciones e Intervenciones Manuales](./docs/manual_configuration.md)**
* **[Especificaciones de OpenAPI 3.0](./docs/openapi.md)**
* **[Daemon Planificador y Control de Agenda](./docs/scheduler.md)**
* **[Resultados del Benchmark de Recursos](./docs/benchmark.md)**
* **[Empaquetamiento y Distribución en Linux](./docs/cli_packaging.md)**
* **Métodos y Estrategias de Raspado:**
* [Método 1: Detección Sintáctica Estática](./docs/methods/syntactic.md)
* [Método 2: Deep Scan Interactivo (Playwright)](./docs/methods/deep_scan.md)
* [Método 3: Bypass TLS y Evasión (Cloudscraper)](./docs/methods/tls_bypass.md)
* [Método 4: Compresión Semántica y Clustering K-Means](./docs/methods/semantic_clustering.md)
* [Método 5: Extracción Estructurada con Modelos Locales ONNX](./docs/methods/semantic_extraction.md)
---
## 📜 Licencia y Créditos
Este proyecto se distribuye bajo la licencia MIT. Consulta el archivo [CREDITS.md](./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.