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: OpenAPI + Code + AST + Docs + Chunks)
Knowledge Graph (nodos + edges + confianza + comunidades)
↓ (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 fuente) |
| 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 (imports) | EXTRACTED |
| inherits | class → base class | EXTRACTED |
| contains | module → class, class → method | EXTRACTED |
| defines_schema | schema → endpoint | EXTRACTED |
| semantically_similar_to | concept → concept (LLM) | 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
- AMBIGUOUS (score 0.2) — requiere revision humana
El BFS de bib_impact_query soporta filtro min_confidence para excluir edges poco fiables.
Comunidades
Deteccion automatica de clusters via Label Propagation (in-worker, TypeScript):
- Cohesion: densidad de edges internas vs totales
- Bridge nodes: nodos con conexiones a 3+ comunidades
- Coupling report: pares de comunidades con mayor acoplamiento
Code Health (inspirado en TrueCourse)
Tres analisis automaticos sobre el grafo existente:
| Analisis | Que detecta | Por que importa |
|---|---|---|
| Ciclos | A→B→C→A en imports/calls (DFS) | Dependencias circulares impiden modularizar |
| God nodes | Nodos con degree >= 15 | Hotspots que acoplan todo el sistema |
| Dead code | Nodos sin incoming calls/imports | Codigo que nadie usa, ruido en el grafo |
God nodes se clasifican en:
- dependency_magnet: muchos incoming (todo depende de el)
- dependency_spreader: muchos outgoing (depende de todo)
- balanced: alto degree bidireccional
Precision del detector de dead code
El detector filtra automaticamente patrones de framework (Django/Ninja) que parecen dead code pero estan vivos por diseno:
Filtros SQL (por file_path):
middleware/,management/commands/,templatetags/— wired via settingsviews.py,htmx_views.py,views_publish*— URL routingsignals.py,adapters.py,events.py— framework hooks*_api.py,/api/— endpoints HTTP (Ninja/DRF)/services/— service layer (siempre llamado desde endpoints)consumers.py— Django Channels (ASGI routing)tasks.py— Huey/Celery (task scheduler)terminal/agent/— standalone executables con conditional imports
Filtros metadata (por decorators/bases/nombre):
- HTTP decorators:
get,post,put,patch,delete - Framework decorators:
receiver,db_task,db_periodic_task - Pydantic bases:
Schema,ModelSchema,FilterSchema - Framework bases:
Command,Adapter,AppConfig - Dunder methods, ORM methods (
save/delete/clean) resolve_*validators, inner functions (decorator/wrapper)- Framework decorators preparados (
tracked_task,tenant_throttle)
Filtro de ancestros:
- Si CUALQUIER ancestro (modulo, paquete, clase) tiene incoming imports, el nodo es reachable
Exclusion por tipo:
- Todos los models (tienen migraciones, vivos por definicion)
- endpoints, schemas, modules, docs (tipos estructurales)
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 |
Python ast builtin | Extraccion AST (zero deps) | tree-sitter (multi-lenguaje) |
MCP Tools (29)
Consulta
| Tool | Proposito |
|---|---|
bib_context_query | Briefing de un modulo (modelos, endpoints, docs) |
bib_impact_query | Que docs afecta un cambio de archivo (con min_confidence) |
bib_search_nodes | Buscar nodos por nombre/tipo/app |
bib_get_node | Detalle de un nodo con relaciones (incluye confidence) |
bib_app_summary | Resumen de una app |
bib_list_endpoints | Listar endpoints con filtros |
bib_doc_coverage | Que tiene y que falta documentacion |
bib_call_graph | Trazar callers/callees de una funcion |
bib_stale_report | Nodos desactualizados |
bib_stats | Estado general (nodos, edges, confidence, comunidades) |
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 |
Comunidades (Graphify)
| Tool | Proposito |
|---|---|
bib_compute_communities | Detectar clusters via Label Propagation |
bib_get_community | Detalle de una comunidad o comunidad de un nodo |
bib_coupling_report | Acoplamiento entre comunidades, bridge nodes |
Code Health (TrueCourse-inspired)
| Tool | Proposito |
|---|---|
bib_cycle_report | Dependencias circulares (DFS en imports/calls) |
bib_god_nodes | Nodos con degree >= 15 (hotspots arquitectonicos) |
bib_dead_code | Nodos sin incoming calls/imports (posible dead code) |
Indexacion
| Tool | Proposito |
|---|---|
bib_index_openapi | Indexar endpoints desde OpenAPI JSON |
bib_index_code | Indexar modelos/servicios en batch (con confidence) |
bib_index_ast | Indexar AST Python (clases, funciones, imports, calls) |
bib_index_docs | Indexar documentos markdown en batch |
bib_full_reindex | Guia de reindexacion completa (6 fases) |
Mantenimiento
| Tool | Proposito |
|---|---|
bib_register_node | Registrar nuevo nodo (upsert) |
bib_create_edge | Crear relacion (con confidence EXTRACTED/INFERRED/AMBIGUOUS) |
bib_remove_edge | Eliminar relacion |
bib_register_doc | Registrar documento con metadatos |
bib_report_change | Marcar docs para revision tras commit |
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 | Despues de commit | bib_report_change(file_path="<ruta>") |
Reindexacion (6 fases)
bib_index_openapi— endpoints + schemas del OpenAPI JSONbib_index_code— modelos, servicios, signalsbib_index_ast— clases, funciones, imports, call graphs (Python AST)bib_index_docs— documentos markdownbib_index_chunks— embeddings para busqueda semanticabib_compute_communities— deteccion de clusters
Extractor AST
Script Python que usa ast builtin (zero deps):
python scripts/bib_ast.py --stats # Solo estadisticas
python scripts/bib_ast.py --output ast.json # JSON a archivo
python scripts/bib_ast.py --apps racks,monitoring # Solo ciertas apps
python scripts/bib_ast.py --incremental --push # Solo archivos cambiadosExtrae: modulos, clases (detecta Django models por herencia), metodos, funciones, imports, herencia, call graphs. Cache SHA256 por archivo para modo incremental.
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, 15 inherits, 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
Widget: Salud del Sistema
Dashboard widget (React) que muestra 3 indicadores de salud:
| Indicador | Que muestra | Semaforo |
|---|---|---|
| Backup D1 | Ultimo export + filas totales | Verde <48h, Rojo >48h |
| Biblioteca | % nodos actualizados (stale check diario) | Verde >=80%, Naranja >=50%, Rojo <50% |
| Grafo | Nodos, comunidades, cohesion media | Verde >=80%, Naranja >=50%, Rojo <50% |
Archivos:
health-widget.tsx— Componente React (copiar asrc/components/dashboard/)health-api.ts— GET endpoint que alimenta el widget (copiar afunctions/api/maintenance/status.ts)stale-check-api.ts— POST endpoint para health check diario via cron
Prerequisitos: tablas activity_log, bib_nodes, bib_edges, bib_communities.
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
- [[ia-tech—metodo—claude-method-guide]]
- [[ia-tech—metodo—quick-start]]
- [[ia-tech—metodo—harness-engineering]]
- [[crearack-tech—guides—biblioteca-staff-guide]]
- [[crearack-tech—method—harness-guide]]