reflex-agentkit 0.1.0rc1__py3-none-any.whl

reflex_agentkit/components/composer.py

@@ -0,0 +1,44 @@
+"""``composer``: the message input (API §10, REQ-023.3, REQ-023.9)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import reflex as rx
+
+__all__ = ["composer"]
+
+
+def composer(
+    state: type[Any], *, placeholder: str = "Send a message…", **props: Any
+) -> rx.Component:
+    """A text area and a send button; disabled unless ``state.can_send``.
+
+    Enter submits and Shift+Enter inserts a newline (REQ-023.3).
+    """
+    props.setdefault("width", "100%")
+    return rx.form(
+        rx.hstack(
+            rx.text_area(
+                name="message",
+                placeholder=placeholder,
+                enter_key_submit=True,
+                disabled=~state.can_send,
+                aria_label="Message",
+                width="100%",
+                rows="2",
+                resize="vertical",
+            ),
+            rx.button(
+                rx.icon("send", size=16, aria_hidden="true"),
+                type="submit",
+                disabled=~state.can_send,
+                aria_label="Send message",
+            ),
+            align="end",
+            width="100%",
+        ),
+        on_submit=lambda form: state.send_message(form.to(dict)["message"]),
+        reset_on_submit=True,
+        **props,
+    )

reflex_agentkit/components/messages.py

@@ -0,0 +1,104 @@
+"""``message_list``: the conversation in order (API §10, REQ-023.2, DD-015)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import reflex as rx
+
+from reflex_agentkit.components.tools import ToolRenderer, tool_call_card
+from reflex_agentkit.core.models import ChatMessage, ToolCall
+
+__all__ = ["message_list"]
+
+
+def _markdown(content: rx.Var[str]) -> rx.Component:
+    # Raw HTML is on by default in Reflex 0.10.1; model output must stay text (DD-015).
+    return rx.markdown(content, use_raw=False)
+
+
+def _streaming_indicator(message: rx.Var[ChatMessage]) -> rx.Component:
+    return rx.cond(
+        message.streaming,
+        rx.spinner(size="1", aria_label="Streaming"),
+    )
+
+
+def _tool_cards(
+    state: type[Any], message: rx.Var[ChatMessage], renderers: Mapping[str, ToolRenderer]
+) -> rx.Component:
+    def card(tool_call: rx.Var[ToolCall]) -> rx.Component:
+        return rx.cond(
+            tool_call.parent_message_id == message.id,
+            tool_call_card(state, tool_call, renderers=renderers),
+        )
+
+    return rx.foreach(state.tool_calls, card)
+
+
+def _message(
+    state: type[Any], message: rx.Var[ChatMessage], renderers: Mapping[str, ToolRenderer]
+) -> rx.Component:
+    return rx.match(
+        message.role,
+        (
+            "user",
+            rx.box(
+                rx.text(message.content, white_space="pre-wrap"),
+                align_self="flex-end",
+                background_color=rx.color("accent", 3),
+                padding="0.5em 0.75em",
+                border_radius="0.75em",
+                max_width="80%",
+                aria_label="User message",
+            ),
+        ),
+        (
+            "assistant",
+            rx.vstack(
+                rx.cond(
+                    message.reasoning,
+                    rx.el.details(
+                        rx.el.summary("Reasoning"),
+                        rx.text(message.reasoning, size="1", color_scheme="gray"),
+                    ),
+                ),
+                rx.cond(message.content, _markdown(message.content)),
+                _streaming_indicator(message),
+                _tool_cards(state, message, renderers),
+                align_self="flex-start",
+                width="100%",
+                spacing="2",
+                aria_label="Assistant message",
+            ),
+        ),
+        (
+            "tool",
+            rx.el.details(
+                rx.el.summary("Tool result"),
+                rx.el.pre(message.content, style={"white_space": "pre-wrap"}),
+                aria_label="Tool message",
+            ),
+        ),
+        rx.fragment(),
+    )
+
+
+def message_list(
+    state: type[Any], *, tool_renderers: Mapping[str, ToolRenderer] | None = None, **props: Any
+) -> rx.Component:
+    """User, assistant and tool messages in order, with tool calls under their message.
+
+    Assistant text is rendered as markdown without raw HTML (DD-015); tool arguments and
+    results are plain text.
+    """
+    renderers = dict(tool_renderers or {})
+    props.setdefault("width", "100%")
+    props.setdefault("spacing", "3")
+    return rx.vstack(
+        rx.foreach(state.messages, lambda m: _message(state, m, renderers)),
+        role="log",
+        aria_live="polite",
+        **props,
+    )

reflex_agentkit/components/shared_state.py

@@ -0,0 +1,32 @@
+"""``shared_state_panel`` (API §10, REQ-023.7)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import reflex as rx
+
+__all__ = ["shared_state_panel"]
+
+
+def shared_state_panel(state: type[Any], **props: Any) -> rx.Component:
+    """The shared state as JSON, with a marker while it is stale."""
+    props.setdefault("width", "100%")
+    return rx.card(
+        rx.vstack(
+            rx.hstack(
+                rx.text("Shared state", weight="medium", size="2"),
+                rx.cond(
+                    state.shared_state_stale,
+                    rx.badge("stale", color_scheme="amber", aria_label="Shared state is stale"),
+                ),
+                align="center",
+            ),
+            rx.el.pre(
+                state.shared_state.to_string(),
+                style={"white_space": "pre-wrap", "word_break": "break-word"},
+            ),
+            spacing="2",
+        ),
+        **props,
+    )

reflex_agentkit/components/status.py

@@ -0,0 +1,41 @@
+"""``run_status_bar`` (API §10, REQ-023.6)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import reflex as rx
+
+__all__ = ["run_status_bar"]
+
+
+def run_status_bar(state: type[Any], **props: Any) -> rx.Component:
+    """The run status and step, a cancel button while running, and the error."""
+    props.setdefault("width", "100%")
+    return rx.vstack(
+        rx.hstack(
+            rx.badge(state.run_status, variant="soft", aria_label="Run status"),
+            rx.cond(state.is_running, rx.spinner(size="1", aria_label="Running")),
+            rx.cond(state.current_step != "", rx.text(state.current_step, size="1")),
+            rx.spacer(),
+            rx.cond(
+                state.is_running,
+                rx.button(
+                    "Cancel",
+                    on_click=state.cancel_run,
+                    variant="soft",
+                    color_scheme="red",
+                    size="1",
+                    aria_label="Cancel run",
+                ),
+            ),
+            align="center",
+            width="100%",
+        ),
+        rx.cond(
+            state.error != "",
+            rx.callout(state.error, icon="triangle_alert", color_scheme="red", role="alert"),
+        ),
+        spacing="2",
+        **props,
+    )

reflex_agentkit/components/tools.py

@@ -0,0 +1,97 @@
+"""``tool_call_card``: one tool call with its status (API §10, REQ-019, REQ-023.4, DD-013)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import reflex as rx
+
+from reflex_agentkit.core.models import ToolCall
+
+__all__ = ["ToolRenderer", "tool_call_card"]
+
+ToolRenderer = Callable[[rx.Var[ToolCall]], rx.Component]
+
+_BADGE_COLORS: dict[str, str] = {
+    "streaming": "gray",
+    "pending_approval": "amber",
+    "running": "blue",
+    "done": "green",
+    "rejected": "orange",
+    "error": "red",
+}
+
+
+def _section(title: str, content: rx.Var[Any]) -> rx.Component:
+    """A collapsible section whose content is shown as plain text, never markup (DD-015)."""
+    return rx.el.details(
+        rx.el.summary(title),
+        rx.el.pre(content, style={"white_space": "pre-wrap", "word_break": "break-word"}),
+    )
+
+
+def default_tool_body(tool_call: rx.Var[ToolCall]) -> rx.Component:
+    """Arguments and result as collapsible text sections (REQ-023.4)."""
+    return rx.vstack(
+        _section("Arguments", tool_call.args_text),
+        rx.cond(tool_call.result, _section("Result", tool_call.result)),
+        spacing="1",
+        width="100%",
+    )
+
+
+def _status_badge(tool_call: rx.Var[ToolCall]) -> rx.Component:
+    color = rx.match(
+        tool_call.status,
+        *((status, color) for status, color in _BADGE_COLORS.items()),
+        "gray",
+    )
+    return rx.badge(tool_call.status, color_scheme=color, variant="soft")
+
+
+def tool_call_card(
+    state: type[Any],
+    tool_call: rx.Var[ToolCall],
+    *,
+    body: ToolRenderer | None = None,
+    renderers: Mapping[str, ToolRenderer] | None = None,
+    **props: Any,
+) -> rx.Component:
+    """A card with the tool name, a status badge and a body (API §10).
+
+    Args:
+        state: The ``AgentState`` subclass (kept for a uniform signature).
+        tool_call: The tool call var, usually from ``rx.foreach``.
+        body: Replaces the default body for every call rendered by this card.
+        renderers: Body renderers by tool name, resolved at compile time with
+            ``rx.match`` (DD-013); other names use the default body.
+        props: Standard Reflex props for the root element.
+    """
+    del state
+    if body is not None:
+        content = body(tool_call)
+    elif renderers:
+        content = rx.match(
+            tool_call.name,
+            *((name, render(tool_call)) for name, render in renderers.items()),
+            default_tool_body(tool_call),
+        )
+    else:
+        content = default_tool_body(tool_call)
+    props.setdefault("width", "100%")
+    return rx.card(
+        rx.vstack(
+            rx.hstack(
+                rx.icon("wrench", size=14, aria_hidden="true"),
+                rx.text(tool_call.name, weight="medium", size="2"),
+                _status_badge(tool_call),
+                align="center",
+                spacing="2",
+            ),
+            content,
+            spacing="2",
+            width="100%",
+        ),
+        **props,
+    )

reflex_agentkit/core/__init__.py

@@ -0,0 +1,56 @@
+"""Pure core: AG-UI models, reducer and clients. Must never import reflex or any extra."""
+
+from reflex_agentkit.core.clients import (
+    AgentClient,
+    AgentSource,
+    AGUIAgent,
+    HttpAGUIClient,
+    InProcessAGUIClient,
+)
+from reflex_agentkit.core.conversation import ConversationState
+from reflex_agentkit.core.errors import (
+    AdapterNotInstalledError,
+    AgentHTTPError,
+    AgentKitError,
+    AgentStreamError,
+    ConfigurationError,
+    ErrorCode,
+)
+from reflex_agentkit.core.models import (
+    ChatMessage,
+    CustomEventRecord,
+    Diagnostic,
+    PendingInterrupt,
+    RunStatus,
+    ToolCall,
+    ToolCallStatus,
+)
+from reflex_agentkit.core.reducer import reduce
+from reflex_agentkit.core.run_input import RunInputBuilder
+from reflex_agentkit.core.tools import ClientTool, client_tool
+
+__all__ = [
+    "AGUIAgent",
+    "AdapterNotInstalledError",
+    "AgentClient",
+    "AgentHTTPError",
+    "AgentKitError",
+    "AgentSource",
+    "AgentStreamError",
+    "ChatMessage",
+    "ClientTool",
+    "ConfigurationError",
+    "ConversationState",
+    "CustomEventRecord",
+    "Diagnostic",
+    "ErrorCode",
+    "HttpAGUIClient",
+    "InProcessAGUIClient",
+    "PendingInterrupt",
+    "RunInputBuilder",
+    "RunStatus",
+    "ToolCall",
+    "ToolCallStatus",
+    "client_tool",
+    "reduce",
+]

reflex_agentkit/core/_log.py

@@ -0,0 +1,47 @@
+"""Library logging (TD §7.1, REQ-027).
+
+Every logger lives under ``reflex_agentkit``. Run-scoped records go through
+:class:`RunLogger`, which puts ``thread_id`` and ``run_id`` both in the message prefix
+and as record attributes (REQ-027.1). Message contents, tool args and results are only
+ever logged at DEBUG (REQ-027.2).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import MutableMapping
+from typing import Any
+
+__all__ = ["LOGGER_NAME", "RunLogger", "get_logger"]
+
+LOGGER_NAME = "reflex_agentkit"
+
+
+def get_logger(name: str) -> logging.Logger:
+    """The child logger ``reflex_agentkit.<name>``."""
+    return logging.getLogger(f"{LOGGER_NAME}.{name}")
+
+
+class RunLogger(logging.LoggerAdapter[logging.Logger]):
+    """Adds the run context to every record."""
+
+    def __init__(self, logger: logging.Logger, *, thread_id: str, run_id: str) -> None:
+        super().__init__(logger, {"thread_id": thread_id, "run_id": run_id})
+
+    def with_run(self, run_id: str) -> RunLogger:
+        """The same logger for a follow-up run of the thread."""
+        return RunLogger(self.logger, thread_id=self.thread_id, run_id=run_id)
+
+    @property
+    def thread_id(self) -> str:
+        return str((self.extra or {})["thread_id"])
+
+    @property
+    def run_id(self) -> str:
+        return str((self.extra or {})["run_id"])
+
+    def process(
+        self, msg: Any, kwargs: MutableMapping[str, Any]
+    ) -> tuple[Any, MutableMapping[str, Any]]:
+        kwargs["extra"] = {**(self.extra or {}), **kwargs.get("extra", {})}
+        return f"[thread={self.thread_id} run={self.run_id}] {msg}", kwargs

reflex_agentkit/core/_patch.py

@@ -0,0 +1,46 @@
+"""Typed façade over ``jsonpatch`` for RFC 6902 shared-state deltas (TD DD-007).
+
+This is the only module that imports ``jsonpatch``. Patches are applied to a deep copy,
+so a failure anywhere leaves the caller's document untouched (REQ-016.3).
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import jsonpatch  # type: ignore[import-untyped]  # jsonpatch ships no stubs (DD-007, Art. 7)
+
+from reflex_agentkit.core.models import JsonObject
+
+__all__ = ["PatchError", "apply_patch"]
+
+_PATCH_FAILURES: tuple[type[BaseException], ...] = (
+    jsonpatch.JsonPatchException,
+    jsonpatch.JsonPointerException,
+    AttributeError,
+    IndexError,
+    KeyError,
+    RecursionError,  # pathologically deep documents or values
+    TypeError,
+    ValueError,
+)
+
+
+class PatchError(Exception):
+    """An RFC 6902 patch could not be applied; the input is unchanged."""
+
+
+def apply_patch(doc: JsonObject, ops: list[JsonObject]) -> JsonObject:
+    """Apply ``ops`` atomically to a deep copy of ``doc`` and return the result.
+
+    Raises:
+        PatchError: on any failure (bad path, failed ``test`` op, malformed operation,
+            or a result that is not a JSON object).
+    """
+    try:
+        result: Any = jsonpatch.apply_patch(doc, ops, in_place=False)
+    except _PATCH_FAILURES as exc:
+        raise PatchError(f"JSON Patch failed: {exc}") from exc
+    if not isinstance(result, dict):
+        raise PatchError("JSON Patch failed: the result is not a JSON object")
+    return cast(JsonObject, result)

reflex_agentkit/core/clients/__init__.py

@@ -0,0 +1,14 @@
+"""AG-UI clients (HTTP/SSE and in-process) and the protocols they implement."""
+
+from reflex_agentkit.core.clients.base import AgentClient, AgentSource, AGUIAgent, validate_event
+from reflex_agentkit.core.clients.http import HttpAGUIClient
+from reflex_agentkit.core.clients.in_process import InProcessAGUIClient
+
+__all__ = [
+    "AGUIAgent",
+    "AgentClient",
+    "AgentSource",
+    "HttpAGUIClient",
+    "InProcessAGUIClient",
+    "validate_event",
+]

reflex_agentkit/core/clients/base.py

@@ -0,0 +1,71 @@
+"""Client protocols and validated event decoding (API §7.1-7.2).
+
+``AGUIAgent`` is what adapters implement (they yield AG-UI events for a run input);
+``AgentClient`` is what ``AgentState`` consumes. Both are runtime-checkable, so
+``AgentState.agent`` can hold either (``AgentSource``). Clients validate every event
+with :func:`validate_event`, which skips and logs anything invalid (REQ-012.2-3).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from typing import Protocol, TypeAlias, runtime_checkable
+
+from ag_ui.core import BaseEvent, RunAgentInput
+
+from reflex_agentkit.core.models import Diagnostic
+from reflex_agentkit.core.reducer import parse_event
+
+__all__ = ["AGUIAgent", "AgentClient", "AgentSource", "validate_event"]
+
+logger = logging.getLogger("reflex_agentkit.core.clients")
+
+_LEVELS = {"debug": logging.DEBUG, "info": logging.INFO, "warning": logging.WARNING}
+
+
+@runtime_checkable
+class AGUIAgent(Protocol):
+    """An in-process agent that yields AG-UI events for a run (API §7.1)."""
+
+    def run(self, run_input: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        """Yield the run's events, from ``RUN_STARTED`` to one terminal event."""
+        ...
+
+
+@runtime_checkable
+class AgentClient(Protocol):
+    """The transport ``AgentState`` streams from (API §7.2)."""
+
+    def stream(self, run_input: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        """Yield validated events; raise ``AgentHTTPError``/``AgentStreamError`` on failure."""
+        ...
+
+    async def aclose(self) -> None:
+        """Release pooled resources. Idempotent."""
+        ...
+
+
+AgentSource: TypeAlias = AgentClient | AGUIAgent
+"""What ``AgentState.agent`` accepts; an ``AGUIAgent`` is wrapped in-process."""
+
+
+def validate_event(raw: object) -> BaseEvent | None:
+    """Validate a wire dict or an event object; ``None`` (logged) if it must be skipped.
+
+    Event objects are re-validated through their camelCase dump, so events built with
+    ``model_construct`` cannot bypass the schema (REQ-012.3).
+    """
+    if isinstance(raw, BaseEvent):
+        try:
+            raw = raw.model_dump(mode="json", by_alias=True, exclude_none=True, warnings=False)
+        except (TypeError, ValueError) as exc:  # pragma: no cover - defensive
+            logger.warning(
+                "skipped an AG-UI event that cannot be serialized: %s", type(exc).__name__
+            )
+            return None
+    result = parse_event(raw)
+    if isinstance(result, Diagnostic):
+        logger.log(_LEVELS.get(result.level, logging.WARNING), "%s", result.message)
+        return None
+    return result