🧠 NexusMind

🧠 NexusMind

                                              ╔══════════════════════════════════════╗
                                              ║                                      ║
                                              ║           🧠 NexusMind 🧠           ║
                                              ║                                      ║
                                              ║     Intelligent Scientific           ║
                                              ║     Reasoning through                ║
                                              ║     Graph-of-Thoughts                ║
                                              ║                                      ║
                                              ╚══════════════════════════════════════╝

📚 ドキュメント

詳細なインストール手順、使用ガイド、設定オプション、API リファレンス、貢献ガイドライン、プロジェクトのロードマップなど、NexusMind に関する包括的な情報については、以下の完全版ドキュメントサイトをご覧ください。

➡️ NexusMind ドキュメントサイト (注：新しいワークフローで GitHub Pages サイトがデプロイされると、このリンクが有効になります。)

🔍 概要

NexusMind は、Neo4j グラフデータベースを活用して高度な科学的推論を実行し、パイプラインの各ステージ内でグラフ操作を管理します。**Model Context Protocol（MCP）**を実装することで、Claude Desktop などの AI アプリケーションと連携します。複雑な研究タスク向けに設計された、Advanced Scientific Reasoning Graph-of-Thoughts（ASR-GoT）フレームワークを提供します。

主な特長：

• グラフベースの推論を使用して複雑な科学的クエリを処理
• 多次元評価による動的な信頼度スコアリング
• 高いパフォーマンスを実現する、最新の Python と FastAPI による構築
• デプロイが容易な Docker 化
• 拡張やカスタマイズに対応するモジュール設計
• MCP プロトコルを介した Claude Desktop との連携

📂 プロジェクト構成

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

NexusMind/
├── 📁 .github/                           # GitHub specific files (workflows)
├── 📁 config/                             # Configuration files (settings.yaml)
├── 📁 docs_src/                           # Source files for MkDocs documentation
├── 📁 src/                                # Source code
│   └── 📁 asr_got_reimagined/            # Main application package
├── 📁 tests/                             # Test suite
├── Dockerfile                            # Docker container definition
├── docker-compose.yml                    # Docker Compose for development
├── docker-compose.prod.yml               # Docker Compose for production
├── mkdocs.yml                            # MkDocs configuration
├── poetry.lock                           # Poetry dependency lock file
├── pyproject.toml                        # Python project configuration (Poetry)
├── pyrightconfig.json                    # Pyright type checker configuration
├── README.md                             # This file
└── setup_claude_connection.py            # Script for Claude Desktop connection setup (manual run)

🚀 はじめに

デプロイの前提条件

NexusMind を実行する前に（Neo4j を含む提供済みの docker-compose.prod.yml を使用せず、ローカルまたは Docker 経由で実行する場合）、次の条件を満たしていることを確認してください。

• 稼働中の Neo4j インスタンス：NexusMind は 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 のインデックス戦略をご覧ください。

  注：提供済みの 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/NexusMind.git
   cd NexusMind
   

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

   poetry install
   

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

3. 仮想環境を有効にします：

   poetry shell
   

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

   # Copy example configuration
   cp config/settings.example.yaml config/settings.yaml
   
   # Edit configuration as needed
   vim config/settings.yaml
   

5. 環境変数を設定します（任意）：

   # Create .env file for sensitive configuration
   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 "Development Environment"
        A[👨‍💻 Developer] --> B[🐳 Docker Compose]
    end
    
    subgraph "Container Orchestration"
        B --> C[📦 NexusMind Container]
        B --> D[📊 Monitoring Container]
        B --> E[🗄️ Database Container]
    end
    
    subgraph "NexusMind Application"
        C --> F[⚡ FastAPI Server]
        F --> G[🧠 ASR-GoT Engine]
        F --> H[🔌 MCP Protocol]
    end
    
    subgraph "External Integrations"
        H --> I[🤖 Claude Desktop]
        H --> J[🔗 Other AI Clients]
    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 によるクイックスタート：

   # Build and run all services
   docker-compose up --build
   
   # For detached mode (background)
   docker-compose up --build -d
   
   # View logs
   docker-compose logs -f nexusmind
   

2. 個別の Docker コンテナー：

   # Build the image
   docker build -t nexusmind:latest .
   
   # Run the container
   docker run -p 8000:8000 -v $(pwd)/config:/app/config nexusmind:latest
   

3. 本番環境へのデプロイ：

   # Use production compose file
   docker-compose -f docker-compose.prod.yml up --build -d
   

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

• Smithery.ai：Smithery.ai プラットフォームへのデプロイでは、通常、提供されている Docker イメージをそのまま使用します。
  • カスタム Docker イメージのデプロイ手順については、Smithery.ai の公式ドキュメントを参照してください。
  • ポート設定：NexusMind コンテナーでポート 8000（または APP_PORT で設定したポート。上書きされている場合）を公開するよう、プラットフォームが設定されていることを確認してください。これは FastAPI アプリケーションがデフォルトで使用するポートです。
  • ヘルスチェック：Smithery.ai は、コンテナーの状態を監視するためにヘルスチェックを使用する場合があります。NexusMind の 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 エンドポイント

NexusMind が公開する主な API エンドポイントは次のとおりです。

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

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

    {
      "jsonrpc": "2.0",
      "method": "asr_got.query",
      "params": {
        "query": "マイクロバイオームの多様性とがんの進行との関係を分析してください。",
        "parameters": {
          "include_reasoning_trace": true,
          "include_graph_state": false
        }
      },
      "id": "123"
    }
    

  • ほかに、initialize と shutdown の MCP メソッドをサポートしています。

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

  • アプリケーションの簡易的なヘルスステータスを返します。
  • レスポンス例：

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

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

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

セッションの処理（session_id）

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

システムは session_id を生成して利用しますが、NexusMind は現在、同じ session_id を使った後続のクエリに対して、以前のクエリの詳細なグラフ状態や推論コンテキストを自動的に読み込んで再利用する、真のマルチターン会話の継続には対応していません。現時点では、各クエリは個別に処理されます。

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

NexusMind の将来的な機能強化として、セッションの永続化が考えられます。これにより、ユーザーは次のことが可能になり、より対話的で発展性のある推論プロセスを実現できます。

1. 状態の永続化： クエリから生成されたグラフの状態と関連する推論コンテキストを、その session_id に関連付けて保存します。保存先としては、Neo4j データベースが考えられます。
2. 状態の再読み込み： 既存の session_id を指定して新しいクエリが送信された際に、保存済みの状態を読み込み、その後の処理の開始点として使用します。
3. 修正と拡張： 新しいクエリで読み込んだグラフを操作できるようにします。たとえば、以前の仮説を修正したり、既存の構造に新たな証拠を追加したり、確立されたコンテキストに基づいて別の推論経路を探索したりできます。

セッションの永続化を実装するには、次のような堅牢な方法を開発する必要があります。

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

これは、NexusMind の対話機能を大幅に強化できる重要な機能です。セッションの永続化機能の設計と実装に関するコミュニティからの貢献を歓迎します。

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

現在、NexusMind の推論パイプラインの 8 つのステージは順次実行されます。複雑なクエリに対応する場合や、パフォーマンスをさらに最適化する場合、一部のパイプライン処理を非同期または並列で実行する方法を検討することが、将来的な機能強化として考えられます。

並列化できる可能性のある領域：

• 仮説の生成： HypothesisStage は、DecompositionStage で特定された各次元について仮説を生成します。互いに独立した異なる次元の仮説を生成する処理は、並列化できる可能性があります。たとえば、3 つの次元に分解された場合、それぞれの次元の仮説を生成する 3 つの並列タスクを実行できます。
• 証拠の統合（一部）： EvidenceStage で評価対象として複数の仮説が選択された場合、これらの異なる仮説に対する「計画の実行」フェーズ（証拠収集のシミュレーション）を同時に実行できる可能性があります。

課題と考慮事項：

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

• データの整合性： 同時実行される処理、特に Neo4j データベースへの書き込み（複数の仮説ノードや証拠ノードを同時に作成する場合など）は、データの完全性を確保し、競合状態を回避できるよう慎重に処理する必要があります。並列実行に対応した堅牢な一意 ID の生成方式も必要です。
• トランザクション管理： 同時書き込みに対する Neo4j のトランザクションを適切に管理する必要があります。
• 依存関係の管理： 他のステージの出力に実際に依存するステージ（またはステージの一部）が正しい順序で実行されるようにすることが重要です。
• リソースの使用： 並列実行によって、リソース（CPU、メモリ、データベース接続）の需要が増える可能性があります。
• 複雑さ： GoTProcessor 全体の制御フローがより複雑になります。

現在の順次実行では明確で管理しやすいデータフローが確保されていますが、独立した次元の仮説生成など、対象を絞った並列化により、NexusMind の将来のバージョンでパフォーマンスが向上する可能性があります。これは引き続き研究開発が求められる分野です。

🧪 テストと品質保証

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

開発コマンド

# Run full test suite with coverage using Poetry
poetry run pytest --cov=src --cov-report=html --cov-report=term

# Or using Makefile for the default test run
make test

# Run specific test categories (using poetry)
poetry run pytest tests/unit/stages/          # Stage-specific tests
poetry run pytest tests/integration/         # Integration tests
poetry run pytest -k "test_confidence"       # Tests matching pattern

# Type checking and linting (can also be run via Makefile targets: make lint, make check-types)
poetry run mypy src/ --strict                # Strict type checking
poetry run ruff check . --fix                # Auto-fix linting issues
poetry run ruff format .                     # Format code

# Pre-commit hooks (recommended)
poetry run pre-commit install                # Install hooks
poetry run pre-commit run --all-files       # Run all hooks

# See Makefile for other useful targets like 'make all-checks'.

🗺️ ロードマップと今後の展望

NexusMind の将来には、わくわくするようなビジョンがあります！ロードマップには、グラフの可視化の強化、Arxiv などのデータソースとの連携、コア推論エンジンのさらなる改良が含まれています。

計画中の機能や長期目標の詳細については、ロードマップ（ドキュメントサイトからもご覧いただけます）をご確認ください。

🗺️ ロードマップと今後の展望

NexusMind の将来には、わくわくするようなビジョンがあります！ロードマップには、グラフの可視化の強化、Arxiv などのデータソースとの連携、コア推論エンジンのさらなる改良が含まれています。

計画中の機能や長期目標の詳細については、ロードマップをご確認ください。

🤝 コントリビューション

コントリビューションを歓迎します！始め方、ブランチ戦略、コードスタイルなどの詳細については、コントリビューションガイドライン（ドキュメントサイトからもご覧いただけます）をご確認ください。

📄 ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。ライセンス。

🙏 謝辞

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