使用说明

🧠 NexusMind

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

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

🚀 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）
诗歌：用于依赖关系管理
码头工人 和 Docker Compose：用于集装箱化部署

安装和设置（本地开发）

克隆存储库:

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

使用Poetry安装依赖项:
```
poetry install
```
这将创建一个虚拟环境，并安装中指定的所有必要软件包 pyproject.toml.
激活虚拟环境:
```
poetry shell
```

配置应用程序:

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

# Edit configuration as needed
vim config/settings.yaml

设置环境变量 （可选）：

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

运行开发服务器:

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

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

单个Docker容器:

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

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

生产部署:

# 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的要求进行调整。

访问服务:
- 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未来的一个潜在增强是实现持久会话。这将使用户能够：

持续状态： 存储查询中生成的图形状态和相关推理上下文，并将其与其关联 session_id，可能在Neo4j数据库中。
重新加载状态： 当新查询与现有查询一起提交时 session_id，系统可以重新加载此保存的状态作为进一步处理的起点。
优化和扩展： 允许新查询与加载的图进行交互，例如，通过改进之前的假设、向现有结构添加新证据或基于已建立的上下文探索替代推理路径。

实施持续会议将涉及制定强有力的战略，以：

在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

使用说明

🧠 NexusMind

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

📚 文档

🔍 概述

📂 项目结构

🚀 入门指南

部署先决条件

先决条件

安装和设置（本地开发）

Docker部署

特定部署平台说明

🔌 API终点

会话处理(session_id)

未来增强：持续会话

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

🧪 测试和质量保证

开发命令

🗺️ 路线图和未来方向

🗺️ 路线图和未来方向

🤝 贡献

📄 许可证

🙏 致谢

相关 MCP

知识图谱MCP服务器

图数据库协议服务

深度研究报告生成工具

NebulaGraph模型上下文协议服务器

论文与代码搜索工具

深度研究服务器

会话处理(`session_id`)