Data Olympus

data-olympus

¿Eres nuevo? Empieza con WHY.md. Es la historia detrás del proyecto: el problema que seguíamos encontrando con los agentes de codificación, qué hace data-olympus de manera diferente, cómo se relaciona con el Open Knowledge Format de Google, y dónde dicen nuestros benchmarks que es fuerte y dónde no. El resto de este README es la referencia técnica.

data-olympus es un formato de base de conocimiento y servidor de grado de gobernanza para fuerzas de trabajo de agentes. Es legible por consumidores de Open Knowledge Format (OKF) v0.2: hereda la estructura de directorios de OKF, las convenciones de frontmatter, los nombres de archivo reservados y el modelo de enlaces, y luego añade extensiones de gobernanza encima (id estable, campos controlados type/status/tier, cadenas supersedes) además de un servidor MCP de escritor único y un CLI. CI demuestra dos direcciones concretas contra el commit oficial de Google OKF v0.2 ad30107c31c06aec8a7d5636e0d1058118604e6f: su consumidor de visualización de referencia lee cada concepto en example-bundle, y data-olympus importa, lint, indexa, busca y recupera la muestra oficial de Bitcoin fijada. Esta es evidencia de interoperabilidad limitada a fixtures, no una garantía general para cada paquete OKF o revisión futura ascendente. El resultado es un grafo de documentos versionado y nativo de git de estándares de ingeniería, decisiones arquitectónicas y conocimiento del proyecto que agentes y humanos pueden leer, buscar y extender sin ningún servicio propietario.

Gobierna decisiones, no código. Cuando un agente está a punto de tomar una elección (una biblioteca, un patrón, una migración), data-olympus saca a la superficie el estándar establecido o la decisión que debería gobernar esa elección. Deliberadamente no es una herramienta de búsqueda de código, búsqueda de referencias o "dónde se usa X": LSP, grep y Sourcegraph ya hacen eso bien. La tarea de recuperación a la que apunta es de intención de codificación a regla gobernante, y ayuda donde la interacción actual del modelo durante el vibe-coding es más débil: mantener el modelo alineado con los patrones que el equipo ya ha establecido como correctos.

Estado: beta pre-1.0. Las versiones estables se distribuyen a través de PyPI y GHCR.

Por qué

• Portátil, sin bloqueo. Toda la KB es un directorio de archivos markdown en git. Sin base de datos, sin esquema propietario, sin proveedor.
• Diffs y revisión nativos de git. Cada cambio es un commit. Las ediciones propuestas pasan por una cola pendiente antes del commit; el historial es un simple git log.
• Legible por agentes y humanos. Markdown simple con frontmatter YAML. No se requiere SDK para leer o redactar un documento.
• Escrituras multi-agente gobernadas. El pipeline MCP de escritor único (bloqueos de asesoría, worktrees por sesión, cola de push duradera) previene carreras de escritura concurrentes sin requerir infraestructura de bloqueo distribuido.
• Consultable por estado, nivel y tipo. Filtra por status: accepted, tier: T1 o type: decision sin post-procesamiento. La cadena supersedes permite rastrear el historial de decisiones a través del grafo.
• Probado con herramientas oficiales de OKF. CI fija una revisión exacta de Google OKF y demuestra ambas direcciones de consumo sobre fixtures comprometidos. El pin, el checksum del fixture y la procedencia de la licencia Apache 2.0 viven en tests/okf/reference.json.

Inicio rápido

Requiere Python 3.13+ y uv. Ejecuta el CLI estable directamente desde PyPI:

uvx --from data-olympus data-olympus --help

Instálalo de forma persistente cuando estés listo para crear un bundle y ejecutar el servidor:

uv tool install data-olympus
data-olympus init my-kb
data-olympus-mcp --help

Un candidato anunciado permanece opt-in a través de su versión exacta de PyPI. Reemplaza X.Y.ZrcN con el candidato nombrado en la página de versiones, si lo hay:

uvx --from 'data-olympus==X.Y.ZrcN' data-olympus --help

Consulta canales de versión para saber qué significa cada canal, cómo verificar un candidato antes de adoptarlo y cómo revertir.

Consulta docs/quickstart.md para la inicialización del bundle, el arranque del servidor, la preparación, el registro de agentes y la instalación de fuentes del contribuidor.

Consulta docs/adoption.md para la guía completa de autoría de bundles.

Documentación

• SPEC.md: especificación del formato (disposición del bundle, esquema de frontmatter, contratos de servicio).
• docs/quickstart.md: procedimiento verificado de ejecución local.
• docs/adoption.md: guía de trae-tu-propia-KB (autor, lint, indexa, sirve, conecta un agente).
• docs/serving.md: modelo de servicio de réplica única, réplicas de solo lectura, bucle de git pull, división de salud/preparación/viveza, cabeceras de proxy, rotación de registros de auditoría.
• docs/operations.md: runbook de producción — copia de seguridad, actualización, playbooks de recuperación (degradado/fallo de fetch, reescritura de historial, entradas de push congeladas/despromovidas, bloqueos huérfanos), el modelo de salud/alertas y los canales de versión (estable y candidato, verificación, reversión).
• docs/comparison.md: cómo se relaciona data-olympus con OKF, catálogos empresariales, herramientas de KB markdown, convenciones de contexto de agentes, RAG y herramientas de ADR.
• docs/okf-profile.md: perfil OKF campo por campo — qué extensiones de gobernanza son estables, cuáles son solo campos de servicio en tiempo de ejecución y cuáles son candidatos experimentales.
• docs/glama.md: notas de reclamación, versión y mantenimiento de puntuación del registro Glama.
• docs/mcp-registry.md: notas oficiales del Registro MCP, qué declara server.json y la lista de verificación para publicar.
• docs/enforcement.md: convertir la KB en una puerta de consulta obligatoria (hooks, kb enforce).
• benchmarks/README.md: metodología del benchmark de recuperación y cómo reproducir los números en docs/comparison.md.
• SECURITY.md: versiones soportadas y cómo reportar una vulnerabilidad.

Licencia

Apache 2.0. Consulta LICENSE y NOTICE.