Biblioteca — Hypercontexto
Concepto
La Biblioteca es un grafo de conocimiento que mapea codigo a documentacion. Permite al agente IA consultar contexto de forma precisa sin cargar toda la documentacion en la ventana de contexto.
Problema que resuelve: En proyectos grandes (500+ endpoints), la documentacion supera la ventana de contexto. La Biblioteca permite consultar solo lo relevante, bajo demanda.
Arquitectura
Codigo fuente
↓ (indexacion)
Knowledge Graph (nodos + edges)
↓ (busqueda)
MCP Tools (bib_*)
↓ (respuesta)
Claude Code (contexto bajo demanda)Nodos
| Tipo | Ejemplo | Fuente |
|---|---|---|
| endpoint | GET /api/users/ | OpenAPI |
| model | User | Code + AST |
| service | AuthService | Code |
| schema | UserOut | OpenAPI |
| template | dashboard.html | Code |
| js_module | ApiService.js | Code |
| doc | AUTHENTICATION.md | Doc indexer |
| module | racks.models | AST (archivo .py) |
| class | RackService | AST (clase no-modelo) |
| method | Device.get_power_usage | AST (metodo) |
| function | rack_list | AST (funcion standalone) |
Edges (relaciones)
| Relacion | Ejemplo | Confidence |
|---|---|---|
| documents | doc → endpoint | EXTRACTED |
| uses_model | endpoint → model | EXTRACTED |
| calls_service | endpoint → service | EXTRACTED |
| calls | function → function (AST call graph) | EXTRACTED |
| imports | module → module (Python imports) | EXTRACTED |
| inherits | class → base class | EXTRACTED |
| contains | module → class, class → method | EXTRACTED |
| defines_schema | schema → endpoint | EXTRACTED |
| semantically_similar_to | concept → concept (futuro) | INFERRED |
Confianza en edges
Cada relacion tiene un nivel de confianza:
- EXTRACTED (score 1.0) — determinista, del AST o indexacion directa
- INFERRED (score 0.5) — inferido por LLM (futuro)
- AMBIGUOUS (score 0.2) — requiere revision humana
El BFS de bib_impact_query soporta filtro min_confidence para excluir edges poco fiables.
Stack recomendado
| Componente | Rol | Alternativas |
|---|---|---|
| Cloudflare D1 | Almacenamiento del grafo | SQLite, PostgreSQL |
| Workers AI (bge-m3) | Embeddings para busqueda semantica | OpenAI embeddings |
| Cloudflare Pages Functions | MCP server | Express, FastAPI |
| Gemini Flash | Sintesis de respuestas (ask) | Claude Haiku |
MCP Tools
Consulta
| Tool | Proposito |
|---|---|
bib_context_query | Briefing de un modulo (modelos, endpoints, docs) |
bib_impact_query | Que docs afecta un cambio de archivo |
bib_search_nodes | Buscar nodos por nombre/tipo/app |
bib_get_node | Detalle de un nodo con relaciones |
bib_app_summary | Resumen de una app |
bib_doc_coverage | Que tiene y que falta documentacion |
bib_stale_report | Nodos desactualizados |
bib_stats | Estado general del grafo |
Busqueda semantica (Archivo Maestro)
| Tool | Proposito |
|---|---|
bib_search_semantic | Busqueda vectorial por embeddings |
bib_ask | Pregunta en lenguaje natural → respuesta sintetizada |
bib_index_chunks | Indexar documentos con embeddings |
Graphify (AST + Comunidades)
| Tool | Proposito |
|---|---|
bib_index_ast | Indexar estructura de codigo Python (clases, funciones, calls, imports) |
bib_call_graph | Trazar callers/callees de una funcion |
bib_compute_communities | Detectar clusters via Label Propagation |
bib_get_community | Detalle de una comunidad o comunidad de un nodo |
bib_coupling_report | Detectar acoplamiento entre comunidades |
Mantenimiento
| Tool | Proposito |
|---|---|
bib_register_node | Registrar nuevo nodo |
bib_create_edge | Crear relacion (con confidence) |
bib_report_change | Marcar docs para revision tras commit |
bib_index_code | Indexar modelos/servicios en batch |
Flujo obligatorio en cada commit
| Paso | Cuando | Tool |
|---|---|---|
| 1. Contexto | Antes de editar | bib_context_query(topic="<app>") |
| 2. Impacto | Antes de commit | bib_impact_query(file_path="<ruta>") |
| 3. Reporte | Antes de commit (Fase 2 Supercontexto — Abril 2026) | bib_report_change(file_path="<ruta>", change_type="modified") |
Cambio 2026-04-20: el Paso 3 pasa de “despues de commit” a “antes de commit”. El hook scripts/harness/bib_report_check.py (instalado vía claude-method/harness/install_hooks.sh) bloquea el commit si un archivo de codigo MODIFIED no tiene bib_report_change en los ultimos 10 minutos. Bypass puntual: BIB_SKIP=1 git commit (el bypass queda registrado en /biblioteca/pulse).
Robustez del handler bib_report_change (fix 2026-04-20)
Dos bugs descubiertos durante el rodaje de Fase 2 y corregidos en el commit f34983e:
-
Chunking D1 bind limit:
bfsImpactahora trocea las queries conIN (...)en batches de 90. Archivos con muchos nodos (ej.core/models.pycon 26+ modelos) dejaron de dispararD1_ERROR: too many SQL variables. -
Registro sin nodos indexados: si el archivo no tiene nodos todavia (archivo nuevo, reindex pendiente), el handler crea igualmente una entrada centinela en
bib_index_runs+bib_change_log(node_id NULL, new_value=file_path)./api/biblioteca/recent-reportsusa LEFT JOIN + COALESCE para verlos. Consecuencia: el hook pre-commit no bloquea archivos nuevos-y-luego-modificados aunque el reindex aun no los haya recogido.
Endpoints de soporte (añadidos Abril 2026)
| Endpoint | Auth | Proposito |
|---|---|---|
GET /biblioteca/hot + /api/biblioteca/hot | CF Access / Bearer | Hot cache del proyecto (actividad, alertas, tareas, grafo, commits, drift, bypasses) |
GET /api/biblioteca/recent-reports?since=N | Bearer | Paths con bib_report_change en los ultimos N segundos. Consumido por bib_report_check.py |
GET /biblioteca/drift + /api/biblioteca/drift | CF Access / Bearer | Snapshot de docs desactualizados |
POST /api/biblioteca/drift-run?dry_run=0|1 | Bearer | Ejecuta drift + persiste alert rolling. Invocado por cron diario |
POST /api/biblioteca/skip-log | Bearer | Registra bypasses de BIB_SKIP en activity_log |
Resultados reales
En CreaRack Pro (Abril 2026):
- ~3100 nodos indexados (496 endpoints, 198 schemas, 79 modelos, 168 docs, 256 modulos, 308 clases, 588 metodos, 981 funciones)
- ~7500 edges (3339 calls, 1956 contains, 641 imports, 1577 anteriores)
- 1489 chunks con embeddings
- Busqueda semantica sobre 58 paginas de wiki
- Comunidades auto-detectadas via Label Propagation
- Confianza EXTRACTED/INFERRED/AMBIGUOUS en cada edge
Origen: Graphify
Ideas adaptadas de safishamsi/graphify:
- AST profundo con
astbuiltin (en vez de tree-sitter) — zero deps, Python-only - Confianza en edges — score 0.0-1.0 por relacion
- Deteccion de comunidades — Label Propagation en TypeScript (in-worker, <100ms)
Véase también
- [[crearack-tech—backend—biblioteca]]
- [[concept—workspace—supercontexto-02-bibliotecario]]
- [[crearack-tech—guides—biblioteca-guide]]