vvz-agent-memory 1.7.46__py3-none-any.whl

vvz_agent_memory/__init__.py

@@ -0,0 +1,12 @@
+"""vvz-agent-memory — the agent-memory CLI of the prompt-factory contract.
+
+Agents of a `file_access: local` project write and read their dialogue messages
+through this tool. It is a wrapper over `ailogger-client`: while the AI Logger is
+reachable every call goes to it; while it is not, messages are kept in
+`.agent-memory/<session_id>/` as `.msg` + `.emb` file pairs and are later moved
+into the logger with their original identity and time by `agent-memory import`.
+
+The package version equals the contract version it serves.
+"""
+
+__version__ = "1.7.46"

vvz_agent_memory/cli.py

@@ -0,0 +1,304 @@
+"""`agent-memory` — the command line.
+
+Every command prints exactly one JSON object on stdout:
+``{"success": true, "store": ..., "data": ...}`` or ``{"success": false, "error": {"code", "message"}}``.
+
+Exit codes: 0 success; 1 the logger refused or failed; 2 usage; 3 file store unavailable;
+4 logger unreachable (and no fallback); 5 not found; 6 configuration invalid;
+7 embedding service unavailable where a vector is required.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+
+from . import __version__, config as cfg
+from .filestore import FileStore, FileStoreUnavailable, project_root
+from .logger import LoggerFailure, LoggerUnreachable
+from .memory import Memory, NotFound, Unavailable
+
+KINDS = ("human", "model", "tool", "system")
+RELATION_KINDS = ("reply", "influence", "tool_result")
+EXIT = {"LOGGER_FAILURE": 1, "USAGE": 2, "FILE_STORE_UNAVAILABLE": 3, "LOGGER_UNREACHABLE": 4,
+        "NOT_FOUND": 5, "CONFIG_INVALID": 6, "EMBEDDING_UNAVAILABLE": 7}
+
+
+def _uuid4(value: str) -> str:
+    try:
+        parsed = uuid.UUID(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"not a UUID: {value!r}") from exc
+    if parsed.version != 4 or str(parsed) != value.lower():
+        raise argparse.ArgumentTypeError(f"not a canonical UUID4: {value!r}")
+    return str(parsed)
+
+
+def _relation(value: str) -> dict[str, str]:
+    kind, _, target = value.partition(":")
+    if kind not in RELATION_KINDS:
+        raise argparse.ArgumentTypeError(f"relation kind must be one of {list(RELATION_KINDS)}: {value!r}")
+    return {"to_message_id": _uuid4(target), "kind": kind}
+
+
+def _attributes(value: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"--attributes is not JSON: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise argparse.ArgumentTypeError("--attributes must be a JSON object")
+    return parsed
+
+
+def _non_negative(value: str) -> int:
+    number = int(value)
+    if number < 0:
+        raise argparse.ArgumentTypeError("must be >= 0")
+    return number
+
+
+def _positive(value: str) -> int:
+    number = int(value)
+    if number <= 0:
+        raise argparse.ArgumentTypeError("must be > 0")
+    return number
+
+
+def _batch(value: str) -> int:
+    number = _positive(value)
+    if number > 1000:
+        raise argparse.ArgumentTypeError("the logger imports at most 1000 messages per call")
+    return number
+
+
+def _bool(value: str) -> bool:
+    if value.lower() in ("true", "yes", "1"):
+        return True
+    if value.lower() in ("false", "no", "0"):
+        return False
+    raise argparse.ArgumentTypeError("expected true or false")
+
+
+def _global_options(parser: argparse.ArgumentParser, suppress: bool) -> None:
+    """The same options before and after the subcommand; the subcommand's copy only overrides when given."""
+
+    def default(value: Any) -> Any:
+        return argparse.SUPPRESS if suppress else value
+
+    parser.add_argument("--config", default=default(None),
+                        help=f"configuration document (default ${cfg.ENV_VAR} or {cfg.DEFAULT_PATH})")
+    parser.add_argument("--root", default=default(None),
+                        help="project root holding .agent-memory/ (default: the git top level of the cwd)")
+    parser.add_argument("--store", choices=("auto", "logger", "file"), default=default("auto"),
+                        help="auto (default): logger, file store only while the logger is unreachable")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-memory",
+        description="Agent dialogue memory: AI Logger, with the .agent-memory/ file store while it is unreachable.",
+    )
+    parser.add_argument("--version", action="version", version=f"agent-memory {__version__}")
+    _global_options(parser, suppress=False)
+    common = argparse.ArgumentParser(add_help=False)
+    _global_options(common, suppress=True)
+
+    class _Sub(argparse._SubParsersAction):  # every subcommand also takes the global options
+        def add_parser(self, name: str, **kwargs: Any) -> argparse.ArgumentParser:
+            kwargs.setdefault("parents", [common])
+            return super().add_parser(name, **kwargs)
+
+    parser.register("action", "parsers", _Sub)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    w = sub.add_parser("write", help="append one message (append_message)")
+    w.add_argument("--session-id", required=True, type=_uuid4)
+    text = w.add_mutually_exclusive_group(required=True)
+    text.add_argument("--text")
+    text.add_argument("--text-file", help="file holding the text; '-' reads stdin")
+    w.add_argument("--sender-kind", required=True, choices=KINDS)
+    w.add_argument("--sender-identity", required=True)
+    w.add_argument("--receiver-kind", required=True, choices=KINDS)
+    w.add_argument("--receiver-identity", required=True)
+    w.add_argument("--reply-to", type=_uuid4, action="append", default=[], metavar="MESSAGE_ID",
+                   help="a reply relation to this message (repeatable)")
+    w.add_argument("--relation", type=_relation, action="append", default=[], metavar="KIND:MESSAGE_ID",
+                   help=f"a relation, kind one of {list(RELATION_KINDS)} (repeatable)")
+    w.add_argument("--attributes", type=_attributes, help="free-form JSON object")
+    w.add_argument("--priority", type=_non_negative)
+    w.add_argument("--corrects", type=_uuid4, metavar="MESSAGE_ID", help="the message this one corrects")
+    w.add_argument("--message-id", type=_uuid4, help="identifier to accept the message under (a retry)")
+
+    r = sub.add_parser("read", help="read one referenced message")
+    r.add_argument("--session-id", required=True, type=_uuid4)
+    r.add_argument("--message-id", required=True, type=_uuid4)
+    r.add_argument("--sequence-number", type=_non_negative)
+
+    p = sub.add_parser("preview", help="messages of one sender, one character of text each")
+    p.add_argument("--session-id", required=True, type=_uuid4)
+    p.add_argument("--sender-identity", required=True)
+    p.add_argument("--page-size", type=_positive, default=100)
+
+    ws = sub.add_parser("working-set", help="recent and closest messages around an anchor")
+    ws.add_argument("--session-id", required=True, type=_uuid4)
+    anchor = ws.add_mutually_exclusive_group(required=True)
+    anchor.add_argument("--anchor-message-id", type=_uuid4)
+    anchor.add_argument("--anchor-text")
+    ws.add_argument("--recency-count", type=_non_negative, default=10)
+    ws.add_argument("--similarity-count", type=_non_negative, default=10)
+
+    rel = sub.add_parser("relations", help="declared relations of a session")
+    rel.add_argument("--session-id", required=True, type=_uuid4)
+
+    e = sub.add_parser("embed", help="compute the missing .emb files of the file store")
+    e.add_argument("--session-id", type=_uuid4, action="append", default=[])
+
+    i = sub.add_parser("import", help="move file-store messages into the logger with their ids and times")
+    i.add_argument("--session-id", type=_uuid4, action="append", default=[],
+                   help="session to import (repeatable; default: every session in the store)")
+    i.add_argument("--batch-size", type=_batch, default=500)
+    i.add_argument("--keep", action="store_true",
+                   help="leave imported files in place (default: move them to .agent-memory/.imported/)")
+
+    c = sub.add_parser("config", help="generate or validate the configuration document")
+    csub = c.add_subparsers(dest="config_command", required=True)
+    g = csub.add_parser("generate", help="write a configuration document; every setting has an argument")
+    g.add_argument("--output", required=True, help="path of the document to write")
+    g.add_argument("--force", action="store_true", help="overwrite an existing document")
+    for side, port in (("logger", 8008), ("embed", 8001)):
+        g.add_argument(f"--{side}-protocol", choices=cfg.PROTOCOLS, default="mtls")
+        g.add_argument(f"--{side}-host", required=True)
+        g.add_argument(f"--{side}-port", type=int, default=port)
+        g.add_argument(f"--{side}-timeout", type=float, default=cfg.DEFAULT_TIMEOUT)
+        g.add_argument(f"--{side}-cert")
+        g.add_argument(f"--{side}-key")
+        g.add_argument(f"--{side}-ca")
+        g.add_argument(f"--{side}-check-hostname", type=_bool)
+        g.add_argument(f"--{side}-token")
+        g.add_argument(f"--{side}-token-header")
+    g.add_argument("--embed-model", default="BAAI/bge-m3", help="must be the logger's embedding model")
+    g.add_argument("--embed-dimension", type=_positive, default=1024)
+    csub.add_parser("validate", help="validate the configuration document", parents=[common])
+    return parser
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    json.dump(payload, sys.stdout, ensure_ascii=False, default=str)
+    sys.stdout.write("\n")
+
+
+def _fail(code: str, message: str, **extra: Any) -> int:
+    _emit({"success": False, "error": {"code": code, "message": message, **extra}})
+    return EXIT[code]
+
+
+def _config_command(args: argparse.Namespace) -> int:
+    if args.config_command == "generate":
+        out = Path(args.output).expanduser().resolve()
+        if out.exists() and not args.force:
+            return _fail("USAGE", f"{out} exists; pass --force to overwrite")
+        document = cfg.generate(args)
+        errors = cfg.validate(document, out.parent)
+        if errors:
+            return _fail("CONFIG_INVALID", "the generated document is invalid; nothing written", errors=errors)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+        _emit({"success": True, "data": {"path": str(out)}})
+        return 0
+    try:
+        loaded = cfg.load(args.config)
+    except cfg.ConfigProblem as exc:
+        return _fail("CONFIG_INVALID", "configuration document is invalid", errors=exc.errors)
+    _emit({"success": True, "data": {"path": str(loaded.path), "errors": []}})
+    return 0
+
+
+def _read_text(args: argparse.Namespace) -> str:
+    if args.text is not None:
+        return args.text
+    if args.text_file == "-":
+        return sys.stdin.read()
+    return Path(args.text_file).read_text(encoding="utf-8")
+
+
+async def _run(args: argparse.Namespace, memory: Memory) -> dict[str, Any]:
+    if args.command == "write":
+        relations = [{"to_message_id": m, "kind": "reply"} for m in args.reply_to] + args.relation
+        text = _read_text(args)
+        if not text:
+            raise ValueError("the text is empty")
+        return await memory.write(
+            session_id=args.session_id, text=text, sender_kind=args.sender_kind,
+            sender_identity=args.sender_identity, receiver_kind=args.receiver_kind,
+            receiver_identity=args.receiver_identity, priority=args.priority, message_id=args.message_id,
+            relations=relations, corrects_message_id=args.corrects, attributes=args.attributes,
+        )
+    if args.command == "read":
+        return await memory.read(session_id=args.session_id, message_id=args.message_id,
+                                 sequence_number=args.sequence_number)
+    if args.command == "preview":
+        return await memory.preview(session_id=args.session_id, sender_identity=args.sender_identity,
+                                    page_size=args.page_size)
+    if args.command == "working-set":
+        return await memory.working_set(
+            session_id=args.session_id, anchor_message_id=args.anchor_message_id, anchor_text=args.anchor_text,
+            recency_count=args.recency_count, similarity_count=args.similarity_count)
+    if args.command == "relations":
+        return await memory.relations(session_id=args.session_id)
+    if args.command == "embed":
+        return await memory.embed_missing(session_ids=args.session_id)
+    if args.command == "import":
+        return await memory.import_sessions(session_ids=args.session_id, batch_size=args.batch_size,
+                                            keep=args.keep)
+    raise AssertionError(args.command)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "config":
+        return _config_command(args)
+    try:
+        loaded = cfg.load(args.config)
+    except cfg.ConfigProblem as exc:
+        return _fail("CONFIG_INVALID", "configuration document is invalid", errors=exc.errors)
+    files: FileStore | None = None
+    problem: str | None = None
+    try:
+        files = FileStore.open(project_root(args.root))
+    except FileStoreUnavailable as exc:
+        problem = str(exc)
+    if args.store == "file" and files is None:
+        return _fail("FILE_STORE_UNAVAILABLE", problem or "file store unavailable")
+    if args.command in ("embed", "import") and files is None:
+        return _fail("FILE_STORE_UNAVAILABLE", problem or "file store unavailable")
+    try:
+        result = asyncio.run(_run(args, Memory(loaded, args.store, files, problem)))
+    except ValueError as exc:
+        return _fail("USAGE", str(exc))
+    except NotFound as exc:
+        return _fail("NOT_FOUND", str(exc))
+    except FileStoreUnavailable as exc:
+        return _fail("FILE_STORE_UNAVAILABLE", str(exc))
+    except LoggerUnreachable as exc:
+        return _fail("LOGGER_UNREACHABLE", str(exc))
+    except Unavailable as exc:
+        return _fail("LOGGER_UNREACHABLE", str(exc), sides=exc.reasons)
+    except LoggerFailure as exc:
+        return _fail("LOGGER_FAILURE", str(exc), logger_code=exc.code)
+    code = 0
+    if args.command == "import" and any(s["failed"] for s in result["data"]["sessions"]):
+        code = EXIT["LOGGER_FAILURE"]
+    if args.command == "embed" and result["data"]["failed"]:
+        code = EXIT["EMBEDDING_UNAVAILABLE"]
+    _emit({"success": code == 0, **result})
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vvz_agent_memory/config.py

@@ -0,0 +1,219 @@
+"""The configuration document of the agent-memory CLI: location, reading, validation, generation.
+
+The document is JSON with exactly three sections:
+
+- ``ailogger_client`` — the published ai-logger client section, read by
+  ``ailogger_client.config`` itself (protocol, server.host/port, client.timeout,
+  client.ssl or ssl cert/key/ca, ssl.check_hostname, auth.token/token_header);
+- ``embedding_client`` — the same sectioned shape for the embedding service;
+- ``embedding_model`` — ``model`` and ``dimension``; they must be the logger's own,
+  otherwise vectors written while the logger is down are not comparable with its own.
+
+Relative certificate paths are resolved against the document's directory.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+ENV_VAR = "AGENT_MEMORY_CONFIG"
+DEFAULT_PATH = Path.home() / ".config" / "vvz-agent-memory" / "config.json"
+SECTIONS = ("ailogger_client", "embedding_client", "embedding_model")
+PROTOCOLS = ("http", "https", "mtls")
+DEFAULT_TIMEOUT = 10.0
+
+
+class ConfigProblem(Exception):
+    """The configuration document cannot be used; ``errors`` lists every problem found."""
+
+    def __init__(self, errors: list[dict[str, str]]) -> None:
+        super().__init__("; ".join(f"{e['section']}.{e['key']}: {e['message']}" for e in errors))
+        self.errors = errors
+
+
+@dataclass(frozen=True)
+class Config:
+    path: Path
+    document: Mapping[str, Any]
+
+    @property
+    def base_dir(self) -> str:
+        return str(self.path.parent)
+
+    @property
+    def logger_section(self) -> Mapping[str, Any]:
+        return self.document["ailogger_client"]
+
+    @property
+    def embedding_section(self) -> Mapping[str, Any]:
+        return self.document["embedding_client"]
+
+    @property
+    def model(self) -> str:
+        return str(self.document["embedding_model"]["model"])
+
+    @property
+    def dimension(self) -> int:
+        return int(self.document["embedding_model"]["dimension"])
+
+
+def resolve_path(explicit: str | None) -> Path:
+    """``--config`` wins, then ``$AGENT_MEMORY_CONFIG``, then ``~/.config/vvz-agent-memory/config.json``."""
+    if explicit:
+        return Path(explicit).expanduser().resolve()
+    env = os.environ.get(ENV_VAR)
+    if env:
+        return Path(env).expanduser().resolve()
+    return DEFAULT_PATH
+
+
+def load(explicit: str | None) -> Config:
+    path = resolve_path(explicit)
+    if not path.is_file():
+        raise ConfigProblem([{"section": "-", "key": "-", "message": f"configuration document not found: {path}"}])
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConfigProblem([{"section": "-", "key": "-", "message": f"{path}: invalid JSON: {exc}"}]) from exc
+    errors = validate(document, path.parent)
+    if errors:
+        raise ConfigProblem(errors)
+    return Config(path=path, document=document)
+
+
+def _get(section: Any, dotted: str) -> Any:
+    node = section
+    for part in dotted.split("."):
+        if not isinstance(node, Mapping):
+            return None
+        node = node.get(part)
+    return node
+
+
+def _err(section: str, key: str, message: str) -> dict[str, str]:
+    return {"section": section, "key": key, "message": message}
+
+
+def _check_client_section(name: str, section: Any, base_dir: Path) -> list[dict[str, str]]:
+    errors: list[dict[str, str]] = []
+    if not isinstance(section, Mapping):
+        return [_err(name, "-", "must be an object")]
+    protocol = section.get("protocol", "http")
+    if protocol not in PROTOCOLS:
+        errors.append(_err(name, "protocol", f"must be one of {list(PROTOCOLS)}, got {protocol!r}"))
+    host = _get(section, "server.host")
+    if not isinstance(host, str) or not host:
+        errors.append(_err(name, "server.host", "required non-empty string"))
+    port = _get(section, "server.port")
+    if not isinstance(port, int) or isinstance(port, bool) or not 0 < port < 65536:
+        errors.append(_err(name, "server.port", "required integer 1..65535"))
+    timeout = _get(section, "client.timeout")
+    if timeout is not None and (not isinstance(timeout, (int, float)) or isinstance(timeout, bool) or timeout <= 0):
+        errors.append(_err(name, "client.timeout", "must be a positive number"))
+    material = {}
+    for key in ("cert", "key", "ca"):
+        value = _get(section, f"client.ssl.{key}") or _get(section, f"ssl.{key}")
+        if value is not None and not isinstance(value, str):
+            errors.append(_err(name, f"ssl.{key}", "must be a path string"))
+            continue
+        if value:
+            material[key] = value
+            if not (base_dir / value).is_file():
+                errors.append(_err(name, f"ssl.{key}", f"file not found: {base_dir / value}"))
+    if protocol == "mtls":
+        for key in ("cert", "key", "ca"):
+            if key not in material:
+                errors.append(_err(name, f"ssl.{key}", "required when protocol is mtls"))
+    elif protocol == "http" and material:
+        errors.append(_err(name, "ssl", "certificate material is set but protocol is http"))
+    if ("cert" in material) != ("key" in material):
+        errors.append(_err(name, "ssl.cert", "ssl.cert and ssl.key are set together or not at all"))
+    check_hostname = _get(section, "ssl.check_hostname")
+    if check_hostname is not None and not isinstance(check_hostname, bool):
+        errors.append(_err(name, "ssl.check_hostname", "must be a boolean"))
+    token = _get(section, "auth.token")
+    if token is not None and not isinstance(token, str):
+        errors.append(_err(name, "auth.token", "must be a string"))
+    header = _get(section, "auth.token_header")
+    if header is not None and not token:
+        errors.append(_err(name, "auth.token_header", "set without auth.token"))
+    return errors
+
+
+def validate(document: Any, base_dir: Path) -> list[dict[str, str]]:
+    """Every problem of the document; empty when it is usable."""
+    if not isinstance(document, Mapping):
+        return [_err("-", "-", "the document must be a JSON object")]
+    errors: list[dict[str, str]] = []
+    for name in document:
+        if name not in SECTIONS:
+            errors.append(_err(name, "-", f"unknown section; allowed: {list(SECTIONS)}"))
+    for name in SECTIONS:
+        if name not in document:
+            errors.append(_err(name, "-", "required section is missing"))
+    if "ailogger_client" in document:
+        errors += _check_client_section("ailogger_client", document["ailogger_client"], base_dir)
+        if not errors:
+            from ailogger_client.config import ConfigError, load_config_kwargs
+
+            try:
+                load_config_kwargs(document["ailogger_client"], str(base_dir))
+            except ConfigError as exc:
+                errors.append(_err("ailogger_client", "-", f"refused by ailogger_client.config: {exc}"))
+    if "embedding_client" in document:
+        errors += _check_client_section("embedding_client", document["embedding_client"], base_dir)
+    model = document.get("embedding_model")
+    if model is not None:
+        if not isinstance(model, Mapping):
+            errors.append(_err("embedding_model", "-", "must be an object"))
+        else:
+            if not isinstance(model.get("model"), str) or not model.get("model"):
+                errors.append(_err("embedding_model", "model", "required non-empty string"))
+            dim = model.get("dimension")
+            if not isinstance(dim, int) or isinstance(dim, bool) or dim <= 0:
+                errors.append(_err("embedding_model", "dimension", "required positive integer"))
+    return errors
+
+
+def _client_section(protocol: str, host: str, port: int, timeout: float, cert: str | None, key: str | None,
+                    ca: str | None, check_hostname: bool | None, token: str | None,
+                    token_header: str | None) -> dict[str, Any]:
+    section: dict[str, Any] = {
+        "protocol": protocol,
+        "server": {"host": host, "port": port},
+        "client": {"timeout": timeout},
+    }
+    ssl: dict[str, Any] = {}
+    for name, value in (("cert", cert), ("key", key), ("ca", ca)):
+        if value:
+            ssl[name] = value
+    if check_hostname is not None:
+        ssl["check_hostname"] = check_hostname
+    if ssl:
+        section["ssl"] = ssl
+    if token:
+        section["auth"] = {"token": token, "token_header": token_header or "X-API-Key"}
+    return section
+
+
+def generate(args: Any) -> dict[str, Any]:
+    """Build a document from the ``config generate`` arguments; every setting has an argument."""
+    return {
+        "ailogger_client": _client_section(
+            args.logger_protocol, args.logger_host, args.logger_port, args.logger_timeout,
+            args.logger_cert, args.logger_key, args.logger_ca, args.logger_check_hostname,
+            args.logger_token, args.logger_token_header,
+        ),
+        "embedding_client": _client_section(
+            args.embed_protocol, args.embed_host, args.embed_port, args.embed_timeout,
+            args.embed_cert or args.logger_cert, args.embed_key or args.logger_key,
+            args.embed_ca or args.logger_ca, args.embed_check_hostname, args.embed_token,
+            args.embed_token_header,
+        ),
+        "embedding_model": {"model": args.embed_model, "dimension": args.embed_dimension},
+    }

vvz_agent_memory/embedding.py

@@ -0,0 +1,93 @@
+"""Vectors for the file store, through the published embed_client, with the logger's model.
+
+The section is reshaped exactly as ai-logger's own binding does it
+(``ailogger/embedding_client.py``), so the same service answers with the same model.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from .config import DEFAULT_TIMEOUT, Config, _get
+
+
+class EmbeddingUnavailable(Exception):
+    """The embedding service did not give a vector; the message is kept without `.emb`."""
+
+
+def _config_dict(section: Mapping[str, Any], base_dir: str) -> dict[str, Any]:
+    protocol = str(section.get("protocol", "http"))
+    host = _get(section, "server.host")
+    port = _get(section, "server.port")
+    timeout = float(_get(section, "client.timeout") or DEFAULT_TIMEOUT)
+
+    def path(key: str) -> str | None:
+        value = _get(section, f"client.ssl.{key}") or _get(section, f"ssl.{key}")
+        return str(Path(base_dir) / value) if value else None
+
+    scheme = "http" if protocol == "http" else "https"
+    result: dict[str, Any] = {
+        "protocol": protocol,
+        "server": {"host": host, "port": port, "base_url": f"{scheme}://{host}:{port}"},
+        "client": {"timeout": timeout},
+    }
+    cert, key, ca = path("cert"), path("key"), path("ca")
+    ssl: dict[str, Any] = {}
+    if cert or key or ca:
+        ssl.update(enabled=True, cert_file=cert, key_file=key, ca_cert_file=ca)
+    check_hostname = _get(section, "ssl.check_hostname")
+    if check_hostname is not None:
+        ssl["check_hostname"] = check_hostname
+    if ssl:
+        result["ssl"] = ssl
+    token = _get(section, "auth.token")
+    if token:
+        result["auth"] = {
+            "method": "api_key",
+            "api_keys": {"default": token},
+            "api_key_header": _get(section, "auth.token_header") or "X-API-Key",
+        }
+    return result
+
+
+async def embed(config: Config, text: str) -> dict[str, Any]:
+    """The `.emb` body for ``text``: ``{model, dimension, embedding}``.
+
+    Raises EmbeddingUnavailable on any failure of the service or a vector of the wrong
+    model or dimension — a vector that does not match the logger's is worse than none.
+    """
+    from embed_client import EmbeddingClient
+    from embed_client.response_parsers import extract_embeddings
+
+    section = config.embedding_section
+    timeout = float(_get(section, "client.timeout") or DEFAULT_TIMEOUT)
+    try:
+        client = EmbeddingClient.from_config_dict(_config_dict(section, config.base_dir))
+        async with client:
+            data = await client.embed([text], model=config.model, wait=True, wait_timeout=int(timeout) or 60)
+    except Exception as exc:  # the service, its transport and its client all count as "no vector"
+        raise EmbeddingUnavailable(f"{type(exc).__name__}: {exc}") from exc
+    if not isinstance(data, Mapping):
+        raise EmbeddingUnavailable(f"unexpected answer type {type(data).__name__}")
+    vectors = data.get("embeddings")
+    if vectors is None:
+        vectors = extract_embeddings({"result": {"success": True, "data": data}})
+    if not vectors or not isinstance(vectors[0], Sequence):
+        raise EmbeddingUnavailable("the answer carries no vector")
+    vector = [float(x) for x in vectors[0]]
+    model = data.get("model", config.model)
+    if model != config.model:
+        raise EmbeddingUnavailable(f"service answered with model {model!r}, configured {config.model!r}")
+    if len(vector) != config.dimension:
+        raise EmbeddingUnavailable(f"vector dimension {len(vector)}, configured {config.dimension}")
+    return {"model": model, "dimension": len(vector), "embedding": vector}
+
+
+def cosine(a: Sequence[float], b: Sequence[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b, strict=True))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    return dot / (na * nb) if na and nb else 0.0