ecadlib 0.3.0__py3-none-any.whl

ecadlib/llm/__init__.py

@@ -0,0 +1,276 @@
+"""Bring your own model: which provider, model, endpoint and key every AI feature uses.
+
+Two providers:
+  anthropic          Claude through the Messages API (datasheet.Client, unchanged: PDF document blocks, structured
+                     outputs, Message Batches, prompt caching, server-side refusal fallback). The default.
+  openai-compatible  any /v1/chat/completions server: OpenAI, OpenRouter, Google's OpenAI-compatible Gemini endpoint,
+                     and local servers (Ollama, LM Studio, vLLM, llama.cpp). base_url + the NAME of the env var holding
+                     the key; a local server needs no key. ecadlib.llm.openai_compat translates our Messages-shaped
+                     requests and answers, so everything after the call (checks, cache, cost ledger) is shared.
+
+Settings (ecadlib.toml), all optional - with no [ai] table everything is exactly as before (Claude Opus 5.5):
+
+    [ai]
+    provider = "anthropic"        # anthropic | openai-compatible | a preset: openai, openrouter, gemini, ollama,
+                                  #   lmstudio, vllm, llamacpp (preset = openai-compatible + its usual base_url / key var)
+    model = ""                    # "" = [datasheet] model (claude-opus-5-5)
+    base_url = ""                 # openai-compatible only; "" = the preset's
+    api_key_env = ""              # NAME of the env var with the key ("" = the preset's; none for local servers)
+    assist = "auto"               # guide rails: auto (by the model's tier) | off | full   (ecadlib.llm.rails)
+    feedback_retry = true         # one retry that feeds datasheet's exact check errors back (every model, Claude too)
+    detect = true                 # ask an openai-compatible server what the model can do (context, vision, price)
+    temperature = "auto"          # auto | off | 0..2: temperature 0 + seed where the model takes them (llm.sampling)
+    [ai.profiles."qwen2.5:7b"]    # override what ecadlib assumes about a model (ecadlib.llm.profiles)
+    tier = "small"                # frontier | mid | small
+    [ai.endpoints.local]          # named endpoints for a mixed ladder: [datasheet] ladder = ["local:qwen2.5:7b",
+    provider = "ollama"           #   "claude-opus-5-5"] tries the local model first and escalates to Claude
+
+[datasheet] and [agent.proof] may set provider / base_url / api_key_env / model / assist of their own; empty = [ai].
+Keys are read from environment variables only and never written anywhere. Nothing here phones home: no telemetry,
+no hosted service of this project; requests go only to the endpoint you configure."""
+import ipaddress, os, re
+from urllib.parse import urlparse
+
+PROVIDERS = ("anthropic", "openai-compatible")
+# preset name -> (base_url, key env var name); every preset is an openai-compatible endpoint
+PRESETS = {"openai": ("https://api.openai.com/v1", "OPENAI_API_KEY"),
+           "openrouter": ("https://openrouter.ai/api/v1", "OPENROUTER_API_KEY"),
+           "gemini": ("https://generativelanguage.googleapis.com/v1beta/openai", "GEMINI_API_KEY"),
+           "ollama": ("http://localhost:11434/v1", ""),
+           "lmstudio": ("http://localhost:1234/v1", ""),
+           "vllm": ("http://localhost:8000/v1", ""),
+           "llamacpp": ("http://localhost:8080/v1", "")}
+ASSIST = ("auto", "off", "full")
+ANTHROPIC_MODEL = "claude-opus-5-5"
+ANTHROPIC_KEY = "ANTHROPIC_API_KEY"
+DEFAULTS = {"provider": "anthropic", "model": "", "base_url": "", "api_key_env": "", "assist": "auto",
+            "feedback_retry": True, "detect": True, "profiles": {}, "endpoints": {}, "temperature": "auto"}
+SECTION_KEYS = ("provider", "base_url", "assist")       # added to [datasheet] and [agent.proof] (empty = [ai])
+MODEL_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+\-]{0,199}")
+ENV_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+ENDPOINT_KEYS = ("provider", "base_url", "api_key_env", "assist")
+NO_KEY = "no-key-needed"                                # a local endpoint: there is no key to send
+
+
+class AIConfigError(ValueError):
+    pass
+
+
+def is_local(url):
+    """localhost, loopback, private and link-local addresses, *.local / *.lan hosts: a server on your own network."""
+    host = (urlparse(url or "").hostname or "").lower()
+    if not host:
+        return False
+    if host in ("localhost", "host.docker.internal") or host.endswith((".local", ".lan", ".internal", ".localhost")):
+        return True
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return ip.is_loopback or ip.is_private or ip.is_link_local
+
+
+def _ai(rules):
+    got = (rules or {}).get("ai") if isinstance(rules, dict) else None
+    return {**DEFAULTS, **{k: v for k, v in (got or {}).items() if k in DEFAULTS}}
+
+
+def _section(rules, section):
+    r = rules if isinstance(rules, dict) else {}
+    if section == "proof":
+        return ((r.get("agent") or {}).get("proof") or {})
+    return r.get(section) or {}
+
+
+def _norm_provider(p):
+    """-> (provider, preset or None)."""
+    p = (p or "anthropic").strip().lower()
+    if p in PRESETS:
+        return "openai-compatible", p
+    if p in ("openai-compatible", "openai_compatible", "openai-compat"):
+        return "openai-compatible", None
+    if p == "anthropic":
+        return "anthropic", None
+    raise AIConfigError(f"provider {p!r}: use anthropic, openai-compatible or one of {', '.join(PRESETS)}")
+
+
+def split_ref(ref, rules=None):
+    """'local:qwen2.5:7b' -> ('local', 'qwen2.5:7b') when [ai.endpoints.local] exists, else (None, ref)."""
+    eps = _ai(rules).get("endpoints") or {}
+    head, sep, rest = str(ref or "").partition(":")
+    if sep and head in eps and rest:
+        return head, rest
+    return None, ref
+
+
+def endpoint(rules=None, section="datasheet", model=None):
+    """Where a request for `section` goes: {provider, preset, base_url, key_env, model, ref, name, local, assist,
+    feedback_retry, detect}. `model` (an explicit --model or a ladder rung) may name an endpoint: 'local:qwen2.5:7b'.
+    With no [ai] table and no section overrides this is Anthropic + [datasheet] model + [datasheet] api_key_env."""
+    ai, sec = _ai(rules), _section(rules, section)
+    ds = _section(rules, "datasheet")
+    if section == "proof":                                # [agent.proof] empty = [datasheet] (as before)
+        sec = {k: sec.get(k) or ds.get(k) for k in set(sec) | set(ds) | {"provider", "base_url", "assist", "model",
+                                                                         "api_key_env"}}
+    name, mref = split_ref(model, rules) if model else (None, None)
+    if name:
+        ep_cfg = ai["endpoints"][name] or {}
+        provider, preset = _norm_provider(ep_cfg.get("provider") or "openai-compatible")
+        base = ep_cfg.get("base_url") or (PRESETS[preset][0] if preset else "")
+        key_env = ep_cfg.get("api_key_env") or (PRESETS[preset][1] if preset else "")
+        assist = ep_cfg.get("assist") or sec.get("assist") or ai["assist"]
+    else:
+        provider, preset = _norm_provider(sec.get("provider") or ai["provider"])
+        own_provider = bool(sec.get("provider"))
+        base = sec.get("base_url") or ("" if own_provider and sec.get("provider") != ai["provider"] else ai["base_url"]) \
+            or (PRESETS[preset][0] if preset else "")
+        sk = sec.get("api_key_env") or ""
+        if sk == ANTHROPIC_KEY and (provider != "anthropic" or ai["api_key_env"]):
+            sk = ""                                       # [datasheet]'s default key name: [ai] api_key_env / the endpoint's decide
+        key_env = sk or ai["api_key_env"] or (PRESETS[preset][1] if preset else "") or \
+            (ANTHROPIC_KEY if provider == "anthropic" else "")
+        assist = sec.get("assist") or ai["assist"]
+        mref = model
+    if not mref:
+        sm = sec.get("model") or ""
+        if section in ("datasheet", "proof") and sm == ANTHROPIC_MODEL and (ai["model"] or provider != "anthropic"):
+            sm = ""                                       # [datasheet] model at its default: [ai] model decides
+        mref = sm or ai["model"] or (ANTHROPIC_MODEL if provider == "anthropic" else "")
+    if not mref:
+        raise AIConfigError(f"no model set for provider {preset or provider}: set [ai] model (e.g. \"qwen2.5:7b\" for "
+                            "Ollama, \"gpt-5\" for OpenAI)")
+    if provider == "openai-compatible" and not base:
+        raise AIConfigError("provider openai-compatible needs [ai] base_url (e.g. http://localhost:11434/v1)")
+    if assist not in ASSIST:
+        raise AIConfigError(f"assist = {assist!r}: use auto, off or full")
+    ref = f"{name}:{mref}" if name else mref
+    return {"provider": provider, "preset": preset, "base_url": base.rstrip("/") if base else "", "key_env": key_env,
+            "model": mref, "ref": ref, "name": name or (preset or provider), "local": is_local(base),
+            "assist": assist, "feedback_retry": bool(ai["feedback_retry"]), "detect": bool(ai["detect"])}
+
+
+def key_for(ep, explicit=None, environ=None):
+    """The key for an endpoint, from the environment only. Anthropic: explicit, the named variable, then
+    ANTHROPIC_API_KEY (as datasheet.require_key always did). A local endpoint needs none (NO_KEY). Otherwise None."""
+    env = os.environ if environ is None else environ
+    if explicit:
+        return explicit
+    k = env.get(ep["key_env"]) if ep.get("key_env") else None
+    if ep["provider"] == "anthropic":
+        return k or env.get(ANTHROPIC_KEY)
+    if k:
+        return k
+    return NO_KEY if ep["local"] or not ep.get("key_env") else None   # no key named: the server takes none
+
+
+def needs_key_message(ep):
+    if ep["provider"] == "anthropic":
+        return (f"{ep['key_env']} is not set: add your Claude API key on the setup page (`ecadlib setup`) or with "
+                f"`ecadlib keys set {ep['key_env']}`")
+    name = ep['key_env'] or '[ai] api_key_env'
+    return (f"{name} is not set: add the key for {ep['base_url']} on the setup page (`ecadlib setup`) or with "
+            f"`ecadlib keys set {name}` (or point [ai] base_url at a local server, which needs none)")
+
+
+# ---------------------------------------------------------------- model registry (prices / profiles of models in use)
+_REG = {}
+
+
+def register(ref, ep, prof):
+    _REG[ref] = {"endpoint": ep, "profile": prof}
+
+
+def registered(ref):
+    return _REG.get(ref)
+
+
+def price(ref):
+    """(input, output) $ per MTok for a model in use, or None when unknown. Claude: datasheet.PRICES. A local
+    endpoint: (0, 0). Others: what the profile says (rules override, or detected from OpenRouter's /models)."""
+    from .. import datasheet as D
+    if ref in D.PRICES:
+        return D.PRICES[ref]
+    r = _REG.get(ref)
+    if not r:
+        return None
+    if r["endpoint"]["local"]:
+        return (0.0, 0.0)
+    p = r["profile"]
+    if p.get("price_in") is not None and p.get("price_out") is not None:
+        return (float(p["price_in"]), float(p["price_out"]))
+    return None
+
+
+def is_anthropic(ref, rules=None):
+    r = _REG.get(ref)
+    if r:
+        return r["endpoint"]["provider"] == "anthropic"
+    try:
+        return endpoint(rules, model=ref)["provider"] == "anthropic"
+    except AIConfigError:
+        return False
+
+
+# ---------------------------------------------------------------- rules validation (called from rules.validate)
+def validate(where, raw_ai, sections, err):
+    """[ai], [ai.profiles.*], [ai.endpoints.*] and the provider keys of [datasheet] / [agent.proof]."""
+    from . import profiles as PR
+    ai = raw_ai or {}
+    if not isinstance(ai, dict):
+        err(where, "[ai]", "must be a table")
+    for k, v in ai.items():
+        if k not in DEFAULTS:
+            err(where, f"ai.{k}", f"is not a known key; known in [ai]: {', '.join(DEFAULTS)}")
+        if k == "temperature":
+            from .sampling import check
+            if check(v):
+                err(where, "ai.temperature", check(v))
+            continue
+        d = DEFAULTS[k]
+        if isinstance(d, bool):
+            if not isinstance(v, bool):
+                err(where, f"ai.{k}", "must be true or false")
+        elif isinstance(d, dict):
+            if not isinstance(v, dict) or not all(isinstance(x, dict) for x in v.values()):
+                err(where, f"ai.{k}", f"must be tables: [ai.{k}.\"name\"] key = value")
+        elif not isinstance(v, str):
+            err(where, f"ai.{k}", "must be text")
+    for label, d in [("ai", ai)] + list(sections):
+        if not isinstance(d, dict):
+            continue
+        if d.get("provider"):
+            try:
+                _norm_provider(d["provider"])
+            except AIConfigError as e:
+                err(where, f"{label}.provider", f"= {d['provider']!r}: {e}")
+        if d.get("assist") and d["assist"] not in ASSIST:
+            err(where, f"{label}.assist", f"= {d['assist']!r}: must be auto (by the model's tier), off or full")
+        if d.get("base_url") and not re.fullmatch(r"https?://[^\s]+", str(d["base_url"])):
+            err(where, f"{label}.base_url", "must be an http(s):// URL such as http://localhost:11434/v1")
+        if d.get("base_url") and str(d["base_url"]).startswith("http://") and not is_local(d["base_url"]):
+            err(where, f"{label}.base_url", "plain http:// is only allowed for a server on this machine or your own "
+                                            "network (the key would travel unencrypted); use https://")
+        if d.get("api_key_env") and not ENV_RE.fullmatch(str(d["api_key_env"])):
+            err(where, f"{label}.api_key_env", "must be the NAME of an environment variable (never the key itself)")
+        if d.get("model") and not MODEL_RE.fullmatch(str(d["model"])):
+            err(where, f"{label}.model", f"= {d['model']!r}: must be a model id such as claude-opus-5-5 or qwen2.5:7b")
+    for n, ep in (ai.get("endpoints") or {}).items():
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]*", n):
+            err(where, f"ai.endpoints.{n}", "endpoint names are letters, digits, _ and - (used as name:model in a ladder)")
+        for k, v in ep.items():
+            if k not in ENDPOINT_KEYS:
+                err(where, f"ai.endpoints.{n}.{k}", f"is not a known key; known: {', '.join(ENDPOINT_KEYS)}")
+            if not isinstance(v, str):
+                err(where, f"ai.endpoints.{n}.{k}", "must be text")
+        validate(where, None, [(f"ai.endpoints.{n}", ep)], err) if ep else None
+        try:
+            p, preset = _norm_provider(ep.get("provider") or "openai-compatible")
+        except AIConfigError:
+            continue
+        if p == "openai-compatible" and not ep.get("base_url") and not preset:
+            err(where, f"ai.endpoints.{n}.base_url", "is needed for an openai-compatible endpoint without a preset")
+    for m, prof in (ai.get("profiles") or {}).items():
+        for k, v in prof.items():
+            msg = PR.check_field(k, v)
+            if msg:
+                err(where, f"ai.profiles.{m}.{k}", msg)

ecadlib/llm/cli.py

@@ -0,0 +1,70 @@
+"""`ecadlib ai`: which model, provider and guide rails the AI features use.
+
+    ecadlib ai show [--model M] [--section datasheet|proof] [--detect] [--rules FILE] [--json]
+    ecadlib ai rails                      every rail: layer (support / capability / guidance) and what it does
+
+show prints the endpoint (provider, base_url, key variable: set or not, never the value), the capability profile
+and where it came from, and the rails a read would run, by layer. --detect asks an openai-compatible server about
+the model (GET /models, Ollama /api/show); without it nothing is sent anywhere."""
+import argparse, json, os, sys
+
+from . import AIConfigError, endpoint, key_for, NO_KEY, profiles as PR, rails as R
+
+
+def show(rules, model=None, section="datasheet", detect=False):
+    ep = endpoint(rules, section, model)
+    if detect and ep["provider"] == "openai-compatible":
+        prof = PR.resolve(ep, rules, key_for(ep))
+    else:
+        prof = PR.profile(ep["model"], ep["provider"], rules)
+    plan = R.plan(prof, ep["assist"], ep["feedback_retry"])
+    k = key_for(ep)
+    key = "none needed" if k == NO_KEY else (f"{ep['key_env'] or 'ANTHROPIC_API_KEY'} set" if k else f"{ep['key_env']} NOT set")
+    return {"endpoint": {**ep, "key": key}, "profile": prof, "plan": plan, "layers": R.layers(plan)}
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="ecadlib ai", description="the model, provider and guide rails the AI features use",
+                                 epilog="examples:\n  ecadlib ai show\n  ecadlib ai show --model qwen2.5:7b --detect\n"
+                                        "  ecadlib ai rails", formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("show", help="endpoint, profile and rails for the configured (or a given) model")
+    s.add_argument("--model", help="a model id (or endpoint:model); default: [ai] / [datasheet] model")
+    s.add_argument("--section", choices=["datasheet", "proof"], default="datasheet")
+    s.add_argument("--detect", action="store_true", help="ask an openai-compatible server what the model can do")
+    s.add_argument("--rules", help="rules file (default: ecadlib.toml found from here)")
+    s.add_argument("--json", action="store_true")
+    sub.add_parser("rails", help="list every rail and its layer")
+    a = ap.parse_args(argv)
+    if a.cmd == "rails":
+        for layer in ("support", "capability", "guidance"):
+            print(f"{layer}:")
+            for k, (lv, what) in R.RAILS.items():
+                if lv == layer:
+                    tiers = [t for t, rs in R.TIER_RAILS.items() if k in rs]
+                    print(f"  {k:<17} {what}" + (f"  [tiers: {', '.join(tiers)}]" if tiers else ""))
+        return 0
+    from .. import rules as RU
+    rules = RU.load(a.rules)
+    try:
+        rep = show(rules, a.model, a.section, a.detect)
+    except AIConfigError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    if a.json:
+        print(json.dumps(rep, indent=2, default=str))
+        return 0
+    ep, p = rep["endpoint"], rep["profile"]
+    print(f"model     {ep['model']}  via {ep['name']} ({'Anthropic API' if ep['provider'] == 'anthropic' else ep['base_url']})")
+    print(f"key       {ep['key']}")
+    print(f"profile   {PR.describe(p)}")
+    if p.get("detect"):
+        print(f"detected  {p['detect']}")
+    print(f"assist    {ep['assist']} -> {rep['plan']['tier']} tier")
+    for layer, names in rep["layers"].items():
+        print(f"{layer:<11}{', '.join(names) or '-'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ecadlib/llm/openai_compat.py

@@ -0,0 +1,214 @@
+"""An OpenAI-compatible /v1/chat/completions endpoint behind the same interface as datasheet.Client.
+
+messages(body, headers) takes our Messages-API-shaped request and returns a Messages-API-shaped answer, so the
+datasheet reader, visual check, cache and cost ledger need no second code path:
+
+  request   system blocks -> one system message; text -> text parts; image (base64) -> image_url data URL; a PDF
+            document -> a file part (only when the profile says the endpoint reads PDFs; otherwise the rails turn it
+            into page text first: ecadlib.llm.rails); assistant turns (a feedback retry) -> their text.
+            output_config.format json_schema -> response_format json_schema (strict) when the profile has json_schema,
+            else json_object; effort, cache_control, fallbacks and other Anthropic-only fields are dropped.
+  answer    choices[0].message.content -> one text block; finish_reason stop/length/content_filter -> stop_reason
+            end_turn/max_tokens/refusal (message.refusal too); usage prompt/completion tokens -> input/output tokens.
+
+Retries 408/409/429/5xx and network errors with backoff (retry-after honoured), like datasheet.Client. A server that
+rejects response_format with HTTP 400 is asked once more without it (json_object, then none), and the answer goes
+through the JSON-repair rail. Every request is logged as one JSON line without the key or the image/PDF bytes.
+The key is only ever sent to the configured base_url."""
+import datetime, json, random, time
+from pathlib import Path
+
+import requests
+
+RETRY_STATUS = {408, 409, 429, 500, 502, 503, 504, 529}
+FINISH = {"stop": "end_turn", "length": "max_tokens", "content_filter": "refusal", "tool_calls": "tool_use"}
+
+
+class OpenAICompatClient:
+    def __init__(self, base_url, key=None, profile=None, retries=4, backoff=2.0, max_wait=60.0, timeout=600, sleep=None,
+                 log_file=None, say=None, post=None, model=None):
+        from .. import datasheet as D
+        self.base, self.key = base_url.rstrip("/"), key
+        self.model = model                                 # the server's model id ('qwen2.5:7b' of ref 'local:qwen2.5:7b')
+        self.profile = dict(profile or {})
+        self.retries, self.backoff, self.max_wait, self.timeout = retries, backoff, max_wait, timeout
+        self.sleep = sleep or time.sleep
+        self.log_file, self.say = log_file or D._LOG["file"], say or D._LOG["say"]
+        self._post = post
+        self.format_fallback = None                        # set when the server rejected json_schema once
+        self.sampling = {}                                 # temperature / seed for every request (llm.sampling)
+
+    # --- translation
+    def to_chat(self, body):
+        from ..datasheet import DatasheetError
+        msgs = []
+        sys_txt = "\n\n".join(b.get("text", "") for b in body.get("system") or [] if isinstance(b, dict)) \
+            if isinstance(body.get("system"), list) else (body.get("system") or "")
+        if sys_txt:
+            msgs.append({"role": "system", "content": sys_txt})
+        for m in body.get("messages") or []:
+            content = m.get("content")
+            if isinstance(content, str):
+                msgs.append({"role": m["role"], "content": content})
+                continue
+            if m["role"] == "assistant":
+                msgs.append({"role": "assistant", "content": "".join(b.get("text", "") for b in content if b.get("type") == "text")})
+                continue
+            parts = []
+            for b in content:
+                t = b.get("type")
+                if t == "text":
+                    parts.append({"type": "text", "text": b["text"]})
+                elif t == "image":
+                    src = b["source"]
+                    url = src["url"] if src.get("type") == "url" else f"data:{src['media_type']};base64,{src['data']}"
+                    parts.append({"type": "image_url", "image_url": {"url": url}})
+                elif t == "document":
+                    src = b["source"]
+                    if not self.profile.get("pdf"):
+                        raise DatasheetError("this model does not take PDF input and the PDF was not turned into page text "
+                                             "(set [ai.profiles] pdf = true if it does)")
+                    if src.get("type") != "base64":
+                        raise DatasheetError("this endpoint can't fetch a PDF by URL: the datasheet must be downloaded here")
+                    parts.append({"type": "file", "file": {"filename": "datasheet.pdf",
+                                                           "file_data": f"data:application/pdf;base64,{src['data']}"}})
+            msgs.append({"role": m["role"], "content": parts})
+        out = {"model": self.model or body["model"], "messages": msgs}
+        mt = body.get("max_tokens")
+        if mt:
+            out[self.profile.get("max_tokens_param") or "max_tokens"] = mt
+        fmt = ((body.get("output_config") or {}).get("format") or {})
+        mode = self.format_fallback or ("json_schema" if self.profile.get("json_schema") else "json_object")
+        if fmt.get("type") == "json_schema" and mode == "json_schema":
+            out["response_format"] = {"type": "json_schema",
+                                      "json_schema": {"name": "answer", "schema": fmt["schema"], "strict": True}}
+        elif fmt.get("type") == "json_schema" and mode == "json_object":
+            out["response_format"] = {"type": "json_object"}
+        if fmt.get("type") == "json_schema" and mode != "json_schema" and self.profile.get("json_schema"):
+            # the plan relied on a schema response format the server rejected: the schema goes in the prompt instead
+            from .rails import schema_text
+            st = schema_text(fmt["schema"])
+            if msgs and msgs[0]["role"] == "system":
+                if st.strip() not in msgs[0]["content"]:
+                    msgs[0]["content"] += st
+            else:
+                msgs.insert(0, {"role": "system", "content": st.strip()})
+        for k in ("temperature", "seed"):
+            if k in body:
+                out[k] = body[k]
+            elif k in (self.sampling or {}):
+                out[k] = self.sampling[k]
+        return out
+
+    @staticmethod
+    def to_message(resp, model):
+        ch = (resp.get("choices") or [{}])[0]
+        m = ch.get("message") or {}
+        text = m.get("content")
+        if isinstance(text, list):                           # some servers return content parts
+            text = "".join(p.get("text", "") for p in text if isinstance(p, dict))
+        stop = FINISH.get(ch.get("finish_reason"), "end_turn")
+        if m.get("refusal"):
+            stop = "refusal"
+        u = resp.get("usage") or {}
+        cached = ((u.get("prompt_tokens_details") or {}).get("cached_tokens")) or 0
+        return {"id": resp.get("id"), "type": "message", "role": "assistant", "model": resp.get("model") or model,
+                "content": [{"type": "text", "text": text or ""}], "stop_reason": stop,
+                "stop_details": {"type": "refusal", "category": None, "explanation": m.get("refusal")} if stop == "refusal" else None,
+                "usage": {"input_tokens": int(u.get("prompt_tokens") or 0) - int(cached), "cache_read_input_tokens": int(cached),
+                          "output_tokens": int(u.get("completion_tokens") or 0)}}
+
+    # --- HTTP
+    def _log(self, rec):
+        if self.log_file:
+            Path(self.log_file).parent.mkdir(parents=True, exist_ok=True)
+            with open(self.log_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(rec, default=str) + "\n")
+
+    def _summary(self, chat):
+        def s(v):
+            if isinstance(v, dict):
+                return {k: (f"<{len(x)} chars>" if k in ("url", "file_data") and isinstance(x, str) and x.startswith("data:")
+                            else f"<json schema>" if k == "schema" else s(x)) for k, x in v.items()}
+            if isinstance(v, list):
+                return [s(x) for x in v]
+            if isinstance(v, str) and len(v) > 300:
+                return v[:120] + f"... <{len(v)} chars>"
+            return v
+        return s(chat)
+
+    def chat(self, chat):
+        from ..datasheet import APIError
+        url = self.base + "/chat/completions"
+        h = {"content-type": "application/json"}
+        if self.key and self.key != "no-key-needed":
+            h["authorization"] = f"Bearer {self.key}"
+        post = self._post or requests.post
+        for attempt in range(self.retries + 1):
+            t0 = time.time()
+            rec = {"t": datetime.datetime.now().isoformat(timespec="seconds"), "method": "POST", "url": url,
+                   "attempt": attempt + 1, "body": self._summary(chat)}
+            retry_after = None
+            try:
+                from ..term import waiting
+                with waiting(f"the model at {self.base} (model call)"):
+                    r = post(url, headers=h, json=chat, timeout=self.timeout)
+            except requests.RequestException as e:
+                err = APIError(f"{self.base}: request failed: {type(e).__name__}: {str(e)[:200]}", retryable=True)
+                rec.update(error=str(err), ms=int((time.time() - t0) * 1000))
+            else:
+                try:
+                    payload = r.json()
+                except ValueError:
+                    payload = None
+                rec.update(status=r.status_code, ms=int((time.time() - t0) * 1000))
+                if r.status_code == 200 and isinstance(payload, dict) and "choices" in payload:
+                    rec["usage"] = payload.get("usage")
+                    self._log(rec)
+                    return payload
+                e = (payload or {}).get("error") if isinstance(payload, dict) else None
+                emsg = (e.get("message") if isinstance(e, dict) else e) or (getattr(r, "text", "") or "")[:200]
+                hint = {401: " (the key was rejected: check it and the variable it is read from)",
+                        404: " (unknown model or endpoint: check [ai] model and base_url)",
+                        429: " (rate limited)"}.get(r.status_code, "")
+                err = APIError(f"{self.base}: HTTP {r.status_code}: {str(emsg)[:300]}{hint}", r.status_code,
+                               (e or {}).get("type") if isinstance(e, dict) else None, r.status_code in RETRY_STATUS)
+                rec["error"] = str(emsg)[:300]
+                retry_after = (getattr(r, "headers", None) or {}).get("retry-after")
+            self._log(rec)
+            if not err.retryable or attempt == self.retries:
+                raise err
+            try:
+                wait = float(retry_after) if retry_after is not None else None
+            except ValueError:
+                wait = None
+            wait = min(self.max_wait * 5, wait) if wait is not None else min(self.max_wait, self.backoff * 2 ** attempt + random.uniform(0, 1))
+            if self.say:
+                self.say(f"  model API: {err.args[0][:120]}; retry {attempt + 1}/{self.retries} in {wait:.0f}s")
+            self.sleep(wait)
+
+    def messages(self, body, headers=None):
+        """Messages-shaped body -> Messages-shaped answer (see the module docstring)."""
+        from ..datasheet import APIError
+        chat = self.to_chat(body)
+        try:
+            resp = self.chat(chat)
+        except APIError as e:
+            if e.status == 400 and "response_format" in chat and self.format_fallback != "none":
+                # the server does not take this response format: ask once more with a looser one (the rails repair JSON)
+                self.format_fallback = "json_object" if chat["response_format"]["type"] == "json_schema" else "none"
+                return self.messages(body, headers)
+            raise
+        msg = self.to_message(resp, body["model"])
+        if self.format_fallback and self.profile.get("json_schema") and msg["stop_reason"] == "end_turn":
+            from .rails import extract_json               # no schema-constrained output: unwrap a fenced / wrapped object
+            try:
+                val, fixes = extract_json(msg["content"][0]["text"])
+            except ValueError:
+                val, fixes = None, []
+            if fixes and isinstance(val, dict):
+                msg["content"] = [{"type": "text", "text": json.dumps(val)}]
+        return msg
+
+    def count_tokens(self, body):
+        raise NotImplementedError("count_tokens is an Anthropic endpoint")