zu-providers 0.1.0__tar.gz

zu_providers-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Test / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Zu runtime artifacts
+*.db
+zu.db
+zu.yaml.local
+zu_review.jsonl
+*.review.jsonl
+# Per-agent cost telemetry ledger — machine-local run history, not source.
+cost.jsonl
+# A recorded replay path is learned per-run and machine-local — regenerated on
+# every successful run, not source. The agent ships; its track does not.
+track.json
+# …except the flagship example ships its track on purpose, as a demo of the
+# record/replay convergence (committed; re-runs show as ordinary modifications).
+!examples/agents/vet-appointment/track.json
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Claude Code local session state
+.claude/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Microsoft Office temp/lock files
+~$*
+
+# Internal design / strategy docs — kept local, never in the public repo
+*.docx
+*.pdf
+# BUILD.md is the internal build-sequence / deferred-gaps ledger — kept local.
+# (ARCHITECTURE.md is public: an onboarding agent needs the structural map.)
+docs/BUILD.md
+
+# Local secret — API key for live validation, never commit
+zu_demo_key.md
+*_key.md

zu_providers-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: zu-providers
+Version: 0.1.0
+Summary: Zu model-provider adapters: scripted, anthropic, openai-compatible
+Project-URL: Homepage, https://github.com/k3-mt/zu
+Project-URL: Repository, https://github.com/k3-mt/zu
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: zu-core==0.1.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'

zu_providers-0.1.0/README.md

@@ -0,0 +1,31 @@
+# zu-providers
+
+Model adapters — the **`ModelProvider`** port (the any-model seam). An adapter
+turns the harness's one normalized `ModelRequest` into a `ModelResponse` (text +
+tool calls + usage + finish reason) and declares its `Capabilities`. The core
+never special-cases a provider; it reads capabilities and proceeds.
+
+**Credentials are resolved from the environment inside the adapter** — never
+placed in the model's context or in a config file.
+
+## Registered plugins (`zu.providers`)
+
+| Name | Class | Notes |
+|------|-------|-------|
+| `scripted` | `ScriptedProvider` | The fake model: replays fixed moves in order. Deterministic; the basis of every offline test. No key, no network. |
+| `anthropic` | `AnthropicProvider` | The Anthropic Messages API. Needs `[anthropic]` SDK extra + an API key. |
+| `openai-compatible` | `OpenAICompatibleProvider` | Any OpenAI-compatible endpoint (OpenAI, OpenRouter, Ollama, vLLM) via a base URL. Needs `[openai]` SDK extra. |
+
+`_messages.py` holds the shared request/response translation both real adapters
+build on, so they behave identically against the neutral contract.
+
+## Extend
+
+Implement the `ModelProvider` shape, register it under `zu.providers` in
+`pyproject.toml`, and add a deterministic test (the contract test asserts every
+adapter behaves identically on the neutral surface).
+
+## Tests
+
+`uv run pytest packages/zu-providers` — offline. Live-API smoke tests are opt-in
+behind `ZU_LIVE_*` env flags.

zu_providers-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "zu-providers"
+version = "0.1.0"
+description = "Zu model-provider adapters: scripted, anthropic, openai-compatible"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = ["zu-core==0.1.0"]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40"]
+openai = ["openai>=1.40"]
+
+[project.entry-points."zu.providers"]
+scripted = "zu_providers.scripted:ScriptedProvider"
+anthropic = "zu_providers.anthropic:AnthropicProvider"
+openai-compatible = "zu_providers.openai_compatible:OpenAICompatibleProvider"
+
+[project.urls]
+Homepage = "https://github.com/k3-mt/zu"
+Repository = "https://github.com/k3-mt/zu"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zu_providers"]

zu_providers-0.1.0/src/zu_providers/__init__.py

@@ -0,0 +1,12 @@
+"""Zu model-provider adapters.
+
+Every adapter implements the ModelProvider port: it turns a normalized
+ModelRequest into a ModelResponse and declares its Capabilities. The harness
+never imports a model SDK — it speaks only the port.
+"""
+
+from __future__ import annotations
+
+from .scripted import ScriptedProvider
+
+__all__ = ["ScriptedProvider"]

zu_providers-0.1.0/src/zu_providers/_messages.py

@@ -0,0 +1,179 @@
+"""Translate Zu's neutral message format into each provider's wire format.
+
+The loop speaks one neutral shape (pinned by ``test_message_format_is_stable``):
+
+    {"role": "system" | "user", "content": "<text>"}
+    {"role": "assistant", "tool_calls": [{"name": ..., "args": {...}}, ...],
+                          "content": "<optional reasoning text>"}
+    {"role": "tool", "name": ..., "content": "<json string>"}
+
+An assistant tool-call turn MAY carry ``content`` (the model's reasoning emitted
+alongside the calls); it is preserved into each wire format (a leading Anthropic
+text block / an OpenAI ``content`` field) and omitted when empty.
+
+Crucially the neutral form carries **no tool-call ids** — an assistant turn's
+tool calls and the ``tool`` results that follow are matched by *order*. Both
+provider wire formats require ids (Anthropic ``tool_use.id`` ↔
+``tool_result.tool_use_id``; OpenAI ``tool_calls[].id`` ↔ ``tool.tool_call_id``),
+so we synthesize ids on the assistant turn and assign them to the following
+results FIFO. This is safe because the loop emits one assistant-tool turn
+immediately followed by its results, in order.
+"""
+
+from __future__ import annotations
+
+import json
+
+
+class _ToolIds:
+    """The shared id bookkeeping both translators need: synthesize a fresh id per
+    tool call on an assistant turn, then match the following ``tool`` results to
+    those ids FIFO. Both wire formats require ids on a matched pair; the neutral
+    form carries none, so order is the contract (see the module docstring).
+
+    Failing loudly here — rather than fabricating or dropping an id — turns a
+    malformed history into a clear local ValueError instead of an opaque provider
+    400 (``tool_result references unknown tool_use_id`` / a tool message with no
+    matching call). The mismatch is *symmetric*: too many results (a result with
+    no pending call) and too few (calls left unmatched at the end) both raise."""
+
+    def __init__(self, prefix: str) -> None:
+        self._prefix = prefix
+        self._counter = 0
+        self._pending: list[str] = []
+
+    def open_calls(self, n: int) -> list[str]:
+        """Begin an assistant tool-call turn: mint ``n`` fresh ids, replacing any
+        still-pending ones (the loop emits a turn's results before the next turn,
+        so anything left here is the too-few case, caught by ``finish``)."""
+        self._pending = []
+        for _ in range(n):
+            self._counter += 1
+            self._pending.append(f"{self._prefix}{self._counter}")
+        return list(self._pending)
+
+    def match_result(self) -> str:
+        """Claim the next pending id for a ``tool`` result. Raises if there is no
+        preceding tool call to match — more results than calls (out of order, or
+        a stray result)."""
+        if not self._pending:
+            raise ValueError(
+                "tool result has no matching tool call in the message history "
+                "(an assistant tool-call turn must immediately precede its results)"
+            )
+        return self._pending.pop(0)
+
+    def finish(self) -> None:
+        """End of history: every opened tool call must have been matched. Leftover
+        pending ids mean fewer results than calls — the mirror of ``match_result``,
+        and just as much a malformed history, so it fails just as loudly."""
+        if self._pending:
+            raise ValueError(
+                f"{len(self._pending)} tool call(s) have no matching tool result in "
+                "the message history (each tool call must be followed by its result)"
+            )
+
+
+def to_anthropic_messages(messages: list[dict]) -> tuple[str | None, list[dict]]:
+    """Return ``(system, messages)`` for the Anthropic Messages API.
+
+    System turns are concatenated into the separate ``system`` parameter
+    (Anthropic keeps system out of ``messages``). Tool results are gathered into
+    a single ``user`` turn of ``tool_result`` blocks, as the API expects."""
+    system_parts: list[str] = []
+    out: list[dict] = []
+    ids = _ToolIds("toolu_")
+    pending_results: list[dict] = []  # tool_result blocks to flush as one user turn
+
+    def flush() -> None:
+        nonlocal pending_results
+        if pending_results:
+            out.append({"role": "user", "content": pending_results})
+            pending_results = []
+
+    for m in messages:
+        role = m.get("role")
+        if role == "system":
+            system_parts.append(str(m.get("content", "")))
+        elif role == "user":
+            flush()
+            out.append({"role": "user", "content": m.get("content", "")})
+        elif role == "assistant":
+            flush()
+            calls = m.get("tool_calls")
+            if calls:
+                tids = ids.open_calls(len(calls))
+                blocks: list[dict] = []
+                # A leading text block preserves the model's reasoning emitted
+                # with the tool calls; Anthropic accepts text before tool_use.
+                text = m.get("content")
+                if text:
+                    blocks.append({"type": "text", "text": str(text)})
+                blocks += [
+                    {"type": "tool_use", "id": tid, "name": c["name"], "input": c.get("args", {})}
+                    for tid, c in zip(tids, calls, strict=True)
+                ]
+                out.append({"role": "assistant", "content": blocks})
+            else:
+                out.append({"role": "assistant", "content": m.get("content", "")})
+        elif role == "tool":
+            pending_results.append(
+                {"type": "tool_result", "tool_use_id": ids.match_result(), "content": m.get("content", "")}
+            )
+    ids.finish()
+    flush()
+    system = "\n\n".join(p for p in system_parts if p) or None
+    return system, out
+
+
+def to_openai_messages(messages: list[dict]) -> list[dict]:
+    """Return messages for the OpenAI Chat Completions API (system stays inline)."""
+    out: list[dict] = []
+    ids = _ToolIds("call_")
+
+    for m in messages:
+        role = m.get("role")
+        if role in ("system", "user"):
+            out.append({"role": role, "content": m.get("content", "")})
+        elif role == "assistant":
+            calls = m.get("tool_calls")
+            if calls:
+                tids = ids.open_calls(len(calls))
+                tcs = [
+                    {
+                        "id": tid,
+                        "type": "function",
+                        "function": {"name": c["name"], "arguments": json.dumps(c.get("args", {}))},
+                    }
+                    for tid, c in zip(tids, calls, strict=True)
+                ]
+                # Keep the model's reasoning text alongside the calls when
+                # present (OpenAI allows content + tool_calls on one message).
+                out.append({"role": "assistant", "content": m.get("content") or None, "tool_calls": tcs})
+            else:
+                out.append({"role": "assistant", "content": m.get("content", "")})
+        elif role == "tool":
+            out.append({"role": "tool", "tool_call_id": ids.match_result(), "content": m.get("content", "")})
+    ids.finish()
+    return out
+
+
+def anthropic_tool(schema: dict) -> dict:
+    """Neutral tool schema (name/description/parameters) → Anthropic tool."""
+    return {
+        "name": schema["name"],
+        "description": schema.get("description", ""),
+        "input_schema": schema.get("parameters", {"type": "object", "properties": {}}),
+    }
+
+
+def openai_tool(schema: dict) -> dict:
+    """Neutral tool schema → OpenAI function tool (near-identity)."""
+    return {
+        "type": "function",
+        "function": {
+            "name": schema["name"],
+            "description": schema.get("description", ""),
+            "parameters": schema.get("parameters", {"type": "object", "properties": {}}),
+        },
+    }

zu_providers-0.1.0/src/zu_providers/anthropic.py

@@ -0,0 +1,149 @@
+"""Anthropic Messages API adapter (build step 7).
+
+Translates Zu's neutral ``ModelRequest`` into a Messages API call via the
+official ``anthropic`` SDK, and the response back into a neutral
+``ModelResponse`` — so the rest of the runtime never imports a model SDK. The
+API key is resolved from the environment *inside* the adapter and never placed
+in the model's context or in config, consistent with the security model.
+
+The client is injectable (an ``AsyncAnthropic`` with a mock transport) so the
+translation and parsing are proven offline against the real SDK; a live call is
+opt-in. The same neutral contract is implemented by ``openai_compatible`` —
+both pass one shared checklist, which is what makes "run on any model" real.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from zu_core.ports import Capabilities, Finish, ModelRequest, ModelResponse, ToolCall
+
+from ._messages import anthropic_tool, to_anthropic_messages
+
+logger = logging.getLogger("zu.providers.anthropic")
+
+# Anthropic stop_reason -> neutral Finish. A tool-call finish is decided by the
+# presence of tool calls, not this map, so the ``tool_use`` reason is absent here
+# (a text+tool response still finalises right via presence-of-calls).
+_FINISH = {
+    "end_turn": Finish.STOP,
+    "stop_sequence": Finish.STOP,
+    "max_tokens": Finish.LENGTH,
+    "refusal": Finish.STOP,
+    "pause_turn": Finish.STOP,
+}
+
+# Default per-response output cap. Agent turns are short (a tool call or a small
+# JSON answer); override per request via ``ModelRequest.params["max_tokens"]``.
+_DEFAULT_MAX_TOKENS = 4096
+
+# Default per-call wall-time and retry bounds. A "production runtime" must not
+# inherit the SDK's unbounded defaults: a hung connection or the SDK's own
+# exponential-backoff retries can otherwise stack arbitrarily inside a short
+# run budget. The loop wraps ``complete`` in its own wall-time too, but the
+# adapter sets a floor so direct/embed use (no loop deadline) is bounded as well.
+_DEFAULT_TIMEOUT_S = 60.0
+_DEFAULT_MAX_RETRIES = 2
+
+
+class AnthropicProvider:
+    def __init__(
+        self,
+        model: str = "claude-opus-4-8",
+        api_key_env: str = "ANTHROPIC_API_KEY",
+        api_key: str | None = None,
+        max_tokens: int = _DEFAULT_MAX_TOKENS,
+        timeout: float = _DEFAULT_TIMEOUT_S,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        client: Any = None,
+    ) -> None:
+        self.model = model
+        self.api_key_env = api_key_env
+        # An explicit key (for programmatic / in-memory use, e.g. zu.run with a
+        # key your app already holds). Prefer ``api_key_env`` so the key never
+        # lands in a committed config file; either way it stays out of the
+        # model's context. Never hard-code or ship a key.
+        self.api_key = api_key
+        self.max_tokens = max_tokens
+        self.timeout = timeout
+        self.max_retries = max_retries
+        # client is a testability/config seam (an AsyncAnthropic, possibly with a
+        # mock transport); None -> construct from the resolved key on first use.
+        self._client = client
+        # vision=False: the neutral ModelRequest has no image channel yet, so the
+        # adapter never sends or handles image blocks — multimodal is deferred
+        # until the neutral request grows one. Declaring it would be decorative.
+        self.capabilities = Capabilities(native_tools=True, vision=False, max_context=1_000_000)
+
+    def _ensure_client(self) -> Any:
+        if self._client is None:
+            try:
+                import anthropic
+            except ModuleNotFoundError as exc:
+                raise RuntimeError(
+                    "the anthropic provider needs the SDK: "
+                    "pip install 'zu-runtime[anthropic]'"
+                ) from exc
+
+            key = self.api_key or os.environ.get(self.api_key_env)
+            if not key:
+                raise RuntimeError(
+                    f"no Anthropic API key: pass api_key=... or set ${self.api_key_env} "
+                    "(the key is read here, never placed in the model's context or a config file)."
+                )
+            self._client = anthropic.AsyncAnthropic(
+                api_key=key, timeout=self.timeout, max_retries=self.max_retries
+            )
+        return self._client
+
+    async def complete(self, req: ModelRequest) -> ModelResponse:
+        client = self._ensure_client()
+        system, messages = to_anthropic_messages(req.messages)
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "max_tokens": int(req.params.get("max_tokens", self.max_tokens)),
+            "messages": messages,
+        }
+        if system:
+            kwargs["system"] = system
+        if req.tools:
+            kwargs["tools"] = [anthropic_tool(t) for t in req.tools]
+        resp = await client.messages.create(**kwargs)
+        return _to_model_response(resp)
+
+
+def _to_model_response(resp: Any) -> ModelResponse:
+    text_parts: list[str] = []
+    calls: list[ToolCall] = []
+    for block in resp.content:
+        if block.type == "text":
+            text_parts.append(block.text)
+        elif block.type == "tool_use":
+            calls.append(ToolCall(name=block.name, args=dict(block.input or {})))
+    if not calls and resp.stop_reason == "refusal":
+        # A model refusal. No distinct neutral Finish exists, so it maps to STOP —
+        # but warn rather than collapse it silently, so a refusal isn't mistaken
+        # for a clean completion (mirrors the openai adapter's content_filter).
+        logger.warning("model response was a refusal (mapped to STOP)")
+    finish = Finish.TOOL_CALLS if calls else _FINISH.get(resp.stop_reason, Finish.STOP)
+    # Normalised usage shape shared with the openai-compatible adapter:
+    # input/output/total. Anthropic's API doesn't return a total, so compute it
+    # (input + output) — both adapters hand the cost projection the same shape.
+    # Guard a missing/partial usage object the same way the openai adapter does,
+    # so a response without usage degrades to {} rather than raising AttributeError
+    # — the two adapters behave identically on this edge, not just the happy path.
+    raw_usage = getattr(resp, "usage", None)
+    if raw_usage is None:
+        usage: dict = {}
+    else:
+        in_tok = getattr(raw_usage, "input_tokens", 0) or 0
+        out_tok = getattr(raw_usage, "output_tokens", 0) or 0
+        usage = {"input_tokens": in_tok, "output_tokens": out_tok, "total_tokens": in_tok + out_tok}
+    return ModelResponse(
+        text="".join(text_parts) or None,
+        tool_calls=calls,
+        finish=finish,
+        usage=usage,
+    )

zu_providers-0.1.0/src/zu_providers/openai_compatible.py

@@ -0,0 +1,173 @@
+"""OpenAI-compatible adapter (build step 7).
+
+One adapter, pointed at a different base URL, reaches OpenRouter, OpenAI, and
+local servers (Ollama, vLLM) — covering a vast range of models, including open
+ones. It translates Zu's neutral ``ModelRequest`` into a Chat Completions call
+via the official ``openai`` SDK and parses the response back, so the rest of
+the runtime never imports a model SDK. Base URL and key are resolved from the
+environment *inside* the adapter, never placed in the model's context.
+
+The client is injectable (an ``AsyncOpenAI`` with a mock transport) so the
+translation and parsing are proven offline against the real SDK; a live call is
+opt-in. This adapter and ``anthropic`` pass one shared checklist — identical
+neutral behaviour from two different wire formats.
+
+A model without native tool-calling would need the prompt-based tool fallback
+(inject schemas into the prompt, parse a structured action out of the text);
+that path is deferred. The native path is what ships here.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+from zu_core.ports import Capabilities, Finish, ModelRequest, ModelResponse, ToolCall
+
+from ._messages import openai_tool, to_openai_messages
+
+logger = logging.getLogger("zu.providers.openai")
+
+# OpenAI finish_reason -> neutral Finish. A tool-call finish is decided by the
+# presence of tool calls, not this map, so the tool_calls/function_call reasons
+# are intentionally absent here.
+_FINISH = {
+    "stop": Finish.STOP,
+    "length": Finish.LENGTH,
+    "content_filter": Finish.STOP,
+}
+
+# Default per-call wall-time and retry bounds — see the anthropic adapter: a
+# production runtime must not inherit the SDK's unbounded timeout / stacked
+# backoff. Override per provider via the constructor (or config ``options``).
+_DEFAULT_TIMEOUT_S = 60.0
+_DEFAULT_MAX_RETRIES = 2
+
+
+class OpenAICompatibleProvider:
+    def __init__(
+        self,
+        model: str,
+        base_url_env: str = "OPENAI_BASE_URL",
+        api_key_env: str = "OPENAI_API_KEY",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        native_tools: bool = True,
+        max_tokens: int | None = None,
+        timeout: float = _DEFAULT_TIMEOUT_S,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        client: Any = None,
+    ) -> None:
+        self.model = model
+        self.base_url_env = base_url_env
+        self.api_key_env = api_key_env
+        # Explicit key/base_url for programmatic use; prefer the *_env forms so a
+        # key never lands in a committed config. Either way it stays out of the
+        # model's context. Never hard-code or ship a key.
+        self.api_key = api_key
+        self.base_url = base_url
+        self.max_tokens = max_tokens
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client = client
+        self.capabilities = Capabilities(native_tools=native_tools)
+
+    def _ensure_client(self) -> Any:
+        if self._client is None:
+            try:
+                import openai
+            except ModuleNotFoundError as exc:
+                raise RuntimeError(
+                    "the openai-compatible provider needs the SDK: "
+                    "pip install 'zu-runtime[openai]'"
+                ) from exc
+
+            # Local servers (Ollama/vLLM) need no key; the SDK still wants a
+            # non-empty string, so fall back to a placeholder. Base URL is
+            # optional (defaults to OpenAI) and read from the env when set.
+            key = self.api_key or os.environ.get(self.api_key_env) or "not-needed"
+            base_url = self.base_url or os.environ.get(self.base_url_env) or None
+            self._client = openai.AsyncOpenAI(
+                api_key=key,
+                base_url=base_url,
+                timeout=self.timeout,
+                max_retries=self.max_retries,
+            )
+        return self._client
+
+    async def complete(self, req: ModelRequest) -> ModelResponse:
+        if not self.capabilities.native_tools:
+            raise NotImplementedError(
+                "prompt-based tool fallback for non-native-tool models is deferred; "
+                "set native_tools=True to use the Chat Completions path."
+            )
+        client = self._ensure_client()
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "messages": to_openai_messages(req.messages),
+        }
+        if req.tools:
+            kwargs["tools"] = [openai_tool(t) for t in req.tools]
+        max_tokens = req.params.get("max_tokens", self.max_tokens)
+        if max_tokens is not None:
+            kwargs["max_tokens"] = int(max_tokens)
+        resp = await client.chat.completions.create(**kwargs)
+        return _to_model_response(resp)
+
+
+def _to_model_response(resp: Any) -> ModelResponse:
+    # Some OpenAI-compatible servers (vLLM/Ollama/proxies) return an empty
+    # ``choices`` array on certain errors or policy stops. Index [0] would
+    # IndexError; instead surface it as a no-answer STOP (the loop ends the run
+    # cleanly with "model finalised with no answer") and keep any usage reported.
+    choices = resp.choices or []
+    if not choices:
+        logger.warning("provider returned no choices (mapped to an empty STOP response)")
+        return ModelResponse(text=None, tool_calls=[], finish=Finish.STOP, usage=_usage_of(resp))
+    choice = choices[0]
+    msg = choice.message
+    calls: list[ToolCall] = []
+    for tc in msg.tool_calls or []:
+        raw = tc.function.arguments or "{}"
+        try:
+            args = json.loads(raw)
+        except (ValueError, TypeError):
+            args = {}
+        if not isinstance(args, dict):
+            args = {}
+        if args == {} and raw not in ("", "{}"):
+            # Malformed (or non-object) tool args. We keep the run alive — a
+            # malformed-args tool call becomes an empty-args call the loop will
+            # still dispatch — but we do NOT swallow it: surface it as a warning
+            # so a model emitting broken arguments is visible, not silent.
+            logger.warning(
+                "tool call %r produced unparsable arguments, dispatching with {}: %r",
+                tc.function.name,
+                raw,
+            )
+        calls.append(ToolCall(name=tc.function.name, args=args))
+    if not calls and choice.finish_reason == "content_filter":
+        # The provider's moderation stopped generation. The neutral Finish set has
+        # no distinct moderation value, so it maps to STOP — but we do NOT collapse
+        # it silently: surface it so a refusal/cut-off is visible, not mistaken for
+        # a clean completion (the same "fail loudly" posture as malformed args).
+        logger.warning("model response stopped by content_filter (mapped to STOP)")
+    finish = Finish.TOOL_CALLS if calls else _FINISH.get(choice.finish_reason, Finish.STOP)
+    return ModelResponse(
+        text=msg.content or None, tool_calls=calls, finish=finish, usage=_usage_of(resp)
+    )
+
+
+def _usage_of(resp: Any) -> dict:
+    """The normalised usage shape (input/output/total) shared with the anthropic
+    adapter, degrading to ``{}`` when the provider reports no usage."""
+    raw = getattr(resp, "usage", None)
+    if raw is None:
+        return {}
+    return {
+        "input_tokens": raw.prompt_tokens,
+        "output_tokens": raw.completion_tokens,
+        "total_tokens": raw.total_tokens,
+    }

zu_providers-0.1.0/src/zu_providers/scripted.py

@@ -0,0 +1,106 @@
+"""The fake model — a deterministic stand-in for an LLM.
+
+You hand it a fixed list of moves — call this tool, then that one, then
+finish — and it plays them back in order, ignoring the request. With no API
+key, no token cost, and no randomness, the whole loop does the exact same
+thing every run. Almost every offline test leans on this provider; it is what
+makes build steps 3–6 testable before any real model is wired in (step 7).
+"""
+
+from __future__ import annotations
+
+from zu_core.ports import (
+    Capabilities,
+    Finish,
+    ModelProvider,
+    ModelRequest,
+    ModelResponse,
+    ToolCall,
+)
+
+
+class ScriptedProvider:
+    """Replays a fixed list of ModelResponse moves, one per `complete` call.
+
+    Construct from explicit ModelResponse objects, or use the `tool_calls` /
+    `finish` helpers to build a script tersely:
+
+        ScriptedProvider.from_moves([
+            {"tool": "http_fetch", "args": {"url": "https://example.com"}},
+            {"text": "done", "finish": "stop"},
+        ])
+    """
+
+    # No real model behind the fake provider, so cost attribution records None
+    # (satisfies the ModelProvider ``model`` contract; real adapters set an id).
+    model: str | None = None
+
+    def __init__(
+        self,
+        moves: list[ModelResponse],
+        capabilities: Capabilities | None = None,
+    ) -> None:
+        self._moves = list(moves)
+        self._i = 0
+        self.capabilities = capabilities or Capabilities()
+
+    @classmethod
+    def from_moves(cls, moves: list[dict], **kw) -> ScriptedProvider:
+        responses: list[ModelResponse] = []
+        for i, m in enumerate(moves):
+            # Fail loudly on a malformed move rather than silently swallowing it:
+            # a tool move is {tool, args}; a text move is {text?, finish?}. An
+            # unrecognised key (a typo like {"toolname": ...}) or an empty move
+            # would otherwise be quietly turned into a do-nothing STOP response,
+            # masking a broken script — exactly the "explicit over implicit" trap.
+            # An optional ``usage`` dict ({"total_tokens": N} or {"input_tokens",
+            # "output_tokens"}) lets a script carry real per-turn token cost, so the
+            # loop's token accounting and the resource observer can be exercised
+            # deterministically (without it, a scripted run reports zero tokens and
+            # any token-budget check is vacuous).
+            if "tool" in m:
+                extra = set(m) - {"tool", "args", "usage"}
+                if extra:
+                    raise ValueError(
+                        f"move {i} is a tool call with unexpected key(s) {sorted(extra)}; "
+                        "a tool move takes only 'tool', 'args', and optional 'usage'"
+                    )
+                responses.append(
+                    ModelResponse(
+                        tool_calls=[ToolCall(name=m["tool"], args=m.get("args", {}))],
+                        finish=Finish.TOOL_CALLS,
+                        usage=m.get("usage") or {},
+                    )
+                )
+            else:
+                extra = set(m) - {"text", "finish", "usage"}
+                if extra or not m:
+                    raise ValueError(
+                        f"move {i} is not a valid move: {m!r}; expected a tool move "
+                        "{'tool': ..., 'args': ...} or a text move {'text': ..., 'finish': ...} "
+                        "(either may carry an optional 'usage')"
+                    )
+                responses.append(
+                    ModelResponse(
+                        text=m.get("text"),
+                        finish=Finish(m.get("finish", "stop")),
+                        usage=m.get("usage") or {},
+                    )
+                )
+        return cls(responses, **kw)
+
+    async def complete(self, req: ModelRequest) -> ModelResponse:
+        if self._i >= len(self._moves):
+            # Out of script: behave as a model that has nothing left to say.
+            return ModelResponse(text=None, finish=Finish.STOP)
+        move = self._moves[self._i]
+        self._i += 1
+        return move
+
+    @property
+    def exhausted(self) -> bool:
+        return self._i >= len(self._moves)
+
+
+# Structural conformance check (no runtime cost; documents intent).
+_: type[ModelProvider] = ScriptedProvider

zu_providers-0.1.0/tests/test_providers.py

@@ -0,0 +1,377 @@
+"""Build step 7 — the real ModelProvider adapters: anthropic + openai-compatible.
+
+The headline contract: **both adapters pass one shared checklist, so they behave
+identically.** Each is exercised offline against its *real* SDK — an injected
+client wired to an ``httpx.MockTransport`` returns canned provider JSON, so the
+adapter's translation and the SDK's own parsing both run, with no network. A
+live call against each API is opt-in (env-gated) so it never blocks CI.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+import anthropic
+import httpx
+import openai
+import pytest
+
+from zu_core.ports import Finish, ModelRequest
+from zu_providers._messages import to_anthropic_messages, to_openai_messages
+from zu_providers.anthropic import AnthropicProvider
+from zu_providers.openai_compatible import OpenAICompatibleProvider
+
+_TOOL = {
+    "name": "http_fetch",
+    "description": "Fetch a URL.",
+    "parameters": {
+        "type": "object",
+        "properties": {"url": {"type": "string"}},
+        "required": ["url"],
+    },
+}
+
+# Canned provider responses for each checklist scenario, in each wire format.
+_ANTHROPIC: dict[str, dict] = {
+    "text": {
+        "id": "msg_1", "type": "message", "role": "assistant", "model": "claude-opus-4-8",
+        "content": [{"type": "text", "text": "hello world"}],
+        "stop_reason": "end_turn", "stop_sequence": None,
+        "usage": {"input_tokens": 10, "output_tokens": 5},
+    },
+    "tool": {
+        "id": "msg_2", "type": "message", "role": "assistant", "model": "claude-opus-4-8",
+        "content": [{"type": "tool_use", "id": "toolu_x", "name": "http_fetch", "input": {"url": "http://e.test/"}}],
+        "stop_reason": "tool_use", "stop_sequence": None,
+        "usage": {"input_tokens": 12, "output_tokens": 7},
+    },
+    "length": {
+        "id": "msg_3", "type": "message", "role": "assistant", "model": "claude-opus-4-8",
+        "content": [{"type": "text", "text": "partial"}],
+        "stop_reason": "max_tokens", "stop_sequence": None,
+        "usage": {"input_tokens": 10, "output_tokens": 4},
+    },
+}
+_OPENAI: dict[str, dict] = {
+    "text": {
+        "id": "c1", "object": "chat.completion", "created": 0, "model": "gpt-x",
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": "hello world"}, "finish_reason": "stop"}],
+        "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+    },
+    "tool": {
+        "id": "c2", "object": "chat.completion", "created": 0, "model": "gpt-x",
+        "choices": [{
+            "index": 0,
+            "message": {
+                "role": "assistant", "content": None,
+                "tool_calls": [{
+                    "id": "call_x", "type": "function",
+                    "function": {"name": "http_fetch", "arguments": "{\"url\": \"http://e.test/\"}"},
+                }],
+            },
+            "finish_reason": "tool_calls",
+        }],
+        "usage": {"prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19},
+    },
+    "length": {
+        "id": "c3", "object": "chat.completion", "created": 0, "model": "gpt-x",
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": "partial"}, "finish_reason": "length"}],
+        "usage": {"prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14},
+    },
+}
+
+
+def _mock_transport(payload: dict, captured: list) -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured.append(json.loads(request.content))
+        return httpx.Response(200, json=payload)
+
+    return httpx.MockTransport(handler)
+
+
+def make_anthropic(scenario: str, captured: list) -> AnthropicProvider:
+    client = anthropic.AsyncAnthropic(
+        api_key="test", http_client=httpx.AsyncClient(transport=_mock_transport(_ANTHROPIC[scenario], captured))
+    )
+    return AnthropicProvider(client=client)
+
+
+def make_openai(scenario: str, captured: list) -> OpenAICompatibleProvider:
+    client = openai.AsyncOpenAI(
+        api_key="test",
+        base_url="http://test.local/v1",
+        http_client=httpx.AsyncClient(transport=_mock_transport(_OPENAI[scenario], captured)),
+    )
+    return OpenAICompatibleProvider(model="gpt-x", client=client)
+
+
+_PROVIDERS = [
+    pytest.param(make_anthropic, id="anthropic"),
+    pytest.param(make_openai, id="openai-compatible"),
+]
+
+
+# --- the shared checklist: identical neutral behaviour from both adapters -----
+
+
+@pytest.mark.parametrize("make", _PROVIDERS)
+async def test_text_finalize(make) -> None:
+    p = make("text", [])
+    r = await p.complete(ModelRequest(messages=[{"role": "user", "content": "hi"}]))
+    assert r.finish is Finish.STOP
+    assert r.text == "hello world"
+    assert r.tool_calls == []
+    assert r.usage["input_tokens"] == 10 and r.usage["output_tokens"] == 5
+
+
+@pytest.mark.parametrize("make", _PROVIDERS)
+async def test_tool_call(make) -> None:
+    p = make("tool", [])
+    r = await p.complete(ModelRequest(messages=[{"role": "user", "content": "fetch"}], tools=[_TOOL]))
+    assert r.finish is Finish.TOOL_CALLS
+    assert len(r.tool_calls) == 1
+    assert r.tool_calls[0].name == "http_fetch"
+    assert r.tool_calls[0].args == {"url": "http://e.test/"}  # parsed to a dict, both ways
+    assert r.text is None
+
+
+@pytest.mark.parametrize("make", _PROVIDERS)
+async def test_length_is_finish_length(make) -> None:
+    p = make("length", [])
+    r = await p.complete(ModelRequest(messages=[{"role": "user", "content": "x"}]))
+    assert r.finish is Finish.LENGTH
+
+
+@pytest.mark.parametrize("make", _PROVIDERS)
+async def test_capabilities_present(make) -> None:
+    assert make("text", []).capabilities.native_tools is True
+
+
+@pytest.mark.parametrize("make", _PROVIDERS)
+async def test_usage_shape_is_normalised(make) -> None:
+    # The neutral usage dict the cost projection reads carries the SAME keys from
+    # both adapters: input/output/total. OpenAI returns a total on the wire;
+    # Anthropic doesn't, so the adapter computes it (input + output) — either way
+    # the cost projection sees one shape.
+    r = await make("text", []).complete(ModelRequest(messages=[{"role": "user", "content": "hi"}]))
+    assert r.usage["input_tokens"] == 10
+    assert r.usage["output_tokens"] == 5
+    assert r.usage["total_tokens"] == 15  # 10 + 5, whether the API gave it or not
+
+
+def test_api_key_resolution_prefers_explicit_then_env(monkeypatch) -> None:
+    # A directly-passed key works with no env var set; without either, the
+    # adapter raises a clear error rather than calling the API with no auth.
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    AnthropicProvider(model="claude-x", api_key="sk-explicit")._ensure_client()  # no raise
+
+    with pytest.raises(RuntimeError, match="no Anthropic API key"):
+        AnthropicProvider(model="claude-x")._ensure_client()
+
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-from-env")
+    AnthropicProvider(model="claude-x")._ensure_client()  # resolves from env
+
+
+async def test_native_tools_false_raises_not_implemented() -> None:
+    # The prompt-based tool fallback for non-native-tool models is deferred;
+    # the adapter must raise clearly, never silently guess.
+    p = OpenAICompatibleProvider(model="local", native_tools=False, client=object())
+    with pytest.raises(NotImplementedError):
+        await p.complete(ModelRequest(messages=[{"role": "user", "content": "hi"}]))
+
+
+async def test_openai_empty_choices_is_no_answer_not_crash() -> None:
+    # Some OpenAI-compatible servers (vLLM/Ollama/proxies) return choices: [] on
+    # certain errors/policy stops. The adapter must surface that as a no-answer
+    # STOP, never IndexError on choices[0].
+    captured: list = []
+    payload = {
+        "id": "c0", "object": "chat.completion", "created": 0, "model": "gpt-x",
+        "choices": [],
+        "usage": {"prompt_tokens": 3, "completion_tokens": 0, "total_tokens": 3},
+    }
+    client = openai.AsyncOpenAI(
+        api_key="test", base_url="http://test.local/v1",
+        http_client=httpx.AsyncClient(transport=_mock_transport(payload, captured)),
+    )
+    p = OpenAICompatibleProvider(model="gpt-x", client=client)
+    resp = await p.complete(ModelRequest(messages=[{"role": "user", "content": "hi"}]))
+    assert resp.text is None
+    assert resp.tool_calls == []
+    assert resp.finish is Finish.STOP
+    assert resp.usage["total_tokens"] == 3  # usage still captured
+
+
+def test_orphan_tool_result_raises_not_silent() -> None:
+    # A tool result with no preceding tool call is a malformed history; both
+    # translators must fail loudly here rather than fabricate an id that the
+    # provider would reject downstream as an opaque 400.
+    bad = [{"role": "tool", "name": "http_fetch", "content": "{}"}]
+    with pytest.raises(ValueError):
+        to_anthropic_messages(bad)
+    with pytest.raises(ValueError):
+        to_openai_messages(bad)
+
+
+# --- request translation (provider-specific wire shapes) ----------------------
+
+
+async def test_anthropic_request_translation() -> None:
+    captured: list = []
+    p = make_anthropic("text", captured)
+    await p.complete(
+        ModelRequest(
+            messages=[{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}],
+            tools=[_TOOL],
+        )
+    )
+    body = captured[0]
+    assert body["system"] == "sys"  # system lifted out of messages
+    assert body["messages"] == [{"role": "user", "content": "hi"}]
+    assert body["max_tokens"] == 4096  # adapter default
+    assert body["tools"][0]["name"] == "http_fetch"
+    assert "input_schema" in body["tools"][0]  # parameters -> input_schema
+
+
+async def test_openai_request_translation() -> None:
+    captured: list = []
+    p = make_openai("text", captured)
+    await p.complete(
+        ModelRequest(
+            messages=[{"role": "system", "content": "sys"}, {"role": "user", "content": "hi"}],
+            tools=[_TOOL],
+        )
+    )
+    body = captured[0]
+    assert body["messages"][0] == {"role": "system", "content": "sys"}  # system stays inline
+    assert body["tools"][0]["type"] == "function"
+    assert body["tools"][0]["function"]["name"] == "http_fetch"
+
+
+# --- the id-matching translation (pure, no SDK) -------------------------------
+
+_TOOL_HISTORY: list[dict] = [
+    {"role": "user", "content": "q"},
+    {"role": "assistant", "tool_calls": [{"name": "http_fetch", "args": {"url": "u"}}]},
+    {"role": "tool", "name": "http_fetch", "content": "{\"html\": \"x\"}"},
+]
+
+
+def test_to_anthropic_matches_synthesised_tool_ids() -> None:
+    _, out = to_anthropic_messages(_TOOL_HISTORY)
+    use_id = out[1]["content"][0]["id"]
+    result_block = out[2]["content"][0]
+    assert result_block["type"] == "tool_result"
+    assert result_block["tool_use_id"] == use_id  # result references the same id
+
+
+def test_to_openai_matches_synthesised_tool_ids() -> None:
+    out = to_openai_messages(_TOOL_HISTORY)
+    call_id = out[1]["tool_calls"][0]["id"]
+    assert out[2]["role"] == "tool"
+    assert out[2]["tool_call_id"] == call_id
+
+
+# An assistant turn that reasons *and* calls a tool: the text must survive into
+# both wire formats (regression: it used to be silently dropped on replay).
+_TOOL_HISTORY_WITH_TEXT: list[dict] = [
+    {"role": "user", "content": "q"},
+    {"role": "assistant", "content": "I'll fetch the page first.",
+     "tool_calls": [{"name": "http_fetch", "args": {"url": "u"}}]},
+    {"role": "tool", "name": "http_fetch", "content": "{\"html\": \"x\"}"},
+]
+
+
+def test_anthropic_preserves_assistant_text_with_tool_calls() -> None:
+    _, out = to_anthropic_messages(_TOOL_HISTORY_WITH_TEXT)
+    blocks = out[1]["content"]
+    assert blocks[0] == {"type": "text", "text": "I'll fetch the page first."}
+    assert blocks[1]["type"] == "tool_use"  # text leads, tool_use follows
+
+
+def test_openai_preserves_assistant_text_with_tool_calls() -> None:
+    out = to_openai_messages(_TOOL_HISTORY_WITH_TEXT)
+    assert out[1]["content"] == "I'll fetch the page first."
+    assert out[1]["tool_calls"][0]["function"]["name"] == "http_fetch"
+
+
+# --- the adapter drives the real loop (full assistant/tool history) -----------
+
+
+async def test_anthropic_adapter_drives_the_loop() -> None:
+    # The checklist uses simple messages; this proves the loop's full neutral
+    # history (system + user -> tool_use -> assistant tool_calls + tool result ->
+    # finalise) round-trips through the adapter's translation, end to end.
+    from zu_core.bus import EventBus
+    from zu_core.contracts import Status, TaskSpec
+    from zu_core.loop import run_task
+    from zu_core.registry import Registry
+    from zu_tools.fetch import HttpFetch
+
+    page = "<html><body><span class='price'>$9.00</span></body></html>"
+
+    def fetch_handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, text=page)
+
+    reg = Registry()
+    reg.register(
+        "tools", "http_fetch", HttpFetch(allow_private=True, transport=httpx.MockTransport(fetch_handler))
+    )
+
+    # Stateful model mock: first call asks to fetch, second call finalises.
+    turn = {"n": 0}
+
+    def model_handler(request: httpx.Request) -> httpx.Response:
+        turn["n"] += 1
+        if turn["n"] == 1:
+            payload = {
+                "id": "m1", "type": "message", "role": "assistant", "model": "claude-opus-4-8",
+                "content": [{"type": "tool_use", "id": "toolu_a", "name": "http_fetch", "input": {"url": "http://x.test/"}}],
+                "stop_reason": "tool_use", "stop_sequence": None,
+                "usage": {"input_tokens": 20, "output_tokens": 8},
+            }
+        else:
+            payload = {
+                "id": "m2", "type": "message", "role": "assistant", "model": "claude-opus-4-8",
+                "content": [{"type": "text", "text": "{\"price\": \"$9.00\"}"}],
+                "stop_reason": "end_turn", "stop_sequence": None,
+                "usage": {"input_tokens": 40, "output_tokens": 12},
+            }
+        return httpx.Response(200, json=payload)
+
+    client = anthropic.AsyncAnthropic(
+        api_key="test", http_client=httpx.AsyncClient(transport=httpx.MockTransport(model_handler))
+    )
+    provider = AnthropicProvider(client=client)
+
+    result = await run_task(TaskSpec(query="get the price"), provider, reg, EventBus())
+    assert result.status == Status.SUCCESS
+    assert result.value == {"price": "$9.00"}
+    assert turn["n"] == 2  # the loop drove two model turns through the adapter
+
+
+# --- opt-in live calls (@pytest.mark.live + a real key; run with --run-live) ---
+
+
+@pytest.mark.live
+@pytest.mark.skipif(not os.environ.get("ANTHROPIC_API_KEY"), reason="needs ANTHROPIC_API_KEY")
+async def test_live_anthropic() -> None:
+    p = AnthropicProvider()
+    r = await p.complete(
+        ModelRequest(messages=[{"role": "user", "content": "Reply with the single word: pong"}], params={"max_tokens": 16})
+    )
+    assert r.text is not None and "pong" in r.text.lower()
+
+
+@pytest.mark.live
+@pytest.mark.skipif(
+    not (os.environ.get("OPENAI_API_KEY") or os.environ.get("OPENAI_BASE_URL")),
+    reason="needs OPENAI_API_KEY or OPENAI_BASE_URL",
+)
+async def test_live_openai() -> None:
+    p = OpenAICompatibleProvider(model=os.environ.get("ZU_LIVE_OPENAI_MODEL", "gpt-4o-mini"))
+    r = await p.complete(
+        ModelRequest(messages=[{"role": "user", "content": "Reply with the single word: pong"}], params={"max_tokens": 16})
+    )
+    assert r.text is not None and "pong" in r.text.lower()

zu_providers-0.1.0/tests/test_scripted.py

@@ -0,0 +1,48 @@
+"""Build step 2 — the fake model plays its script back in order."""
+
+from __future__ import annotations
+
+from zu_core.ports import Finish
+from zu_providers.scripted import ScriptedProvider
+
+
+async def _req():
+    from zu_core.ports import ModelRequest
+
+    return ModelRequest(messages=[{"role": "user", "content": "go"}])
+
+
+async def test_plays_moves_in_order() -> None:
+    p = ScriptedProvider.from_moves(
+        [
+            {"tool": "http_fetch", "args": {"url": "https://example.com"}},
+            {"tool": "html_parse", "args": {"selector": ".price"}},
+            {"text": "the price is $9", "finish": "stop"},
+        ]
+    )
+
+    r1 = await p.complete(await _req())
+    assert r1.finish is Finish.TOOL_CALLS
+    assert r1.tool_calls[0].name == "http_fetch"
+    assert r1.tool_calls[0].args == {"url": "https://example.com"}
+
+    r2 = await p.complete(await _req())
+    assert r2.tool_calls[0].name == "html_parse"
+
+    r3 = await p.complete(await _req())
+    assert r3.finish is Finish.STOP
+    assert r3.text == "the price is $9"
+    assert p.exhausted
+
+
+async def test_past_end_is_a_stop() -> None:
+    p = ScriptedProvider.from_moves([{"text": "done"}])
+    await p.complete(await _req())
+    overrun = await p.complete(await _req())
+    assert overrun.finish is Finish.STOP
+    assert overrun.text is None
+
+
+def test_declares_capabilities() -> None:
+    p = ScriptedProvider.from_moves([])
+    assert p.capabilities.native_tools is True