Add Workflow Streams library

pyproject.toml

@@ -86,6 +86,7 @@ dev = [
   "opentelemetry-exporter-otlp-proto-grpc>=1.11.1,<2",
   "opentelemetry-semantic-conventions>=0.40b0,<1",
   "opentelemetry-sdk-extension-aws>=2.0.0,<3",
+  "async-timeout>=4.0,<6; python_version < '3.11'",
 ]
 
 [tool.poe.tasks]

temporalio/contrib/workflow_streams/README.md

@@ -0,0 +1,33 @@
+# Temporal Workflow Streams
+
+> ⚠️ **This package is currently at an experimental release stage.** ⚠️
+
+**Workflow Streams** is a Temporal Python SDK contrib library that gives a
+Workflow a durable, offset-addressed event channel for keeping outside
+observers updated on the progress of the Workflow and its Activities.
+Typical uses include driving a UI for a long-running AI agent, surfacing
+status during in-flight payment or order processing, and reporting progress
+from data pipelines. It is not designed for ultra-low-latency applications
+such as real-time voice; per-roundtrip latency is around 100ms, and cost
+scales with durable batches rather than tokens.
+
+Under the hood the stream is built directly on Temporal's existing
+message-passing primitives: Signals carry publishes, Updates serve
+long-poll subscriptions, and a Query exposes the current global offset.
+The library packages the boilerplate that turns those primitives into
+a usable stream: batching to amortize per-event overhead, deduplication
+for exactly-once delivery, topic filtering, and continue-as-new helpers
+that hand stream state across Workflow runs.
+
+## Documentation
+
+📖 **The full guide lives in the Temporal documentation site:**
+**[Workflow Streams — Python SDK](https://docs.temporal.io/develop/python/libraries/workflow-streams)**
+
+It covers installation, enabling streaming on a Workflow, publishing from
+Workflows and Activities, subscribing, continue-as-new, delivery semantics,
+codec and payload encoding, architecture, and caveats — with runnable code
+snippets throughout.
+
+For runnable end-to-end examples, see the
+[Workflow Streams samples](https://github.com/temporalio/samples-python/tree/main/workflow-streams).

temporalio/contrib/workflow_streams/__init__.py

@@ -0,0 +1,43 @@
+"""Workflow Streams for Temporal workflows.
+
+.. warning::
+    This package is experimental and may change in future versions.
+
+The Workflow Streams contrib library gives a workflow a durable,
+offset-addressed event channel built from Signals and polling Updates
+with an SSE bridge. Cost scales with durable batches, not tokens.
+Latency is around 100ms per roundtrip; not for ultra-low-latency voice.
+
+See :py:class:`WorkflowStream` for the workflow-side stream object and
+:py:class:`WorkflowStreamClient` for the external client interface.
+"""
+
+from temporalio.contrib.workflow_streams._client import WorkflowStreamClient
+from temporalio.contrib.workflow_streams._stream import WorkflowStream
+from temporalio.contrib.workflow_streams._topic_handle import (
+    TopicHandle,
+    WorkflowTopicHandle,
+)
+from temporalio.contrib.workflow_streams._types import (
+    PollInput,
+    PollResult,
+    PublishEntry,
+    PublisherState,
+    PublishInput,
+    WorkflowStreamItem,
+    WorkflowStreamState,
+)
+
+__all__ = [
+    "PollInput",
+    "PollResult",
+    "PublishEntry",
+    "PublishInput",
+    "PublisherState",
+    "TopicHandle",
+    "WorkflowStream",
+    "WorkflowStreamClient",
+    "WorkflowStreamItem",
+    "WorkflowStreamState",
+    "WorkflowTopicHandle",
+]