vercel-workflow 0.9.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.
- vercel_workflow-0.9.0/.gitignore +130 -0
- vercel_workflow-0.9.0/LICENSE +21 -0
- vercel_workflow-0.9.0/PKG-INFO +230 -0
- vercel_workflow-0.9.0/README.md +212 -0
- vercel_workflow-0.9.0/_vercel_hatch_build.py +151 -0
- vercel_workflow-0.9.0/hatch_build.py +29 -0
- vercel_workflow-0.9.0/pyproject.toml +71 -0
- vercel_workflow-0.9.0/vercel/workflow/__init__.py +67 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/__init__.py +0 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/core.py +328 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/__init__.py +21 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/constants.py +26 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/parse.py +347 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/stringify.py +290 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/utils.py +221 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/encryption.py +250 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/errors.py +5 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/loop.py +43 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/nanoid.py +228 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/py_sandbox.py +986 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/runtime.py +1678 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/serde.py +384 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/serialization.py +240 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/streams.py +620 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/ulid.py +157 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/world.py +1178 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/worlds/__init__.py +0 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/worlds/local.py +1268 -0
- vercel_workflow-0.9.0/vercel/workflow/_internal/worlds/vercel.py +859 -0
- vercel_workflow-0.9.0/vercel/workflow/errors.py +21 -0
- vercel_workflow-0.9.0/vercel/workflow/py.typed +1 -0
- vercel_workflow-0.9.0/vercel/workflow/sandbox.py +32 -0
- vercel_workflow-0.9.0/vercel/workflow/version.py +3 -0
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
*$py.class
|
|
4
|
+
|
|
5
|
+
# C extensions
|
|
6
|
+
*.so
|
|
7
|
+
|
|
8
|
+
# Distribution / packaging
|
|
9
|
+
.Python
|
|
10
|
+
build/
|
|
11
|
+
develop-eggs/
|
|
12
|
+
dist/
|
|
13
|
+
downloads/
|
|
14
|
+
eggs/
|
|
15
|
+
.eggs/
|
|
16
|
+
lib/
|
|
17
|
+
lib64/
|
|
18
|
+
parts/
|
|
19
|
+
sdist/
|
|
20
|
+
var/
|
|
21
|
+
wheels/
|
|
22
|
+
share/python-wheels/
|
|
23
|
+
*.egg-info/
|
|
24
|
+
.installed.cfg
|
|
25
|
+
*.egg
|
|
26
|
+
MANIFEST
|
|
27
|
+
|
|
28
|
+
# PyInstallerhave
|
|
29
|
+
*.manifest
|
|
30
|
+
*.spec
|
|
31
|
+
|
|
32
|
+
# Installer logs
|
|
33
|
+
pip-log.txt
|
|
34
|
+
pip-delete-this-directory.txt
|
|
35
|
+
|
|
36
|
+
# Unit test / coverage reports
|
|
37
|
+
.benchmarks/
|
|
38
|
+
htmlcov/
|
|
39
|
+
.tox/
|
|
40
|
+
.nox/
|
|
41
|
+
.coverage
|
|
42
|
+
.coverage.*
|
|
43
|
+
.cache
|
|
44
|
+
nosetests.xml
|
|
45
|
+
coverage.xml
|
|
46
|
+
*.cover
|
|
47
|
+
*.py,cover
|
|
48
|
+
.hypothesis/
|
|
49
|
+
.pytest_cache/
|
|
50
|
+
.ruff_cache/
|
|
51
|
+
|
|
52
|
+
# Translations
|
|
53
|
+
*.mo
|
|
54
|
+
*.pot
|
|
55
|
+
|
|
56
|
+
# Scrapy
|
|
57
|
+
.scrapy
|
|
58
|
+
|
|
59
|
+
# Sphinx documentation
|
|
60
|
+
docs/_build/
|
|
61
|
+
|
|
62
|
+
# PyBuilder
|
|
63
|
+
target/
|
|
64
|
+
|
|
65
|
+
# Jupyter Notebook
|
|
66
|
+
.ipynb_checkpoints
|
|
67
|
+
|
|
68
|
+
# IPython
|
|
69
|
+
profile_default/
|
|
70
|
+
ipython_config.py
|
|
71
|
+
|
|
72
|
+
# pyenv
|
|
73
|
+
.python-version
|
|
74
|
+
|
|
75
|
+
# pipenv
|
|
76
|
+
Pipfile.lock
|
|
77
|
+
|
|
78
|
+
# poetry
|
|
79
|
+
poetry.lock
|
|
80
|
+
|
|
81
|
+
# PDM
|
|
82
|
+
pdm.lock
|
|
83
|
+
.pdm.toml
|
|
84
|
+
|
|
85
|
+
# Hatch
|
|
86
|
+
.hatch/
|
|
87
|
+
|
|
88
|
+
# pyright/mypy
|
|
89
|
+
.mypy_cache/
|
|
90
|
+
.dmypy.json
|
|
91
|
+
dmypy.json
|
|
92
|
+
|
|
93
|
+
# pyre
|
|
94
|
+
.pyre/
|
|
95
|
+
|
|
96
|
+
# pytype
|
|
97
|
+
.pytype/
|
|
98
|
+
|
|
99
|
+
# Caches
|
|
100
|
+
__pypackages__/
|
|
101
|
+
|
|
102
|
+
# Editor/project files
|
|
103
|
+
.DS_Store
|
|
104
|
+
.idea/
|
|
105
|
+
.vscode/
|
|
106
|
+
.zed/
|
|
107
|
+
*.swp
|
|
108
|
+
*.swo
|
|
109
|
+
|
|
110
|
+
# Virtual environments
|
|
111
|
+
.env
|
|
112
|
+
.venv
|
|
113
|
+
.venv.*
|
|
114
|
+
env/
|
|
115
|
+
venv/
|
|
116
|
+
**/.env
|
|
117
|
+
**/.venv
|
|
118
|
+
**/.venv.*
|
|
119
|
+
**/env/
|
|
120
|
+
**/venv/
|
|
121
|
+
ENV/
|
|
122
|
+
env.bak/
|
|
123
|
+
venv.bak/
|
|
124
|
+
|
|
125
|
+
# dotenv anywhere
|
|
126
|
+
**/.env
|
|
127
|
+
**/.env.*
|
|
128
|
+
**/*.env
|
|
129
|
+
|
|
130
|
+
.claude
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Vercel, Inc.
|
|
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,230 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: vercel-workflow
|
|
3
|
+
Version: 0.9.0
|
|
4
|
+
Summary: Python SDK for Vercel Workflows
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Requires-Dist: anyio<5,>=4.0.0
|
|
9
|
+
Requires-Dist: cbor2<7,>=6.0
|
|
10
|
+
Requires-Dist: cryptography>=43.0.0
|
|
11
|
+
Requires-Dist: httpx<1,>=0.27.0
|
|
12
|
+
Requires-Dist: pydantic<3,>=2.7.0
|
|
13
|
+
Requires-Dist: typing-extensions<5,>=4.0.0; python_version < '3.11'
|
|
14
|
+
Requires-Dist: vercel-internal-core<0.2.0,>=0.1.2
|
|
15
|
+
Requires-Dist: vercel-oidc>=0.8.0
|
|
16
|
+
Requires-Dist: vercel-queue>=0.8.0
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
|
|
19
|
+
# Workflow
|
|
20
|
+
|
|
21
|
+
`vercel.workflow` provides Vercel Workflows primitives: `Workflows`, workflow
|
|
22
|
+
registration, step registration, durable sleeps, hooks, and `start`.
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
pip install vercel-workflow
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Basic Workflow
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
from vercel.workflow import Workflows, sleep, start
|
|
32
|
+
|
|
33
|
+
app = Workflows()
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@app.step
|
|
37
|
+
async def charge_customer(customer_id: str) -> None:
|
|
38
|
+
...
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@app.workflow
|
|
42
|
+
async def renew_subscription(customer_id: str) -> None:
|
|
43
|
+
await sleep("1h")
|
|
44
|
+
await charge_customer(customer_id)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
async def main() -> None:
|
|
48
|
+
run = await start(renew_subscription, "cus_123")
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`app.workflow` registers async workflow functions. `app.step` registers async
|
|
52
|
+
steps that can be called only from inside a workflow. `sleep()` creates a
|
|
53
|
+
durable wait in a workflow run.
|
|
54
|
+
|
|
55
|
+
## Queue namespaces
|
|
56
|
+
|
|
57
|
+
Pass a namespace to a workflow registry to isolate its messages on a dedicated
|
|
58
|
+
queue topic:
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
workflows = Workflows(namespace="billing")
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Hooks
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from dataclasses import dataclass
|
|
68
|
+
from vercel.workflow import BaseHook, Workflows
|
|
69
|
+
|
|
70
|
+
app = Workflows()
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@dataclass
|
|
74
|
+
class Approval(BaseHook):
|
|
75
|
+
approved: bool
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@app.workflow
|
|
79
|
+
async def wait_for_approval() -> bool:
|
|
80
|
+
approval = await Approval.wait()
|
|
81
|
+
return bool(approval and approval.approved)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`BaseHook` supports dataclasses and Pydantic models for external resume events.
|
|
85
|
+
|
|
86
|
+
## Streaming
|
|
87
|
+
|
|
88
|
+
Every run has a stream a step can write to while it runs, so a client sees
|
|
89
|
+
progress without waiting for the run to finish:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from vercel.workflow import Workflows, get_writable
|
|
93
|
+
|
|
94
|
+
app = Workflows()
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
@app.step
|
|
98
|
+
async def summarize(*, document: str) -> str:
|
|
99
|
+
writable = get_writable()
|
|
100
|
+
summary = []
|
|
101
|
+
async for token in llm.stream(document):
|
|
102
|
+
await writable.write(token)
|
|
103
|
+
summary.append(token)
|
|
104
|
+
return "".join(summary)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
@app.step
|
|
108
|
+
async def done() -> None:
|
|
109
|
+
await get_writable().close()
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
@app.workflow
|
|
113
|
+
async def analyze(*, document: str) -> str:
|
|
114
|
+
summary = await summarize(document=document)
|
|
115
|
+
await done()
|
|
116
|
+
return summary
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
A workflow body can call `get_writable()` too and pass the result to its steps,
|
|
120
|
+
which take it as a `WorkflowWritable` and write to it:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
@app.step
|
|
124
|
+
async def summarize(*, document: str, out: WorkflowWritable) -> str:
|
|
125
|
+
await out.write("starting")
|
|
126
|
+
...
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
@app.workflow
|
|
130
|
+
async def analyze(*, document: str) -> str:
|
|
131
|
+
out = get_writable()
|
|
132
|
+
return await summarize(document=document, out=out)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Only a step can write. Calling `write()` on what the workflow body holds raises.
|
|
136
|
+
|
|
137
|
+
Chunks are values, not just bytes: anything the payload format carries (see
|
|
138
|
+
below) can be written, and a reader gets it back. A `bytes` chunk arrives on the
|
|
139
|
+
TypeScript side as a `Uint8Array`, so a consumer there can pipe the stream
|
|
140
|
+
straight into a `Response`.
|
|
141
|
+
|
|
142
|
+
Three things are worth knowing:
|
|
143
|
+
|
|
144
|
+
- **Nothing closes a stream for you.** Not the end of a step, not the end of the
|
|
145
|
+
run — the stream spans steps, and a closed stream cannot be reopened. A reader
|
|
146
|
+
of a stream nobody closes waits until the run expires, so close it from the
|
|
147
|
+
last step that has something to say.
|
|
148
|
+
- **A step is not complete until its chunks are.** `write()` returns once the
|
|
149
|
+
chunk is buffered, and the step handler flushes before recording the step, so
|
|
150
|
+
"the step finished" implies "everything it streamed is readable". Call
|
|
151
|
+
`await writable.drain()` if you need that guarantee earlier.
|
|
152
|
+
- **Retries re-stream.** A step that fails halfway has already written what it
|
|
153
|
+
wrote, and the retry writes it again. Keep chunks idempotent, or stream from a
|
|
154
|
+
step you are willing to see repeated.
|
|
155
|
+
|
|
156
|
+
`await writable.write_from(source)` forwards an async iterable in one call, and
|
|
157
|
+
`get_writable(namespace="logs")` gives the run a second, independent stream.
|
|
158
|
+
|
|
159
|
+
`async with get_writable() as writable:` closes the stream on the way out — on
|
|
160
|
+
the clean path only, so a step that raises leaves the stream open for its retry.
|
|
161
|
+
|
|
162
|
+
### Reading it back
|
|
163
|
+
|
|
164
|
+
`run.readable()` yields the values as they are written, and ends when a step
|
|
165
|
+
closes the stream:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
run = await start(analyze, document=text)
|
|
169
|
+
|
|
170
|
+
async for chunk in run.readable():
|
|
171
|
+
print(chunk)
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`run.readable_bytes()` is the same thing narrowed to `bytes`, which is what an
|
|
175
|
+
HTTP body wants — hand it to a streaming response as-is.
|
|
176
|
+
|
|
177
|
+
Pass `start_index` to resume: a positive index picks up exactly where a client
|
|
178
|
+
left off, a negative one reads that many chunks back from the end. Only the
|
|
179
|
+
positive form survives a dropped connection, because a negative index resolves
|
|
180
|
+
against wherever the tail happened to be when it connected.
|
|
181
|
+
|
|
182
|
+
```python
|
|
183
|
+
async for chunk in run.readable(start_index=last_seen + 1):
|
|
184
|
+
...
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
A read reconnects on its own when the transport drops, which it will: the
|
|
188
|
+
server ends a long read at its own time limit. Resuming is exact, so nothing is
|
|
189
|
+
duplicated or skipped.
|
|
190
|
+
|
|
191
|
+
`run.stream_info()` gives the last chunk index and whether the stream is closed
|
|
192
|
+
(`tail_index` is `-1` before anything is written), `run.list_streams()` lists
|
|
193
|
+
every stream the run has, and `read_stream(run_id, name)` reads one by name.
|
|
194
|
+
|
|
195
|
+
The same stream is readable from the TypeScript SDK (`run.readable`), the
|
|
196
|
+
dashboard, and `workflow inspect stream <id> --run=<run-id>`.
|
|
197
|
+
|
|
198
|
+
## Serializing your own types
|
|
199
|
+
|
|
200
|
+
Workflow inputs, step results and hook payloads travel in the devalue format
|
|
201
|
+
`@workflow/core` uses, which carries `datetime`, `bytes`, `set` and repeated
|
|
202
|
+
references natively. `Decimal`, `UUID`, `date`, `time`, `timedelta` and `Path`
|
|
203
|
+
are registered on top of that; anything else needs a registration:
|
|
204
|
+
|
|
205
|
+
```python
|
|
206
|
+
import enum
|
|
207
|
+
|
|
208
|
+
from vercel.workflow import serializable
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
@serializable
|
|
212
|
+
class Point:
|
|
213
|
+
def __init__(self, x: int, y: int) -> None:
|
|
214
|
+
self.x, self.y = x, y
|
|
215
|
+
|
|
216
|
+
def _workflow_serialize(self) -> dict[str, int]:
|
|
217
|
+
return {"x": self.x, "y": self.y}
|
|
218
|
+
|
|
219
|
+
@classmethod
|
|
220
|
+
def _workflow_deserialize(cls, data: dict[str, int]) -> "Point":
|
|
221
|
+
return cls(**data)
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
@serializable # an Enum needs no methods
|
|
225
|
+
class Tier(enum.Enum):
|
|
226
|
+
PRO = "pro"
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
`register_serializable()` is the function form, for classes you cannot
|
|
230
|
+
decorate.
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
`vercel.workflow` provides Vercel Workflows primitives: `Workflows`, workflow
|
|
4
|
+
registration, step registration, durable sleeps, hooks, and `start`.
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
pip install vercel-workflow
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## Basic Workflow
|
|
11
|
+
|
|
12
|
+
```python
|
|
13
|
+
from vercel.workflow import Workflows, sleep, start
|
|
14
|
+
|
|
15
|
+
app = Workflows()
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@app.step
|
|
19
|
+
async def charge_customer(customer_id: str) -> None:
|
|
20
|
+
...
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@app.workflow
|
|
24
|
+
async def renew_subscription(customer_id: str) -> None:
|
|
25
|
+
await sleep("1h")
|
|
26
|
+
await charge_customer(customer_id)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
async def main() -> None:
|
|
30
|
+
run = await start(renew_subscription, "cus_123")
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`app.workflow` registers async workflow functions. `app.step` registers async
|
|
34
|
+
steps that can be called only from inside a workflow. `sleep()` creates a
|
|
35
|
+
durable wait in a workflow run.
|
|
36
|
+
|
|
37
|
+
## Queue namespaces
|
|
38
|
+
|
|
39
|
+
Pass a namespace to a workflow registry to isolate its messages on a dedicated
|
|
40
|
+
queue topic:
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
workflows = Workflows(namespace="billing")
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Hooks
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from dataclasses import dataclass
|
|
50
|
+
from vercel.workflow import BaseHook, Workflows
|
|
51
|
+
|
|
52
|
+
app = Workflows()
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class Approval(BaseHook):
|
|
57
|
+
approved: bool
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
@app.workflow
|
|
61
|
+
async def wait_for_approval() -> bool:
|
|
62
|
+
approval = await Approval.wait()
|
|
63
|
+
return bool(approval and approval.approved)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`BaseHook` supports dataclasses and Pydantic models for external resume events.
|
|
67
|
+
|
|
68
|
+
## Streaming
|
|
69
|
+
|
|
70
|
+
Every run has a stream a step can write to while it runs, so a client sees
|
|
71
|
+
progress without waiting for the run to finish:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
from vercel.workflow import Workflows, get_writable
|
|
75
|
+
|
|
76
|
+
app = Workflows()
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@app.step
|
|
80
|
+
async def summarize(*, document: str) -> str:
|
|
81
|
+
writable = get_writable()
|
|
82
|
+
summary = []
|
|
83
|
+
async for token in llm.stream(document):
|
|
84
|
+
await writable.write(token)
|
|
85
|
+
summary.append(token)
|
|
86
|
+
return "".join(summary)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
@app.step
|
|
90
|
+
async def done() -> None:
|
|
91
|
+
await get_writable().close()
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@app.workflow
|
|
95
|
+
async def analyze(*, document: str) -> str:
|
|
96
|
+
summary = await summarize(document=document)
|
|
97
|
+
await done()
|
|
98
|
+
return summary
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
A workflow body can call `get_writable()` too and pass the result to its steps,
|
|
102
|
+
which take it as a `WorkflowWritable` and write to it:
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
@app.step
|
|
106
|
+
async def summarize(*, document: str, out: WorkflowWritable) -> str:
|
|
107
|
+
await out.write("starting")
|
|
108
|
+
...
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
@app.workflow
|
|
112
|
+
async def analyze(*, document: str) -> str:
|
|
113
|
+
out = get_writable()
|
|
114
|
+
return await summarize(document=document, out=out)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Only a step can write. Calling `write()` on what the workflow body holds raises.
|
|
118
|
+
|
|
119
|
+
Chunks are values, not just bytes: anything the payload format carries (see
|
|
120
|
+
below) can be written, and a reader gets it back. A `bytes` chunk arrives on the
|
|
121
|
+
TypeScript side as a `Uint8Array`, so a consumer there can pipe the stream
|
|
122
|
+
straight into a `Response`.
|
|
123
|
+
|
|
124
|
+
Three things are worth knowing:
|
|
125
|
+
|
|
126
|
+
- **Nothing closes a stream for you.** Not the end of a step, not the end of the
|
|
127
|
+
run — the stream spans steps, and a closed stream cannot be reopened. A reader
|
|
128
|
+
of a stream nobody closes waits until the run expires, so close it from the
|
|
129
|
+
last step that has something to say.
|
|
130
|
+
- **A step is not complete until its chunks are.** `write()` returns once the
|
|
131
|
+
chunk is buffered, and the step handler flushes before recording the step, so
|
|
132
|
+
"the step finished" implies "everything it streamed is readable". Call
|
|
133
|
+
`await writable.drain()` if you need that guarantee earlier.
|
|
134
|
+
- **Retries re-stream.** A step that fails halfway has already written what it
|
|
135
|
+
wrote, and the retry writes it again. Keep chunks idempotent, or stream from a
|
|
136
|
+
step you are willing to see repeated.
|
|
137
|
+
|
|
138
|
+
`await writable.write_from(source)` forwards an async iterable in one call, and
|
|
139
|
+
`get_writable(namespace="logs")` gives the run a second, independent stream.
|
|
140
|
+
|
|
141
|
+
`async with get_writable() as writable:` closes the stream on the way out — on
|
|
142
|
+
the clean path only, so a step that raises leaves the stream open for its retry.
|
|
143
|
+
|
|
144
|
+
### Reading it back
|
|
145
|
+
|
|
146
|
+
`run.readable()` yields the values as they are written, and ends when a step
|
|
147
|
+
closes the stream:
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
run = await start(analyze, document=text)
|
|
151
|
+
|
|
152
|
+
async for chunk in run.readable():
|
|
153
|
+
print(chunk)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`run.readable_bytes()` is the same thing narrowed to `bytes`, which is what an
|
|
157
|
+
HTTP body wants — hand it to a streaming response as-is.
|
|
158
|
+
|
|
159
|
+
Pass `start_index` to resume: a positive index picks up exactly where a client
|
|
160
|
+
left off, a negative one reads that many chunks back from the end. Only the
|
|
161
|
+
positive form survives a dropped connection, because a negative index resolves
|
|
162
|
+
against wherever the tail happened to be when it connected.
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
async for chunk in run.readable(start_index=last_seen + 1):
|
|
166
|
+
...
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
A read reconnects on its own when the transport drops, which it will: the
|
|
170
|
+
server ends a long read at its own time limit. Resuming is exact, so nothing is
|
|
171
|
+
duplicated or skipped.
|
|
172
|
+
|
|
173
|
+
`run.stream_info()` gives the last chunk index and whether the stream is closed
|
|
174
|
+
(`tail_index` is `-1` before anything is written), `run.list_streams()` lists
|
|
175
|
+
every stream the run has, and `read_stream(run_id, name)` reads one by name.
|
|
176
|
+
|
|
177
|
+
The same stream is readable from the TypeScript SDK (`run.readable`), the
|
|
178
|
+
dashboard, and `workflow inspect stream <id> --run=<run-id>`.
|
|
179
|
+
|
|
180
|
+
## Serializing your own types
|
|
181
|
+
|
|
182
|
+
Workflow inputs, step results and hook payloads travel in the devalue format
|
|
183
|
+
`@workflow/core` uses, which carries `datetime`, `bytes`, `set` and repeated
|
|
184
|
+
references natively. `Decimal`, `UUID`, `date`, `time`, `timedelta` and `Path`
|
|
185
|
+
are registered on top of that; anything else needs a registration:
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
import enum
|
|
189
|
+
|
|
190
|
+
from vercel.workflow import serializable
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
@serializable
|
|
194
|
+
class Point:
|
|
195
|
+
def __init__(self, x: int, y: int) -> None:
|
|
196
|
+
self.x, self.y = x, y
|
|
197
|
+
|
|
198
|
+
def _workflow_serialize(self) -> dict[str, int]:
|
|
199
|
+
return {"x": self.x, "y": self.y}
|
|
200
|
+
|
|
201
|
+
@classmethod
|
|
202
|
+
def _workflow_deserialize(cls, data: dict[str, int]) -> "Point":
|
|
203
|
+
return cls(**data)
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
@serializable # an Enum needs no methods
|
|
207
|
+
class Tier(enum.Enum):
|
|
208
|
+
PRO = "pro"
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`register_serializable()` is the function form, for classes you cannot
|
|
212
|
+
decorate.
|