Nexus Mind 2 0

🧠 NexusMind

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

通过思维图形进行智能科学推理

](https://github.com/SaptaDey/NexusMind/releases)   ](Dockerfile)   

🚀 Next-Generation AI Reasoning Framework for Scientific Research

Leveraging graph structures to transform how AI systems approach scientific reasoning

📚 文档

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

➡️ NexusMind文档网站 *（注意：一旦GitHub Pages网站通过新工作流部署，此链接将处于活动状态。）*

🔍 概述

NexusMind利用 Neo4j图形数据库 执行复杂的科学推理，在其管道阶段管理图形操作。它实现了 模型上下文协议（MCP） 与Claude Desktop等人工智能应用程序集成，提供专为复杂研究任务设计的高级科学推理思维图（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-compose.prod.yml 其中包括Neo4j），确保您拥有：

• 正在运行的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）
• 诗歌：用于依赖关系管理
• 码头工人 和 ****：用于集装箱化部署

安装和设置（本地开发）

1. 克隆存储库:

   git clone https://github.com/SaptaDey/NexusMind.git
   cd NexusMind

1. 使用Poetry安装依赖项:

   poetry install

这将创建一个虚拟环境，并安装中指定的所有必要软件包 pyproject.toml.

1. 激活虚拟环境:

   poetry shell

1. 配置应用程序:

   # Copy example configuration
   cp config/settings.example.yaml config/settings.yaml

   # Edit configuration as needed
   vim config/settings.yaml

1. 设置环境变量 （可选）：

   # Create .env file for sensitive configuration
   echo "LOG_LEVEL=DEBUG" > .env
   echo "API_HOST=0.0.0.0" >> .env
   echo "API_PORT=8000" >> .env

1. 运行开发服务器:

   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

1. 单个Docker容器:

   # Build the image
   docker build -t nexusmind:latest .

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

1. 生产部署:

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

特定部署平台说明

• Smithery.ai：部署到Smithery.ai平台通常需要直接使用提供的Docker镜像。

- 有关部署自定义Docker镜像的说明，请参阅Smithery.ai的具体文档。 - 端口配置：确保平台配置为暴露端口8000（或通过以下方式配置的端口 APP_PORT 如果被覆盖），因为这是FastAPI应用程序使用的默认端口。 - 健康检查：Smithery.ai可能会使用健康检查来监控容器状态。NexusMind Docker镜像包括 HEALTHCHECK 验证以下内容的指令 /health 端点（例如。， http://localhost:8000/health).如果Smithery.ai需要特定的健康检查路径，请确保将其配置为使用此终结点。 - 提供的 Dockerfile 和 docker-compose.prod.yml 作为理解容器设置的基准。根据Smithery.ai的要求进行调整。

1. 访问服务:

- 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)

目前 session_id API请求中可用的参数（例如 asr_got.query)并且存在于响应中主要用于识别和跟踪单个完整的查询响应周期。它还用于关联进度通知（如 got/queryProgress)与原始查询一起。

当系统生成和利用 session_ids、 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的未来版本提供性能优势。这仍然是一个开放的研究和开发领域。

🧪 测试和质量保证

🧪 Testing 🔍 Type Checking ✨ Linting 📊 Coverage

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许可证2.0获得许可。 许可证.

🙏 致谢

• 网络X 图形分析能力社区
• 快速 API 优秀web框架团队
• 派丹蒂克 用于稳健的数据验证
• 科研界寻求灵感和反馈

______________________________________________________________________

Built with ❤️ for the scientific research community

NexusMind - Advancing scientific reasoning through intelligent graph structures