Skip to content

Added the stream examples, one per path and one composed. - #112

Open
moetemp wants to merge 3 commits into
moe/AI-198-s1-py-22-eviction-settlefrom
moe/AI-198-s1-py-23-examples
Open

moetemp wants to merge 3 commits into
moe/AI-198-s1-py-22-eviction-settlefrom
moe/AI-198-s1-py-23-examples

Conversation

@moetemp

@moetemp moetemp commented Oct 6, 2026

Copy link
Copy Markdown
Owner

This PR adds the stream examples, one per path, one composed agent, and the June scenarios.

What changed?

Two commits: the paths and the agent first, then the June scenarios.

  • examples/streams/path_a_publish.py: a workflow publishes progress and a backend follows it from latest().
  • path_b_produce.py: an Activity appends to its workflow's topic, a backend produces and consumes, and the consumer handles a supersession when the first attempt fails.
  • path_c_consume.py: a workflow consumes a topic fed from outside and runs an Activity per record with the cache off. On Redis, the outside append wakes the parked workflow with the reserved Signal.
  • agent.py and run.py compose the three on workflow_streams and redis, and behind the Nexus front with workflow_streams, memory or redis behind it. The agent races its reader against the generator, so an exhausted generator fails the run. There's no plain memory mode, since memory isn't replay-safe.
  • examples/streams/june_scenarios/ has one demo per scenario in Roey's June notes. Each file opens with the notes' heading, a status and why. run.py runs them all on one provider.
  • s2 runs the three standalone alternatives on the handle, alt 3 with a StreamRef passed into the workflow start. s8 (b) returns a StreamRef from a Nexus operation.
  • README.md maps each path to its call. _setup.py is the one place a store is named, and every example defines its topics once with streams.topic().
  • Outside examples/: a changelog line, and examples under the type checker in pyproject.toml.

Part of AI-198 (epic AI-37).

Why?

It puts the portability claim in code a reviewer can run, with the same accessor in every context. The June suite answers Roey's scenarios one by one. It says plainly which are implemented, which are emulated and which are unsupported by design. It sits on the top of the series, since it needs every provider at once.

The earlier version also ran on the native server-side provider. Native streams pause with the notification channel per the 2026-10-05 design review, so the native setup and its usage lines come back in phase 2, and the prose here speaks only of the providers this series ships.

How did you test it?

Link to a test plan if any -

  • Unit Tests
  • Staging
  • End to End Tests

The lint set is clean with examples/ under the type checker. On a stock dev server with a local Redis, run.py exits 0 on workflow_streams and redis, and run.py nexus exits 0 through an endpoint on that server with workflow_streams, memory and redis behind it. The three path examples exit 0 on workflow_streams and redis. The June suite exits 0 on workflow_streams, memory and redis. A provider that can't serve a scenario says so: s2 and s5 (b) and (c) on workflow_streams, s1 (d) off memory, and s7 on memory. The worker and consumer that die in s6 and s8 do so on purpose.

Each example takes the provider's name, and _setup.py is the one place a store is named. run.py composes the three paths in one agent, also behind the Nexus front.
One file per scenario family, each with a status. A scenario a provider cannot serve says so and the next one starts clean.
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