Biblioteca · Arquitectura del Knowledge Graph

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 settings
views.py, htmx_views.py, views_publish* — URL routing
signals.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 JSON
bib_index_code — modelos, servicios, signals
bib_index_ast — clases, funciones, imports, call graphs (Python AST)
bib_index_docs — documentos markdown
bib_index_chunks — embeddings para busqueda semantica
bib_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 cambiados

Extrae: 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

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 a src/components/dashboard/)
health-api.ts — GET endpoint que alimenta el widget (copiar a functions/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 ast builtin (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]]