Adaptive Graph Of Thoughts MCP Server

🚀 🧠 Adaptive Graph of Thoughts

グラフ構造を活用して、AIシステムが科学的推論にアプローチする方法を変革する、次世代のAI推論フレームワークです。

🚀 クイックスタート

Adaptive Graph of Thoughtsの包括的な情報（詳細なインストール手順、使用ガイド、設定オプション、APIリファレンス、コントリビューションガイドライン、およびプロジェクトのロードマップ）については、以下の完全なドキュメントサイトをご覧ください。

➡️ Adaptive Graph of Thoughtsドキュメントサイト (注: このリンクは、新しいワークフローを通じてGitHub Pagesサイトがデプロイされた後に有効になります。)

✨ 主な機能

Adaptive Graph of Thoughtsは、Neo4jグラフデータベースを活用して高度な科学的推論を行い、グラフ操作はパイプライン段階で管理されます。また、Model Context Protocol (MCP) を実装してClaude DesktopなどのAIアプリケーションと統合し、複雑な研究タスクに対応したAdvanced Scientific Reasoning Graph-of-Thoughts (ASR-GoT) フレームワークを提供します。

主な特長:

• グラフベースの推論を使用して複雑な科学的クエリを処理
• 多次元評価による動的な信頼度スコアリング
• 高性能を実現するために最新のPythonとFastAPIで構築
• 簡単なデプロイのためにDocker化
• 拡張性とカスタマイズ性を備えたモジュール設計
• MCPプロトコルを介したClaude Desktopとの統合

📦 インストール

デプロイの前提条件

Adaptive Graph of Thoughtsを実行する前に（docker-compose.prod.ymlを使用しない場合、ローカルまたはDockerを介して）、以下のものが必要です。

• 実行中のNeo4jインスタンス: Adaptive Graph of Thoughtsは、Neo4jグラフデータベースへの接続が必要です。
  • APOCライブラリ: 重要なことですが、Neo4jインスタンスには必ずAPOC (Awesome Procedures On Cypher) ライブラリをインストールする必要があります。アプリケーションの推論段階で使用されるいくつかのCypherクエリは、APOCプロシージャ（例: apoc.create.addLabels, apoc.merge.node）を利用しています。APOCがないと、アプリケーションは正しく機能しません。公式APOCウェブサイトでインストール手順を確認できます。
  • 設定: config/settings.yaml（または対応する環境変数）がNeo4jインスタンスのURI、ユーザー名、およびパスワードを正しく指すようにしてください。
  • インデックス作成: 最適なパフォーマンスを得るために、適切なNeo4jインデックスを作成してください。詳細はNeo4j Indexing Strategyを参照してください。

注: 提供されているdocker-compose.yml（開発用）とdocker-compose.prod.yml（本番用）には、すでにAPOCライブラリが事前に構成されたNeo4jサービスが含まれています。Docker Composeを使用する場合は、この要件を満たしています。

前提条件

• Python 3.11以上 (pyproject.tomlで指定されています。例えば、DockerイメージはPython 3.11.x、3.12.x、3.13.xを使用します)
• Poetry: 依存関係の管理に使用します。
• Docker と Docker Compose: コンテナ化されたデプロイに使用します。

インストールとセットアップ（ローカル開発）

1. リポジトリをクローンします:

   git clone https://github.com/SaptaDey/Adaptive Graph of Thoughts.git
   cd Adaptive Graph of Thoughts
   

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

   poetry install
   

   これにより、仮想環境が作成され、pyproject.tomlで指定されたすべての必要なパッケージがインストールされます。

3. 仮想環境をアクティブ化します:

   poetry shell
   

4. アプリケーションを設定します:

   # サンプル設定をコピーします
   cp config/settings.example.yaml config/settings.yaml
   
   # 必要に応じて設定を編集します
   vim config/settings.yaml
   

5. 環境変数を設定します（オプション）:

   # 機密設定用の.envファイルを作成します
   echo "LOG_LEVEL=DEBUG" > .env
   echo "API_HOST=0.0.0.0" >> .env
   echo "API_PORT=8000" >> .env
   

6. 開発サーバーを実行します:

   python src/asr_got_reimagined/main.py
   

   または、より細かい制御が必要な場合は:

   uvicorn asr_got_reimagined.main:app --reload --host 0.0.0.0 --port 8000
   

   APIはhttp://localhost:8000で利用可能になります。

Dockerデプロイ

graph TB
    subgraph "開発環境"
        A[👨‍💻 開発者] --> B[🐳 Docker Compose]
    end
    
    subgraph "コンテナオーケストレーション"
        B --> C[📦 Adaptive Graph of Thoughtsコンテナ]
        B --> D[📊 モニタリングコンテナ]
        B --> E[🗄️ データベースコンテナ]
    end
    
    subgraph "Adaptive Graph of Thoughtsアプリケーション"
        C --> F[⚡ FastAPIサーバー]
        F --> G[🧠 ASR-GoTエンジン]
        F --> H[🔌 MCPプロトコル]
    end
    
    subgraph "外部統合"
        H --> I[🤖 Claude Desktop]
        H --> J[🔗 その他のAIクライアント]
    end
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style F fill:#fff3e0
    style G fill:#ffebee
    style H fill:#f1f8e9

1. Docker Composeですぐに始める:

   # すべてのサービスをビルドして実行します
   docker-compose up --build
   
   # デタッチモード（バックグラウンド）で実行する場合は
   docker-compose up --build -d
   
   # ログを表示する場合は
   docker-compose logs -f adaptive-graph-of-thoughts
   

2. 個別のDockerコンテナ:

   # イメージをビルドします
   docker build -t adaptive-graph-of-thoughts:latest .
   
   # コンテナを実行します
   docker run -p 8000:8000 -v $(pwd)/config:/app/config adaptive-graph-of-thoughts:latest
   

3. 本番環境でのデプロイ:

   # 本番用のcomposeファイルを使用します
   docker-compose -f docker-compose.prod.yml up --build -d
   

特定のデプロイプラットフォームに関する注意事項

• Smithery.ai: Smithery.aiプラットフォームへのデプロイは、通常、提供されているDockerイメージを直接使用します。
  • Smithery.aiの特定のドキュメントを参照して、カスタムDockerイメージをデプロイする手順を確認してください。
  • ポート設定: プラットフォームがAdaptive Graph of Thoughtsコンテナのポート8000（またはAPP_PORTで設定されたポート）を公開するように設定されていることを確認してください。これはFastAPIアプリケーションが使用するデフォルトのポートです。
  • ヘルスチェック: Smithery.aiはコンテナの状態を監視するためにヘルスチェックを使用する場合があります。Adaptive Graph of ThoughtsのDockerイメージには、/healthエンドポイント（例: http://localhost:8000/health）を検証するHEALTHCHECK命令が含まれています。Smithery.aiが特定のヘルスチェックパスを必要とする場合は、このエンドポイントを使用するように設定してください。
  • 提供されているDockerfileとdocker-compose.prod.ymlは、コンテナのセットアップを理解するためのベースラインとして機能します。Smithery.aiの要件に合わせて調整してください。

4. サービスにアクセスする:
   • APIドキュメント: http://localhost:8000/docs
   • ヘルスチェック: http://localhost:8000/health
   • MCPエンドポイント: http://localhost:8000/mcp

💻 使用例

基本的な使用法

APIエンドポイント

Adaptive Graph of Thoughtsが公開する主なAPIエンドポイントは次の通りです。

• MCPプロトコルエンドポイント: POST /mcp

  • このエンドポイントは、Claude DesktopなどのMCPクライアントとの通信に使用されます。
  • asr_got.queryメソッドのリクエスト例:

    {
      "jsonrpc": "2.0",
      "method": "asr_got.query",
      "params": {
        "query": "Analyze the relationship between microbiome diversity and cancer progression.",
        "parameters": {
          "include_reasoning_trace": true,
          "include_graph_state": false
        }
      },
      "id": "123"
    }
    

  • 他にサポートされているMCPメソッドには、initializeとshutdownがあります。

• ヘルスチェックエンドポイント: GET /health

  • アプリケーションの簡単なヘルスステータスを提供します。
  • レスポンス例:

    {
      "status": "healthy",
      "version": "0.1.0" 
    }
    

    (注: 以前に表示されていたタイムスタンプフィールドは、現在のヘルスチェックレスポンスには含まれていません。)

現行バージョンでは、以前にリストされていた高度なAPIエンドポイント（例: /api/v1/graph/query）は実装されておらず、将来の開発のために予約されています。

高度な使用法

セッション管理 (session_id)

現在、APIリクエスト（例: asr_got.query）で利用可能なsession_idパラメータと、レスポンスに含まれるsession_idは、主に単一の完全なクエリ - レスポンスサイクルを識別および追跡するために使用されます。また、進行状況通知（例: got/queryProgress）を元のクエリと関連付けるためにも使用されます。

システムはsession_idを生成して利用していますが、Adaptive Graph of Thoughtsは現在、以前のクエリの詳細なグラフ状態や推論コンテキストが自動的にロードされ、同じsession_idを使用した後続のクエリで再利用されるような、真のマルチターン会話の連続性をサポートしていません。現時点では、各クエリは独立して処理されます。

将来の機能強化: 永続的なセッション

Adaptive Graph of Thoughtsの潜在的な将来の機能強化は、永続的なセッションの実装です。これにより、ユーザーが次のことを行えるようになり、より対話的で進化する推論プロセスが可能になります。

1. 状態の保存: クエリから生成されたグラフ状態と関連する推論コンテキストを、そのsession_idに関連付けて、おそらくNeo4jデータベース内に保存します。
2. 状態の再読み込み: 既存のsession_idで新しいクエリが送信されたとき、システムはこの保存された状態を再読み込み、さらなる処理の開始点として使用できます。
3. 精錬と拡張: 新しいクエリが読み込まれたグラフと対話できるようにします。たとえば、以前の仮説を精錬したり、既存の構造に新しい証拠を追加したり、確立されたコンテキストに基づいて代替の推論パスを探索したりできます。

永続的なセッションを実装するには、次のことに対する堅牢な戦略を開発する必要があります。

• Neo4jでセッション固有のグラフデータを効率的に保存および取得する。
• セッションデータのライフサイクル（作成、更新、期限切れ）を管理する。
• 新しいクエリが既存のセッションコンテキストやグラフとどのようにマージ、変更、または拡張するかの高度なロジックを設計する。

これは、Adaptive Graph of Thoughtsの対話機能を大幅に向上させる重要な機能です。永続的なセッション機能の設計と実装におけるコミュニティからの貢献を歓迎します。

将来の機能強化: 非同期および並列ステージ実行

現在、Adaptive Graph of Thoughtsの推論パイプラインの8つのステージは逐次的に実行されています。複雑なクエリやパフォーマンスをさらに最適化するために、パイプラインの特定の部分を非同期または並列に実行することは、潜在的な将来の機能強化です。

並列化の潜在的な領域:

• 仮説生成: HypothesisStageは、DecompositionStageによって識別された各次元に対して仮説を生成します。異なる独立した次元に対する仮説生成プロセスは、潜在的に並列化できます。たとえば、3つの次元が分解された場合、3つの並列タスクがそれぞれの次元に対する仮説を生成することができます。
• 証拠統合（部分的）: EvidenceStage内で、複数の仮説が評価のために選択された場合、これらの異なる仮説に対する「計画実行」フェーズ（シミュレートされた証拠収集）は、同時に実行できる可能性があります。

課題と考慮事項:

並列ステージ実行を実装すると、慎重に管理する必要がある複雑さが生じます。

• データの整合性: 同時操作、特にNeo4jデータベースへの書き込み（例: 複数の仮説ノードまたは証拠ノードを同時に作成する）は、データの整合性を確保し、競合状態を回避するために慎重に処理する必要があります。並列実行のためには、一意のID生成スキームが堅牢である必要があります。
• トランザクション管理: 同時書き込みのためのNeo4jトランザクションは、適切に管理する必要があります。
• 依存関係管理: 他のステージ（またはステージの一部）の出力に本当に依存するステージが正しくシーケンスされていることを確認することが重要です。
• リソースの利用: 並列実行は、リソースの要求（CPU、メモリ、データベース接続）を増加させる可能性があります。
• 複雑さ: GoTProcessorの全体的な制御フローは、より複雑になります。

現在の逐次実行は、明確で管理しやすいデータフローを保証していますが、独立した次元に対する仮説生成などの領域でのターゲットとなる並列化は、Adaptive Graph of Thoughtsの将来のバージョンでパフォーマンスの向上をもたらす可能性があります。これは、研究と開発のためのオープンな領域のままです。

📚 ドキュメント

テストと品質保証

poetry run pytest

make test

poetry run mypy src/

pyright src/

poetry run ruff check .

poetry run ruff format .

poetry run pytest --cov=src

coverage html

開発コマンド

# Poetryを使用してカバレッジ付きで完全なテストスイートを実行する
poetry run pytest --cov=src --cov-report=html --cov-report=term

# または、Makefileを使用してデフォルトのテストを実行する
make test

# 特定のテストカテゴリを実行する（poetryを使用）
poetry run pytest tests/unit/stages/          # ステージ固有のテスト
poetry run pytest tests/integration/         # 統合テスト
poetry run pytest -k "test_confidence"       # パターンに一致するテスト

# 型チェックとリンティング（Makefileターゲットを介しても実行できます: make lint, make check-types）
poetry run mypy src/ --strict                # 厳格な型チェック
poetry run ruff check . --fix                # リンティング問題を自動修正
poetry run ruff format .                     # コードをフォーマット

# プリコミットフック（推奨）
poetry run pre-commit install                # フックをインストール
poetry run pre-commit run --all-files       # すべてのフックを実行

# 他の有用なターゲット（make all-checksなど）についてはMakefileを参照してください。

🔧 技術詳細

プロジェクト構造

プロジェクトは以下のように構成されています（詳細はドキュメントサイトを参照してください）。

Adaptive Graph of Thoughts/
├── 📁 .github/                           # GitHub固有のファイル（ワークフロー）
├── 📁 config/                            # 設定ファイル（settings.yaml）
├── 📁 docs_src/                          # MkDocsドキュメントのソースファイル
├── 📁 src/                               # ソースコード
│   └── 📁 adaptive_graph_of_thoughts     # メインアプリケーションパッケージ
├── 📁 tests/                             # テストスイート
├── Dockerfile                            # Dockerコンテナの定義
├── docker-compose.yml                    # 開発用のDocker Compose
├── docker-compose.prod.yml               # 本番用のDocker Compose
├── mkdocs.yml                            # MkDocsの設定
├── poetry.lock                           # Poetryの依存関係ロックファイル
├── pyproject.toml                        # Pythonプロジェクトの設定（Poetry）
├── pyrightconfig.json                    # Pyright型チェッカーの設定
├── README.md                             # このファイル
└── setup_claude_connection.py            # Claude Desktop接続の設定スクリプト（手動実行）

🗺️ ロードマップと将来の方向性

Adaptive Graph of Thoughtsの将来には、グラフの可視化の強化、Arxivなどのより多くのデータソースとの統合、およびコア推論エンジンのさらなる改良など、多くの計画があります。

計画されている機能と長期的な目標の詳細については、ロードマップ（ドキュメントサイトにもあります）を参照してください。

🤝 コントリビューション

コントリビューションを歓迎します！ 始める方法、ブランチング戦略、コードスタイルなどの詳細については、コントリビューションガイドライン（ドキュメントサイトにもあります）を参照してください。

📄 ライセンス

このプロジェクトは、Apache License 2.0の下でライセンスされています。ライセンスを参照してください。

🙏 謝辞

• グラフ分析機能を提供してくれたNetworkXコミュニティ
• 優れたウェブフレームワークを提供してくれたFastAPIチーム
• 堅牢なデータ検証を提供してくれたPydantic
• インスピレーションとフィードバックを提供してくれた科学研究コミュニティ