使用说明

🧠 自适应思维图

🚀 用于科学研究的下一代人工智能推理框架

利用图结构改变人工智能系统进行科学推理的方式

🔍 概述

自适应思维图（AGoT）是一种 高性能MCP服务器 这实现了 高级科学推理思维图（ASR GoT） 框架。它使用 Neo4j图形数据库 作为一个动态知识库，通过 模型上下文协议（MCP），实现与Claude Desktop等人工智能助手的无缝集成。

关键亮点

特性	描述
🧠 基于图的推理	具有8个专门推理阶段的多级管道
📊 动态信心评分	具有不确定性量化的多维评估
🔬 证据整合	实时连接PubMed、谷歌学术和考试搜索
⚡ 高性能	异步FastAPI与Neo4j图操作
🔌 MCP协议	原生Claude桌面和VS代码集成
🐳 云就绪	完全支持Docker+Kubernetes（Helm）

🏗️ 系统架构

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9', 'primaryTextColor': '#fff', 'primaryBorderColor': '#2C5F8A', 'lineColor': '#666', 'secondaryColor': '#52B788', 'tertiaryColor': '#F8F9FA'}}}%%
graph TB
    subgraph Clients["🖥️ Client Layer"]
        CD["🤖 Claude Desktop"]
        VS["💻 VS Code / Cursor"]
        CC["🔗 Custom MCP Clients"]
    end

    subgraph Gateway["🌐 API Gateway Layer"]
        MCP_EP["⚡ MCP Endpoint\n/mcp"]
        NLQ_EP["🔍 NLQ Endpoint\n/nlq"]
        GE_EP["📊 Graph Explorer\n/graph"]
        HE["💚 Health Check\n/health"]
    end

    subgraph Core["🧠 Core Application Layer"]
        direction TB
        GTP["🔄 GoT Processor\nOrchestrator"]
        subgraph Pipeline["ASR-GoT 8-Stage Pipeline"]
            S1["1️⃣ Init &\nContext Setup"]
            S2["2️⃣ Query\nDecomposition"]
            S3["3️⃣ Hypothesis\nGeneration"]
            S4["4️⃣ Evidence\nIntegration"]
            S5["5️⃣ Pruning &\nMerging"]
            S6["6️⃣ Subgraph\nExtraction"]
            S7["7️⃣ Synthesis &\nComposition"]
            S8["8️⃣ Reflection &\nAudit"]
            S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8
        end
        GTP --> Pipeline
    end

    subgraph Services["🛠️ Service Layer"]
        LLM["🤖 LLM Service\nOpenAI / Claude"]
        EDB["📚 Evidence DB\nPubMed · Scholar · Exa"]
    end

    subgraph Storage["🗄️ Storage Layer"]
        NEO4J["📦 Neo4j\nGraph Database"]
        CONFIG["⚙️ Config\n(YAML + ENV)"]
    end

    Clients -->|"MCP JSON-RPC\nBearer Auth"| Gateway
    MCP_EP --> GTP
    NLQ_EP --> LLM
    GE_EP --> NEO4J
    GTP --> Services
    GTP --> NEO4J
    LLM --> EDB

    style Clients fill:#E3F2FD,stroke:#1565C0
    style Gateway fill:#F3E5F5,stroke:#6A1B9A
    style Core fill:#E8F5E9,stroke:#1B5E20
    style Services fill:#FFF8E1,stroke:#F57F17
    style Storage fill:#FCE4EC,stroke:#880E4F

🔄 ASR GoT推理管道

8阶段推理流程将原始问题转化为存储在知识图中的全面、有证据支持的答案：

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#7B68EE', 'edgeLabelBackground': '#fff'}}}%%
flowchart LR
    Q([❓ Scientific\nQuestion]) --> S1

    subgraph S1["Stage 1: Initialization"]
        I1["Set context\n& parameters"]
        I2["Create root\ngraph node"]
        I1 --> I2
    end

    subgraph S2["Stage 2: Decomposition"]
        D1["Identify\nsub-questions"]
        D2["Map knowledge\ndomains"]
        D1 --> D2
    end

    subgraph S3["Stage 3: Hypothesis"]
        H1["Generate\nhypotheses"]
        H2["Score initial\nconfidence"]
        H1 --> H2
    end

    subgraph S4["Stage 4: Evidence"]
        E1["Query PubMed\nScholar · Exa"]
        E2["Integrate\nevidence nodes"]
        E1 --> E2
    end

    subgraph S5["Stage 5: Pruning"]
        P1["Remove weak\nhypotheses"]
        P2["Merge related\nnodes"]
        P1 --> P2
    end

    subgraph S6["Stage 6: Subgraph"]
        SG1["Extract key\nsubgraphs"]
        SG2["Score relevance\n& centrality"]
        SG1 --> SG2
    end

    subgraph S7["Stage 7: Synthesis"]
        C1["Compose final\nnarrative"]
        C2["Build\nconclusions"]
        C1 --> C2
    end

    subgraph S8["Stage 8: Reflection"]
        R1["Audit\nconsistency"]
        R2["Return final\nresult"]
        R1 --> R2
    end

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8
    S8 --> A([✅ Reasoned\nAnswer])

    style Q fill:#FFD700,stroke:#DAA520,color:#000
    style A fill:#90EE90,stroke:#228B22,color:#000

🕸️ 知识图谱连接组

Neo4j知识图将推理结构捕获为一个丰富的连接体——节点表示概念、假设和证据，而边表示语义和逻辑关系：

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#6C63FF', 'primaryTextColor': '#fff', 'edgeLabelBackground': '#f0f0ff'}}}%%
graph TD
    RootQuery["🔍 Root Query\n(Session Node)"]

    subgraph Decomp["📐 Decomposition Layer"]
        D1["📌 Sub-question A\n[domain: biology]"]
        D2["📌 Sub-question B\n[domain: chemistry]"]
        D3["📌 Sub-question C\n[domain: physics]"]
    end

    subgraph Hypo["💡 Hypothesis Layer"]
        H1["💭 Hypothesis 1\nconf: 0.85"]
        H2["💭 Hypothesis 2\nconf: 0.72"]
        H3["💭 Hypothesis 3\nconf: 0.61"]
        H4["💭 Hypothesis 4\nconf: 0.90"]
    end

    subgraph Evid["🔬 Evidence Layer"]
        E1["📄 PubMed Paper\nPMID: 38492"]
        E2["📄 Scholar Article\nDOI: 10.1038/..."]
        E3["🌐 Exa Result\nexpert consensus"]
        E4["📊 Statistical\nMeta-analysis"]
    end

    subgraph Synth["🎯 Synthesis Layer"]
        C1["✅ Merged\nConclusion A"]
        C2["✅ Merged\nConclusion B"]
        FINAL["🏆 Final Answer\n[confidence: 0.88]"]
    end

    RootQuery -->|"DECOMPOSES_TO"| D1
    RootQuery -->|"DECOMPOSES_TO"| D2
    RootQuery -->|"DECOMPOSES_TO"| D3

    D1 -->|"GENERATES"| H1
    D1 -->|"GENERATES"| H2
    D2 -->|"GENERATES"| H3
    D3 -->|"GENERATES"| H4

    H1 -->|"SUPPORTED_BY"| E1
    H2 -->|"SUPPORTED_BY"| E2
    H3 -->|"CONTRADICTED_BY"| E3
    H4 -->|"SUPPORTED_BY"| E4

    H1 -->|"MERGES_WITH"| C1
    H4 -->|"MERGES_WITH"| C1
    H2 -->|"MERGES_WITH"| C2
    C1 -->|"SYNTHESIZES_TO"| FINAL
    C2 -->|"SYNTHESIZES_TO"| FINAL

    style RootQuery fill:#4A90D9,color:#fff,stroke:#2C5F8A
    style FINAL fill:#27AE60,color:#fff,stroke:#1E8449
    style H3 fill:#E74C3C,color:#fff,stroke:#C0392B

🔁 请求流

%%{init: {'theme': 'base'}}%%
sequenceDiagram
    actor User as 🤖 Claude / MCP Client
    participant API as ⚡ FastAPI Server
    participant Auth as 🔐 Auth Middleware
    participant GTP as 🧠 GoT Processor
    participant NEO as 📦 Neo4j DB
    participant LLM as 🤖 LLM Service

    User->>API: POST /mcp {"method": "asr_got.query"}
    API->>Auth: Verify Bearer Token
    Auth-->>API: ✅ Authorized

    API->>GTP: Process query
    GTP->>NEO: Create session + root node

    loop 8 Pipeline Stages
        GTP->>LLM: Generate hypotheses / summaries
        LLM-->>GTP: LLM response
        GTP->>NEO: Write nodes & relationships
        NEO-->>GTP: Confirmed
    end

    GTP->>NEO: Extract final subgraph
    NEO-->>GTP: Final answer graph
    GTP-->>API: Structured result

    API-->>User: JSON-RPC response\n{result, confidence, graph_state}

📚 文档

完整的文档，包括API参考、配置指南和贡献指南：

➡️ 自适应思维图文档网站

📂 项目结构

Adaptive-Graph-of-Thoughts-MCP-server/
├── 📁 .github/             # CI/CD workflows (CodeQL, Dependabot)
├── 📁 agt_setup/           # Interactive setup wizard CLI
├── 📁 config/              # settings.yaml configuration
├── 📁 docs_src/            # MkDocs documentation source
├── 📁 helm/                # Kubernetes Helm chart
├── 📁 src/
│   └── 📁 adaptive_graph_of_thoughts/
│       ├── 📁 api/         # FastAPI routes & schemas
│       ├── 📁 application/ # GoTProcessor orchestrator
│       ├── 📁 domain/      # 8-stage pipeline & models
│       ├── 📁 infrastructure/ # Neo4j utilities
│       └── 📁 services/    # LLM & external API clients
├── 📁 tests/               # Comprehensive test suite
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md

🚀 快速开始

git clone https://github.com/SaptaDey/Adaptive-Graph-of-Thoughts-MCP-server.git
cd Adaptive-Graph-of-Thoughts-MCP-server
poetry install
poetry run python -m agt_setup   # Interactive credential setup wizard
poetry run uvicorn adaptive_graph_of_thoughts.main:app --reload

访问 http://localhost:8000/docs 用于交互式API文档。

🚀 入门指南

部署先决条件

在运行Adaptive Graph of Thoughts之前（本地或通过Docker，如果不使用提供的 docker-compose.prod.yml 其中包括Neo4j），确保您拥有：

正在运行的Neo4j实例：Adaptive Graph of Thoughts需要连接到Neo4j图形数据库。
- APOC图书馆：至关重要的是，Neo4j实例必须安装APOC（Awesome Procedures On Cypher）库。应用程序推理阶段内的几个Cypher查询利用APOC过程（例如。， apoc.create.addLabels, apoc.merge.node).没有APOC，应用程序将无法正常运行。您可以在上找到安装说明 APOC官方网站.
- 配置：确保您的 config/settings.yaml （或相应的环境变量）正确指向您的Neo4j实例URI、用户名和密码。
- 索引：为了获得最佳性能，请确保创建了适当的Neo4j索引。你可以跑 python scripts/run_cypher_migrations.py 自动应用提供的Cypher迁移。看 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/Adaptive-Graph-of-Thoughts-MCP-server.git
cd Adaptive-Graph-of-Thoughts-MCP-server

使用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

秘密管理

在生产环境中，设置 SECRETS_PROVIDER 环境变量 aws, gcp，或 vault 从支持的机密中获取敏感值经理。可选提供 <VAR>_SECRET_NAME 变量（例如 OPENAI_API_KEY_SECRET_NAME)控制每个秘密的名称。当一个秘密提供程序已配置，值为 OPENAI_API_KEY, ANTHROPIC_API_KEY，以及 NEO4J_PASSWORD 启动时自动加载。

运行开发服务器:

python src/adaptive_graph_of_thoughts/main.py

或者，为了获得更多控制：

uvicorn adaptive_graph_of_thoughts.main:app --reload --host 0.0.0.0 --port 8000

API将于 http://localhost:8000.

✨ 安装向导

交互式向导可用于简化初始配置。

poetry run python -m agt_setup

然后访问 http://localhost:8000/setup 完成基于网络的步骤。

安装向导演示GIF将出现在完整文档中。

Docker部署

graph TB
    subgraph "Development Environment"
        A[👨‍💻 Developer] --> B[🐳 Docker Compose]
    end
    
    subgraph "Container Orchestration"
        B --> C[📦 Adaptive Graph of Thoughts Container]
        B --> D[📊 Monitoring Container]
        B --> E[🗄️ Database Container]
    end
    
    subgraph "Adaptive Graph of Thoughts 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 adaptive-graph-of-thoughts

单个Docker容器:

# Build the image
docker build -t adaptive-graph-of-thoughts:latest .

# Run the container
docker run -p 8000:8000 -v $(pwd)/config:/app/config adaptive-graph-of-thoughts:latest

生产部署:

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

Kubernetes部署（Helm）

最低限度舵图表如下 helm/agot-server 为了在Kubernetes集群上运行自适应思维图。

helm install agot helm/agot-server

在中自定义值 helm/agot-server/values.yaml 为了设置图像存储库，资源限制和其他选项。

特定部署平台说明

Smithery.ai：使用随附的进行部署 smithery.yaml.
- 在Smithery上连接您的GitHub存储库并单击部署.
- 容器监听 PORT 环境变量（默认值 8000).
- 健康检查 依靠 /health 终点。
- 这 Dockerfile 和 docker-compose.prod.yml 说明容器设置。

访问服务:
- API文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health
- MCP端点: http://localhost:8000/mcp

🔌 MCP客户端集成

支持的MCP客户端

Adaptive Graph of Thoughts支持与各种MCP客户端的集成：

克劳德桌面版 -完全支持STDIO和HTTP
VS Code -通过MCP扩展
自定义MCP客户端 -通用配置可用

快速客户端设置

克劳德桌面/VS代码设置

{
  "mcpServers": {
    "adaptive-graph-of-thoughts": {
      "command": "python",
      "args": ["-m", "adaptive_graph_of_thoughts.main"],
      "cwd": "/path/to/Adaptive-Graph-of-Thoughts-MCP-server",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

可用的MCP工具

工具	说明
`scientific_reasoning_query`	用图形分析进行高级科学推理
`analyze_research_hypothesis`	基于置信度评分的假设评估
`explore_scientific_relationships`	概念关系映射
`validate_scientific_claims`	基于证据的索赔验证

🔌 API终点

自适应思想图谱揭示的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、 Adaptive Graph of Thoughts目前不支持真正的多回合对话连续性，其中来自前一个查询的详细图形状态或推理上下文会自动加载，并使用相同的上下文重新用于后续查询 session_id。此时每个查询都是独立处理的。

未来增强：持续会话

自适应思维图未来的一个潜在增强是实现持久会话。这将使用户能够：

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

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

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

这是一个重要的功能，可以大大增强自适应思维图的交互能力。欢迎社区在设计和实现持久会话功能方面做出贡献。

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

目前，自适应思维图推理流水线的8个阶段是按顺序执行的。对于复杂的查询或进一步优化性能，探索管道某些部分的异步或并行执行是未来的一个潜在增强。

并行性的潜在领域：

假设生成： 这 HypothesisStage 为每个维度生成假设 DecompositionStage生成假设的过程 不同的、独立的维度 可以潜在地并行化。例如，如果分解了三个维度，三个并行任务可以为每个维度生成假设。
证据整合（部分）： 在 EvidenceStage如果选择了多个假设进行评估，那么这些不同假设的“计划执行”阶段（模拟证据收集）可能会同时进行。

挑战和考虑因素：

实施并行阶段执行将引入需要谨慎管理的复杂性：

数据一致性： 并发操作，特别是写入Neo4j数据库（例如，同时创建多个假设节点或证据节点），必须谨慎处理，以确保数据完整性并避免竞争条件。唯一的ID生成方案需要对并行执行具有鲁棒性。
交易管理： 需要对并发写入的Neo4j事务进行适当的管理。
依赖关系管理： 确保真正依赖于他人输出的阶段（或阶段的一部分）正确排序至关重要。
资源利用率： 并行执行可能会增加资源需求（CPU、内存、数据库连接）。
复杂性： 总体控制流程 GoTProcessor 会变得更加复杂。

虽然当前的顺序执行确保了清晰和可管理的数据流，但在独立维度的假设生成等领域有针对性的并行性可以为未来版本的自适应思维图提供性能优势。这仍然是一个开放的研究和开发领域。

🧪 测试和质量保证

🧪 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

开发命令

GitHub Actions上的持续集成管道运行测试、CodeQL分析和用于DevOps安全扫描的Microsoft Defender。

# 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 (runs Ruff and MyPy)

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

🖥 仪表板之旅

仪表板演示GIF即将推出。

💻 IDE 集成

使用 vscode-agot 扩展从VS Code查询服务器。运行扩展并执行 AGoT：问图… 从命令选项板。

❓ 故障排除

如果服务器无法启动或安装程序报告错误，请确保您的Neo4j实例正在运行，并且中的凭据 .env 是正确的。有关详细信息，请参阅控制台输出。

🗺️ 路线图和未来方向

我们对自适应思维图谱的未来有着令人兴奋的愿景！我们的路线图包括增强图形可视化的计划，与Arxiv等更多数据源的集成，以及对核心推理引擎的进一步改进。

有关我们计划的功能和长期目标的更多详细信息，请参阅我们的路线图（也可在文档网站上找到）。

🤝 贡献

我们欢迎捐款！请查看我们的贡献指南（也可在文档网站上找到），了解如何开始、我们的分支策略、代码风格等详细信息。

📄 许可证

此项目根据Apache许可证2.0获得许可。许可证.

🔒 安全

请查看我们的安全策略用于报告漏洞和支持版本的详细信息。

🙏 致谢

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

Built with ❤️ for the scientific research community

Adaptive Graph of Thoughts - Advancing scientific reasoning through intelligent graph structures