🧠 NexusMind

🧠 NexusMind

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

📚 文档

如需了解 NexusMind 的全面信息，包括详细的安装说明、使用指南、配置选项、API 参考、贡献指南和项目路线图，请访问我们的完整文档网站：

➡️ 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 之前（无论是在本地运行，还是通过 Docker 运行；如果不使用包含 Neo4j 的 docker-compose.prod.yml），请确保：

• 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 镜像。
  • 请参阅 Smithery.ai 的相关文档，了解部署自定义 Docker 镜像的说明。
  • 端口配置：请确保平台已配置为向 NexusMind 容器开放端口 8000（或通过 APP_PORT 配置的端口，如有覆盖），因为这是 FastAPI 应用程序默认使用的端口。
  • 健康检查：Smithery.ai 可能会使用健康检查来监控容器状态。NexusMind Docker 镜像包含一条 HEALTHCHECK 指令，用于验证 /health 端点（例如，http://localhost:8000/health）。如果 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": "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，但 NexusMind 目前不支持真正的多轮对话连续性，也就是说，不会自动加载并重用先前查询的详细图状态或推理上下文，以便使用相同的 session_id 处理后续查询。目前，每个查询都是独立处理的。

未来增强：持久化会话

NexusMind 未来可能进行的一项增强是实现持久化会话。这样，用户便可以：

1. **持久化状态：**存储查询生成的图状态和相关推理上下文，并将其与对应的 session_id 关联；这些数据可能存储在 Neo4j 数据库中。
2. **重新加载状态：**如果新查询使用已有的 session_id 提交，系统可以重新加载已保存的状态，将其作为后续处理的起点。
3. **优化和扩展：**允许新查询与加载的图进行交互，例如优化先前的假设、向现有结构添加新证据，或基于既定上下文探索其他推理路径。

实现持久化会话需要制定可靠的策略，以便：

• 在 Neo4j 中高效地存储和检索特定会话的图数据。
• 管理会话数据的生命周期（例如，创建、更新、过期）。
• 设计复杂的逻辑，确定新查询如何与预先存在的会话上下文和图合并、修改或扩展。

这是一项重要功能，可以大幅增强 NexusMind 的交互能力。欢迎社区参与设计和实现持久化会话功能。

未来增强：异步和并行执行阶段

目前，NexusMind 推理管道的 8 个阶段按顺序执行。对于复杂查询，或为了进一步优化性能，未来可以探索对管道的某些部分进行异步或并行执行。

可能适合并行处理的部分：

• 假设生成：HypothesisStage 会针对 DecompositionStage 识别出的每个维度生成假设。针对不同且彼此独立的维度生成假设的过程可能可以并行化。例如，如果分解出三个维度，就可以启动三个并行任务，分别为每个维度生成假设。
• **证据整合（部分）：**在 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 团队打造出色的 Web 框架
• 感谢 Pydantic 提供可靠的数据验证
• 感谢科学研究社区带来的灵感与反馈