TestGraph

AI アシスタント間で共有可能な検証可能なメモリを実現する、実験的な AI ネイティブ経験グラフ。

ステータス: 動作中のプレリリース研究システムです。アーキテクチャと MCP ワークフローは複数の AI クライアントで試行済みですが、このプロジェクトはまだ安定した本番サービスまたは API としては提供されていません。

TestGraph は、人間のレビューと AI が導出した構造を永続的なグラフ知識として保存し、エビデンス、来歴、サーバー検証可能な実行をモデルの主張から分離して管理します。あらかじめ完全なドメインスキーマを必要とせず、さまざまな AI システムが同じ知識に貢献し、再利用できるように設計されています。

プロジェクトの目標

1. スキーマの創発: 事前にカテゴリを設計することなく、複数の AI にとなじみのない体験を与え、有用な構造を得ること。

2. 制御された不一致: 対立する分類は、揺れ動くのではなく、エビデンス、信頼度、サーバーのルールによって収束させる。

3. 正直な実行: サーバーが検証しない限り、モデルは発見、拡充、調整が行われたと主張できない。

4. 呼び出し側の AI 能力: TestGraph は、呼び出し側の AI を意図的にセマンティック・エンジンおよび発見エンジンとして使用します。AI は、未知の主題に対して、利用可能な推論、検索、ツール機能を適用し、有用な構造と関係を導き出し、TestGraph がドメイン固有の形式を規定するのを待たずに証拠を調整できる必要があります。TestGraph は、安定したグラフプリミティブ、永続化、サーバー側検証を提供し、呼び出し側の AI が開かれた知性を提供します。

これらの目標は、個々の AI クライアントのための単なる指針ではなく、TestGraph のアーキテクチャとテストの受入基準です。

Related MCP server: Graph-Mem MCP

標準ボキャブラリモデル

レビューは、DNS スタイルのコンセプトパスではなく、安定した subject_type_id 値に基づいて保存されます。柔軟な入力は、正規のサブジェクトタイプとグローバルに一意なエイリアスによって解決され、大文字・小文字、句読、所有格、通常の複数形は機械的に正規化されます。未知のタイプは、辞書検索後に暫定エントリとして作成されることがあります。

分類は別のメタデータです。たとえば、ferry belongs_to transportation は交通に関する広範囲の検索を向上しますが、フェリーレビューが保存される場所を変更することはありません。review はレコードタイプであり、ボキャブラリのノードではありません。再利用可能な構造化フィールドは、独自の安定 ID とエイリアスを持ち、複数のサブジェクトタイプに頻帯できます。

マイグレーション 0009_flat_standard_vocabulary は、ユーザー、OAuth 状態、機能に利用できる認証資格情報を保持しながら、古い v2 のコンセプト/レビューデータを意図的に破棄します。

ローカルセットアップ

1. Python 3.11+ の仮想環境を作成します。

2. 依存関係をインストールします:

pip install -r requirements.txt

3. .env.example を .env にコピーし、すべてのプレースホルダーのシークレットを独自の値に置き換ます。

4. マイグレーションを実行します:

alembic upgrade head

5. スキーマとデモ用IDをシードします:

python -m scripts.seed

6. アプリケーションを起動します:

python run.py

http://127.0.0.1:8000 と http://127.0.0.1:8000/docs を開いてください。

ローカル開発環境の外部で、例示の資格情報や開発用の資格情報を再利用しないでください。シークレット、API キー、OAuth 接続コード、所有者の認証情報をリポジトリにコミットしてはいけません。

MCP と OAuth

TestGraph には、ツールのみの MCP アプリが含まれています。現在のマルチモデル統合は /mcp-v2 で試行されます。本番の接続は、OAuth 2.1 Authorization Code + PKCE を使用します。接続した AI は、短期間のスコープ付きトークンを受け取り、接続コード、API キー、TestGraph の所有者 ID を取得しません。

MCP サーフェスには、レビューの検索・取得・保存操作と、マルチモデル実験で使用される新しいグラフ/調整機能が含まれています。この実験的なサーフェスはまだ進化しているため、デプロイされている MCP スキーマを正規のものとして扱う必要があります。

デプロイ前に、長いランダムな OAUTH_CONNECTION_CODE を設定し、適切な OAUTH_OWNER_USER_ID を設定し、本番のシークレットがデプロイ環境にのみ存在することを確認してください。

オープンな UCI レシピレビューのインポート

マイグレーションと python -m scripts.seed の後、次のコマンドを実行します:

python -m scripts.import_uci_recipe_reviews --representative-reviews 100 --load

これにより、CC の BY 4.0 UCI データセットをダウンロードし、その 100 レシピそれぞれから証拠が豊富なレビューを 1 件選択します。変換されたレコードを data/uci_recipe_reviews_100.json に書き出し、設定されたデータベースに読み込みます。再実行しても安全です。安定したソース ID を持つため、重複が発生しません。

元のレビューテキスト、0〜5 のスターレート、タイムスタンプ、投票、ソース レコード ID、ライセンス、帰属は来歴にのまま保存されます。インポーターは、味、明確さ、所要時間、食材の入手期間、難易度、繰り返しの価値、変更点に関する明示的な記述を解釈します。各解釈は、その裏付けとなるソース文を保持し、まだ裏付けのないものはすべて null です。

ダウンロードや再生成をせずに、チェック済みバンドルを読み込むには:

python -m scripts.import_uci_recipe_reviews --load-bundle data/uci_recipe_reviews_100.json

開発用データのリセット

ガードされたリセットページは /development/reset で利用できます。このページは非表示で、明示的に有効にしない限り 404 を返します:

ENABLE_DEVELOPMENT_RESET=true

このページは、 v1/v2 のレビューと知識データを完全に削除し、ユーザー、スキーマ、OAuth 接続、機能資格情報を保持します。公開の本番デプロイでは、この機能が無効のままになるようにしなければなりません。

テスト

pytest -q

パブリックリリースは、完全なテストスイートがリリースコミットに対して合格し、デプロイ準備のチェックが成功しない限り、実施すべきではありません。RELEASE_CHECKLIST.md を参照してください。

Railway デプロイ

1. リポジトリを GitHub にプッシュする。

2. GitHub リポジトリから Railway プロジェクトを作成する。

3. PostgreSQL を追加する。

4. Postgres サービスの DATABASE_URL を参照すること。未解決の Railway 参照をプレーンな文字列として貼り付けないでください。

5. 本番変数を設定し、一意でランダムなシークレットを使用する:

ENVIRONMENT=production
APP_SECRET=<random secret>
DEVELOPMENT_API_KEY=<long random key; development/admin use only>
CLIENT_API_KEYS={}
OAUTH_OWNER_USER_ID=<owner UUID>
OAUTH_CONNECTION_CODE=<long random connection code>
PUBLIC_BASE_URL=https://<your-domain>
ALLOWED_HOSTS=["<your-domain>","<railway-domain>"]
CORS_ORIGINS=["https://<your-domain>"]
ENABLE_DEVELOPMENT_RESET=false

railway.json は、デプロイ前のマイグレーション、Railway の$PORT を使用した Uvicorn 起動、/health/ready` での準備チェックを設定します。

このアプリケーションは、プロジェクトが Psycopg 3 を使用しているため、Railway の postgresql:// URL を SQLAlchemy の postgresql+psycopg:// 形式に変換します。PostgreSQL を解決できない本番デプロイで、静かに SQLite にフォールバックするのではなく、停止させる必要があります。

実装されたアーキテクチャ

• 呼び出し側の AI 能力を、サーバーを検証・永続化層とした開かれたセマンティック・ディスカバリエンジンとして利用

• 安定したフラットなサブジェクトタイプ ID

• 正規語とエイリアス

• ストレージアドレスではなく、検索に使用する編集可能な型関係

• バージョン管理されたスキーマレジストリ

• ドメイン固有の Pydantic バリデーションを JSON/JSONB として保存

• 明示的な承認/バージョンを伴うドラフト先行の出版

• スコープ付きクライアント資格情報

• 中央集権的な読み取りポリシー

• 正規のサブジェクトの解決とバージョンチェック付きドラフト編集

• OAuth 2.1 Authorization Code + PKCE、動的クライアント登録、リフレッシュトークンのローテーション、スコープ付きアクセストークン

• 認証された AI アクセスのための MCP エンドポイント

• べき等キー

• 来歴、同意、所有権、可視性

• レビュアーと読者の単位での整合、読者固有の関連性

• 監査ログとソフト削除

• リクエスト ID、一貫した JSON エラー、リクエストサイズ制限、ページング可能なエンドポイント

• Alembic マイグレーション

• ローカルでは SQLite、本番では PostgreSQL

• モデル間の調整と、サーバーが記録する検討/評価ワークフロー

安全な読み取りと編集のルール

• 公開リストは、公開済み かつ public の両方の条件を満たすユーザー体験だけを返します。

• 正確な ID で、公開済みの unlisted な体験を取得できます。

• ドラフトや非公開の体験には、適切な読み取り資格情報が必要です。

• aggregate_only の体験は、個別のレビューとして返されることはありません。

• 編集したり構造化知識を添付したりする前に、サブジェクトを解決します。

• バージョンチェックが、同時編集からドラフトを保護します。

• オプションのクライアント資格情報は、一意で取り消し可能なシークレットと、必要最小限のスコープを使用する必要があります。

ライセンス

TestGraph は、GNU Affero General Public License v3.0 (AGPL-3.0) でライセンスされています。LICENSE を参照してください。

AGPL は、その条件に従って使用・修正・再配布を許可します。ネットワークサービスを提供するために用いられる修正版のネットワークソースへの妥協なども含みます。

AGPL-3.0 が要件に合わない場合は、代替の商用またはプロプライエタリライセンスが利用できる場合があります。別途のライセンス契約については、testgraph@21dle.co.uk: までご連絡ください。

コントリビューターは CONTRIBUTING.md を読んでください。貢献は、プロジェクトが別のライセンスを提供できる能力を維持する条件、および治てのみ受け付けられます。

リポジトリを公開する前に

RELEASE_CHECKLIST.md と SECURITY.md を読んでください。特に、秘密鍵の履歴の確認を完了し、公開データの境界を確認し、完全なテストスイスを実行し、完全なリリースコミットからクリーンなデプロイを検証してください。

Wait: There are potential mistakes. Let's adjust the phrasing in some places.

• The "reuse" or "再利用".

• "re-run it is safe" wording.

Also note "v1/v2" etc.

Need maybe "レビューと知識" vs "ストア".

"knowledge data" is "知識データ".

Need "and" in architecture list? Fine.

Potential issue: "S馬鹿" no.

Let's finalize, but needs to be accurate. There are a few Japanese nuances.

Let's proofread final output for translation errors.

1. "Controlled disagreement" should be "制御された不一致" not "制御された入れ替"? I wrote "制御された入れ替" in translation? Actually above I wrote "リの... " Let's control.

In "Project goals" bullet 2: "制御された入れ替え" is wrong. Should be "制御された不一致" or "制御された対立". Original "Controlled disagreement" = "制御された意見の相違". Let's set "制御された不一致".

In "3. Honest execution" I wrote "誠実な実行" "正直な実行" okay.

"サーバーが検証しない限り" - Actually "unless the server can verify it" is "サーバーが検証できる場合を除き" or "サーバーが検証できない限り"? Japanese nuance: Unless X = "X でない限り". Original: "Models cannot claim that discovery happened unless the server can verify it." Means "サーバーがそれを検証できない限り、モデルは発生したと主張できません" (if server cannot verify, cannot claim). But English "unless the server can verify it" = "except if server can verify". So "サーバーが検証できる場合を除いて". Use "サーバーが検証しない限り" ambiguous? Actually "しない限り" = "unless not". Danger. Let's phrase: "サーバーが検証できる場合を除き、モデルは ... ことを主張できない". Better.

• " server can verify it": "server can verify it" = "サーバーが検証できる場合"

So update.

"呼び出し側 AI 能力" bullet: Need "受入基準" not "receive".

" semantic engine" etc.

"MCP サーフェス" maybe "サーフェス" is okay.

At "The page permanently removes v1/v2 review knowledge" I wrote "レビューと知識データを完全に削除" good.

Need "本番でなければ無効としなければ". Good.

"Curse"? OK.

"mass" translations.

Let's make final polished.

Let's final.# TestGraph

AI アシスタント間で共有可能な検証可能なメモリのための、実験的な AI ネイティブ経験グラフ。

ステータス: プレリリースの研究システムとして動作しています。アーキテクチャと MCP ワークフローは複数の AI クライアントで試行されていますが、現時点では安定した本番サービスや API として提供されるものではありません。

TestGraph は、人間のレビューと AI が導出した構造を永続的なグラフ知識として保存し、エビデンス、来歴、サーバー検証可能な実行をモデルの主張から分離して管理します。これにより、異なる AI システムが事前に完全なドメインスキーマを必要とせずに、同じ知識に貢献し、再利用できるよう設計されています。

プロジェクト目標

1. スキーマの創発: 事前にカテゴリを設計することなく、複数の AI に馴染みのない体験を与え、有用な構造を得られるのは.

2. 制御された不一致: 対立する分類は、振り子のように揺れるのではなく、エビデンス、信頼度、サーバールールによって収束したものに変わる。

3. 誠実な実行: サーバーが検証できる場合を除いて、モデルはあとで発見や拡張、再調整が行われたとがんばって正しく主張できるとは限らず、実際にできなければなりすましになる。

4. 呼び出し側 AI の能力: TestGraph は意図的に、呼び出し側の AI をセマンティックエンジン兼発見エンジンとして使います。AI は、使い慣れないテーマに対しても利用可能な推論・検索・ツール機能を適用し、有用な構造と関連を導出し、TestGraph がドメイン固有の形式を前もって定めるのを待たずにエビデンスを整える能力を持ちます。TestGraph が提供するのは、安定したグラフプリミティブ、永続化、サーバーサイドの検証であり、呼び出しAIが開かれた形の知能を提供します。

これらの目標は、個々の AI クライアントへの参考ではなく、TestGraph のアーキテクチャとテストの受入条件です。

標準語彙モデル

レビューは、DNS 形式の概念パスではなく、安定した subject_type_id 値に対して格納されます。柔軟な入力は、正規のサブジェクトタイプとグローバルに一意なエイリアスで解決されます。大文字小文字、句読点、所有格、ふ送りの複数形は機械的に正規化されます。未知のタイプは辞書検索後、暫定エントリとして作成されることがあります。

分類は別のメタデータです。たとえば、ferry belongs_to transportation は交通に関する広い検索を改善しますが、フェリーレビューが保存される場所を変更することはありません。review はレコードタイプであり、語彙上のノードではありません。再利用可能な構造化フィールドは独自の安定 ID とエイリアスを持つ場を持ち、複数のサブジェクトタイプに割り当てることができます。

マイグレーション 0009_flat_standard_vocabulary は、ユーザー、OAuth 状態、機能性、認証情報、その他の認証データを維持しつつ、従来の v2 コンセプト/レ dataを意図的に破棄します。

ローカル環境のセットアップ

1. Python 3.11+ の仮想環境を作成します。

2. 依存関係をインストールします:

pip install -r requirements.txt

3. .env.example を .env にコピーし、すべてのプレースホルダーのシークレットをマイクロソフトの確認に置き換えます。

4. マイグレーションを実行します:

alembic upgrade head

5. スキーマとデモ用IDをシードします:

python -m scripts.seed

6. アプリケーションを起動します:

python run.py

http://127.0.0.1:8000 と http://127.0.0.1:8000/docs を開いてください。

例示の資格情報や開発用の資格情報をローカル開発環境外で再利用しないでください。シークレット、API キー、OAuth 接続コード、所有者の識別している情報はリポジトリにコミットしてはいけません。

MCP と OAuth

TestGraph にはツール形式の MCP アプリが含まれています。現在のマルチモデル統合は /mcp-v2 を介して動作します。本番接続は OAuth 2.1 Authorization Code + PKCE を使用します。接続した AI は短期のスコープ付きトークンを受け取ります。接続コード、API キー、TestGraph のオーナーIDを受け取りません。

MCPサーフェスの種別には、レビューの検索・取得・保存と、マルチモデル実験で使用する新しいグラフや統合機能が含まれます。この実験的なサーフェスはまだ転導しているため、デプロイされた MCP スキーマを公式なものとして扱ってください。

デプロイする前は、長いランダムな OAUTH_CONNECTION_CODE、適切な OAUTH_OWNER_USER_ID を設定し、本番シークレットがデプロイ環境にのみ存在することを確認してください。

公開の UCI レシピレビューをインポートする

マイグレーションと python -m scripts.seed を実行した後、次を実行します:

python -m scripts.import_uci_recipe_reviews --representative-reviews 100 --load

この操作で、CC BY 4.0 の UCI データセットをダウンロードし、その 100 レシピそれぞれについて、証拠が十分に含まれているレ 1つを選びます。変換したレコードを data/uci_recipe_reviews_100.json に書き出し、設定されたデータベースへ取り込みます。再実行は安全です。安定したソース ID のおかげで重複が起こりません。

元のレビューレビュー、0-5 星の評価、タイムスタスト、持ち点、ソースレコードID、ライセンス、クレジットは来歴として調査されます。また、インポーターは、風味、明確さ、所要時間、材料の入手可能性、難易度、繰り返しの価値、追加の変更などについて明確に述べられている文を解釈します。各解釈には実例となる原文文を対応させ、何が裏付けられないものはすべて null のままです。

再ダウロードや再生成をせずにチェック済みバンドルを読み込むには:

python -m scripts.import_uci_recipe_reviews --load-bundle data/uci_recipe_reviews_100.json

開発データのリセット

/development/reset には保護されたリセットページがあります。このページは非表示であり、明示的に有効にしない限り 404 を返します:

ENABLE_DEVELOPMENT_RESET=true

このページは、v1/v2 のレビューと知識データを永久に削除し、ユーザー、スキーマ、OAuth 接続、機能資格情報を保存します。公開の本番デプロイでは、このページは無効に維持する必要があります。

テスト

pytest -q

パブリックリリースに切り替える前には、リリースコミットに対してテストスイート全体をパス、デプロイ準備チェックを成功させる必要があります。詳しくは RELEASE_CHECKLIST.md を参照してください。

Railway デプロイメント

1. リポジトリを GitHub にプッシュします。

2. GitHub リポジトリから Railway プロジェクトを作成します。

3. PostgreSQL を追加します。

4. Postgres サービスの DATABASE_URL を参照します。未解決の Railway リファレンスをそのまま文字列として貼り付けない。

5. 一意でランダムなシークレットを使い、本番変数を設定します:

ENVIRONMENT=production
APP_SECRET=<random secret>
DEVELOPMENT_API_KEY=<long random key; development/admin use only>
CLIENT_API_KEYS={}
OAUTH_OWNER_USER_ID=<owner UUID>
OAUTH_CONNECTION_CODE=<long random connection code>
PUBLIC_BASE_URL=https://<your-domain>
ALLOWED_HOSTS=["<your-domain>","<railway-domain>"]
CORS_ORIGINS=["https://<your-domain>"]
ENABLE_DEVELOPMENT_RESET=false

railway.json は、デプロイ前マイグレーション、Railway の $PORT を使った Uvicorn 起動、/health/ready の確認を行います。

このアプリケーションは、Psycopg 3 を使用しているため、Railway の postgresql:// URL を SQLAlchemy の postgresql+psycopg:// の形式に変換します。PostgreSQL を解決できない本番デプロイは、黙って SQLite にフォールバックせずに停止する必要があります。

実装されたアーキテクチャ

• 呼び出しAIの能力をサーバーが検証し永続化する、柔軟なセマンティック・発見エンジンとして利用

• 安定したフラットなサブジェクトタイプ ID

• 正規用語とエイリアス

• 検索に使われ、単なる記憶場所ではない編集可能なタイプ関係

• バージョン管理されたスキーマ探索

• JSON/JSONB に保存されるドメイン固有の Pydantic 検証

• ドラフト先行・明示的な承認/バージョンの公開

• 特定スコープ付きクライアント認証物

• 中央集権的な読み取りポリシー

• 正規サブジェクト解決と、バージョンチェック付きドラフト編集

• OAuth 2.1 Authorization Code + PKCE、動的クライアント登録、リフレッシュトークンの回転、作用範囲を持つアクセストークン

• 認証された AI アクセスのための MCP エンドポイント

• 冪等性を持つキー

• 来歴、同意、所有権、可視性

• レビュアーと読者のペア調整、読者固有の双方的な関連性

• 監査ログとソフトデリート

• リクエストID、一貫した JSON エラー、リクエストサイズ制限、ページング可能なエンドポイント

• Alembic マイグレーション

• ローカルでは SQLite、本番では PostgreSQL

• モデル横断の統合と、サーバーに記録される評定/評価ワークフロー

安全な読み取り・編集ルール

• 公開リストには、published かつ public の両方を満たす経験だけが返されます。

• 正確なIDを使えば、公開された unlisted の経験も取得できます。

• ドラフトや非公開の経験は、適切な読み取り資格情報が必要です。

• aggregate_only の経験が個々のレビュー結果として返されることはありません。

• 編集や構造化知識を排除する前に、サブジェクトを解決します。

• バージョンチェックは、同時並行のドラフト編集を保護します。

• オプショナルなクライアント資格情報は、一意で失効可能、かつ必要最低限のスコープ範囲を使用しなければなりません。

ライセンス

TestGraph は、GNU Affero General Public License v3.0 (AGPL-3.0) の下で提供されます。LICENSE を参照してください。

AGPL は、その規定に従った利用、改変、再頒布を許可します。特に、ネットワークサービスを提供するための改作はすべてそのソースコードの公開が条件です。

AGPL-3.0 がご要件に合わない場合は、商用またはプロプライアエタリな代替ライセンスを提供できることがあります。別のライセンス契約を希望する場合は、testgraph@21dle.co.uk までお問い合わせください。

コントリビュータの方は CONTRIBUTING.md をご覧ください。コントリビューションは、プロジェクトが代替ライセンスを提供する能力を損なわない条件下でのみ受け付けます。

リポジトリを公開する前に

RELEASE_CHECKLIST.md と SECURITY.md を読んでください。特に、シークレットの履歴の完全確認、公開データの境界の決定、完全なテストスイートの実行、リリースコミットそのものからのクリーンな配布の検証アクションを完了してください。