rippletide-python 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

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/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",
 }
@@ -120,6 +121,9 @@ class _LogExporter(LogRecordExporter):
         self.telemetry.enqueue("logs", otlp_json(encode_logs(records)))
         return LogRecordExportResult.SUCCESS
 
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
     def shutdown(self) -> None:
         pass
 

{rippletide_python-0.2.0.dist-info → rippletide_python-0.3.1.dist-info}/METADATA

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: rippletide-python
-Version: 0.2.0
+Version: 0.3.1
 Summary: Monitor-first Python SDK for Rippletide-connected agents
 License: UNLICENSED
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: opentelemetry-sdk==1.40.0
-Requires-Dist: opentelemetry-exporter-otlp-proto-common==1.40.0
+Requires-Dist: opentelemetry-api<2,>=1.45.1
+Requires-Dist: opentelemetry-sdk<2,>=1.45.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-common<2,>=1.45.1
 
 # Rippletide Python
 
@@ -16,8 +17,11 @@ 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.1`. It requires
 the platform's OTLP ingestion/readers and does not provide V1 trace compatibility.
+It depends on OpenTelemetry Python `>=1.45.1,<2` (API, SDK and OTLP proto
+common), so it does not hold back the agent's own OpenTelemetry or FastAPI
+upgrades.
 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 +45,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 +88,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 +185,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.3.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+rippletide/__init__.py,sha256=lPw2FwwCVSYhMQdQlgZufRLZLZrECKYPvtrMELUxYdI,304
+rippletide/client.py,sha256=3qFew8n5s-Dknjxs_waqh_ixP_t5XiF3GH36POVt4rM,45301
+rippletide/telemetry.py,sha256=riGE6TcdpW0TNpiEW1K4sbVYeYR_kDM23YwoKWBAVVQ,13886
+rippletide_python-0.3.1.dist-info/METADATA,sha256=xTxLnG_8faC51boSa2IN4M1OoE5RJEsrdzGt3E4jh9k,9434
+rippletide_python-0.3.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+rippletide_python-0.3.1.dist-info/top_level.txt,sha256=NAEYCFwQDE0G96JlVKq00OiKb0YLZ_Er8rcAhOiYHzo,11
+rippletide_python-0.3.1.dist-info/RECORD,,

{rippletide_python-0.2.0.dist-info → rippletide_python-0.3.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

rippletide_python-0.2.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-rippletide/__init__.py,sha256=lPw2FwwCVSYhMQdQlgZufRLZLZrECKYPvtrMELUxYdI,304
-rippletide/client.py,sha256=gAxI38pg9a1kNvyV6s_lmfauCNgeGrwOXXM-CEz-cl8,36623
-rippletide/telemetry.py,sha256=oG6YaRZLwUvIshl3egXeMN5ViD5mDMMVWClCvH3nnM0,13729
-rippletide_python-0.2.0.dist-info/METADATA,sha256=k8jWdR_NzOpRbHK4dOhgstK1AiwLsaK65YMcX3gNFoQ,7659
-rippletide_python-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-rippletide_python-0.2.0.dist-info/top_level.txt,sha256=NAEYCFwQDE0G96JlVKq00OiKb0YLZ_Er8rcAhOiYHzo,11
-rippletide_python-0.2.0.dist-info/RECORD,,