steerable-agent-runtime 0.1.0__py3-none-any.whl

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/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/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/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

steerable_agent_runtime/llm/openai_compat.py

@@ -0,0 +1,256 @@
+"""OpenAI-compatible chat-completions provider.
+
+Covers the OpenAI API itself plus any vendor that exposes a `/chat/completions`
+endpoint matching the OpenAI v1 schema:
+
+  * Ollama (`http://localhost:11434/v1`)
+  * vLLM
+  * SiliconFlow
+  * DeepSeek
+  * 万界 wanjiedata (OpenAI-compatible path)
+
+The implementation is dependency-light: it uses `httpx` directly so end users do
+not need to install the heavyweight `openai` SDK.
+"""
+
+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 OpenAICompatProvider:
+    """OpenAI-compatible chat-completions provider."""
+
+    name: str
+    model: str
+    base_url: str
+    api_key: str | None = None
+    default_temperature: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.base_url:
+            raise ValueError("OpenAICompatProvider requires base_url")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    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]:
+        import httpx  # local import — keeps the runtime importable without httpx
+
+        body = self._build_body(
+            messages=messages,
+            tools=tools,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=False,
+            extra=kwargs,
+        )
+        async with httpx.AsyncClient(timeout=httpx.Timeout(60.0)) as client:
+            response = await client.post(
+                f"{self.base_url.rstrip('/')}/chat/completions",
+                headers=self._headers(),
+                json=body,
+            )
+            response.raise_for_status()
+            payload = response.json()
+
+        choice = payload["choices"][0]
+        message = choice["message"]
+        usage = payload.get("usage") or {}
+        out = LLMMessage(
+            role="assistant",
+            content=message.get("content") or "",
+            tool_calls=_decode_tool_calls(message.get("tool_calls")),
+        )
+        return out, LLMUsage(
+            prompt_tokens=int(usage.get("prompt_tokens", 0) or 0),
+            completion_tokens=int(usage.get("completion_tokens", 0) or 0),
+            total_tokens=int(usage.get("total_tokens", 0) or 0),
+        )
+
+    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]:
+        import httpx
+
+        body = self._build_body(
+            messages=messages,
+            tools=tools,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+            extra=kwargs,
+        )
+        async with httpx.AsyncClient(timeout=httpx.Timeout(None)) as client:
+            async with client.stream(
+                "POST",
+                f"{self.base_url.rstrip('/')}/chat/completions",
+                headers=self._headers(),
+                json=body,
+            ) as response:
+                response.raise_for_status()
+                async for line in response.aiter_lines():
+                    if not line:
+                        continue
+                    if line.startswith(":"):  # comment/keepalive
+                        continue
+                    if line.startswith("data:"):
+                        line = line[5:].strip()
+                    if line == "[DONE]":
+                        return
+                    try:
+                        chunk = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    parsed = _parse_stream_chunk(chunk)
+                    if parsed is not None:
+                        yield parsed
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _build_body(
+        self,
+        *,
+        messages: Sequence[LLMMessage],
+        tools: Iterable[dict[str, Any]] | None,
+        temperature: float | None,
+        max_tokens: int | None,
+        stream: bool,
+        extra: dict[str, Any],
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "model": self.model,
+            "messages": [_encode_message(m) for m in messages],
+            "stream": stream,
+        }
+        eff_temperature = temperature if temperature is not None else self.default_temperature
+        if eff_temperature is not None:
+            body["temperature"] = eff_temperature
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+        if tools is not None:
+            tools_list = list(tools)
+            if tools_list:
+                body["tools"] = tools_list
+        body.update(extra)
+        return body
+
+
+# ---------------------------------------------------------------------------
+# Wire-format helpers (kept pure functions for unit-testability)
+# ---------------------------------------------------------------------------
+
+
+def _encode_message(message: LLMMessage) -> dict[str, Any]:
+    out: dict[str, Any] = {"role": message.role, "content": message.content}
+    if message.name is not None:
+        out["name"] = message.name
+    if message.tool_call_id is not None:
+        out["tool_call_id"] = message.tool_call_id
+    if message.tool_calls:
+        out["tool_calls"] = [
+            {
+                "id": tc.id,
+                "type": "function",
+                "function": {
+                    "name": tc.name,
+                    "arguments": json.dumps(tc.arguments),
+                },
+            }
+            for tc in message.tool_calls
+        ]
+    return out
+
+
+def _decode_tool_calls(value: Any) -> list[ToolCall] | None:
+    if not value:
+        return None
+    out: list[ToolCall] = []
+    for item in value:
+        function = item.get("function") or {}
+        try:
+            arguments = json.loads(function.get("arguments") or "{}")
+        except (TypeError, json.JSONDecodeError):
+            arguments = {}
+        out.append(
+            ToolCall(
+                id=item.get("id") or "",
+                name=function.get("name") or "",
+                arguments=arguments,
+            )
+        )
+    return out or None
+
+
+def _parse_stream_chunk(chunk: dict[str, Any]) -> LLMStreamChunk | None:
+    choices = chunk.get("choices") or []
+    if not choices:
+        usage = chunk.get("usage")
+        if usage:
+            return LLMStreamChunk(
+                usage=LLMUsage(
+                    prompt_tokens=int(usage.get("prompt_tokens", 0) or 0),
+                    completion_tokens=int(usage.get("completion_tokens", 0) or 0),
+                    total_tokens=int(usage.get("total_tokens", 0) or 0),
+                ),
+                raw=chunk,
+            )
+        return None
+
+    choice = choices[0]
+    delta = choice.get("delta") or {}
+    finish_reason = choice.get("finish_reason")
+    content = delta.get("content")
+    reasoning = delta.get("reasoning_content")
+    tool_call_delta: ToolCall | None = None
+    raw_tool_calls = delta.get("tool_calls")
+    if raw_tool_calls:
+        first = raw_tool_calls[0]
+        function = first.get("function") or {}
+        try:
+            arguments = json.loads(function.get("arguments") or "{}")
+        except (TypeError, json.JSONDecodeError):
+            arguments = {}
+        tool_call_delta = ToolCall(
+            id=first.get("id") or "",
+            name=function.get("name") or "",
+            arguments=arguments,
+        )
+    return LLMStreamChunk(
+        content_delta=content,
+        reasoning_delta=reasoning,
+        tool_call_delta=tool_call_delta,
+        finish_reason=finish_reason,
+        raw=chunk,
+    )