rippletide-python 0.2.0__tar.gz → 0.3.0__tar.gz

{rippletide_python-0.2.0 → rippletide_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rippletide-python
-Version: 0.2.0
+Version: 0.3.0
 Summary: Monitor-first Python SDK for Rippletide-connected agents
 License: UNLICENSED
 Requires-Python: >=3.10
@@ -16,7 +16,7 @@ hand-written provider or internal HTTP call at the existing model seam.
 
 ## Install and connect
 
-The native OTel release candidate is `rippletide-python==0.2.0`. It requires
+The current release is `rippletide-python==0.3.0`. It requires
 the platform's OTLP ingestion/readers and does not provide V1 trace compatibility.
 Until it is published, validate it by installing a locally built wheel; do not
 assume the unversioned registry install below contains candidate changes.
@@ -41,8 +41,7 @@ prompt with your coding agent in that repository. The CLI also supports
 Run a real turn that uses a tool and delivers a response. Confirm **Runtime
 verified (5/5)** in Fleet and the run's tool calls and **Delivered** outcome in
 Activity. Copying a prompt or storing credentials alone does not prove a
-connection. The SDK supports synchronous call sites. Async execution and
-streaming are not supported.
+connection.
 
 ## Instrument existing call sites
 
@@ -85,6 +84,34 @@ connection takes precedence over those legacy values; explicit constructor
 arguments take precedence over either format. Never use a Platform key in the
 agent or commit the `.env`.
 
+## Async and streaming agents
+
+The same client serves synchronous and asyncio code. `guard_tool_call()`,
+`guard_tool_result()` and `deliver_response()` accept `async def` callbacks and
+then return a coroutine to await; the policy round trip and receipts run in a
+worker thread, so the event loop is never blocked. `run()`, `agent()` and
+`span()` are plain `with` blocks in both cases. `traced()` wraps sync
+functions, coroutine functions, and calls that return a provider stream: the
+stream is passed through untouched and its span ends once the stream is
+consumed, closed, or abandoned, in which case the span is marked
+`stream_not_consumed`. Policy decides on the complete response: pass the text
+the agent has assembled from the stream to `deliver_response()` before the
+existing sink delivers it. When the tokens must reach the caller as they arrive,
+pass the stream itself as `response`: chunks flow through to `deliver` untouched
+and the decision is recorded on the assembled text once the stream ends, with no
+suppression possible, so a BLOCK is marked as decided after delivery.
+Use `await rippletide.aflush()` and
+`await rippletide.ashutdown()` from asyncio code.
+
+```python
+async def handle(request):
+    with rippletide.run(name="inbound_request", input=request):
+        stream = rippletide.traced(open_model_stream, name=MODEL_OPERATION, kind="model")(messages)
+        candidate = "".join([chunk.text async for chunk in stream])
+        await rippletide.guard_tool_call(toolset="core", tool="lookup", params=args, execute=lookup_async)
+        return await rippletide.deliver_response(request=request, response=candidate, deliver=send_async)
+```
+
 ## Policy failures and capture
 
 The client starts disabled when no Connection key is present. For
@@ -154,6 +181,6 @@ native response shape, and the SDK records the applied outcome as a receipt.
 Result fingerprints use the server's ECMAScript JSON encoding, including its
 number formatting and UTF-16 object-key ordering.
 
-This first release supports synchronous Python call sites. Python MCP servers,
-async generators, and response streaming remain unsupported rather than being
-silently represented as complete response-delivery protection.
+Python MCP servers remain unsupported. A response that is streamed to the
+caller before it is complete cannot be protected by `deliver_response()`; the
+SDK does not represent such a path as complete response-delivery protection.

{rippletide_python-0.2.0 → rippletide_python-0.3.0}/README.md

@@ -6,7 +6,7 @@ hand-written provider or internal HTTP call at the existing model seam.
 
 ## Install and connect
 
-The native OTel release candidate is `rippletide-python==0.2.0`. It requires
+The current release is `rippletide-python==0.3.0`. It requires
 the platform's OTLP ingestion/readers and does not provide V1 trace compatibility.
 Until it is published, validate it by installing a locally built wheel; do not
 assume the unversioned registry install below contains candidate changes.
@@ -31,8 +31,7 @@ prompt with your coding agent in that repository. The CLI also supports
 Run a real turn that uses a tool and delivers a response. Confirm **Runtime
 verified (5/5)** in Fleet and the run's tool calls and **Delivered** outcome in
 Activity. Copying a prompt or storing credentials alone does not prove a
-connection. The SDK supports synchronous call sites. Async execution and
-streaming are not supported.
+connection.
 
 ## Instrument existing call sites
 
@@ -75,6 +74,34 @@ connection takes precedence over those legacy values; explicit constructor
 arguments take precedence over either format. Never use a Platform key in the
 agent or commit the `.env`.
 
+## Async and streaming agents
+
+The same client serves synchronous and asyncio code. `guard_tool_call()`,
+`guard_tool_result()` and `deliver_response()` accept `async def` callbacks and
+then return a coroutine to await; the policy round trip and receipts run in a
+worker thread, so the event loop is never blocked. `run()`, `agent()` and
+`span()` are plain `with` blocks in both cases. `traced()` wraps sync
+functions, coroutine functions, and calls that return a provider stream: the
+stream is passed through untouched and its span ends once the stream is
+consumed, closed, or abandoned, in which case the span is marked
+`stream_not_consumed`. Policy decides on the complete response: pass the text
+the agent has assembled from the stream to `deliver_response()` before the
+existing sink delivers it. When the tokens must reach the caller as they arrive,
+pass the stream itself as `response`: chunks flow through to `deliver` untouched
+and the decision is recorded on the assembled text once the stream ends, with no
+suppression possible, so a BLOCK is marked as decided after delivery.
+Use `await rippletide.aflush()` and
+`await rippletide.ashutdown()` from asyncio code.
+
+```python
+async def handle(request):
+    with rippletide.run(name="inbound_request", input=request):
+        stream = rippletide.traced(open_model_stream, name=MODEL_OPERATION, kind="model")(messages)
+        candidate = "".join([chunk.text async for chunk in stream])
+        await rippletide.guard_tool_call(toolset="core", tool="lookup", params=args, execute=lookup_async)
+        return await rippletide.deliver_response(request=request, response=candidate, deliver=send_async)
+```
+
 ## Policy failures and capture
 
 The client starts disabled when no Connection key is present. For
@@ -144,6 +171,6 @@ native response shape, and the SDK records the applied outcome as a receipt.
 Result fingerprints use the server's ECMAScript JSON encoding, including its
 number formatting and UTF-16 object-key ordering.
 
-This first release supports synchronous Python call sites. Python MCP servers,
-async generators, and response streaming remain unsupported rather than being
-silently represented as complete response-delivery protection.
+Python MCP servers remain unsupported. A response that is streamed to the
+caller before it is complete cannot be protected by `deliver_response()`; the
+SDK does not represent such a path as complete response-delivery protection.

{rippletide_python-0.2.0 → rippletide_python-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rippletide-python"
-version = "0.2.0"
+version = "0.3.0"
 description = "Monitor-first Python SDK for Rippletide-connected agents"
 readme = "README.md"
 requires-python = ">=3.10"

{rippletide_python-0.2.0 → rippletide_python-0.3.0}/rippletide/client.py

@@ -1,22 +1,26 @@
-"""The small synchronous Python counterpart to rippletide-package/sdk.
+"""The small Python counterpart to rippletide-package/sdk.
 
 The client intentionally has no provider dependency.  It can surround a raw
-urllib/requests/httpx provider call and never owns the customer's traffic.
+urllib/requests/httpx provider call, synchronous or asynchronous, streamed or
+not, and never owns the customer's traffic.
 """
 
 from __future__ import annotations
 
+import asyncio
+import inspect
 import json
 import math
 import os
 import re
+import sys
 import time
 import uuid
 from hashlib import sha256
 from http.client import HTTPException
 from contextlib import contextmanager, nullcontext
 from datetime import datetime, timezone
-from typing import Any, Callable, Iterator, Mapping, TypeVar
+from typing import Any, Awaitable, Callable, Iterator, Mapping, TypeVar
 from urllib.error import HTTPError, URLError
 from urllib.parse import quote, unquote, urlsplit
 from urllib.request import Request, urlopen
@@ -230,10 +234,18 @@ class _Span:
             self.client._warn("Rippletide span capture unavailable; continuing normally")
         self.trace_id = format(self.native.get_span_context().trace_id, "032x")
         self.span_id = format(self.native.get_span_context().span_id, "016x")
-        self.scope = trace.use_span(self.native, end_on_exit=False, record_exception=False, set_status_on_exception=False) if self.native.is_recording() else nullcontext()
+        self.scope = self._activation()
         self.scope.__enter__()
         return self
 
+    def _activation(self) -> Any:
+        return trace.use_span(self.native, end_on_exit=False, record_exception=False, set_status_on_exception=False) if self.native.is_recording() else nullcontext()
+
+    def detach(self) -> None:
+        """Leave the current context while the span stays open for a deferred result."""
+        self.scope.__exit__(None, None, None)
+        self.scope = nullcontext()
+
     def set_output(self, output: Any, **attributes: Any) -> None:
         self.output, self.output_set = output, True
         self.end_attributes.update(attributes)
@@ -260,8 +272,126 @@ class _Span:
         return False
 
 
+def _span_kind(kind: str) -> str:
+    normalized = {"llm": "model", "other": "operation"}.get(kind, kind)
+    return normalized if normalized in {"run", "agent", "model", "tool", "policy", "operation"} else "operation"
+
+
+def _complete(span: _Span, result: Any, after: Callable[[], None] | None = None) -> Any:
+    """Close the span with a plain result now, or once an awaited result settles."""
+    if inspect.isawaitable(result):
+        span.detach()
+        return _settle(span, result, after)
+    if after:
+        after()
+    span.set_output(result)
+    span.__exit__(None, None, None)
+    return result
+
+
+async def _settle(span: _Span, awaitable: Awaitable[Any], after: Callable[[], None] | None = None) -> Any:
+    with span._activation():
+        try:
+            result = await awaitable
+        except BaseException:
+            if after:
+                await asyncio.to_thread(after)
+            span.__exit__(*sys.exc_info())
+            raise
+        if after:
+            await asyncio.to_thread(after)
+        span.set_output(result)
+        span.__exit__(None, None, None)
+        return result
+
+
+class _TracedStream:
+    """Passes a stream through untouched and ends its span once the stream is exhausted, closed, or abandoned.
+
+    `finish(chunks, complete)` runs first when given and returns extra end attributes.
+    """
+
+    def __init__(self, span: _Span, stream: Any, finish: Callable[[list[Any], bool], dict[str, Any]] | None = None) -> None:
+        self._span, self._stream, self._finish, self._chunks, self._ended = span, stream, finish, [], False
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return getattr(self._stream, name)
+
+    def __iter__(self) -> "_TracedStream":
+        return self
+
+    def __aiter__(self) -> "_TracedStream":
+        return self
+
+    def __next__(self) -> Any:
+        try:
+            return self._collect(next(self._stream))
+        except BaseException as error:
+            self._end(isinstance(error, StopIteration), error)
+            raise
+
+    async def __anext__(self) -> Any:
+        try:
+            return self._collect(await self._stream.__anext__())
+        except BaseException as error:
+            self._end(isinstance(error, StopAsyncIteration), error)
+            raise
+
+    def __enter__(self) -> "_TracedStream":
+        if hasattr(self._stream, "__enter__"):
+            self._stream.__enter__()
+        return self
+
+    def __exit__(self, *exc: Any) -> Any:
+        self._end(False)
+        return self._stream.__exit__(*exc) if hasattr(self._stream, "__exit__") else False
+
+    async def __aenter__(self) -> "_TracedStream":
+        if hasattr(self._stream, "__aenter__"):
+            await self._stream.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> Any:
+        self._end(False)
+        return await self._stream.__aexit__(*exc) if hasattr(self._stream, "__aexit__") else False
+
+    def close(self) -> None:
+        self._end(False)
+        if hasattr(self._stream, "close"):
+            self._stream.close()
+
+    async def aclose(self) -> None:
+        self._end(False)
+        if hasattr(self._stream, "aclose"):
+            await self._stream.aclose()
+
+    def __del__(self) -> None:
+        try:
+            self._end(False)
+        except Exception:
+            pass
+
+    def _collect(self, chunk: Any) -> Any:
+        if self._finish or len(self._chunks) < 51:
+            self._chunks.append(chunk)
+        return chunk
+
+    def _end(self, complete: bool, error: BaseException | None = None) -> None:
+        if self._ended:
+            return
+        self._ended = True
+        error = None if complete else error
+        attributes = {"streaming": True, **({} if complete else {"captureCompleteness": "stream_not_consumed"})}
+        if self._finish:
+            attributes.update(self._finish(self._chunks, complete))
+        self._span.set_output(self._chunks, **attributes)
+        self._span.__exit__(type(error) if error else None, error, getattr(error, "__traceback__", None))
+
+
 class Rippletide:
-    """Synchronous policy client with native OpenTelemetry instrumentation."""
+    """Policy client with native OpenTelemetry instrumentation for synchronous and asyncio agents."""
 
     def __init__(self, *, agent_id: str | None = None, api_key: str | None = None, base_url: str | None = None, name: str | None = None, description: str | None = None, capture_content: bool = False, runtime_traces: bool = True, disabled: bool | None = None, timeout_ms: int | None = None, warn: Callable[[str], None] | None = None) -> None:
         from_env = _connection_env()
@@ -327,20 +457,56 @@ class Rippletide:
 
     @contextmanager
     def span(self, kind: str, *, name: str, input: Any = _UNSET, tool_call_id: str | None = None, invocation_id: str | None = None, decision_id: str | None = None, attributes: Mapping[str, Any] | None = None, links: list[trace.Link] | None = None) -> Iterator[_Span]:
-        normalized = {"llm": "model", "other": "operation"}.get(kind, kind)
-        if normalized not in {"run", "agent", "model", "tool", "policy", "operation"}:
-            normalized = "operation"
-        with _Span(self, normalized, name, input=input, toolCallId=tool_call_id, invocationId=invocation_id, decisionId=decision_id, attributes=attributes, links=links) as current:
+        with _Span(self, _span_kind(kind), name, input=input, toolCallId=tool_call_id, invocationId=invocation_id, decisionId=decision_id, attributes=attributes, links=links) as current:
             yield current
 
     def traced(self, fn: Callable[..., T], *, name: str | None = None, kind: str = "tool") -> Callable[..., T]:
+        """Record each call as a span; an awaited result or a returned (async) iterator keeps it open until settled or exhausted."""
+        label = name or getattr(fn, "__name__", None) or "anonymous"
+
         def wrapped(*args: Any, **kwargs: Any) -> T:
-            with self.span(kind, name=name or fn.__name__ or "anonymous", input={"args": args, "kwargs": kwargs}) as current:
+            span = _Span(self, _span_kind(kind), label, input={"args": args, "kwargs": kwargs}).__enter__()
+            try:
                 result = fn(*args, **kwargs)
-                current.set_output(result)
-                return result
+            except BaseException:
+                span.__exit__(*sys.exc_info())
+                raise
+            if hasattr(result, "__next__") or hasattr(result, "__anext__"):
+                span.detach()
+                return _TracedStream(span, result)  # type: ignore[return-value]
+            return _complete(span, result)
         return wrapped
 
+    def _guarded(self, decide: Callable[[], tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]], callback: Callable[[Any], Any]) -> Any:
+        """Run the blocking policy round trip in decide(), then the callback inside the action span.
+
+        A coroutine-function callback yields a coroutine that moves the HTTP work to a
+        worker thread, so an asyncio agent is never blocked by decisions or receipts.
+        """
+        if not inspect.iscoroutinefunction(callback):
+            kind, options, argument, before, after = decide()
+            span = _Span(self, kind, **options).__enter__()
+            if before:
+                before()
+            try:
+                result = callback(argument)
+            except BaseException:
+                if after:
+                    after()
+                span.__exit__(*sys.exc_info())
+                raise
+            return _complete(span, result, after)
+
+        async def guarded() -> Any:
+            kind, options, argument, before, after = await asyncio.to_thread(decide)
+            span = _Span(self, kind, **options).__enter__()
+            span.detach()
+            if before:
+                await asyncio.to_thread(before)
+            return await _settle(span, callback(argument), after)
+
+        return guarded()
+
     def trace_headers(self) -> dict[str, str]:
         headers: dict[str, str] = {}
         TraceContextTextMapPropagator().inject(headers)
@@ -500,23 +666,25 @@ class Rippletide:
         action, invocation_id = f"{quote(toolset, safe='')}/{quote(tool, safe='')}", str(uuid.uuid4())
         if self.disabled:
             return execute(params)
-        started = time.monotonic()
-        body = {"invocationId": invocation_id, "action": action, "params": dict(params), "context": dict(context or {})}
-        with self.span("policy", name=f"before_action:{action}", input=body, tool_call_id=tool_call_id, invocation_id=invocation_id, attributes={"trigger": "before_action", "action": action}) as policy_span:
-            decision = self._decide("/decide", body, action)
-            decision_id = decision.get("decisionId") if decision else None
-            policy_span.options["decisionId"] = decision_id
-            elapsed = int((time.monotonic() - started) * 1000)
-            policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
-        if decision and decision.get("disposition") == "BLOCK":
-            self._receipt(decision, "PREVENTED", elapsed)
-            with self.span("tool", name=tool, input=params, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], tool_call_id=tool_call_id, invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": False, "applicationOutcome": "PREVENTED"}):
-                raise RippletidePolicyBlockedError(action, decision)
-        with self.span("tool", name=tool, input=params, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], tool_call_id=tool_call_id, invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": True, "disposition": decision.get("disposition") if decision else "FALLBACK"}) as tool_span:
-            self._receipt(decision, "EXECUTED", elapsed)
-            result = execute(params)
-            tool_span.set_output(result)
-            return result
+
+        def decide() -> tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]:
+            started = time.monotonic()
+            body = {"invocationId": invocation_id, "action": action, "params": dict(params), "context": dict(context or {})}
+            with self.span("policy", name=f"before_action:{action}", input=body, tool_call_id=tool_call_id, invocation_id=invocation_id, attributes={"trigger": "before_action", "action": action}) as policy_span:
+                decision = self._decide("/decide", body, action)
+                decision_id = decision.get("decisionId") if decision else None
+                policy_span.options["decisionId"] = decision_id
+                elapsed = int((time.monotonic() - started) * 1000)
+                policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+            options: dict[str, Any] = {"name": tool, "input": params, "links": [trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], "toolCallId": tool_call_id, "invocationId": invocation_id, "decisionId": decision_id}
+            if decision and decision.get("disposition") == "BLOCK":
+                self._receipt(decision, "PREVENTED", elapsed)
+                with _Span(self, "tool", **options, attributes={"action": action, "executed": False, "applicationOutcome": "PREVENTED"}):
+                    raise RippletidePolicyBlockedError(action, decision)
+            options["attributes"] = {"action": action, "executed": True, "disposition": decision.get("disposition") if decision else "FALLBACK"}
+            return "tool", options, params, lambda: self._receipt(decision, "EXECUTED", elapsed), None
+
+        return self._guarded(decide, execute)
 
     def guard_tool_result(self, *, toolset: str, tool: str, params: Mapping[str, Any], result: Any, result_items: list[Mapping[str, Any]], apply: Callable[[Mapping[str, Any]], T], context: Mapping[str, Any] | None = None, tool_call_id: str | None = None, allow_result_export: bool = False) -> T:
         """Filter an already-completed tool result before its next local sink.
@@ -535,75 +703,105 @@ class Rippletide:
         evaluated_result = _clone_policy_value(result, "result")
         evaluated_items = [_clone_policy_value(item, f"result_items[{index}]") for index, item in enumerate(result_items)]
         evaluated_context = _clone_policy_value(dict(context or {}), "trusted context")
-        decision: Mapping[str, Any] | None = None
-        elapsed = 0
-        policy_span = None
 
-        if allow_result_export and not self.disabled:
-            invocation_id = str(uuid.uuid4())
-            body = {"invocationId": invocation_id, "action": action, "params": evaluated_params, "result": evaluated_result, "context": evaluated_context}
-            started = time.monotonic()
-            with self.span("policy", name=f"after_action:{action}", input=body, tool_call_id=tool_call_id, invocation_id=invocation_id, attributes={"trigger": "after_action", "action": action, "rawResultExport": True}) as policy_span:
-                decision = self._decide_result(body, action, evaluated_result, evaluated_items)
-                policy_span.options["decisionId"] = decision.get("decisionId") if decision else None
-                elapsed = int((time.monotonic() - started) * 1000)
-                policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
-
-        delivered_items = list(evaluated_items)
-        excluded_items: list[dict[str, Any]] = []
-        if decision:
-            delivered_items = []
-            for item, item_decision in zip(evaluated_items, decision["items"]):
-                if item_decision["disposition"] != "BLOCK":
-                    delivered_items.append(item)
-                    continue
-                detail = item_decision.get("decision") if isinstance(item_decision.get("decision"), Mapping) else {}
-                excluded_items.append({
-                    "index": item_decision["index"],
-                    "itemId": item_decision["itemId"],
-                    "item": item,
-                    "reason": detail.get("reason") if isinstance(detail.get("reason"), str) else "Blocked by policy",
-                    "blockingRuleIds": list(detail.get("blockingRuleIds", [])) if isinstance(detail.get("blockingRuleIds"), list) else [],
-                })
-        outcome = "RESULT_FILTERED" if excluded_items else "RESULT_DELIVERED"
-        filtered = {"result": evaluated_result, "deliveredItems": delivered_items, "excludedItems": excluded_items, "policyDecision": _clone_policy_value(decision, "policy decision") if decision else None}
-        with self.span("operation", name="result_application", input=filtered, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})] if policy_span else [], tool_call_id=tool_call_id, invocation_id=decision.get("invocationId") if decision else None, decision_id=decision.get("decisionId") if decision else None, attributes={"action": action, "applicationOutcome": outcome, "deliveredItemCount": len(delivered_items), "excludedItemCount": len(excluded_items), "executed": True}) as result_span:
-            try:
-                applied = apply(filtered)
-                result_span.set_output(applied)
-                return applied
-            finally:
-                if decision:
-                    self._receipt_body(decision["decisionId"], {
-                        "outcome": outcome,
-                        "occurredAt": _now(),
-                        "resultPlanFingerprint": decision["resultPlanFingerprint"],
-                        "deliveredItemIndexes": [index for index, item in enumerate(decision["items"]) if item["disposition"] != "BLOCK"],
-                        "excludedItemIndexes": [index for index, item in enumerate(decision["items"]) if item["disposition"] == "BLOCK"],
-                        "decisionRoundtripMs": elapsed,
+        def decide() -> tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]:
+            decision: Mapping[str, Any] | None = None
+            elapsed = 0
+            policy_span = None
+
+            if allow_result_export and not self.disabled:
+                invocation_id = str(uuid.uuid4())
+                body = {"invocationId": invocation_id, "action": action, "params": evaluated_params, "result": evaluated_result, "context": evaluated_context}
+                started = time.monotonic()
+                with self.span("policy", name=f"after_action:{action}", input=body, tool_call_id=tool_call_id, invocation_id=invocation_id, attributes={"trigger": "after_action", "action": action, "rawResultExport": True}) as policy_span:
+                    decision = self._decide_result(body, action, evaluated_result, evaluated_items)
+                    policy_span.options["decisionId"] = decision.get("decisionId") if decision else None
+                    elapsed = int((time.monotonic() - started) * 1000)
+                    policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+
+            delivered_items = list(evaluated_items)
+            excluded_items: list[dict[str, Any]] = []
+            if decision:
+                delivered_items = []
+                for item, item_decision in zip(evaluated_items, decision["items"]):
+                    if item_decision["disposition"] != "BLOCK":
+                        delivered_items.append(item)
+                        continue
+                    detail = item_decision.get("decision") if isinstance(item_decision.get("decision"), Mapping) else {}
+                    excluded_items.append({
+                        "index": item_decision["index"],
+                        "itemId": item_decision["itemId"],
+                        "item": item,
+                        "reason": detail.get("reason") if isinstance(detail.get("reason"), str) else "Blocked by policy",
+                        "blockingRuleIds": list(detail.get("blockingRuleIds", [])) if isinstance(detail.get("blockingRuleIds"), list) else [],
                     })
+            outcome = "RESULT_FILTERED" if excluded_items else "RESULT_DELIVERED"
+            filtered = {"result": evaluated_result, "deliveredItems": delivered_items, "excludedItems": excluded_items, "policyDecision": _clone_policy_value(decision, "policy decision") if decision else None}
+            options = {"name": "result_application", "input": filtered, "links": [trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})] if policy_span else [], "toolCallId": tool_call_id, "invocationId": decision.get("invocationId") if decision else None, "decisionId": decision.get("decisionId") if decision else None, "attributes": {"action": action, "applicationOutcome": outcome, "deliveredItemCount": len(delivered_items), "excludedItemCount": len(excluded_items), "executed": True}}
+            after = (lambda: self._receipt_body(decision["decisionId"], {
+                "outcome": outcome,
+                "occurredAt": _now(),
+                "resultPlanFingerprint": decision["resultPlanFingerprint"],
+                "deliveredItemIndexes": [index for index, item in enumerate(decision["items"]) if item["disposition"] != "BLOCK"],
+                "excludedItemIndexes": [index for index, item in enumerate(decision["items"]) if item["disposition"] == "BLOCK"],
+                "decisionRoundtripMs": elapsed,
+            })) if decision else None
+            return "operation", options, filtered, None, after
+
+        return self._guarded(decide, apply)
 
     def deliver_response(self, *, request: Any, response: Any, deliver: Callable[[Any], T], context: Mapping[str, Any] | None = None) -> T:
+        """Decide on the complete candidate, then deliver it.
+
+        A sync or async iterator as `response` is streamed delivery: chunks pass
+        through to `deliver` untouched, and the decision runs on the assembled
+        text once the stream ends. It is recorded, never enforced: the outcome is
+        always DELIVERED and a BLOCK is marked as decided after delivery.
+        """
         invocation_id, action = str(uuid.uuid4()), "rippletide/response"
         if self.disabled:
             return deliver(response)
-        started = time.monotonic()
-        body = {"invocationId": invocation_id, "request": request, "response": response, "context": dict(context or {})}
-        with self.span("policy", name="before_response:rippletide/response", input=body, invocation_id=invocation_id, attributes={"trigger": "before_response", "action": action}) as policy_span:
-            decision = self._decide("/decide-response", body, action)
-            decision_id = decision.get("decisionId") if decision else None
-            policy_span.options["decisionId"] = decision_id
-            elapsed = int((time.monotonic() - started) * 1000)
-            policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
-        if decision and decision.get("disposition") == "BLOCK":
-            self._receipt(decision, "SUPPRESSED", elapsed)
-            with self.span("operation", name="response_delivery", input=response, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": False, "applicationOutcome": "SUPPRESSED"}):
-                raise RippletidePolicyBlockedError(action, decision)
-        with self.span("operation", name="response_delivery", input=response, links=[trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], invocation_id=invocation_id, decision_id=decision_id, attributes={"action": action, "executed": True, "applicationOutcome": "DELIVERED", "disposition": decision.get("disposition") if decision else "FALLBACK"}) as delivery_span:
-            self._receipt(decision, "DELIVERED", elapsed)
-            result = deliver(response)
-            delivery_span.set_output(result)
-            return result
+        if hasattr(response, "__next__") or hasattr(response, "__anext__"):
+            span = _Span(self, "operation", "response_delivery", invocationId=invocation_id, attributes={"action": action, "executed": True, "applicationOutcome": "DELIVERED", "decidedAfterDelivery": True}).__enter__()
+            span.detach()
+
+            def finish(chunks: list[Any], _complete: bool) -> dict[str, Any]:
+                text = "".join(chunk for chunk in chunks if isinstance(chunk, str))
+                started = time.monotonic()
+                body = {"invocationId": invocation_id, "request": request, "response": text if text or not chunks else [capture_value(chunk)[0] for chunk in chunks], "context": dict(context or {})}
+                links = [trace.Link(span.native.get_span_context(), {"rippletide.link.type": "follows_from"})]
+                with self.span("policy", name="before_response:rippletide/response", input=body, invocation_id=invocation_id, links=links, attributes={"trigger": "before_response", "action": action, "decidedAfterDelivery": True}) as policy_span:
+                    try:
+                        decision = self._decide("/decide-response", body, action)
+                    except RippletidePolicyDecisionError as error:
+                        self._warn(f"{error}; streamed response already delivered")
+                        decision = None
+                    policy_span.options["decisionId"] = span.options["decisionId"] = decision.get("decisionId") if decision else None
+                    elapsed = int((time.monotonic() - started) * 1000)
+                    policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+                self._receipt(decision, "DELIVERED", elapsed)
+                return {"disposition": decision.get("disposition") if decision else "FALLBACK"}
+
+            return deliver(_TracedStream(span, response, finish))  # type: ignore[arg-type]
+
+        def decide() -> tuple[str, dict[str, Any], Any, Callable[[], None] | None, Callable[[], None] | None]:
+            started = time.monotonic()
+            body = {"invocationId": invocation_id, "request": request, "response": response, "context": dict(context or {})}
+            with self.span("policy", name="before_response:rippletide/response", input=body, invocation_id=invocation_id, attributes={"trigger": "before_response", "action": action}) as policy_span:
+                decision = self._decide("/decide-response", body, action)
+                decision_id = decision.get("decisionId") if decision else None
+                policy_span.options["decisionId"] = decision_id
+                elapsed = int((time.monotonic() - started) * 1000)
+                policy_span.set_output(decision, disposition=decision.get("disposition") if decision else "FALLBACK")
+            options: dict[str, Any] = {"name": "response_delivery", "input": response, "links": [trace.Link(policy_span.native.get_span_context(), {"rippletide.link.type": "depends_on"})], "invocationId": invocation_id, "decisionId": decision_id}
+            if decision and decision.get("disposition") == "BLOCK":
+                self._receipt(decision, "SUPPRESSED", elapsed)
+                with _Span(self, "operation", **options, attributes={"action": action, "executed": False, "applicationOutcome": "SUPPRESSED"}):
+                    raise RippletidePolicyBlockedError(action, decision)
+            options["attributes"] = {"action": action, "executed": True, "applicationOutcome": "DELIVERED", "disposition": decision.get("disposition") if decision else "FALLBACK"}
+            return "operation", options, response, lambda: self._receipt(decision, "DELIVERED", elapsed), None
+
+        return self._guarded(decide, deliver)
 
     def flush(self) -> bool:
         if self.disabled or not self.agent_id or not self.runtime_traces or self._telemetry is None:
@@ -611,7 +809,13 @@ class Rippletide:
         self._ensure_registered()
         return self._telemetry.flush()
 
+    async def aflush(self) -> bool:
+        return await asyncio.to_thread(self.flush)
+
     def shutdown(self) -> None:
         self.flush()
         if self._telemetry:
             self._telemetry.shutdown()
+
+    async def ashutdown(self) -> None:
+        await asyncio.to_thread(self.shutdown)

{rippletide_python-0.2.0 → rippletide_python-0.3.0}/rippletide/telemetry.py

@@ -36,7 +36,8 @@ INDEXED = {
     "streaming": "rippletide.model.streaming", "toolCallIds": "rippletide.model.tool_call_ids", "toolCallCount": "rippletide.model.tool_call_count",
     "captureCompleteness": "rippletide.capture.completeness", "trigger": "rippletide.policy.trigger", "action": "rippletide.policy.action",
     "disposition": "rippletide.policy.disposition", "decisionRoundtripMs": "rippletide.policy.roundtrip_ms", "failOpen": "rippletide.policy.fail_open",
-    "policyFallback": "rippletide.policy.fallback", "executed": "rippletide.action.executed", "applicationOutcome": "rippletide.action.application_outcome",
+    "policyFallback": "rippletide.policy.fallback", "decidedAfterDelivery": "rippletide.policy.decided_after_delivery",
+    "executed": "rippletide.action.executed", "applicationOutcome": "rippletide.action.application_outcome",
     "deliveredItemCount": "rippletide.result.delivered_item_count", "excludedItemCount": "rippletide.result.excluded_item_count",
     "signal": "rippletide.signal", "source": "rippletide.source", "standalone": "rippletide.standalone",
 }

{rippletide_python-0.2.0 → rippletide_python-0.3.0}/rippletide_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rippletide-python
-Version: 0.2.0
+Version: 0.3.0
 Summary: Monitor-first Python SDK for Rippletide-connected agents
 License: UNLICENSED
 Requires-Python: >=3.10
@@ -16,7 +16,7 @@ hand-written provider or internal HTTP call at the existing model seam.
 
 ## Install and connect
 
-The native OTel release candidate is `rippletide-python==0.2.0`. It requires
+The current release is `rippletide-python==0.3.0`. It requires
 the platform's OTLP ingestion/readers and does not provide V1 trace compatibility.
 Until it is published, validate it by installing a locally built wheel; do not
 assume the unversioned registry install below contains candidate changes.
@@ -41,8 +41,7 @@ prompt with your coding agent in that repository. The CLI also supports
 Run a real turn that uses a tool and delivers a response. Confirm **Runtime
 verified (5/5)** in Fleet and the run's tool calls and **Delivered** outcome in
 Activity. Copying a prompt or storing credentials alone does not prove a
-connection. The SDK supports synchronous call sites. Async execution and
-streaming are not supported.
+connection.
 
 ## Instrument existing call sites
 
@@ -85,6 +84,34 @@ connection takes precedence over those legacy values; explicit constructor
 arguments take precedence over either format. Never use a Platform key in the
 agent or commit the `.env`.
 
+## Async and streaming agents
+
+The same client serves synchronous and asyncio code. `guard_tool_call()`,
+`guard_tool_result()` and `deliver_response()` accept `async def` callbacks and
+then return a coroutine to await; the policy round trip and receipts run in a
+worker thread, so the event loop is never blocked. `run()`, `agent()` and
+`span()` are plain `with` blocks in both cases. `traced()` wraps sync
+functions, coroutine functions, and calls that return a provider stream: the
+stream is passed through untouched and its span ends once the stream is
+consumed, closed, or abandoned, in which case the span is marked
+`stream_not_consumed`. Policy decides on the complete response: pass the text
+the agent has assembled from the stream to `deliver_response()` before the
+existing sink delivers it. When the tokens must reach the caller as they arrive,
+pass the stream itself as `response`: chunks flow through to `deliver` untouched
+and the decision is recorded on the assembled text once the stream ends, with no
+suppression possible, so a BLOCK is marked as decided after delivery.
+Use `await rippletide.aflush()` and
+`await rippletide.ashutdown()` from asyncio code.
+
+```python
+async def handle(request):
+    with rippletide.run(name="inbound_request", input=request):
+        stream = rippletide.traced(open_model_stream, name=MODEL_OPERATION, kind="model")(messages)
+        candidate = "".join([chunk.text async for chunk in stream])
+        await rippletide.guard_tool_call(toolset="core", tool="lookup", params=args, execute=lookup_async)
+        return await rippletide.deliver_response(request=request, response=candidate, deliver=send_async)
+```
+
 ## Policy failures and capture
 
 The client starts disabled when no Connection key is present. For
@@ -154,6 +181,6 @@ native response shape, and the SDK records the applied outcome as a receipt.
 Result fingerprints use the server's ECMAScript JSON encoding, including its
 number formatting and UTF-16 object-key ordering.
 
-This first release supports synchronous Python call sites. Python MCP servers,
-async generators, and response streaming remain unsupported rather than being
-silently represented as complete response-delivery protection.
+Python MCP servers remain unsupported. A response that is streamed to the
+caller before it is complete cannot be protected by `deliver_response()`; the
+SDK does not represent such a path as complete response-delivery protection.

{rippletide_python-0.2.0 → rippletide_python-0.3.0}/tests/test_client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import json
 import sys
 import unittest
@@ -74,6 +75,7 @@ class PlatformHandler(BaseHTTPRequestHandler):
     requests: list[tuple[str, dict]] = []
     headers_by_path: dict[str, dict[str, str]] = {}
     disposition = "ALLOW"
+    response_disposition: str | None = None
     result_dispositions: list[str] = ["ALLOW"]
     result_status = 200
 
@@ -96,7 +98,7 @@ class PlatformHandler(BaseHTTPRequestHandler):
             payload = {
                 "decisionId": "00000000-0000-4000-8000-000000000099",
                 "invocationId": body["invocationId"],
-                "disposition": type(self).disposition,
+                "disposition": (type(self).response_disposition if self.path.endswith("-response") else None) or type(self).disposition,
                 "decision": {"reason": "Test policy"},
             }
         else:
@@ -148,6 +150,7 @@ class ClientTests(unittest.TestCase):
         PlatformHandler.requests = []
         PlatformHandler.headers_by_path = {}
         PlatformHandler.disposition = "ALLOW"
+        PlatformHandler.response_disposition = None
         PlatformHandler.result_dispositions = ["ALLOW"]
         PlatformHandler.result_status = 200
         self.client = Rippletide(agent_id=AGENT_ID, api_key="test-connection-key", base_url=self.base_url, name="Raw HTTP agent")
@@ -429,6 +432,136 @@ class ClientTests(unittest.TestCase):
             )
         self.assertEqual(applications, [])
 
+    def test_async_callbacks_keep_action_spans_open_until_they_settle(self):
+        async def turn():
+            async def lookup(params):
+                await asyncio.sleep(0)
+                inner = self.client.traced(lambda: {"plan": "pro"}, name="db.query")
+                return {"account": params["id"], **inner()}
+
+            async def send(value):
+                await asyncio.sleep(0)
+                return f"sent:{value}"
+
+            with self.client.run(name="inbound_request"):
+                result = await self.client.guard_tool_call(toolset="core", tool="lookup", params={"id": "a-1"}, execute=lookup)
+                delivered = await self.client.deliver_response(request={}, response="answer", deliver=send)
+            return result, delivered, await self.client.aflush()
+
+        self.assertEqual(asyncio.run(turn()), ({"account": "a-1", "plan": "pro"}, "sent:answer", True))
+        receipts = [body["outcome"] for path, body in PlatformHandler.requests if path.endswith("/receipt")]
+        self.assertEqual(receipts, ["EXECUTED", "DELIVERED"])
+        events = {(event["name"], event["eventType"]): event for event in runtime_facts(PlatformHandler.requests)}
+        self.assertEqual(events[("lookup", "span_start")]["parentSpanId"], events[("inbound_request", "span_start")]["spanId"])
+        self.assertEqual(events[("db.query", "span_start")]["parentSpanId"], events[("lookup", "span_start")]["spanId"])
+        self.assertEqual(events[("lookup", "span_end")]["decisionId"], events[("before_action:core/lookup", "span_end")]["decisionId"])
+        self.assertEqual(events[("response_delivery", "span_end")]["attributes"]["applicationOutcome"], "DELIVERED")
+
+        PlatformHandler.disposition = "BLOCK"
+
+        async def blocked():
+            with self.client.run():
+                await self.client.guard_tool_call(toolset="core", tool="delete", params={}, execute=lookup)
+
+        async def lookup(_params):
+            self.fail("blocked tool executed")
+
+        with self.assertRaises(RippletidePolicyBlockedError):
+            asyncio.run(blocked())
+
+    def test_traced_streams_end_the_model_span_when_consumed_closed_or_awaited(self):
+        self.client.capture_content = True
+
+        class ProviderStream:
+            response = "raw-http-response"
+
+            def __init__(self, chunks):
+                self.chunks, self.closed = iter(chunks), False
+
+            def __iter__(self):
+                return self
+
+            def __next__(self):
+                return next(self.chunks)
+
+            def close(self):
+                self.closed = True
+
+        async def provider_stream():
+            for chunk in ("a", "b"):
+                yield chunk
+
+        async def async_model():
+            await asyncio.sleep(0)
+            return {"content": "awaited"}
+
+        stream = self.client.traced(lambda: ProviderStream(["x", "y", "z"]), name="model.stream", kind="model")
+        with self.client.run(name="consumed"):
+            consumed = stream()
+            self.assertEqual(consumed.response, "raw-http-response")
+            self.assertEqual(list(consumed), ["x", "y", "z"])
+        with self.client.run(name="abandoned"):
+            abandoned = stream()
+            self.assertEqual(next(abandoned), "x")
+            abandoned.close()
+            self.assertTrue(abandoned.closed)
+
+        async def turn():
+            with self.client.run(name="async"):
+                chunks = [chunk async for chunk in self.client.traced(provider_stream, kind="model")()]
+                return chunks, await self.client.traced(async_model, kind="model")()
+
+        self.assertEqual(asyncio.run(turn()), (["a", "b"], {"content": "awaited"}))
+        self.client.flush()
+        ends = {}
+        for event in runtime_facts(PlatformHandler.requests):
+            if event["eventType"] == "span_end" and event["kind"] == "model":
+                ends[event["name"], event["attributes"].get("captureCompleteness")] = event
+        self.assertEqual(ends["model.stream", "complete"]["output"], ["x", "y", "z"])
+        self.assertEqual(ends["model.stream", "stream_not_consumed"]["output"], ["x"])
+        self.assertEqual(ends["provider_stream", "complete"]["output"], ["a", "b"])
+        self.assertEqual(ends["async_model", "complete"]["output"], {"content": "awaited"})
+        self.assertTrue(all(event["attributes"]["streaming"] for (name, _), event in ends.items() if name != "async_model"))
+        runs = {event["name"]: event["spanId"] for event in runtime_facts(PlatformHandler.requests) if event["kind"] == "run" and event["eventType"] == "span_start"}
+        self.assertEqual(ends["model.stream", "stream_not_consumed"]["parentSpanId"], runs["abandoned"])
+        self.assertEqual(ends["async_model", "complete"]["parentSpanId"], runs["async"])
+
+    def test_streamed_delivery_records_the_decision_after_the_answer_reached_the_caller(self):
+        async def model_stream():
+            for token in ("Hel", "lo"):
+                yield token
+
+        async def lookup(_params):
+            return {"plan": "pro"}
+
+        async def send(stream):
+            return "".join([chunk async for chunk in stream])
+
+        async def turn():
+            with self.client.run(name="streamed_turn"):
+                tokens = [token async for token in self.client.traced(model_stream, kind="model")()]
+                await self.client.guard_tool_call(toolset="core", tool="lookup", params={}, execute=lookup)
+
+                async def answer():
+                    for token in tokens:
+                        yield token
+                return await self.client.deliver_response(request={"q": "hi"}, response=answer(), deliver=send)
+
+        for disposition in ("ALLOW", "BLOCK"):
+            with self.subTest(disposition=disposition):
+                self.setUp()
+                PlatformHandler.response_disposition = disposition
+                self.assertEqual(asyncio.run(turn()), "Hello")
+                self.client.flush()
+                decide = next(body for path, body in PlatformHandler.requests if path == "/v1/policy/decide-response")
+                self.assertEqual(decide["response"], "Hello")
+                self.assertEqual([body["outcome"] for path, body in PlatformHandler.requests if path.endswith("/receipt")], ["EXECUTED", "DELIVERED"])
+                ends = {event["name"]: event for event in runtime_facts(PlatformHandler.requests) if event["eventType"] == "span_end"}
+                self.assertEqual({ends[name]["traceId"] for name in ("model_stream", "lookup", "before_response:rippletide/response", "response_delivery")}, {ends["streamed_turn"]["traceId"]})
+                delivery = ends["response_delivery"]
+                self.assertEqual(delivery["decisionId"], ends["before_response:rippletide/response"]["decisionId"])
+                self.assertEqual({key: delivery["attributes"][key] for key in ("streaming", "applicationOutcome", "disposition", "decidedAfterDelivery", "captureCompleteness")}, {"streaming": True, "applicationOutcome": "DELIVERED", "disposition": disposition, "decidedAfterDelivery": True, "captureCompleteness": "not_captured"})
+
     def test_open_source_manual_agent_uses_raw_anthropic_http_and_exports_the_complete_turn(self):
         example = Path(__file__).parents[3] / "examples/python-anthropic-manual-agent/agent.py"
         spec = spec_from_file_location("manual_agent", example)