contextweaver

contextweaver

エージェントの実効的な機能範囲を取得してコミットし、デプロイ前に意味のある変更を確認できます。

ContextWeaver は現在、意図的に対象を絞った製品仮説を検証しています。 機能スナップショット＋意味的ドリフトです。

OpenAPI ドキュメント、取得済みの MCP tools/list 応答、またはネイティブの ContextWeaver カタログを入力すると、D1 実験によって決定論的に正規化された スナップショットが生成されます。内容を確認、検証し、後から作成した候補と比較できます。 モデルアカウント、ゲートウェイ、ツール実行環境、Weaver Stack は必要ありません。

ステータス： アルファ版、具体的には製品実験です。実装は動作し、テスト済みですが、 ユーザーにとっての価値に関する仮説はまだ立証されていません。このワークフローを実際の プロジェクトで試した独立したユーザーが、継続して利用するかどうかを積極的に測定しています。

機能ドリフト実験を試す

リポジトリをクローンし、そのチェックアウトをインストールしてください。これにより、 保守されているサンプルフィクスチャと評価対象のコードが必ず一致します。

以下のコマンドでは、リポジトリでデフォルトとしてドキュメント化されている python3（docs/agent-context/workflows.md）を使用します。Python をランチャー経由で 実行する Windows 環境では、python3 を py -3 に置き換えてください。環境で意図した インタープリターがすでに python として公開されている場合は、一貫してそちらを使用してください。

git clone --depth 1 https://github.com/dgenio/contextweaver.git
cd contextweaver
python3 -m pip install .

保守されている OpenAPI の例を実行します。

python3 -m contextweaver.d1 snapshot examples/d1/openapi_before.json --source-type openapi --output ./cw-before.json
python3 -m contextweaver.d1 snapshot examples/d1/openapi_after.json --source-type openapi --output ./cw-after.json
python3 -m contextweaver.d1 inspect ./cw-after.json
python3 -m contextweaver.d1 verify ./cw-after.json
python3 -m contextweaver.d1 diff ./cw-before.json ./cw-after.json

候補フィクスチャでは、意図的に次の変更を行っています。

• 既存の listInvoices 機能で customer_id を必須にします。
• 説明を変更します。
• 新しい getInvoice 機能を追加します。

差分では、機能の追加・削除と、既存の論理機能の変更を区別し、変更された構造化パスを 報告します。契約の変更とドキュメントのみの変更は分けて示されます。required、type、 enum などのフィールドに関わる変更には、確認用に破壊的変更の可能性ありという フラグが付けられます。

このフラグは意図的に保守的です。ContextWeaver は、完全な JSON Schema 互換性チェッカーで あるとは主張しません。

詳しい手順：機能ドリフト実験。

独自のソースで使う

OpenAPI

python3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities.json
python3 -m contextweaver.d1 verify ./capabilities.json

API の変更後：

python3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities-candidate.json
python3 -m contextweaver.d1 diff ./capabilities.json ./capabilities-candidate.json

取得済みの MCP ツール

MCP tools/list 応答を JSON として保存してある場合：

python3 -m contextweaver.d1 snapshot ./tools-list.json \
  --source-type mcp \
  --output ./capabilities.json

MCP の場合、D1 は上流の論理名でツールを比較します。そのため、入力スキーマの編集は、 説明のない削除と追加の組み合わせではなく、同じ機能への変更として表示されます。 スキーマに依存する従来のルーティング ID は、確認用に normalized_id として別途保持されます。

稼働中の MCP サーバーから情報を取得する操作は別途行います。snapshot、inspect、 diff、verify は、検出された機能を実行しません。

ネイティブの ContextWeaver カタログ

python3 -m contextweaver.d1 snapshot ./catalog.json \
  --source-type native \
  --output ./capabilities.json

verify の意味

verify は、D1 スナップショットの契約を検証します。対象は、構造、決定論的な順序、論理 ID の一意性、正規の機能ダイジェストです。

次のものではありません。

• デプロイの承認；
• セキュリティ認証；
• 認証または認可；
• ツールの実装が正しいことの保証；
• ルーティング品質の評価；
• 本番環境のランタイムに関する証明。

ContextWeaver D1 を使わないほうがよい場合

否定的な回答も、このプロジェクトにとって有用な証拠です。機能スナップショットが整然として見えるという理由だけで、ContextWeaver を追加しないでください。

次の場合は、よりシンプルな方法を使ってください。

• 通常の Git diff、設定のレビュー、テストで機能の変更内容がすでに明らかになる場合；
• ツール／API の範囲が小さく、変更頻度も低い場合；
• 解決したい問題がプロバイダー標準のツール検索だけである場合；
• エージェントのループ、ツール実行機能、IAM レイヤー、本番環境向けオーケストレーターが必要な場合；
• もうひとつコミット対象の成果物を保守するコストが、それによって解消されるレビュー／デバッグの問題より大きい場合。

D1 を試して、Git／テストのほうが手軽だと判断した場合、それは妥当なプロダクト上の結論です。ぜひお聞かせください。

テスト対象

現在の存続性実験では、コードが動作するかどうかよりも、さらに踏み込んだ問いを検証します。

機能スナップショットとセマンティックドリフトレポートは、実際のレビュー／手作業／リスク管理のプロセスを改善し、独立したユーザーが使い続けるほどの価値をもたらすでしょうか？

このプロジェクトでは、次を区別します。

qualified exposure
  -> understood the problem
  -> chose to evaluate
  -> attempted setup
  -> reached first useful output
  -> used on a real project
  -> retained independently / removed

スター、フォーク、ダウンロード数、デモの成功、メンテナーが作成したインテグレーションは、継続的な採用とはみなしません。

プロダクトに関する主要な意思決定は #758 で追跡しており、配布品質のゲートは #855 です。支援なしで最初の成果を得られるかどうかと継続利用については #658 で、実際の採用については #551 で追跡しています。

ルーティング、コンテキストのコンパイル、MCP ゲートウェイについて

ContextWeaver には、これまでに実装された実行時機能がすでに数多く含まれています。そのコードは現在も残っており、現在提供している動作については引き続き正確で安全な説明を保つ必要があります。しかし、実装が既存であることは、プロジェクトがその機能の拡張を続けるべき根拠にはなりません。

次の 2 つの広範な仮説は、明示的に証拠を重視します。

• D2 — 範囲限定／フェーズ認識型のコンテキストコンパイル： 条件付きです。現代のプロバイダー／ランタイム標準の仕組みを超える、重要な価値を示す必要があります。
• D3 — 独自の決定論的なツール選択： 仮説の反証を目的とする検証です。対象ユーザーが実際に重視する点で、現代のプロバイダー標準のツール検索／遅延読み込み、またはシンプルな検索ベースラインを上回る必要があります。

D1 の実験中は、具体的な外部の阻害要因または承認済みの反証実験がない限り、プロジェクトはルーティングの高度化、ランタイムバンドルの仕組み、メモリ／セッション機能、フレームワークの対応範囲、ゲートウェイの範囲、ベクトルストア、モデルを使った機能拡張を進めません。

これらの従来の機能を使う既存のインテグレーションを保守している場合は、関連ドキュメントを引き続き利用できます。

• どの従来のパターンが適しているか
• コンテキストファイアウォール
• MCP コンテキストゲートウェイのアーキテクチャ
• MCP ゲートウェイのセキュリティモデル
• 比較／代替手段
• エコシステムマップ

エビデンスと主張

D1 の実装が裏付けるのは、文書化されたソース／アダプターの契約に基づく決定論的なスナップショット構築や、構造化されたセマンティック差分の出力など、範囲を限定したエンジニアリング上の主張です。ユーザーがこの製品を必要としている、または使い続けているという、より強い主張はまだ裏付けられません。

過去に掲げたトークン削減の見出しは、D1 の宣伝には意図的に使用していません。これらの過去のベンチマーク主張に関する現在のエビデンスの完全性への取り組みは、#841 で追跡しています。

主張の一覧については主張とエビデンスを、D1 の正確な契約と制限についてはD1 の機能ドリフト実験を参照してください。

Python API の安定性

D1 は、意図的に次の形で公開しています。

python3 -m contextweaver.d1 ...

従来の最上位 CLI や、大規模な新しい公開 Python API としてすぐに昇格させることはしていません。これは意図的な判断です。この実験は、プロジェクトが新たな互換性維持の責務を負う前に、実際に使い続けられることで恒久的なインターフェースとしての価値を示す必要があります。

Weaver Stack の一部として（任意）

ContextWeaver は単体で使用できます。兄弟プロジェクトへのハード依存はありません。

より広範な Weaver Stack には、計画、実行境界、ガードレール、教訓、評価に関する関連実験／コンポーネントが含まれています。このエコシステムは D1 の評価に必要ありません。また、Stack の一貫性は、ContextWeaver の機能が単独で価値を示せない場合に、その機能を維持する理由にはなりません。

関連する責務が実際に必要な場合にのみ、エコシステムマップを参照してください。

インストールと互換性

pip install contextweaver

Python 3.10～3.14 は、リポジトリの CI マトリックスでカバーされています。

現在のパッケージバージョン：0.18.2

プロジェクト	リリース
ContextWeaver（このリポジトリ、v0.18.2）	現在のパッケージリリース

このリポジトリは 1.0 より前のバージョンです。バグ修正とセキュリティ修正には、サポート対象の最新のパッチリリースを使用してください。また、過去のランタイム API に依存する前に、変更履歴を確認してください。

現在のロードマップ

ロードマップは意図的に、機能の一覧ではなく、製品に関する意思決定の順序として構成しています。

マイルストーン	状況	意味
v0.18.1 — D1 の存続実験のベースライン	✅ 完了	オフラインでのスナップショット／検査／差分／検証が可能です。ユーザー価値はまだ検証されていません。
v0.18.2	✅ 現行（v0.18.2）	D1 の存続実験とリリース経路の復旧
D1 の配布ゲート	🔬 まずエビデンス	最初の利用窓口を分かりやすくし、適格な評価者を募り、初回の成功と継続利用を測定します。
D1 の判断	⏸ 次の判断	適切な配布を行った後、継続的な価値に基づいて、継続するか、さらに縮小するか、終了するかを決定します。
D2 / D3	🧪 条件付き	D1 のエビデンス、または独立した課題の発見によって、範囲を限定した反証実験が正当化される場合にのみ実施します。

CI が成功しても、それだけでロードマップが前進することはありません。

貢献

存続実験中に最も価値のある貢献は、範囲が限定され、エビデンスに結び付いたものです。

• 実際の D1 評価を妨げている問題
• 現状で誤解を招く、または気付かれないまま失われるセマンティック差分の事例
• 決定論的な正規化の正確性
• パッケージが現在も提供している動作に関する、セキュリティ／リリースの保守
• よりシンプルな代替案のほうが優れていることを示す否定的なエビデンス

完全性だけを理由に、フレームワークアダプター、ルーティングポリシー、ストレージバックエンド、ランタイムフェーズ、エコシステム統合を追加しないでください。

リポジトリのエンジニアリング規約については、CONTRIBUTING.md と AGENTS.md を参照してください。

セキュリティ

サポート対象バージョンと脆弱性の報告方法については、SECURITY.md を参照してください。公開の導入／評価レポートには、認証情報、顧客データ、独自のスキーマ、非公開のプロンプトを含めないでください。

Documentation

• Documentation site
• Capability drift experiment
• Claims & evidence
• Daily Driver guide — historical/runtime users
• Cookbook — broader shipped surfaces
• FAQ
• Changelog

License

Apache-2.0. See LICENSE.