egutierrez
9042110ea2
Cinco issues que componen el plan: - 0026: sistema de jobs (infra, contrato wire) - 0027: tipo Webpage + cache de documentos - 0028: enricher fetch_webpage (MVP end-to-end) - 0028b: enrichers extract_domain / extract_links / extract_text_entities - 0029: variantes CDP (Chrome headless, screenshot) - 0030: macro "Deep enrich" + expand_domain Tambien anade los issues previos 0012-0025 que estaban untracked. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
---
|
|
id: 0028
|
|
title: Enricher fetch_webpage (MVP end-to-end)
|
|
status: pending
|
|
priority: high
|
|
created: 2026-05-01
|
|
depends_on: [0026, 0027]
|
|
---
|
|
|
|
## Objetivo
|
|
|
|
Primer enricher real sobre el sistema de jobs (0026). Right-click sobre
|
|
un nodo `Url` o `Webpage` → "Fetch web page". Descarga el HTML, lo
|
|
convierte a markdown, guarda los blobs en cache, actualiza el nodo
|
|
(o lo convierte a Webpage si era Url) y crea el nodo `Domain` con
|
|
relacion `BELONGS_TO`.
|
|
|
|
Este enricher valida el contrato entero. Los siguientes (0028b) reusan
|
|
exactamente el mismo wire protocol.
|
|
|
|
## Archivos
|
|
|
|
```
|
|
apps/graph_explorer/enrichers/fetch_webpage/
|
|
manifest.yaml
|
|
run.py
|
|
```
|
|
|
|
## `manifest.yaml`
|
|
|
|
```yaml
|
|
id: fetch_webpage
|
|
name: "Fetch web page"
|
|
description: "Descarga HTML, extrae markdown limpio y guarda en cache."
|
|
applies_to: [Webpage, Url]
|
|
emits: [Domain]
|
|
relations: [BELONGS_TO]
|
|
params:
|
|
- { name: timeout_s, type: int, default: 15 }
|
|
```
|
|
|
|
## `run.py`
|
|
|
|
Logica:
|
|
1. Lee JSON de stdin.
|
|
2. Saca `url` de `metadata.url` (o `metadata.address` si es Url legacy).
|
|
3. `PROGRESS:0.05 normalize` — `normalize_url_py_cybersecurity`.
|
|
4. `PROGRESS:0.20 fetching` — descarga via `requests.get(url, timeout=N)`.
|
|
5. `PROGRESS:0.60 parsing` — `html_to_markdown_py_core` con readabilipy.
|
|
6. `PROGRESS:0.85 writing` — calcula sha256(url), escribe `cache/<sha[0:2]>/<sha>.html` y `.md`.
|
|
7. Emite stdout JSON:
|
|
- `node_updates`: cambia type a Webpage si era Url, anade title/status_code/content_type/fetched_at/html_path/markdown_path/text_length.
|
|
- `entities`: `{type: Domain, name: <dominio>, metadata: {}}`.
|
|
- `relations`: `from_id: <node_id>, to_name: <dominio>, to_type: Domain, kind: BELONGS_TO`.
|
|
|
|
## Funciones del registry usadas
|
|
|
|
- `normalize_url_py_cybersecurity` — limpia tracking params.
|
|
- `html_to_markdown_py_core` — readabilipy + markdownify.
|
|
- `extract_domain` se hace inline en el enricher (regex trivial sobre la URL parseada).
|
|
|
|
## Manejo de errores
|
|
|
|
- HTTP error (4xx/5xx) → escribe status_code en metadata pero NO marca el job como error (el nodo guarda evidencia del fallo).
|
|
- Timeout / DNS error / etc → exit con error JSON en stdout: `{"error": "...", "node_updates": [], "entities": [], "relations": []}`.
|
|
- Si el enricher levanta excepcion, sale con codigo != 0 y stderr capturado va a `jobs.error`.
|
|
|
|
## Definicion de hecho
|
|
|
|
- Crear nodo Url con `https://example.com` → click derecho → "Fetch web page".
|
|
- En segundos aparece en panel Jobs como `running` con progress.
|
|
- Al terminar:
|
|
- El nodo cambia a tipo `Webpage` con icono `ti-file-text`.
|
|
- El inspector muestra title, status_code, html_path, markdown_path.
|
|
- Aparece nodo `Domain` "example.com" conectado por `BELONGS_TO`.
|
|
- El archivo `cache/<sha>.md` existe en disco.
|
|
- El job aparece en panel Jobs como `done` con `entities_added=1, relations_added=1`.
|
|
- Tirar la red (sin internet) → el job acaba en `error` con mensaje claro.
|