provekit 0.1.0__py3-none-any.whl

provekit/services/promptfoo.py

@@ -0,0 +1,92 @@
+"""Convert a promptfoo config into .provekit test files.
+
+Promptfoo is the de-facto eval format and OpenAI's official migration target after it
+shut down its own hosted Evals — so importing it is the on-ramp for that user base.
+We map the common, faithfully-translatable pieces and REPORT what we skip (never a
+silent drop): unknown providers, code (javascript/python) asserts, etc.
+"""
+from __future__ import annotations
+
+import yaml
+
+from . import testfile
+
+# promptfoo assert.type -> (our type, field-mapper)
+_CONTAINS = {"contains", "icontains", "contains-any", "contains-all"}
+_EQUALS = {"equals", "is-equals"}
+_JUDGE = {"llm-rubric", "model-graded-closedqa", "model-graded-factuality", "factuality", "g-eval"}
+
+
+def _map_assert(a: dict) -> tuple[dict | None, str | None]:
+    t = a.get("type", "")
+    val = a.get("value")
+    if t in _CONTAINS:
+        return {"type": "contains", "value": val}, None
+    if t in _EQUALS:
+        return {"type": "equals", "value": val}, None
+    if t == "regex":
+        return {"type": "regex", "value": val}, None
+    if t in ("is-json", "is-valid-json"):
+        schema = val if isinstance(val, dict) else {}
+        return {"type": "json_schema", "schema": schema}, None
+    if t in ("latency", "latency-lt"):
+        return {"type": "latency_lt", "value": a.get("threshold", val)}, None
+    if t in _JUDGE:
+        return {"type": "llm_judge", "criteria": val}, None
+    return None, f"unsupported assert type '{t}'"
+
+
+def _provider_to_request(provider) -> tuple[dict, str | None]:
+    """Return (partial request, connection_name). Handles 'openai:gpt-4o' shorthand and
+    the http provider; falls back to a prompt with the raw provider id as the connection."""
+    if isinstance(provider, str):
+        label, _, model = provider.partition(":")
+        return {"type": "prompt", "model": model or label}, label
+    if isinstance(provider, dict):
+        pid = provider.get("id", "")
+        cfg = provider.get("config") or {}
+        if pid in ("http", "https") or cfg.get("url"):
+            return {"type": "agent", "method": cfg.get("method", "POST"),
+                    "path": "", "body": cfg.get("body")}, pid or "http"
+        label, _, model = pid.partition(":")
+        return {"type": "prompt", "model": model or label}, label
+    return {"type": "prompt", "model": ""}, None
+
+
+def import_promptfoo(text: str) -> tuple[list[tuple[str, str]], list[str]]:
+    """Returns (files, warnings) where files = [(filename, yaml_text), ...]."""
+    cfg = yaml.safe_load(text) or {}
+    providers = cfg.get("providers") or [None]
+    prompts = cfg.get("prompts") or ["{{prompt}}"]
+    tests = cfg.get("tests") or []
+    warnings: list[str] = []
+
+    req_base, conn = _provider_to_request(providers[0])
+    if len(providers) > 1:
+        warnings.append(f"{len(providers)} providers found — importing only the first ({conn})")
+    user_prompt = prompts[0] if isinstance(prompts[0], str) else "{{prompt}}"
+    if len(prompts) > 1:
+        warnings.append(f"{len(prompts)} prompts found — importing only the first")
+
+    files: list[tuple[str, str]] = []
+    for i, test in enumerate(tests):
+        asserts, skipped = [], 0
+        for a in test.get("assert") or []:
+            mapped, warn = _map_assert(a)
+            if mapped:
+                asserts.append(mapped)
+            else:
+                skipped += 1
+                warnings.append(f"test {i + 1}: {warn}")
+        request = dict(req_base)
+        if request["type"] == "prompt":
+            request["user"] = user_prompt
+        request["assertions"] = asserts
+        name = test.get("description") or f"promptfoo test {i + 1}"
+        dataset = [{"name": name, "variables": test.get("vars") or {}}] if test.get("vars") else None
+        yaml_text = testfile.dump_test(name, request, conn, dataset)
+        files.append((f"promptfoo-{i + 1}.yaml", yaml_text))
+
+    if not tests:
+        warnings.append("no tests found in the promptfoo config")
+    return files, warnings

provekit/services/providers/a2a_client.py

@@ -0,0 +1,110 @@
+"""A2A (Agent2Agent) client — talk to any agent that speaks the Linux Foundation A2A
+protocol. A2A hit v1.0 with 150+ orgs (AWS/Microsoft/ServiceNow/Salesforce) but the
+official inspector is hobby-grade, so a real client is open ground.
+
+Supported: agent-card discovery (v1.0 /.well-known/agent-card.json AND the v0.3
+/.well-known/agent.json path), JSON-RPC 2.0 message/send (+ best-effort message/stream).
+"""
+from __future__ import annotations
+
+import json
+import uuid
+
+import httpx
+
+from ..netguard import guard_url
+
+_CARD_PATHS = ["/.well-known/agent-card.json", "/.well-known/agent.json"]  # v1.0, then v0.3
+
+
+async def fetch_card(base_url: str, headers: dict | None = None, timeout: float = 15) -> dict:
+    """Fetch + lightly validate an agent card. Tries the v1.0 path then the v0.3 path."""
+    base = base_url.rstrip("/")
+    guard_url(base)
+    last = None
+    async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
+        for path in _CARD_PATHS:
+            try:
+                r = await client.get(base + path, headers=headers or None)
+                if r.status_code == 200:
+                    card = r.json()
+                    if not isinstance(card, dict) or not card.get("name"):
+                        raise ValueError("agent card missing 'name'")
+                    card["_path"] = path
+                    card["_version"] = card.get("protocolVersion") or card.get("version") or "unknown"
+                    return card
+                last = f"HTTP {r.status_code}"
+            except Exception as exc:  # try the next path
+                last = str(exc)
+    raise RuntimeError(f"no agent card at {base} ({last})")
+
+
+def _extract_text(result: dict) -> str:
+    """Pull text out of an A2A Message or Task result (parts / artifacts / status)."""
+    def parts_text(parts):
+        return "".join(p.get("text", "") for p in (parts or []) if p.get("kind", "text") == "text")
+
+    if not isinstance(result, dict):
+        return ""
+    if result.get("parts"):                      # a Message
+        return parts_text(result["parts"])
+    text = ""
+    for art in result.get("artifacts") or []:    # a Task's artifacts
+        text += parts_text(art.get("parts"))
+    if text:
+        return text
+    status = result.get("status") or {}
+    return parts_text((status.get("message") or {}).get("parts"))
+
+
+def _endpoint(base_url: str, card: dict | None) -> str:
+    # A2A v1.0 puts the JSON-RPC endpoint in the card's `url`.
+    return (card or {}).get("url") or base_url.rstrip("/")
+
+
+async def arun(*, base_url: str, text: str, headers: dict | None = None, stream: bool = False,
+               card: dict | None = None, timeout: float = 120):
+    """Send one message to an A2A agent; yield unified events (delta/result)."""
+    endpoint = _endpoint(base_url, card)
+    guard_url(endpoint)
+    message = {"messageId": uuid.uuid4().hex, "role": "user",
+               "parts": [{"kind": "text", "text": text}]}
+    method = "message/stream" if stream else "message/send"
+    payload = {"jsonrpc": "2.0", "id": uuid.uuid4().hex, "method": method,
+               "params": {"message": message}}
+    hdrs = {"Content-Type": "application/json", **(headers or {})}
+
+    # follow_redirects stays False: guard_url only vetted the initial endpoint (SSRF).
+    async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
+        if stream:
+            collected = ""
+            async with client.stream("POST", endpoint, json=payload, headers=hdrs) as resp:
+                if resp.status_code >= 400:
+                    raise RuntimeError(f"A2A error {resp.status_code}: {(await resp.aread()).decode()[:300]}")
+                async for line in resp.aiter_lines():
+                    if not line or not line.startswith("data:"):
+                        continue
+                    try:
+                        evt = json.loads(line[5:].strip())
+                    except json.JSONDecodeError:
+                        continue
+                    result = evt.get("result", evt)
+                    chunk = _extract_text(result)
+                    if chunk:
+                        collected += chunk
+                        yield {"type": "delta", "text": chunk}
+            yield {"type": "result", "data": {"text": collected} if collected else None,
+                   "meta": {"protocol": "a2a", "streamed": True}}
+            return
+
+        resp = await client.post(endpoint, json=payload, headers=hdrs)
+        if resp.status_code >= 400:
+            raise RuntimeError(f"A2A error {resp.status_code}: {resp.text[:300]}")
+        data = resp.json()
+        if "error" in data:
+            raise RuntimeError(str((data["error"] or {}).get("message", "A2A error")))
+        result = data.get("result", data)
+        text_out = _extract_text(result)
+        if text_out:
+            yield {"type": "delta", "text": text_out}
+        yield {"type": "result", "data": result, "meta": {"protocol": "a2a"}}

provekit/services/providers/agent_http.py

@@ -0,0 +1,55 @@
+"""Generic HTTP agent caller (async) — call any agent/API endpoint, with optional SSE
+streaming. Yields {"type":"delta"} for streamed text/events and {"type":"result"} for a
+buffered JSON/text response."""
+from __future__ import annotations
+
+import json
+
+import httpx
+
+from ..netguard import guard_url
+
+# Cap a buffered agent response so a hostile/misbehaving endpoint can't OOM the worker.
+MAX_RESPONSE_BYTES = 16 * 1024 * 1024
+
+
+async def arun(*, base_url: str, method: str, path: str, headers: dict | None = None,
+               body=None, stream: bool = False, timeout: float = 120):
+    url = base_url.rstrip("/") + "/" + path.lstrip("/") if path else base_url.rstrip("/")
+    guard_url(url)
+    method = (method or "POST").upper()
+    hdrs = {"Accept": "application/json, text/event-stream", **(headers or {})}
+
+    # follow_redirects stays False (httpx default) on purpose: guard_url only vetted the
+    # initial URL, so a redirect could point at an internal address (SSRF).
+    async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
+        if stream:
+            async with client.stream(method, url, json=body if body is not None else None, headers=hdrs) as resp:
+                status = resp.status_code
+                async for line in resp.aiter_lines():
+                    if not line:
+                        continue
+                    if line.startswith("data:"):
+                        data = line[5:].strip()
+                        if data == "[DONE]":
+                            break
+                        try:
+                            yield {"type": "event", "data": json.loads(data)}
+                        except json.JSONDecodeError:
+                            yield {"type": "delta", "text": data}
+                    else:
+                        yield {"type": "delta", "text": line}
+                yield {"type": "result", "data": None, "meta": {"status": status, "streamed": True}}
+            return
+
+        async with client.stream(method, url, json=body if body is not None else None, headers=hdrs) as resp:
+            status = resp.status_code
+            ctype = resp.headers.get("content-type", "")
+            buf = bytearray()
+            async for chunk in resp.aiter_bytes():
+                buf += chunk
+                if len(buf) > MAX_RESPONSE_BYTES:
+                    raise ValueError(f"agent response exceeded {MAX_RESPONSE_BYTES} bytes")
+            raw = bytes(buf)
+        data = json.loads(raw) if ctype.startswith("application/json") and raw else raw.decode("utf-8", "replace")
+        yield {"type": "result", "data": data, "meta": {"status": status}}

provekit/services/providers/llm.py

@@ -0,0 +1,364 @@
+"""Generic LLM streaming over httpx.AsyncClient — provider-agnostic (OpenAI, Anthropic,
+any OpenAI-compatible base URL, OpenAI Responses / Open Responses).
+
+`astream(...)` is an async generator yielding {"type":"delta"} tokens, optional
+{"type":"node"} stop events, {"type":"tool_call"} when the model asks for a tool, and a
+final {"type":"usage"}. Async so a long stream occupies the event loop, not a threadpool
+thread.
+
+Messages are provider-agnostic; each provider translates them on the way out:
+
+    {"role": "user",      "content": str}
+    {"role": "assistant", "content": str, "tool_calls": [{"id", "name", "args"}]}
+    {"role": "tool",      "tool_call_id": str, "name": str, "content": str}
+
+The caller (dispatch) owns the tool loop — it appends the assistant/tool turns above and
+calls astream again. Providers disagree on how a tool round is represented, which is
+exactly why that shape is normalized here rather than leaking into the dispatcher.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+
+from ..netguard import guard_url
+
+
+def _mock_reply(user: str, system: str | None) -> str:
+    """Canned but context-aware reply for the keyless demo agent."""
+    u = (user or "").lower()
+    sys = (system or "").lower()
+    if not user:
+        return "Hi — I'm the ProveKit demo agent. Ask me anything. I run with no API key, so you can try the console instantly."
+    if "classify" in sys or "classify" in u:
+        return "support_request"
+    if "extract" in sys or "json" in sys:
+        return '{"summary": "demo extraction", "priority": "normal", "is_demo": true}'
+    if "agent" in u and any(k in u for k in ("what", "explain", "define")):
+        return ("An AI agent is a program that reads context, decides on an action, and uses tools or model "
+                "calls to reach a goal — often looping until the task is done. This reply came from ProveKit's "
+                "built-in mock provider, so no API key was needed.")
+    if any(k in u for k in ("urgent", "angry", "complaint", "refund", "cancel", "asap")):
+        return "This looks urgent — it mentions a time-sensitive or negative signal, so I'd route it to a human. (Demo mock response.)"
+    short = " ".join((user or "").split())[:160]
+    return (f"Here's a demo answer to: \"{short}\". In a live run this would come from your OpenAI or Anthropic "
+            "connection — swap one in from the Connections tab. For now this is ProveKit's keyless mock agent.")
+
+
+def _mock_tool_args(schema: dict, user: str) -> dict:
+    """Fill a tool's required string params with the user's text — enough for the keyless
+    demo to make a real, plausible MCP call."""
+    props = (schema or {}).get("properties") or {}
+    args = {}
+    for name in (schema or {}).get("required") or []:
+        spec = props.get(name) or {}
+        t = spec.get("type", "string")
+        if t == "string":
+            args[name] = " ".join((user or "demo").split())[:80]
+        elif t in ("number", "integer"):
+            args[name] = 1
+        elif t == "boolean":
+            args[name] = True
+    return args
+
+
+async def _stream_mock(system, messages, tools=None):
+    """Stream a canned reply token-by-token — a working agent with no credentials.
+
+    With tools attached it calls the first one once, then answers using the result, so the
+    whole MCP tool-calling loop is demonstrable offline with no API key.
+    """
+    user = next((str(m.get("content") or "") for m in reversed(messages) if m.get("role") == "user"), "")
+    already_ran = any(m.get("role") == "tool" for m in messages)
+    if tools and not already_ran:
+        t = tools[0]
+        # the three provider tool schemas nest the name/params differently
+        fn = t.get("function") or t
+        schema = fn.get("parameters") or fn.get("input_schema") or {}
+        yield {"type": "tool_call", "call": {"id": "mock-call-1", "name": fn.get("name", ""),
+                                             "args": _mock_tool_args(schema, user)}}
+        return
+    if already_ran:
+        out = next((str(m.get("content") or "") for m in reversed(messages) if m.get("role") == "tool"), "")
+        reply = (f"The tool returned: {' '.join(out.split())[:200]}. "
+                 "(Demo mock agent — it called a real MCP tool, with no API key.)")
+    else:
+        reply = _mock_reply(user, system)
+    spent = 0.0  # cap total artificial delay so concurrent demo runs stay cheap
+    for tok in reply.split(" "):
+        yield {"type": "delta", "text": tok + " "}
+        if spent < 0.6:
+            await asyncio.sleep(0.012); spent += 0.012
+    ptok = sum(len(str(m.get("content") or "").split()) for m in messages) + len((system or "").split())
+    ctok = len(reply.split())
+    yield {"type": "usage", "usage": {"prompt_tokens": ptok, "completion_tokens": ctok, "total_tokens": ptok + ctok}}
+
+
+DEFAULT_BASE = {
+    "openai": "https://api.openai.com/v1",
+    "openai-responses": "https://api.openai.com/v1",
+    "compatible": "http://localhost:11434/v1",
+    "anthropic": "https://api.anthropic.com/v1",
+}
+
+
+# Some 2026 models reject sampling params — send temperature only when it's meaningful.
+def _maybe_temp(body: dict, temperature: float) -> None:
+    if temperature is not None:
+        body["temperature"] = temperature
+
+
+async def _aiter_sse(resp: httpx.Response):
+    """Yield parsed `data:` JSON objects from an SSE response (skips [DONE])."""
+    async for line in resp.aiter_lines():
+        if not line or not line.startswith("data:"):
+            continue
+        data = line[5:].strip()
+        if data == "[DONE]":
+            return
+        try:
+            yield json.loads(data)
+        except json.JSONDecodeError:
+            continue
+
+
+async def astream(*, provider: str, base_url: str, api_key: str, model: str,
+                  system: str | None, messages: list[dict], temperature: float = 0.7,
+                  max_tokens: int = 1024, tools: list[dict] | None = None):
+    provider = (provider or "openai").lower()
+    base = (base_url or DEFAULT_BASE.get(provider) or DEFAULT_BASE["openai"]).rstrip("/")
+
+    if provider == "mock":
+        async for ev in _stream_mock(system, messages, tools):
+            yield ev
+        return
+    guard_url(base)
+    if provider == "anthropic":
+        gen = _stream_anthropic(base, api_key, model, system, messages, temperature, max_tokens, tools)
+    elif provider == "openai-responses":
+        gen = _stream_responses(base, api_key, model, system, messages, temperature, max_tokens, tools)
+    else:
+        gen = _stream_openai(base, api_key, model, system, messages, temperature, max_tokens, tools)
+    async for ev in gen:
+        yield ev
+
+
+def _args(raw: str) -> dict:
+    """Tool arguments arrive as a JSON string, streamed in fragments. A model can emit
+    invalid JSON; that's a failed tool call, not a failed run, so it degrades to {}."""
+    try:
+        out = json.loads(raw or "{}")
+        return out if isinstance(out, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+def collect_text_sync(**kwargs) -> str:
+    """Drive astream to completion and return the concatenated text — for sync callers
+    (the LLM-judge assertion, the CLI). Runs its own event loop; never call from within one."""
+    async def _run():
+        parts = []
+        async for ev in astream(**kwargs):
+            if ev["type"] == "delta":
+                parts.append(ev["text"])
+        return "".join(parts)
+    return asyncio.run(_run())
+
+
+def _openai_messages(messages: list[dict]) -> list[dict]:
+    out = []
+    for m in messages:
+        if m.get("role") == "tool":
+            out.append({"role": "tool", "tool_call_id": m.get("tool_call_id"),
+                        "content": m.get("content", "")})
+        elif m.get("tool_calls"):
+            out.append({"role": "assistant", "content": m.get("content") or None,
+                        "tool_calls": [{"id": c["id"], "type": "function",
+                                        "function": {"name": c["name"],
+                                                     "arguments": json.dumps(c.get("args") or {})}}
+                                       for c in m["tool_calls"]]})
+        else:
+            out.append({"role": m.get("role", "user"), "content": m.get("content", "")})
+    return out
+
+
+async def _stream_openai(base, api_key, model, system, messages, temperature, max_tokens, tools=None):
+    msgs = ([{"role": "system", "content": system}] if system else []) + _openai_messages(messages)
+    body = {"model": model, "messages": msgs, "stream": True,
+            "temperature": temperature, "max_tokens": max_tokens,
+            "stream_options": {"include_usage": True}}
+    if tools:
+        body["tools"] = tools
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    async with httpx.AsyncClient(timeout=120, follow_redirects=False) as client:
+        async with client.stream("POST", f"{base}/chat/completions", json=body, headers=headers) as resp:
+            if resp.status_code >= 400:
+                raise RuntimeError(f"LLM error {resp.status_code}: {(await resp.aread()).decode()[:400]}")
+            # tool_calls stream in fragments keyed by index: the id and name land on the
+            # first chunk, then `arguments` arrives a few characters at a time.
+            pending: dict[int, dict] = {}
+            async for obj in _aiter_sse(resp):
+                for choice in obj.get("choices", []):
+                    delta = choice.get("delta") or {}
+                    if delta.get("content"):
+                        yield {"type": "delta", "text": delta["content"]}
+                    for tc in delta.get("tool_calls") or []:
+                        slot = pending.setdefault(tc.get("index", 0), {"id": "", "name": "", "raw": ""})
+                        if tc.get("id"):
+                            slot["id"] = tc["id"]
+                        fn = tc.get("function") or {}
+                        if fn.get("name"):
+                            slot["name"] = fn["name"]
+                        if fn.get("arguments"):
+                            slot["raw"] += fn["arguments"]
+                if obj.get("usage"):
+                    yield {"type": "usage", "usage": obj["usage"]}
+            for slot in pending.values():
+                if slot["name"]:
+                    yield {"type": "tool_call",
+                           "call": {"id": slot["id"], "name": slot["name"], "args": _args(slot["raw"])}}
+
+
+def _responses_input(messages: list[dict]) -> list[dict]:
+    """Responses takes a flat item list: a tool round is a function_call item followed by a
+    matching function_call_output item, not assistant/tool roles."""
+    items = []
+    for m in messages:
+        if m.get("role") == "tool":
+            items.append({"type": "function_call_output", "call_id": m.get("tool_call_id"),
+                          "output": m.get("content", "")})
+            continue
+        if m.get("content"):
+            items.append({"role": "assistant" if m.get("role") == "assistant" else "user",
+                          "content": m["content"]})
+        for c in m.get("tool_calls") or []:
+            items.append({"type": "function_call", "call_id": c["id"], "name": c["name"],
+                          "arguments": json.dumps(c.get("args") or {})})
+    return items
+
+
+async def _stream_responses(base, api_key, model, system, messages, temperature, max_tokens, tools=None):
+    """OpenAI Responses API / 'Open Responses' (also vLLM, Ollama, HF, OpenRouter)."""
+    body = {"model": model, "input": _responses_input(messages), "stream": True,
+            "max_output_tokens": max_tokens}
+    if tools:
+        body["tools"] = tools
+    if system:
+        body["instructions"] = system
+    _maybe_temp(body, temperature)
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    async with httpx.AsyncClient(timeout=120, follow_redirects=False) as client:
+        async with client.stream("POST", f"{base}/responses", json=body, headers=headers) as resp:
+            if resp.status_code >= 400:
+                raise RuntimeError(f"LLM error {resp.status_code}: {(await resp.aread()).decode()[:400]}")
+            # `.added` announces the call with EMPTY arguments; `.done` carries the filled-in
+            # ones. Both are kept in one slot per call_id so the later, fuller payload wins —
+            # taking the first and deduping would report every call with no arguments at all.
+            pending: dict[str, dict] = {}
+            async for obj in _aiter_sse(resp):
+                et = obj.get("type", "")
+                if et == "response.output_text.delta" and obj.get("delta"):
+                    yield {"type": "delta", "text": obj["delta"]}
+                elif et in ("response.output_item.added", "response.output_item.done"):
+                    item = obj.get("item") or {}
+                    if item.get("type") != "function_call":
+                        continue
+                    cid = item.get("call_id") or item.get("id") or ""
+                    slot = pending.setdefault(cid, {"name": "", "raw": ""})
+                    if item.get("name"):
+                        slot["name"] = item["name"]
+                    if item.get("arguments"):
+                        slot["raw"] = item["arguments"]
+                    if et.endswith(".done") and slot["name"]:
+                        yield {"type": "tool_call",
+                               "call": {"id": cid, "name": slot["name"], "args": _args(slot["raw"])}}
+                        pending.pop(cid, None)
+                elif et in ("response.completed", "response.incomplete"):
+                    usage = (obj.get("response") or {}).get("usage")
+                    if usage:
+                        yield {"type": "usage", "usage": usage}
+            for cid, slot in pending.items():
+                if slot["name"]:  # announced but never completed — report it rather than lose it
+                    yield {"type": "tool_call",
+                           "call": {"id": cid, "name": slot["name"], "args": _args(slot["raw"])}}
+
+
+def _anthropic_messages(messages: list[dict]) -> list[dict]:
+    """Anthropic carries a tool round as content blocks: tool_use on the assistant turn, and
+    tool_result blocks on the *user* turn. Consecutive results must be merged into one user
+    message — a separate message per result is rejected."""
+    out: list[dict] = []
+    for m in messages:
+        role = m.get("role")
+        if role == "tool":
+            block = {"type": "tool_result", "tool_use_id": m.get("tool_call_id"),
+                     "content": m.get("content", "")}
+            if out and out[-1]["role"] == "user" and isinstance(out[-1]["content"], list):
+                out[-1]["content"].append(block)
+            else:
+                out.append({"role": "user", "content": [block]})
+        elif m.get("tool_calls"):
+            blocks = ([{"type": "text", "text": m["content"]}] if m.get("content") else [])
+            blocks += [{"type": "tool_use", "id": c["id"], "name": c["name"],
+                        "input": c.get("args") or {}} for c in m["tool_calls"]]
+            out.append({"role": "assistant", "content": blocks})
+        elif role in ("user", "assistant"):
+            out.append({"role": role, "content": m.get("content", "")})
+    return out
+
+
+async def _stream_anthropic(base, api_key, model, system, messages, temperature, max_tokens, tools=None):
+    body = {"model": model, "messages": _anthropic_messages(messages), "stream": True,
+            "max_tokens": max_tokens}
+    if tools:
+        body["tools"] = tools
+    _maybe_temp(body, temperature)
+    if system:
+        body["system"] = system
+    headers = {"Content-Type": "application/json", "anthropic-version": "2023-06-01"}
+    if api_key:
+        headers["x-api-key"] = api_key
+    async with httpx.AsyncClient(timeout=120, follow_redirects=False) as client:
+        async with client.stream("POST", f"{base}/messages", json=body, headers=headers) as resp:
+            if resp.status_code >= 400:
+                raise RuntimeError(f"LLM error {resp.status_code}: {(await resp.aread()).decode()[:400]}")
+            usage = {}
+            cur: dict | None = None  # the tool_use block being streamed, if any
+            async for obj in _aiter_sse(resp):
+                t = obj.get("type")
+                if t == "content_block_start":
+                    blk = obj.get("content_block") or {}
+                    if blk.get("type") == "tool_use":
+                        cur = {"id": blk.get("id", ""), "name": blk.get("name", ""), "raw": ""}
+                elif t == "content_block_delta":
+                    d = obj.get("delta") or {}
+                    if d.get("type") == "text_delta" and d.get("text"):
+                        yield {"type": "delta", "text": d["text"]}
+                    elif d.get("type") == "input_json_delta" and cur is not None:
+                        # the tool's input object arrives as JSON text fragments
+                        cur["raw"] += d.get("partial_json") or ""
+                elif t == "content_block_stop" and cur is not None:
+                    yield {"type": "tool_call",
+                           "call": {"id": cur["id"], "name": cur["name"], "args": _args(cur["raw"])}}
+                    cur = None
+                elif t == "message_start":
+                    usage = (obj.get("message") or {}).get("usage", {}) or usage
+                elif t == "message_delta":
+                    if obj.get("usage"):
+                        usage = {**usage, **obj["usage"]}
+                    stop = (obj.get("delta") or {}).get("stop_reason")
+                    if stop and stop not in ("end_turn", "stop_sequence"):
+                        yield {"type": "node", "data": {"stop_reason": stop}}
+            if cur is not None:
+                # Stream ended without a content_block_stop (truncated/aborted): still report
+                # the call rather than losing it.
+                yield {"type": "tool_call",
+                       "call": {"id": cur["id"], "name": cur["name"], "args": _args(cur["raw"])}}
+            if usage:
+                yield {"type": "usage", "usage": usage}