steerable-agent-runtime 0.1.0__tar.gz

steerable_agent_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: steerable-agent-runtime
+Version: 0.1.0
+Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
+Requires-Dist: steerable-agent-harness<1.0.0,>=0.1.0
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == "sqlalchemy"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Requires-Dist: starlette>=0.37; extra == "fastapi"
+Provides-Extra: openai
+Requires-Dist: httpx>=0.27; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: sqlalchemy>=2.0; extra == "all"
+Requires-Dist: fastapi>=0.110; extra == "all"
+Requires-Dist: starlette>=0.37; extra == "all"
+Requires-Dist: httpx>=0.27; extra == "all"
+Requires-Dist: anthropic>=0.40; extra == "all"
+
+# steerable-agent-runtime
+
+Tier 3 runtime for the Steerable framework.
+
+Provides four orthogonal pluggable adapters:
+
+- `LLMProvider` — chat-completion / streaming / tool-call abstraction, with
+  reference implementations for OpenAI-compatible servers (covers OpenAI,
+  Ollama, vLLM, SiliconFlow, etc.) and Anthropic native.
+- `ToolRouter` — in-process tool registry. Auto-classifies tools into
+  `ToolMode`s using `steerable_agent_harness.policy`, supports per-tool
+  permission overrides, and dispatches `ToolCall` → `ToolResult`.
+- `StorageAdapter` — persistence interface for `AgentSession`, `ChatMessage`,
+  `ChatAgent`, and `HarnessTrace + spans + events`. Reference impls: in-memory
+  (default for sidecar/dev) and SQLAlchemy (for hosted backends).
+- `TransportAdapter` — wire format. `FastAPISseTransport` exports SSE for
+  hosted setups; `StdioJsonRpcTransport` powers the steerable-sidecar.
+
+The runtime is **Python only** by design — frontends never depend on it
+directly. Browsers/Electron consume runtime output via either the SSE transport
+(over HTTP) or the stdio JSON-RPC transport (sidecar pattern).
+
+## Install
+
+```bash
+pip install steerable-agent-runtime[all]
+```
+
+Selectively install just the bits you need:
+
+```bash
+pip install "steerable-agent-runtime[openai]"
+pip install "steerable-agent-runtime[anthropic]"
+pip install "steerable-agent-runtime[sqlalchemy]"
+pip install "steerable-agent-runtime[fastapi]"
+```

steerable_agent_runtime-0.1.0/README.md

@@ -0,0 +1,36 @@
+# steerable-agent-runtime
+
+Tier 3 runtime for the Steerable framework.
+
+Provides four orthogonal pluggable adapters:
+
+- `LLMProvider` — chat-completion / streaming / tool-call abstraction, with
+  reference implementations for OpenAI-compatible servers (covers OpenAI,
+  Ollama, vLLM, SiliconFlow, etc.) and Anthropic native.
+- `ToolRouter` — in-process tool registry. Auto-classifies tools into
+  `ToolMode`s using `steerable_agent_harness.policy`, supports per-tool
+  permission overrides, and dispatches `ToolCall` → `ToolResult`.
+- `StorageAdapter` — persistence interface for `AgentSession`, `ChatMessage`,
+  `ChatAgent`, and `HarnessTrace + spans + events`. Reference impls: in-memory
+  (default for sidecar/dev) and SQLAlchemy (for hosted backends).
+- `TransportAdapter` — wire format. `FastAPISseTransport` exports SSE for
+  hosted setups; `StdioJsonRpcTransport` powers the steerable-sidecar.
+
+The runtime is **Python only** by design — frontends never depend on it
+directly. Browsers/Electron consume runtime output via either the SSE transport
+(over HTTP) or the stdio JSON-RPC transport (sidecar pattern).
+
+## Install
+
+```bash
+pip install steerable-agent-runtime[all]
+```
+
+Selectively install just the bits you need:
+
+```bash
+pip install "steerable-agent-runtime[openai]"
+pip install "steerable-agent-runtime[anthropic]"
+pip install "steerable-agent-runtime[sqlalchemy]"
+pip install "steerable-agent-runtime[fastapi]"
+```

steerable_agent_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "steerable-agent-runtime"
+version = "0.1.0"
+description = "Steerable agent runtime: LLM, tool, storage, and transport adapters."
+readme = "README.md"
+requires-python = ">=3.10"
+# Pre-1.0 inter-package pins use `>=X,<1.0.0` ranges so release-please can
+# bump individual packages without forcing a coordinated re-pin here.
+# See packages/agent-harness/py/pyproject.toml for the rationale.
+dependencies = [
+  "pydantic>=2.10.0",
+  "steerable-agent-protocol>=0.1.0,<1.0.0",
+  "steerable-agent-harness>=0.1.0,<1.0.0",
+]
+
+[project.optional-dependencies]
+sqlalchemy = ["sqlalchemy>=2.0"]
+fastapi = ["fastapi>=0.110", "starlette>=0.37"]
+openai = ["httpx>=0.27"]
+anthropic = ["anthropic>=0.40"]
+all = [
+  "sqlalchemy>=2.0",
+  "fastapi>=0.110",
+  "starlette>=0.37",
+  "httpx>=0.27",
+  "anthropic>=0.40",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv.sources]
+steerable-agent-protocol = { workspace = true }
+steerable-agent-harness = { workspace = true }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

steerable_agent_runtime-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steerable_agent_runtime-0.1.0/src/steerable_agent_runtime/__init__.py

@@ -0,0 +1,34 @@
+"""Steerable agent runtime — Tier 3 adapter package."""
+
+from .errors import (
+    BudgetExhaustedError,
+    PolicyDeniedError,
+    RuntimeError as SteerableRuntimeError,
+    StorageError,
+    ToolDispatchError,
+    TransportError,
+)
+from .llm import LLMMessage, LLMProvider, LLMStreamChunk, LLMUsage
+from .storage import StorageAdapter
+from .tools import RegisteredTool, ToolRouter, tool
+from .transport import TransportAdapter
+
+__all__ = [
+    "BudgetExhaustedError",
+    "PolicyDeniedError",
+    "SteerableRuntimeError",
+    "StorageError",
+    "ToolDispatchError",
+    "TransportError",
+    "LLMMessage",
+    "LLMProvider",
+    "LLMStreamChunk",
+    "LLMUsage",
+    "RegisteredTool",
+    "ToolRouter",
+    "tool",
+    "StorageAdapter",
+    "TransportAdapter",
+]
+
+__version__ = "0.1.0"

steerable_agent_runtime-0.1.0/src/steerable_agent_runtime/errors.py

@@ -0,0 +1,34 @@
+"""Common runtime exceptions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class RuntimeError(Exception):  # noqa: A001 - intentional override of builtin
+    """Base class for all steerable-agent-runtime errors."""
+
+    def __init__(self, message: str, *, data: Any | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.data = data
+
+
+class StorageError(RuntimeError):
+    """Persistence layer failure."""
+
+
+class ToolDispatchError(RuntimeError):
+    """Tool router could not satisfy a ToolCall."""
+
+
+class PolicyDeniedError(ToolDispatchError):
+    """A tool call was denied by policy (e.g. destructive without consent)."""
+
+
+class BudgetExhaustedError(RuntimeError):
+    """The harness budget would be violated by the next operation."""
+
+
+class TransportError(RuntimeError):
+    """Wire-level failure (SSE close, JSON-RPC parse error, etc.)."""

steerable_agent_runtime-0.1.0/src/steerable_agent_runtime/llm/__init__.py

@@ -0,0 +1,104 @@
+"""LLMProvider interface and reference implementations.
+
+The runtime intentionally keeps LLMProvider small. Higher-level concerns
+(retry, budget, multi-step orchestration) live in `steerable_agent_harness`.
+
+The interface speaks the protocol-level types (`ToolCall`, `ToolResult`,
+`ChatMessage`) but accepts a slightly looser `LLMMessage` shape for inputs so
+callers do not have to materialise full ChatMessage records when constructing
+prompts.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from steerable_agent_protocol.generated import ToolCall
+
+LLMRole = Literal["system", "user", "assistant", "tool"]
+
+
+@dataclass(slots=True)
+class LLMMessage:
+    """A single chat-message item passed to an LLMProvider."""
+
+    role: LLMRole
+    content: str
+    name: str | None = None
+    tool_call_id: str | None = None
+    tool_calls: list[ToolCall] | None = None
+
+
+@dataclass(slots=True)
+class LLMUsage:
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+@dataclass(slots=True)
+class LLMStreamChunk:
+    """Provider-agnostic stream chunk."""
+
+    content_delta: str | None = None
+    reasoning_delta: str | None = None
+    tool_call_delta: ToolCall | None = None
+    finish_reason: str | None = None
+    usage: LLMUsage | None = None
+    raw: Any | None = None
+
+
+@runtime_checkable
+class LLMProvider(Protocol):
+    """Async chat-completion adapter.
+
+    Implementations must support both `complete()` (one-shot) and `stream()`
+    (incremental). Both flavors must:
+      * Accept a sequence of LLMMessage records.
+      * Optionally accept a list of tool descriptors (already in OpenAI
+        function-calling shape; providers that need a different shape transform
+        internally).
+      * Return / yield content alongside any tool calls the model proposed.
+      * Surface usage tokens whenever the upstream provider reports them.
+    """
+
+    name: str
+    model: str
+
+    async def complete(
+        self,
+        messages: Sequence[LLMMessage],
+        *,
+        tools: Iterable[dict[str, Any]] | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> tuple[LLMMessage, LLMUsage]:
+        ...
+
+    def stream(
+        self,
+        messages: Sequence[LLMMessage],
+        *,
+        tools: Iterable[dict[str, Any]] | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[LLMStreamChunk]:
+        ...
+
+
+from .openai_compat import OpenAICompatProvider  # noqa: E402
+from .anthropic_native import AnthropicProvider  # noqa: E402
+
+__all__ = [
+    "LLMMessage",
+    "LLMProvider",
+    "LLMRole",
+    "LLMStreamChunk",
+    "LLMUsage",
+    "OpenAICompatProvider",
+    "AnthropicProvider",
+]

steerable_agent_runtime-0.1.0/src/steerable_agent_runtime/llm/anthropic_native.py

@@ -0,0 +1,261 @@
+"""Anthropic native-protocol provider.
+
+Why a separate provider instead of always using OpenAI-compatible endpoints?
+Some hosted gateways aggressively buffer the OpenAI-compatible SSE stream and
+break true byte-level streaming. Going directly to the Anthropic native
+``/v1/messages`` endpoint (or its vendor mirror) produces sub-second first-byte
+latency under those gateways.
+
+This implementation is intentionally a thin shim around the official
+``anthropic`` Python SDK so we inherit auth, retries, and SSE parsing.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from steerable_agent_protocol.generated import ToolCall
+
+from . import LLMMessage, LLMStreamChunk, LLMUsage
+
+
+@dataclass(slots=True)
+class AnthropicProvider:
+    name: str
+    model: str
+    api_key: str | None = None
+    base_url: str | None = None
+    default_temperature: float | None = None
+    default_max_tokens: int = 1024
+
+    async def complete(
+        self,
+        messages: Sequence[LLMMessage],
+        *,
+        tools: Iterable[dict[str, Any]] | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> tuple[LLMMessage, LLMUsage]:
+        client = self._client()
+        body = self._build_body(
+            messages=messages,
+            tools=tools,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            extra=kwargs,
+        )
+        message = await client.messages.create(**body)
+        text_chunks: list[str] = []
+        tool_calls: list[ToolCall] = []
+        for block in message.content or []:
+            block_type = getattr(block, "type", None)
+            if block_type == "text":
+                text_chunks.append(getattr(block, "text", "") or "")
+            elif block_type == "tool_use":
+                tool_calls.append(
+                    ToolCall(
+                        id=getattr(block, "id", "") or "",
+                        name=getattr(block, "name", "") or "",
+                        arguments=getattr(block, "input", {}) or {},
+                    )
+                )
+        usage = getattr(message, "usage", None)
+        out_usage = LLMUsage(
+            prompt_tokens=int(getattr(usage, "input_tokens", 0) or 0),
+            completion_tokens=int(getattr(usage, "output_tokens", 0) or 0),
+            total_tokens=int(
+                (getattr(usage, "input_tokens", 0) or 0)
+                + (getattr(usage, "output_tokens", 0) or 0)
+            ),
+        )
+        return (
+            LLMMessage(
+                role="assistant",
+                content="".join(text_chunks),
+                tool_calls=tool_calls or None,
+            ),
+            out_usage,
+        )
+
+    async def stream(  # type: ignore[override]
+        self,
+        messages: Sequence[LLMMessage],
+        *,
+        tools: Iterable[dict[str, Any]] | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[LLMStreamChunk]:
+        client = self._client()
+        body = self._build_body(
+            messages=messages,
+            tools=tools,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            extra=kwargs,
+        )
+        async with client.messages.stream(**body) as stream:
+            async for event in stream:
+                chunk = _parse_anthropic_event(event)
+                if chunk is not None:
+                    yield chunk
+            final = await stream.get_final_message()
+            usage = getattr(final, "usage", None)
+            if usage is not None:
+                yield LLMStreamChunk(
+                    usage=LLMUsage(
+                        prompt_tokens=int(getattr(usage, "input_tokens", 0) or 0),
+                        completion_tokens=int(getattr(usage, "output_tokens", 0) or 0),
+                        total_tokens=int(
+                            (getattr(usage, "input_tokens", 0) or 0)
+                            + (getattr(usage, "output_tokens", 0) or 0)
+                        ),
+                    ),
+                    finish_reason="stop",
+                )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _client(self) -> Any:
+        from anthropic import AsyncAnthropic  # local import keeps optional dep optional
+
+        kwargs: dict[str, Any] = {}
+        if self.api_key:
+            kwargs["api_key"] = self.api_key
+        if self.base_url:
+            kwargs["base_url"] = self.base_url
+        return AsyncAnthropic(**kwargs)
+
+    def _build_body(
+        self,
+        *,
+        messages: Sequence[LLMMessage],
+        tools: Iterable[dict[str, Any]] | None,
+        temperature: float | None,
+        max_tokens: int | None,
+        extra: dict[str, Any],
+    ) -> dict[str, Any]:
+        system_text, formatted = _split_system_and_messages(messages)
+        body: dict[str, Any] = {
+            "model": self.model,
+            "messages": formatted,
+            "max_tokens": max_tokens or self.default_max_tokens,
+        }
+        if system_text:
+            body["system"] = system_text
+        eff_temperature = temperature if temperature is not None else self.default_temperature
+        if eff_temperature is not None:
+            body["temperature"] = eff_temperature
+        if tools:
+            anth_tools = [_openai_tool_to_anthropic(t) for t in tools if isinstance(t, dict)]
+            if anth_tools:
+                body["tools"] = anth_tools
+        body.update(extra)
+        return body
+
+
+# ---------------------------------------------------------------------------
+# Helpers (pure functions kept module-level for unit-testability)
+# ---------------------------------------------------------------------------
+
+
+def _split_system_and_messages(
+    messages: Sequence[LLMMessage],
+) -> tuple[str | None, list[dict[str, Any]]]:
+    system_chunks: list[str] = []
+    out: list[dict[str, Any]] = []
+    for message in messages:
+        if message.role == "system":
+            if message.content:
+                system_chunks.append(message.content)
+            continue
+        if message.role == "tool":
+            out.append(
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": message.tool_call_id or "",
+                            "content": message.content,
+                        }
+                    ],
+                }
+            )
+            continue
+        if message.tool_calls:
+            blocks: list[dict[str, Any]] = []
+            if message.content:
+                blocks.append({"type": "text", "text": message.content})
+            for tc in message.tool_calls:
+                blocks.append(
+                    {
+                        "type": "tool_use",
+                        "id": tc.id or "",
+                        "name": tc.name,
+                        "input": tc.arguments or {},
+                    }
+                )
+            out.append({"role": "assistant", "content": blocks})
+            continue
+        out.append({"role": message.role, "content": message.content})
+    system = "\n\n".join(system_chunks) if system_chunks else None
+    return system, out
+
+
+def _openai_tool_to_anthropic(tool: dict[str, Any]) -> dict[str, Any]:
+    if "name" in tool and "input_schema" in tool:
+        return tool  # already anthropic-shaped
+    function = tool.get("function") or {}
+    return {
+        "name": function.get("name") or tool.get("name"),
+        "description": function.get("description") or tool.get("description") or "",
+        "input_schema": function.get("parameters") or {"type": "object", "properties": {}},
+    }
+
+
+def _parse_anthropic_event(event: Any) -> LLMStreamChunk | None:
+    event_type = getattr(event, "type", None)
+    if event_type == "content_block_delta":
+        delta = getattr(event, "delta", None)
+        delta_type = getattr(delta, "type", None)
+        if delta_type == "text_delta":
+            return LLMStreamChunk(content_delta=getattr(delta, "text", "") or None, raw=event)
+        if delta_type == "thinking_delta":
+            return LLMStreamChunk(
+                reasoning_delta=getattr(delta, "thinking", "") or None,
+                raw=event,
+            )
+        if delta_type == "input_json_delta":
+            partial = getattr(delta, "partial_json", "") or ""
+            try:
+                args = json.loads(partial) if partial else {}
+            except json.JSONDecodeError:
+                args = {}
+            return LLMStreamChunk(
+                tool_call_delta=ToolCall(id="", name="", arguments=args),
+                raw=event,
+            )
+    if event_type == "content_block_start":
+        block = getattr(event, "content_block", None)
+        if getattr(block, "type", None) == "tool_use":
+            return LLMStreamChunk(
+                tool_call_delta=ToolCall(
+                    id=getattr(block, "id", "") or "",
+                    name=getattr(block, "name", "") or "",
+                    arguments={},
+                ),
+                raw=event,
+            )
+    if event_type == "message_delta":
+        delta = getattr(event, "delta", None)
+        finish_reason = getattr(delta, "stop_reason", None)
+        if finish_reason:
+            return LLMStreamChunk(finish_reason=str(finish_reason), raw=event)
+    return None