🧠 Adaptive Graph of Thoughts

🧠 自适应思维图

🔍 概述

自适应思维图（AGoT）是一款高性能 MCP 服务，实现了高级科学推理思维图（ASR-GoT）框架。它使用Neo4j 图数据库作为动态知识存储，并通过**模型上下文协议（MCP）**提供推理能力，从而能够与 Claude Desktop 等 AI 助手无缝集成。

主要亮点

🏗️ 系统架构

%%{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 之前（无论是在本地运行，还是在不使用包含 Neo4j 的 docker-compose.prod.yml 时通过 Docker 运行），请确保具备以下条件：

• 正在运行的 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）
• Poetry：用于依赖管理
• Docker 和 Docker Compose：用于容器化部署

安装和设置（本地开发）

1. 克隆代码库：

   git clone https://github.com/SaptaDey/Adaptive-Graph-of-Thoughts-MCP-server.git
   cd Adaptive-Graph-of-Thoughts-MCP-server
   

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
   

密钥管理

在生产环境中，将 SECRETS_PROVIDER 环境变量设为 aws、gcp 或 vault，以从受支持的密钥管理器中获取敏感值。你还可以选择提供 <VAR>_SECRET_NAME 变量（例如 OPENAI_API_KEY_SECRET_NAME），以控制各个密钥的名称。配置密钥提供方后，启动时会自动加载 OPENAI_API_KEY、ANTHROPIC_API_KEY 和 NEO4J_PASSWORD 的值。

6. 运行开发服务器：

   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，完成基于 Web 的设置步骤。

完整文档中将在此处展示设置向导演示 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

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 adaptive-graph-of-thoughts
   

2. 单独的 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
   

3. 生产环境部署：

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

Kubernetes 部署（Helm）

我们在 helm/agot-server 下提供了一个精简的 Helm chart，用于在 Kubernetes 集群上运行 Adaptive Graph of Thoughts。

helm install agot helm/agot-server

在 helm/agot-server/values.yaml 中自定义配置，以设置镜像仓库、资源限制和其他选项。

特定部署平台说明

• Smithery.ai：使用随附的 smithery.yaml 进行部署。
  • 在 Smithery 上连接你的 GitHub 仓库，然后点击 Deploy。
  • 容器监听 PORT 环境变量（默认值为 8000）。
  • 健康检查依赖 /health 端点。
  • Dockerfile 和 docker-compose.prod.yml 展示了容器设置。

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

🔌 MCP 客户端集成

支持的 MCP 客户端

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

• Claude Desktop - 完整支持 STDIO 和 HTTP
• VS Code - 通过 MCP 扩展
• 自定义 MCP 客户端 - 提供通用配置

快速设置客户端

Claude Desktop / VS Code 设置

{
  "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 工具

🔌 API 端点

Adaptive Graph of Thoughts 提供的主要 API 端点如下：

• MCP 协议端点：POST /mcp

  • 此端点用于与 Claude Desktop 等 MCP 客户端通信。
  • asr_got.query 方法的请求示例：

    {
      "jsonrpc": "2.0",
      "method": "asr_got.query",
      "params": {
        "query": "分析微生物组多样性与癌症进展之间的关系。",
        "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 请求中可用的 session_id 参数（例如用于 asr_got.query 的请求）以及响应中包含的 session_id，主要用于标识和跟踪单次完整的请求—响应周期。它也用于将进度通知（如 got/queryProgress）与发起该通知的请求关联起来。

虽然系统会生成并使用 session_id，但 Adaptive Graph of Thoughts 目前不支持真正的多轮对话连续性，也就是说，不会自动加载并复用先前查询的详细图状态或推理上下文，以便使用相同的 session_id 处理后续查询。目前，每个查询都是独立处理的。

未来增强：持久会话

Adaptive Graph of Thoughts 未来可能会增强持久会话功能。通过允许用户执行以下操作，这一功能可以实现更具交互性且不断演进的推理过程：

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

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

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

这是一项重要功能，能够大幅增强 Adaptive Graph of Thoughts 的交互能力。欢迎社区参与设计和实现持久会话功能。

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

目前，Adaptive Graph of Thoughts 推理管线的 8 个阶段按顺序执行。对于复杂查询，或为了进一步优化性能，探索并行或异步执行管线中的某些部分，是一项未来可能的增强。

可能实现并行的环节：

• 假设生成： HypothesisStage 会针对 DecompositionStage 识别的每个维度生成假设。针对不同且相互独立的维度生成假设的过程可能可以并行执行。例如，如果拆解出三个维度，就可以运行三个并行任务，分别为每个维度生成假设。
• 证据整合（部分）： 在 EvidenceStage 中，如果选取了多个假设进行评估，那么针对这些不同假设的“计划执行”阶段（模拟证据收集）可能可以并发执行。

挑战与注意事项：

实现并行阶段执行会带来复杂问题，需要谨慎管理：

• 数据一致性： 必须谨慎处理并发操作，尤其是对 Neo4j 数据库的写入（例如同时创建多个假设节点或证据节点），以确保数据完整性并避免竞态条件。唯一 ID 生成方案必须能可靠地支持并行执行。
• 事务管理： 需要妥善管理并发写入的 Neo4j 事务。
• 依赖管理： 确保真正依赖其他阶段输出的阶段（或阶段的部分环节）按正确顺序执行，这一点至关重要。
• 资源利用： 并行执行可能会增加资源需求（CPU、内存、数据库连接）。
• 复杂性： GoTProcessor 的整体控制流会变得更加复杂。

当前按顺序执行的方式可确保数据流清晰且易于管理，而针对独立维度的假设生成等环节进行定向并行化，则可能为 Adaptive Graph of Thoughts 的未来版本带来性能优势。这仍是一个有待研究和开发的领域。

🧪 测试与质量保证

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 分析和 Microsoft Defender for DevOps 安全扫描。

# 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: Ask Graph…。

❓ 故障排除

如果服务无法启动或设置过程中报告错误，请确保 Neo4j 实例正在运行，并确认 .env 中的凭据正确。请查看控制台输出了解详情。

🗺️ 路线图与未来方向

我们对 Adaptive Graph of Thoughts 的未来有着令人振奋的愿景！路线图包括增强图可视化、集成更多数据源（如 Arxiv），以及进一步改进核心推理引擎。

如需详细了解计划中的功能和长期目标，请参阅我们的路线图（文档网站上也提供此内容）。

🤝 参与贡献

欢迎参与贡献！有关如何开始、分支策略、代码风格等详情，请参阅我们的贡献指南（文档网站上也提供此内容）。

📄 许可证

本项目基于 Apache License 2.0 授权。许可证。

🔒 安全

有关漏洞报告方式和受支持版本的详情，请参阅我们的安全策略。

🙏 致谢

• 感谢 NetworkX 社区提供图分析能力
• 感谢 FastAPI 团队打造出色的 Web 框架
• 感谢 Pydantic 提供可靠的数据验证
• 感谢科学研究社区带来的灵感与反馈