# zhongyi-zhou/toolgrad architecture

> Architecture diagram of the GitHub repository zhongyi-zhou/toolgrad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhongyi-zhou/toolgrad
- Repository: https://github.com/zhongyi-zhou/toolgrad

## Overview

ToolGrad is a tool-use workflow and dataset-generation framework, with separate tooling for preparing training data, fine-tuning models, and evaluating tool-use results. Its runtime workflow samples APIs, proposes and executes calls, selects reports, and updates a workflow; prebuilt graphs support MCP and ToolBench. The README documents raw workflow generation, SFT, and BFCL evaluation. Some large modules and data branches are indexed but not excerpted, so their internal call relationships are omitted rather than inferred.

Main entry points: [`toolgrad/modules/graph_lib.py`](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/graph_lib.py) (Workflow stages), [`toolgrad/modules/module_lib.py`](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/module_lib.py) (Proposal and execution), [`toolgrad/utils/toolbench/toolbench_langchain_utils.py`](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/toolbench/toolbench_langchain_utils.py) (ToolBench adapter), [`toolgrad/prebuilt/toolgrad_on_mcp.py`](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/prebuilt/toolgrad_on_mcp.py) (MCP graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow runtime"]
  node_prebuilt_mcp["MCP graph<br/>[toolgrad_on_mcp.py]"]
  node_prebuilt_toolbench["ToolBench graph"]
  node_graph_stages["Workflow stages<br/>[graph_lib.py]"]
  node_stage_models["Proposal and execution<br/>[module_lib.py]"]
  node_prompt_design["Prompt construction<br/>[prompt_lib.py]"]
  node_workflow_state["Workflow state<br/>[states.py]"]
  node_trace["Run tracing<br/>[trace_utils.py]"]
end

subgraph group_integrations["Tool integrations"]
  node_llm["LLM providers<br/>[langchain.py]"]
  node_mcp_tools["MCP tools<br/>[mcp.py]"]
  node_toolbench_adapter["ToolBench adapter"]
  node_toolbench_catalog[("ToolBench catalog")]
end

subgraph group_dataset["Dataset preparation"]
  node_data_generation["Workflow generation"]
  node_json_data["JSON data helpers<br/>[data.py]"]
  node_format_data["Data formatting<br/>[data_format_lib.py]"]
  node_negative_samples["Negative sampling"]
  node_data_splits["Dataset splitting<br/>[split_lib.py]"]
end

subgraph group_modeling["Training and evaluation"]
  node_model["Model support<br/>[model_lib.py]"]
  node_sft["SFT training<br/>[train_sft.py]"]
  node_evaluation["Tool-use evaluation<br/>[eval.py]"]
  node_eval_metrics["Evaluation metrics<br/>[eval_lib.py]"]
end

node_user(("User query"))
node_toolbench_api["ToolBench API service"]
node_mcp_service["MCP service"]

node_user -->|"submits query"| node_prebuilt_mcp
node_prebuilt_mcp -->|"configures stages"| node_graph_stages
node_prebuilt_toolbench -->|"configures stages"| node_graph_stages
node_graph_stages -->|"invokes"| node_stage_models
node_graph_stages -.->|"updates state"| node_workflow_state
node_stage_models -->|"uses prompts"| node_prompt_design
node_stage_models -->|"uses schemas"| node_workflow_state
node_stage_models -->|"uses clients"| node_llm
node_graph_stages -->|"samples MCP APIs"| node_mcp_tools
node_graph_stages -->|"records workflow"| node_trace
node_prebuilt_mcp -->|"configures service"| node_mcp_tools
node_mcp_tools -->|"discovers tools"| node_mcp_service
node_prebuilt_toolbench -.->|"selects integration"| node_toolbench_adapter
node_toolbench_adapter -->|"loads API metadata"| node_toolbench_catalog
node_toolbench_adapter -.->|"wraps API calls"| node_toolbench_api
node_data_generation -->|"uses model clients"| node_llm
node_data_generation -->|"records traces"| node_trace
node_format_data -->|"reads tool names"| node_toolbench_adapter
node_format_data -->|"writes metadata"| node_json_data
node_negative_samples -->|"uses formatted data"| node_format_data
node_sft -.->|"trains model"| node_model
node_evaluation -->|"creates judge"| node_eval_metrics
node_eval_metrics -->|"loads model support"| node_model

click node_prebuilt_mcp "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/prebuilt/toolgrad_on_mcp.py"
click node_prebuilt_toolbench "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/prebuilt/toolgrad_on_toolbench.py"
click node_graph_stages "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/graph_lib.py"
click node_stage_models "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/module_lib.py"
click node_prompt_design "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/prompt_lib.py"
click node_workflow_state "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/states.py"
click node_trace "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/trace_utils.py"
click node_llm "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/langchain.py"
click node_mcp_tools "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/mcp.py"
click node_toolbench_adapter "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/toolbench/toolbench_langchain_utils.py"
click node_toolbench_catalog "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/toolbench/toolbench_data_utils.py"
click node_data_generation "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/generate_toolgrad_data.py"
click node_json_data "https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/data.py"
click node_format_data "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/data/data_format_lib.py"
click node_negative_samples "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/data/negative_sample_lib.py"
click node_data_splits "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/data/split_lib.py"
click node_model "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/models/model_lib.py"
click node_sft "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/train/train_sft.py"
click node_evaluation "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/eval.py"
click node_eval_metrics "https://github.com/zhongyi-zhou/toolgrad/blob/main/src/eval_lib.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_prebuilt_mcp,node_prebuilt_toolbench,node_graph_stages,node_stage_models,node_prompt_design,node_workflow_state,node_trace,node_user toneBlue
class node_llm,node_mcp_tools,node_toolbench_adapter,node_toolbench_catalog toneAmber
class node_data_generation,node_json_data,node_format_data,node_negative_samples,node_data_splits,node_toolbench_api toneMint
class node_model,node_sft,node_evaluation,node_eval_metrics toneRose
class node_mcp_service toneIndigo
```

## Components

### Workflow runtime

- [MCP graph](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/prebuilt/toolgrad_on_mcp.py): `toolgrad/prebuilt/toolgrad_on_mcp.py`
- [ToolBench graph](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/prebuilt/toolgrad_on_toolbench.py): `toolgrad/prebuilt/toolgrad_on_toolbench.py`
- [Workflow stages](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/graph_lib.py): `toolgrad/modules/graph_lib.py`
- [Proposal and execution](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/module_lib.py): `toolgrad/modules/module_lib.py`
- [Prompt construction](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/modules/prompt_lib.py): `toolgrad/modules/prompt_lib.py`
- [Workflow state](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/states.py): `toolgrad/states.py`
- [Run tracing](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/trace_utils.py): `toolgrad/utils/trace_utils.py`

### Tool integrations

- [LLM providers](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/langchain.py): `toolgrad/utils/langchain.py`
- [MCP tools](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/mcp.py): `toolgrad/utils/mcp.py`
- [ToolBench adapter](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/toolbench/toolbench_langchain_utils.py): `toolgrad/utils/toolbench/toolbench_langchain_utils.py`
- [ToolBench catalog](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/toolbench/toolbench_data_utils.py): `toolgrad/utils/toolbench/toolbench_data_utils.py`

### Dataset preparation

- [Workflow generation](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/generate_toolgrad_data.py): `src/generate_toolgrad_data.py`
- [JSON data helpers](https://github.com/zhongyi-zhou/toolgrad/blob/main/toolgrad/utils/data.py): `toolgrad/utils/data.py`
- [Data formatting](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/data/data_format_lib.py): `src/data/data_format_lib.py`
- [Negative sampling](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/data/negative_sample_lib.py): `src/data/negative_sample_lib.py`
- [Dataset splitting](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/data/split_lib.py): `src/data/split_lib.py`

### Training and evaluation

- [Model support](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/models/model_lib.py): `src/models/model_lib.py`
- [SFT training](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/train/train_sft.py): `src/train/train_sft.py`
- [Tool-use evaluation](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/eval.py): `src/eval.py`
- [Evaluation metrics](https://github.com/zhongyi-zhou/toolgrad/blob/main/src/eval_lib.py): `src/eval_lib.py`

### Other components

- **User query**
- **ToolBench API service**
- **MCP service**

## Connections

- User query → MCP graph: submits query (evidence: `README.md`)
- MCP graph → Workflow stages: configures stages (evidence: `toolgrad/prebuilt/toolgrad_on_mcp.py`)
- ToolBench graph → Workflow stages: configures stages (evidence: `toolgrad/prebuilt/toolgrad_on_toolbench.py`)
- Workflow stages → Proposal and execution: invokes (evidence: `toolgrad/modules/graph_lib.py`)
- Workflow stages → Workflow state: updates state (evidence: `toolgrad/modules/graph_lib.py`)
- Proposal and execution → Prompt construction: uses prompts (evidence: `toolgrad/modules/module_lib.py`)
- Proposal and execution → Workflow state: uses schemas (evidence: `toolgrad/modules/module_lib.py`)
- Proposal and execution → LLM providers: uses clients (evidence: `toolgrad/modules/module_lib.py`)
- Workflow stages → MCP tools: samples MCP APIs (evidence: `toolgrad/modules/graph_lib.py`)
- Workflow stages → Run tracing: records workflow (evidence: `toolgrad/modules/graph_lib.py`)
- MCP graph → MCP tools: configures service (evidence: `toolgrad/prebuilt/toolgrad_on_mcp.py`)
- MCP tools → MCP service: discovers tools (evidence: `toolgrad/utils/mcp.py`)
- ToolBench graph → ToolBench adapter: selects integration
- ToolBench adapter → ToolBench catalog: loads API metadata (evidence: `toolgrad/utils/toolbench/toolbench_langchain_utils.py`)
- ToolBench adapter → ToolBench API service: wraps API calls
- Workflow generation → LLM providers: uses model clients (evidence: `src/generate_toolgrad_data.py`)
- Workflow generation → Run tracing: records traces (evidence: `src/generate_toolgrad_data.py`)
- Data formatting → ToolBench adapter: reads tool names (evidence: `src/data/data_format_lib.py`)
- Data formatting → JSON data helpers: writes metadata (evidence: `src/data/data_format_lib.py`)
- Negative sampling → Data formatting: uses formatted data (evidence: `src/data/negative_sample_lib.py`)
- SFT training → Model support: trains model
- Tool-use evaluation → Evaluation metrics: creates judge (evidence: `src/eval.py`)
- Evaluation metrics → Model support: loads model support (evidence: `src/eval_lib.py`)
