Skip to content

feat: add the Streams API for Activity and client code - #2129

Draft
moetemp wants to merge 24 commits into
moe/streams-generated-codefrom
moe/streams-api
Draft

moetemp wants to merge 24 commits into
moe/streams-generated-codefrom
moe/streams-api

Conversation

@moetemp

@moetemp moetemp commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

What changed?

This PR adds the Streams API to the Python SDK, for Activity and client code. It's experimental.

A Stream is an ordered log of Records, for example the tokens of a model call. An Activity or a client writes it, and any of them reads it.

from temporalio_streams_redis import RedisStreamStore

store = RedisStreamStore("redis://localhost:6379")
client = await Client.connect("localhost:7233", stream_config=StreamConfig(stores=[store]))

stream = await client.create_stream(id="chat-43", body_type=str)
await stream.append("Hello", " world")
async for record in stream.read():
    print(record.body)
await stream.close()

The public API is the code that nexgen generates from the Stream WIT, which is in #2128. This PR is the hand-written part.

  • Stores. StreamConfig gives a client its Stores, in the shape of ExternalStorage, and a Worker uses the config of its client. A Store is a Python class with the five operations, StreamStore. The SDK has no Store of its own, and its bridge has no Stream code. A Store gives the limits of one batch as StreamStore.limits, at most 1,000 Records and 4 MiB. RedisStreamStore and a MemoryStreamStore for tests are packages with their own native modules, in feat: add the Python packages of the Redis Store and the memory Store temporal-community/sdk-streams#10.
  • Fencing. An Activity writes as its attempt, so the Store refuses the late writes of an older attempt (feat: add the dispatching Workflow Task to activity.Info for a Local Activity #2127). append takes an optional sequence, so a retried batch is written once.
  • A stored Producer. current_producer() gives the Producer of the calling code. An Activity that goes on from its heartbeat details stores it and passes it to append, so its retry keeps the epoch of its first attempt.
  • Batching. BufferedAppender collects appends into one write. Its max_batch_records cuts the batches for a Store that allows fewer Records.
  • Workflow code can't call a Stream in this PR. A call fails the Workflow Task with a message that says so. The Workflow part is feat: let Workflow code read, append to and close a Stream, through Core #2132.

It depends on two things that have no release yet.

Why?

An agent application shows partial output, such as the tokens of a model call, while the work still runs. Workflow History isn't the place for that data, so a Stream keeps its Records in a Store outside History.

How did you test it?

The tests are in tests/nexus/test_stream_store*.py and tests/contrib/streams/. They run on a Store that is written in Python, DictStreamStore in tests/helpers/streams.py. The tests of the Redis Store moved to its package.

Link to a test plan if any -

  • Unit Tests
  • Staging
  • End to End Tests

@moetemp
moetemp added this pull request to stack #2130 November 14, 2026 01:00
@moetemp
moetemp removed this pull request from stack #2130 November 15, 2026 08:27
@moetemp moetemp changed the title feat: add the Streams API, with Stream Stores on Redis and in memory feat: add the Streams API for Activity and client code, with Stores on Redis and in memory Nov 17, 2026
@moetemp
moetemp added this pull request to stack #2139 November 18, 2026 01:19
A client takes its Stream Stores in a `StreamConfig`, and each call of the generated Streams
API goes to one of them. The Stores run Core's Stream runtime through the bridge.
The Stream WIT now gives the Workflow target `append` and `close`, and keeps `read` out of it.
The Workflow `Stream` has `append` again, and Workflow code can't do I/O. The Local Activity writes as its own Producer with a fixed attempt, so a retry in one Workflow Task writes once.
A Local Activity reaches the Store before its Workflow Task completes, so a failed task would leave a closed Stream. A Worker with Stream Stores now polls for Activity Tasks, so it can run the close.
A create can name its Store with `store=`, so a config with several Stores needs no selector.
A call that names no Store on such a config raises `StreamConfigError` at the call.
A failed Workflow Task retries for good, and a Worker with no Stream config never recovers.
Workflow code now gets a non-retryable `ApplicationError`, so a user sees the failed Workflow.
A timer of the Workflow event loop goes into History, so in Workflow code the appender starts
its write at the next yield instead. The appends of one activation become one Local Activity.
The public Streams API is the generated code. A helper on top of it is a library,
so it belongs in contrib.
The other contrib packages have one, and the appender's rules for Workflow code need a place.
A design review decided that Workflow code needs no Activity Task Queue for a Stream.
A Worker with Workflows and Stream Stores polls for Activity Tasks only for its own Activities.
The docs state that a failed Workflow Task after a close leaves the Stream closed.
Code can keep the Producer of its attempt and pass it to a later append with `producer=`.
The tests cover each kind of Producer as an Activity argument and an Activity result.
Heartbeat details decode with no type hint, so a stored Producer comes back as its proto message.
`as_producer` gives the `Producer` back, so an Activity's retry can append as its first attempt.
The API docs have two classes called Producer, so the short link had no target in `gen-docs`.
The Stream crate lets a Workflow Producer append with its Workflow Task as the epoch.
Both crates call the option `producer_idle_ttl`, since it counts from any Producer's last write.
The Store keeps one Producer state for a run, so it fences a late write of a failed Workflow Task.
A Workflow's appends and close on one Stream run one at a time, so their sequences go up in order.
The expired reason of a Stream said the old name of the Store option.
The first release step gives Streams to Activity and client code only. A Stream call of
Workflow code fails its Workflow Task with one message, and the Store gets no call.
The changelog lists only what this step ships.
The regenerated Stream terminal calls `_schedule_system_nexus_operation`, as upstream nexgen does.
An interceptor of Workflow code then sees a Stream operation only in its operation-specific method.
A loop over Records uses `read`, a loop over pages uses `read_pages`, and one request uses
`read_page`. The Stream package is generated from commit 07b565b6 of the nexgen fork.
The Store is now the `temporalio-streams-redis` package, so the bridge has no code for one Store
only. A user's Store has the same path as this one.
The next commit removes the memory Store from the SDK. `DictStreamStore` now has the three
behaviors that the tests took from it. These are the resend of a batch, the fence of an older
epoch and the wait of a read.
The memory Store moves to the `temporalio-streams-memory` package. The bridge has no Stream code
left, so a Store is any subclass of `StreamStore`. Core keeps only the protos and the WIT that the
generated code needs.
@moetemp moetemp changed the title feat: add the Streams API for Activity and client code, with Stores on Redis and in memory feat: add the Streams API for Activity and client code Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant