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.
Files changed (33) hide show
  1. vercel_workflow-0.9.0/.gitignore +130 -0
  2. vercel_workflow-0.9.0/LICENSE +21 -0
  3. vercel_workflow-0.9.0/PKG-INFO +230 -0
  4. vercel_workflow-0.9.0/README.md +212 -0
  5. vercel_workflow-0.9.0/_vercel_hatch_build.py +151 -0
  6. vercel_workflow-0.9.0/hatch_build.py +29 -0
  7. vercel_workflow-0.9.0/pyproject.toml +71 -0
  8. vercel_workflow-0.9.0/vercel/workflow/__init__.py +67 -0
  9. vercel_workflow-0.9.0/vercel/workflow/_internal/__init__.py +0 -0
  10. vercel_workflow-0.9.0/vercel/workflow/_internal/core.py +328 -0
  11. vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/__init__.py +21 -0
  12. vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/constants.py +26 -0
  13. vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/parse.py +347 -0
  14. vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/stringify.py +290 -0
  15. vercel_workflow-0.9.0/vercel/workflow/_internal/devalue/utils.py +221 -0
  16. vercel_workflow-0.9.0/vercel/workflow/_internal/encryption.py +250 -0
  17. vercel_workflow-0.9.0/vercel/workflow/_internal/errors.py +5 -0
  18. vercel_workflow-0.9.0/vercel/workflow/_internal/loop.py +43 -0
  19. vercel_workflow-0.9.0/vercel/workflow/_internal/nanoid.py +228 -0
  20. vercel_workflow-0.9.0/vercel/workflow/_internal/py_sandbox.py +986 -0
  21. vercel_workflow-0.9.0/vercel/workflow/_internal/runtime.py +1678 -0
  22. vercel_workflow-0.9.0/vercel/workflow/_internal/serde.py +384 -0
  23. vercel_workflow-0.9.0/vercel/workflow/_internal/serialization.py +240 -0
  24. vercel_workflow-0.9.0/vercel/workflow/_internal/streams.py +620 -0
  25. vercel_workflow-0.9.0/vercel/workflow/_internal/ulid.py +157 -0
  26. vercel_workflow-0.9.0/vercel/workflow/_internal/world.py +1178 -0
  27. vercel_workflow-0.9.0/vercel/workflow/_internal/worlds/__init__.py +0 -0
  28. vercel_workflow-0.9.0/vercel/workflow/_internal/worlds/local.py +1268 -0
  29. vercel_workflow-0.9.0/vercel/workflow/_internal/worlds/vercel.py +859 -0
  30. vercel_workflow-0.9.0/vercel/workflow/errors.py +21 -0
  31. vercel_workflow-0.9.0/vercel/workflow/py.typed +1 -0
  32. vercel_workflow-0.9.0/vercel/workflow/sandbox.py +32 -0
  33. 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.