novacode-cli 1.2.0__py3-none-any.whl

novacode_cli/memory/builtin_lessons.py

@@ -0,0 +1,60 @@
+"""Lessons every installation starts with.
+
+Running the learning loop across a dozen unrelated tasks, the only things that
+earned a place in the shared pool were environment facts that are true for
+everyone: run ``apt-get update`` first, how to get Python into a bare container.
+There is no reason for each user to pay to rediscover those, so they ship here.
+
+They are recalled exactly like learned lessons — only when what is on screen
+matches — and are never injected wholesale. Each is written symptom-first,
+because the symptom is what a session is looking at when it needs the lesson.
+
+Every entry below was hit by an agent on Terminal-Bench and resolved the way it
+says. Keep it that way: add something only once it has been seen to work.
+
+This is a Python module rather than a data file because the package ships only
+``*.jinja`` as package data.
+"""
+
+from __future__ import annotations
+
+import os
+
+TOPIC = "builtin-environment"
+
+LESSONS: tuple[str, ...] = (
+    "- **Symptom:** `E: Unable to locate package <name>` from `apt-get install` in a fresh "
+    "container. **Cause:** the image ships with no package lists. **Fix:** run `apt-get update` "
+    "first, then install.",
+    "- **Symptom:** `apt-get install` stops at a `Geographic area:` / `Configuring tzdata` menu, or "
+    "hangs with no output. **Cause:** debconf is waiting for an answer and there is no terminal. "
+    "**Fix:** `DEBIAN_FRONTEND=noninteractive apt-get install -y <packages>`.",
+    "- **Symptom:** `bash: python3: command not found` or `python: command not found`. **Cause:** "
+    "the image has no Python (or only `python3`, not `python`). **Fix:** `apt-get update && "
+    "apt-get install -y python3 python3-pip`, and call it as `python3`.",
+    "- **Symptom:** `error: externally-managed-environment` from `pip install`. **Cause:** PEP 668 — "
+    "the system Python refuses global installs. **Fix:** `pip install --break-system-packages "
+    "<pkg>` in a throwaway container, or create a venv with `python3 -m venv`.",
+    "- **Symptom:** `E: Could not get lock /var/lib/dpkg/lock` or `lock-frontend`. **Cause:** "
+    "another apt/dpkg process is still running. **Fix:** wait for it to finish (`while pgrep -x "
+    "apt-get >/dev/null || pgrep -x dpkg >/dev/null; do sleep 2; done`); do not delete the lock.",
+    "- **Symptom:** `Could not find a suitable TLS CA certificate bundle` or SSL certificate "
+    "errors from pip/curl in a minimal image. **Cause:** no CA certificates installed. **Fix:** "
+    "`apt-get install -y ca-certificates`.",
+    "- **Symptom:** `curl: command not found` (or `timeout: failed to run command 'curl'`). "
+    "**Cause:** minimal image. **Fix:** `apt-get install -y curl`, or use `wget` or Python's "
+    "`urllib` if one of those is present.",
+    "- **Symptom:** a command takes minutes and its output comes back truncated. **Cause:** it "
+    "printed megabytes (a binary dump, a runaway loop, a huge log). **Fix:** bound the output — "
+    "`| head -c 2000`, `| tail -n 40`, or compare hashes/sizes instead of printing content.",
+)
+
+
+def enabled() -> bool:
+    """Off with ``NOVA_BUILTIN_LESSONS=0``."""
+    return os.environ.get("NOVA_BUILTIN_LESSONS", "").strip().lower() not in {"0", "false", "off"}
+
+
+def body() -> str:
+    """The lessons as a topic-file body."""
+    return "# Environment basics\n\n" + "\n".join(LESSONS) + "\n"

novacode_cli/memory/dream_gates.py

@@ -0,0 +1,192 @@
+"""When Nova may dream: the three gates in front of automatic memory consolidation.
+
+A dream (``/dream``) consolidates the memory wiki. Run automatically, it must
+neither over-dream (burning tokens on a wiki that barely changed) nor
+under-dream (letting a busy week's lessons sit unconsolidated). It runs only
+when all three gates pass:
+
+- **Time gate:** at least :data:`TIME_GATE` since the last dream.
+- **Session gate:** at least :data:`SESSION_GATE` sessions (with messages)
+  started since the last dream.
+- **Lock gate:** the consolidation lock is free, so two Nova processes (or a
+  manual ``/dream`` and an automatic one) never consolidate at once.
+
+A manual ``/dream`` skips the time and session gates (the user asked) but still
+takes the lock, and any finished dream resets both counters.
+
+State lives beside the memory it guards: ``<agent_dir>/.dream.json`` and the
+lock file ``<agent_dir>/.dream.lock``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+#: Minimum time between dreams.
+TIME_GATE = timedelta(hours=24)
+#: Minimum sessions started since the last dream.
+SESSION_GATE = 5
+#: A lock older than this belongs to a dream that died; it may be taken over.
+STALE_LOCK = timedelta(hours=2)
+
+_STATE = ".dream.json"
+_LOCK = ".dream.lock"
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _read_state(agent_dir: Path) -> dict:
+    try:
+        return json.loads((agent_dir / _STATE).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_state(agent_dir: Path, state: dict) -> None:
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    tmp = agent_dir / f"{_STATE}.tmp"
+    tmp.write_text(json.dumps(state, indent=2), encoding="utf-8")
+    tmp.replace(agent_dir / _STATE)
+
+
+def last_dream(agent_dir: Path) -> datetime:
+    """When the gates were last reset.
+
+    On the first check there is no record; that moment becomes the baseline, so
+    upgrading Nova does not set off a dream over months of old sessions at once.
+    """
+    state = _read_state(agent_dir)
+    try:
+        return datetime.fromisoformat(state["last_dream_at"])
+    except (KeyError, TypeError, ValueError):
+        now = _now()
+        _write_state(agent_dir, {**state, "last_dream_at": now.isoformat(), "trigger": "baseline"})
+        return now
+
+
+def record_dream(agent_dir: Path, trigger: str, outcome: str) -> None:
+    """Reset the time and session gates after a dream finished."""
+    state = _read_state(agent_dir)
+    state.update(last_dream_at=_now().isoformat(), trigger=trigger, outcome=outcome)
+    _write_state(agent_dir, state)
+
+
+def sessions_since(sessions_dir: Path, since: datetime) -> int:
+    """Sessions with at least one message started after ``since``."""
+    cutoff = since.timestamp()
+    count = 0
+    try:
+        entries = list(sessions_dir.iterdir())
+    except OSError:
+        return 0
+    for entry in entries:
+        try:
+            # A session untouched since the cutoff cannot have started after it;
+            # this skips reading most of a large history's meta files.
+            if not entry.is_dir() or entry.stat().st_mtime < cutoff:
+                continue
+            meta = json.loads((entry / "meta.json").read_text(encoding="utf-8"))
+            started = datetime.fromisoformat(meta["created_at"])
+        except (OSError, ValueError, KeyError, TypeError):
+            continue
+        if started > since and int(meta.get("message_count") or 0) > 0:
+            count += 1
+    return count
+
+
+@dataclass(frozen=True)
+class GateReport:
+    """Each gate's state, for the decision and for ``/dream status``."""
+
+    since: datetime
+    sessions: int
+    lock_holder: str | None  # "pid 1234 since 10:02", or None when free
+
+    @property
+    def time_ok(self) -> bool:
+        """At least :data:`TIME_GATE` since the last dream."""
+        return _now() - self.since >= TIME_GATE
+
+    @property
+    def sessions_ok(self) -> bool:
+        """At least :data:`SESSION_GATE` sessions since the last dream."""
+        return self.sessions >= SESSION_GATE
+
+    @property
+    def lock_ok(self) -> bool:
+        """No other dream holds the lock."""
+        return self.lock_holder is None
+
+    @property
+    def open(self) -> bool:
+        """All three gates pass: an automatic dream may run."""
+        return self.time_ok and self.sessions_ok and self.lock_ok
+
+
+def check_gates(agent_dir: Path, sessions_dir: Path) -> GateReport:
+    """Evaluate the three gates (reads files; call off the UI thread)."""
+    since = last_dream(agent_dir)
+    return GateReport(
+        since=since,
+        sessions=sessions_since(sessions_dir, since),
+        lock_holder=_lock_holder(agent_dir),
+    )
+
+
+def _lock_holder(agent_dir: Path) -> str | None:
+    """Who holds a live lock, or None when it is free or stale."""
+    try:
+        info = json.loads((agent_dir / _LOCK).read_text(encoding="utf-8"))
+        taken = datetime.fromisoformat(info["at"])
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+    if _now() - taken > STALE_LOCK:
+        return None
+    return f"pid {info.get('pid')} since {taken.astimezone().strftime('%H:%M')}"
+
+
+class DreamLock:
+    """The lock gate: an exclusive lock file; ``acquire()`` returns False if held."""
+
+    def __init__(self, agent_dir: Path) -> None:  # noqa: D107
+        self._path = agent_dir / _LOCK
+        self._held = False
+
+    def acquire(self) -> bool:
+        """Take the lock, replacing a stale one; False when another dream holds it."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        for _ in range(2):
+            try:
+                fd = os.open(self._path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            except FileExistsError:
+                if _lock_holder(self._path.parent) is not None:
+                    return False
+                # Stale (or unreadable): remove and retry once. A racing process
+                # that wins the retry keeps the lock; we then report it held.
+                try:
+                    self._path.unlink()
+                except OSError:
+                    return False
+                continue
+            with os.fdopen(fd, "w", encoding="utf-8") as stream:
+                json.dump({"pid": os.getpid(), "at": _now().isoformat()}, stream)
+            self._held = True
+            return True
+        return False
+
+    def release(self) -> None:
+        """Give the lock back (only if this object took it)."""
+        if self._held:
+            self._held = False
+            with contextlib.suppress(OSError):
+                self._path.unlink()

novacode_cli/memory/limits.py

@@ -0,0 +1,59 @@
+"""Shared limits for the memory tiers.
+
+Single source of truth for the per-file character budget used on both the
+**write** side (Semantic-tier compaction in ``hermes/memory_tiers.py``) and the
+**read** side (prompt-injection truncation in ``memory/agent_memory.py``). These
+were previously two independent ``MAX_MEMORY_CHARS = 12_000`` constants that
+could silently drift.
+
+Compaction invariant (keep-newest):
+    Memory files are written newest-first (new sections/lessons are prepended,
+    above older ones). Both compaction and injection-time truncation therefore
+    keep the **head** of the file — which is the most recent content. Any new
+    memory writer MUST prepend, not append, to preserve this.
+"""
+
+from __future__ import annotations
+
+# Maximum characters per memory file before disk compaction / truncation
+# (~3,000 tokens at 4 chars/token). This is the WRITE-side cap only: it bounds
+# what survives on disk, and is deliberately larger than the injection budget
+# below so raising the budget later can still recover content.
+MAX_MEMORY_CHARS = 12_000
+
+
+#: Share of the context window ONE injected memory block may occupy. Four
+#: blocks are injected every turn (agent.md, INDEX.md, HABITS.md, project
+#: memory), so the tier as a whole is capped at ~12% of the window.
+MEMORY_WINDOW_FRACTION = 0.03
+
+
+#: Default per-block *injection* budget (agent.md, INDEX, HABITS, project
+#: memory). Lowered from the 12k disk cap: the injected head is what the model
+#: reads every turn, and older content is reachable on demand via
+#: ``memory_search``. User-overridable in Nova.config.json
+#: (``memory_block_chars``).
+DEFAULT_MEMORY_BLOCK_CHARS = 6_000
+
+
+#: Chars of the topic-memory INDEX injected into the system prompt. The index is
+#: a pointer list (newest first); the rest is reachable via ``memory_search``, so
+#: a small slice is enough to orient without paying for ~100k chars of pointers.
+DEFAULT_MEMORY_INDEX_CHARS = 2_000
+
+
+def memory_budget(context_window: int, cap: int = DEFAULT_MEMORY_BLOCK_CHARS) -> int:
+    """Chars one injected memory block may use, given the model's window.
+
+    ``MAX_MEMORY_CHARS`` is a *disk* cap and is window-independent — but as an
+    injection cap it was the same 12k on a 200K Claude window and on a 40K
+    Ollama one, where the four blocks together could claim a third of the
+    window before the conversation started. Skills already budget this way
+    (``skills.refreshing_middleware.listing_budget``); memory now does too.
+
+    ``cap`` overrides the ceiling (the user-configurable per-block budget);
+    the window fraction still applies, so a small window is never overrun.
+    """
+    if context_window <= 0:
+        return cap
+    return max(2_000, min(cap, int(context_window * MEMORY_WINDOW_FRACTION * 4)))

novacode_cli/memory/parsed_cache.py

@@ -0,0 +1,106 @@
+"""Parsed memory cache with entry and resident-size limits."""
+
+# JSON and LangGraph interfaces carry heterogeneous values.
+# ruff: noqa: ANN401
+import hashlib
+import sys
+from collections import OrderedDict
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+
+def file_hash(path: Any) -> str:
+    """Hash current contents in bounded chunks regardless of timestamps."""
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(64 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def resident_size(value: Any) -> int:
+    """Count strings and token sets as well as the container holding them."""
+    if isinstance(value, (tuple, list, set, frozenset)):
+        return sys.getsizeof(value) + sum(resident_size(item) for item in value)
+    return sys.getsizeof(value)
+
+
+class ParsedMemoryCache(OrderedDict):
+    """LRU; conservative accounting counts shared values for each entry."""
+
+    def __init__(self, max_entries: int = 512, max_bytes: int = 16 * 1024 * 1024) -> None:
+        """Initialize local state without acquiring invocation ownership."""
+        super().__init__()
+        self.max_entries, self.max_bytes = max_entries, max_bytes
+        self.resident_bytes = 0
+        self._sizes: dict[Any, int] = {}
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        """Insert a parsed entry and evict the least recently used entries."""
+        size = resident_size(key) + resident_size(value) + 256
+        if key in self:
+            self.resident_bytes -= self._sizes.pop(key)
+            super().__delitem__(key)
+        if size > self.max_bytes:
+            return
+        super().__setitem__(key, value)
+        self._sizes[key] = size
+        self.resident_bytes += size
+        while len(self) > self.max_entries or self.resident_bytes > self.max_bytes:
+            oldest, _ = super().popitem(last=False)
+            self.resident_bytes -= self._sizes.pop(oldest)
+
+    def __getitem__(self, key: Any) -> Any:
+        """Read an entry and mark it as most recently used."""
+        value = super().__getitem__(key)
+        self.move_to_end(key)
+        return value
+
+    def __delitem__(self, key: Any) -> None:
+        """Delete a parsed entry and its resident-size accounting."""
+        super().__delitem__(key)
+        self.resident_bytes -= self._sizes.pop(key)
+
+    def clear(self) -> None:
+        """Release entries and their resident-size accounting together."""
+        super().clear()
+        self._sizes.clear()
+        self.resident_bytes = 0
+
+
+class MemoryCorpus(Mapping):
+    """Keep discovery order while caching parsed bodies independently of corpus size."""
+
+    def __init__(self, cache: ParsedMemoryCache, tokenize: Any) -> None:
+        """Retain source descriptors; parse individual entries when retrieved."""
+        self.cache, self.tokenize = cache, tokenize
+        self.sources: dict[str, tuple[Any, Any, str]] = {}
+
+    def add(self, topic: str, title: Any, source: Path | str, digest: str) -> None:
+        """Register a source without admitting its body into the cache."""
+        self.sources[topic] = (title, source, digest)
+
+    def __len__(self) -> int:
+        """Count discoverable topics, including uncached topics."""
+        return len(self.sources)
+
+    def __iter__(self) -> Iterator[str]:
+        """Keep the original source ordering."""
+        return iter(self.sources)
+
+    def __getitem__(self, topic: str) -> Any:
+        """Parse on demand and retain only bodies that fit the bounded LRU."""
+        title, source, digest = self.sources[topic]
+        key = (topic, str(source) if isinstance(source, Path) else "inline", digest)
+        if key in self.cache:
+            return self.cache[key]
+        try:
+            body = source.read_text(encoding="utf-8") if isinstance(source, Path) else source
+        except OSError:
+            # A file can disappear between discovery and retrieval. Do not
+            # retain a negative parse; the next discovery sees the deletion.
+            return title, "", frozenset()
+        value = title, body, self.tokenize(body)
+        self.cache[key] = value
+        return value

novacode_cli/memory/recall_stats.py

@@ -0,0 +1,97 @@
+"""Which lessons get recalled, and whether recalling them helped.
+
+Memory that is only ever written to grows without limit and nobody can tell the
+useful part from the rest. This keeps two counts per lesson:
+
+* ``recalls``  — how many times it was put in front of the model;
+* ``resolved`` — how many of those were at a failure that was followed by a
+  non-failure. That is a weak signal (the next command may have succeeded for
+  any reason), but a lesson recalled twenty times at errors that never clear is
+  not earning its place, and one that is never recalled at all is dead weight.
+
+Nothing here deletes anything: :func:`unused` and :func:`report` say what the
+evidence is, and a person or a curation pass decides.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_FILE = ".recall-stats.json"
+
+
+def _key(bullet: str) -> str:
+    text = " ".join(bullet.lstrip("-*• ").split()).lower()
+    return hashlib.sha1(text.encode("utf-8")).hexdigest()[:16]  # noqa: S324 — an id, not security
+
+
+def _path(agent_dir: Path) -> Path:
+    return agent_dir / "memories" / _FILE
+
+
+def _read(agent_dir: Path) -> dict[str, dict]:
+    try:
+        data = json.loads(_path(agent_dir).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write(agent_dir: Path, stats: dict[str, dict]) -> None:
+    try:
+        path = _path(agent_dir)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(stats, indent=1), encoding="utf-8")
+    except OSError:
+        logger.debug("could not write recall stats", exc_info=True)
+
+
+def note_recalled(agent_dir: Path, bullets: list[str]) -> list[str]:
+    """Count one recall for each bullet; returns their keys."""
+    if not bullets:
+        return []
+    stats, now, keys = _read(agent_dir), time.time(), []
+    for bullet in bullets:
+        key = _key(bullet)
+        entry = stats.setdefault(
+            key, {"text": bullet.lstrip("-*• ").strip()[:160], "recalls": 0, "resolved": 0, "first": now}
+        )
+        entry["recalls"] += 1
+        entry["last"] = now
+        keys.append(key)
+    _write(agent_dir, stats)
+    return keys
+
+
+def note_resolved(agent_dir: Path, keys: list[str]) -> None:
+    """The failure these lessons were recalled at was followed by a non-failure."""
+    if not keys:
+        return
+    stats = _read(agent_dir)
+    for key in keys:
+        if key in stats:
+            stats[key]["resolved"] = stats[key].get("resolved", 0) + 1
+    _write(agent_dir, stats)
+
+
+def report(agent_dir: Path) -> list[dict]:
+    """Every tracked lesson, most recalled first."""
+    return sorted(_read(agent_dir).values(), key=lambda e: -e.get("recalls", 0))
+
+
+def unused(agent_dir: Path, lessons: list[str], *, older_than_days: float = 30.0) -> list[str]:
+    """Lessons that exist but have never been recalled, among ``lessons``.
+
+    ``older_than_days`` cannot be checked for a lesson with no recall record (it
+    has no timestamp here), so callers pass only lessons they know to be at
+    least that old — typically from the topic file's own review timestamps.
+    """
+    del older_than_days  # documented contract; ageing is the caller's knowledge
+    seen = _read(agent_dir)
+    return [bullet for bullet in lessons if _key(bullet) not in seen]

novacode_cli/memory/semantic.py

@@ -0,0 +1,116 @@
+"""Meaning-level similarity between short texts, computed locally.
+
+Lesson handling used to compare words: is this bullet a repeat of that one, has
+another project recorded the same fact, does this lesson bear on the error on
+screen. Word overlap got each of those wrong on real data — it missed four of
+five same-fact pairs, "confirmed" a toolchain note because it shared the phrase
+``apt-get update``, and could not connect ``python3: command not found`` to a
+lesson that only described the fix.
+
+This uses the static embedding model Nova already depends on for code search
+(``potion-code-16M`` via ``model2vec``): no network or API call per use, ~1 s to
+load once, and a few hundred texts embed in ~20 ms. If it cannot be loaded every
+caller falls back to word overlap, so nothing depends on it being present.
+
+Measured on lessons from Terminal-Bench runs (cosine):
+same fact reworded 0.59-0.81; different facts on one subject 0.34-0.47 (one pair
+0.65); unrelated ~0.0; the error a lesson is about 0.50-0.70; ordinary output
+against every lesson under 0.2.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from contextlib import suppress
+from typing import Any
+
+from novacode_cli.computation_cache import digest
+from novacode_cli.embeddings import get_model
+from novacode_cli.memory.parsed_cache import ParsedMemoryCache
+
+logger = logging.getLogger(__name__)
+
+#: Two bullets at or above this say the same thing.
+SAME_FACT = 0.66
+#: A lesson at or above this bears on the text it is compared with.
+RELEVANT = 0.45
+
+_CACHE_LIMIT = 4096
+_cache = ParsedMemoryCache(max_entries=_CACHE_LIMIT, max_bytes=8 * 1024 * 1024)
+_cache_model: Any = None
+_embed_lock = threading.Lock()
+
+
+def enabled() -> bool:
+    """False when switched off by ``NOVA_SEMANTIC_MEMORY=0`` or the model is missing."""
+    if os.environ.get("NOVA_SEMANTIC_MEMORY", "").strip().lower() in {"0", "false", "off"}:
+        return False
+    return _load() is not None
+
+
+def _load() -> Any:  # noqa: ANN401
+    return get_model()
+
+
+def embed(texts: list[str]) -> Any:  # noqa: ANN401
+    """Unit-length vectors for ``texts`` (rows), or None when unavailable."""
+    if not texts or not enabled():
+        return None
+    import numpy as np
+
+    global _cache_model  # noqa: PLW0603
+    model = _load()
+    cache_enabled = os.environ.get("NOVA_DISABLE_COMPUTATION_CACHE") != "1"
+    # Concurrent memory searches share one miss computation. The lock also
+    # protects LRU promotion and eviction; no network calls happen in encode.
+    with _embed_lock:
+        if _cache_model is not model:
+            _cache.clear()
+            _cache_model = model
+        unique = dict.fromkeys(texts)
+        keys = {text: digest(text) for text in unique}
+        found = {}
+        for text in unique:
+            if cache_enabled:
+                with suppress(KeyError):
+                    found[text] = _cache[keys[text]]
+        missing = [text for text in unique if text not in found]
+        if missing:
+            try:
+                vectors = model.encode(missing)
+            except Exception:  # noqa: BLE001
+                logger.debug("embedding failed", exc_info=True)
+                return None
+            norms = np.linalg.norm(vectors, axis=1, keepdims=True)
+            vectors = vectors / np.where(norms == 0, 1.0, norms)
+            for text, vector in zip(missing, vectors, strict=True):
+                # A row view would retain the entire batch allocation even if
+                # every other row was evicted, defeating the byte budget.
+                found[text] = vector.copy()
+                if cache_enabled:
+                    _cache[keys[text]] = found[text]
+        return np.stack([found[text] for text in texts])
+
+
+def best_match(text: str, candidates: list[str]) -> tuple[float, int]:
+    """``(similarity, index)`` of the candidate closest to ``text``; ``(0.0, -1)`` if none."""
+    if not text.strip() or not candidates:
+        return 0.0, -1
+    vectors = embed([text, *candidates])
+    if vectors is None:
+        return 0.0, -1
+    scores = vectors[1:] @ vectors[0]
+    index = int(scores.argmax())
+    return float(scores[index]), index
+
+
+def similarities(text: str, candidates: list[str]) -> list[float]:
+    """Similarity of ``text`` to each candidate; empty when unavailable."""
+    if not text.strip() or not candidates:
+        return []
+    vectors = embed([text, *candidates])
+    if vectors is None:
+        return []
+    return [float(s) for s in vectors[1:] @ vectors[0]]