dex-python-sdk 0.2.6__tar.gz → 0.2.8__tar.gz

{dex_python_sdk-0.2.6 → dex_python_sdk-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dex-python-sdk
-Version: 0.2.6
+Version: 0.2.8
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: grpcio-status>=1.83.0
 Requires-Dist: protobuf>=7.35.1
@@ -173,11 +173,30 @@ Worker output queue:
 async def execute(
     self, context: dex.AsyncContext, input: str
 ) -> dex.StepDecision:
-    progress.write(context, "started")
+    writer = progress.buffered_text(context)
+    writer.write("started")
     await context.heartbeat({"offset": 10})
     return dex.graceful_complete(input)
 ```
 
+The async buffered writer has a synchronous `write` method, so `writer.write`
+can be passed directly as an LLM delta callback. It flushes after one second, at
+a soft 16 KiB UTF-8 threshold, or before the final result or error. It
+concatenates chunks exactly and ignores empty chunks.
+
+A synchronous generator uses the cooperative form because only yielded
+`StepOutput` values can reach gRPC:
+
+```python
+writer = progress.buffered_text(context)
+yield from writer.write(delta)
+yield from writer.flush()
+```
+
+Its interval is checked by the next write, and the handler must explicitly
+flush the tail. Retry does not restore either writer's unsent buffer or
+deduplicate sent batches.
+
 Call `heartbeat()` or `await context.heartbeat()` without a value to clear previous
 details. Passing Python `None` persists a present null Value. On a later regular
 attempt, use `context.has_last_heartbeat_value()` before decoding with

{dex_python_sdk-0.2.6 → dex_python_sdk-0.2.8}/README.md

@@ -157,11 +157,30 @@ Worker output queue:
 async def execute(
     self, context: dex.AsyncContext, input: str
 ) -> dex.StepDecision:
-    progress.write(context, "started")
+    writer = progress.buffered_text(context)
+    writer.write("started")
     await context.heartbeat({"offset": 10})
     return dex.graceful_complete(input)
 ```
 
+The async buffered writer has a synchronous `write` method, so `writer.write`
+can be passed directly as an LLM delta callback. It flushes after one second, at
+a soft 16 KiB UTF-8 threshold, or before the final result or error. It
+concatenates chunks exactly and ignores empty chunks.
+
+A synchronous generator uses the cooperative form because only yielded
+`StepOutput` values can reach gRPC:
+
+```python
+writer = progress.buffered_text(context)
+yield from writer.write(delta)
+yield from writer.flush()
+```
+
+Its interval is checked by the next write, and the handler must explicitly
+flush the tail. Retry does not restore either writer's unsent buffer or
+deduplicate sent batches.
+
 Call `heartbeat()` or `await context.heartbeat()` without a value to clear previous
 details. Passing Python `None` persists a present null Value. On a later regular
 attempt, use `context.has_last_heartbeat_value()` before decoding with

{dex_python_sdk-0.2.6 → dex_python_sdk-0.2.8}/dex/__init__.py

@@ -92,7 +92,12 @@ from dex.step import (
     heartbeat,
 )
 from dex.step_execution import StepExecutionId, TimerId
-from dex.stream import Stream, StreamMessage
+from dex.stream import (
+    AsyncBufferedTextStream,
+    BufferedTextStream,
+    Stream,
+    StreamMessage,
+)
 from dex.subflow import SubFlow
 from dex.timer import Timer
 from dex.wait import Wait
@@ -112,9 +117,11 @@ __all__ = [
     "AttributeMap",
     "AsyncContext",
     "AsyncClient",
+    "AsyncBufferedTextStream",
     "AsyncWorker",
     "BlobCache",
     "BlobCacheConfig",
+    "BufferedTextStream",
     "Channel",
     "ChannelMap",
     "Client",

{dex_python_sdk-0.2.6 → dex_python_sdk-0.2.8}/dex/_async_worker_dispatcher.py

@@ -29,6 +29,7 @@ class _AsyncStepOutputEmitter:
     def __init__(self) -> None:
         self.queue: asyncio.Queue[StepOutput] = asyncio.Queue()
         self._is_closed = False
+        self._close_callbacks: list[Callable[[], None]] = []
 
     def emit_nowait(self, output: StepOutput) -> None:
         if self._is_closed:
@@ -44,7 +45,17 @@ class _AsyncStepOutputEmitter:
             raise asyncio.CancelledError
 
     def close(self) -> None:
+        if self._is_closed:
+            return
         self._is_closed = True
+        for callback in self._close_callbacks:
+            callback()
+
+    def add_close_callback(self, callback: Callable[[], None]) -> None:
+        if self._is_closed:
+            callback()
+            return
+        self._close_callbacks.append(callback)
 
 
 class AsyncWorkerDispatcher(WorkerDispatcher):
@@ -93,18 +104,21 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
             output_emitter=emitter,
         )
         input = self._values.decode(request.step_input, step.input_codec)
-        wait = step.step.wait_for(context, input)
-        if isgenerator(wait):
-            wait.close()
-            raise InvalidStepResultError(
-                flow.name,
-                step.name,
-                "wait_for",
-                "synchronous generators require Worker",
-            )
-        if isawaitable(wait):
-            wait = await wait
+        response: pb.InvokeWaitForMethodResponse | None = None
+        failure: BaseException | None = None
+        cause: BaseException | None = None
         try:
+            wait = step.step.wait_for(context, input)
+            if isgenerator(wait):
+                wait.close()
+                raise InvalidStepResultError(
+                    flow.name,
+                    step.name,
+                    "wait_for",
+                    "synchronous generators require Worker",
+                )
+            if isawaitable(wait):
+                wait = await wait
             if not isinstance(wait, Wait):
                 raise TypeError("wait_for must return Wait")
             response = pb.InvokeWaitForMethodResponse(
@@ -116,11 +130,22 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
             waiting = self._map_wait(flow, wait)
             if waiting is not None:
                 response.waiting_condition.CopyFrom(waiting)
-            return response
+        except InvalidStepResultError as error:
+            failure = error
         except (TypeError, ValueError) as error:
-            raise InvalidStepResultError(
+            failure = InvalidStepResultError(
                 flow.name, step.name, "wait_for", str(error)
-            ) from error
+            )
+            cause = error
+        except BaseException as error:
+            failure = error
+        combined = context._finalize_step_outputs(failure)
+        if combined is not None:
+            if cause is not None:
+                raise combined from cause
+            raise combined
+        assert response is not None
+        return response
 
     async def invoke_execute(  # type: ignore[override]
         self,
@@ -166,31 +191,46 @@ class AsyncWorkerDispatcher(WorkerDispatcher):
             output_emitter=emitter,
         )
         input = self._values.decode(request.step_input, step.input_codec)
-        decision: Any = step.step.execute(context, input)
-        if isgenerator(decision):
-            decision.close()
-            raise InvalidStepResultError(
-                flow.name,
-                step.name,
-                "execute",
-                "synchronous generators require Worker",
-            )
-        if isawaitable(decision):
-            decision = await decision
+        response: pb.InvokeExecuteMethodResponse | None = None
+        failure: BaseException | None = None
+        cause: BaseException | None = None
         try:
+            decision: Any = step.step.execute(context, input)
+            if isgenerator(decision):
+                decision.close()
+                raise InvalidStepResultError(
+                    flow.name,
+                    step.name,
+                    "execute",
+                    "synchronous generators require Worker",
+                )
+            if isawaitable(decision):
+                decision = await decision
             if not isinstance(decision, StepDecision):
                 raise TypeError("execute must return StepDecision")
-            return pb.InvokeExecuteMethodResponse(
+            response = pb.InvokeExecuteMethodResponse(
                 step_decision=self._map_decision(flow, decision),
                 upsert_attributes=list(context.attribute_writes.values()),
                 record_events=context.events,
                 upsert_step_exe_locals=list(context.local_writes.values()),
                 publish_to_channel=context.publications,
             )
+        except InvalidStepResultError as error:
+            failure = error
         except (TypeError, ValueError) as error:
-            raise InvalidStepResultError(
+            failure = InvalidStepResultError(
                 flow.name, step.name, "execute", str(error)
-            ) from error
+            )
+            cause = error
+        except BaseException as error:
+            failure = error
+        combined = context._finalize_step_outputs(failure)
+        if combined is not None:
+            if cause is not None:
+                raise combined from cause
+            raise combined
+        assert response is not None
+        return response
 
     async def _invoke_timeout_handler_async(
         self,

{dex_python_sdk-0.2.6 → dex_python_sdk-0.2.8}/dex/_invocation_context.py

@@ -46,6 +46,14 @@ class _StepOutputEmitter(Protocol):
 
     async def emit(self, output: StepOutput) -> None: ...
 
+    def add_close_callback(self, callback: Callable[[], None]) -> None: ...
+
+
+class _StepOutputFinalizer(Protocol):
+    def _finalize_step_output(self) -> None: ...
+
+    def _cancel_step_output(self) -> None: ...
+
 
 class InvocationContext:
     def __init__(
@@ -76,6 +84,8 @@ class InvocationContext:
         self.events: list[pb.KV] = []
         self.publications: list[pb.ChannelMessage] = []
         self._event_names: set[str] = set()
+        self._step_output_finalizers: list[_StepOutputFinalizer] = []
+        self._step_outputs_finalized = False
 
     @property
     def flow_id(self) -> str:
@@ -221,6 +231,44 @@ class InvocationContext:
         self._output_emitter.emit_nowait(output)
         return None
 
+    def _prepare_buffered_stream(self, definition: Stream[object]) -> bool:
+        if self._method not in (InvocationMethod.WAIT_FOR, InvocationMethod.EXECUTE):
+            raise ValueError("Buffered Streams require a Step Context")
+        self._require_registered(definition)
+        return self._output_emitter is not None
+
+    def _register_step_output_finalizer(
+        self,
+        finalizer: _StepOutputFinalizer,
+    ) -> None:
+        if self._step_outputs_finalized or self._output_emitter is None:
+            raise ValueError(
+                "Buffered Stream finalizers require an active async Step Context"
+            )
+        self._step_output_finalizers.append(finalizer)
+        self._output_emitter.add_close_callback(finalizer._cancel_step_output)
+
+    def _finalize_step_outputs(
+        self,
+        failure: BaseException | None = None,
+    ) -> BaseException | None:
+        if self._step_outputs_finalized:
+            return failure
+        self._step_outputs_finalized = True
+        failures: list[BaseException] = [] if failure is None else [failure]
+        for finalizer in self._step_output_finalizers:
+            try:
+                finalizer._finalize_step_output()
+            except BaseException as error:
+                failures.append(error)
+        if not failures:
+            return None
+        if len(failures) == 1:
+            return failures[0]
+        return BaseExceptionGroup(
+            "Step handler and buffered Stream finalization failed", failures
+        )
+
     def _get_attribute(
         self,
         definition: Attribute[ValueT] | AttributeMap[ValueT],

{dex_python_sdk-0.2.6 → dex_python_sdk-0.2.8}/dex/context.py

@@ -18,6 +18,12 @@ if TYPE_CHECKING:
     from dex.step import StepOutput
     from dex.stream import Stream
 
+    class _StepOutputFinalizer(Protocol):
+        def _finalize_step_output(self) -> None: ...
+
+        def _cancel_step_output(self) -> None: ...
+
+
 ValueT = TypeVar("ValueT")
 
 
@@ -227,6 +233,13 @@ class Context(Protocol):
         value: ValueT,
     ) -> StepOutput | None: ...
 
+    def _prepare_buffered_stream(self, definition: Stream[object]) -> bool: ...
+
+    def _register_step_output_finalizer(
+        self,
+        finalizer: _StepOutputFinalizer,
+    ) -> None: ...
+
 
 class AsyncContext(Context, Protocol):
     """Expose Context operations available to asynchronous Step handlers.

dex_python_sdk-0.2.8/dex/stream.py

@@ -0,0 +1,408 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Super Durable Source License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Generic, TypeVar, cast, overload
+
+from dex._utils import require_name
+from dex.step import StepOutput
+
+if TYPE_CHECKING:
+    from dex.context import AsyncContext, Context
+
+ValueT = TypeVar("ValueT")
+_DEFAULT_BUFFERED_TEXT_FLUSH_INTERVAL = timedelta(seconds=1)
+_DEFAULT_BUFFERED_TEXT_MAX_BYTES = 16 * 1024
+
+
+@dataclass(frozen=True)
+class Stream(Generic[ValueT]):
+    """Define a typed best-effort resumable Stream owned by one Flow type.
+
+    Attributes:
+        name: Logical name unique within the Flow persistence schema.
+        value_type: Python type encoded for every message.
+        stream_capacity_bytes: Positive approximate budget shared by all Flow instances.
+    """
+
+    name: str
+    value_type: type[ValueT]
+    stream_capacity_bytes: int
+
+    def __post_init__(self) -> None:
+        """Validate the Stream definition after dataclass construction.
+
+        Raises:
+            ValueError: If the name is empty or the byte budget is not positive.
+            TypeError: If the byte budget is not an integer.
+        """
+        require_name(self.name)
+        if not isinstance(self.stream_capacity_bytes, int):
+            raise TypeError("Stream stream_capacity_bytes must be an integer")
+        if self.stream_capacity_bytes <= 0:
+            raise ValueError("Stream stream_capacity_bytes must be positive")
+
+    @overload
+    def write(  # type: ignore[overload-overlap]
+        self,
+        context: AsyncContext,
+        value: ValueT,
+    ) -> None:
+        """Enqueue one message from an asynchronous Step handler."""
+        ...
+
+    @overload
+    def write(self, context: Context, value: ValueT) -> StepOutput:
+        """Create one message output for a synchronous Step generator."""
+        ...
+
+    def write(
+        self,
+        context: Context,
+        value: ValueT,
+    ) -> StepOutput | None:
+        """Emit one best-effort message from the current Step execution.
+
+        A synchronous generator must yield the returned StepOutput. An asynchronous
+        Step calls this method without ``await``; the message enters the invocation's
+        ordered output queue immediately. Neither form waits for Dex Stream Store
+        persistence. Calls may write the same Stream any number of times. RPC and
+        Flow-timeout Contexts reject Stream writes.
+
+        Args:
+            context: Current synchronous or asynchronous Step Context.
+            value: Typed message to append.
+
+        Returns:
+            A StepOutput for a synchronous Context, or ``None`` for AsyncContext.
+
+        Raises:
+            ValueError: If the Stream is unregistered or the Context is not a Step.
+            ValueMappingError: If ``value`` cannot be encoded.
+        """
+        return context._write_stream(self, value)
+
+    @overload
+    def buffered_text(  # type: ignore[overload-overlap]
+        self: Stream[str],
+        context: AsyncContext,
+        *,
+        flush_interval: timedelta = _DEFAULT_BUFFERED_TEXT_FLUSH_INTERVAL,
+        max_buffered_bytes: int = _DEFAULT_BUFFERED_TEXT_MAX_BYTES,
+    ) -> AsyncBufferedTextStream: ...
+
+    @overload
+    def buffered_text(
+        self: Stream[str],
+        context: Context,
+        *,
+        flush_interval: timedelta = _DEFAULT_BUFFERED_TEXT_FLUSH_INTERVAL,
+        max_buffered_bytes: int = _DEFAULT_BUFFERED_TEXT_MAX_BYTES,
+    ) -> BufferedTextStream: ...
+
+    def buffered_text(
+        self: Stream[str],
+        context: Context,
+        *,
+        flush_interval: timedelta = _DEFAULT_BUFFERED_TEXT_FLUSH_INTERVAL,
+        max_buffered_bytes: int = _DEFAULT_BUFFERED_TEXT_MAX_BYTES,
+    ) -> AsyncBufferedTextStream | BufferedTextStream:
+        """Create an invocation-managed writer that batches text chunks.
+
+        The first non-empty chunk starts a one-shot timer. Async Step writers append their current
+        batch after ``flush_interval`` even without another chunk. Synchronous generator writers
+        check the interval only when ``write`` is called and require an explicit final ``flush``.
+        Both forms flush early after crossing the soft UTF-8 byte threshold. Chunks are never split
+        or modified.
+
+        AsyncWorker finalizes the writer before sending the invocation result or error. Its
+        synchronous ``write`` method can be passed directly as a text-delta callback. Neither form
+        waits for Dex Stream Store acknowledgement.
+
+        Args:
+            context: Current asynchronous or synchronous Step Context.
+            flush_interval: Positive maximum async buffering interval. Defaults to one second.
+            max_buffered_bytes: Positive soft UTF-8 threshold. Defaults to 16 KiB.
+
+        Returns:
+            An async invocation-managed writer, or a cooperative synchronous writer.
+
+        Raises:
+            TypeError: If this Stream does not carry ``str`` values or an option has the wrong type.
+            ValueError: If an option is not positive, the Stream is unregistered, or the Context is
+                not a Step invocation.
+        """
+        if self.value_type is not str:
+            raise TypeError("Buffered Streams require Stream[str]")
+        _validate_buffered_text_options(flush_interval, max_buffered_bytes)
+        is_async = context._prepare_buffered_stream(cast(Stream[object], self))
+        if is_async:
+            writer = AsyncBufferedTextStream(
+                self,
+                context,
+                flush_interval,
+                max_buffered_bytes,
+            )
+            context._register_step_output_finalizer(writer)
+            return writer
+        return BufferedTextStream(
+            self,
+            context,
+            flush_interval,
+            max_buffered_bytes,
+        )
+
+
+@dataclass(frozen=True)
+class StreamMessage(Generic[ValueT]):
+    """Describe one retained Stream message returned by a Client.
+
+    Attributes:
+        value: Decoded application message.
+        resume_token: Opaque token for the next read.
+        created_time: Server-assigned UTC creation time.
+        source: Informational client source or Step-generated ``#stepExecutionID``.
+    """
+
+    value: ValueT
+    resume_token: str
+    created_time: datetime
+    source: str
+
+
+class AsyncBufferedTextStream:
+    """Batch text chunks for an asynchronous Step invocation.
+
+    Create this writer with :meth:`Stream.buffered_text`. ``write`` is synchronous and returns
+    after local buffering or Worker-output enqueueing. AsyncWorker automatically stops its timer
+    and flushes remaining text before the invocation result or error.
+    """
+
+    def __init__(
+        self,
+        stream: Stream[str],
+        context: Context,
+        flush_interval: timedelta,
+        max_buffered_bytes: int,
+    ) -> None:
+        """Initialize an invocation-managed writer from validated factory inputs.
+
+        Args:
+            stream: Registered string Stream receiving each batch.
+            context: Current asynchronous Step Context.
+            flush_interval: Positive one-shot timer interval.
+            max_buffered_bytes: Positive soft UTF-8 batch threshold.
+        """
+        self._stream = stream
+        self._context = context
+        self._flush_interval_seconds = flush_interval.total_seconds()
+        self._max_buffered_bytes = max_buffered_bytes
+        self._buffer: list[str] = []
+        self._buffered_bytes = 0
+        self._timer: asyncio.TimerHandle | None = None
+        self._timer_generation = 0
+        self._is_closed = False
+        self._terminal_error: BaseException | None = None
+        self._loop = asyncio.get_running_loop()
+
+    def write(self, chunk: str) -> None:
+        """Append one text chunk and flush after reaching the soft size threshold.
+
+        Empty chunks are ignored. The first non-empty chunk starts the configured one-shot timer.
+        This method does not wait for the timer or Stream Store acknowledgement.
+
+        Args:
+            chunk: Text to append without modification.
+
+        Raises:
+            TypeError: If ``chunk`` is not a string.
+            BaseException: The previously latched timer or Worker-output failure.
+            ValueError: If the invocation already finished.
+        """
+        self._require_open()
+        if not isinstance(chunk, str):
+            raise TypeError("Buffered Stream chunks must be strings")
+        if not chunk:
+            return
+        was_empty = not self._buffer
+        self._buffer.append(chunk)
+        self._buffered_bytes += len(chunk.encode("utf-8"))
+        if was_empty:
+            self._start_timer()
+        if self._buffered_bytes >= self._max_buffered_bytes:
+            self._stop_timer()
+            self._flush_buffer()
+
+    def _finalize_step_output(self) -> None:
+        if self._is_closed:
+            if self._terminal_error is not None:
+                raise self._terminal_error
+            return
+        self._stop_timer()
+        try:
+            if self._terminal_error is not None:
+                raise self._terminal_error
+            self._flush_buffer()
+        finally:
+            self._is_closed = True
+
+    def _cancel_step_output(self) -> None:
+        self._stop_timer()
+        self._buffer.clear()
+        self._buffered_bytes = 0
+        self._is_closed = True
+
+    def _start_timer(self) -> None:
+        self._timer_generation += 1
+        generation = self._timer_generation
+        self._timer = self._loop.call_later(
+            self._flush_interval_seconds,
+            self._flush_from_timer,
+            generation,
+        )
+
+    def _flush_from_timer(self, generation: int) -> None:
+        if (
+            self._is_closed
+            or self._terminal_error is not None
+            or generation != self._timer_generation
+        ):
+            return
+        self._timer = None
+        try:
+            self._flush_buffer()
+        except BaseException as error:
+            self._terminal_error = error
+
+    def _stop_timer(self) -> None:
+        self._timer_generation += 1
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+    def _flush_buffer(self) -> None:
+        if not self._buffer:
+            return
+        value = "".join(self._buffer)
+        self._buffer.clear()
+        self._buffered_bytes = 0
+        try:
+            output = self._stream.write(self._context, value)
+            if output is not None:
+                raise RuntimeError(
+                    "Async Buffered Stream produced a synchronous StepOutput"
+                )
+        except BaseException as error:
+            self._terminal_error = error
+            raise
+
+    def _require_open(self) -> None:
+        if self._terminal_error is not None:
+            raise self._terminal_error
+        if self._is_closed:
+            raise ValueError("Buffered Stream invocation has finished")
+
+
+class BufferedTextStream:
+    """Batch text chunks for a synchronous Step generator.
+
+    Create this writer with :meth:`Stream.buffered_text`. Yield every output returned by ``write``
+    and ``flush``. The interval is cooperative: elapsed time is checked when another chunk arrives.
+    """
+
+    def __init__(
+        self,
+        stream: Stream[str],
+        context: Context,
+        flush_interval: timedelta,
+        max_buffered_bytes: int,
+    ) -> None:
+        """Initialize a cooperative writer from validated factory inputs.
+
+        Args:
+            stream: Registered string Stream receiving each batch.
+            context: Current synchronous Step Context.
+            flush_interval: Positive cooperative flush interval.
+            max_buffered_bytes: Positive soft UTF-8 batch threshold.
+        """
+        self._stream = stream
+        self._context = context
+        self._flush_interval_seconds = flush_interval.total_seconds()
+        self._max_buffered_bytes = max_buffered_bytes
+        self._buffer: list[str] = []
+        self._buffered_bytes = 0
+        self._started_at: float | None = None
+
+    def write(self, chunk: str) -> tuple[StepOutput, ...]:
+        """Append one chunk and return an output when a threshold is reached.
+
+        Args:
+            chunk: Text to append without modification.
+
+        Returns:
+            An empty tuple while buffering, or one StepOutput that the handler must yield.
+
+        Raises:
+            TypeError: If ``chunk`` is not a string.
+            ValueMappingError: If the combined text cannot be encoded.
+        """
+        if not isinstance(chunk, str):
+            raise TypeError("Buffered Stream chunks must be strings")
+        if not chunk:
+            return ()
+        if self._started_at is None:
+            self._started_at = time.monotonic()
+        self._buffer.append(chunk)
+        self._buffered_bytes += len(chunk.encode("utf-8"))
+        has_elapsed = (
+            time.monotonic() - self._started_at >= self._flush_interval_seconds
+        )
+        if self._buffered_bytes < self._max_buffered_bytes and not has_elapsed:
+            return ()
+        return self.flush()
+
+    def flush(self) -> tuple[StepOutput, ...]:
+        """Return the current batch as one StepOutput for the handler to yield.
+
+        Returns:
+            An empty tuple for an empty buffer, or one Stream StepOutput.
+
+        Raises:
+            ValueMappingError: If the combined text cannot be encoded.
+        """
+        if not self._buffer:
+            return ()
+        value = "".join(self._buffer)
+        self._buffer.clear()
+        self._buffered_bytes = 0
+        self._started_at = None
+        output = self._stream.write(self._context, value)
+        if output is None:
+            raise RuntimeError(
+                "Synchronous Buffered Stream did not produce a StepOutput"
+            )
+        return (output,)
+
+
+def _validate_buffered_text_options(
+    flush_interval: timedelta,
+    max_buffered_bytes: int,
+) -> None:
+    if not isinstance(flush_interval, timedelta):
+        raise TypeError("Buffered Stream flush_interval must be timedelta")
+    if flush_interval <= timedelta(0):
+        raise ValueError("Buffered Stream flush_interval must be positive")
+    if not isinstance(max_buffered_bytes, int) or isinstance(max_buffered_bytes, bool):
+        raise TypeError("Buffered Stream max_buffered_bytes must be an integer")
+    if max_buffered_bytes <= 0:
+        raise ValueError("Buffered Stream max_buffered_bytes must be positive")

{dex_python_sdk-0.2.6 → dex_python_sdk-0.2.8}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "dex-python-sdk"
 # Publish uses tag sdk-python/v*; CI stamps this for release builds.
-version = "0.2.6"
+version = "0.2.8"
 description = "Python SDK for the Dex workflow engine"
 authors = [{name = "Super Durable"}]
 readme = "README.md"

dex_python_sdk-0.2.6/dex/stream.py

@@ -1,106 +0,0 @@
-# Copyright (c) 2026 Super Durable, Inc.
-#
-# Licensed under the Super Durable Source License 1.0.
-# You may not use this file except in compliance with the License.
-# See the LICENSE file in the repository root.
-#
-# SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import datetime
-from typing import TYPE_CHECKING, Generic, TypeVar, overload
-
-from dex._utils import require_name
-from dex.step import StepOutput
-
-if TYPE_CHECKING:
-    from dex.context import AsyncContext, Context
-
-ValueT = TypeVar("ValueT")
-
-
-@dataclass(frozen=True)
-class Stream(Generic[ValueT]):
-    """Define a typed best-effort resumable Stream owned by one Flow type.
-
-    Attributes:
-        name: Logical name unique within the Flow persistence schema.
-        value_type: Python type encoded for every message.
-        stream_capacity_bytes: Positive approximate budget shared by all Flow instances.
-    """
-
-    name: str
-    value_type: type[ValueT]
-    stream_capacity_bytes: int
-
-    def __post_init__(self) -> None:
-        """Validate the Stream definition after dataclass construction.
-
-        Raises:
-            ValueError: If the name is empty or the byte budget is not positive.
-            TypeError: If the byte budget is not an integer.
-        """
-        require_name(self.name)
-        if not isinstance(self.stream_capacity_bytes, int):
-            raise TypeError("Stream stream_capacity_bytes must be an integer")
-        if self.stream_capacity_bytes <= 0:
-            raise ValueError("Stream stream_capacity_bytes must be positive")
-
-    @overload
-    def write(  # type: ignore[overload-overlap]
-        self,
-        context: AsyncContext,
-        value: ValueT,
-    ) -> None:
-        """Enqueue one message from an asynchronous Step handler."""
-        ...
-
-    @overload
-    def write(self, context: Context, value: ValueT) -> StepOutput:
-        """Create one message output for a synchronous Step generator."""
-        ...
-
-    def write(
-        self,
-        context: Context,
-        value: ValueT,
-    ) -> StepOutput | None:
-        """Emit one best-effort message from the current Step execution.
-
-        A synchronous generator must yield the returned StepOutput. An asynchronous
-        Step calls this method without ``await``; the message enters the invocation's
-        ordered output queue immediately. Neither form waits for Dex Stream Store
-        persistence. Calls may write the same Stream any number of times. RPC and
-        Flow-timeout Contexts reject Stream writes.
-
-        Args:
-            context: Current synchronous or asynchronous Step Context.
-            value: Typed message to append.
-
-        Returns:
-            A StepOutput for a synchronous Context, or ``None`` for AsyncContext.
-
-        Raises:
-            ValueError: If the Stream is unregistered or the Context is not a Step.
-            ValueMappingError: If ``value`` cannot be encoded.
-        """
-        return context._write_stream(self, value)
-
-
-@dataclass(frozen=True)
-class StreamMessage(Generic[ValueT]):
-    """Describe one retained Stream message returned by a Client.
-
-    Attributes:
-        value: Decoded application message.
-        resume_token: Opaque token for the next read.
-        created_time: Server-assigned UTC creation time.
-        source: Informational client source or Step-generated ``#stepExecutionID``.
-    """
-
-    value: ValueT
-    resume_token: str
-    created_time: datetime
-    source: str