Skip to content

Commit e237cb7

Browse files
committed
Added the Stream examples and the end-to-end Redis tests.
The examples run on the memory and Redis lanes, as the tests do. The `temporalio.common` module doc and the changelog describe Streams.
1 parent 0c7ec5b commit e237cb7

13 files changed

Lines changed: 1355 additions & 3 deletions

File tree

‎.github/CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,5 @@
1212
# manage repo-wide concerns.
1313
/temporalio/contrib/workflow_streams/ @temporalio/ai-sdk @temporalio/sdk
1414
/tests/contrib/workflow_streams/ @temporalio/ai-sdk @temporalio/sdk
15+
/temporalio/contrib/stream/ @temporalio/ai-sdk @temporalio/sdk
16+
/tests/contrib/streams/ @temporalio/ai-sdk @temporalio/sdk

‎changelog/added/babbling-brook.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Add experimental Streams to `temporalio.common`. A Stream is an ordered log of Records that Workflows, Activities and clients write, and that clients and Activities read. Register a backend with `stream_backends=` on `Client.connect`, `Replayer` or `WorkflowEnvironment`, then use `workflow.create_stream`, `Client.create_stream` or `Client.stream`.
2+
Add a Redis Stream backend in `temporalio.contrib.stream`, and an in-memory one for tests in `temporalio.contrib.stream.testing`. The Redis backend needs a build with the bridge's `streams` feature, which the official builds have.

‎temporalio/common/__init__.py‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,25 @@
1-
"""Common code used in the Temporal SDK."""
1+
"""Common code used in the Temporal SDK.
2+
3+
This module also has the Streams API. A Stream is an ordered log of Records that Workflows,
4+
Activities and clients write and read. A Stream definition is a subclass of
5+
:py:class:`StreamDefinition` with ``@common.defn``. It gives the Stream name and its one payload
6+
type. Code creates a Stream before its first publish, and a create is create-or-get. Workflow
7+
code creates one with :py:func:`temporalio.workflow.create_stream`, and a client with
8+
:py:meth:`temporalio.client.Client.create_stream`. A client binds any Stream with
9+
:py:meth:`temporalio.client.Client.stream`. A Stream is data. A Workflow can pass it as an
10+
argument to an Activity, a child Workflow or the next run, or hand it out through a query. The
11+
parameter's type sets the handle class for that context, such as :py:class:`ActivityStream`.
12+
13+
A :py:class:`StreamBackend` makes the Stream calls and registers a backend name. Examples are
14+
:py:class:`temporalio.contrib.stream.RedisStreamBackend` (``redis``) and
15+
:py:class:`temporalio.contrib.stream.testing.MemoryStreamBackend` (``memory``). Register
16+
backends with ``Client.connect(..., stream_backends=[...])``. A handle stores the name of its
17+
backend. With more than one registered backend, exactly one must have ``default=True``. A
18+
create with no ``backend=`` uses that backend. A Worker serves only one backend.
19+
20+
.. warning::
21+
The Streams API is experimental.
22+
"""
223

324
from __future__ import annotations
425

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Examples for the Brook streams API proposal
2+
3+
Each file is a complete program for one section of the proposal. `test_examples.py` runs each one
4+
end to end on the memory Store and on Redis.
5+
6+
| Proposal section | File |
7+
|---|---|
8+
| A UI backend reads a Workflow's Stream | [`ui_backend_reads.py`](ui_backend_reads.py) |
9+
| A client resumes a Stream from an offset | [`resume_from_offset.py`](resume_from_offset.py) |
10+
| A client creates a Stream and passes it to a Workflow | [`client_creates_stream.py`](client_creates_stream.py) |
11+
| An agent Workflow publishes its turns | [`agent_publishes_turns.py`](agent_publishes_turns.py) |
12+
| An Activity streams tokens to the Workflow's Stream | [`activity_streams_tokens.py`](activity_streams_tokens.py) |
13+
| Worker setup | [`worker_setup.py`](worker_setup.py) |
14+
15+
The proposal's Nexus examples aren't in this directory.

‎tests/contrib/streams/examples/__init__.py‎

Whitespace-only changes.
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
"""Brook API proposal, "An Activity streams tokens to the Workflow's Stream".
2+
3+
An async Activity publishes each token with an awaited ``publish``, which returns the offset,
4+
and batches the rest with ``BufferedPublisher``. A sync Activity takes ``SyncActivityStream``,
5+
which works in a thread pool executor.
6+
"""
7+
8+
from __future__ import annotations
9+
10+
import concurrent.futures
11+
import uuid
12+
from dataclasses import dataclass
13+
from datetime import timedelta
14+
15+
from temporalio import activity, common, workflow
16+
from temporalio.client import Client
17+
from temporalio.worker import Worker
18+
19+
20+
@common.defn(name="tokens")
21+
class Tokens(common.StreamDefinition[str]): ...
22+
23+
24+
@dataclass
25+
class CallModelInput:
26+
prompt: str
27+
tokens: common.ActivityStream[str] # the Stream that the Workflow passes
28+
29+
30+
@dataclass
31+
class SummarizeInput:
32+
text: str
33+
tokens: common.SyncActivityStream[str]
34+
35+
36+
@activity.defn
37+
async def call_model(input: CallModelInput) -> int:
38+
words = input.prompt.split()
39+
# Each awaited publish has written its Record when it returns.
40+
last = await input.tokens.publish(words[0])
41+
# A fast model sends many small tokens, so the helper batches them.
42+
async with common.BufferedPublisher(
43+
input.tokens, max_delay=timedelta(milliseconds=100)
44+
) as fast:
45+
for word in words[1:]:
46+
fast.publish(word)
47+
return last
48+
49+
50+
@activity.defn
51+
def summarize(input: SummarizeInput) -> int:
52+
return input.tokens.publish(f"summary: {input.text}")
53+
54+
55+
@workflow.defn
56+
class Model:
57+
@workflow.query
58+
def stream(self) -> common.WorkflowStream[str]:
59+
return workflow.stream_handle(Tokens)
60+
61+
@workflow.run
62+
async def run(self, prompt: str) -> list[int]:
63+
tokens = await workflow.create_stream(Tokens)
64+
first = await workflow.execute_activity(
65+
call_model,
66+
CallModelInput(prompt, common.ActivityStream.from_handle(tokens)),
67+
start_to_close_timeout=timedelta(minutes=5),
68+
)
69+
summary = await workflow.execute_activity(
70+
summarize,
71+
SummarizeInput(prompt, common.SyncActivityStream.from_handle(tokens)),
72+
start_to_close_timeout=timedelta(minutes=5),
73+
)
74+
await tokens.close()
75+
return [first, summary]
76+
77+
78+
async def main(
79+
client: Client, task_queue: str
80+
) -> tuple[list[int], list[common.Record[str]]]:
81+
with concurrent.futures.ThreadPoolExecutor() as executor:
82+
async with Worker(
83+
client,
84+
task_queue=task_queue,
85+
workflows=[Model],
86+
activities=[call_model, summarize],
87+
activity_executor=executor,
88+
):
89+
handle = await client.start_workflow(
90+
Model.run,
91+
"one two three",
92+
id=f"model-{uuid.uuid4()}",
93+
task_queue=task_queue,
94+
)
95+
offsets = await handle.result()
96+
stream = await handle.query("stream", result_type=common.ClientStream[str])
97+
records = [r async for r in stream.subscribe() if isinstance(r, common.Record)]
98+
return offsets, records
Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
"""Brook API proposal, "An agent Workflow publishes its turns".
2+
3+
The Workflow creates its two Streams, turns and token deltas, and hands out the turns Stream
4+
through a ``stream`` query. It publishes each turn with an awaited ``publish``, and passes the
5+
tokens Stream to the model Activity in its one input object. A create is create-or-get, so the
6+
run after continue-as-new gets the same Streams. It closes both Streams before it returns, since
7+
a run's end doesn't close a Stream.
8+
"""
9+
10+
from __future__ import annotations
11+
12+
import uuid
13+
from dataclasses import dataclass, field
14+
from datetime import timedelta
15+
16+
from temporalio import activity, common, workflow
17+
from temporalio.client import Client
18+
from temporalio.worker import Worker
19+
20+
21+
@dataclass
22+
class Turn:
23+
kind: str
24+
text: str = ""
25+
26+
27+
@common.defn(name="turns")
28+
class Turns(common.StreamDefinition[Turn]): ...
29+
30+
31+
@common.defn(name="tokens")
32+
class Tokens(common.StreamDefinition[str]): ...
33+
34+
35+
@dataclass
36+
class Reply:
37+
text: str
38+
tool_calls: list[str] = field(default_factory=list)
39+
40+
41+
@dataclass
42+
class CallModelInput:
43+
messages: list[str]
44+
tokens: common.ActivityStream[str]
45+
46+
47+
@activity.defn
48+
async def call_model(input: CallModelInput) -> Reply:
49+
await input.tokens.publish(*input.messages[-1].split())
50+
if len(input.messages) == 1:
51+
return Reply("", tool_calls=["search"])
52+
return Reply("the answer")
53+
54+
55+
@activity.defn
56+
async def run_tool(call: str) -> str:
57+
return f"{call} result"
58+
59+
60+
@workflow.defn
61+
class Agent:
62+
@workflow.query
63+
def stream(self) -> common.WorkflowStream[Turn]:
64+
# The handle makes no call, so a reader can get it before the create.
65+
return workflow.stream_handle(Turns)
66+
67+
@workflow.run
68+
async def run(self, messages: list[str]) -> str:
69+
# Create-or-get, so a retry or the run after continue-as-new gets the same Streams.
70+
turns = await workflow.create_stream(Turns, retention=timedelta(days=1))
71+
tokens = await workflow.create_stream(Tokens, retention=timedelta(days=1))
72+
while True:
73+
if workflow.info().is_continue_as_new_suggested():
74+
workflow.continue_as_new(messages)
75+
# The publish is one Local Activity. History keeps its offset, not the Turn.
76+
await turns.publish(Turn("model"))
77+
reply = await workflow.execute_activity(
78+
call_model,
79+
CallModelInput(messages, common.ActivityStream.from_handle(tokens)),
80+
start_to_close_timeout=timedelta(minutes=5),
81+
)
82+
if not reply.tool_calls:
83+
await turns.publish(Turn("done", reply.text))
84+
# A run's end doesn't close the Streams, so the Workflow closes them.
85+
await turns.close(result=reply.text)
86+
await tokens.close()
87+
return reply.text
88+
for call in reply.tool_calls:
89+
messages.append(
90+
await workflow.execute_activity(
91+
run_tool, call, start_to_close_timeout=timedelta(minutes=5)
92+
)
93+
)
94+
95+
96+
async def main(client: Client, task_queue: str) -> list[common.Record | common.Closed]:
97+
async with Worker(
98+
client,
99+
task_queue=task_queue,
100+
workflows=[Agent],
101+
activities=[call_model, run_tool],
102+
):
103+
handle = await client.start_workflow(
104+
Agent.run,
105+
["find it"],
106+
id=f"agent-{uuid.uuid4()}",
107+
task_queue=task_queue,
108+
)
109+
await handle.result()
110+
# The Workflow hands out its turns Stream, and the client reads it as a ClientStream.
111+
stream = await handle.query("stream", result_type=common.ClientStream[Turn])
112+
return [
113+
item
114+
async for item in stream.subscribe()
115+
if isinstance(item, (common.Record, common.Closed))
116+
]
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
"""Brook API proposal, "A client creates a Stream and passes it to a Workflow".
2+
3+
The client creates the Stream with its settings, passes it to the Workflow as data, reads it,
4+
and closes it, since the creator owns it. A create is create-or-get by Stream id.
5+
"""
6+
7+
from __future__ import annotations
8+
9+
import uuid
10+
from dataclasses import dataclass
11+
from datetime import timedelta
12+
13+
from temporalio import common, workflow
14+
from temporalio.client import Client
15+
from temporalio.worker import Worker
16+
17+
18+
@dataclass
19+
class Turn:
20+
kind: str
21+
text: str = ""
22+
23+
24+
@common.defn(name="turns")
25+
class Turns(common.StreamDefinition[Turn]): ...
26+
27+
28+
@workflow.defn
29+
class Chat:
30+
@workflow.run
31+
async def run(self, stream: common.WorkflowStream[Turn]) -> None:
32+
# The Workflow only writes. The client closes the Stream.
33+
await stream.publish(Turn("model", "hi"), Turn("last", "bye"))
34+
35+
36+
async def main(client: Client, task_queue: str) -> list[Turn]:
37+
async with Worker(client, task_queue=task_queue, workflows=[Chat]):
38+
turns = []
39+
# The block closes the Stream at its end, or with the error that ends it.
40+
async with client.create_stream(
41+
Turns, id=f"chat-{uuid.uuid4()}", retention=timedelta(days=1)
42+
) as stream:
43+
await client.start_workflow(
44+
Chat.run,
45+
# A Stream is data, so the Workflow gets it as an argument.
46+
common.WorkflowStream.from_handle(stream),
47+
id=f"chat-{uuid.uuid4()}",
48+
task_queue=task_queue,
49+
)
50+
async for r in stream.subscribe():
51+
if not isinstance(r, common.Record):
52+
continue
53+
turns.append(r.data)
54+
if r.data.kind == "last":
55+
break
56+
return turns

0 commit comments

Comments
 (0)