dynworkflow 0.1.0__tar.gz

dynworkflow-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.3
+Name: dynworkflow
+Version: 0.1.0
+Summary: Dynamic Workflow Library for Alkaid0
+Author: cxykevin
+Author-email: cxykevin <cxykevin@yeah.net>
+Requires-Dist: websockets>=15.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# dynworkflow
+
+`dynworkflow` 是一个 Python 3.12 库，用于编排动态工作流，工作流节点可以调用一个或多个 ACP Agent。
+
+## 安装
+
+使用项目包管理器安装：
+
+```bash
+uv sync
+```
+
+运行时依赖为 `websockets`，开发依赖包括 `pytest` 和 `mypy`。
+
+## 快速开始
+
+```python
+import dynworkflow as d
+
+flow = d.Flow(
+    "document-flow",
+    agent=d.AgentClient("ws://127.0.0.1:7433/acp?k=a"),
+)
+
+@flow.node("summarize")
+def summarize() -> d.TaskGenerator:
+    result = yield d.Agent("Summarize the documents in docs/test", path="docs/test")
+    return d.Result(result)
+
+flow.execute(summarize())
+```
+
+使用 `@flow.node(name)` 声明节点。普通节点可以返回 `None`、`Result` 或一个或多个下游 `Execute` 任务。生成器节点可以 `yield Agent` 或 `MultiAgent`，接收 Agent 结果后返回节点结果。
+
+## 公共 API
+
+- `Flow`：创建并执行工作流。
+- `Flow.node(name)`：注册节点函数。
+- `Flow.execute(*tasks)`：在当前进程中执行任务，并在所有节点结束后抛出节点异常。
+- `Flow.run(*tasks)`：在 fork 子进程中运行工作流，并监听 stdin 中的 JSONL 控制命令。
+- `Agent`：描述一次 Agent 请求。
+- `MultiAgent`：并发运行多个 Agent 请求。
+- `AgentClient`：连接 ACP WebSocket 端点。
+- `Result`：保存节点的最终结果。
+
+## 执行语义
+
+- 相互独立的节点会并发运行。
+- 节点失败后会立即变为 `error` 状态，并在启用上报时立即发送状态。
+- 失败节点不会停止兄弟节点。
+- 所有节点异常会在最后统一以 `ExceptionGroup` 抛出。
+- 节点和 Agent 的终止命令只影响指定目标；工作流关闭会终止整个工作流。
+
+## 缓存与状态上报
+
+缓存默认启用。可以使用 `Flow(..., cache=False)` 关闭缓存。缓存文件位于 `.alkaid0/workflow.db`；设置 `ALKAID0_WORKFLOW_SESSION_ID` 可以隔离不同会话。
+
+可以通过 `Flow(..., report=True)` 或环境变量 `ALKAID0_WORKFLOW_REPORT=1` 开启 JSONL 状态上报。`Flow.run()` 会自动开启上报。事件包括 `graph`、`node`、`agent`、`agents_start`、`node_code` 和 `node_log`。
+
+## 示例
+
+参见 `example.py`，其中包含使用 `AgentClient`、`Agent`、`MultiAgent`、分支和回退参数的完整工作流示例。
+
+## 测试
+
+运行测试套件：
+
+```bash
+python -m pytest -q
+```
+
+运行静态编译检查：
+
+```bash
+python -m compileall -q src tests
+```
+
+## 文档索引
+
+- `docs/SKILL.md`：仅供 AI Agent 读取的使用说明，保持英文。
+- `docs/architecture.md`：面向人的实现与生命周期说明。
+- `docs/protocol.md`：stdin 控制命令和 JSONL 上报事件说明。
+- `docs/test/ai_must_read.md`：示例工作流读取的测试文档。

dynworkflow-0.1.0/README.md

@@ -0,0 +1,83 @@
+# dynworkflow
+
+`dynworkflow` 是一个 Python 3.12 库，用于编排动态工作流，工作流节点可以调用一个或多个 ACP Agent。
+
+## 安装
+
+使用项目包管理器安装：
+
+```bash
+uv sync
+```
+
+运行时依赖为 `websockets`，开发依赖包括 `pytest` 和 `mypy`。
+
+## 快速开始
+
+```python
+import dynworkflow as d
+
+flow = d.Flow(
+    "document-flow",
+    agent=d.AgentClient("ws://127.0.0.1:7433/acp?k=a"),
+)
+
+@flow.node("summarize")
+def summarize() -> d.TaskGenerator:
+    result = yield d.Agent("Summarize the documents in docs/test", path="docs/test")
+    return d.Result(result)
+
+flow.execute(summarize())
+```
+
+使用 `@flow.node(name)` 声明节点。普通节点可以返回 `None`、`Result` 或一个或多个下游 `Execute` 任务。生成器节点可以 `yield Agent` 或 `MultiAgent`，接收 Agent 结果后返回节点结果。
+
+## 公共 API
+
+- `Flow`：创建并执行工作流。
+- `Flow.node(name)`：注册节点函数。
+- `Flow.execute(*tasks)`：在当前进程中执行任务，并在所有节点结束后抛出节点异常。
+- `Flow.run(*tasks)`：在 fork 子进程中运行工作流，并监听 stdin 中的 JSONL 控制命令。
+- `Agent`：描述一次 Agent 请求。
+- `MultiAgent`：并发运行多个 Agent 请求。
+- `AgentClient`：连接 ACP WebSocket 端点。
+- `Result`：保存节点的最终结果。
+
+## 执行语义
+
+- 相互独立的节点会并发运行。
+- 节点失败后会立即变为 `error` 状态，并在启用上报时立即发送状态。
+- 失败节点不会停止兄弟节点。
+- 所有节点异常会在最后统一以 `ExceptionGroup` 抛出。
+- 节点和 Agent 的终止命令只影响指定目标；工作流关闭会终止整个工作流。
+
+## 缓存与状态上报
+
+缓存默认启用。可以使用 `Flow(..., cache=False)` 关闭缓存。缓存文件位于 `.alkaid0/workflow.db`；设置 `ALKAID0_WORKFLOW_SESSION_ID` 可以隔离不同会话。
+
+可以通过 `Flow(..., report=True)` 或环境变量 `ALKAID0_WORKFLOW_REPORT=1` 开启 JSONL 状态上报。`Flow.run()` 会自动开启上报。事件包括 `graph`、`node`、`agent`、`agents_start`、`node_code` 和 `node_log`。
+
+## 示例
+
+参见 `example.py`，其中包含使用 `AgentClient`、`Agent`、`MultiAgent`、分支和回退参数的完整工作流示例。
+
+## 测试
+
+运行测试套件：
+
+```bash
+python -m pytest -q
+```
+
+运行静态编译检查：
+
+```bash
+python -m compileall -q src tests
+```
+
+## 文档索引
+
+- `docs/SKILL.md`：仅供 AI Agent 读取的使用说明，保持英文。
+- `docs/architecture.md`：面向人的实现与生命周期说明。
+- `docs/protocol.md`：stdin 控制命令和 JSONL 上报事件说明。
+- `docs/test/ai_must_read.md`：示例工作流读取的测试文档。

dynworkflow-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "dynworkflow"
+version = "0.1.0"
+description = "Dynamic Workflow Library for Alkaid0"
+readme = "README.md"
+authors = [{ name = "cxykevin", email = "cxykevin@yeah.net" }]
+requires-python = ">=3.12"
+dependencies = ["websockets>=15.0"]
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1", "mypy>=1.15"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.pyright]
+include = ["src", "tests"]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+reportMissingTypeStubs = false
+reportPrivateUsage = false

dynworkflow-0.1.0/src/dynworkflow/__init__.py

@@ -0,0 +1,19 @@
+from .flow import Flow, Agents, Result, Node, Execute, NodeResult, TaskGenerator
+from .agent import (
+    Agent,
+    MultiAgent,
+    AgentClient
+)
+
+__all__ = [
+    "Flow",
+    "Agent",
+    "Agents",
+    "MultiAgent",
+    "Result",
+    "Node",
+    "Execute",
+    "NodeResult",
+    "TaskGenerator",
+    "AgentClient"
+]