# worstscan — Manga Translation Pipeline

Pipeline de traducción automática de manga (JP/EN/KR/CN → ES) con bot de Telegram, API REST, y delivery a Kindle vía Nextcloud. Descarga de nhentai/e-hentai, traduce con LLM via proxy OpenAI-compatible, inpinta globos con modelos de visión, renderiza texto, empaqueta en MOBI con KCC y sube a Nextcloud.

---

## Arquitectura General

```
                    ┌──────────────────────────────────────────────────────┐
                    │                  Entry Points                         │
                    │  bot_artifacts.py  │  artifacts.py  │  cli.py         │
                    └────────┬──────────┴───────┬──────────┴───────┬────────┘
                             │                  │                  │
                    ┌────────▼──────────────────▼──────────────────▼────────┐
                    │              Queues & State                            │
                    │  UrlQueue (JSON)    GalleryQueue (JSON)    StateDB    │
                    │  data/bot_queue.json data/modal_queue/     SQLite     │
                    └────────────────────────┬──────────────────────────────┘
                                             │
                    ┌────────────────────────▼──────────────────────────────┐
                    │              Translation Pipeline                      │
                    │  ┌──────┐  ┌──────────┐  ┌──────┐  ┌────────┐  ┐     │
                    │  │DL    │→ │Preprocess│→ │Refine│→ │Inpaint │→ │     │
                    │  │.cbz  │  │detect/   │  │LLM   │  │AOT/   │  │     │
                    │  │      │  │OCR/trans │  │polish│  │lama   │  │     │
                    │  └──────┘  └──────────┘  └──────┘  └────────┘  │     │
                    │  ┌────────────────────────┐  ┌──────────┐  ┐  │     │
                    │  │Complete (V14 Render)   │→ │KCC→MOBI  │→ │  │     │
                    │  │PIL+textbbox typesetting│  │KPW34     │  │  │     │
                    │  └────────────────────────┘  └──────────┘  ┘  │     │
                    └────────────────────────┬──────────────────────────────┘
                                             │
                    ┌────────────────────────▼──────────────────────────────┐
                    │                 Delivery                               │
                    │  Nextcloud (sudo cp + occ files:scan)                  │
                    │  Local (shutil.copy2 to output/)                        │
                    └────────────────────────┬──────────────────────────────┘
                                             │
                    ┌────────────────────────▼──────────────────────────────┐
                    │              API REST (FastAPI)                        │
                    │  GET /health | /status | POST /galleries | /search    │
                    │  /summary | /cover | X-API-Key auth. Puerto 8080.    │
                    │  Swagger en /docs. Puerto 8080.                      │
                    └───────────────────────────────────────────────────────┘
```

---

## Entry Points (Completo)

| File | Rol | Cómo ejecutar | Producción |
|------|-----|---------------|------------|
| **`bot_artifacts.py`** | **Bot Telegram + API REST + Feed diario** | `uv run python3 bot_artifacts.py` (systemd `bot-artifacts.service`) | ✅ |
| **`artifacts.py`** | **Pipeline completa** (download → translate → inpaint → render → MOBI) | `python artifacts.py [--skip-mobi] [--no-es-search] <url>` | ✅ |
| **`cli.py`** | **CLI tool** (11 subcomandos) | `python cli.py <subcommand> [args]` | ✅ |
| `inject_gallery.py` | Inyección directa al pipeline | `python inject_gallery.py <URL1> <URL2> ...` | ❌ aux |
| `process.py` | Pipeline anterior (718 lines, coexiste) | — | ❌ legacy |
| `bot.py` | Bot Telegram legacy (26KB, 749 lines) | `python -m src.bot` | ❌ legacy |
| `visual_feedback.py` | Bucle de feedback visual LLM | — | ❌ standalone |
| `_render_all.py` | Render interno variante | — | ❌ exp |
| `_render_gallery.py` | Render interno | — | ❌ exp |
| `_render_no_stroke.py` | Render sin stroke | — | ❌ exp |
| `_render_variants.py` | Variantes de render | — | ❌ exp |
| `_smart_render.py` | Smart render v1 | — | ❌ exp |
| `_smart_render_v2.py` | Smart render v2 | — | ❌ exp |
| `_smart_render_v3.py` | Smart render v3 | — | ❌ exp |
| `_vision_feedback.py` | Vision feedback v1 | — | ❌ exp |
| `_vision_feedback_v2.py` | Vision feedback v2 | — | ❌ exp |
| `scripts/batch_convert_cbz.py` | Batch KCC de CBZs en Nextcloud | Standalone | ❌ script |
| `scripts/download_type90.py` | Descarga TYPE.90 español | Standalone | ❌ script |
| `scripts/test_pipeline_653011.py` | Test end-to-end nhentai | Standalone | ❌ script |

### systemd service
```ini
# /etc/systemd/system/bot-artifacts.service
ExecStart=/home/ren/.local/bin/uv run python3 bot_artifacts.py
Restart=always
```
Restart: `sudo systemctl restart bot-artifacts.service`
Logs: `sudo journalctl -u bot-artifacts.service -f`

### Import Quirk
`src/` NO está instalado como paquete. Todos los comandos se ejecutan desde la raíz del proyecto, o `PYTHONPATH=.` cuando se corre desde otro lado.

---

## Config (.env vía pydantic-settings)

Todas las settings via `src/config.py:Settings(BaseSettings)`. `.env` en la raíz del proyecto.

### Telegram y Delivery

| Variable | Default | Descripción |
|----------|---------|-------------|
| `telegram_bot_token` | `""` | Token del bot (obligatorio para bot_artifacts.py) |
| `telegram_chat_id` | `0` | Chat/User autorizado |
| `delivery_backend` | `"local"` | `"local"` o `"nextcloud"` |
| `output_dir` | `"output"` | Directorio de salida para delivery local |
| `nextcloud_url` | `""` | Nextcloud server URL |
| `nextcloud_user` | `""` | Nextcloud username |
| `nextcloud_pass` | `""` | Nextcloud password |
| `nextcloud_base_path` | `"/kindle"` | Nextcloud base path |
| `nextcloud_data_path` | `""` | Nextcloud data directory path |
| `state_db_path` | `"data/manga_state.db"` | SQLite DB path |

### Translation Pipeline

| Variable | Default | Descripción |
|----------|---------|-------------|
| `translation_enabled` | `True` | Flag para activar/desactivar traducción |
| `translation_api_key` | `""` | API key para proxy de traducción |
| `translation_api_base` | `"http://127.0.0.1:55990/v1"` | Endpoint del proxy (OpenAI-compatible) |
| `translation_model` | `"xiaomi/mimo-v2.5"` | Modelo LLM por defecto |
| `translation_target_lang` | `"ESP"` | Lengua destino |
| `translation_config_path` | `"translate_config.json"` | Config file de manga-translator |
| `minimax_api_key` | `""` | MiniMax API key (fallback de translation_api_key) |
| `minimax_api_host` | `"https://api.minimax.io"` | MiniMax host |
| `vlm_endpoint` | `"/v1/coding_plan/vlm"` | VLM endpoint |
| `minimax_chat_model` | `"MiniMax-Text-01"` | MiniMax chat model |
| `vlm_timeout` | `90` | VLM timeout en segundos |

### Scrapers

| Variable | Default | Descripción |
|----------|---------|-------------|
| `hentai_search_url` | `"https://e-hentai.org/..."` | URL por defecto de búsqueda e-hentai |
| `hentai_subfolder` | `"hentai"` | Subcarpeta para hentai en Nextcloud |
| `hentai_cleanup_days` | `7` | Días para cleanup |
| `hentai_run_hour` | `6` | Hora del scheduler |
| `hentai_rate_limit` | `1.5` | Rate limit en segundos |
| `priority_rate_limit` | `0.75` | Rate limit para priority |
| `ehentai_manga_run_hour` | `6` | Hora del EhentaiMangaScheduler |
| `nhentai_daily_count` | `10` | Límite diario nhentai |
| `fansub_enabled` | `True` | Activar fansub pipeline |

### REST API

| Variable | Default | Descripción |
|----------|---------|-------------|
| `api_enabled` | `True` | Activar servidor API REST |
| `api_host` | `"0.0.0.0"` | Bind address |
| `api_port` | `8080` | Puerto |
| `api_key` | `""` | API key (vacío = sin auth en dev) |
| `api_rate_limit_per_min` | `60` | Rate limit general req/min |
| `api_submit_limit_per_min` | `10` | Rate limit para submits/min |

### Misc

| Variable | Default | Descripción |
|----------|---------|-------------|
| `mangas_folder` | `"/mnt/mangas"` | Carpeta vigilada por MangaWatcher |
| `kindle_profile` | `"KPW34"` | Perfil Kindle para KCC |
| `watch_interval` | `30` | Intervalo MangaWatcher en segundos |

---

## Pipeline de Traducción — Flujo de Cascada

`bot_artifacts.py` y `artifacts.py` ejecutan el mismo pipeline de 5 fases:

```
URL (nhentai/e-hentai)
  │
  ▼
┌───────────────────────────────────────────────────────┐
│ [1/5] Download  (artifacts.download_only)              │
│ nhentai CDN (i.nhentai.net, ~0.1s/page)               │
│ o fallback: e-hentai scraper (~2s/page)                │
│ → data/work_{gid}/download_meta.json (enriquecido)     │
│ → data/work_{gid}/ CBZ extraído en images/             │
└───────────────────────┬───────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────┐
│ [2/5] Preprocess (preprocess.preprocess_gallery)       │
│ Detección de texto (CTD para JP, dbconvnext para EN)   │
│ OCR (48px) → LLM translate → máscaras de inpaint       │
│ Dynamic detection con 4 fallback detectors              │
│ Pages en chunks de 50 con gc.collect() entre chunks     │
│ → data/work_{gid}/ regions/ y masks/                   │
└───────────────────────┬───────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────┐
│ [3/5] Quality + Refine (refine.refine_gallery)         │
│ LLM polish con contexto completo de la galería         │
│ 2 pasadas de refinamiento por página                   │
│ Chunking: si >50 págs, chunks de 50                    │
│ Timeout: n_chunks * 120s (mín 300s)                   │
│ max_tokens=14000 (límite 16K del modelo)               │
└───────────────────────┬───────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────┐
│ [4/5] Inpaint (inpaint_local.inpaint_gallery_local)    │
│ GPU auto-detection (CUDA > MPS > CPU)                  │
│ Modelo global único: AOT (JP) o lama_large (EN/KR/CN)  │
│ Semaphore: min(max(cpu//2,3),8) páginas concurrentes    │
│ Missing/empty masks → copia original                   │
│ → data/work_{gid}/ inpainted/                          │
└───────────────────────┬───────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────┐
│ [5/5] Complete + MOBI (complete.complete_gallery_cbz)  │
│ V14 PIL renderer con textbbox real                     │
│ Binary-search font size (24-64px, fallback 12-23px)    │
│ Flood-fill bubble detection + overlap resolution       │
│ → CBZ → KCC (--format MOBI --profile KPW34) → .mobi   │
│ → output/artifacts/{gid}/  + upload a Nextcloud        │
└───────────────────────────────────────────────────────┘
```

### Enriched download metadata (`download_meta.json`)

A partir del commit de /summary + /cover, `_download()` en `artifacts.py` escribe `download_meta.json` enriquecido con:

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `gid` | str | Gallery ID |
| `title` | str | Título en inglés |
| `title_jpn` | str | Título en japonés (si existe) |
| `config` | str | Ruta del config de traducción |
| `num_pages` | int | Número de páginas |
| `pages` | int | Alias backward-compat de `num_pages` |
| `is_spanish` | bool | Si ya está en español (skip translate) |
| `url` | str | URL original |
| `source` | str | `"nhentai"` o `"ehentai"` |
| `media_id` | str | media_id de nhentai (para cover URL) |
| `tags` | list[str] | Tags completos (`artist:xxx`, `parody:yyy`, etc.) |
| `artist` | str | Artista extraído de tags |
| `parody` | str | Parodia/franquicia extraída de tags |
| `cover_url` | str | URL externa de portada (nhentai CDN o e-hentai thumb) |

Las galleries **viejas** (descargadas antes del cambio) no tendrán estos campos. El endpoint `/summary` hace fallback a `QueueItem` de `UrlQueue` para cubrir `media_id`/`title_jpn`/`artist`/`parody`.

---

## bot_artifacts.py — Bot Telegram + API Server

Archivo de **1586 líneas**. Se ejecuta como servicio systemd. Es el entry point más importante.

### Arquitectura de Procesamiento (Two-Phase)

El procesamiento de galleries se divide en dos fases con **semáforos separados**:

```
                    asyncio.Queue (_processing_queue)
                    ┌─────────────────────┐
                    │  6 Workers (_queue_worker)  │
                    │  Consume (url, bot, chat_id)│
                    └──────────┬──────────┘
                               │
          ┌────────────────────┼────────────────────┐
          │ Phase 1 (I/O)      │ Phase 2 (CPU)      │
          ▼                    ▼                    ▼
┌──────────────────┐  ┌────────────────────┐
│ _download_sem     │  │ _translate_sem     │
│ MAX_CONCURRENT=2  │  │ MAX_CONCURRENT=2   │
│ artifacts.        │  │ _process_one() →   │
│   download_only() │  │ artifacts.process()│
│ (descarga CBZ)    │  │ (translate+inpaint │
│                   │  │  +render+MOBI+up)  │
└──────────────────┘  └────────────────────┘
```

### Inicialización (`main()` + `_post_init`)

1. `Application.builder().token(settings.telegram_bot_token).build()`
2. Registra CommandHandlers + MessageHandler
3. `_post_init` corre AL ARRANCAR el bot:
   1. Notifica "Bot encendido" a `ALLOWED_CHAT_ID`
   2. Lanza 6 workers (`_queue_worker`)
   3. `_drain_pending_on_startup(app)` — recupera galleries pendientes/fallidas
   4. Si `settings.api_enabled` → lanza `_start_api_server()`
   5. `_periodic_cleanup_loop()` — cleanup cada 24h
   6. `_daily_nhentai_feed_loop(app)` — feed diario a las 6AM ART (UTC-3)

### Comandos de Telegram

| Comando | Handler | Descripción |
|---------|---------|-------------|
| `/start` | `start_command` | Texto de ayuda listando todos los comandos |
| `/status` | `status_command` | Galleries activas, slots, UrlQueue stats, CPU/RAM, fallidas |
| `/retry [gid]` | `retry_command` | Reintentar todas o una gallery fallida |
| `/clean` | `clean_command` | Limpiar archivos >72h (vía `src.cleaner.clean_old_files`) |
| `/b <url>` | `bypass_command` | Procesar gallery saltando filtros de tags |
| `/update` | `nhfeed_command` | Activar manualmente el feed de portada de nhentai.net |
| `/nhfeed` | `nhfeed_command` | Alias de /update |
| `/wipe` | `wipe_command` | Limpiar cola + work dirs (NO borra output/artifacts ni Nextcloud) |

### Message Handler: `handle_message`

Detecta URLs en el mensaje usando `MessageEntity` (offset+length exacto) con fallback a regex.

**Tipos de URL** y sus rutas:

| Tipo URL | Regex | Routing |
|----------|-------|---------|
| `gallery` | `e-hentai.org/g/(\d+)/([a-f0-9]+)` o `nhentai.net/g/(\d+)` | `_processing_queue.put()` → `_queue_worker` → `_process_gallery_url()` |
| `search` | `e-hentai.org/?` | `asyncio.create_task(_process_search_url())` |
| `nh_search` | `nhentai.net/search?` | `asyncio.create_task(_process_nhentai_search_url())` |
| `nh_artist` | `nhentai.net/artist/([a-z0-9_-]+)` | `asyncio.create_task(_process_nhentai_artist_url())` |

**Dedup en handle_message** para URLs de tipo `gallery`:
1. Si ya está `processing` o `pending` → skip
2. Si ya completada (artifacts dir o status completed) → skip
3. Si fallida antes → limpia work_dir, resetea a pending, reintenta
4. Si nueva → `UrlQueue.add()` + encola

### Funciones Internas Clave

| Función | Firma | Rol |
|---------|-------|-----|
| `_queue_worker` | `(worker_id: int) -> None` | Loop infinito: consume `_processing_queue`, llama `_process_gallery_url` |
| `_process_gallery_url` | `(url, bot, chat_id, bypass_filter=False)` | **Two-phase**: download_sem → `artifacts.download_only()`; translate_sem → `_process_one()` |
| `_process_one` | `(url, bot, chat_id) -> bool` | Fase 2: `artifacts.process()` → CBZ → `send_to_kindle()` → actualiza stats |
| `_process_search_url` | `(url, bot, chat_id)` | Búsqueda e-hentai: scrape → batch metadata → dedup 5 niveles → batch processing |
| `_process_nhentai_search_url` | `(url, bot, chat_id)` | Búsqueda nhentai: content filter → FC→B&W redirect → dedup → batch processing |
| `_process_nhentai_artist_url` | `(url, bot, chat_id)` | Artista nhentai: mismo flujo que search |
| `_find_bw_alternative` | `(detail) -> NhentariGallery \| None` | Busca versión B&W alternativa cuando `should_download` bloquea por full color |
| `_check_duplicate` | `(gid, url, metadata) -> str \| None` | 5 niveles: artifacts dir → work dir → work_key → parent key → SQLite fingerprint |
| `_gdata_metadata` | `(gid, token) -> dict \| None` | Fetch metadata de e-hentai gdata API |
| `_drain_pending_on_startup` | `(application)` | Recupera URLs pendientes + fallidas post-reinicio |
| `_periodic_cleanup_loop` | `()` | Cleanup cada 24h via `src.cleaner.clean_old_files()` |
| `_daily_nhentai_feed_loop` | `(app)` | Feed diario nhentai a las 6AM ART |
| `_start_api_server` | `()` | Inicia FastAPI/uvicorn en el mismo event loop |
| `_wipe_all` | `()` | Wipe standalone (sin bot) — llamado por API DELETE /queue |
| `_clean_idle_memory` | `()` | Limpia cachés globales de manga-translator + `gc.collect()` cuando idle |
| `_load_failed` / `_save_failed` | `() -> list` / `(list)` | Persistencia de fallidas en `data/failed_galleries.json` |
| `_add_failed` / `_remove_failed` | `(url, gid, title, error)` / `(gid)` | Manager de lista de fallidas |
| `_extract_urls` | `(text, entities) -> list[(url, type)]` | Extrae URLs + tipo del texto del mensaje |
| `_extract_nh_query` | `(url) -> str` | Extrae `?q=` de URL de búsqueda nhentai |
| `_extract_nh_artist_sort` | `(url) -> str` | Extrae `?sort=` de URL de artista nhentai |
| `_build_parent_work_key` | `(title, title_jpn, tags) -> str` | Work key que ignora chapter/volume markers |
| `_detect_batch_lang` | `(tags) -> str` | Detecta idioma de tags para dedup batch |
| `_send_batch_summary` | `(batch) -> None` | Envía resumen de batch processing |
| `_notify_batch_done` | `(batch_id) -> None` | Tracking interno de progreso de batch |

### Variables Globales

```python
MAX_CONCURRENT = 2        # Slots de download y translate
_NUM_WORKERS = 6           # Workers de la cola
_translate_sem = Semaphore(2)
_download_sem = Semaphore(2)
_stats = {"completed": 0, "failed": 0, "active": 0}
_wiping = False
_processing_queue: asyncio.Queue = asyncio.Queue()
_batch_tracker: dict[str, dict] = {}
_LANG_PRIORITY = {"english": 0, "spanish": 1, "japanese": 2, ...}
FAILED_FILE = Path("data/failed_galleries.json")
ARTIFACTS_DIR = Path("output/artifacts")
```

### Restart Recovery

- `_drain_pending_on_startup()` corre en `post_init`
- UrlQueue se persiste en `data/bot_queue.json` (JSON)
- Items en estado "processing" al reiniciar se resetean a "pending" (crash recovery)
- `failed_galleries.json` también se drena al arranque
- `reload_from_disk()` es función **module-level** en `url_queue.py`

---

## REST API (FastAPI) — `src/api/`

Servidor FastAPI en el mismo event loop que el bot de Telegram. Corre en `0.0.0.0:8080` por defecto.

### Inicio

```python
# bot_artifacts.py:1497-1498 y 1550-1582
if settings.api_enabled:
    asyncio.create_task(_start_api_server())

async def _start_api_server():
    api_app = create_app(
        download_sem=_download_sem,
        translate_sem=_translate_sem,
        process_gallery_url=_process_gallery_url,
        wipe_fn=_wipe_all,
        api_key=settings.api_key,
        ...
    )
    config = uvicorn.Config(api_app, host=..., port=..., log_level="warning")
    server = uvicorn.Server(config)
    await server.serve()
```

### Estructura de Archivos

| Archivo | Rol |
|---------|-----|
| `src/api/__init__.py` | Factory `create_app()` — recibe semáforos y callbacks |
| `src/api/main.py` | `create_fastapi_app()` — monta middleware CORS, auth, routers |
| `src/api/auth.py` | `ApiKeyMiddleware` — auth via header `X-API-Key` |
| `src/api/deps.py` | Inyección de dependencias (semáforos, funciones) |
| `src/api/models.py` | Schemas Pydantic + helpers `ok()`, `err()`, `slot_info()` |
| `src/api/errors.py` | Rate limiter token-bucket + exception handlers |
| `src/api/routes/__init__.py` | Agregación de routers |
| `src/api/routes/system.py` | `GET /health`, `GET /status` |
| `src/api/routes/galleries.py` | CRUD de galleries |
| `src/api/routes/queue.py` | Queue management |
| `src/api/routes/search.py` | Search endpoints |

### Endpoints

| Método | Ruta | Descripción | Auth | Rate Limit |
|--------|------|-------------|------|------------|
| `GET` | `/api/v1/health` | Health check simple (uptime, version) | ❌ Público | — |
| `GET` | `/api/v1/status` | Estado completo: cola, slots, activas, RAM, CPU, modelo actual | ✅ | — |
| `POST` | `/api/v1/galleries` | Enviar URL para procesamiento completo | ✅ | Submit |
| `POST` | `/api/v1/galleries/download` | Solo descarga (fase 1) | ✅ | Submit |
| `GET` | `/api/v1/galleries` | Lista galleries (filtro por status + paginación) | ✅ | — |
| `GET` | `/api/v1/galleries/{gid}` | Detalle de una gallery | ✅ | — |
| `GET` | `/api/v1/galleries/{gid}/summary` | Resumen completo: title, title_jpn, tags, artist, parody, cover URL, pipeline status | ✅ | — |
| `GET` | `/api/v1/galleries/{gid}/cover` | Foto de portada (página 1) como FileResponse | ✅ | — |
| `GET` | `/api/v1/galleries/{gid}/artifacts` | Archivos generados | ✅ | — |
| `DELETE` | `/api/v1/galleries/{gid}` | Cancelar y eliminar gallery | ✅ | — |
| `POST` | `/api/v1/search` | Buscar en nhentai/e-hentai (sin procesar) | ✅ | General |
| `POST` | `/api/v1/search/process` | Buscar + auto-encolar resultados no bloqueados | ✅ | Submit |
| `GET` | `/api/v1/queue` | Lista cola (filtro + paginación) | ✅ | — |
| `GET` | `/api/v1/queue/stats` | Estadísticas de cola + slots | ✅ | — |
| `POST` | `/api/v1/queue/{gid}/retry` | Reintentar gallery fallida | ✅ | — |
| `DELETE` | `/api/v1/queue` | Wipe completo (equivalente a `/wipe`) | ✅ | — |

Swagger UI en `GET /docs`, ReDoc en `GET /redoc`, schema en `GET /openapi.json`.

### Autenticación

- **Middleware**: `ApiKeyMiddleware` (Starlette `BaseHTTPMiddleware`)
- **Header**: `X-API-Key`
- **Bypass paths**: `/api/v1/health` siempre público
- **Bypass IPs**: `127.0.0.1`, `::1`, `::ffff:127.0.0.1`
- **Dev mode**: si `api_key` está vacío en `.env`, no requiere auth
- **401 response**: `{"error": {"code": "unauthorized", "message": "Missing or invalid API key"}}`

### Rate Limiting

Token bucket in-memory por IP:
- **General**: `api_rate_limit_per_min` (default 60/min) — aplica a GETs y search
- **Submit**: `api_submit_limit_per_min` (default 10/min) — aplica a POST gallerias + search/process
- **429 response**: `{"error": {"code": "rate_limited", "message": "..."}}`

### NullBot

La API usa `_NullBot` como reemplazo de `telegram.Bot` para los mensajes de progreso. Los absorbe y los envía a logger en vez de a Telegram.

### CORS

Permite todos los orígenes (`*`) para scripts locales. Lockear en producción vía nginx.

---

## Módulos del Pipeline (`src/translator/`)

### `preprocess.py` — Detección, OCR, Traducción, Máscaras

- `preprocess_gallery(gallery_dir, device)`: Procesa página por página
  - Detecta texto (dynamic detection con 4 fallbacks)
  - OCR con tesseract/manga-ocr
  - LLM translate (proxy OpenAI-compatible)
  - Genera máscaras de inpaint (por región, con `_rebuild_mask_per_region`)
- Chunks de 50 páginas con `gc.collect()` entre chunks
- RSS threshold: `min(max(total_mem * 0.7, 6.0), 24.0)` GB
- Timeout por página: 600s (env `PAGE_TIMEOUT`)
- Concurrencia dinámica: `set_preprocess_concurrent(n)`

### `refine.py` — LLM Polish

- `refine_gallery(gallery_dir, chunk_size=0)`:
  - 2 pasadas de refinamiento LLM por página
  - Chunking automático (>50 pages → chunks de 50)
  - Timeout dinámico: `n_chunks * 120s` (mín 300s)
  - `_call_llm()` con `max_tokens=14000`
- El modelo real es el mismo que usa traducción (seteado vía `os.environ["OPENAI_MODEL"]`)
- El default `mimo-v2.5-free` en refine.py es un **fallback muerto** — nunca se usa

### `inpaint_local.py` — Inpainting

- `inpaint_gallery_local(gallery_dir, device)`:
  - Modelo global único (AOT para JP, lama_large para EN/KR/CN)
  - Semaphore: `min(max(cpu_count // 2, 3), 8)` páginas concurrentes
  - Missing/empty masks → copia original
  - Failed → fallback a original

### `complete.py` — Render V14 + CBZ Packaging

**V14 Renderer** (PIL-based, producción):
- `render_page_v14(inpainted_img, regions_data, mask_gray) -> np.ndarray`:
  - Flood-fill bounded bubble detection sobre imagen inpainted
  - Binary-search font size con PIL `textbbox` (24-64px, fallback 12-23px)
  - White stroke para legibilidad
  - Iterative overlap resolution (3 pasadas, shift 25-35px)
  - Character-by-character font fallback para símbolos no soportados
  - CJK stripping para targets no-CJK
  - Normaliza puntuación CJK (… → ..., ‼ → !!)
  - Spanish word hyphenation (`_split_word_spanish`)
  - `_draw_text_with_fallback`: si un carácter no está en el font principal, usa Arial Unicode

- `complete_gallery_cbz(gallery_dir, inpainted_dir, output_cbz) -> Path`:
  - Procesa cada página: render V14 si tiene texto, inpainted direct si no
  - Empaqueta en CBZ (JPEG quality 92)
  - Pipeline state tracking por página

### `dynamic_detection.py` — Adaptive Detection

- `compute_adaptive_config(config_dict, image) -> dict`: Ajusta `detection_size`, `text_threshold`, `box_threshold`, `unclip_ratio` según:
  - Tamaño de imagen: <1MP→1024, 1-3MP→1536, >3MP→2048
  - Contraste: <30→th 0.1, 30-50→0.15, >50→0.2
  - Text scale (Laplacian edge density)

- Fallback detector chain (4 intentos):
  1. Config adaptativa
  2. Detector `default` con thresholds bajos (0.15/0.2), 1536px
  3. `ctd` con thresholds mínimos (0.1/0.15), 1024px
  4. `default` con thresholds mínimos, 2048px

### `language.py` — Detección de Idioma + Config Routing

- `detect_language(tags) -> str`: Detecta idioma de tags (e-hentai `language:japanese` o nhentai `japanese`)
- `select_config_path(language) -> str`: Mapea idioma a archivo de configuración
- `write_metadata(gallery_dir, gid, title, tags, source, language)`: Escribe `source_metadata.json`
- Priority: Spanish > English > Korean > Chinese > Japanese
- Config files: japonés→`translate_config.json`, otros→ `translate_config_english/korean/chinese.json`

### `pipeline_state.py` — Tracking de Estado

```python
_active_galleries: dict[str, PipelineState] = {}
```

- `set_pipeline_state(gallery_id, phase, done, total)`: Actualiza estado (llamado desde preprocess, inpaint, render, mobi, upload)
- `get_active_galleries() -> dict`: Usado por `/status` y API `GET /status`
- `clear_pipeline_state(gallery_id)`: Limpia al completar/fallar

### `queue.py` — GalleryQueue

- JSON-backed singleton en `data/modal_queue/queue.json`
- Thread-safe via `threading.Lock` — múltiples instancias comparten estado
- Gallery dirs en `data/modal_queue/gallery_{gid}/` con `images/`, `masks/`, `regions/`
- Status: `pending → processing → completed/failed`
- Métodos: `add()`, `get()`, `mark_processing()`, `mark_completed()`, `mark_failed()`, `set_cbz_path()`, `set_priority()`, `reset_to_pending()`, `remove()`, `cleanup_completed()`, `get_pending()`, `get_incomplete()`, `get_failed()`

### `config.py` — TranslationConfig

```python
@dataclass
class TranslationConfig:
    api_key: str = ""
    api_base: str = "https://api.z.ai/api/coding/paas/v4"
    model: str = "GLM-5.1"
    target_lang: str = "ESP"
    config_path: str = "translate_config.json"
```

- `from_settings(settings)`: build desde `Settings` (usa `minimax_api_key` como fallback)

### `runner.py` — CLI Wrapper para manga-image-translator

- `run_translator(input_dir, output_dir, config)`: Corre `python -m manga_translator local`
- Parallel batch processing: divide imágenes en batches, corre concurrentemente
- CPU optimization flags: `OMP_NUM_THREADS`, `MKL_NUM_THREADS`, etc.
- Fallback: copia originales para páginas sin texto detectado
- Workers: `min(max(cpu_count // 2, 3), 8)`

### `__init__.py` — translate_manga()

- `translate_manga(cbz_path, config, output_dir=None) -> Path`: Alto nivel para CBZ
  - Extrae CBZ → corre translator → repack → devuelve path del CBZ traducido
  - On failure **RAISES** (no fallback al original)

### `_threadloop.py` — Thread-Local Event Loops

- Cada thread worker tiene su propio event loop persistente (evita `asyncio.run()` y memory leaks)
- `run_coro(coro)`: corre coroutine en el loop del thread actual
- `get_translator()`: crea/obtiene MangaTranslator thread-local con HTTP client propio
- Dummy 64x64 al init fuerza carga de modelos en el thread correcto
- PyTorch model weights SHARED globalmente (solo HTTP client es per-instance)

### `api_fallback.py` — API Fallback y Model Scoring

- Primary proxy: `http://127.0.0.1:6446/v1` (OpenAI-compatible local)
- NSFW fallback: NVIDIA API con `minimaxai/minimax-m3`
- Proxy health-check via `GET /v1/models` cada 30 segundos
- **Model scoring**: success +0.1 (max 2.0); retryable errors -0.2 (min 0.1); hard errors -0.5 (min 0.1) con streak penalty
- **Circuit breaker**:
  - `503` / service unavailable → banned 120s
  - `401` / unauthorized → banned 1800s (30 min — dead model)
  - `pick_model()` filtra modelos baneados
- Default target: `nvidia/nemotron-3-ultra-550b-a55b:free`
- Blocklist: `stepfun/step-3.7-flash:free` (returns empty/None)
- Scores persisten en `data/model_scores.json`
- `setup_api(pick_model())` setea `os.environ["OPENAI_MODEL"]` **antes** de cualquier refine call

---

## Configs de Traducción por Idioma

| Config | Detector | Detection Size | Inpainter | Inpaint Size | Font Offset | Mask Dilation/Kernel |
|--------|----------|---------------|-----------|-------------|-------------|---------------------|
| `translate_config.json` (JP) | ctd | 2048 | default (AOT) | 1024 | +10 | 35/5 |
| `translate_config_english.json` (EN) | default | 2048 | **lama_large** | 2048 | +10 | **55/8** |
| `translate_config_korean.json` (KR) | default | 2048 | **lama_large** | 2048 | +10 | **55/8** |
| `translate_config_chinese.json` (CN) | default | 2048 | **lama_large** | 2048 | +10 | **55/8** |

- Todos usan renderer `manga2eng`, OCR `48px`, target `ESP`, translator `chatgpt`
- EN/KR/CN requieren `lama_large` con dilation/kernel más alto (texto no-CJK ocupa más espacio)
- JP usa detector CTD (entrenado en kanji); otros usan default (dbconvnext)

---

## Sistema de Colas

### UrlQueue (`src/url_queue.py`) — Cola del Bot

- JSON-backed (thread-safe)
- Persiste en `data/bot_queue.json`
- Items clave: `gid`, `url`, `token`, `title`, `work_key`, `is_spanish`, `filecount`, `status`
- Status: `pending → processing → completed/failed`
- Crash recovery: items en "processing" al cargar disco se resetean a "pending"
- Dedup via `work_key`: fingerprint canónico de `title_jpn` (tier 1) o `artist + clean_title` (tier 2)
- `media_id_cache` separada (`data/media_id_cache.json`) mapea e-hentai gid → nhentai media_id
- Funciones clave: `add()`, `get()`, `find_duplicate()`, `claim_next_pending()`, `mark_completed()`, `mark_failed()`, `reset_to_pending()`, `get_pending()`, `get_all()`
- `build_work_key(tags, title, title_jpn) -> str`: Construye key canónico
- `reload_from_disk()`: **module-level function** para recargar desde disco
- `reload_from_disk()` en `queue.py`: Force-reload para scripts externos

### GalleryQueue (`src/translator/queue.py`) — Cola del Pipeline

- JSON-backed singleton en `data/modal_queue/queue.json` con estado compartido module-level
- Thread-safe via `threading.Lock`
- Gallery dirs en `data/modal_queue/gallery_{gid}/` con `images/`, `masks/`, `regions/`
- Diferencia clave con UrlQueue: esta es para el **pipeline de traducción local**, no para el bot
- `QueuedGallery`: `gallery_id`, `title`, `source`, `num_pages`, `status`, `cbz_path`, `priority`, `language`, `token`

---

## Pipeline Orchestration (`src/pipeline.py`)

- `run_pipeline_once(settings)`: Entry point único
  - Retry failures → preprocess → inpaint → render → MOBI → deliver
- Llamado desde `cli.py worker` (loop) y `cli.py prioridad`/`manga` (inline)
- Paralelismo: `min(max(cpu_count // 4, 3), 6)` galleries en paralelo
- Timeout por gallery: `max(num_pages * 120, 1800)` segundos
- Permanent error patterns (no retry): "opencv", "content filtered", "no images found"

---

## Scrapers

### nhentai (`src/nhentai_scraper/`)

- Scrapling `StealthySession` para Cloudflare bypass
- CDN download preferido: `i.nhentai.net/galleries/{media_id}/{page}.{ext}` (~0.1s/page)
- e-hentai fallback para no-Spanish
- Content filter: skip non-manga, non-JP source, <10 pages
- Rate limiting + retry con exponential backoff
- Funciones: `scrape_search`, `search_nhentai`, `_fetch_gallery_v2`, `should_download`, `fetch_gallery_links_httpx_async`, `safe_nh_api_get`

**Dedup** (`src/nhentai_scraper/dedup.py`):
- `select_winners(raw_galleries, state_db, notify_fn) -> DedupReport`:
  - Phase 1: Enrich each raw gallery with v2 metadata
  - Phase 1b: Bridge galleries without title_jpn via EN-title matching
  - Phase 2: Group by fingerprint
  - Phase 3: DB cross-reference + select winner per group
  - Winner selection: Spanish > English > Japanese > Chinese, then page count, then higher GID
- `DedupReport`: `groups`, `no_fingerprint`, `winners`, `stats`
- `format_dry_run_table(report)`: Render tabla legible para dry-run
- `detect_language(tags, title_jpn)`: Detecta idioma via title markers (más confiable que tags)
  - Priority 1: title_jpn markers (`[スペイン翻訳]`, `[英訳]`, etc.)
  - Priority 2: tags (bare or prefixed)

### e-hentai (`src/hentai_scraper/` + `src/ehentai_search.py`)

- API method: `gdata` (no legacy `gmetadata`)
- Front page scrape para scheduler diario; metadata fetch via API
- `search_spanish_version(title_jpn, artist_tag, title)`: Busca versión española en e-hentai
  - Step 1: Búsqueda específica (artist + title keywords + language:spanish)
  - Step 2: Fallback a búsqueda amplia (artist + language:spanish) + CJK title matching
  - Match por fingerprint de título (CJK o EN)
- `scrape_front_page(category_mask, max_pages)`: Scrapea front page de e-hentai
- `fetch_metadata_batch(galleries)`: Fetch metadata batch via API (25 por lote)

### EhentaiMangaScheduler (`src/ehentai_manga_scheduler.py`)

Scheduler diario que reemplaza a `HentaiScheduler` + `NhentaiScheduler` legacy.

```
Front page e-hentai (Manga + Doujinshi)
  → Metadata batch API
  → Filter: only Manga/Doujinshi, not processed, content-safe
  → Dedup + fingerprint grouping (ESP > EN > JP > CN)
  → Por cada gallery:
    ├─ Spanish tag → download (nhentai CDN preferido, fallback e-hentai) → MOBI → upload
    └─ Not Spanish → search_spanish_version()
        ├─ Found Spanish → download esa versión → MOBI → upload
        └─ Not found → download de nhentai (o e-hentai) + GalleryQueue para traducción
```

- `_probe_nhentai_cdn(gid)`: Verifica si gallery existe en nhentai CDN
- `_resolve_nhentai_media_id(gid, title)`: Resuelve media_id correcto (fast: gid, slow: v2 API search)
- `_search_nhentai_v2(title)`: Busca en nhentai v2 API por título
- `_download_and_upload(meta)`: Download + KCC + Nextcloud upload
- `_download_and_translate(meta)`: Download + GalleryQueue encolado para traducción

---

## Fansub Pipeline (`src/fansub/`)

Pipeline alternativo para nhentai galleries (independiente de `src/translator/`).

```
nhentai gallery
  → RT-DETR ONNX detection (class 0=bodies, 1=text, 2=frames)
  → MiniMax VLM OCR/translation
  → TELEA inpainting
  → Pillow typesetting
  → CBZ
```

- ONNX model en `/tmp/rtdetr/model.onnx` (descargado en Docker build)
- Activado via `fansub_enabled=True` en `nhentai_scraper/scheduler.py`
- Text regions grouped via Union-Find clustering (25px proximity)
- Fallback font: `fonts/Anime_Ace_3.ttf`
- `FansubPipeline` class en `__init__.py`, `run_fansub_pipeline()` en `pipeline.py`
- Módulos: `detector.py`, `text_detector.py`, `translator.py`, `redrawer.py`, `typesetter.py`, `cleaner.py`, `packager.py`, `config.py`
- Requirements propios: `src/fansub/requirements_fansub.txt`

---

## State Database (`src/base_state.py`)

- SQLite via `BaseStateDB` — nunca escribir raw SQL fuera de este módulo
- Subclasses:
  - `HentaiStateDB` — e-hentai gallery state
  - `NhentaiStateDB` — nhentai gallery state
  - `MangaStateDB` — manga (MangaWatcher) state
- Status: `pending → downloading → downloaded → processing → completed → failed`
- `find_by_fingerprint(fp)`: Cross-db dedup por fingerprint de title_jpn

**Dual State Tracking (KNOWN ISSUE)**: Tanto SQLite (`NhentaiStateDB`/`HentaiStateDB`) como GalleryQueue/UrlQueue trackean estado de galleries SIN reconciliación cruzada.

---

## Delivery

### Nextcloud (`src/nextcloud_uploader.py`)

```python
send_to_kindle(path, settings, subfolder)
```

- `sudo cp + chown www-data:www-data` al data dir de Nextcloud
- `docker exec -u 33 nextcloud occ files:scan --path=...` para indexar
- No WebDAV — copia directa al filesystem

### Local (`src/local_uploader.py`)

```python
send_to_kindle(path, settings, subfolder)
```

- `shutil.copy2` a `output_dir/{subfolder}/`
- Backend default cuando `delivery_backend=local`

---

## Notifications (`src/notifier.py`)

- Protocol-based: `Notifier` Protocol class
- Implementaciones:
  - `ConsoleNotifier` — log a stdout
  - `TelegramNotifier` — envía mensajes a Telegram
  - `NullNotifier` — no-op (default)
- Registro global via `utils.set_notifier(notifier)` al startup
- Uso: `utils.notify(message=...)` desde cualquier módulo

---

## GPU/Device Auto-Detection (`src/device.py`)

```python
def get_device() -> str:     # "cuda" | "mps" | "cpu"
def prefer_gpu() -> bool:    # get_device() != "cpu"
```

- No config, no env vars — detecta en runtime via `torch.cuda.is_available()` / `torch.backends.mps.is_available()`
- Usado por: `_threadloop.py` (MangaTranslator `use_gpu`), `inpaint_local.py` (inpainting device), `artifacts.py`/`process.py`

---

## Utilidades Compartidas (`src/utils.py`)

| Función | Descripción |
|---------|-------------|
| `set_notifier(notifier)` | Registra notificador activo |
| `notify(message)` | Despacha mensaje via notificador activo |
| `gallery_date_folder()` | Fecha UTC como `M_D_YYYY` (portable, sin zero-padding) |
| `sanitize_filename(name, max_len)` | Sanitiza nombre de archivo (elimina chars inseguros) |
| `format_gallery_name(lang, title, gid)` | Formato `[LANG] (title) (gallery_id)` |
| `normalize_title_for_dedup(title)` | Normaliza título EN para dedup cross-source |
| `normalize_jp_title_for_dedup(title_jpn)` | Normaliza título JP para dedup (strip brackets, chapter markers, etc.) |
| `title_has_english(title)` | Check si título tiene `[English]` |
| `title_has_spanish(title)` | Check si título tiene `[Spanish]` |
| `format_summary(downloaded, failed)` | Formatea resumen de descargas |

---

## Otros Módulos

### `src/converter.py`

Conversión de formatos: EPUB, PDF, CBR, CBZ, ZIP → Kindle format.
- `is_image_pdf(src)`: Detecta si PDF es imagen vs texto
- `convert(src, fmt)`: Detecta formato y convierte
- `_fetch_metadata(stem)`: Fetch metadata via `fetch-ebook-metadata`
- `_safe_extract(zf, dest)`: ZIP extraction segura (previene path traversal)

### `src/file_handler.py`

- `download_file(update, tmp_dir)`: Descarga archivo de Telegram
- `download_from_url(url, tmp_dir, timeout)`: Stream-download desde URL
- `cleanup_tmp_dir(tmp_dir)`: Elimina directorio temporal

### `src/cleaner.py`

- `clean_old_files(artifacts_dir, data_dir, max_age_hours, dry_run) -> CleanupStats`:
  - Elimina archivos >72h de `output/artifacts/` y `data/work_*`
  - Protege `bot_queue.json`, `manga_state.db`, `failed_galleries.json`, `model_scores.json`, `media_id_cache.json`
  - Soportado como script standalone: `python -m src.cleaner --hours 72 --dry-run`

### `src/libgen.py`

Búsqueda en Library Genesis:
- `search_books(query, by_author=False) -> list[Book]`: Busca y devuelve top 5 (EPUB first)
- `resolve_download_url(book) -> str | None`: Resuelve URL de descarga directa
- `Book`: id, md5, title, author, year, pages, language, extension, size, mirrors
- Usa BeautifulSoup para parsear HTML de resultados

### `src/manga_watcher.py`

- `MangaWatcher(config, bot_app)`: Vigila carpeta de Nextcloud para nuevos mangas
  - Polling loop cada `watch_interval` segundos
  - `_validate(filepath)`: Verifica extensión y contenido (imágenes dentro de ZIP/CBR)
  - `_translate_if_enabled(filepath)`: Traduce si `translation_enabled=True`
  - `_convert(input_path)`: KCC → MOBI
  - `_upload_to_nextcloud(output_dir, title)`: Upload a Nextcloud
  - Trackea estado via `MangaStateDB`

### `src/exceptions.py`

```python
KindleError(Exception)        # Base
  ├─ ConversionError           # Conversión fallida
  ├─ UploadError               # Upload fallido
  ├─ ScrapingError             # Scraping/download fallido
  └─ TranslationError          # Traducción fallida
```

---

## Scripts (`scripts/`)

| Script | Descripción |
|--------|-------------|
| `batch_convert_cbz.py` | Batch KCC conversion de CBZs en Nextcloud |
| `download_type90.py` | Descargar TYPE.90 español, convertir, subir |
| `llama_server.ps1` | PowerShell management de llama.cpp server local |
| `test_pipeline_653011.py` | Test end-to-end nhentai pipeline |

---

## KCC Wrapper (`src/kcc.py`)

- `kcc-c2e` en su propio grupo de procesos con timeout (**600s default**)
- Si el proceso cuelga: `kill -- -$PGID` (Linux) o `taskkill /T /F` (Windows)
- File-based completion detection (espera archivo `.mobi`, polling)
- Flags: `--format MOBI --profile KPW34 --manga-style --stretch --splitter 2`

---

## Visual Feedback Loop (`visual_feedback.py`)

- Vision LLM (xiaomi/mimo-v2.5) evalúa legibilidad del texto renderizado por burbuja
- Verdictos: READABLE / TOO_SMALL / OVERFLOWING / EMPTY
- Auto-ajusta `font_size_offset`, `font_size_minimum`, `font_size_maximum`
- Sanity bounds: offset [-20, 50], minimum [6, 60], maximum [25, 100]

---

## Windows Encoding

Set `PYTHONUTF8=1` o `sys.stdin.reconfigure(encoding='utf-8')` para evitar problemas cp1252. Sin esto, `asyncio.create_subprocess_exec` con `PIPE` puede corromper output de manga-translator en Windows.

---

## Known Bugs & Design Issues

1. `scraper.py` dead code: `fetch_gallery_links_httpx()` raises `NotImplementedError` — nunca se llama
2. `scraper.py` dead parameter: `should_download()` acepta `translation_enabled` pero nunca lo usa
3. `scraper.py` code duplication: `_fetch_gallery_httpx()` y `_fetch_gallery_sync()` tienen lógica de parsing casi idéntica
4. Dual state tracking: SQLite (`NhentaiStateDB`/`HentaiStateDB`) Y GalleryQueue/UrlQueue trackean estado de galleries sin reconciliación cruzada
5. `process.py` coexiste con `artifacts.py` — versión anterior del pipeline
6. `bot.py` (legacy, 26KB) coexiste con `bot_artifacts.py` (producción, ~30KB)
7. Hardcoded paths: `docker exec -u 33 nextcloud` en `nextcloud_uploader.py`
8. No centralized rate limiting: cada scraper maneja su propio rate limit
9. `mark_processing` en `base_state.py` NO incrementa `retry_count` (se hace por separado)
10. `url_queue.py` dead code: `_build_work_key_for_item` tiene un `return` inalcanzable después de un docstring duplicado de `reload_from_disk`
11. API REST no tiene autenticación por defecto en dev (`api_key` vacío = sin auth)
12. `_render_*.py` y `_smart_render_*.py` y `_vision_feedback*.py` son experimentales sin entry point — coexisten como archivos muertos en la raíz
13. `src/converter.py` usa `subprocess` para `ebook-convert` y `fetch-ebook-metadata` de Calibre — puede fallar si no está instalado

---

## What NOT to Add

- No CI/CD pipelines, no pre-commit hooks, no linter/formatter configs
- No WebDAV endpoints (replaced by local filesystem copy)
- No new entry points without discussion