Documentación de jw-agent-toolkit

Toda la documentación está en español. Los archivos en inglés del repositorio original han sido traducidos in situ.

Mapa rápido

Comienza aquí

• README principal — Visión general del proyecto, paquetes y comandos.
• QUICKSTART — Instalación, primer comando, conexión a Claude Desktop.
• ARCHITECTURE — Manual de arquitectura: capas, endpoints, decisiones clave.
• ROADMAP — Hoja de ruta operacional por fases (0-10, completadas).
• VISION — Roadmap de visión a largo plazo: qué falta para un ecosistema LLM/IA completo para TJ (reunión semanal, ministerio, audio, multilenguaje, multimodalidad, etc.).
• VISION_AUDIT — Verificación 1:1 de cada ítem de VISION contra los 12 módulos entregados en Fases 11-18.
• Overview Fases 65-76 — Familia planeada de IA agéntica + multimodal + ML clásico + voz: meta-orquestador, sparring conversacional, reasoner doctrinal CoT, coach de oratoria, búsqueda visual de Broadcasting, verificador de citas en imágenes, cámara para libros físicos, drift doctrinal, clonado de voz familiar consentida.

Manual conceptual — entender el porqué

Para colaboradores nuevos y para tomar decisiones de diseño con criterio.

• Glosario JW.org — Términos del ecosistema JW: WOL, nwtsty, JWPUB (descifrado), pub-media, lp-tag, docid, infraestructura Fase 9.
• Decisiones de diseño — Las 17 decisiones que dan forma al proyecto: por qué monorepo, agentes procedurales, FakeEmbedder, JWPUB con crédito, telemetría opt-in, etc.
• Estrategia multi-idioma — Niveles de soporte, registro Language, colisiones ortográficas.
• Inventario de endpoints — Cada endpoint externo (incluyendo weblang y los 3 patrones WOL nuevos): método, auth, payload, TTL de cache, ejemplos.
• Flujos end-to-end — Diagramas de secuencia de los flujos más comunes (incluyendo politely_get y JWPUB decryption).
• Integración con JW Library — Fase 19: cómo y por qué conectamos con la app oficial (deep links, backups, sync incremental, catálogo MEPS, Full Disk Access en macOS).
• Integración con Obsidian — Fase 20: portar utilidades del plugin obsidian-library-linker, sync bidireccional vault ↔ toolkit, plugin Obsidian propio, 17 locales de nombres de libros.
• Polyglot Python — venv per feature — Fase 53: patrón arquitectónico para usar librerías ML pesadas con cadencias de soporte de Python distintas (fairseq2 sin wheels cp313) sin atar la versión del monorepo. Subprocess + venv dedicado + contrato JSON.
• Extrapolar el toolkit a otras religiones — Visión futura: análisis de qué capas son agnósticas de religión (Plugin SDK F41, BrainDomain F49, multi-tenant F57.16, versification F46) y tres caminos posibles para reutilizar la arquitectura con católico/judío/islámico/mormón/budista. Plantillas, religiones piloto, riesgos, plan ilustrativo F65-F75.
• CI y testing — GitHub Actions workflow, suite de pruebas, sistema de cassettes pytest-recording.

Guías por tema — hacer algo concreto

Orientadas a casos de uso. Cada una es autocontenida con código de ejemplo.

• Fidelidad NLI en runtime — Fase 39: verificación NLI claim/premise sobre cada Finding; 5 providers (Claude / OpenAI / DeBERTa / Ollama / Fake) con FakeNLI siempre disponible; CLI/MCP --fidelity {off,warn,reject}.
• Content provenance (Fase 40) — trazabilidad reproducible del texto citado: 4 claves en Citation.metadata + ProvenanceValidator que re-fetcha y compara hashes + integración opt-in con Fase 39. CLI jw provenance check + MCP verify_provenance.
• Plugin SDK (Fase 41) — extension points sin forkear el monorepo: 5 entry-point groups (agents/parsers/embedders/vlm_providers/gen_providers) + CLI jw plugins {list,verify,disable} + conflict policy NAMESPACED por default. Ver también security, capabilities, authoring.
• Scaffolding de un plugin (Fase 42) — create-jw-agent (PyPI standalone) genera proyectos plugin con entry-points F41 pre-cableados en <10 min. 5 tipos (agent/parser/embedder/vlm/gen), validación PEP 503, i18n en/es/pt. Cookbook ejecutable con 12 recetas verificadas por el plugin pytest-cookbook (docs/cookbook/*.md).
• Second Brain (Fase 49) — Karpathy-style compiler + GraphRAG sobre el toolkit. Dual backend DuckDB/Neo4j, Wiki sobre Obsidian con human_edited honored, CLI jw brain {init,compile,query,lint,status,snapshot,list}, MCP second_brain_*. Multi-tenant. BrainDomain plugins via F41 (TJ builtin + financial fixture).
• Bible Knowledge Graph — Fase 58: hidrata jw-brain con personas, lugares, periodos y pasajes bíblicos desde fuentes JW puras (Insight + NWT). Atribución y separación del KG académico inter-religioso.
• Semantic chunking (Fase 45) — chunking por unidad de pensamiento: continuation/closure markers es/en/pt + LLMChunker con cache + NDCG@10 bench con per-language lift gate. CLI jw chunker-bench, MCP set_chunker. Backwards-compat byte-stable.
• Extensión WOL para el navegador — Fase 48: extensión Chrome/Edge/Firefox que añade botones inline en wol.jw.org (📖 Explicar / 🔗 Refs / 📝 Obsidian). 100% local, 3 capas de defensa contra requests externos.
• Agent tracing (Fase 43) — trazas JSONL local-first que registran cada decisión interna del agente (kept/dropped/warn/step). CLI jw apologetics --trace, viewer jw trace {view,list,gc}, MCP get_trace. Bridge OpenTelemetry opt-in bajo extra [otel].
• Synth Judge (Fase 44) — filtro de calidad 3-etapa (heurísticas always-on + LLM pedagógico opt-in + NLI Fase 39 opt-in) sobre Q&A sintético antes de data/train.jsonl. CLI --judge=off/loose/strict, env JW_SYNTH_JUDGE_LLM/NLI, per-recipe overrides, dump de rejected para audit.
• Canonical versification (Fase 46) — mapeo de referencias bíblicas entre tradiciones de numeración (nwt/masoretic/lxx/vulgate) con catálogo curado y explicaciones trilingües. CLI jw versification {map,explain,list}. Joel 2:28 ↔ Joel 3:1 (BHS), Malaquías 4 ↔ Malaquías 3:19, superscripciones de Salmos.
• jw-core-js (Fase 47 MVP) — port TypeScript de jw-core para extensión WOL, Capacitor móvil y web playground. MVP cubre parseReference, BibleRef, wolUrl, tabla 66 libros en/es/pt, versification F46. Paquete @jw-agent-toolkit/core con dual ESM+CJS, fixture compartido contra Python.
• Generador de publicaciones .jwpub (Fase 50) — port de darioragusa/html2jwpub (MIT): JwpubBuilder empaqueta HTML+media como .jwpub cifrado (SHA-256+XOR plus AES-128-CBC plus zlib). Crypto compartido jw_core.jwpub_crypto (compute_key_iv, encrypt_blob, decrypt_blob). CLI jw jwpub build.
• Schemas organized-app (Fase 51) — port a Pydantic v2 de sws2apps/organized-app (MIT): PersonType, SchedWeekType, Week IntEnum, AssignmentCode (100-300), MeetingAttendanceType, FieldServiceGroupType, UserFieldServiceMonthlyReportType (post-2023 S-21), envelope CRDT Timestamped[T]. Interop sin runtime React/Firebase.
• Escritor de backups .jwlibrary (Fase 52) — port de erykjj/jwlmanager (MIT) export pipeline: write_backup() empaqueta userData.db+manifest+SHA-256+ZIP. update_backup() para round-trip extract→modify→repack. CLI jw library {inspect,re-export,from-notes}. Closing read-write loop con la app oficial JW Library.
• Omnilingual ASR para 1672 idiomas (Fase 53) — integra facebookresearch/omnilingual-asr (Apache 2.0). Arquitectura polyglot Python: fairseq2 no tiene wheels cp313, así que el provider corre en venv Python 3.12 dedicado vía subprocess JSON. Cubre quechua, kinyarwanda, aymara, guaraní, lenguas bantúes. CLI jw omnilingual {install,status,transcribe,supports}.
• NLLB-200 translation con ref-preservation (Fase 54) — proveedor NLLBProvider con CTranslate2 INT8 (200 idiomas, CC-BY-NC-4.0). is_commercial_safe=False chequeable a runtime. translate_preserving_references() enmascara refs bíblicas antes del modelo y restaura en el idioma destino. CLI jw translate, MCP tool translate_preserving_refs.
• Wire-up multilingüe (Fase 55) — los 8 call sites que convierten F50–F54 de islas en capacidades del toolkit: router ASR/translation por idioma+licencia, jw translate, jw library, jw jwpub build, IO organized-app backup, bridge S-21, agente cross_lingual_research, broadcasting multilenguaje. 24 tests de wire-up; 1887 totales.
• Ingest de PDFs históricos y docs Office (Fase 62) — añade Atalayas escaneadas, libros JW pre-EPUB y documentos compartidos por hermanos (.docx/.pptx/.xlsx) al RAG personal vía marker + markitdown. Detección automática de firmas JW (metadata.is_jw), idempotencia por sha256, GPU/LLM opt-in. CLI jw rag ingest-pdf + jw rag ingest-office; MCP ingest_pdf + ingest_office_doc.
• Memoria persistente del asistente (Fase 61) — MemoryStore Protocol con tres backends: FakeMemoryStore (in-memory default), SqliteMemoryStore (local + Fernet opt-in via JW_MEMORY_KEY, precedente F25), LettaMemoryStore (opt-in, multi-device sync). Factory build_memory_store() env-driven (JW_MEMORY_BACKEND). Wire-up en conversation_assistant con compatibility preservada. MCP tools memory_record/recall/forget_session.
• Diarización ASR con WhisperX (Fase 64) — transcribe discursos y asambleas identificando oradores con pyannote/speaker-diarization-3.1 + word-level timestamps. DiarizedSegment extiende TranscriptionSegment sin breaking; enrichment opcional con BibleRef vía parse_all_references(). HF token gating con error claro. CLI jw audio transcribe --diarize --bible-refs; MCP transcribe_audio_diarized.
• Reunión-en-vivo: meeting-media (Fase 57) — subpkg clean-room (inspirado en M³, NO portado AGPL): descubre el programa semanal mwb/w desde WOL, descarga imágenes/videos/audio/JWPUB con cache sha256 idempotente y entrega presenter Tauri con control REST /presenter/*. CLI jw meeting {discover,download,list}; MCP meeting_discover_week/download_media/list_programs/open_presenter. Ver también análisis del HTML del WOL en Programa semanal mwb/w.
• Meta-orquestador (Fase 65) — orquesta los 12 agentes existentes en un solo comando jw plan-sunday con plan/execute/critique/replan. Plugin SDK F41 para extensión. CLI jw meta {tools,plan,run} + MCP meta_list_tools/meta_plan_goal/meta_run_plan. 55 tests passing (MVP+post-MVP cerrados).
• Talk-lab (Fase 68) — coach de oratoria multimodal: WhisperX F64 + prosodia (librosa opt + numpy fallback) + 6 counsel points pedagógicos. CLI jw talklab {analyze,history,compare,counsel-points} + MCP 3 tools. Catálogo TOML es/en/pt. Local-first, audio nunca sale del disco. 61 tests passing.
• Sparring conversacional (Fase 66) — entrena predicación contra interlocutor simulado con memoria por sesión (F61) + feedback NLI F39. 6 personas builtin con variantes es/en/pt (18 TOMLs). CLI jw spar {personas,start,turn,show,close,voice-turn} + MCP 4 tools. Voice mode F34 (ASR+TTS), MD export, golden conversations, tool spar.session en F65. 56 tests passing.
• Razonador doctrinal (Fase 67) — chain-of-thought verificable con reformulator de framing tóxico + planner LLM (es/en/pt) + ReAct executor con NLI F39 (off/warn/reject) + summary prose. CLI jw reason {ask,languages} + MCP doctrinal_reason. Integrado en F65 como reason.doctrinal. 41 tests passing.
• Búsqueda visual frame-level (Fase 69) — indexa videos locales por frame con VLM + CLIP. Búsqueda híbrida FTS5 + cosine + RRF k=60 con deep links a tv.jw.org. Frames nunca se almacenan. CLI jw broadcasting-visual {index,search,stats} + MCP 3 tools. Integrado en F65 como broadcasting.visual_search. 30 tests passing.
• Verificador de citas en imágenes (Fase 70) — defensa visual contra desinformación: preprocess + OCR + visual fingerprint + RAG/NLI inyectables → 4 veredictos discretos (SUPPORTED/DISTORTED/FABRICATED/UNVERIFIABLE). CLI jw verify-image {check,verdicts} + MCP verify_image_quote_tool. Integrado en F65 como verification.image_quote. 51 tests passing.
• Cámara para libros físicos (Fase 71) — OCR + classify_content (bible_verse/study_question/watchtower_paragraph/plain_text/unknown) + acciones contextuales (read_aloud/open_in_jw_library/open_in_wol/show_answer). CLI jw book-camera {analyze,kinds} + MCP book_camera_analyze. Integrado en F65 como book_camera.analyze. 30 tests passing.
• Análisis de drift doctrinal (Fase 72) — embeddings temporales + DBSCAN-style cosine clustering (numpy puro) sobre corpus diacrónico. Nota Prov 4:18 trilingüe SIEMPRE inyectada. CLI jw drift {analyze,note,eras} + MCP drift_analyze. Integrado en F65 como drift.analyze. 31 tests passing.
• TTS con voz familiar consentida (Fase 76) — license gate de 3 capas (deny list de nombres + consent activo + texto no comercial) + registry JSON por perfil + audit hook F43-ready + FakeVoiceProvider determinista. CLI jw voiceclone {register-from-consent,list,show,say,revoke,delete} + MCP voice_clone_{list,synthesize,audit}. 40 tests passing.
• Resolver citas bíblicas — Usar parse_reference, manejar idiomas, construir URLs.
• Usar los clientes HTTP — CDN, WOL, Mediator, PubMedia, TopicIndex: patrones comunes.
• Infraestructura Fase 9 — Cache SQLite, throttler per-host, telemetría opt-in, factory unificado.
• Construir un agente — Cómo escribir un nuevo agente procedural sobre jw-core.
• Indexar y buscar con RAG — Ingest (incluyendo JWPUB descifrado), persistencia, búsqueda híbrida, RRF, embedders.
• Embeddings y reranking — Fase 33: providers reales (BGE-M3, Cohere, Jina, Voyage, Ollama, E5) + cross-encoder reranker con auto-detect.
• Constrained decoding — Fase 35: gramáticas GBNF + Pydantic para forzar citas verificables en cualquier LLM consumidor de AgentResult.
• Extender el parser de referencias — Añadir un idioma, añadir abreviaturas, manejar casos especiales.
• Conectar el MCP a Claude Desktop — Configuración paso a paso, troubleshooting.
• Integración con JW Library — Deep links jwlibrary://, parser de backups .jwlibrary, sync incremental, catálogo MEPS docid↔pub_code, inspector local (Windows publications.db + macOS userData.db con Full Disk Access).
• Usar con Obsidian (second brain) — Setup paso a paso del plugin Obsidian: linkify, insertar versos con quote callouts, importar notas de JW Library al vault, indexar al RAG, agente LLM con vista total.
• Scripts de exploración — Los 20 scripts en scripts/: discovery de fixtures, exploración de HTML, reverse engineering JWPUB, live tests end-to-end.
• Eval doctrinal — Suite de regresión doctrinal jw-eval: 3 capas (estructural, citas, semántico), CI bloqueante + nightly.
• Fine-tuning local — Entrena tu propio modelo JW personal con jw-finetune (Unsloth + JWPUB/EPUB locales).

Guías de los módulos Fase 11-18 (VISION.md)

• Asistente de ministerio — Módulo 2: objeciones, presentaciones, revisitas, búsqueda inversa.
• Audio y voz — Módulo 3: TTS pluggable, transcripción Whisper, índice JW Broadcasting.
• Estudio personal — Módulo 4: planes lectura, notas personales, flashcards SM-2, Strong’s.
• Familia y niños — Módulo 5: lecciones, adoración familiar, quiz por edad.
• Calendario y eventos — Módulo 6: Memorial, asambleas, visita superintendente.
• Multimodalidad visual — Módulo 7: OCR, mapas bíblicos, generador de slides.
• Idiomas expandidos — Módulo 8: Tier 1 10 idiomas, sign languages, traducción preservando refs.
• Apologética avanzada — Módulo 9: fact_checker, detector de apócrifa.
• Infraestructura operacional — Módulo 10: logging estructurado, REST API, bots.
• Privacidad local-first — Módulo 11: cifrado, Ollama, audit telemetría.
• Personalización y accesibilidad — Módulo 12: profile, memoria, tono, easy-read.
• Citation integrity validator — Fase 23. Valida URLs wol.jw.org de agentes (estructural / live / drift). Hermana de Fase 22.
• Monitor de novedades — jw news digest detecta publicaciones, videos y workbooks nuevos. Local-first, determinista.
• Partes del estudiante — guion 4-sección para lectura, conversación, revisita y estudio bíblico (Fase 26).
• Concordancia exacta — jw grep literal con SQLite FTS5 sobre NWT + JWPUB + EPUB (Fase 28).
• Exportador de hoja de estudio — Fase 31: convertir cualquier AgentResult en Markdown / PDF / DOCX / Anki con citas verificables y GUIDs Anki estables (re-export idempotente).
• Temas de vida — Fase 32: asistente life_topics informativo con citas + redirect a ancianos en temas sensibles. Nunca sustituye consejería pastoral.

Referencia exhaustiva — cada función documentada

Documentación módulo a módulo, clase a clase, función a función. Incluye firmas, parámetros, retornos, excepciones y ejemplos.

• jw-core — Modelos, parsers (incluyendo JWPUB con decryption), 6 clientes HTTP (CDN, WOL, Mediator, PubMedia, TopicIndex, Weblang), infraestructura Fase 9 (auth, cache, throttle, telemetry, _polite, factory), languages, data/books.
• jw-cli — Los 8 comandos (verse, chapter, daily, search, languages, download, jwpub, topic) con sus opciones y códigos de salida.
• jw-mcp — Las 29 herramientas MCP con contratos completos.
• jw-rag — VectorStore, Embedder, chunker, ingest (incluyendo ingest_jwpub y ingest_epub), retrieve.
• jw-agents — verse_explainer, research_topic, meeting_helper, apologetics.
• integraciones — Fase 19: capa jw_core.integrations (deep links, sync incremental, catálogo MEPS, inspector local + FDA macOS) y parser .jwlibrary.

Convenciones

• Idioma: todo en español. Términos técnicos del código (nombres de clases, funciones, parámetros) se conservan en su forma original.
• Diagramas: ASCII art primero; Mermaid solo donde la complejidad lo justifique.
• Ejemplos: ejecutables. Los snippets Python asumen el monorepo instalado con uv sync --all-packages.
• Rutas: relativas a la raíz del repo cuando empiezan por packages/, docs/ o scripts/. Absolutas cuando son URLs.
• Versiones: la documentación refleja el estado al 2026-05. Los cambios estructurales se reflejan aquí antes que en el código.