Proyecto independiente No afiliado, patrocinado ni avalado por la Watch Tower Bible and Tract Society o Jehovah's Witnesses.
jw-agent-toolkit
EN

2026-05-31 · Release 33-48

6 fases entregadas. 10 fases planeadas . Ecosistema al SOTA.

Las Fases 33-38 subieron el techo técnico del núcleo (embeddings, audio, gramáticas, VLM, visual, generación). Las Fases 39-48 atacan tres frentes ortogonales: confianza en runtime (NLI + provenance), comunidad (plugin SDK + scaffolding + tracing) y superficie JS (TS port + browser extension).

Fases entregadas

6

33 → 38

Commits TDD

99

red → green → commit

Tests nuevos

+312

1641 → 1986 passing

Planeadas

10

specs + plans listos

▌ ENTREGADAS · Fases 33-38

Implementadas, 99 commits TDD, suite 1986/0, 0 regresiones.

Tier 1 · Confianza en runtime

Mide y protege todo lo demás en vivo.

Fase 33

embed-rerank

Núcleo RAG al SOTA multilingüe

+50 tests 19 commits ✓ Shipped
Guía →

Reemplaza el FakeEmbedder por proveedores reales con auto-detección triple-target (API/MLX/NVIDIA/CPU) + cross-encoder reranker después del RRF. NDCG@10 sube significativamente en es/en/pt.

Qué se entregó

  • 6 embedders: BGE-M3, Multilingual-E5, Jina v3, Cohere v3, Voyage, Ollama nomic.
  • 3 rerankers: BGE-reranker-v2-m3 (local Apache 2.0), Cohere Rerank 3.5, Jina Reranker v2.
  • VectorStore.hybrid_search(rerank=True) con backwards-compat completa.
  • Auto-detect: API → MLX → NVIDIA → CPU según JW_EMBED_PROVIDER / JW_RERANK_PROVIDER.
  • Tests cross-provider con stub SDK vía sys.modules — cero red.

Pendiente / siguiente PR

  • Métricas NDCG sobre corpus mayor con eval comparativo.

Fase 34

audio-premium

TTS / ASR de calidad sin perder local-first

+36 tests 14 commits ✓ Shipped
Guía →

Añade providers premium sin tocar los 3 existentes (system/edge/piper). Kokoro 82M es default cuando hay; XTTSv2 voice-cloning gateado por doble opt-in (consent.txt obligatorio).

Qué se entregó

  • TTS premium: Kokoro 82M (SOTA TTS Arena ene-2026), XTTSv2 cloning, F5-TTS, ElevenLabs API.
  • ASR: WhisperLargeV3Turbo con auto-select por VRAM, Deepgram streaming API.
  • XTTSv2 doble opt-in: requiere --voice-clone flag AND consent.txt junto al sample.
  • Chain default: kokoro_local → edge → system → ElevenLabs → piper.
  • Backwards-compat: transcribe_file('audio.mp3') sigue dando model_size='base'.

Tier 2 · Comunidad

Plugin SDK, scaffolding, tracing, judge.

Fase 35

constrained-decoding

Citas verificables a nivel de gramática

+46 tests 16 commits ✓ Shipped
Guía →

Aplica el principio "citas verificables" al nivel de DECODIFICACIÓN del LLM, no del prompt. Property test con 100 prompts adversariales: 0 outputs sin citation_url válida.

Qué se entregó

  • Módulo nuevo jw_core.grammar/ con GBNF builders + Pydantic mirror models.
  • citation_grammar fuerza ^https://wol\.jw\.org/... en cada Finding.
  • 4 adapters: OllamaAdapter (grammar kwarg), Anthropic (tool-use), OpenAI (response_format), llama-cpp-python.
  • FakeConstrainedCaller determinístico para tests offline.
  • Property test 100 prompts adversariales × Hypothesis → 0 schema violations.
  • CLI `jw constrained ask` + MCP tool `run_constrained`.

Fase 36

vlm-ocr

VLM moderno reemplaza Tesseract

+53 tests 18 commits ✓ Shipped
Guía →

Output estructurado por bloques (header/paragraph/citation/footnote) listo para ingestar al RAG. Tesseract sigue como fallback con DeprecationWarning.

Qué se entregó

  • VLMProvider Protocol + StructuredPage Pydantic con bloques tipados.
  • Providers: Qwen3-VL local (mlx-vlm/vLLM/llama.cpp), Qwen3-VL API (DashScope), ClaudeVision (adapter SDK anthropic), OpenAIVision.
  • ClaudeVisionProvider NO es un modelo separado — es adapter sobre claude-haiku-4-5/sonnet-4-6/opus-4-7 con input de imagen.
  • ingest_image() en jw-rag consume StructuredPage y emite un chunk por bloque.
  • End-to-end demo: PNG de versículo → BibleRef(book_num=43, chapter=3, verse=16).

Tier 3 · Frontera técnica

Chunking semántico, versification.

Fase 37

colpali-visual

Late interaction sobre páginas renderizadas

+42 tests 14 commits ✓ Shipped
Guía →

Recuperación visual sobre páginas rasterizadas de PDF/EPUB/JWPUB. Multi-vector embeddings + MaxSim scoring. Three-way RRF (BM25 + text-vector + visual-MaxSim).

Qué se entregó

  • Subpaquete jw_rag.visual con ColPali + ColQwen2 embedders (multi-vector).
  • VisualVectorStore con persistence + MaxSim + mismatch detection.
  • PageRasterizer para PDF (pdf2image) / EPUB (playwright) / JWPUB.
  • Fail-fast sin GPU: ConfigError con install hint accionable, NO CPU path.
  • Ingest pipeline sha256-idempotent (re-runs skip unchanged).
  • 5 figure-heavy L1 golden cases nuevos en eval.

Pendiente / siguiente PR

  • Solo NVIDIA primario; MLX vía mlx-vlm experimental.
  • Sin API fallback (no hay servicio comercial ColPali estable en 2026).

Tier 4 · Superficie JS

Port TS mínimo + extensión navegador.

Fase 38

jw-gen (8º paquete)

Generación con difusión y política LOAD-BEARING

+85 tests 18 commits ✓ Shipped
Guía →

Octavo paquete del monorepo. Imagen + audio + video para presentaciones/discursos personales. Política no-negociable: watermark + EXIF/XMP + disclaimer.txt sibling. Safety filters anti-emulación JW oficial.

Qué se entregó

  • Paquete nuevo packages/jw-gen/ (8º workspace member).
  • 13 adapters: 5 image (NanoBanana, Flux 2 Pro, Recraft v4, Ideogram v3, Imagen 4) + 3 audio (ElevenLabs, Suno, MusicGen) + 5 video (Veo 3, Kling, Seedance, Higgsfield, Runway).
  • Policy fail-closed: finalize_output exige watermark + metadata + disclaimer.
  • 3 safety filters: anti-logo-JW (con bypass real encontrado y corregido: 'Despertai'), voice-cloning double opt-in, realistic-faces stylized default.
  • MCP tool generate_illustration fuerza watermark=True silenciosamente.
  • Audit log con sha256(prompt) — nunca prompt en claro.
  • Property test Hypothesis 100 prompts adversariales en en/es/pt.

Pendiente / siguiente PR

  • CI matrix con [pdf]/[docx]/[anki] extras instalados.
  • Cassettes pytest-recording para los 13 adapters reales.

▌ PLANEADAS · Fases 39-48

Specs + plans escritos (4205 + 34148 = 38353 líneas, 155 TDD tasks). Listas para implementar por tiers.

Tier 1 · Confianza en runtime

Mide y protege todo lo demás en vivo.

Fase 39

nli-runtime

El guardián semántico en vivo

📋 Planeada

Verifica en runtime que cada Finding del agente se desprende lógicamente del passage citado. Es la contraparte ONLINE de la eval doctrinal (Fase 22) y la contraparte SEMÁNTICA de constrained-decoding (Fase 35).

Planeado

  • Spec aprobado: 395 líneas. Plan TDD: 3962 líneas, 16 tasks.
  • Triple-target: DeBERTa-v3-MNLI local + Claude/OpenAI/Ollama NLI APIs.
  • Decorador @fidelity_wrap(min_score=0.7, on_fail='warn') sobre agentes existentes.
  • Default on_fail='warn' (no 'reject') para no romper los 1986 tests existentes.

Fase 40

content-provenance

Trazabilidad del passage exacto usado

📋 Planeada

Cada Citation lleva published_date + accessed_at + content_hash + revision. Permite re-validar cuando jw.org cambia un artículo o NWT publica una revisión. Complemento natural de Fase 39.

Planeado

  • Spec aprobado: 336 líneas. Plan TDD: 3607 líneas, 14 tasks.
  • Citation.metadata gana 4 campos obligatorios (backwards-compat: aditivo).
  • provenance_check() re-fetcha la URL y compara content_hash.
  • Cuando detecta cambio, re-ejecuta NLI (Fase 39) automáticamente.

Tier 2 · Comunidad

Plugin SDK, scaffolding, tracing, judge.

Fase 41

plugin-sdk

Extension points sin forkear el monorepo

📋 Planeada

Terceros publican paquetes Python en PyPI que extienden el toolkit vía entry points (PEP 621). 5 grupos: agentes / parsers / embedders / VLMs / gen providers. La pieza más alta de palanca para convertir el proyecto en 'lo de la comunidad'.

Planeado

  • Spec aprobado: 495 líneas. Plan TDD: 3398 líneas, 16 tasks.
  • 5 entry-point groups documentados con Protocols estrictos.
  • Política de conflictos: NAMESPACED (no FIRST_WINS) para evitar dependencia del orden de install.
  • Evolución de contratos: additive-only Protocols + hasattr capability detection.

Fase 42

scaffolding

create-jw-agent + cookbook ejecutable

📋 Planeada

CLI generator que baja la curva de 'primer agente custom' a 10 minutos. Cookbook con 12 recipes auto-testeados en CI vía plugin pytest-cookbook.

Planeado

  • Spec aprobado: 443 líneas. Plan TDD: 3412 líneas, 18 tasks.
  • Doble surface: paquete PyPI standalone `create-jw-agent` + wrapper `jw create-agent`.
  • 12 recipes copy-pasteables con bloques '# test' parseados automáticamente.
  • CI job cookbook-tests rompe build si cualquier recipe deja de compilar.

Fase 43

agent-tracing

Debuggability local de agentes

📋 Planeada

Cada agente emite trace JSON con findings considerados, descartados, ranking y razones. Distinto de Fase 22 (mide outputs) — esto explica el PROCESO.

Planeado

  • Spec aprobado: 394 líneas. Plan TDD: 3231 líneas, 15 tasks.
  • JSONL append-only en ~/.jw-agent-toolkit/traces/ (envelope al final, no header).
  • OTel bridge opt-in vía [otel] extra (no default, para mantener zero-dep local-first).
  • CustomEvent escape hatch + lint guard en CI para agentes nuevos sin instrumentar.

Fase 44

synth-judge

Filtro de calidad para Q&A sintético

📋 Planeada

Filtra pares Q&A sintéticos antes de fine-tuning. Reusa Fase 39 (NLI). 4 dimensiones: cites_jw_publication / nli_score / pedagogical_quality / overall.

Planeado

  • Spec aprobado: 453 líneas. Plan TDD: 3413 líneas, 13 tasks.
  • NLI extrae premise de comilla inline en respuesta (no del chunk fuente).
  • Fórmula overall aditiva con valores neutros para degradación grácil.
  • Default modo loose descarta overall < 6; recipe override.

Tier 3 · Frontera técnica

Chunking semántico, versification.

Fase 45

semantic-chunking

Chunking por unidad de pensamiento

📋 Planeada

Mejora chunking actual (paragraph-based) con detección de continuación argumentativa. Heurística primero + LLM opt-in. Métrica de éxito: NDCG@10 ≥10% mejora PER language.

Planeado

  • Spec aprobado: 346 líneas. Plan TDD: 3341 líneas, 12 tasks.
  • Backwards-compat: paragraph chunker se mueve, façade existente queda bit-identical.
  • Continuation markers en es/en/pt vía JSON catalog.
  • NDCG@10 ≥10% PER LANGUAGE (no aggregate) para evitar regresión sub-idioma.

Fase 46

canonical-versification

Mapeo entre tradiciones de numeración

📋 Planeada

Mapeo entre cristiano (NWT) / hebreo masorético / Septuaginta / Vulgata. ~150 discrepancias documentadas (Salmos superscripts, Joel 2:28-32 = Joel 3 Heb, etc.).

Planeado

  • Spec aprobado: 372 líneas. Plan TDD: 2512 líneas, 14 tasks.
  • VerseCoord permite verse_start=0 (superscripciones); BibleRef stays strict.
  • MappingResult wrapper fuerza acknowledge tradition incluso cuando no hay discrepancia.
  • Copyright guard test: scan stop-phrases de Tov/BHS/NETS para garantizar prosa original.

Tier 4 · Superficie JS

Port TS mínimo + extensión navegador.

Fase 47

jw-core-js-minimal

Port TypeScript de 3 módulos críticos

📋 Planeada

Port TS de parse_reference + WOLClient.get_bible_chapter + parsers.article. Abre la puerta Capacitor/Expo/browser sin portar 33k líneas de Python. Cross-language parity en CI.

Planeado

  • Spec aprobado: 591 líneas. Plan TDD: 3944 líneas, 21 tasks (8 sprints).
  • Stack: pnpm + tsdown (Rolldown) + Biome + Vitest. ESM-only.
  • 500 cross-lang fixtures: parse_reference TS y Python deben producir JSON idéntico.
  • npm scope @jw-agent-toolkit con placeholder v0.0.1 reservado en Sprint 1.

Fase 48

wol-browser-ext

Extensión Chrome/Firefox para wol.jw.org

📋 Planeada

Inyecta UI inline en wol.jw.org. Cada versículo gana botones: 📖 Explicar, 🔗 Cross-refs, 📝 Guardar a Obsidian. Backend REST localhost:8765 — local-only, sin enviar datos a 3rd parties.

Planeado

  • Spec aprobado: 380 líneas. Plan TDD: 3328 líneas, 16 tasks.
  • Manifest v3 unificado Chrome/Edge/Firefox.
  • Tighten CORS de '*' a allow-list explícito wol.jw.org + chrome-extension://* (fix de seguridad).
  • Distribución v0.1: GitHub Releases zip + 'Load unpacked'. Web stores en v0.2+ (review tardío).
  • Vault path validation: defensa anti path-traversal con check '.obsidian/' marker.

▌ Más

← Fases 22-32 Roadmap maestro 22-48 →