Data Olympus

data-olympus

Novo aqui? Comece com WHY.md. É a história por trás do projeto: o problema que continuávamos enfrentando com agentes de codificação, o que o data-olympus faz de diferente, como ele se relaciona com o Open Knowledge Format do Google, e onde nossos benchmarks indicam que ele é forte e onde não é. O restante deste README é a referência técnica.

O data-olympus é um formato de base de conhecimento e servidor de nível de governança para forças de trabalho de agentes. Ele é legível por consumidores do Open Knowledge Format (OKF) v0.2: ele herda a estrutura de diretórios do OKF, convenções de frontmatter, nomes de arquivos reservados e modelo de links, e então adiciona extensões de governança por cima (id estável, campos controlados type/status/tier, cadeias supersedes) além de um servidor MCP de escrita única e uma CLI. A CI prova duas direções concretas contra o commit oficial ad30107c31c06aec8a7d5636e0d1058118604e6f do Google OKF v0.2: seu consumidor de visualização de referência lê cada conceito em example-bundle, e o data-olympus importa, faz lint, indexa, pesquisa e recupera a amostra oficial fixada do Bitcoin. Esta é uma evidência de interoperabilidade limitada a fixtures, não uma garantia geral para cada pacote OKF ou revisão futura upstream. O resultado é um grafo de documentos versionado e nativo em git, contendo padrões de engenharia, decisões de arquitetura e conhecimento de projeto que agentes e humanos podem ler, pesquisar e estender sem qualquer serviço proprietário.

Ele governa decisões, não código. Quando um agente está prestes a fazer uma escolha (uma biblioteca, um padrão, uma migração), o data-olympus apresenta o padrão ou decisão estabelecida que deve governar essa escolha. Ele deliberadamente não é uma ferramenta de busca de código, localização de referências ou "onde X é usado": LSP, grep e Sourcegraph já fazem isso bem. A tarefa de recuperação que ele visa é intenção de codificação para regra de governança, e ele ajuda onde a interação atual do modelo durante a codificação por vibração é mais fraca: mantendo o modelo alinhado aos padrões que a equipe já estabeleceu como corretos.

Status: beta pré-1.0. Lançamentos estáveis são distribuídos via PyPI e GHCR.

Por quê

• Portátil, sem lock-in. Toda a KB é um diretório de arquivos markdown em git. Sem banco de dados, sem esquema proprietário, sem fornecedor.
• Diffs e revisão nativos em git. Cada mudança é um commit. Edições propostas passam por uma fila pendente antes do commit; o histórico é um simples git log.
• Legível por agentes e humanos. Markdown simples com frontmatter YAML. Nenhum SDK é necessário para ler ou criar um documento.
• Escritas multi-agente governadas. O pipeline MCP de escrita única (locks de aviso, worktrees por sessão, fila de push durável) previne corridas de escrita concorrentes sem exigir infraestrutura de locking distribuído.
• Consultável por status, nível e tipo. Filtre por status: accepted, tier: T1 ou type: decision sem pós-processamento. A cadeia supersedes permite rastrear o histórico de decisões através do grafo.
• Testado com ferramentas oficiais do OKF. A CI fixa uma revisão exata do Google OKF e prova ambas as direções de consumo sobre fixtures commitados. O pin, o checksum do fixture e a proveniência da licença Apache 2.0 vivem em tests/okf/reference.json.

Início rápido

Requer Python 3.13+ e uv. Execute a CLI estável diretamente do PyPI:

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

Instale-o persistentemente quando estiver pronto para criar um bundle e executar o servidor:

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

Um candidato anunciado permanece opt-in através de sua versão exata no PyPI. Substitua X.Y.ZrcN pelo candidato nomeado na página de lançamentos, se houver:

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

Veja canais de lançamento para saber o que cada canal significa, como verificar um candidato antes de adotá-lo e como fazer rollback.

Veja docs/quickstart.md para inicialização do bundle, inicialização do servidor, prontidão, registro de agentes e instalação da fonte do contribuidor.

Veja docs/adoption.md para o guia completo de autoria de bundles.

Documentação

• SPEC.md: especificação do formato (layout do bundle, esquema de frontmatter, contratos de serviço).
• docs/quickstart.md: procedimento verificado de execução local.
• docs/adoption.md: guia traga-sua-própria-KB (autoria, lint, indexação, serviço, conexão de um agente).
• docs/serving.md: modelo de serviço de réplica única, réplicas somente leitura, loop de git pull, divisão health/readiness/liveness, cabeçalhos de proxy, rotação de log de auditoria.
• docs/operations.md: runbook de produção — backup, upgrade, playbooks de recuperação (degradado/falha de fetch, reescrita de histórico, entradas de push congeladas/rebaixadas, locks órfãos), o modelo de health/alerting e canais de lançamento (estável e candidato, verificação, rollback).
• docs/comparison.md: como o data-olympus se relaciona com OKF, catálogos empresariais, ferramentas de KB markdown, convenções de contexto de agente, RAG e ferramentas de ADR.
• docs/okf-profile.md: perfil OKF campo a campo — quais extensões de governança são estáveis, quais são campos de serviço somente em tempo de execução e quais são candidatos experimentais.
• docs/glama.md: reivindicação de registro Glama, lançamento e notas de manutenção de pontuação.
• docs/mcp-registry.md: notas oficiais do MCP Registry, o que server.json declara e o checklist para publicação.
• docs/enforcement.md: transformando a KB em um portão de consulta obrigatória (hooks, kb enforce).
• benchmarks/README.md: metodologia de benchmark de recuperação e como reproduzir os números em docs/comparison.md.
• SECURITY.md: versões suportadas e como relatar uma vulnerabilidade.

Licença

Apache 2.0. Veja LICENSE e NOTICE.