hum-cli 0.0.1__py3-none-any.whl

hum/runtime/autonomy.py

@@ -0,0 +1,71 @@
+"""Earned autonomy. The level a policy runs at on a class of tasks is a number
+the world assigns from graded outcomes, not a mode a user picks.
+
+Per task class we keep a Beta posterior over "unsupervised policy run passes".
+The level is chosen from a lower confidence bound on that posterior, so a
+class earns ``act`` only with enough evidence, and loses it when outcomes
+turn. Updated online as verdicts arrive; persisted as JSON so it survives
+the session and follows the weights.
+
+Levels
+  observe  policy drafts; every tool call needs a human decision; mutating
+           calls are executed only as the human's own turn
+  propose  every policy turn is gated (accept / edit / reject)
+  review   read-only turns run; mutating turns are gated
+  act      ungated; the human may still steer or take over
+"""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Literal
+
+Level = Literal["observe", "propose", "review", "act"]
+_ORDER: list[Level] = ["observe", "propose", "review", "act"]
+
+
+class AutonomyPolicy:
+    def __init__(self, path: Path | None = None, *, prior: tuple[float, float] = (1.0, 1.0), z: float = 1.0,
+                 thresholds: dict[Level, float] | None = None):
+        self.path = path
+        self.prior = prior
+        self.z = z
+        self.thresholds: dict[Level, float] = thresholds or {"propose": 0.5, "review": 0.7, "act": 0.9}
+        self.counts: dict[str, tuple[int, int]] = {}  # task_class -> (passes, fails)
+        if path and path.exists():
+            self.counts = {k: tuple(v) for k, v in json.loads(path.read_text()).items()}  # type: ignore[misc]
+
+    def update(self, task_class: str, passed: bool) -> Level:
+        p, f = self.counts.get(task_class, (0, 0))
+        self.counts[task_class] = (p + int(passed), f + int(not passed))
+        if self.path:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(json.dumps(self.counts))
+        return self.level(task_class)
+
+    def lower_bound(self, task_class: str) -> float:
+        p, f = self.counts.get(task_class, (0, 0))
+        a, b = self.prior[0] + p, self.prior[1] + f
+        mean = a / (a + b)
+        var = (a * b) / ((a + b) ** 2 * (a + b + 1))
+        return max(0.0, mean - self.z * math.sqrt(var))
+
+    def level(self, task_class: str | None) -> Level:
+        if task_class is None:
+            return "propose"
+        lb = self.lower_bound(task_class)
+        lvl: Level = "observe"
+        for cand in ("propose", "review", "act"):
+            if lb >= self.thresholds[cand]:
+                lvl = cand
+        return lvl
+
+    @staticmethod
+    def gates(level: Level, mutating: bool) -> bool:
+        """Does a policy turn need a human decision before it executes?"""
+        if level == "act":
+            return False
+        if level == "review":
+            return mutating
+        return True

hum/runtime/config.py

@@ -0,0 +1,101 @@
+"""Deployment configuration. Metaphi sets this; the SME never sees it.
+
+~/.hum/config.toml (or HUM_CONFIG):
+
+    [model]
+    name = "openrouter/z-ai/glm-5.3"     # or "policy" behind the proxy
+    api_base = "https://proxy.metaphi.ai"
+    api_key_env = "HUM_API_KEY"
+
+    [[mcp]]                              # native tools mounted into every session
+    name = "control"
+    url = "https://.../mcp"
+
+    [policy]                             # backend behaviour — defaults are "be a great agent"
+    gate = "off"                         # off | earned   (earned = autonomy-gated sessions)
+    shadow = false                       # fork-and-grade on intervention (needs a grader + forkable executor)
+    grader = ""                          # shell command or "mcp:<server>__<tool>"
+    task_class = ""                      # autonomy bucket; default = workspace name
+"""
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class MCPConfig:
+    name: str
+    url: str | None = None
+    command: str | None = None
+    args: list[str] = field(default_factory=list)
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class Config:
+    model: str = "openrouter/z-ai/glm-5.3"
+    api_base: str | None = None
+    api_key: str | None = None
+    reasoning_effort: str | None = None
+    temperature: float | None = None
+    mcp: list[MCPConfig] = field(default_factory=list)
+    gate: str = "off"
+    shadow: bool = False
+    grader: str = ""
+    task_class: str = ""
+    max_turns: int = 400
+    raw: dict[str, Any] = field(default_factory=dict)
+    byo: bool = False          # the person's own provider key (model turns not ours to train on)
+    user: str | None = None
+
+
+def _env(name: str | None) -> str | None:
+    """Empty environment variables are absent, not keys."""
+    v = os.environ.get(name) if name else None
+    return v if v else None
+
+
+def _credentials() -> dict[str, Any]:
+    p = Path(os.environ.get("HUM_HOME") or Path.home() / ".hum") / "credentials.json"
+    try:
+        return json.loads(p.read_text()) if p.exists() else {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def load(path: Path | None = None) -> Config:
+    """Precedence: env > ~/.hum/config.toml [model] > the person's login (our proxy)
+    > their BYO key for the model's provider > defaults."""
+    p = path or Path(os.environ.get("HUM_CONFIG") or Path(os.environ.get("HUM_HOME") or Path.home() / ".hum") / "config.toml")
+    d: dict[str, Any] = {}
+    if p.exists():
+        d = tomllib.loads(p.read_text())
+    m, pol = d.get("model", {}), d.get("policy", {})
+    cred = _credentials()
+    key_env = m.get("api_key_env") or "HUM_API_KEY"
+    model = _env("HUM_MODEL") or m.get("name") or cred.get("model") or cred.get("default_model") or Config.model
+    api_base = _env("HUM_API_BASE") or m.get("api_base")
+    api_key = _env(key_env) or _env("HUM_API_KEY")
+    byo = False
+    if api_base is None and api_key is None and cred.get("api_base") and cred.get("api_key") and not cred.get("model"):
+        api_base, api_key = cred["api_base"], cred["api_key"]          # logged in: our proxy
+    if api_key is None and api_base is None:
+        prov = model.split("/", 1)[0] if "/" in model else "openai"
+        env_name = {"openrouter": "OPENROUTER_API_KEY", "anthropic": "ANTHROPIC_API_KEY", "openai": "OPENAI_API_KEY", "gemini": "GEMINI_API_KEY"}.get(prov)
+        api_key = (cred.get("byo") or {}).get(prov) or _env(env_name)
+        byo = api_key is not None
+    cfg = Config(
+        model=model, api_base=api_base, api_key=api_key,
+        reasoning_effort=m.get("reasoning_effort"), temperature=m.get("temperature"),
+        mcp=[MCPConfig(name=s["name"], url=s.get("url"), command=s.get("command"), args=s.get("args", []), headers=s.get("headers", {})) for s in d.get("mcp", [])],
+        gate=pol.get("gate", "off"), shadow=bool(pol.get("shadow", False)), grader=pol.get("grader", ""),
+        task_class=pol.get("task_class", ""), max_turns=int(pol.get("max_turns", 400)), raw=d,
+    )
+    cfg.byo = byo
+    cfg.user = cred.get("email")
+    return cfg

hum/runtime/drivers.py

@@ -0,0 +1,79 @@
+"""Turn sources. A driver produces the next Turn given the chat so far. The
+loop does not care whether a driver is a model, a person at a web client, or
+a policy continuing in shadow — only who it says it is.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from pydantic import BaseModel
+
+from .llm import LLM
+from .models import Intervention, Turn
+
+
+class PolicyDriver:
+    author = "policy"
+
+    def __init__(self, llm: LLM, author: str = "policy", on_text: Any = None):
+        self.llm = llm
+        self.author = author
+        self.on_text = on_text
+
+    async def next(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]) -> Turn:
+        t = await self.llm.complete(messages, tools, on_text=self.on_text)
+        if t.author != self.author:
+            t = t.model_copy(update={"author": self.author})
+        return t
+
+
+class HumanAction(BaseModel):
+    """What a human sends into the loop.
+
+    - ``intervention`` on a gated proposal: accept | edit | reject | takeover
+    - ``turn``: the human's own action (tool calls) or steering text
+    - ``release``: hand control back to the policy after a takeover
+    """
+
+    intervention: Intervention | None = None
+    turn: Turn | None = None
+
+
+class HumanDriver:
+    """The human's two channels into the loop.
+
+    ``decisions`` answers gated proposals (accept / edit / reject / takeover);
+    ``steering`` carries unsolicited input while the policy acts ungated
+    (text, a human action, a takeover, a release). Keeping them apart means a
+    decision sent before the proposal is surfaced is still a decision, and
+    steering is never mistaken for one.
+    """
+
+    author = "human"
+
+    def __init__(self) -> None:
+        self.decisions: asyncio.Queue[HumanAction] = asyncio.Queue()
+        self.steering: asyncio.Queue[HumanAction] = asyncio.Queue()
+        self.proposals: asyncio.Queue[Turn] = asyncio.Queue()  # surfaced to the client
+
+    # loop side
+    async def review(self, proposal: Turn) -> HumanAction:
+        await self.proposals.put(proposal)
+        return await self.decisions.get()
+
+    async def next(self) -> HumanAction:
+        return await self.steering.get()
+
+    def pending(self) -> HumanAction | None:
+        try:
+            return self.steering.get_nowait()
+        except asyncio.QueueEmpty:
+            return None
+
+    # client side
+    def decide(self, action: HumanAction) -> None:
+        self.decisions.put_nowait(action)
+
+    def send(self, action: HumanAction) -> None:
+        self.steering.put_nowait(action)

hum/runtime/executor.py

@@ -0,0 +1,120 @@
+"""Where tools run. The runtime never touches a filesystem or a shell directly;
+it goes through an Executor so the same loop drives a local directory, a
+Harbor sandbox, or a hosted SME session.
+
+``snapshot``/``fork`` exist for counterfactual shadow: the fork point is the
+state *before* the human's intervention executes, and the shadow branch needs
+its own copy to continue in.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import uuid
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+WINDOWS = os.name == "nt"
+
+
+def pick_shell() -> tuple[str, list[str]]:
+    """(name, argv-prefix). POSIX: bash. Windows: Git Bash if installed, else PowerShell."""
+    if not WINDOWS:
+        return "bash", ["/bin/bash", "-c"]
+    for cand in (shutil.which("bash"), r"C:\Program Files\Git\bin\bash.exe", r"C:\Program Files\Git\usr\bin\bash.exe"):
+        if cand and Path(cand).exists() and "System32" not in cand:  # System32\bash.exe is the WSL launcher, not a shell for cwd
+            return "bash", [cand, "-c"]
+    pwsh = shutil.which("pwsh") or shutil.which("powershell") or "powershell"
+    return "powershell", [pwsh, "-NoProfile", "-NonInteractive", "-Command"]
+
+
+class ExecResult(BaseModel):
+    stdout: str
+    stderr: str = ""
+    returncode: int
+    timed_out: bool = False
+
+    @property
+    def text(self) -> str:
+        out = self.stdout
+        if self.stderr:
+            out = f"{out}\n[stderr]\n{self.stderr}" if out else f"[stderr]\n{self.stderr}"
+        return out
+
+
+def decode(data: bytes) -> str:
+    """Estate files are latin-1/CRLF; most of the world is UTF-8. Never raise."""
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return data.decode("latin-1")
+
+
+@runtime_checkable
+class Executor(Protocol):
+    cwd: str
+
+    async def exec(self, command: str, cwd: str | None = None, timeout_sec: int | None = None) -> ExecResult: ...
+    async def read(self, path: str) -> bytes: ...
+    async def write(self, path: str, data: bytes) -> None: ...
+    async def snapshot(self) -> str: ...
+    async def fork(self, snapshot_id: str) -> "Executor": ...
+    async def close(self) -> None: ...
+
+
+class LocalExecutor:
+    """A directory on this machine. Used by tests, the terminal client, and
+    any SME session that runs where the files are."""
+
+    def __init__(self, root: Path, snapshots_dir: Path | None = None):
+        self.root = Path(root).resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.cwd = str(self.root)
+        self.snapshots_dir = Path(snapshots_dir) if snapshots_dir else self.root.parent / f".{self.root.name}.snapshots"
+        self.shell, self._shell_argv = pick_shell()
+
+    def _abs(self, path: str) -> Path:
+        p = Path(path)
+        return p if p.is_absolute() else self.root / p
+
+    async def exec(self, command: str, cwd: str | None = None, timeout_sec: int | None = None) -> ExecResult:
+        proc = await asyncio.create_subprocess_exec(
+            *self._shell_argv, command,
+            cwd=str(self._abs(cwd)) if cwd else self.cwd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            out, err = await asyncio.wait_for(proc.communicate(), timeout=timeout_sec)
+        except asyncio.TimeoutError:
+            proc.kill()
+            out, err = await proc.communicate()
+            return ExecResult(stdout=decode(out), stderr=decode(err), returncode=-9, timed_out=True)
+        return ExecResult(stdout=decode(out), stderr=decode(err), returncode=proc.returncode or 0)
+
+    async def read(self, path: str) -> bytes:
+        return self._abs(path).read_bytes()
+
+    async def write(self, path: str, data: bytes) -> None:
+        p = self._abs(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(data)
+
+    async def snapshot(self) -> str:
+        sid = uuid.uuid4().hex[:12]
+        dst = self.snapshots_dir / sid
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        await asyncio.to_thread(shutil.copytree, self.root, dst, symlinks=True)
+        return sid
+
+    async def fork(self, snapshot_id: str) -> "LocalExecutor":
+        src = self.snapshots_dir / snapshot_id
+        dst = self.snapshots_dir / f"{snapshot_id}-fork-{uuid.uuid4().hex[:6]}"
+        await asyncio.to_thread(shutil.copytree, src, dst, symlinks=True)
+        return LocalExecutor(dst, snapshots_dir=self.snapshots_dir)
+
+    async def close(self) -> None:
+        return None

hum/runtime/grader.py

@@ -0,0 +1,41 @@
+"""The world's opinion. A Grader turns a terminal state into a Verdict. In
+production this is CONTROL through its MCP (blind, gated); in tests it is a
+predicate on the workspace. The runtime treats the grader as the reward AND as
+a tool the agent may call mid-run (verifier in the loop) — same instrument,
+two uses.
+"""
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Protocol
+
+from .executor import Executor
+from .models import Verdict
+
+
+class Grader(Protocol):
+    name: str
+
+    async def grade(self, executor: Executor, task: dict[str, Any]) -> Verdict: ...
+
+
+class PredicateGrader:
+    def __init__(self, name: str, fn: Callable[[Executor, dict[str, Any]], Awaitable[tuple[bool, float, dict[str, Any]]]]):
+        self.name, self.fn = name, fn
+
+    async def grade(self, executor: Executor, task: dict[str, Any]) -> Verdict:
+        passed, score, detail = await self.fn(executor, task)
+        return Verdict(passed=passed, score=score, grader=self.name, detail=detail)
+
+
+class MCPGrader:
+    """Grade by calling a tool on an already-mounted MCP toolset (e.g. control__grade_case).
+    ``to_verdict`` maps the tool's text/JSON output to (passed, score, detail)."""
+
+    def __init__(self, name: str, call: Callable[[dict[str, Any]], Awaitable[str]], args_for: Callable[[dict[str, Any]], dict[str, Any]],
+                 to_verdict: Callable[[str], tuple[bool, float, dict[str, Any]]]):
+        self.name, self._call, self._args_for, self._to_verdict = name, call, args_for, to_verdict
+
+    async def grade(self, executor: Executor, task: dict[str, Any]) -> Verdict:
+        out = await self._call(self._args_for(task))
+        passed, score, detail = self._to_verdict(out)
+        return Verdict(passed=passed, score=score, grader=self.name, detail=detail)

hum/runtime/llm.py

@@ -0,0 +1,225 @@
+"""Model client with native tool calling over litellm. Anything with an
+OpenAI-compatible endpoint works: frontier APIs, OpenRouter, a LiteLLM proxy
+with per-expert keys, or the policy served from the trainer. When the server
+returns token ids / logprobs they are kept on the Turn for token custody.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Awaitable, Callable, Protocol
+
+from .models import ToolCall, Turn, Usage
+
+OnText = Callable[[str], None]
+
+
+class LLM(Protocol):
+    model: str
+
+    async def complete(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None, on_text: OnText | None = None) -> Turn: ...
+
+
+def _raw_usage(resp: Any) -> dict[str, Any]:
+    try:
+        d = resp.model_dump() if hasattr(resp, "model_dump") else dict(resp)
+        return d.get("usage") or {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def _parse(msg: Any, resp: Any, model: str, author: str, cost_hint: float | None = None) -> Turn:
+    calls: list[ToolCall] = []
+    for tc in getattr(msg, "tool_calls", None) or []:
+        try:
+            args = json.loads(tc.function.arguments or "{}")
+        except json.JSONDecodeError:
+            args = {"_raw": tc.function.arguments}
+        calls.append(ToolCall(id=tc.id, name=tc.function.name, arguments=args))
+    u = getattr(resp, "usage", None)
+    raw = _raw_usage(resp)
+    usage = Usage(
+        input_tokens=getattr(u, "prompt_tokens", 0) or 0,
+        output_tokens=getattr(u, "completion_tokens", 0) or 0,
+        cache_tokens=(getattr(getattr(u, "prompt_tokens_details", None), "cached_tokens", 0) or 0),
+        cost_usd=float(cost_hint or raw.get("cost_usd") or raw.get("cost")
+                       or (getattr(resp, "_hidden_params", None) or {}).get("response_cost") or 0.0),
+    ) if u else None
+    return Turn(author=author, content=msg.content or "", reasoning=getattr(msg, "reasoning_content", None),  # type: ignore[arg-type]
+                tool_calls=calls, model=getattr(resp, "model", model) or model, usage=usage, done=not calls)
+
+
+class LiteLLMClient:
+    def __init__(self, model: str, *, api_base: str | None = None, api_key: str | None = None,
+                 temperature: float | None = None, reasoning_effort: str | None = None,
+                 max_tokens: int | None = None, timeout: float = 600.0, extra: dict[str, Any] | None = None,
+                 author: str = "policy", stream: bool = True):
+        self.model = model
+        self.api_base, self.api_key = api_base, api_key
+        self.temperature, self.reasoning_effort, self.max_tokens, self.timeout = temperature, reasoning_effort, max_tokens, timeout
+        self.extra = extra or {}
+        self.author = author
+        self.stream = stream
+
+    def _kwargs(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None) -> dict[str, Any]:
+        kw: dict[str, Any] = dict(model=self.model, messages=messages, timeout=self.timeout, **self.extra)
+        if tools:
+            kw["tools"], kw["tool_choice"] = tools, "auto"
+        if self.api_base:
+            kw["api_base"] = self.api_base
+        if self.api_key:
+            kw["api_key"] = self.api_key
+        if self.temperature is not None:
+            kw["temperature"] = self.temperature
+        if self.reasoning_effort:
+            kw["reasoning_effort"] = self.reasoning_effort
+        if self.max_tokens:
+            kw["max_tokens"] = self.max_tokens
+        return kw
+
+    async def complete(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None, on_text: OnText | None = None) -> Turn:
+        import litellm  # lazy: tests never import it
+
+        litellm.suppress_debug_info = True
+        kw = self._kwargs(messages, tools)
+        if not (self.stream and on_text):
+            resp = await litellm.acompletion(**kw)
+            return _parse(resp.choices[0].message, resp, self.model, self.author)
+        chunks, cost_hint = [], None
+        async for chunk in await litellm.acompletion(stream=True, stream_options={"include_usage": True}, **kw):
+            chunks.append(chunk)
+            delta = chunk.choices[0].delta if chunk.choices else None
+            if delta is not None and getattr(delta, "content", None):
+                on_text(delta.content)
+            ru = _raw_usage(chunk)
+            if ru.get("cost_usd") or ru.get("cost"):
+                cost_hint = float(ru.get("cost_usd") or ru.get("cost"))
+        resp = litellm.stream_chunk_builder(chunks, messages=messages)
+        return _parse(resp.choices[0].message, resp, self.model, self.author, cost_hint=cost_hint)
+
+
+class ScriptedLLM:
+    """Deterministic stand-in for tests and replay: returns pre-written turns in
+    order. ``on_call`` runs before each turn is returned (tests use it to
+    change the workspace between turns, the way a person would)."""
+
+    def __init__(self, turns: list[Turn], model: str = "scripted", on_call: Callable[[int], Awaitable[None] | None] | None = None):
+        self.turns, self.model, self.calls, self.on_call = list(turns), model, [], on_call
+
+    async def complete(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None, on_text: OnText | None = None) -> Turn:
+        self.calls.append(messages)
+        if self.on_call:
+            r = self.on_call(len(self.calls))
+            if r is not None:
+                await r
+        if not self.turns:
+            return Turn(author="policy", content="(script exhausted)", done=True)
+        t = self.turns.pop(0)
+        if on_text and t.content:
+            on_text(t.content)
+        return t
+
+
+class OpenAICompatClient:
+    """Direct OpenAI-compatible client (httpx). Used for our own proxy and any
+    OpenAI-compatible base: exact usage/cost passthrough, no provider shims.
+    Streams SSE and accumulates tool-call deltas."""
+
+    def __init__(self, model: str, *, api_base: str, api_key: str | None = None, temperature: float | None = None,
+                 reasoning_effort: str | None = None, max_tokens: int | None = None, timeout: float = 600.0,
+                 author: str = "policy", stream: bool = True, transport: Any = None):
+        self.model, self.api_base, self.api_key = model.split("/", 1)[1] if model.startswith("openai/") else model, api_base.rstrip("/"), api_key
+        self.temperature, self.reasoning_effort, self.max_tokens, self.timeout = temperature, reasoning_effort, max_tokens, timeout
+        self.author, self.stream, self._transport = author, stream, transport
+
+    def _body(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None, stream: bool) -> dict[str, Any]:
+        b: dict[str, Any] = {"model": self.model, "messages": messages}
+        if tools:
+            b["tools"], b["tool_choice"] = tools, "auto"
+        if self.temperature is not None:
+            b["temperature"] = self.temperature
+        if self.reasoning_effort:
+            b["reasoning_effort"] = self.reasoning_effort
+        if self.max_tokens:
+            b["max_tokens"] = self.max_tokens
+        if stream:
+            b["stream"], b["stream_options"] = True, {"include_usage": True}
+        return b
+
+    def _headers(self) -> dict[str, str]:
+        h = {"content-type": "application/json"}
+        if self.api_key:
+            h["authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    @staticmethod
+    def _usage(u: dict[str, Any] | None) -> Usage | None:
+        if not u:
+            return None
+        return Usage(input_tokens=u.get("prompt_tokens", 0) or 0, output_tokens=u.get("completion_tokens", 0) or 0,
+                     cache_tokens=((u.get("prompt_tokens_details") or {}).get("cached_tokens", 0) or 0),
+                     cost_usd=float(u.get("cost_usd") or u.get("cost") or 0.0))
+
+    @staticmethod
+    def _calls(raw: list[dict[str, Any]] | None) -> list[ToolCall]:
+        out: list[ToolCall] = []
+        for tc in raw or []:
+            fn = tc.get("function") or {}
+            try:
+                args = json.loads(fn.get("arguments") or "{}")
+            except json.JSONDecodeError:
+                args = {"_raw": fn.get("arguments")}
+            out.append(ToolCall(id=tc.get("id") or f"call_{len(out)}", name=fn.get("name") or "", arguments=args))
+        return out
+
+    async def complete(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None, on_text: OnText | None = None) -> Turn:
+        import httpx
+
+        url = f"{self.api_base}/chat/completions"
+        async with httpx.AsyncClient(timeout=self.timeout, transport=self._transport) as http:
+            if not (self.stream and on_text):
+                r = await http.post(url, json=self._body(messages, tools, False), headers=self._headers())
+                if r.status_code != 200:
+                    raise RuntimeError(f"{r.status_code} {r.text[:300]}")
+                d = r.json()
+                msg = d["choices"][0]["message"]
+                calls = self._calls(msg.get("tool_calls"))
+                return Turn(author=self.author, content=msg.get("content") or "", reasoning=msg.get("reasoning_content"),  # type: ignore[arg-type]
+                            tool_calls=calls, model=d.get("model") or self.model, usage=self._usage(d.get("usage")), done=not calls)
+            content, reasoning, usage, model = [], [], None, self.model
+            acc: dict[int, dict[str, Any]] = {}
+            async with http.stream("POST", url, json=self._body(messages, tools, True), headers=self._headers()) as r:
+                if r.status_code != 200:
+                    body = (await r.aread()).decode(errors="replace")
+                    raise RuntimeError(f"{r.status_code} {body[:300]}")
+                async for line in r.aiter_lines():
+                    if not line.startswith("data:"):
+                        continue
+                    data = line[5:].strip()
+                    if data == "[DONE]":
+                        break
+                    try:
+                        d = json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+                    model = d.get("model") or model
+                    if d.get("usage"):
+                        usage = d["usage"]
+                    for ch in d.get("choices") or []:
+                        delta = ch.get("delta") or {}
+                        if delta.get("content"):
+                            content.append(delta["content"]); on_text(delta["content"])
+                        if delta.get("reasoning_content"):
+                            reasoning.append(delta["reasoning_content"])
+                        for tc in delta.get("tool_calls") or []:
+                            i = tc.get("index", 0)
+                            a = acc.setdefault(i, {"id": None, "function": {"name": "", "arguments": ""}})
+                            if tc.get("id"):
+                                a["id"] = tc["id"]
+                            fn = tc.get("function") or {}
+                            if fn.get("name"):
+                                a["function"]["name"] += fn["name"]
+                            if fn.get("arguments"):
+                                a["function"]["arguments"] += fn["arguments"]
+            calls = self._calls([acc[i] for i in sorted(acc)])
+            return Turn(author=self.author, content="".join(content), reasoning="".join(reasoning) or None,  # type: ignore[arg-type]
+                        tool_calls=calls, model=model, usage=self._usage(usage), done=not calls)