flowforge-sdk 0.3.0__tar.gz → 0.3.2__tar.gz

{flowforge_sdk-0.3.0 → flowforge_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowforge-sdk
-Version: 0.3.0
+Version: 0.3.2
 Summary: Python SDK for FlowForge - AI workflow orchestration
 Project-URL: Homepage, https://github.com/flowforge/flowforge
 Project-URL: Documentation, https://flowforge.dev/docs
@@ -144,3 +144,42 @@ result = await flowforge.cancel_run("761c0321-...")
 `retry_run` is different from replaying: it preserves the memoized results of
 all completed steps so execution resumes from where it failed rather than
 starting over from scratch.
+
+## Streaming Run Events (SSE)
+
+Stream real-time events from a running workflow via Server-Sent Events:
+
+```python
+from flowforge import FlowForge, RunEvent
+
+flowforge = FlowForge(app_id="my-app", api_key="ff_live_...")
+
+# Async iterator
+async for event in flowforge.stream_run("run-uuid"):
+    print(f"[{event.event_type.value}] {event.data}")
+
+# With callback
+async for event in flowforge.stream_run("run-uuid", on_event=lambda e: print(e)):
+    pass
+```
+
+The stream automatically closes when the run completes or fails. Available event types:
+
+- `step_started`, `step_completed`, `step_failed`
+- `thinking`, `thinking_chunk`
+- `tool_call_started`, `tool_call_completed`
+- `approval_required`, `approval_resolved`
+- `run_started`, `run_paused`, `run_resumed`, `run_completed`, `run_failed`
+
+Options:
+
+```python
+async for event in flowforge.stream_run(
+    "run-uuid",
+    include_history=True,   # Include past events on connect (default: True)
+    timeout=300.0,          # Server-side stream timeout in seconds (default: 300)
+    on_event=my_callback,   # Optional callback for each event
+):
+    if event.is_terminal:
+        print("Run finished:", event.data)
+```

{flowforge_sdk-0.3.0 → flowforge_sdk-0.3.2}/README.md

@@ -92,3 +92,42 @@ result = await flowforge.cancel_run("761c0321-...")
 `retry_run` is different from replaying: it preserves the memoized results of
 all completed steps so execution resumes from where it failed rather than
 starting over from scratch.
+
+## Streaming Run Events (SSE)
+
+Stream real-time events from a running workflow via Server-Sent Events:
+
+```python
+from flowforge import FlowForge, RunEvent
+
+flowforge = FlowForge(app_id="my-app", api_key="ff_live_...")
+
+# Async iterator
+async for event in flowforge.stream_run("run-uuid"):
+    print(f"[{event.event_type.value}] {event.data}")
+
+# With callback
+async for event in flowforge.stream_run("run-uuid", on_event=lambda e: print(e)):
+    pass
+```
+
+The stream automatically closes when the run completes or fails. Available event types:
+
+- `step_started`, `step_completed`, `step_failed`
+- `thinking`, `thinking_chunk`
+- `tool_call_started`, `tool_call_completed`
+- `approval_required`, `approval_resolved`
+- `run_started`, `run_paused`, `run_resumed`, `run_completed`, `run_failed`
+
+Options:
+
+```python
+async for event in flowforge.stream_run(
+    "run-uuid",
+    include_history=True,   # Include past events on connect (default: True)
+    timeout=300.0,          # Server-side stream timeout in seconds (default: 300)
+    on_event=my_callback,   # Optional callback for each event
+):
+    if event.is_terminal:
+        print("Run finished:", event.data)
+```

{flowforge_sdk-0.3.0 → flowforge_sdk-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowforge-sdk"
-version = "0.3.0"
+version = "0.3.2"
 description = "Python SDK for FlowForge - AI workflow orchestration"
 readme = "README.md"
 requires-python = ">=3.11"

{flowforge_sdk-0.3.0 → flowforge_sdk-0.3.2}/src/flowforge/__init__.py

@@ -26,6 +26,7 @@ from flowforge.exceptions import (
 )
 from flowforge.network import Network, NetworkResult, NetworkState, RouterContext, network
 from flowforge.steps import step
+from flowforge.streaming import RunEvent, RunEventType
 from flowforge.tools import Tool, tool
 from flowforge.triggers import Trigger, trigger
 
@@ -68,6 +69,9 @@ __all__ = [
     "concurrency",
     "rate_limit",
     "throttle",
+    # Streaming
+    "RunEvent",
+    "RunEventType",
     # Exceptions
     "FlowForgeError",
     "StepError",

{flowforge_sdk-0.3.0 → flowforge_sdk-0.3.2}/src/flowforge/client.py

@@ -5,7 +5,7 @@ import hmac
 import json
 import os
 import uuid
-from collections.abc import Awaitable, Callable
+from collections.abc import AsyncIterator, Awaitable, Callable
 from datetime import datetime
 from typing import Any, TypeVar
 
@@ -33,6 +33,7 @@ from flowforge.context import Context, Event
 from flowforge.decorators import FlowForgeFunction
 from flowforge.decorators import function as make_function
 from flowforge.execution import ExecutionEngine, FunctionDefinition
+from flowforge.streaming import RunEvent, RunEventType
 from flowforge.triggers import TriggerBuilder
 
 T = TypeVar("T")
@@ -448,6 +449,85 @@ class FlowForge:
         response.raise_for_status()
         return response.json()
 
+    async def stream_run(
+        self,
+        run_id: str,
+        *,
+        include_history: bool = True,
+        timeout: float = 300.0,
+        on_event: Callable[[RunEvent], None] | None = None,
+    ) -> AsyncIterator[RunEvent]:
+        """
+        Stream real-time SSE events for a run.
+
+        Args:
+            run_id: The run UUID to stream.
+            include_history: Whether to include past events on connect.
+            timeout: Server-side stream timeout in seconds.
+            on_event: Optional callback invoked for each event.
+
+        Yields:
+            RunEvent for each SSE event. Stops on terminal events
+            (run_completed, run_failed).
+
+        Example:
+            async for event in flowforge.stream_run("run-uuid"):
+                print(f"[{event.event_type.value}] {event.data}")
+        """
+        params = {
+            "include_history": str(include_history).lower(),
+            "timeout": str(int(timeout)),
+        }
+        url = f"{self.api_url}/api/v1/runs/{run_id}/stream"
+
+        headers: dict[str, str] = {"Accept": "text/event-stream"}
+        if self.api_key:
+            headers["X-FlowForge-API-Key"] = self.api_key
+
+        # Use a dedicated client with extended read timeout for streaming
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(connect=10.0, read=timeout + 30.0, write=10.0, pool=10.0),
+        ) as client:
+            async with client.stream(
+                "GET", url, params=params, headers=headers,
+            ) as response:
+                response.raise_for_status()
+
+                event_type: str | None = None
+                data_buf: list[str] = []
+
+                async for line in response.aiter_lines():
+                    # Skip keepalive comments
+                    if line.startswith(":"):
+                        continue
+
+                    # Blank line = dispatch event
+                    if not line:
+                        if event_type and data_buf:
+                            raw_data = "\n".join(data_buf)
+                            try:
+                                evt = RunEvent.from_raw(event_type, raw_data, run_id)
+                            except (ValueError, json.JSONDecodeError):
+                                event_type = None
+                                data_buf = []
+                                continue
+
+                            if on_event:
+                                on_event(evt)
+                            yield evt
+
+                            if evt.is_terminal:
+                                return
+
+                        event_type = None
+                        data_buf = []
+                        continue
+
+                    if line.startswith("event:"):
+                        event_type = line[len("event:"):].strip()
+                    elif line.startswith("data:"):
+                        data_buf.append(line[len("data:"):].strip())
+
     async def close(self) -> None:
         """Close the HTTP client."""
         if self._http_client:

flowforge_sdk-0.3.2/src/flowforge/streaming.py

@@ -0,0 +1,66 @@
+"""SSE streaming types for FlowForge run events."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class RunEventType(str, Enum):
+    """Event types emitted by the SSE run stream."""
+
+    STEP_STARTED = "step_started"
+    STEP_COMPLETED = "step_completed"
+    STEP_FAILED = "step_failed"
+    THINKING = "thinking"
+    THINKING_CHUNK = "thinking_chunk"
+    TOOL_CALL_STARTED = "tool_call_started"
+    TOOL_CALL_COMPLETED = "tool_call_completed"
+    APPROVAL_REQUIRED = "approval_required"
+    APPROVAL_RESOLVED = "approval_resolved"
+    RUN_STARTED = "run_started"
+    RUN_PAUSED = "run_paused"
+    RUN_RESUMED = "run_resumed"
+    RUN_COMPLETED = "run_completed"
+    RUN_FAILED = "run_failed"
+
+
+_TERMINAL_EVENTS = {RunEventType.RUN_COMPLETED, RunEventType.RUN_FAILED}
+
+
+@dataclass
+class RunEvent:
+    """A single event from an SSE run stream."""
+
+    event_type: RunEventType
+    data: dict[str, Any]
+    run_id: str
+    timestamp: datetime
+
+    @classmethod
+    def from_raw(cls, event_type_str: str, json_data: str, run_id: str) -> RunEvent:
+        """Parse a raw SSE event into a RunEvent."""
+        parsed = json.loads(json_data) if isinstance(json_data, str) else json_data
+        ts = parsed.get("timestamp") or parsed.get("ts")
+        if isinstance(ts, str):
+            try:
+                timestamp = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+            except ValueError:
+                timestamp = datetime.utcnow()
+        else:
+            timestamp = datetime.utcnow()
+
+        return cls(
+            event_type=RunEventType(event_type_str),
+            data=parsed,
+            run_id=run_id,
+            timestamp=timestamp,
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        """True if this event signals the run has ended."""
+        return self.event_type in _TERMINAL_EVENTS