reflex-agentkit 0.1.0__py3-none-any.whl

reflex_agentkit/core/clients/http.py

@@ -0,0 +1,147 @@
+"""``HttpAGUIClient``: AG-UI over HTTP + SSE (API §7.3, §8).
+
+The client POSTs the ``RunAgentInput`` as camelCase JSON and decodes the SSE response
+into validated events. Transport failures become ``AgentHTTPError`` or
+``AgentStreamError``; it never yields a synthetic ``RUN_ERROR``. Headers (often API
+keys) are sent upstream only: they are never logged, stored, or put in an exception
+message (REQ-021.3, REQ-021.6, Constitution Art. 3).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import AsyncIterator, Callable, Mapping
+
+import httpx
+from ag_ui.core import BaseEvent, EventType, RunAgentInput
+
+from reflex_agentkit.core.clients.base import validate_event
+from reflex_agentkit.core.clients.sse import SSEParser
+from reflex_agentkit.core.errors import AgentHTTPError, AgentStreamError
+
+__all__ = ["DEFAULT_TIMEOUT", "HttpAGUIClient"]
+
+logger = logging.getLogger("reflex_agentkit.core.clients.http")
+
+DEFAULT_TIMEOUT = httpx.Timeout(10.0, read=60.0)
+BODY_EXCERPT_BYTES = 1024
+_TERMINAL = frozenset({EventType.RUN_FINISHED, EventType.RUN_ERROR})
+
+HeadersSource = Mapping[str, str] | Callable[[], Mapping[str, str]]
+
+
+class HttpAGUIClient:
+    """Streams a run from an AG-UI HTTP endpoint (REQ-021.2-4, REQ-021.6).
+
+    Safe to share across sessions: it keeps no per-run state.
+
+    Args:
+        url: The AG-UI endpoint.
+        headers: Static headers, or a callable evaluated per run (rotating tokens).
+        timeout: An ``httpx.Timeout`` or seconds; ``read`` bounds the gap between bytes.
+        http_client: A caller-owned ``httpx.AsyncClient``; ``aclose()`` leaves it open.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        headers: HeadersSource | None = None,
+        timeout: httpx.Timeout | float = DEFAULT_TIMEOUT,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._url = url
+        self._headers = headers
+        self._timeout = timeout if isinstance(timeout, httpx.Timeout) else httpx.Timeout(timeout)
+        self._injected = http_client
+        self._owned: httpx.AsyncClient | None = None
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(url={self._url!r})"
+
+    def _client(self) -> httpx.AsyncClient:
+        if self._injected is not None:
+            return self._injected
+        if self._owned is None or self._owned.is_closed:
+            self._owned = httpx.AsyncClient()
+        return self._owned
+
+    def _request_headers(self) -> dict[str, str]:
+        extra = self._headers() if callable(self._headers) else (self._headers or {})
+        return {**extra, "Content-Type": "application/json", "Accept": "text/event-stream"}
+
+    async def stream(self, run_input: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        """POST ``run_input``; yield validated events until a terminal one (API §8.2)."""
+        body = run_input.model_dump_json(by_alias=True, exclude_none=True)
+        try:
+            async with self._client().stream(
+                "POST",
+                self._url,
+                content=body,
+                headers=self._request_headers(),
+                timeout=self._timeout,
+            ) as response:
+                await _check(response)
+                parser = SSEParser()
+                async for chunk in response.aiter_bytes():
+                    for data in parser.feed(chunk):
+                        event = _decode(data)
+                        if event is None:
+                            continue
+                        yield event
+                        if event.type in _TERMINAL:
+                            return
+                parser.finish()
+        except httpx.ReadTimeout:
+            raise AgentStreamError(
+                "timeout", "read timeout: the agent sent nothing in time"
+            ) from None
+        except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
+            raise AgentStreamError(
+                "connect", f"cannot connect to the agent ({type(exc).__name__})"
+            ) from None
+        except httpx.TransportError as exc:
+            raise AgentStreamError(
+                "eof", f"connection to the agent lost ({type(exc).__name__})"
+            ) from None
+        raise AgentStreamError("eof", "stream ended unexpectedly")
+
+    async def aclose(self) -> None:
+        """Close the owned ``httpx.AsyncClient``, if any. Idempotent."""
+        owned, self._owned = self._owned, None
+        if owned is not None:
+            await owned.aclose()
+
+
+async def _check(response: httpx.Response) -> None:
+    """Raise for non-2xx status and non-SSE content types (API §8.2)."""
+    if not response.is_success:
+        excerpt = await _excerpt(response)
+        logger.debug(
+            "agent endpoint returned HTTP %s; body excerpt: %s", response.status_code, excerpt
+        )
+        raise AgentHTTPError(response.status_code)
+    media_type = response.headers.get("content-type", "").split(";", 1)[0].strip().lower()
+    if media_type != "text/event-stream":
+        raise AgentStreamError(
+            "content_type", f"unexpected content type {media_type or '<none>'!r}"
+        )
+
+
+async def _excerpt(response: httpx.Response) -> str:
+    collected = b""
+    async for chunk in response.aiter_bytes():
+        collected += chunk
+        if len(collected) >= BODY_EXCERPT_BYTES:
+            break
+    return collected[:BODY_EXCERPT_BYTES].decode(errors="replace")
+
+
+def _decode(data: str) -> BaseEvent | None:
+    try:
+        raw = json.loads(data)
+    except ValueError:
+        logger.warning("skipped an SSE frame that is not valid JSON")
+        return None
+    return validate_event(raw)

reflex_agentkit/core/clients/in_process.py

@@ -0,0 +1,67 @@
+"""``InProcessAGUIClient``: run an ``AGUIAgent`` in the current event loop (API §7.3).
+
+No HTTP and no serialization: the agent's event objects are validated and passed on
+(REQ-021.5). Cancelling the consumer cancels the agent, which observes
+``CancelledError`` (REQ-007.3). An exception raised by the agent becomes
+``AgentStreamError(reason="agent_raised")`` with the original as ``__cause__``; its
+message names only the exception type, since agent errors may quote secrets.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+from ag_ui.core import BaseEvent, EventType, RunAgentInput
+
+from reflex_agentkit.core.clients.base import AGUIAgent, validate_event
+from reflex_agentkit.core.errors import AgentStreamError, ConfigurationError
+
+__all__ = ["InProcessAGUIClient"]
+
+_TERMINAL = frozenset({EventType.RUN_FINISHED, EventType.RUN_ERROR})
+
+
+class InProcessAGUIClient:
+    """Wraps an in-process ``AGUIAgent`` as an ``AgentClient`` (REQ-021.5).
+
+    Safe to share across sessions as long as the agent is: it keeps no per-run state.
+    """
+
+    def __init__(self, agent: AGUIAgent) -> None:
+        if not isinstance(agent, AGUIAgent):
+            raise ConfigurationError(
+                f"InProcessAGUIClient needs an AGUIAgent (an object with run()), "
+                f"got {type(agent).__name__}"
+            )
+        self._agent = agent
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(agent={type(self._agent).__name__})"
+
+    async def stream(self, run_input: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        """Yield the agent's validated events until a terminal one."""
+        iterator = self._agent.run(run_input)
+        try:
+            while True:
+                try:
+                    raw = await anext(iterator)
+                except StopAsyncIteration:
+                    break
+                except Exception as exc:
+                    raise AgentStreamError(
+                        "agent_raised", f"the agent raised {type(exc).__name__}"
+                    ) from exc
+                event = validate_event(raw)
+                if event is None:
+                    continue
+                yield event
+                if event.type in _TERMINAL:
+                    return
+        finally:
+            closer = getattr(iterator, "aclose", None)  # plain async iterators lack it
+            if closer is not None:
+                await closer()
+        raise AgentStreamError("eof", "the agent's event stream ended unexpectedly")
+
+    async def aclose(self) -> None:
+        """Nothing to release; present for the ``AgentClient`` protocol. Idempotent."""

reflex_agentkit/core/clients/sse.py

@@ -0,0 +1,75 @@
+"""Incremental Server-Sent Events parser (API §8.2, REQ-021.2).
+
+Only the ``data`` field matters: each dispatched frame's data lines are joined with
+``\\n`` and returned. ``event``, ``id``, ``retry``, unknown fields and comments are
+ignored. CRLF, LF and CR line endings are accepted, including a CRLF split across chunks,
+and bytes are decoded incrementally so a UTF-8 character may span chunks. A frame without
+its terminating blank line at EOF is discarded, as the SSE specification requires (a
+lone CR at EOF counts as a complete line ending).
+"""
+
+from __future__ import annotations
+
+import codecs
+
+__all__ = ["SSEParser"]
+
+
+class SSEParser:
+    """Feed byte or str chunks; get back the ``data`` payload of each complete frame."""
+
+    def __init__(self) -> None:
+        self._reset()
+
+    def _reset(self) -> None:
+        self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+        self._buffer = ""
+        self._data: list[str] = []
+        self._started = False
+
+    def feed(self, chunk: bytes | str) -> list[str]:
+        """Consume ``chunk``; return the payloads of the frames it completes."""
+        text = self._decoder.decode(chunk) if isinstance(chunk, bytes) else chunk
+        if not self._started and text:
+            self._started = True
+            text = text.removeprefix("")
+        self._buffer += text
+        frames: list[str] = []
+        while True:
+            line, ending = self._next_line()
+            if ending is None:
+                return frames
+            if line == "":
+                if self._data:
+                    frames.append("\n".join(self._data))
+                    self._data = []
+                continue
+            self._field(line)
+
+    def finish(self) -> list[str]:
+        """End of stream: return a frame a final lone CR completes, drop the rest, reset."""
+        frames = self.feed("\n") if self._buffer.endswith("\r") else []
+        self._reset()
+        return frames
+
+    def _next_line(self) -> tuple[str, str | None]:
+        """Pop one terminated line from the buffer; ``(…, None)`` if none is complete."""
+        buffer = self._buffer
+        for index, char in enumerate(buffer):
+            if char == "\n":
+                self._buffer = buffer[index + 1 :]
+                return buffer[:index], "\n"
+            if char == "\r":
+                if index + 1 == len(buffer):
+                    return "", None  # may be the first half of CRLF; wait for more
+                skip = 2 if buffer[index + 1] == "\n" else 1
+                self._buffer = buffer[index + skip :]
+                return buffer[:index], "\r"
+        return "", None
+
+    def _field(self, line: str) -> None:
+        if line.startswith(":"):
+            return
+        name, _, value = line.partition(":")
+        if name == "data":
+            self._data.append(value.removeprefix(" "))