bgustscraper 0.2.0

Advanced semantic scraping engine with AI-driven compliance checks and legal terms validation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

# Evaluaciones y Configuraciones Manuales 🛠️📋

Aunque `bgustscraper` está diseñado para operar de la manera más automatizada y resiliente posible, existen ciertos aspectos y dependencias que requieren **configuración, instalación o intervención manual** para garantizar su puesta en marcha y funcionamiento correcto en entornos locales o servidores dedicados.

---

## 🔑 1. Variables de Entorno (`.env`)

En producción o desarrollo local, es **mandatorio** crear un archivo `.env` en la raíz del directorio de `bgustscraper`. Si no se crea, el servidor web utilizará valores por defecto no seguros.

### Estructura del `.env`:
```env
# Clave secreta criptográfica (¡Cambiar en producción!)
# Se usa para la firma HS256 de los Tokens JWT de acceso a la API
JWT_SECRET=bgustscraper_super_secret_key_123_change_me!

# Credenciales de administración para el endpoint de login POST /api/auth
API_USER=admin
API_PASS=bgust2026

# Puerto en el cual el servidor web seguro Axum escuchará las peticiones
PORT=8080

# (Opcional) Sobrescribir el directorio por defecto de caché de Hugging Face
# HF_HOME=/app/models/.cache
```

---

## ⏰ 2. Configuración de Agenda (`config/schedule.json`)

El Daemon programador asíncrono lee de forma estricta el fichero JSON `config/schedule.json`. Este archivo debe ser estructurado o modificado manualmente según las necesidades de scraping programado de la organización.

### Formato Detallado:
```json
{
  "jobs": [
    {
      "name": "bcv_exchange_rate",
      "url": "https://www.bcv.org.ve/",
      "days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
      "windows": [
        { "name": "AM", "start": "09:00", "end": "12:59" },
        { "name": "PM", "start": "13:00", "end": "18:00" }
      ],
      "extract_prompt": "Extrae el valor del Dólar (USD) y del Euro (EUR) y la fecha de vigencia oficial.",
      "output_path": "downloads/bcv_rates.json"
    }
  ]
}
```

### Reglas de Configuración Manual:
1. **`days`:** Lista de días abreviados (`"Mon"`, `"Tue"`, `"Wed"`, `"Thu"`, `"Fri"`, `"Sat"`, `"Sun"`). Sensible a mayúsculas.
2. **`windows`:**
   * Las horas deben estar en formato de **24 horas HH:MM** (ej: `"09:00"`, `"13:00"`).
   * La hora de fin (`end`) debe ser estrictamente posterior a la de inicio (`start`).
   * No deben solaparse ventanas horarias para una misma tarea.
3. **`output_path`:** Directorio de destino físico. `bgustscraper` creará las carpetas intermedias de forma automática si no existen.

---

## 🧠 3. Descarga y Caché de Modelos ONNX (Puesta a Punto Offline)

El scraping semántico estructurado utiliza dos modelos de Hugging Face. Por defecto, en la primera ejecución, la biblioteca `@huggingface/transformers` intentará conectarse a Internet para descargar los pesos. 

Si planeas desplegar el CLI en un entorno **totalmente aislado/offline**, debes pre-cargar los modelos manualmente:
1. **Ejecuta una inferencia inicial con internet:**
   ```bash
   cargo run --release -p bgustscraper -- "https://example.com" --extract "Extrae el título"
   ```
2. Esto descargará los modelos y los guardará en tu directorio home:
   * Ruta en Linux: `~/.cache/huggingface/hub/`
3. Copia esta carpeta de caché al host o contenedor final, y define la variable de entorno `HF_HOME` apuntando a esa ruta.

---

## 🖥️ 4. Dependencias Binarias (Playwright y Node.js)

`bgustscraper` depende de que **Node.js** (v18+) esté instalado en el sistema operativo del host. Adicionalmente, requiere la descarga de los binarios de navegación de Chromium:

1. **Instalación Manual de Paquetes en `worker/`:**
   ```bash
   cd worker
   npm install
   ```
2. **Instalación Manual de Chromium:**
   ```bash
   npx playwright install chromium
   ```
   *Nota: Si estás en un servidor Linux headless sin entorno gráfico (X11/Wayland), es probable que debas instalar dependencias adicionales de sistema para Chromium ejecutando `npx playwright install-deps`.*

---

## 📦 5. Inicialización de Base de Datos y Permisos de Escritura

El scraper persiste el histórico de capturas, marcas de ejecución del scheduler y metadatos en una base de datos local **`redb`** en `downloads/cache.db`.
* **Permisos:** El usuario de sistema que ejecute el CLI (`bgustscraper`) debe poseer permisos de lectura y escritura físicos en la carpeta de despliegue (`downloads/`).
* Si el Daemon no logra inicializar `cache.db` debido a restricciones de permisos del sistema de archivos, abortará inmediatamente con un error de persistencia.