strata-agent-memory 0.2.7__tar.gz → 0.2.9__tar.gz

{strata_agent_memory-0.2.7/strata_agent_memory.egg-info → strata_agent_memory-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strata-agent-memory
-Version: 0.2.7
+Version: 0.2.9
 Summary: Portable, auditable, cross-vendor memory for LLM agents: evidence-bound claims, trust tiers, and compiled context views.
 Author: Strata Intelligence
 License-Expression: Apache-2.0
@@ -20,6 +20,9 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: sign
 Requires-Dist: cryptography>=42; extra == "sign"
+Provides-Extra: retrieval
+Requires-Dist: sqlite-vec>=0.1.9; extra == "retrieval"
+Requires-Dist: fastembed>=0.8; extra == "retrieval"
 Dynamic: license-file
 
 # agent-memory

{strata_agent_memory-0.2.7 → strata_agent_memory-0.2.9}/agent_memory/__init__.py

@@ -9,4 +9,4 @@ see, what did it claim, and can the proof be re-run.
 The core is dependency-free (Python 3.10+ standard library only).
 """
 
-__version__ = "0.2.7"
+__version__ = "0.2.9"

{strata_agent_memory-0.2.7 → strata_agent_memory-0.2.9}/agent_memory/cli.py

@@ -987,6 +987,39 @@ def cmd_memorize(args) -> int:
     return 0
 
 
+def cmd_retrieval(args) -> int:
+    """The retrieval plugin's two steps outside compile (ctr_9e166c2f291b829b): fetch-model,
+    the one that opens a socket, and index, which embeds the records (compile embeds only
+    the task, so its cost never grows with the ledger)."""
+    from . import retrieval as retrieval_mod
+    try:
+        if args.action == "fetch-model":
+            model = args.model
+            if model is None:
+                try:
+                    cfg = retrieval_mod.settings(Ledger.open().config)
+                except FileNotFoundError:
+                    cfg = None  # no ledger here: the default model
+                embed = (cfg or {}).get("embed") or {}
+                if embed.get("backend") == "endpoint":
+                    print(f"retrieval fetch-model: config.retrieval.embed names the endpoint {embed['endpoint']}, "
+                          f"which serves its model: there is nothing to fetch", file=sys.stderr)
+                    return 2
+                model = embed.get("model", retrieval_mod.DEFAULT_MODEL)
+            _print(retrieval_mod.fetch_model(model))
+            return 0
+        ledger = Ledger.open()
+        cfg = retrieval_mod.settings(ledger.config)
+        if cfg is None:
+            print("config.retrieval names no plugin: there is no index to build", file=sys.stderr)
+            return 2
+        _print(retrieval_mod.index(ledger, cfg))
+        return 0
+    except retrieval_mod.RetrievalError as exc:
+        print(f"retrieval {args.action}: {exc}", file=sys.stderr)
+        return 1
+
+
 def cmd_export(args) -> int:
     ledger = Ledger.open()
     reader = _author(args, ledger)  # another user's private receipts are not ours to export
@@ -1073,7 +1106,7 @@ def cmd_serve(args) -> int:
 
 # the local ledger is the whole of what these do; there is nothing to send
 LOCAL_ONLY = ("init", "trust", "untrust", "fsck", "redact", "keygen", "roster", "serve",
-              "mcp", "compact", "memorize")
+              "mcp", "compact", "memorize", "retrieval")
 # answered over --remote, --instance or $AGENT_MEMORY_REMOTE, and never because a checkout's
 # committed config names a replica: the replica's own clone carries that file and still
 # re-checks locally, and so does the nightly CI lane in a checkout that names one
@@ -2527,6 +2560,19 @@ def build_parser() -> argparse.ArgumentParser:
     _add_identity(s)
     s.set_defaults(fn=cmd_memorize)
 
+    s = sub.add_parser("retrieval", help="the reader-side retrieval plugin's steps outside compile "
+                                         "(config.retrieval, docs/PROTOCOL.md section 6)")
+    rs = s.add_subparsers(dest="action", required=True)
+    r = rs.add_parser("fetch-model", help="download the embedding model's weights into the cache: the one "
+                                          "step that opens a socket; compile loads them offline")
+    r.add_argument("--model", help="one of the models the plugin knows (default: config.retrieval.embed's "
+                                   "model, else nomic-ai/nomic-embed-text-v1.5-Q)")
+    rs.add_parser("index", help="bring this ledger's retrieval index up to the ledger and, with "
+                                "config.retrieval.restate, restate every record without a restatement, and "
+                                "with config.retrieval.embed, embed every record without a vector: compile "
+                                "does neither, so run this after records arrive")
+    s.set_defaults(fn=cmd_retrieval)
+
     s = sub.add_parser("export", help="export the ledger in a standard format")
     s.add_argument("--format", choices=list(export_mod.FORMATS), default="prov-json",
                    help="prov-json (W3C PROV for auditors), in-toto (one unsigned Statement per receipt), "

{strata_agent_memory-0.2.7 → strata_agent_memory-0.2.9}/agent_memory/compiler.py

@@ -14,6 +14,7 @@ Roles and modes follow the fork/isolate rule:
 from __future__ import annotations
 
 import re
+import sys
 from dataclasses import dataclass, field
 from datetime import timedelta
 from typing import Callable, Dict, Iterable, List, Optional, Tuple
@@ -142,6 +143,9 @@ class Compiled:
     pinned_cap: Optional[int] = None
     pinned_cut: Dict[str, int] = field(default_factory=dict)
     pinned_full: Dict[str, int] = field(default_factory=dict)
+    # the retrieval plugin that took part (ctr_9e166c2f291b829b): {plugin, share, ids}, and
+    # error when it could not run; None when config.retrieval names none
+    retrieval: Optional[Dict] = None
 
     def included_ids(self) -> List[str]:
         return [i.id for items in self.sections.values() for i in items]
@@ -590,6 +594,10 @@ def compile_context(
         else:
             out.sections["working"].append(item)
 
+    # the retrieval plugin (ctr_9e166c2f291b829b): the ids it finds for the task, of which
+    # the reader sees only what this compile's own policy filter let through (candidates)
+    retrieval_cfg, retrieved = _retrieval(ledger, task, {item.id: item for item, _ in candidates}, out, assessment)
+
     seen_dnr = set()
     for it in do_not_retry:
         key = (it.id, it.statement)
@@ -619,35 +627,72 @@ def compile_context(
     # costed provisionally here and the difference is charged once it is known
     provisional = _obligations(role, mode, round_no, bool(out.sections["cross_check"]), bool(contract_id), lens)
     overhead = overhead_tokens(out, provisional)
-    used = overhead
-    kept: Dict[str, List[Item]] = {name: [] for name in SECTION_ORDER}
-    remaining_by_section = {name: [] for name in SECTION_ORDER}
-    # pass 1: each section up to its share; pass 2: fill leftovers in priority order
-    for name in SECTION_ORDER:
-        cap = int(budget * SECTION_SHARE[name])
-        # half of the constraints section is kept for its human-filed items, which arrive
-        # in standing order, so the freshly filed ones compete for the other half only
-        reserved = int(cap * CONSTRAINT_HUMAN_RESERVE) if name == "constraints" else 0
-        section_used = unreserved_used = 0
-        for item in out.sections[name]:
-            cost = cost_of(item)
-            reserve_eligible = bool(reserved) and item.is_human
-            fits_share = reserve_eligible or unreserved_used + cost <= cap - reserved
-            if section_used + cost <= cap and fits_share and used + cost <= budget:
-                kept[name].append(item)
-                section_used += cost
-                unreserved_used += 0 if reserve_eligible else cost
-                used += cost
-            else:
-                remaining_by_section[name].append(item)
-    for name in SECTION_ORDER:
-        for item in remaining_by_section[name]:
-            cost = cost_of(item)
-            if used + cost <= budget:
-                kept[name].append(item)
-                used += cost
-            else:
-                out.excluded.append((item.id, "budget"))
+    def allocate(reserve: int, found: List[Item], fixed: Optional[List[Item]] = None):
+        """(kept, used, left out for the budget): pass one fills each section up to its
+        share, the retrieval plugin's ``found`` fill its section up to ``reserve``, and pass
+        two fills leftovers in priority order. ``fixed`` is the constraints section as
+        compile alone keeps it: the plugin's share is never taken from what always applies
+        (the review of ctr_9e166c2f291b829b)."""
+        used = overhead
+        kept: Dict[str, List[Item]] = {name: [] for name in SECTION_ORDER}
+        remaining_by_section: Dict[str, List[Item]] = {name: [] for name in SECTION_ORDER}
+        # pass 1: each section up to its share; pass 2: fill leftovers in priority order
+        for name in SECTION_ORDER:
+            if name == "constraints" and fixed is not None:
+                kept[name] = list(fixed)
+                used += sum(cost_of(item) for item in fixed)
+                held = {id(item) for item in fixed}
+                remaining_by_section[name] = [item for item in out.sections[name] if id(item) not in held]
+                continue
+            cap = int(budget * SECTION_SHARE[name])
+            # half of the constraints section is kept for its human-filed items, which arrive
+            # in standing order, so the freshly filed ones compete for the other half only
+            reserved = int(cap * CONSTRAINT_HUMAN_RESERVE) if name == "constraints" else 0
+            section_used = unreserved_used = 0
+            for item in out.sections[name]:
+                cost = cost_of(item)
+                reserve_eligible = bool(reserved) and item.is_human
+                fits_share = reserve_eligible or unreserved_used + cost <= cap - reserved
+                if section_used + cost <= cap and fits_share and used + cost <= budget - reserve:
+                    kept[name].append(item)
+                    section_used += cost
+                    unreserved_used += 0 if reserve_eligible else cost
+                    used += cost
+                else:
+                    remaining_by_section[name].append(item)
+        taken = {item.id for items in kept.values() for item in items}
+        if found:
+            # what the plugin found and pass 1 did not already keep, in the plugin's order,
+            # up to its share: a record shown once, in the section that placed it first
+            kept["retrieved"], spent = [], 0
+            for item in found:
+                cost = cost_of(item)
+                if item.id not in taken and spent + cost <= reserve and used + cost <= budget:
+                    kept["retrieved"].append(item)
+                    taken.add(item.id)
+                    spent += cost
+                    used += cost
+        left_out: List[str] = []
+        for name in SECTION_ORDER:
+            for item in remaining_by_section[name]:
+                if item.id in taken:
+                    continue  # the retrieved section placed it
+                cost = cost_of(item)
+                if used + cost <= budget:
+                    kept[name].append(item)
+                    used += cost
+                else:
+                    left_out.append(item.id)
+        return kept, used, left_out
+
+    # compile alone; and when the retrieval plugin found something, again with its share
+    # held back from every section but the constraints, which keep what compile alone
+    # gives them. A plugin that finds nothing changes nothing (BENCHMARK-PLAN 1.2)
+    kept, used, left_out = allocate(0, [])
+    if retrieved:
+        kept, used, left_out = allocate(int(budget * retrieval_cfg["share"]), retrieved, fixed=kept["constraints"])
+        out.retrieval["ids"] = [item.id for item in kept["retrieved"]]
+    out.excluded += [(rid, "budget") for rid in left_out]
     out.sections = kept
     out.used_tokens = used
 
@@ -668,6 +713,55 @@ def compile_context(
     return out
 
 
+def _retrieval(ledger, task: Optional[str], eligible: Dict[str, "Item"], out: "Compiled",
+               assessment: Optional[dict] = None):
+    """(the plugin's settings or None, the eligible items it found, best first), and
+    ``out.retrieval`` set to what the receipt records. A plugin that cannot run leaves the
+    view as compile alone makes it, and says so: on the receipt, and in one stderr line."""
+    from . import retrieval as retrieval_mod  # local: retrieval imports this module
+    try:
+        cfg = retrieval_mod.settings(ledger.config)
+    except retrieval_mod.RetrievalError as exc:
+        out.retrieval = {"plugin": retrieval_mod.configured_name(ledger.config), "share": None, "ids": [],
+                         "error": str(exc)}
+        print(f"agent-memory: the retrieval plugin did not run ({exc}); compiled without it", file=sys.stderr)
+        return None, []
+    if cfg is None:
+        return None, []
+    out.retrieval = {"plugin": cfg["plugin"], "share": cfg["share"], "ids": []}
+    for part in ("embed", "analyse", "restate"):  # the configuration a view came from, whether it ran or not
+        if part in cfg:
+            out.retrieval[part] = dict(cfg[part])
+    if not task:
+        return cfg, []  # nothing to search by: a view with no task is compile's alone
+    report: dict = {}
+
+    def reported():
+        for part in ("analyse", "embed"):  # what answered, what it cost, and the scope it chose
+            if part in report:
+                out.retrieval[part].update(report[part])
+        if "withheld" in report:  # user-scoped records kept off an endpoint, and sent to one
+            out.retrieval["withheld"], out.retrieval["sent_private"] = report["withheld"], report["sent_private"]
+            out.retrieval["pending_for"] = report["pending_for"]  # which part of the index is behind
+        if "error" in report.get("analyse", {}):
+            print(f"agent-memory: the retrieval plugin's query analysis did not run ({report['analyse']['error']}); "
+                  f"searched by the task's own terms", file=sys.stderr)
+    try:
+        # the reader's policy filter goes into the query, so another reader's records never
+        # take this reader's places under the plugin's cuts (an index is never global)
+        found, pending = retrieval_mod.retrieve(ledger, task, cfg, assessment, allowed=eligible, report=report)
+        if pending is not None:  # records BM25 alone could find: this view is not the configured C1's yet
+            out.retrieval["pending"] = pending
+    except retrieval_mod.RetrievalError as exc:
+        reported()  # an analysis call made before the failure still cost what it cost
+        out.retrieval["error"] = str(exc)
+        print(f"agent-memory: the retrieval plugin {cfg['plugin']} did not run ({exc}); compiled without it",
+              file=sys.stderr)
+        return cfg, []
+    reported()
+    return cfg, [eligible[rid] for rid in found if rid in eligible]
+
+
 def compiled_from_json(payload: dict) -> Compiled:
     """Rebuild a Compiled from ``render.render_json``'s payload.
 
@@ -690,6 +784,7 @@ def compiled_from_json(payload: dict) -> Compiled:
         # saying it was cut
         board=[dict(row) for row in payload.get("board") or []],
     )
+    out.retrieval = payload.get("retrieval") if isinstance(payload.get("retrieval"), dict) else None
     display = payload.get("reader_display")
     out.reader_display = display if isinstance(display, str) and display else None
     out.config_notes = [n for n in payload.get("config_notes") or [] if isinstance(n, str)]
@@ -840,6 +935,10 @@ def record_compilation(ledger, compiled: Compiled, rendered: str, render_name: s
         # which reliability numbers the reader was shown, or null when annotation was off
         "reliability": compiled.reliability_meta,
     }
+    if compiled.retrieval is not None:
+        # which configuration produced the view (ctr_9e166c2f291b829b): the plugin, its
+        # share, the ids it added, and why it did not run when it did not
+        body["retrieval"] = compiled.retrieval
     # which repository the view was cut to, and where it was served and asked from: set
     # only when they are, so a plain view's receipt is what it always was
     for key, value in (("repo", compiled.repo), ("served", compiled.served or None),

{strata_agent_memory-0.2.7 → strata_agent_memory-0.2.9}/agent_memory/contracts.py

@@ -765,7 +765,8 @@ def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout:
             detail = (f"exit {body['exit']} (expected {expect_exit})" + (f"; {body.get('summary')}" if body.get("summary") else "")
                       + ("; timed out, and everything it started was stopped" if body.get("timed_out") else ""))
             if sandbox is not None:
-                reason = ev.sandbox_failure(sandbox["image"], body, expect_exit, check["cmd"]) if not ok else None
+                reason = (ev.sandbox_failure(sandbox["image"], body, expect_exit, check["cmd"],
+                                             unproven=ev.image_proof(sandbox, where)) if not ok else None)
                 if reason:
                     outcome, detail = "error", f"{reason}; {detail}"
                 detail = f"sandboxed: podman {sandbox['image']}; {detail}"

strata_agent_memory-0.2.9/agent_memory/endpoints.py

@@ -0,0 +1,258 @@
+"""The endpoint registry's config half (the operator's decision clm_f1fe183b55ed42e5).
+
+The model endpoints this machine's components may call are named once, in
+``config.endpoints``, each for the model it serves in short, and a component names the
+one it uses:
+
+    "endpoints": {
+      "Qwen3.5-122B": {"url": "https://node-1.example/v1", "model": "Intel/Qwen3.5-122B-A10B-int4-AutoRound",
+                       "key_env": "NODE_1_API_KEY", "send_private": true}
+    }
+
+``url`` is an OpenAI-compatible base (``/chat/completions`` and ``/embeddings`` are appended
+to it) and ``model`` the id asked for; what model actually answered is read from each
+response. The key is named, never held: ``key_env`` is an environment variable and
+``key_keychain`` a login-keychain service (the endpoint's name is the item's account), read
+when a call is made and never when the config is checked, so a key is never in a config, an
+argv, a receipt or an error. ``plaintext_key`` lets a key go over ``http://``, as memorize's
+``--llm-insecure`` does. ``send_private`` says the endpoint may receive user-scoped records,
+which no endpoint does by default: it is the endpoint's property (the fleet's own machine,
+yes; a vendor's, no), and each reader of the registry honours it. Over ``http://`` it also
+needs ``plaintext_private``, whatever the key: a key authenticates, and only https hides the
+records in flight; a receipt then says ``plaintext``. ``timeout`` is a call's
+limit in seconds.
+
+The retrieval plugin reads the registry first (ctr_9e166c2f291b829b); the memorizer, the
+assessor and the benchmark runners adopt it in their own stories. ``endpoints`` is an
+untrusted-policy key (ledger.UNTRUSTED_POLICY): a clone that named its own would be choosing
+where this machine sends its records, and which secret goes with them.
+
+The client opens a socket to the endpoint the config names and nowhere else: it takes no
+proxy from the environment (``HTTP_PROXY`` and its kin), and it follows no redirect, since
+urllib would carry the ``Authorization`` header to wherever a proxy or a redirect pointed.
+It reads a reply only up to MAX_REPLY_BYTES.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Dict, List, Mapping, Optional, Tuple
+
+ENTRY_KEYS = ("url", "model", "key_env", "key_keychain", "plaintext_key", "send_private", "plaintext_private",
+              "timeout")
+# fields that would hold a secret itself: refused by name, so a key pasted into the config
+# is an error rather than a key committed beside it
+SECRET_FIELDS = ("key", "api_key", "apikey", "token", "bearer", "password", "secret")
+NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$")
+KEY_ENV = re.compile(r"^[A-Z_][A-Z0-9_]*$")
+DEFAULT_TIMEOUT = 60.0
+MAX_TIMEOUT = 600.0
+MAX_REPLY_BYTES = 16 * 1024 * 1024  # a completion or a batch of embeddings is far smaller
+DETAIL_CHARS = 300                  # of an error reply, quoted in a degraded run's reason
+
+
+class EndpointError(ValueError):
+    """An entry is malformed, or a call to it failed: the sentence says which, never the key."""
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    name: str
+    url: str
+    model: str
+    key_env: Optional[str] = None
+    key_keychain: Optional[str] = None
+    plaintext_key: bool = False
+    send_private: bool = False
+    plaintext_private: bool = False
+    timeout: float = DEFAULT_TIMEOUT
+
+    def key(self, env: Optional[Mapping[str, str]] = None) -> Optional[str]:
+        """The key this endpoint's entry names, read now; None when it names none. A named
+        key that is not there is an error: the config says this endpoint wants one."""
+        if self.key_env:
+            found = (os.environ if env is None else env).get(self.key_env)
+            if not found:
+                raise EndpointError(f"endpoint {self.name!r}: its key_env {self.key_env} is not set")
+            return found
+        if self.key_keychain:
+            from .remote import keychain_token  # local: the keychain is read only for a call
+            found = keychain_token(self.key_keychain, self.name)
+            if not found:
+                raise EndpointError(f"endpoint {self.name!r}: no login-keychain item with service "
+                                    f"{self.key_keychain} and account {self.name}")
+            return found
+        return None
+
+    def describe(self) -> dict:
+        """What a receipt says of the endpoint: never its key, nor where the key is kept; and
+        ``plaintext`` when it is sent user-scoped records over http://."""
+        out = {"endpoint": self.name, "url": self.url, "model": self.model, "send_private": self.send_private}
+        if self.send_private and self.url.startswith("http://"):
+            out["plaintext"] = True
+        return out
+
+
+def check(name: str, entry) -> Endpoint:
+    """The entry ``name`` as an Endpoint, or EndpointError saying what is wrong with it."""
+    if not isinstance(name, str) or not NAME.match(name):
+        raise EndpointError(f"an endpoint's name is letters, digits and _.:- (up to 64), not {name!r}")
+    if not isinstance(entry, dict):
+        raise EndpointError(f"endpoint {name!r} must be an object with url and model")
+    secrets = sorted(set(entry) & set(SECRET_FIELDS))
+    if secrets:
+        raise EndpointError(f"endpoint {name!r}: a key never goes in the config ({', '.join(secrets)}); name "
+                            f"where it is kept with key_env or key_keychain")
+    unknown = sorted(set(entry) - set(ENTRY_KEYS))
+    if unknown:
+        raise EndpointError(f"endpoint {name!r} has keys the registry does not read: {unknown}")
+    url = entry.get("url")
+    parts = urllib.parse.urlsplit(url) if isinstance(url, str) else None
+    if parts is None or parts.scheme not in ("https", "http") or not parts.hostname:
+        raise EndpointError(f"endpoint {name!r}: url must be an http(s) URL, not {url!r}")
+    if parts.username is not None or parts.password is not None or parts.query or parts.fragment:
+        # a receipt names the url, so nothing that could be a secret may ride in it
+        raise EndpointError(f"endpoint {name!r}: url must carry no credentials, query or fragment")
+    model = entry.get("model")
+    if not isinstance(model, str) or not model.strip():
+        raise EndpointError(f"endpoint {name!r}: model is required (the id to ask for)")
+    key_env, key_keychain = entry.get("key_env"), entry.get("key_keychain")
+    if key_env is not None and key_keychain is not None:
+        raise EndpointError(f"endpoint {name!r}: name one key, key_env or key_keychain")
+    if key_env is not None and not (isinstance(key_env, str) and KEY_ENV.match(key_env)):
+        raise EndpointError(f"endpoint {name!r}: key_env must be an environment variable's name")
+    if key_keychain is not None and not (isinstance(key_keychain, str) and key_keychain.strip()):
+        raise EndpointError(f"endpoint {name!r}: key_keychain must be a keychain service's name")
+    flags = {}
+    for flag in ("plaintext_key", "send_private", "plaintext_private"):
+        value = entry.get(flag, False)
+        if not isinstance(value, bool):
+            raise EndpointError(f"endpoint {name!r}: {flag} must be true or false")
+        flags[flag] = value
+    if (key_env or key_keychain) and parts.scheme == "http" and not flags["plaintext_key"]:
+        raise EndpointError(f"endpoint {name!r}: refusing to send its key to a plaintext endpoint ({url}); use "
+                            f"https, or set plaintext_key if you accept the risk")
+    if flags["send_private"] and parts.scheme == "http" and not flags["plaintext_private"]:
+        # whatever its key: a key authenticates, and only https hides the records in flight
+        raise EndpointError(f"endpoint {name!r}: refusing to send user-scoped records to a plaintext endpoint "
+                            f"({url}); use https, or set plaintext_private if you accept the risk")
+    timeout = entry.get("timeout", DEFAULT_TIMEOUT)
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= MAX_TIMEOUT:
+        raise EndpointError(f"endpoint {name!r}: timeout must be seconds in (0, {MAX_TIMEOUT:g}]")
+    return Endpoint(name=name, url=url.rstrip("/"), model=model, key_env=key_env, key_keychain=key_keychain,
+                    timeout=float(timeout), **flags)
+
+
+def endpoint(config: Optional[dict], name) -> Endpoint:
+    """The endpoint ``name`` from ``config.endpoints``, or EndpointError."""
+    table = (config or {}).get("endpoints")
+    if table is None:
+        table = {}
+    if not isinstance(table, dict):
+        raise EndpointError("config.endpoints must be an object of endpoints by name")
+    if not isinstance(name, str) or name not in table:
+        raise EndpointError(f"no endpoint named {name!r} in config.endpoints")
+    return check(name, table[name])
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None  # the 3xx is answered as an error: the key goes nowhere but the named url
+
+
+def _opener() -> urllib.request.OpenerDirector:
+    """No proxy, which urllib would otherwise take from HTTP_PROXY and its kin (an http one
+    reads the Authorization header), and no redirect: a socket to the named url and nowhere
+    else. Built for each call, as cheap as the call is not."""
+    return urllib.request.build_opener(urllib.request.ProxyHandler({}), _NoRedirect)
+
+
+def _scrub(text: str, key: Optional[str]) -> str:
+    return text.replace(key, "<key>") if key else text
+
+
+def call(ep: Endpoint, path: str, payload: dict, env: Optional[Mapping[str, str]] = None) -> dict:
+    """POST ``payload`` to the endpoint's ``path`` and return the reply's JSON object."""
+    key = ep.key(env)
+    headers = {"Content-Type": "application/json"}
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+    req = urllib.request.Request(ep.url + path, data=json.dumps(payload).encode("utf-8"), headers=headers,
+                                 method="POST")
+    try:
+        with _opener().open(req, timeout=ep.timeout) as resp:
+            raw = resp.read(MAX_REPLY_BYTES + 1)
+    except urllib.error.HTTPError as exc:
+        try:
+            detail = exc.read(DETAIL_CHARS * 4).decode("utf-8", "replace")[:DETAIL_CHARS]
+        except OSError:
+            detail = ""
+        raise EndpointError(f"endpoint {ep.name!r} answered {exc.code}: {_scrub(detail, key)}") from None
+    except (urllib.error.URLError, OSError, ValueError) as exc:  # refused, unreachable, timed out
+        raise EndpointError(f"endpoint {ep.name!r} could not be reached ({type(exc).__name__}: "
+                            f"{_scrub(str(exc), key)[:DETAIL_CHARS]})") from None
+    if len(raw) > MAX_REPLY_BYTES:
+        raise EndpointError(f"endpoint {ep.name!r} replied with more than {MAX_REPLY_BYTES} bytes")
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError):
+        raise EndpointError(f"endpoint {ep.name!r} replied with something other than JSON") from None
+    if not isinstance(body, dict):
+        raise EndpointError(f"endpoint {ep.name!r} replied with JSON that is not an object")
+    return body
+
+
+def usage(body: dict) -> dict:
+    """The reply's token counts, as numbers only: what the read cost is counted from."""
+    found = body.get("usage") if isinstance(body.get("usage"), dict) else {}
+    return {k: v for k, v in found.items() if k in ("prompt_tokens", "completion_tokens", "total_tokens")
+            and isinstance(v, int) and not isinstance(v, bool) and v >= 0}
+
+
+def served(body: dict) -> Optional[str]:
+    model = body.get("model")
+    return model[:200] if isinstance(model, str) and model else None
+
+
+def chat(ep: Endpoint, messages: List[dict], max_tokens: int, env: Optional[Mapping[str, str]] = None
+         ) -> Tuple[str, Optional[str], dict]:
+    """(the reply's text, the served model id, its usage) for one chat completion."""
+    body = call(ep, "/chat/completions", {"model": ep.model, "messages": messages, "temperature": 0.0,
+                                          "max_tokens": max_tokens, "stream": False}, env)
+    try:
+        text = body["choices"][0]["message"]["content"]
+    except (KeyError, IndexError, TypeError):
+        text = None
+    if not isinstance(text, str):
+        raise EndpointError(f"endpoint {ep.name!r} replied with no message content")
+    return text, served(body), usage(body)
+
+
+def embeddings(ep: Endpoint, texts: List[str], env: Optional[Mapping[str, str]] = None
+               ) -> Tuple[List[List[float]], Optional[str], dict]:
+    """(one vector per text, in order; the served model id; the usage) from ``/embeddings``."""
+    body = call(ep, "/embeddings", {"model": ep.model, "input": list(texts)}, env)
+    data = body.get("data")
+    if not isinstance(data, list) or len(data) != len(texts):
+        raise EndpointError(f"endpoint {ep.name!r} replied with {len(data) if isinstance(data, list) else 'no'} "
+                            f"embeddings for {len(texts)} texts")
+    by_index: Dict[int, List[float]] = {}
+    for position, item in enumerate(data):
+        index = item.get("index", position) if isinstance(item, dict) else None
+        vector = item.get("embedding") if isinstance(item, dict) else None
+        if (not isinstance(index, int) or isinstance(index, bool) or not 0 <= index < len(texts)
+                or index in by_index or not isinstance(vector, list) or not vector
+                or not all(isinstance(x, (int, float)) and not isinstance(x, bool) and math.isfinite(x)
+                           for x in vector)):
+            raise EndpointError(f"endpoint {ep.name!r} replied with a malformed embedding")
+        by_index[index] = [float(x) for x in vector]
+    dims = {len(v) for v in by_index.values()}
+    if len(dims) != 1:
+        raise EndpointError(f"endpoint {ep.name!r} replied with embeddings of different lengths")
+    return [by_index[i] for i in range(len(texts))], served(body), usage(body)