shortgraph 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- shortgraph-0.1.0/LICENSE +21 -0
- shortgraph-0.1.0/MANIFEST.in +6 -0
- shortgraph-0.1.0/PKG-INFO +242 -0
- shortgraph-0.1.0/README.md +202 -0
- shortgraph-0.1.0/docs/TUTORIAL.md +153 -0
- shortgraph-0.1.0/examples/quick_start.py +32 -0
- shortgraph-0.1.0/pyproject.toml +32 -0
- shortgraph-0.1.0/requirements.txt +3 -0
- shortgraph-0.1.0/setup.cfg +4 -0
- shortgraph-0.1.0/shortgraph/__init__.py +38 -0
- shortgraph-0.1.0/shortgraph/channels/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/channels/manager.py +92 -0
- shortgraph-0.1.0/shortgraph/checkpoint/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/checkpoint/base.py +115 -0
- shortgraph-0.1.0/shortgraph/graph/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/graph/state.py +75 -0
- shortgraph-0.1.0/shortgraph/memory/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/memory/buffer.py +60 -0
- shortgraph-0.1.0/shortgraph/models/__init__.py +5 -0
- shortgraph-0.1.0/shortgraph/models/base.py +33 -0
- shortgraph-0.1.0/shortgraph/models/factory.py +102 -0
- shortgraph-0.1.0/shortgraph/models/openai.py +49 -0
- shortgraph-0.1.0/shortgraph/paradigms/__init__.py +6 -0
- shortgraph-0.1.0/shortgraph/paradigms/graph_react.py +151 -0
- shortgraph-0.1.0/shortgraph/paradigms/plan_execute.py +146 -0
- shortgraph-0.1.0/shortgraph/paradigms/react.py +90 -0
- shortgraph-0.1.0/shortgraph/paradigms/smart_agent.py +151 -0
- shortgraph-0.1.0/shortgraph/permissions/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/permissions/guard.py +36 -0
- shortgraph-0.1.0/shortgraph/prebuilt/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/prebuilt/tool_node.py +58 -0
- shortgraph-0.1.0/shortgraph/pregel/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/pregel/algo.py +34 -0
- shortgraph-0.1.0/shortgraph/pregel/loop.py +135 -0
- shortgraph-0.1.0/shortgraph/pregel/main.py +53 -0
- shortgraph-0.1.0/shortgraph/tools/__init__.py +3 -0
- shortgraph-0.1.0/shortgraph/tools/base.py +44 -0
- shortgraph-0.1.0/shortgraph/utils/__init__.py +1 -0
- shortgraph-0.1.0/shortgraph.egg-info/PKG-INFO +242 -0
- shortgraph-0.1.0/shortgraph.egg-info/SOURCES.txt +42 -0
- shortgraph-0.1.0/shortgraph.egg-info/dependency_links.txt +1 -0
- shortgraph-0.1.0/shortgraph.egg-info/requires.txt +3 -0
- shortgraph-0.1.0/shortgraph.egg-info/top_level.txt +1 -0
- shortgraph-0.1.0/tests/test_core.py +7 -0
shortgraph-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 ShortGraph Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: shortgraph
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A lightweight, secure, and neutral Python Agent framework.
|
|
5
|
+
Author: ShortGraph Team
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2024 ShortGraph Team
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://github.com/your-repo/shortgraph
|
|
29
|
+
Project-URL: Bug Tracker, https://github.com/your-repo/shortgraph/issues
|
|
30
|
+
Classifier: Programming Language :: Python :: 3
|
|
31
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
32
|
+
Classifier: Operating System :: OS Independent
|
|
33
|
+
Requires-Python: >=3.8
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
License-File: LICENSE
|
|
36
|
+
Requires-Dist: pydantic>=2.0.0
|
|
37
|
+
Requires-Dist: tenacity>=8.0.0
|
|
38
|
+
Requires-Dist: openai>=1.0.0
|
|
39
|
+
Dynamic: license-file
|
|
40
|
+
|
|
41
|
+
# ShortGraph
|
|
42
|
+
|
|
43
|
+
**ShortGraph** 是一个轻量级的、受 LangGraph 启发的 Python 图编排框架,专为构建复杂的 Agent 工作流而设计。
|
|
44
|
+
|
|
45
|
+
它摒弃了传统链式(Chain)调用的局限性,采用**图(Graph)**作为核心抽象,赋予开发者对 Agent 控制流的极致掌控力。无论是循环、条件分支、并行执行,还是人工介入(HITL),ShortGraph 都能以简洁的代码实现。
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 核心架构 (Core Architecture)
|
|
50
|
+
|
|
51
|
+
ShortGraph 的设计严格遵循**图执行引擎**的四大维度:
|
|
52
|
+
|
|
53
|
+
1. **图执行引擎 (Pregel Engine)**:
|
|
54
|
+
* 核心运行时,负责调度节点执行、传递状态。
|
|
55
|
+
* 采用 BSP (Bulk Synchronous Parallel) 模型,支持多节点并行与同步。
|
|
56
|
+
* 位于 `shortgraph/pregel/` 目录。
|
|
57
|
+
2. **状态管理 (State Management)**:
|
|
58
|
+
* `AgentState`:在节点间流转的共享状态对象。
|
|
59
|
+
* 支持类似 Redux 的状态更新机制,确保数据流向清晰。
|
|
60
|
+
* 位于 `shortgraph/channels/` 目录。
|
|
61
|
+
3. **图定义 (Graph Definition)**:
|
|
62
|
+
* `StateGraph`:用于定义图的拓扑结构。
|
|
63
|
+
* **Node (节点)**:执行具体逻辑的函数(或子图)。
|
|
64
|
+
* **Edge (边)**:定义节点间的流转方向。
|
|
65
|
+
* **Conditional Edge (条件边)**:基于运行时状态动态决定下一跳。
|
|
66
|
+
* 位于 `shortgraph/graph/` 目录。
|
|
67
|
+
4. **运行时协议 (Runtime Protocol)**:
|
|
68
|
+
* 支持同步 `invoke` 和流式 `stream` 执行。
|
|
69
|
+
* 支持 **Checkpointer** 持久化机制,实现“断点续传”和“时光倒流”。
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 🛠️ 安装 (Installation)
|
|
74
|
+
|
|
75
|
+
目前推荐源码安装:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
git clone https://github.com/your-repo/shortgraph.git
|
|
79
|
+
cd shortgraph
|
|
80
|
+
pip install -r requirements.txt
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 🚀 快速开始 (Quick Start)
|
|
86
|
+
|
|
87
|
+
### 1. 定义一个最简单的图
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from shortgraph.graph.state import StateGraph
|
|
91
|
+
from shortgraph.channels.manager import AgentState
|
|
92
|
+
|
|
93
|
+
# 1. 定义节点函数
|
|
94
|
+
def step_1(state: AgentState):
|
|
95
|
+
print("执行步骤 1")
|
|
96
|
+
state.set_variable("count", 1)
|
|
97
|
+
return state
|
|
98
|
+
|
|
99
|
+
def step_2(state: AgentState):
|
|
100
|
+
val = state.get_variable("count")
|
|
101
|
+
print(f"执行步骤 2, 当前计数: {val}")
|
|
102
|
+
state.set_variable("count", val + 1)
|
|
103
|
+
return state
|
|
104
|
+
|
|
105
|
+
# 2. 构建图
|
|
106
|
+
workflow = StateGraph()
|
|
107
|
+
workflow.add_node("node_1", step_1)
|
|
108
|
+
workflow.add_node("node_2", step_2)
|
|
109
|
+
|
|
110
|
+
# 3. 定义流向
|
|
111
|
+
workflow.set_entry_point("node_1")
|
|
112
|
+
workflow.add_edge("node_1", "node_2")
|
|
113
|
+
workflow.add_edge("node_2", "__end__")
|
|
114
|
+
|
|
115
|
+
# 4. 编译
|
|
116
|
+
app = workflow.compile()
|
|
117
|
+
|
|
118
|
+
# 5. 运行
|
|
119
|
+
state = AgentState()
|
|
120
|
+
app.invoke(state)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 📚 详细教程与 API (Detailed Documentation)
|
|
126
|
+
|
|
127
|
+
### 1. 图构建 (`StateGraph`)
|
|
128
|
+
|
|
129
|
+
`StateGraph` 是你的工作流蓝图。
|
|
130
|
+
|
|
131
|
+
* **`add_node(name, func, retry=0)`**:
|
|
132
|
+
* `name`: 节点唯一标识符。
|
|
133
|
+
* `func`: 接收 `AgentState` 并返回 `AgentState` 的函数。
|
|
134
|
+
* `retry`: (可选) 失败自动重试次数。
|
|
135
|
+
* **`add_edge(start_key, end_key)`**:
|
|
136
|
+
* 定义从 `start_key` 到 `end_key` 的确定性流转。
|
|
137
|
+
* **`add_conditional_edges(source_key, condition_func, path_map)`**:
|
|
138
|
+
* 实现逻辑分支。
|
|
139
|
+
* `condition_func`: 接收 state,返回字符串(意图)。
|
|
140
|
+
* `path_map`: 字典,将 `condition_func` 的返回值映射到下一个节点名称。
|
|
141
|
+
* **`set_entry_point(key)`**: 指定图的起始节点。
|
|
142
|
+
* **`compile(checkpointer=..., interrupt_before=...)`**:
|
|
143
|
+
* 将图编译为可执行的 `Pregel` 应用。
|
|
144
|
+
|
|
145
|
+
### 2. 状态管理 (`AgentState`)
|
|
146
|
+
|
|
147
|
+
在所有节点间共享的数据容器。
|
|
148
|
+
|
|
149
|
+
* **`state.get_variable(key)`**: 获取变量值。
|
|
150
|
+
* **`state.set_variable(key, value)`**: 更新变量值。
|
|
151
|
+
|
|
152
|
+
### 3. 模型集成 (`LLMFactory`)
|
|
153
|
+
|
|
154
|
+
ShortGraph 内置了对主流大模型的支持,统一封装为 `BaseLLM` 接口。
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
from shortgraph.models.factory import LLMFactory
|
|
158
|
+
|
|
159
|
+
# OpenAI
|
|
160
|
+
llm = LLMFactory.create_openai(api_key="sk-...")
|
|
161
|
+
|
|
162
|
+
# DeepSeek
|
|
163
|
+
llm = LLMFactory.create_deepseek(api_key="sk-...")
|
|
164
|
+
|
|
165
|
+
# Zhipu AI (智谱清言)
|
|
166
|
+
llm = LLMFactory.create_zhipu(api_key="...")
|
|
167
|
+
|
|
168
|
+
# Ollama (本地模型)
|
|
169
|
+
llm = LLMFactory.create_ollama(model="llama3")
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### 4. 进阶功能 (Advanced Features)
|
|
173
|
+
|
|
174
|
+
#### A. 人工介入 (Human-in-the-loop)
|
|
175
|
+
在关键节点前暂停,等待人工审批或修改状态。
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
from shortgraph.checkpoint.memory import MemoryCheckpoint
|
|
179
|
+
|
|
180
|
+
# 启用检查点记录
|
|
181
|
+
checkpointer = MemoryCheckpoint()
|
|
182
|
+
|
|
183
|
+
# 编译时指定中断点
|
|
184
|
+
app = workflow.compile(
|
|
185
|
+
checkpointer=checkpointer,
|
|
186
|
+
interrupt_before=["approval_node"] # 在进入 approval_node 前暂停
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
# 运行(会暂停)
|
|
190
|
+
app.invoke(state, thread_id="thread_1")
|
|
191
|
+
|
|
192
|
+
# ... 人工检查,更新 state ...
|
|
193
|
+
|
|
194
|
+
# 恢复运行(传入相同的 thread_id)
|
|
195
|
+
app.invoke(state, thread_id="thread_1")
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
#### B. 自动重试 (Auto-Retry)
|
|
199
|
+
对于不稳定的节点(如网络请求),可以设置自动重试。
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
# 如果失败,自动重试 3 次
|
|
203
|
+
workflow.add_node("api_call", call_api_func, retry=3)
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
#### C. 子图嵌套 (Subgraphs)
|
|
207
|
+
图可以作为节点嵌入到另一个图中,实现模块化复用。
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
child_app = child_workflow.compile()
|
|
211
|
+
parent_workflow.add_node("research_department", child_app)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
216
|
+
## 📂 目录结构 (Directory Structure)
|
|
217
|
+
|
|
218
|
+
```text
|
|
219
|
+
shortgraph/
|
|
220
|
+
├── pregel/ # [核心] 图执行引擎 (main, loop, algo)
|
|
221
|
+
├── graph/ # [定义] 图结构定义 (StateGraph, Node)
|
|
222
|
+
├── channels/ # [状态] 状态管理 (AgentState)
|
|
223
|
+
├── checkpoint/ # [记忆] 持久化与历史记录
|
|
224
|
+
├── models/ # [模型] LLM 工厂 (OpenAI, DeepSeek, Zhipu...)
|
|
225
|
+
├── paradigms/ # [范式] 预置 Agent 模式 (SmartAgent, GraphReAct...)
|
|
226
|
+
├── tools/ # [工具] 工具定义基类
|
|
227
|
+
└── examples/ # [示例] 丰富的实战代码
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
## 🧩 示例代码 (Examples)
|
|
231
|
+
|
|
232
|
+
请查看 `examples/` 目录获取更多实战代码:
|
|
233
|
+
|
|
234
|
+
* `examples/showcase.py`: **SmartAgent** 完整演示(天气查询)。
|
|
235
|
+
* `examples/hitl_agent.py`: **人工介入 (HITL)** 流程演示。
|
|
236
|
+
* `examples/retry_agent.py`: **自动重试** 机制演示。
|
|
237
|
+
* `examples/subgraph_agent.py`: **多 Agent 协作**(子图嵌套)演示。
|
|
238
|
+
* `examples/graph_agent.py`: 手动构建 ReAct 图的演示。
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
> **ShortGraph** - Make Agents Simple & Powerful.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# ShortGraph
|
|
2
|
+
|
|
3
|
+
**ShortGraph** 是一个轻量级的、受 LangGraph 启发的 Python 图编排框架,专为构建复杂的 Agent 工作流而设计。
|
|
4
|
+
|
|
5
|
+
它摒弃了传统链式(Chain)调用的局限性,采用**图(Graph)**作为核心抽象,赋予开发者对 Agent 控制流的极致掌控力。无论是循环、条件分支、并行执行,还是人工介入(HITL),ShortGraph 都能以简洁的代码实现。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 核心架构 (Core Architecture)
|
|
10
|
+
|
|
11
|
+
ShortGraph 的设计严格遵循**图执行引擎**的四大维度:
|
|
12
|
+
|
|
13
|
+
1. **图执行引擎 (Pregel Engine)**:
|
|
14
|
+
* 核心运行时,负责调度节点执行、传递状态。
|
|
15
|
+
* 采用 BSP (Bulk Synchronous Parallel) 模型,支持多节点并行与同步。
|
|
16
|
+
* 位于 `shortgraph/pregel/` 目录。
|
|
17
|
+
2. **状态管理 (State Management)**:
|
|
18
|
+
* `AgentState`:在节点间流转的共享状态对象。
|
|
19
|
+
* 支持类似 Redux 的状态更新机制,确保数据流向清晰。
|
|
20
|
+
* 位于 `shortgraph/channels/` 目录。
|
|
21
|
+
3. **图定义 (Graph Definition)**:
|
|
22
|
+
* `StateGraph`:用于定义图的拓扑结构。
|
|
23
|
+
* **Node (节点)**:执行具体逻辑的函数(或子图)。
|
|
24
|
+
* **Edge (边)**:定义节点间的流转方向。
|
|
25
|
+
* **Conditional Edge (条件边)**:基于运行时状态动态决定下一跳。
|
|
26
|
+
* 位于 `shortgraph/graph/` 目录。
|
|
27
|
+
4. **运行时协议 (Runtime Protocol)**:
|
|
28
|
+
* 支持同步 `invoke` 和流式 `stream` 执行。
|
|
29
|
+
* 支持 **Checkpointer** 持久化机制,实现“断点续传”和“时光倒流”。
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 🛠️ 安装 (Installation)
|
|
34
|
+
|
|
35
|
+
目前推荐源码安装:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
git clone https://github.com/your-repo/shortgraph.git
|
|
39
|
+
cd shortgraph
|
|
40
|
+
pip install -r requirements.txt
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 🚀 快速开始 (Quick Start)
|
|
46
|
+
|
|
47
|
+
### 1. 定义一个最简单的图
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
from shortgraph.graph.state import StateGraph
|
|
51
|
+
from shortgraph.channels.manager import AgentState
|
|
52
|
+
|
|
53
|
+
# 1. 定义节点函数
|
|
54
|
+
def step_1(state: AgentState):
|
|
55
|
+
print("执行步骤 1")
|
|
56
|
+
state.set_variable("count", 1)
|
|
57
|
+
return state
|
|
58
|
+
|
|
59
|
+
def step_2(state: AgentState):
|
|
60
|
+
val = state.get_variable("count")
|
|
61
|
+
print(f"执行步骤 2, 当前计数: {val}")
|
|
62
|
+
state.set_variable("count", val + 1)
|
|
63
|
+
return state
|
|
64
|
+
|
|
65
|
+
# 2. 构建图
|
|
66
|
+
workflow = StateGraph()
|
|
67
|
+
workflow.add_node("node_1", step_1)
|
|
68
|
+
workflow.add_node("node_2", step_2)
|
|
69
|
+
|
|
70
|
+
# 3. 定义流向
|
|
71
|
+
workflow.set_entry_point("node_1")
|
|
72
|
+
workflow.add_edge("node_1", "node_2")
|
|
73
|
+
workflow.add_edge("node_2", "__end__")
|
|
74
|
+
|
|
75
|
+
# 4. 编译
|
|
76
|
+
app = workflow.compile()
|
|
77
|
+
|
|
78
|
+
# 5. 运行
|
|
79
|
+
state = AgentState()
|
|
80
|
+
app.invoke(state)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 📚 详细教程与 API (Detailed Documentation)
|
|
86
|
+
|
|
87
|
+
### 1. 图构建 (`StateGraph`)
|
|
88
|
+
|
|
89
|
+
`StateGraph` 是你的工作流蓝图。
|
|
90
|
+
|
|
91
|
+
* **`add_node(name, func, retry=0)`**:
|
|
92
|
+
* `name`: 节点唯一标识符。
|
|
93
|
+
* `func`: 接收 `AgentState` 并返回 `AgentState` 的函数。
|
|
94
|
+
* `retry`: (可选) 失败自动重试次数。
|
|
95
|
+
* **`add_edge(start_key, end_key)`**:
|
|
96
|
+
* 定义从 `start_key` 到 `end_key` 的确定性流转。
|
|
97
|
+
* **`add_conditional_edges(source_key, condition_func, path_map)`**:
|
|
98
|
+
* 实现逻辑分支。
|
|
99
|
+
* `condition_func`: 接收 state,返回字符串(意图)。
|
|
100
|
+
* `path_map`: 字典,将 `condition_func` 的返回值映射到下一个节点名称。
|
|
101
|
+
* **`set_entry_point(key)`**: 指定图的起始节点。
|
|
102
|
+
* **`compile(checkpointer=..., interrupt_before=...)`**:
|
|
103
|
+
* 将图编译为可执行的 `Pregel` 应用。
|
|
104
|
+
|
|
105
|
+
### 2. 状态管理 (`AgentState`)
|
|
106
|
+
|
|
107
|
+
在所有节点间共享的数据容器。
|
|
108
|
+
|
|
109
|
+
* **`state.get_variable(key)`**: 获取变量值。
|
|
110
|
+
* **`state.set_variable(key, value)`**: 更新变量值。
|
|
111
|
+
|
|
112
|
+
### 3. 模型集成 (`LLMFactory`)
|
|
113
|
+
|
|
114
|
+
ShortGraph 内置了对主流大模型的支持,统一封装为 `BaseLLM` 接口。
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
from shortgraph.models.factory import LLMFactory
|
|
118
|
+
|
|
119
|
+
# OpenAI
|
|
120
|
+
llm = LLMFactory.create_openai(api_key="sk-...")
|
|
121
|
+
|
|
122
|
+
# DeepSeek
|
|
123
|
+
llm = LLMFactory.create_deepseek(api_key="sk-...")
|
|
124
|
+
|
|
125
|
+
# Zhipu AI (智谱清言)
|
|
126
|
+
llm = LLMFactory.create_zhipu(api_key="...")
|
|
127
|
+
|
|
128
|
+
# Ollama (本地模型)
|
|
129
|
+
llm = LLMFactory.create_ollama(model="llama3")
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### 4. 进阶功能 (Advanced Features)
|
|
133
|
+
|
|
134
|
+
#### A. 人工介入 (Human-in-the-loop)
|
|
135
|
+
在关键节点前暂停,等待人工审批或修改状态。
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
from shortgraph.checkpoint.memory import MemoryCheckpoint
|
|
139
|
+
|
|
140
|
+
# 启用检查点记录
|
|
141
|
+
checkpointer = MemoryCheckpoint()
|
|
142
|
+
|
|
143
|
+
# 编译时指定中断点
|
|
144
|
+
app = workflow.compile(
|
|
145
|
+
checkpointer=checkpointer,
|
|
146
|
+
interrupt_before=["approval_node"] # 在进入 approval_node 前暂停
|
|
147
|
+
)
|
|
148
|
+
|
|
149
|
+
# 运行(会暂停)
|
|
150
|
+
app.invoke(state, thread_id="thread_1")
|
|
151
|
+
|
|
152
|
+
# ... 人工检查,更新 state ...
|
|
153
|
+
|
|
154
|
+
# 恢复运行(传入相同的 thread_id)
|
|
155
|
+
app.invoke(state, thread_id="thread_1")
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
#### B. 自动重试 (Auto-Retry)
|
|
159
|
+
对于不稳定的节点(如网络请求),可以设置自动重试。
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
# 如果失败,自动重试 3 次
|
|
163
|
+
workflow.add_node("api_call", call_api_func, retry=3)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
#### C. 子图嵌套 (Subgraphs)
|
|
167
|
+
图可以作为节点嵌入到另一个图中,实现模块化复用。
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
child_app = child_workflow.compile()
|
|
171
|
+
parent_workflow.add_node("research_department", child_app)
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## 📂 目录结构 (Directory Structure)
|
|
177
|
+
|
|
178
|
+
```text
|
|
179
|
+
shortgraph/
|
|
180
|
+
├── pregel/ # [核心] 图执行引擎 (main, loop, algo)
|
|
181
|
+
├── graph/ # [定义] 图结构定义 (StateGraph, Node)
|
|
182
|
+
├── channels/ # [状态] 状态管理 (AgentState)
|
|
183
|
+
├── checkpoint/ # [记忆] 持久化与历史记录
|
|
184
|
+
├── models/ # [模型] LLM 工厂 (OpenAI, DeepSeek, Zhipu...)
|
|
185
|
+
├── paradigms/ # [范式] 预置 Agent 模式 (SmartAgent, GraphReAct...)
|
|
186
|
+
├── tools/ # [工具] 工具定义基类
|
|
187
|
+
└── examples/ # [示例] 丰富的实战代码
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
## 🧩 示例代码 (Examples)
|
|
191
|
+
|
|
192
|
+
请查看 `examples/` 目录获取更多实战代码:
|
|
193
|
+
|
|
194
|
+
* `examples/showcase.py`: **SmartAgent** 完整演示(天气查询)。
|
|
195
|
+
* `examples/hitl_agent.py`: **人工介入 (HITL)** 流程演示。
|
|
196
|
+
* `examples/retry_agent.py`: **自动重试** 机制演示。
|
|
197
|
+
* `examples/subgraph_agent.py`: **多 Agent 协作**(子图嵌套)演示。
|
|
198
|
+
* `examples/graph_agent.py`: 手动构建 ReAct 图的演示。
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
> **ShortGraph** - Make Agents Simple & Powerful.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# ShortGraph 极简教程:从零构建智能 Agent
|
|
2
|
+
|
|
3
|
+
> **目标用户**:Python 新手、希望快速落地 Agent 的开发者。
|
|
4
|
+
> **核心优势**:比 LangGraph 少写 70% 代码,内置可视化与记忆管理。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 📚 目录
|
|
9
|
+
1. [为什么选择 ShortGraph?](#1-为什么选择-shortgraph)
|
|
10
|
+
2. [一分钟上手](#2-一分钟上手)
|
|
11
|
+
3. [核心概念详解](#3-核心概念详解)
|
|
12
|
+
4. [实战:构建一个天气助手](#4-实战构建一个天气助手)
|
|
13
|
+
5. [进阶功能](#5-进阶功能)
|
|
14
|
+
6. [ShortGraph vs LangGraph 对比](#6-shortgraph-vs-langgraph-对比)
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. 为什么选择 ShortGraph?
|
|
19
|
+
|
|
20
|
+
构建 Agent(智能体)通常很难。你需要管理:
|
|
21
|
+
- **Prompt**(提示词)
|
|
22
|
+
- **Memory**(上下文记忆)
|
|
23
|
+
- **Tools**(工具调用)
|
|
24
|
+
- **State**(状态流转)
|
|
25
|
+
|
|
26
|
+
主流框架(如 LangGraph)虽然强大,但需要定义复杂的图结构、状态类和条件边。
|
|
27
|
+
**ShortGraph** 的设计哲学是:**把复杂留给框架,把简单留给用户。**
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 2. 一分钟上手
|
|
32
|
+
|
|
33
|
+
### 安装
|
|
34
|
+
```bash
|
|
35
|
+
pip install -r requirements.txt
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Hello World (极简代码)
|
|
39
|
+
```python
|
|
40
|
+
from shortgraph.paradigms.smart_agent import SmartAgent
|
|
41
|
+
from shortgraph.core.llm_factory import LLMFactory
|
|
42
|
+
|
|
43
|
+
# 1. 创建模型 (支持 OpenAI, DeepSeek, Ollama 等)
|
|
44
|
+
llm = LLMFactory.create_openai(api_key="your-key")
|
|
45
|
+
|
|
46
|
+
# 2. 创建 Agent (自动可视化)
|
|
47
|
+
agent = SmartAgent(llm=llm, auto_visualize=True)
|
|
48
|
+
|
|
49
|
+
# 3. 对话
|
|
50
|
+
print(agent.run("你好,你是谁?"))
|
|
51
|
+
```
|
|
52
|
+
运行这段代码,你的浏览器会自动弹出一张 Agent 的架构图!
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 3. 核心概念详解
|
|
57
|
+
|
|
58
|
+
在使用 ShortGraph 时,你只需要关注两个概念:
|
|
59
|
+
|
|
60
|
+
### 🛠️ 工具 (Tools)
|
|
61
|
+
工具是 Agent 的“手”。在 ShortGraph 中,**任何 Python 函数都可以直接变成工具**。
|
|
62
|
+
只需加上 `@tool` 装饰器:
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from shortgraph.tools.base import tool
|
|
66
|
+
|
|
67
|
+
@tool
|
|
68
|
+
def calculate(expression: str) -> str:
|
|
69
|
+
"""计算数学表达式。输入示例: '1 + 1'"""
|
|
70
|
+
return str(eval(expression))
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 🧠 智能体 (SmartAgent)
|
|
74
|
+
SmartAgent 是 Agent 的“大脑”。它内置了:
|
|
75
|
+
- **思考回路** (ReAct 范式)
|
|
76
|
+
- **记忆系统** (自动管理对话历史)
|
|
77
|
+
- **可视化引擎** (自动生成流程图)
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 4. 实战:构建一个天气助手
|
|
82
|
+
|
|
83
|
+
让我们把所有知识点串起来,做一个能查询天气的助手。
|
|
84
|
+
|
|
85
|
+
### 第一步:定义工具
|
|
86
|
+
```python
|
|
87
|
+
from shortgraph.tools.base import tool
|
|
88
|
+
|
|
89
|
+
@tool
|
|
90
|
+
def get_weather(city: str) -> str:
|
|
91
|
+
"""查询指定城市的天气"""
|
|
92
|
+
# 这里模拟返回数据,实际可以调用 API
|
|
93
|
+
return f"{city} 今日晴朗,气温 25℃"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### 第二步:组装 Agent
|
|
97
|
+
```python
|
|
98
|
+
import os
|
|
99
|
+
from shortgraph.core.llm_factory import LLMFactory
|
|
100
|
+
from shortgraph.paradigms.smart_agent import SmartAgent
|
|
101
|
+
|
|
102
|
+
# 自动处理 API Key,如果没有则使用模拟模式 (Mock)
|
|
103
|
+
api_key = os.getenv("OPENAI_API_KEY")
|
|
104
|
+
llm = LLMFactory.create_openai(api_key=api_key) if api_key else LLMFactory.create_mock()
|
|
105
|
+
|
|
106
|
+
agent = SmartAgent(
|
|
107
|
+
llm=llm,
|
|
108
|
+
tools=[get_weather], # 注册工具
|
|
109
|
+
system_prompt="你是一个专业的气象员,回答要简洁。",
|
|
110
|
+
auto_visualize=True # 开启自动可视化
|
|
111
|
+
)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### 第三步:运行
|
|
115
|
+
```python
|
|
116
|
+
response = agent.run("帮我查一下北京的天气")
|
|
117
|
+
print(response)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 5. 进阶功能
|
|
123
|
+
|
|
124
|
+
### 📊 自动可视化 (Auto-Visualize)
|
|
125
|
+
不需要写一行绘图代码。只要设置 `auto_visualize=True`,框架会自动生成 Mermaid 流程图并在浏览器中展示。
|
|
126
|
+
|
|
127
|
+
### 🏭 多模型支持 (LLMFactory)
|
|
128
|
+
一键切换不同的大模型,无需修改业务代码。
|
|
129
|
+
```python
|
|
130
|
+
# OpenAI
|
|
131
|
+
llm = LLMFactory.create_openai()
|
|
132
|
+
|
|
133
|
+
# DeepSeek
|
|
134
|
+
llm = LLMFactory.create_deepseek(api_key="sk-...")
|
|
135
|
+
|
|
136
|
+
# Ollama (本地)
|
|
137
|
+
llm = LLMFactory.create_ollama(model="llama3")
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## 6. ShortGraph vs LangGraph 对比
|
|
143
|
+
|
|
144
|
+
| 特性 | LangGraph | ShortGraph |
|
|
145
|
+
| :--- | :--- | :--- |
|
|
146
|
+
| **代码量** | 高 (需定义 State, Node, Edge) | **极低** (仅需定义工具) |
|
|
147
|
+
| **工具定义** | 手动解析 JSON | **@tool 装饰器自动处理** |
|
|
148
|
+
| **可视化** | 需额外配置 | **开箱即用 (自动弹窗)** |
|
|
149
|
+
| **上手难度** | 专家级 | **入门级** |
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
> **总结**:如果你需要极致的控制力,选择 LangGraph;如果你需要**快速落地、代码简洁、自带可视化**,ShortGraph 是你的最佳选择。
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
from shortgraph.graph.state import StateGraph
|
|
2
|
+
from shortgraph.channels.manager import AgentState
|
|
3
|
+
|
|
4
|
+
# 1. 定义节点函数
|
|
5
|
+
def step_1(state: AgentState):
|
|
6
|
+
print("执行步骤 1")
|
|
7
|
+
state.set_variable("count", 1)
|
|
8
|
+
return state
|
|
9
|
+
|
|
10
|
+
def step_2(state: AgentState):
|
|
11
|
+
val = state.get_variable("count")
|
|
12
|
+
print(f"执行步骤 2, 当前计数: {val}")
|
|
13
|
+
state.set_variable("count", val + 1)
|
|
14
|
+
return state
|
|
15
|
+
|
|
16
|
+
# 2. 构建图
|
|
17
|
+
workflow = StateGraph()
|
|
18
|
+
workflow.add_node("node_1", step_1)
|
|
19
|
+
workflow.add_node("node_2", step_2)
|
|
20
|
+
|
|
21
|
+
# 3. 定义流向
|
|
22
|
+
workflow.set_entry_point("node_1")
|
|
23
|
+
workflow.add_edge("node_1", "node_2")
|
|
24
|
+
workflow.add_edge("node_2", "__end__")
|
|
25
|
+
|
|
26
|
+
# 4. 编译
|
|
27
|
+
app = workflow.compile()
|
|
28
|
+
|
|
29
|
+
# 5. 运行
|
|
30
|
+
if __name__ == "__main__":
|
|
31
|
+
state = AgentState()
|
|
32
|
+
app.invoke(state)
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "shortgraph"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "A lightweight, secure, and neutral Python Agent framework."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
authors = [
|
|
11
|
+
{ name = "ShortGraph Team" },
|
|
12
|
+
]
|
|
13
|
+
license = { file = "LICENSE" }
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"License :: OSI Approved :: MIT License",
|
|
17
|
+
"Operating System :: OS Independent",
|
|
18
|
+
]
|
|
19
|
+
requires-python = ">=3.8"
|
|
20
|
+
dependencies = [
|
|
21
|
+
"pydantic>=2.0.0",
|
|
22
|
+
"tenacity>=8.0.0",
|
|
23
|
+
"openai>=1.0.0",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
"Homepage" = "https://github.com/your-repo/shortgraph"
|
|
28
|
+
"Bug Tracker" = "https://github.com/your-repo/shortgraph/issues"
|
|
29
|
+
|
|
30
|
+
[tool.setuptools.packages.find]
|
|
31
|
+
where = ["."]
|
|
32
|
+
include = ["shortgraph*"]
|