lingxigraph 2.0.1__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.
- lingxigraph-2.0.1/LICENSE +21 -0
- lingxigraph-2.0.1/PKG-INFO +256 -0
- lingxigraph-2.0.1/README.md +194 -0
- lingxigraph-2.0.1/pyproject.toml +110 -0
- lingxigraph-2.0.1/setup.cfg +4 -0
- lingxigraph-2.0.1/src/lingxigraph/__init__.py +187 -0
- lingxigraph-2.0.1/src/lingxigraph/__main__.py +6 -0
- lingxigraph-2.0.1/src/lingxigraph/cache.py +84 -0
- lingxigraph-2.0.1/src/lingxigraph/cache_redis.py +66 -0
- lingxigraph-2.0.1/src/lingxigraph/channels.py +190 -0
- lingxigraph-2.0.1/src/lingxigraph/checkpoint/__init__.py +115 -0
- lingxigraph-2.0.1/src/lingxigraph/checkpoint/memory.py +130 -0
- lingxigraph-2.0.1/src/lingxigraph/checkpoint/postgres.py +283 -0
- lingxigraph-2.0.1/src/lingxigraph/checkpoint/sqlite.py +329 -0
- lingxigraph-2.0.1/src/lingxigraph/cli.py +390 -0
- lingxigraph-2.0.1/src/lingxigraph/constants.py +6 -0
- lingxigraph-2.0.1/src/lingxigraph/errors.py +69 -0
- lingxigraph-2.0.1/src/lingxigraph/events.py +57 -0
- lingxigraph-2.0.1/src/lingxigraph/examples/__init__.py +1 -0
- lingxigraph-2.0.1/src/lingxigraph/examples/multi_agent_graph.py +118 -0
- lingxigraph-2.0.1/src/lingxigraph/examples/production_graph.py +36 -0
- lingxigraph-2.0.1/src/lingxigraph/func.py +122 -0
- lingxigraph-2.0.1/src/lingxigraph/graph/__init__.py +7 -0
- lingxigraph-2.0.1/src/lingxigraph/graph/builder.py +317 -0
- lingxigraph-2.0.1/src/lingxigraph/graph/executor.py +2403 -0
- lingxigraph-2.0.1/src/lingxigraph/graph/structure.py +67 -0
- lingxigraph-2.0.1/src/lingxigraph/integrations/__init__.py +37 -0
- lingxigraph-2.0.1/src/lingxigraph/integrations/_http.py +52 -0
- lingxigraph-2.0.1/src/lingxigraph/integrations/coze.py +850 -0
- lingxigraph-2.0.1/src/lingxigraph/integrations/openai_compat.py +225 -0
- lingxigraph-2.0.1/src/lingxigraph/messages.py +227 -0
- lingxigraph-2.0.1/src/lingxigraph/models.py +33 -0
- lingxigraph-2.0.1/src/lingxigraph/observability.py +127 -0
- lingxigraph-2.0.1/src/lingxigraph/patterns/__init__.py +25 -0
- lingxigraph-2.0.1/src/lingxigraph/patterns/multi_agent.py +410 -0
- lingxigraph-2.0.1/src/lingxigraph/prebuilt.py +214 -0
- lingxigraph-2.0.1/src/lingxigraph/protocols/__init__.py +12 -0
- lingxigraph-2.0.1/src/lingxigraph/protocols/a2a.py +165 -0
- lingxigraph-2.0.1/src/lingxigraph/protocols/mcp.py +169 -0
- lingxigraph-2.0.1/src/lingxigraph/py.typed +1 -0
- lingxigraph-2.0.1/src/lingxigraph/runtime.py +275 -0
- lingxigraph-2.0.1/src/lingxigraph/scaffold.py +264 -0
- lingxigraph-2.0.1/src/lingxigraph/schema.py +230 -0
- lingxigraph-2.0.1/src/lingxigraph/sdk.py +522 -0
- lingxigraph-2.0.1/src/lingxigraph/serialization.py +164 -0
- lingxigraph-2.0.1/src/lingxigraph/server/__init__.py +14 -0
- lingxigraph-2.0.1/src/lingxigraph/server/app.py +912 -0
- lingxigraph-2.0.1/src/lingxigraph/server/eventbus.py +80 -0
- lingxigraph-2.0.1/src/lingxigraph/server/migrations/0001_v1.sql +193 -0
- lingxigraph-2.0.1/src/lingxigraph/server/models.py +209 -0
- lingxigraph-2.0.1/src/lingxigraph/server/registry.py +110 -0
- lingxigraph-2.0.1/src/lingxigraph/server/repository.py +1219 -0
- lingxigraph-2.0.1/src/lingxigraph/server/security.py +125 -0
- lingxigraph-2.0.1/src/lingxigraph/server/worker.py +303 -0
- lingxigraph-2.0.1/src/lingxigraph/store/__init__.py +124 -0
- lingxigraph-2.0.1/src/lingxigraph/store/memory.py +196 -0
- lingxigraph-2.0.1/src/lingxigraph/store/postgres.py +242 -0
- lingxigraph-2.0.1/src/lingxigraph/studio/index.html +113 -0
- lingxigraph-2.0.1/src/lingxigraph/studio/studio.css +234 -0
- lingxigraph-2.0.1/src/lingxigraph/studio/studio.js +821 -0
- lingxigraph-2.0.1/src/lingxigraph/tools.py +331 -0
- lingxigraph-2.0.1/src/lingxigraph/types.py +243 -0
- lingxigraph-2.0.1/src/lingxigraph/version.py +5 -0
- lingxigraph-2.0.1/src/lingxigraph.egg-info/PKG-INFO +256 -0
- lingxigraph-2.0.1/src/lingxigraph.egg-info/SOURCES.txt +91 -0
- lingxigraph-2.0.1/src/lingxigraph.egg-info/dependency_links.txt +1 -0
- lingxigraph-2.0.1/src/lingxigraph.egg-info/entry_points.txt +2 -0
- lingxigraph-2.0.1/src/lingxigraph.egg-info/requires.txt +53 -0
- lingxigraph-2.0.1/src/lingxigraph.egg-info/top_level.txt +1 -0
- lingxigraph-2.0.1/tests/test_agent_server.py +409 -0
- lingxigraph-2.0.1/tests/test_architecture.py +52 -0
- lingxigraph-2.0.1/tests/test_builder.py +58 -0
- lingxigraph-2.0.1/tests/test_channels.py +90 -0
- lingxigraph-2.0.1/tests/test_checkpoint.py +53 -0
- lingxigraph-2.0.1/tests/test_execution.py +93 -0
- lingxigraph-2.0.1/tests/test_integrations_v2.py +641 -0
- lingxigraph-2.0.1/tests/test_interrupt.py +88 -0
- lingxigraph-2.0.1/tests/test_messages_tools_v2.py +128 -0
- lingxigraph-2.0.1/tests/test_mvp_hardening.py +745 -0
- lingxigraph-2.0.1/tests/test_patterns_protocols.py +214 -0
- lingxigraph-2.0.1/tests/test_platform_units.py +414 -0
- lingxigraph-2.0.1/tests/test_postgres_integration.py +161 -0
- lingxigraph-2.0.1/tests/test_retry.py +76 -0
- lingxigraph-2.0.1/tests/test_runtime_features.py +134 -0
- lingxigraph-2.0.1/tests/test_sdk.py +157 -0
- lingxigraph-2.0.1/tests/test_send.py +139 -0
- lingxigraph-2.0.1/tests/test_sqlite_saver.py +87 -0
- lingxigraph-2.0.1/tests/test_store.py +125 -0
- lingxigraph-2.0.1/tests/test_streaming.py +51 -0
- lingxigraph-2.0.1/tests/test_studio_and_cli_v2.py +160 -0
- lingxigraph-2.0.1/tests/test_subgraph.py +136 -0
- lingxigraph-2.0.1/tests/test_v1_core.py +222 -0
- lingxigraph-2.0.1/tests/test_v2_agent_core.py +343 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LingXi 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,256 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: lingxigraph
|
|
3
|
+
Version: 2.0.1
|
|
4
|
+
Summary: Enterprise, provider-neutral durable graph runtime for multi-agent systems.
|
|
5
|
+
Author: LingXi Team
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
8
|
+
Classifier: Framework :: FastAPI
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
13
|
+
Classifier: Typing :: Typed
|
|
14
|
+
Requires-Python: >=3.11
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Provides-Extra: server
|
|
18
|
+
Requires-Dist: fastapi<1,>=0.115; extra == "server"
|
|
19
|
+
Requires-Dist: httpx<1,>=0.27; extra == "server"
|
|
20
|
+
Requires-Dist: pydantic<3,>=2.8; extra == "server"
|
|
21
|
+
Requires-Dist: PyJWT[crypto]<3,>=2.9; extra == "server"
|
|
22
|
+
Requires-Dist: uvicorn[standard]<1,>=0.30; extra == "server"
|
|
23
|
+
Provides-Extra: postgres
|
|
24
|
+
Requires-Dist: alembic<2,>=1.13; extra == "postgres"
|
|
25
|
+
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "postgres"
|
|
26
|
+
Provides-Extra: redis
|
|
27
|
+
Requires-Dist: redis<7,>=5.1; extra == "redis"
|
|
28
|
+
Provides-Extra: otel
|
|
29
|
+
Requires-Dist: opentelemetry-api<2,>=1.27; extra == "otel"
|
|
30
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.27; extra == "otel"
|
|
31
|
+
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == "otel"
|
|
32
|
+
Provides-Extra: sdk
|
|
33
|
+
Requires-Dist: httpx<1,>=0.27; extra == "sdk"
|
|
34
|
+
Provides-Extra: coze
|
|
35
|
+
Requires-Dist: httpx<1,>=0.27; extra == "coze"
|
|
36
|
+
Provides-Extra: openai
|
|
37
|
+
Requires-Dist: httpx<1,>=0.27; extra == "openai"
|
|
38
|
+
Provides-Extra: all
|
|
39
|
+
Requires-Dist: fastapi<1,>=0.115; extra == "all"
|
|
40
|
+
Requires-Dist: httpx<1,>=0.27; extra == "all"
|
|
41
|
+
Requires-Dist: alembic<2,>=1.13; extra == "all"
|
|
42
|
+
Requires-Dist: opentelemetry-api<2,>=1.27; extra == "all"
|
|
43
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.27; extra == "all"
|
|
44
|
+
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == "all"
|
|
45
|
+
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "all"
|
|
46
|
+
Requires-Dist: pydantic<3,>=2.8; extra == "all"
|
|
47
|
+
Requires-Dist: PyJWT[crypto]<3,>=2.9; extra == "all"
|
|
48
|
+
Requires-Dist: redis<7,>=5.1; extra == "all"
|
|
49
|
+
Requires-Dist: uvicorn[standard]<1,>=0.30; extra == "all"
|
|
50
|
+
Provides-Extra: dev
|
|
51
|
+
Requires-Dist: build<2,>=1.2; extra == "dev"
|
|
52
|
+
Requires-Dist: coverage[toml]<8,>=7.6; extra == "dev"
|
|
53
|
+
Requires-Dist: cyclonedx-bom<8,>=7; extra == "dev"
|
|
54
|
+
Requires-Dist: hypothesis<7,>=6.112; extra == "dev"
|
|
55
|
+
Requires-Dist: mypy<2,>=1.11; extra == "dev"
|
|
56
|
+
Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
|
|
57
|
+
Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
|
|
58
|
+
Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
|
|
59
|
+
Requires-Dist: ruff<1,>=0.6; extra == "dev"
|
|
60
|
+
Requires-Dist: testcontainers[postgres,redis]<5,>=4.8; extra == "dev"
|
|
61
|
+
Dynamic: license-file
|
|
62
|
+
|
|
63
|
+
# LingxiGraph
|
|
64
|
+
|
|
65
|
+
<div align="center">
|
|
66
|
+
|
|
67
|
+
**面向生产环境的、模型供应商中立的耐久多智能体图运行时**
|
|
68
|
+
|
|
69
|
+
[English](README.en.md) · [快速开始](Wiki/zh/quickstart/installation.mdx) · [完整文档](Wiki/zh/index.mdx) · [API 参考](Wiki/zh/api/overview.mdx) · [更新日志](CHANGELOG.md)
|
|
70
|
+
|
|
71
|
+
[](https://github.com/LingXi-Org/LingxiGraph/actions/workflows/ci.yml)
|
|
72
|
+
[](https://www.python.org/)
|
|
73
|
+
[](LICENSE)
|
|
74
|
+
[](CHANGELOG.md)
|
|
75
|
+
|
|
76
|
+
</div>
|
|
77
|
+
|
|
78
|
+
LingxiGraph 把普通 Python 函数组装成可持久化、可恢复、可流式观察的状态图。你可以只使用零依赖核心将它嵌入应用,也可以运行完整的 Agent Server、分布式 Worker、PostgreSQL 队列和 Studio 调试界面。
|
|
79
|
+
|
|
80
|
+
它适合需要长时间运行、人工审批、并行协作、失败恢复与严格多租户隔离的 Agent 工作负载;不绑定任何模型 SDK、提示词平台或云供应商。
|
|
81
|
+
|
|
82
|
+
## 为什么选择 LingxiGraph
|
|
83
|
+
|
|
84
|
+
- **确定性图运行时**:Pregel 风格 `plan → execute → commit` 超步;并行任务按编译计划确定性归并。
|
|
85
|
+
- **耐久执行**:typed checkpoint、pending writes、历史、replay、fork 与任意深度子图 namespace。
|
|
86
|
+
- **模型中立 Agent 层**:中立消息、`ChatModel`、强类型工具、ReAct 预制件、HITL 审批与结构化输出。
|
|
87
|
+
- **多智能体模式**:supervisor、handoff、swarm、group chat、plan-execute、parallel review 与 map-reduce。
|
|
88
|
+
- **生产控制面**:版本固定、PostgreSQL 租约队列、幂等键、dead-letter/redrive、预算、配额和协作式取消。
|
|
89
|
+
- **开放协议**:REST、可续传 SSE、Python SDK、A2A、MCP、Coze 与 OpenAI-compatible 适配器。
|
|
90
|
+
- **安全与可观测性**:OIDC/JWT、RBAC、tenant 隔离、PostgreSQL RLS、审计、JSON 日志和 OpenTelemetry。
|
|
91
|
+
- **开发者体验**:项目脚手架、本地内存栈、热重载、内嵌 Studio、Docker Compose 与 Helm Chart。
|
|
92
|
+
|
|
93
|
+
## 30 秒上手
|
|
94
|
+
|
|
95
|
+
要求 Python 3.11 或更高版本。
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pip install lingxigraph
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from typing import TypedDict
|
|
103
|
+
|
|
104
|
+
from lingxigraph import END, START, Runtime, StateGraph
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class State(TypedDict):
|
|
108
|
+
request: str
|
|
109
|
+
result: str
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class Context(TypedDict):
|
|
113
|
+
tenant: str
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def resolve(state: State, runtime: Runtime[Context]):
|
|
117
|
+
runtime.stream_writer({"stage": "resolving"})
|
|
118
|
+
return {"result": f"{runtime.context['tenant']}: {state['request']}"}
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
builder = StateGraph(State, context_schema=Context, name="support", version="1.0.0")
|
|
122
|
+
builder.add_node("resolve", resolve, timeout=30)
|
|
123
|
+
builder.add_edge(START, "resolve").add_edge("resolve", END)
|
|
124
|
+
graph = builder.compile()
|
|
125
|
+
|
|
126
|
+
print(graph.invoke(
|
|
127
|
+
{"request": "reset access", "result": ""},
|
|
128
|
+
context={"tenant": "acme"},
|
|
129
|
+
))
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
预期输出:
|
|
133
|
+
|
|
134
|
+
```text
|
|
135
|
+
{'request': 'reset access', 'result': 'acme: reset access'}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
生产副作用应使用 `runtime.idempotency_key` 在下游去重。LingxiGraph 保证状态提交幂等;外部网络调用采用至少一次语义。
|
|
139
|
+
|
|
140
|
+
## 选择你的运行方式
|
|
141
|
+
|
|
142
|
+
| 场景 | 安装或命令 | 适用范围 |
|
|
143
|
+
| --- | --- | --- |
|
|
144
|
+
| 嵌入 Python 应用 | `pip install lingxigraph` | 本地图执行、测试、库集成 |
|
|
145
|
+
| 本地 Agent 开发 | `pip install "lingxigraph[server]"` + `lingxigraph dev` | 内存存储、内嵌 Worker、Studio |
|
|
146
|
+
| 单服务器生产栈 | `docker compose up --build` | PostgreSQL、Redis、API、Worker、Studio |
|
|
147
|
+
| 独立扩展 | `lingxigraph server` / `lingxigraph worker` | 多进程或 Kubernetes 部署 |
|
|
148
|
+
|
|
149
|
+
创建一个可直接运行的 Agent 项目:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
lingxigraph new my-agent
|
|
153
|
+
cd my-agent
|
|
154
|
+
pip install -e .
|
|
155
|
+
lingxigraph dev
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
打开 `http://localhost:8124/studio/` 查看真实图结构、SSE 执行轨迹、thread 状态、检查点和中断恢复。
|
|
159
|
+
|
|
160
|
+
## Agent 与工具
|
|
161
|
+
|
|
162
|
+
核心包不依赖任何模型厂商。模型只需实现 `ChatModel.agenerate()`;支持流式时再实现 `astream()`。工具参数由 Python 类型注解生成 JSON Schema,并可配置权限、secret 注入、超时和人工审批。
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
from lingxigraph import HumanMessage, create_agent, tool
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
@tool(permissions=("knowledge:read",), timeout=10)
|
|
169
|
+
def search(query: str) -> str:
|
|
170
|
+
"""Search the internal knowledge base."""
|
|
171
|
+
return f"result for {query}"
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
agent = create_agent(model, [search], system_prompt="You are a support agent.")
|
|
175
|
+
result = agent.invoke(
|
|
176
|
+
{"messages": [HumanMessage("查找退款规则")]},
|
|
177
|
+
{"tool_permissions": ["knowledge:read"], "max_tool_calls": 4},
|
|
178
|
+
)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
官方适配器按需安装:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
pip install "lingxigraph[coze]" # Coze Bot / Workflow / ChatModel
|
|
185
|
+
pip install "lingxigraph[openai]" # OpenAI-compatible ChatModel
|
|
186
|
+
pip install "lingxigraph[all]" # 完整服务端与集成依赖
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## 平台架构
|
|
190
|
+
|
|
191
|
+
```mermaid
|
|
192
|
+
flowchart LR
|
|
193
|
+
Client["REST / SSE / Python SDK"] --> API["Agent Server"]
|
|
194
|
+
API --> PG[("PostgreSQL\ncontrol plane + queue")]
|
|
195
|
+
API -. "event hints" .-> Redis[("Redis\ncache + PubSub")]
|
|
196
|
+
Worker["Distributed Worker"] -->|"lease + SKIP LOCKED"| PG
|
|
197
|
+
Redis -. "optional acceleration" .-> Worker
|
|
198
|
+
Worker --> Runtime["CompiledGraph runtime"]
|
|
199
|
+
Runtime --> PG
|
|
200
|
+
Runtime --> Remote["Models / Coze / A2A / MCP"]
|
|
201
|
+
Runtime --> OTel["OpenTelemetry"]
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
PostgreSQL 是队列、事件与状态的真相来源。Redis 仅用于缓存、限流、取消和事件提示;Redis 故障时任务与 SSE 会退化为数据库轮询,不影响持久状态正确性。
|
|
205
|
+
|
|
206
|
+
## 文档
|
|
207
|
+
|
|
208
|
+
完整的双语文档库位于醒目的 [`Wiki/`](Wiki/README.md),可直接使用 Mintlify 进行本地预览和部署。
|
|
209
|
+
|
|
210
|
+
| 中文 | English |
|
|
211
|
+
| --- | --- |
|
|
212
|
+
| [安装](Wiki/zh/quickstart/installation.mdx) | [Installation](Wiki/en/quickstart/installation.mdx) |
|
|
213
|
+
| [创建第一个图](Wiki/zh/quickstart/first-graph.mdx) | [Build your first graph](Wiki/en/quickstart/first-graph.mdx) |
|
|
214
|
+
| [Agent Server](Wiki/zh/quickstart/agent-server.mdx) | [Agent Server](Wiki/en/quickstart/agent-server.mdx) |
|
|
215
|
+
| [核心概念](Wiki/zh/concepts/architecture.mdx) | [Core concepts](Wiki/en/concepts/architecture.mdx) |
|
|
216
|
+
| [REST / SSE API](Wiki/zh/api/overview.mdx) | [REST / SSE API](Wiki/en/api/overview.mdx) |
|
|
217
|
+
| [生产部署](Wiki/zh/guides/deployment.mdx) | [Production deployment](Wiki/en/guides/deployment.mdx) |
|
|
218
|
+
| [安全与可观测性](Wiki/zh/operations/security-observability.mdx) | [Security and observability](Wiki/en/operations/security-observability.mdx) |
|
|
219
|
+
|
|
220
|
+
本地预览文档:
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
cd Wiki
|
|
224
|
+
npx mintlify dev
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## 开发与验证
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
git clone https://github.com/LingXi-Org/LingxiGraph.git
|
|
231
|
+
cd LingxiGraph
|
|
232
|
+
python -m venv .venv
|
|
233
|
+
# Linux/macOS: source .venv/bin/activate
|
|
234
|
+
# Windows: .venv\Scripts\activate
|
|
235
|
+
pip install -e ".[dev,all]"
|
|
236
|
+
pytest
|
|
237
|
+
ruff check src tests
|
|
238
|
+
mypy src/lingxigraph
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
CI 覆盖 Python 3.11 与 3.13,并执行单元/集成测试、Ruff、mypy、80% 分支覆盖率门槛、依赖审计、镜像扫描与 CycloneDX SBOM 生成。PostgreSQL/Redis 集成测试需要 Docker。
|
|
242
|
+
|
|
243
|
+
## 兼容性与稳定性
|
|
244
|
+
|
|
245
|
+
- Python:3.11、3.12、3.13。
|
|
246
|
+
- API:版本化路径 `/v1`;错误使用稳定 `code` 与 `retryable` 字段。
|
|
247
|
+
- 状态:安全 JSON typed serializer;不在生产状态中使用 pickle。
|
|
248
|
+
- 发布:graph ID 与 version 固定到每个 run,滚动升级不会改变已排队或暂停的执行。
|
|
249
|
+
|
|
250
|
+
## 参与贡献
|
|
251
|
+
|
|
252
|
+
提交更改前请阅读[贡献指南](Wiki/zh/contributing.mdx)。安全问题请不要公开披露;按[安全指南](Wiki/zh/operations/security-observability.mdx)中的流程联系维护者。
|
|
253
|
+
|
|
254
|
+
## License
|
|
255
|
+
|
|
256
|
+
LingxiGraph 基于 [MIT License](LICENSE) 发布。
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
# LingxiGraph
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
**面向生产环境的、模型供应商中立的耐久多智能体图运行时**
|
|
6
|
+
|
|
7
|
+
[English](README.en.md) · [快速开始](Wiki/zh/quickstart/installation.mdx) · [完整文档](Wiki/zh/index.mdx) · [API 参考](Wiki/zh/api/overview.mdx) · [更新日志](CHANGELOG.md)
|
|
8
|
+
|
|
9
|
+
[](https://github.com/LingXi-Org/LingxiGraph/actions/workflows/ci.yml)
|
|
10
|
+
[](https://www.python.org/)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](CHANGELOG.md)
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
LingxiGraph 把普通 Python 函数组装成可持久化、可恢复、可流式观察的状态图。你可以只使用零依赖核心将它嵌入应用,也可以运行完整的 Agent Server、分布式 Worker、PostgreSQL 队列和 Studio 调试界面。
|
|
17
|
+
|
|
18
|
+
它适合需要长时间运行、人工审批、并行协作、失败恢复与严格多租户隔离的 Agent 工作负载;不绑定任何模型 SDK、提示词平台或云供应商。
|
|
19
|
+
|
|
20
|
+
## 为什么选择 LingxiGraph
|
|
21
|
+
|
|
22
|
+
- **确定性图运行时**:Pregel 风格 `plan → execute → commit` 超步;并行任务按编译计划确定性归并。
|
|
23
|
+
- **耐久执行**:typed checkpoint、pending writes、历史、replay、fork 与任意深度子图 namespace。
|
|
24
|
+
- **模型中立 Agent 层**:中立消息、`ChatModel`、强类型工具、ReAct 预制件、HITL 审批与结构化输出。
|
|
25
|
+
- **多智能体模式**:supervisor、handoff、swarm、group chat、plan-execute、parallel review 与 map-reduce。
|
|
26
|
+
- **生产控制面**:版本固定、PostgreSQL 租约队列、幂等键、dead-letter/redrive、预算、配额和协作式取消。
|
|
27
|
+
- **开放协议**:REST、可续传 SSE、Python SDK、A2A、MCP、Coze 与 OpenAI-compatible 适配器。
|
|
28
|
+
- **安全与可观测性**:OIDC/JWT、RBAC、tenant 隔离、PostgreSQL RLS、审计、JSON 日志和 OpenTelemetry。
|
|
29
|
+
- **开发者体验**:项目脚手架、本地内存栈、热重载、内嵌 Studio、Docker Compose 与 Helm Chart。
|
|
30
|
+
|
|
31
|
+
## 30 秒上手
|
|
32
|
+
|
|
33
|
+
要求 Python 3.11 或更高版本。
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install lingxigraph
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from typing import TypedDict
|
|
41
|
+
|
|
42
|
+
from lingxigraph import END, START, Runtime, StateGraph
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class State(TypedDict):
|
|
46
|
+
request: str
|
|
47
|
+
result: str
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class Context(TypedDict):
|
|
51
|
+
tenant: str
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def resolve(state: State, runtime: Runtime[Context]):
|
|
55
|
+
runtime.stream_writer({"stage": "resolving"})
|
|
56
|
+
return {"result": f"{runtime.context['tenant']}: {state['request']}"}
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
builder = StateGraph(State, context_schema=Context, name="support", version="1.0.0")
|
|
60
|
+
builder.add_node("resolve", resolve, timeout=30)
|
|
61
|
+
builder.add_edge(START, "resolve").add_edge("resolve", END)
|
|
62
|
+
graph = builder.compile()
|
|
63
|
+
|
|
64
|
+
print(graph.invoke(
|
|
65
|
+
{"request": "reset access", "result": ""},
|
|
66
|
+
context={"tenant": "acme"},
|
|
67
|
+
))
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
预期输出:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
{'request': 'reset access', 'result': 'acme: reset access'}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
生产副作用应使用 `runtime.idempotency_key` 在下游去重。LingxiGraph 保证状态提交幂等;外部网络调用采用至少一次语义。
|
|
77
|
+
|
|
78
|
+
## 选择你的运行方式
|
|
79
|
+
|
|
80
|
+
| 场景 | 安装或命令 | 适用范围 |
|
|
81
|
+
| --- | --- | --- |
|
|
82
|
+
| 嵌入 Python 应用 | `pip install lingxigraph` | 本地图执行、测试、库集成 |
|
|
83
|
+
| 本地 Agent 开发 | `pip install "lingxigraph[server]"` + `lingxigraph dev` | 内存存储、内嵌 Worker、Studio |
|
|
84
|
+
| 单服务器生产栈 | `docker compose up --build` | PostgreSQL、Redis、API、Worker、Studio |
|
|
85
|
+
| 独立扩展 | `lingxigraph server` / `lingxigraph worker` | 多进程或 Kubernetes 部署 |
|
|
86
|
+
|
|
87
|
+
创建一个可直接运行的 Agent 项目:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
lingxigraph new my-agent
|
|
91
|
+
cd my-agent
|
|
92
|
+
pip install -e .
|
|
93
|
+
lingxigraph dev
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
打开 `http://localhost:8124/studio/` 查看真实图结构、SSE 执行轨迹、thread 状态、检查点和中断恢复。
|
|
97
|
+
|
|
98
|
+
## Agent 与工具
|
|
99
|
+
|
|
100
|
+
核心包不依赖任何模型厂商。模型只需实现 `ChatModel.agenerate()`;支持流式时再实现 `astream()`。工具参数由 Python 类型注解生成 JSON Schema,并可配置权限、secret 注入、超时和人工审批。
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from lingxigraph import HumanMessage, create_agent, tool
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
@tool(permissions=("knowledge:read",), timeout=10)
|
|
107
|
+
def search(query: str) -> str:
|
|
108
|
+
"""Search the internal knowledge base."""
|
|
109
|
+
return f"result for {query}"
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
agent = create_agent(model, [search], system_prompt="You are a support agent.")
|
|
113
|
+
result = agent.invoke(
|
|
114
|
+
{"messages": [HumanMessage("查找退款规则")]},
|
|
115
|
+
{"tool_permissions": ["knowledge:read"], "max_tool_calls": 4},
|
|
116
|
+
)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
官方适配器按需安装:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
pip install "lingxigraph[coze]" # Coze Bot / Workflow / ChatModel
|
|
123
|
+
pip install "lingxigraph[openai]" # OpenAI-compatible ChatModel
|
|
124
|
+
pip install "lingxigraph[all]" # 完整服务端与集成依赖
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## 平台架构
|
|
128
|
+
|
|
129
|
+
```mermaid
|
|
130
|
+
flowchart LR
|
|
131
|
+
Client["REST / SSE / Python SDK"] --> API["Agent Server"]
|
|
132
|
+
API --> PG[("PostgreSQL\ncontrol plane + queue")]
|
|
133
|
+
API -. "event hints" .-> Redis[("Redis\ncache + PubSub")]
|
|
134
|
+
Worker["Distributed Worker"] -->|"lease + SKIP LOCKED"| PG
|
|
135
|
+
Redis -. "optional acceleration" .-> Worker
|
|
136
|
+
Worker --> Runtime["CompiledGraph runtime"]
|
|
137
|
+
Runtime --> PG
|
|
138
|
+
Runtime --> Remote["Models / Coze / A2A / MCP"]
|
|
139
|
+
Runtime --> OTel["OpenTelemetry"]
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
PostgreSQL 是队列、事件与状态的真相来源。Redis 仅用于缓存、限流、取消和事件提示;Redis 故障时任务与 SSE 会退化为数据库轮询,不影响持久状态正确性。
|
|
143
|
+
|
|
144
|
+
## 文档
|
|
145
|
+
|
|
146
|
+
完整的双语文档库位于醒目的 [`Wiki/`](Wiki/README.md),可直接使用 Mintlify 进行本地预览和部署。
|
|
147
|
+
|
|
148
|
+
| 中文 | English |
|
|
149
|
+
| --- | --- |
|
|
150
|
+
| [安装](Wiki/zh/quickstart/installation.mdx) | [Installation](Wiki/en/quickstart/installation.mdx) |
|
|
151
|
+
| [创建第一个图](Wiki/zh/quickstart/first-graph.mdx) | [Build your first graph](Wiki/en/quickstart/first-graph.mdx) |
|
|
152
|
+
| [Agent Server](Wiki/zh/quickstart/agent-server.mdx) | [Agent Server](Wiki/en/quickstart/agent-server.mdx) |
|
|
153
|
+
| [核心概念](Wiki/zh/concepts/architecture.mdx) | [Core concepts](Wiki/en/concepts/architecture.mdx) |
|
|
154
|
+
| [REST / SSE API](Wiki/zh/api/overview.mdx) | [REST / SSE API](Wiki/en/api/overview.mdx) |
|
|
155
|
+
| [生产部署](Wiki/zh/guides/deployment.mdx) | [Production deployment](Wiki/en/guides/deployment.mdx) |
|
|
156
|
+
| [安全与可观测性](Wiki/zh/operations/security-observability.mdx) | [Security and observability](Wiki/en/operations/security-observability.mdx) |
|
|
157
|
+
|
|
158
|
+
本地预览文档:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
cd Wiki
|
|
162
|
+
npx mintlify dev
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## 开发与验证
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
git clone https://github.com/LingXi-Org/LingxiGraph.git
|
|
169
|
+
cd LingxiGraph
|
|
170
|
+
python -m venv .venv
|
|
171
|
+
# Linux/macOS: source .venv/bin/activate
|
|
172
|
+
# Windows: .venv\Scripts\activate
|
|
173
|
+
pip install -e ".[dev,all]"
|
|
174
|
+
pytest
|
|
175
|
+
ruff check src tests
|
|
176
|
+
mypy src/lingxigraph
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
CI 覆盖 Python 3.11 与 3.13,并执行单元/集成测试、Ruff、mypy、80% 分支覆盖率门槛、依赖审计、镜像扫描与 CycloneDX SBOM 生成。PostgreSQL/Redis 集成测试需要 Docker。
|
|
180
|
+
|
|
181
|
+
## 兼容性与稳定性
|
|
182
|
+
|
|
183
|
+
- Python:3.11、3.12、3.13。
|
|
184
|
+
- API:版本化路径 `/v1`;错误使用稳定 `code` 与 `retryable` 字段。
|
|
185
|
+
- 状态:安全 JSON typed serializer;不在生产状态中使用 pickle。
|
|
186
|
+
- 发布:graph ID 与 version 固定到每个 run,滚动升级不会改变已排队或暂停的执行。
|
|
187
|
+
|
|
188
|
+
## 参与贡献
|
|
189
|
+
|
|
190
|
+
提交更改前请阅读[贡献指南](Wiki/zh/contributing.mdx)。安全问题请不要公开披露;按[安全指南](Wiki/zh/operations/security-observability.mdx)中的流程联系维护者。
|
|
191
|
+
|
|
192
|
+
## License
|
|
193
|
+
|
|
194
|
+
LingxiGraph 基于 [MIT License](LICENSE) 发布。
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "lingxigraph"
|
|
7
|
+
version = "2.0.1"
|
|
8
|
+
description = "Enterprise, provider-neutral durable graph runtime for multi-agent systems."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
authors = [{ name = "LingXi Team" }]
|
|
12
|
+
license = "MIT"
|
|
13
|
+
dependencies = []
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 5 - Production/Stable",
|
|
16
|
+
"Framework :: FastAPI",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Programming Language :: Python :: 3.13",
|
|
21
|
+
"Typing :: Typed",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
[project.optional-dependencies]
|
|
25
|
+
server = [
|
|
26
|
+
"fastapi>=0.115,<1",
|
|
27
|
+
"httpx>=0.27,<1",
|
|
28
|
+
"pydantic>=2.8,<3",
|
|
29
|
+
"PyJWT[crypto]>=2.9,<3",
|
|
30
|
+
"uvicorn[standard]>=0.30,<1",
|
|
31
|
+
]
|
|
32
|
+
postgres = ["alembic>=1.13,<2", "psycopg[binary]>=3.2,<4"]
|
|
33
|
+
redis = ["redis>=5.1,<7"]
|
|
34
|
+
otel = [
|
|
35
|
+
"opentelemetry-api>=1.27,<2",
|
|
36
|
+
"opentelemetry-exporter-otlp-proto-grpc>=1.27,<2",
|
|
37
|
+
"opentelemetry-sdk>=1.27,<2",
|
|
38
|
+
]
|
|
39
|
+
sdk = ["httpx>=0.27,<1"]
|
|
40
|
+
coze = ["httpx>=0.27,<1"]
|
|
41
|
+
openai = ["httpx>=0.27,<1"]
|
|
42
|
+
all = [
|
|
43
|
+
"fastapi>=0.115,<1",
|
|
44
|
+
"httpx>=0.27,<1",
|
|
45
|
+
"alembic>=1.13,<2",
|
|
46
|
+
"opentelemetry-api>=1.27,<2",
|
|
47
|
+
"opentelemetry-exporter-otlp-proto-grpc>=1.27,<2",
|
|
48
|
+
"opentelemetry-sdk>=1.27,<2",
|
|
49
|
+
"psycopg[binary]>=3.2,<4",
|
|
50
|
+
"pydantic>=2.8,<3",
|
|
51
|
+
"PyJWT[crypto]>=2.9,<3",
|
|
52
|
+
"redis>=5.1,<7",
|
|
53
|
+
"uvicorn[standard]>=0.30,<1",
|
|
54
|
+
]
|
|
55
|
+
dev = [
|
|
56
|
+
"build>=1.2,<2",
|
|
57
|
+
"coverage[toml]>=7.6,<8",
|
|
58
|
+
"cyclonedx-bom>=7,<8",
|
|
59
|
+
"hypothesis>=6.112,<7",
|
|
60
|
+
"mypy>=1.11,<2",
|
|
61
|
+
"pip-audit>=2.7,<3",
|
|
62
|
+
"pytest>=9.0.3,<10",
|
|
63
|
+
"pytest-asyncio>=0.24,<2",
|
|
64
|
+
"ruff>=0.6,<1",
|
|
65
|
+
"testcontainers[postgres,redis]>=4.8,<5",
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
[project.scripts]
|
|
69
|
+
lingxigraph = "lingxigraph.cli:main"
|
|
70
|
+
|
|
71
|
+
[tool.setuptools]
|
|
72
|
+
package-dir = { "" = "src" }
|
|
73
|
+
|
|
74
|
+
[tool.setuptools.packages.find]
|
|
75
|
+
where = ["src"]
|
|
76
|
+
|
|
77
|
+
[tool.setuptools.package-data]
|
|
78
|
+
lingxigraph = ["server/migrations/*.sql", "studio/*.html", "studio/*.css", "studio/*.js", "py.typed"]
|
|
79
|
+
|
|
80
|
+
[tool.unittest]
|
|
81
|
+
start-directory = "tests"
|
|
82
|
+
|
|
83
|
+
[tool.ruff]
|
|
84
|
+
target-version = "py311"
|
|
85
|
+
line-length = 96
|
|
86
|
+
|
|
87
|
+
[tool.ruff.lint]
|
|
88
|
+
select = ["E", "F", "I", "B", "ASYNC"]
|
|
89
|
+
ignore = ["E501", "E402", "B008", "ASYNC109", "ASYNC110"]
|
|
90
|
+
|
|
91
|
+
[tool.mypy]
|
|
92
|
+
python_version = "3.11"
|
|
93
|
+
strict = false
|
|
94
|
+
check_untyped_defs = true
|
|
95
|
+
ignore_missing_imports = true
|
|
96
|
+
warn_redundant_casts = true
|
|
97
|
+
warn_unused_ignores = true
|
|
98
|
+
warn_unused_configs = true
|
|
99
|
+
|
|
100
|
+
[tool.pytest.ini_options]
|
|
101
|
+
testpaths = ["tests"]
|
|
102
|
+
asyncio_mode = "auto"
|
|
103
|
+
|
|
104
|
+
[tool.coverage.run]
|
|
105
|
+
branch = true
|
|
106
|
+
source = ["lingxigraph"]
|
|
107
|
+
|
|
108
|
+
[tool.coverage.report]
|
|
109
|
+
show_missing = true
|
|
110
|
+
fail_under = 80
|