🧠 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） - 诗歌：用于依赖关系管理
- 码头工人 和 ****：用于集装箱化部署
安装和设置（本地开发）
- 克隆存储库:
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 8000API将于 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