Data Olympus

data-olympus

初めての方へ? まず WHY.md から始めてください。 これはプロジェクトの背景にあるストーリーです。コーディングエージェントで繰り返し直面してきた問題、data-olympus がそれにどう違う形で取り組んでいるか、Google の Open Knowledge Format とどう関係しているか、そして私たちのベンチマークがどこで強く、どこでそうではないかを説明しています。この README の残りの部分は技術リファレンスです。

data-olympus は、エージェントワークフォース向けのガバナンス水準のナレッジベースフォーマット兼サーバーです。Open Knowledge Format (OKF) v0.2 のコンシューマーから読み取り可能です。OKF のディレクトリ構造、フロントマターの規約、予約ファイル名、リンクモデルを継承し、その上にガバナンス拡張(安定した id、制御された type/status/tier フィールド、supersedes チェーン)と単一ライターの MCP サーバー、ならびに CLI を重ねています。CI は、公式 Google OKF v0.2 コミット ad30107c31c06aec8a7d5636e0d1058118604e6f に対して 2 つの具体的な方向性を証明しています。すなわち、そのリファレンス可視化コンシューマーが example-bundle 内のすべての概念を読み取り、data-olympus が固定された公式 Bitcoin サンプルをインポート、リント、インデックス、検索、取得します。これはフィクスチャに限定された相互運用性の証拠であり、すべての OKF バンドルや将来の上流リビジョンに対する包括的な保証ではありません。その結果として得られるのは、エンジニアリング標準、アーキテクチャ上の意思決定、プロジェクト知識をまとめた、git ネイティブでバージョン管理されたドキュメントグラフであり、エージェントと人間が独自のサービスを一切使わずに読み取り、検索、拡張できます。

これはコードではなく意思決定を統治します。エージェントがある選択(ライブラリ、パターン、移行)を行おうとしているとき、data-olympus はその選択を統治すべき既存の標準や意思決定を提示します。これは意図的に、コード検索、リファレンス検索、あるいは「X はどこで使われているか」を調べるツールではありません。LSP、grep、Sourcegraph はすでにそれをうまくこなします。これが対象とする取得タスクは、コーディングインテントから統治ルールへのマッピングであり、バイブコーディング中の現在のモデルとのやり取りで最も弱い部分、つまりモデルをチームがすでに正しいと確立したパターンに沿わせ続けることを支援します。

ステータス: 1.0 前のベータ版。安定版リリースは PyPI と GHCR を通じて配布されています。

なぜ

• ポータブルでロックインなし。 ナレッジベース全体が git 内の markdown ファイルのディレクトリです。データベースも、独自スキーマも、ベンダーもありません。
• git ネイティブの差分とレビュー。 すべての変更はコミットです。提案された編集は、コミット前に保留キューを経由します。履歴はただの git log です。
• エージェントにも人間にも読みやすい。 YAML フロントマター付きのプレーンな markdown。ドキュメントの読み取りや作成に SDK は不要です。
• ガバナンスされたマルチエージェント書き込み。 単一ライターの MCP パイプライン(アドバイザリロック、セッションごとのワークツリー、耐久性のあるプッシュキュー)により、分散ロックインフラを必要とせずに同時書き込みの競合を防ぎます。
• ステータス、ティア、タイプでクエリ可能。 後処理なしで status: accepted、tier: T1、type: decision でフィルタリングできます。supersedes チェーンにより、グラフ全体で意思決定の履歴をたどることが可能になります。
• 公式 OKF ツールでテスト済み。 CI は正確な Google OKF リビジョンを固定し、コミットされたフィクスチャに対して両方向の消費を証明します。固定したリビジョン、フィクスチャのチェックサム、Apache 2.0 ライセンスの来歴は tests/okf/reference.json にあります。

クイックスタート

Python 3.13+ と uv が必要です。安定版 CLI は PyPI から直接実行できます：

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

バンドルを作成してサーバーを実行する準備ができたら、永続的にインストールしてください：

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

アナウンスされた候補版は、その正確な PyPI バージョンを指定することでオプトインのまま利用できます。リリースページに記載されている候補版がある場合は、X.Y.ZrcN をその名前に置き換えてください：

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

各チャネルの意味、候補版を採用する前の検証方法、ロールバックの方法については、リリースチャネルを参照してください。

バンドルの初期化、サーバーの起動、レディネス、エージェントの登録、コントリビューター向けのソースインストールについては、docs/quickstart.md を参照してください。

バンドル作成の完全なガイドについては、docs/adoption.md を参照してください。

ドキュメント

• SPEC.md: フォーマット仕様（バンドルのレイアウト、フロントマターのスキーマ、提供コントラクト）。
• docs/quickstart.md: 検証済みのローカル実行手順。
• docs/adoption.md: 独自ナレッジベース導入ガイド（作成、リント、インデックス、提供、エージェントの接続）。
• docs/serving.md: 単一レプリカの提供モデル、読み取り専用レプリカ、git pull ループ、ヘルス／レディネス／ライブネスの分離、プロキシヘッダー、監査ログのローテーション。
• docs/operations.md: 本番運用ランブック：バックアップ、アップグレード、リカバリのプレイブック（デグレード／フェッチ失敗、履歴の書き換え、凍結／降格されたプッシュエントリ、孤立したロック）、ヘルス／アラートのモデル、リリースチャネル（安定版と候補版、検証、ロールバック）。
• docs/comparison.md: data-olympus が OKF、エンタープライズカタログ、Markdown ナレッジベースツール、エージェントコンテキストの慣習、RAG、ADR ツールとどのように関係するか。
• docs/okf-profile.md: フィールドごとの OKF プロファイル：どのガバナンス拡張が安定版で、どれがランタイム専用の提供フィールドで、どれが実験的な候補か。
• docs/glama.md: Glama レジストリの申請、リリース、スコア維持に関するメモ。
• docs/mcp-registry.md: 公式 MCP Registry に関するメモ、server.json が宣言する内容、公開のためのチェックリスト。
• docs/enforcement.md: ナレッジベースを必須の参照ゲートにする方法（フック、kb enforce）。
• benchmarks/README.md: 検索ベンチマークの方法論と、docs/comparison.md の数値を再現する方法。
• SECURITY.md: サポート対象バージョンと脆弱性の報告方法。

ライセンス

Apache 2.0。LICENSEおよびNOTICEを参照してください。