Biblioteca — Referencia Tecnica

Biblioteca — Referencia Tecnica

Sistema de grafo de conocimiento que mapea codigo fuente a documentacion. Almacenado en D1 (workspace). Accesible via 26 MCP tools (bib_*). Fecha de creacion: 13-04-2026 | Autor: Edu Graphify: 16-04-2026 — hibridacion con ideas de Graphify (AST profundo, confianza, comunidades)

1. Arquitectura

CreaRack-Pro (Claude Code)
       |
       | llama bib_context_query / bib_impact_query via MCP
       |
Workspace MCP Server (Cloudflare Pages Function)
       |  handlers/biblioteca.ts
       |
Cloudflare D1 — tablas bib_* (9 tablas)

Principio: El contexto de desarrollo se consulta bajo demanda en vez de cargarse estaticamente. CLAUDE.md ya no incluye @ de archivos pesados — la Biblioteca los reemplaza como fuente de verdad consultable.

2. Schema D1

bib_nodes — Nodos del grafo

Cada artefacto indexado (endpoint, modelo, servicio, schema, doc) es un nodo.

| community_id | INTEGER FK | ID de comunidad (Label Propagation, NULL si sin cluster) |

Indices: qualified_name (UNIQUE), node_type, app, file_path, community_id.

bib_edges — Relaciones

Tipos de edge:

• documents — un doc describe un artefacto de codigo
• uses_model — un endpoint/servicio usa un modelo (FK)
• calls_service — un endpoint delega a un servicio
• defines_schema — un schema Pydantic define I/O de un endpoint
• imports, signals, tests, renders_template
• calls — una funcion llama a otra (del AST, mas granular que calls_service)
• inherits — una clase extiende otra (herencia Python)
• contains — un modulo contiene clases/funciones, una clase contiene metodos
• semantically_similar_to — links conceptuales cross-file (futuro, LLM)

Indice UNIQUE en (source_id, target_id, edge_type).

bib_docs — Metadatos de documentos

Tabla extendida para docs markdown con titulo, categoria, secciones H2, apps mencionadas, word count.

bib_endpoints — Metadatos de endpoints

Tabla extendida para endpoints con method, path, operation_id, tags, request/response schema.

bib_agents — Jerarquia de agentes

Flujo de informacion: consultar lateralmente o hacia abajo, informar siempre hacia arriba. El agente-usuario esta completamente aislado (sin acceso a internals).

bib_index_runs — Auditoria de indexaciones

Cada ejecucion de indexacion se registra con tipo, status, contadores, errores, duracion.

bib_change_log — Cambios detectados

Registro de cambios en nodos entre indexaciones (hash cambio, campo modificado).

bib_communities — Comunidades detectadas (Label Propagation)

Resultado de la deteccion automatica de clusters en el grafo.

bib_federation — Multi-biblioteca (futuro)

Preparado para gestionar bibliotecas de multiples productos desde el workspace central.

3. MCP Tools (26)

Consulta (alta frecuencia, read-only)

Mutacion (Bibliotecario/Escribas)

Indexacion (Libreros, batch)

Comunidades (Graphify)

Administracion

4. Contenido indexado

Pre-AST (13-04-2026)

Post-AST (16-04-2026, estimado tras primera indexacion)

Fuentes de datos

1. OpenAPI JSON — extraido de produccion via SSH (api.get_openapi_schema())
2. Modelos Django — extraidos de models.py de las 7 apps por agentes Explore
3. Documentos markdown — escaneados de wiki + root docs, con deteccion de menciones
4. AST Python — scripts/bib_ast.py extrae clases, funciones, metodos, imports, calls, herencia con el modulo ast builtin (zero deps)

5. Flujo de trabajo

Pre-edicion (antes de modificar codigo)

Claude Code: bib_context_query(topic="monitoring")
Biblioteca:  {
  models: [MonitoringTarget, MetricSample, MonitoringAlert, ...],
  endpoints: [GET:/api/monitoring/targets, POST:/api/monitoring/alerts, ...],
  key_docs: [dev-observatory.md, CNS_GUIDE.md, ...],
  app_summary: {endpoints: 175, models: 19}
}

Pre-commit (saber que docs actualizar)

Claude Code: bib_impact_query(file_path="monitoring/services/alert_service.py")
Biblioteca:  {
  direct_docs: ["dev-observatory.md", "CNS_GUIDE.md", ...],
  related_models: ["MonitoringAlert", "AlertEvent", ...],
  update_checklist: ["CHANGELOG.md", "dev-observatory.md", ...]
}

Post-commit (marcar docs para revision)

Claude Code: bib_report_change(file_path="monitoring/services/alert_service.py", change_type="modified")
Biblioteca:  {
  affected_nodes: 5,
  flagged_docs: [{file_path: "dev-observatory.md", title: "..."}],
  action_needed: "Actualizar 3 documento(s) vinculado(s)"
}

6. Reindexacion

La Biblioteca se puede reindexar en ~3 minutos (6 fases):

1. OpenAPI: Extraer JSON via SSH + enviar a bib_index_openapi en batches de 40
2. Modelos: Script Python que registra modelos + FK edges via bib_index_code
3. AST: python scripts/bib_ast.py --push — extrae estructura del codigo Python (clases, funciones, imports, call graphs) y envia a bib_index_ast
4. Docs: Script Python que escanea markdown + detecta menciones via bib_index_docs
5. Chunks: Embeddings para busqueda semantica via bib_index_chunks
6. Comunidades: bib_compute_communities() — detecta clusters en el grafo via Label Propagation

Script AST (scripts/bib_ast.py)

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, enviar al MCP

Usa el modulo ast builtin de Python (zero deps). Extrae: modulos, clases (con deteccion de Django models), metodos, funciones, imports, herencia, call graphs. Cache SHA256 por archivo para modo incremental.

Cuando reindexar: Tras anadir nuevos modelos, endpoints o docs significativos. El AST puede correrse en modo incremental. Las comunidades se recomputan al final.

Deteccion de staleness: bib_stale_report(days_threshold=7) muestra nodos no reindexados recientemente o con content_hash nulo.

Reindex automático (desde 2026-04-21)

El reindex corre cada 10 min en Hetzner Staging via /etc/cron.d/bib-reindex. Antes vivía en el Task Scheduler del PC de Edu (diario 04:00 Windows). La migración resuelve la dependencia de equipos individuales: el grafo evoluciona aunque Edu/Dani tengan el portátil apagado. Detalles de instalación: ver Dokploy Internals §11.

Footgun conocido: D1 bind-param overflow (resuelto 2026-04-21)

El handler bib_index_ast tenía un CHUNK = 500 para las queries WHERE qualified_name IN (?,?,...), pero Cloudflare D1 limita a ~100 bind params por query (no 999 como SQLite vanilla). Apps con más de 100 qualified_names (core 292, terminal 596, monitoring 545) hacían que el handler devolviera HTTP 200 con errors: ["fatal: Error: D1_ERROR: too many SQL variables"] y cero inserts. El script bib_ast.py trataba 200 como éxito, así que el log diario decía [OK] mientras el grafo llevaba semanas estancado. Fix:

• Handler: separar CHUNK_IN = 90 (IN clauses, cuentan contra el budget D1) y CHUNK_BATCH = 500 (db.batch(), cada stmt tiene su propio budget aislado).
• Script: desenvolver el body del MCP, chequear errors[] y el guard “accepted but 0 inserts” → exit ≠ 0 si el cron no insertó nada.

Commit raíz: workspace@af73a3e + CreaRack-Pro@2794b9f.

7. UI del grafo (/biblioteca)

Fase 1 completada (13-04-2026). Pagina en el workspace con 4 vistas.

URL: https://workspace.crearack.com/biblioteca

Vistas

REST API endpoints (4)

Archivos frontend (6)

Nota sobre coverage

El MCP handler (bib_doc_coverage) tiene un bug de rendimiento N+1: hace un query por nodo para verificar si tiene edge documents. El REST endpoint /api/biblioteca/coverage lo resuelve con una subquery EXISTS en un solo SELECT.

8. Archivos del sistema

9. Notas tecnicas

• D1 size: ~0.8MB (de 10GB limite). Crecimiento negligible.
• Latencia: ~200ms por query simple, ~2-7s por indexacion batch de 40 items.
• User-Agent: Cloudflare WAF bloquea Python-urllib. Usar siempre User-Agent: CreaRack-Biblioteca/1.0.
• [skip ci]: Cloudflare Pages respeta [skip ci] en commits — no hace build. Evitar en pushes que necesiten deploy.
• Tokens MCP: Rotados 13-04-2026. Formato Edu:token,Dani:token,Txell:token en env var MCP_TOKENS de CF Pages.
• Activity logging: Las 8 tools de escritura se registran automaticamente en activity_log via LOGGED_TOOLS.

Mantenido por: Claude (Anthropic) + Equipo CreaRack Ultima actualizacion: 16-04-2026 (Graphify — AST, confianza, comunidades)

Véase también

• [[concept—biblioteca—supercontexto]] — sistema Biblioteca Supercontexto — grafo + Archivo Maestro + wiki
• [[crearack-tech—guides—biblioteca-guide]] — guía de uso de la Biblioteca
• [[ia-tech—biblioteca—architecture]] — arquitectura de la Biblioteca
• [[feature—supercontext—fase-4-query-con-cierre]] — Supercontexto Fase 4 — Query con cierre
• [[feature—supercontext—fase-6-metricas-utility]] — Supercontexto Fase 6 — Métricas utility
• [[feature—biblioteca—graphify]] — Graphify — AST extractor
• [[runbook—biblioteca—manual-reindex]] — runbook de reindexado manual
• [[incident—20260421—d1-bind-overflow-silent]] — incidente D1 bind overflow silencioso