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.
Files changed (93) hide show
  1. lingxigraph-2.0.1/LICENSE +21 -0
  2. lingxigraph-2.0.1/PKG-INFO +256 -0
  3. lingxigraph-2.0.1/README.md +194 -0
  4. lingxigraph-2.0.1/pyproject.toml +110 -0
  5. lingxigraph-2.0.1/setup.cfg +4 -0
  6. lingxigraph-2.0.1/src/lingxigraph/__init__.py +187 -0
  7. lingxigraph-2.0.1/src/lingxigraph/__main__.py +6 -0
  8. lingxigraph-2.0.1/src/lingxigraph/cache.py +84 -0
  9. lingxigraph-2.0.1/src/lingxigraph/cache_redis.py +66 -0
  10. lingxigraph-2.0.1/src/lingxigraph/channels.py +190 -0
  11. lingxigraph-2.0.1/src/lingxigraph/checkpoint/__init__.py +115 -0
  12. lingxigraph-2.0.1/src/lingxigraph/checkpoint/memory.py +130 -0
  13. lingxigraph-2.0.1/src/lingxigraph/checkpoint/postgres.py +283 -0
  14. lingxigraph-2.0.1/src/lingxigraph/checkpoint/sqlite.py +329 -0
  15. lingxigraph-2.0.1/src/lingxigraph/cli.py +390 -0
  16. lingxigraph-2.0.1/src/lingxigraph/constants.py +6 -0
  17. lingxigraph-2.0.1/src/lingxigraph/errors.py +69 -0
  18. lingxigraph-2.0.1/src/lingxigraph/events.py +57 -0
  19. lingxigraph-2.0.1/src/lingxigraph/examples/__init__.py +1 -0
  20. lingxigraph-2.0.1/src/lingxigraph/examples/multi_agent_graph.py +118 -0
  21. lingxigraph-2.0.1/src/lingxigraph/examples/production_graph.py +36 -0
  22. lingxigraph-2.0.1/src/lingxigraph/func.py +122 -0
  23. lingxigraph-2.0.1/src/lingxigraph/graph/__init__.py +7 -0
  24. lingxigraph-2.0.1/src/lingxigraph/graph/builder.py +317 -0
  25. lingxigraph-2.0.1/src/lingxigraph/graph/executor.py +2403 -0
  26. lingxigraph-2.0.1/src/lingxigraph/graph/structure.py +67 -0
  27. lingxigraph-2.0.1/src/lingxigraph/integrations/__init__.py +37 -0
  28. lingxigraph-2.0.1/src/lingxigraph/integrations/_http.py +52 -0
  29. lingxigraph-2.0.1/src/lingxigraph/integrations/coze.py +850 -0
  30. lingxigraph-2.0.1/src/lingxigraph/integrations/openai_compat.py +225 -0
  31. lingxigraph-2.0.1/src/lingxigraph/messages.py +227 -0
  32. lingxigraph-2.0.1/src/lingxigraph/models.py +33 -0
  33. lingxigraph-2.0.1/src/lingxigraph/observability.py +127 -0
  34. lingxigraph-2.0.1/src/lingxigraph/patterns/__init__.py +25 -0
  35. lingxigraph-2.0.1/src/lingxigraph/patterns/multi_agent.py +410 -0
  36. lingxigraph-2.0.1/src/lingxigraph/prebuilt.py +214 -0
  37. lingxigraph-2.0.1/src/lingxigraph/protocols/__init__.py +12 -0
  38. lingxigraph-2.0.1/src/lingxigraph/protocols/a2a.py +165 -0
  39. lingxigraph-2.0.1/src/lingxigraph/protocols/mcp.py +169 -0
  40. lingxigraph-2.0.1/src/lingxigraph/py.typed +1 -0
  41. lingxigraph-2.0.1/src/lingxigraph/runtime.py +275 -0
  42. lingxigraph-2.0.1/src/lingxigraph/scaffold.py +264 -0
  43. lingxigraph-2.0.1/src/lingxigraph/schema.py +230 -0
  44. lingxigraph-2.0.1/src/lingxigraph/sdk.py +522 -0
  45. lingxigraph-2.0.1/src/lingxigraph/serialization.py +164 -0
  46. lingxigraph-2.0.1/src/lingxigraph/server/__init__.py +14 -0
  47. lingxigraph-2.0.1/src/lingxigraph/server/app.py +912 -0
  48. lingxigraph-2.0.1/src/lingxigraph/server/eventbus.py +80 -0
  49. lingxigraph-2.0.1/src/lingxigraph/server/migrations/0001_v1.sql +193 -0
  50. lingxigraph-2.0.1/src/lingxigraph/server/models.py +209 -0
  51. lingxigraph-2.0.1/src/lingxigraph/server/registry.py +110 -0
  52. lingxigraph-2.0.1/src/lingxigraph/server/repository.py +1219 -0
  53. lingxigraph-2.0.1/src/lingxigraph/server/security.py +125 -0
  54. lingxigraph-2.0.1/src/lingxigraph/server/worker.py +303 -0
  55. lingxigraph-2.0.1/src/lingxigraph/store/__init__.py +124 -0
  56. lingxigraph-2.0.1/src/lingxigraph/store/memory.py +196 -0
  57. lingxigraph-2.0.1/src/lingxigraph/store/postgres.py +242 -0
  58. lingxigraph-2.0.1/src/lingxigraph/studio/index.html +113 -0
  59. lingxigraph-2.0.1/src/lingxigraph/studio/studio.css +234 -0
  60. lingxigraph-2.0.1/src/lingxigraph/studio/studio.js +821 -0
  61. lingxigraph-2.0.1/src/lingxigraph/tools.py +331 -0
  62. lingxigraph-2.0.1/src/lingxigraph/types.py +243 -0
  63. lingxigraph-2.0.1/src/lingxigraph/version.py +5 -0
  64. lingxigraph-2.0.1/src/lingxigraph.egg-info/PKG-INFO +256 -0
  65. lingxigraph-2.0.1/src/lingxigraph.egg-info/SOURCES.txt +91 -0
  66. lingxigraph-2.0.1/src/lingxigraph.egg-info/dependency_links.txt +1 -0
  67. lingxigraph-2.0.1/src/lingxigraph.egg-info/entry_points.txt +2 -0
  68. lingxigraph-2.0.1/src/lingxigraph.egg-info/requires.txt +53 -0
  69. lingxigraph-2.0.1/src/lingxigraph.egg-info/top_level.txt +1 -0
  70. lingxigraph-2.0.1/tests/test_agent_server.py +409 -0
  71. lingxigraph-2.0.1/tests/test_architecture.py +52 -0
  72. lingxigraph-2.0.1/tests/test_builder.py +58 -0
  73. lingxigraph-2.0.1/tests/test_channels.py +90 -0
  74. lingxigraph-2.0.1/tests/test_checkpoint.py +53 -0
  75. lingxigraph-2.0.1/tests/test_execution.py +93 -0
  76. lingxigraph-2.0.1/tests/test_integrations_v2.py +641 -0
  77. lingxigraph-2.0.1/tests/test_interrupt.py +88 -0
  78. lingxigraph-2.0.1/tests/test_messages_tools_v2.py +128 -0
  79. lingxigraph-2.0.1/tests/test_mvp_hardening.py +745 -0
  80. lingxigraph-2.0.1/tests/test_patterns_protocols.py +214 -0
  81. lingxigraph-2.0.1/tests/test_platform_units.py +414 -0
  82. lingxigraph-2.0.1/tests/test_postgres_integration.py +161 -0
  83. lingxigraph-2.0.1/tests/test_retry.py +76 -0
  84. lingxigraph-2.0.1/tests/test_runtime_features.py +134 -0
  85. lingxigraph-2.0.1/tests/test_sdk.py +157 -0
  86. lingxigraph-2.0.1/tests/test_send.py +139 -0
  87. lingxigraph-2.0.1/tests/test_sqlite_saver.py +87 -0
  88. lingxigraph-2.0.1/tests/test_store.py +125 -0
  89. lingxigraph-2.0.1/tests/test_streaming.py +51 -0
  90. lingxigraph-2.0.1/tests/test_studio_and_cli_v2.py +160 -0
  91. lingxigraph-2.0.1/tests/test_subgraph.py +136 -0
  92. lingxigraph-2.0.1/tests/test_v1_core.py +222 -0
  93. 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
+ [![CI](https://github.com/LingXi-Org/LingxiGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/LingXi-Org/LingxiGraph/actions/workflows/ci.yml)
72
+ [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
73
+ [![License](https://img.shields.io/badge/License-MIT-16A34A.svg)](LICENSE)
74
+ [![Version](https://img.shields.io/badge/version-2.0.1-0F766E.svg)](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
+ [![CI](https://github.com/LingXi-Org/LingxiGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/LingXi-Org/LingxiGraph/actions/workflows/ci.yml)
10
+ [![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
11
+ [![License](https://img.shields.io/badge/License-MIT-16A34A.svg)](LICENSE)
12
+ [![Version](https://img.shields.io/badge/version-2.0.1-0F766E.svg)](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
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+