ltcai 11.7.0 → 12.0.0

package/latticeai/core/embedding_providers/autodetect.py

@@ -0,0 +1,302 @@
+"""Find the real embedder that is already on this machine.
+
+The default text embedder is :class:`~.text.HashEmbeddingProvider` — feature
+hashing into 384 dimensions. It is deterministic, offline and always available,
+and it is **not semantic**: two sentences that mean the same thing in different
+words score near zero against each other. Every recall complaint about "왜 못
+찾지" that is not a keyword problem is this.
+
+A real provider has always been configurable (``LATTICEAI_EMBEDDING_PROVIDER``),
+but nothing ever *looked* for one, so a machine with a perfectly good embedding
+model already in its Hugging Face cache still hashed. This module is that look:
+
+1. an explicit configuration always wins and is never second-guessed;
+2. otherwise, if a known embedding model is already **downloaded**, name it —
+   filesystem only, no network, no download;
+3. otherwise, if an Ollama server is reachable and has an embedding model
+   pulled, name that;
+4. otherwise, nothing was found, and the hash fallback stays.
+
+Detection **reports**; adoption is a separate decision the caller makes (see
+:func:`resolve_auto_provider`). ``LATTICEAI_EMBEDDING_PROVIDER=auto`` adopts
+what was found; anything else leaves the resolution exactly as it was and the
+finding travels to ``GET /api/embeddings/status`` as ``detected``, so the setup
+surface can offer the switch instead of taking it.
+
+## Why adoption is not automatic
+
+Rust files every vector under ``(embedding_model, embedding_dim)`` and searches
+only rows whose identity matches the embedder it holds — today the hash model.
+Switching the *worker's* provider therefore does not corrupt anything (the two
+identities never mix), but until the read path can embed a query through the
+same provider, provider vectors are written and never read. Adopting silently
+would buy inference cost and no recall. The switch is real, tested and one env
+var away; it is not a default.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+#: ``LATTICEAI_EMBEDDING_PROVIDER=auto`` — adopt whatever detection found.
+AUTO_PROVIDER = "auto"
+#: Set to ``0``/``false`` to skip detection entirely (and its Ollama probe).
+AUTODETECT_ENV = "LATTICEAI_EMBEDDING_AUTODETECT"
+#: Where the Ollama probe looks when nothing else says.
+OLLAMA_BASE_ENV = "LATTICEAI_EMBEDDING_BASE_URL"
+DEFAULT_OLLAMA_BASE = "http://127.0.0.1:11434"
+
+#: Local MLX embedding models this build knows how to drive, best first.
+#: ``dim`` is the model's true output width; ``prefix`` marks the E5 family,
+#: whose quality depends on the ``query:`` / ``passage:`` instruction.
+LOCAL_MLX_MODELS: Tuple[Tuple[str, int, bool], ...] = (
+    ("mlx-community/multilingual-e5-small-mlx", 384, True),
+    ("mlx-community/multilingual-e5-base-mlx", 768, True),
+    ("mlx-community/multilingual-e5-large-mlx", 1024, True),
+    ("mlx-community/snowflake-arctic-embed-l-v2.0-8bit", 1024, False),
+    ("mlx-community/embeddinggemma-300m-4bit", 768, False),
+    ("mlx-community/bge-m3", 1024, False),
+)
+
+#: Ollama model names that are embedders rather than chat models.
+OLLAMA_EMBEDDING_MODELS: Tuple[Tuple[str, int], ...] = (
+    ("bge-m3", 1024),
+    ("mxbai-embed-large", 1024),
+    ("nomic-embed-text", 768),
+    ("all-minilm", 384),
+)
+
+
+@dataclass
+class Detection:
+    """What was found, and how. Every field is safe to show a user."""
+
+    #: ``"mlx"`` | ``"ollama"`` | ``""`` when nothing was found.
+    provider: str = ""
+    model: str = ""
+    dim: int = 0
+    #: ``configured`` | ``local_model`` | ``ollama`` | ``none``.
+    source: str = "none"
+    detail: str = ""
+    #: Every candidate that was looked for and not found, for the UI to offer.
+    candidates: List[Dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def found(self) -> bool:
+        return bool(self.provider)
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "found": self.found,
+            "provider": self.provider,
+            "model": self.model,
+            "dim": self.dim,
+            "source": self.source,
+            "detail": self.detail,
+            "candidates": list(self.candidates),
+        }
+
+
+def autodetect_enabled(env: Optional[Dict[str, str]] = None) -> bool:
+    """Whether to look at all. On unless explicitly switched off."""
+    raw = (env or dict(os.environ)).get(AUTODETECT_ENV, "1").strip().lower()
+    return raw not in {"0", "false", "no", "off"}
+
+
+def hf_cache_roots(env: Optional[Dict[str, str]] = None) -> List[Path]:
+    """Every directory a Hugging Face snapshot could be under, in order."""
+    values = env or dict(os.environ)
+    roots: List[Path] = []
+    for key in ("HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE"):
+        raw = values.get(key, "").strip()
+        if raw:
+            roots.append(Path(raw))
+    home = values.get("HF_HOME", "").strip()
+    if home:
+        roots.append(Path(home) / "hub")
+    roots.append(Path(values.get("HOME", "~")).expanduser() / ".cache/huggingface/hub")
+    seen: List[Path] = []
+    for root in roots:
+        if root not in seen:
+            seen.append(root)
+    return seen
+
+
+def _snapshot_dir(repo_id: str, roots: List[Path]) -> Optional[Path]:
+    """The snapshot directory holding this repo's weights, if it is on disk.
+
+    A cache entry exists as soon as *anything* has been fetched, so presence of
+    the directory is not enough: a snapshot with a ``config.json`` and at least
+    one weight file is what "already downloaded" has to mean, or the detector
+    names a model that cannot load.
+    """
+    flattened = "models--" + repo_id.replace("/", "--")
+    for root in roots:
+        snapshots = root / flattened / "snapshots"
+        if not snapshots.is_dir():
+            continue
+        for snapshot in sorted(snapshots.iterdir()):
+            if not snapshot.is_dir():
+                continue
+            if not (snapshot / "config.json").exists():
+                continue
+            weights = any(
+                (snapshot / name).exists()
+                for name in ("model.safetensors", "weights.safetensors")
+            ) or any(snapshot.glob("*.safetensors"))
+            if weights:
+                return snapshot
+    return None
+
+
+def detect_local_mlx(env: Optional[Dict[str, str]] = None) -> Detection:
+    """The best already-downloaded MLX embedding model, or an empty finding."""
+    roots = hf_cache_roots(env)
+    candidates: List[Dict[str, Any]] = []
+    for repo_id, dim, prefixed in LOCAL_MLX_MODELS:
+        snapshot = _snapshot_dir(repo_id, roots)
+        candidates.append(
+            {
+                "provider": "mlx",
+                "model": repo_id,
+                "dim": dim,
+                "downloaded": snapshot is not None,
+                "e5_prefixes": prefixed,
+            }
+        )
+    for candidate in candidates:
+        if candidate["downloaded"]:
+            return Detection(
+                provider="mlx",
+                model=str(candidate["model"]),
+                dim=int(candidate["dim"]),
+                source="local_model",
+                detail=f"{candidate['model']} is already in the local model cache",
+                candidates=candidates,
+            )
+    return Detection(
+        source="none",
+        detail="no known embedding model is downloaded yet",
+        candidates=candidates,
+    )
+
+
+def detect_ollama(
+    base_url: str = "",
+    timeout: float = 1.5,
+    env: Optional[Dict[str, str]] = None,
+) -> Detection:
+    """An Ollama server with an embedding model pulled, or an empty finding.
+
+    One localhost GET with a short timeout. Any failure — no server, no httpx,
+    a slow answer — is "not found", never an error: detection must not be able
+    to delay or fail a boot.
+    """
+    values = env or dict(os.environ)
+    base = (base_url or values.get(OLLAMA_BASE_ENV, "") or DEFAULT_OLLAMA_BASE).rstrip("/")
+    try:
+        import httpx
+
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(f"{base}/api/tags")
+            response.raise_for_status()
+            payload = response.json()
+    except Exception as exc:
+        return Detection(source="none", detail=f"no Ollama server at {base}: {exc}")
+    names = [
+        str(model.get("name") or "")
+        for model in (payload.get("models") or [])
+        if isinstance(model, dict)
+    ]
+    for known, dim in OLLAMA_EMBEDDING_MODELS:
+        for name in names:
+            if name.split(":")[0] == known:
+                return Detection(
+                    provider="ollama",
+                    model=name,
+                    dim=dim,
+                    source="ollama",
+                    detail=f"{name} is pulled on the Ollama server at {base}",
+                )
+    return Detection(
+        source="none",
+        detail=f"Ollama at {base} has no embedding model pulled",
+    )
+
+
+def detect_embedder(
+    configured_provider: str = "",
+    configured_model: str = "",
+    env: Optional[Dict[str, str]] = None,
+    probe_ollama: bool = True,
+) -> Detection:
+    """What this machine could embed with, without downloading anything.
+
+    A configured provider is reported back as ``source="configured"`` and no
+    probing happens: the operator already answered the question.
+    """
+    values = env or dict(os.environ)
+    configured = str(configured_provider or "").strip().lower()
+    if configured and configured not in {"hash", "local", "fallback", AUTO_PROVIDER}:
+        return Detection(
+            provider=configured,
+            model=configured_model,
+            source="configured",
+            detail=f"{configured} is configured explicitly",
+        )
+    if not autodetect_enabled(values):
+        return Detection(source="none", detail=f"{AUTODETECT_ENV} is off")
+
+    local = detect_local_mlx(values)
+    if local.found:
+        return local
+    if probe_ollama:
+        ollama = detect_ollama(env=values)
+        if ollama.found:
+            ollama.candidates = local.candidates
+            return ollama
+    return local
+
+
+def resolve_auto_provider(
+    configured_provider: str,
+    configured_model: str,
+    configured_dim: int,
+    detection: Detection,
+) -> Tuple[str, str, int]:
+    """The ``(provider, model, dim)`` the embedder should actually be built with.
+
+    Only ``provider == "auto"`` changes anything, and only when detection found
+    something; ``auto`` with nothing found resolves to ``hash``, which is the
+    honest answer rather than a construction that will fail its probe.
+    Explicit configuration is returned untouched.
+    """
+    requested = str(configured_provider or "").strip().lower()
+    if requested != AUTO_PROVIDER:
+        return configured_provider, configured_model, configured_dim
+    if not detection.found:
+        return "hash", "", configured_dim
+    return (
+        detection.provider,
+        configured_model or detection.model,
+        configured_dim or detection.dim,
+    )
+
+
+__all__ = [
+    "AUTODETECT_ENV",
+    "AUTO_PROVIDER",
+    "DEFAULT_OLLAMA_BASE",
+    "LOCAL_MLX_MODELS",
+    "OLLAMA_EMBEDDING_MODELS",
+    "Detection",
+    "autodetect_enabled",
+    "detect_embedder",
+    "detect_local_mlx",
+    "detect_ollama",
+    "hf_cache_roots",
+    "resolve_auto_provider",
+]

package/latticeai/core/embedding_providers/base.py

@@ -45,8 +45,18 @@ _KNOWN_DIMS = {
     "gte-small": 384,
     "gte-base": 768,
     "gte-large": 1024,
+    "e5-small": 384,
+    "e5-base": 768,
     "e5-large": 1024,
+    "multilingual-e5-small": 384,
+    "multilingual-e5-small-mlx": 384,
+    "multilingual-e5-base": 768,
+    "multilingual-e5-base-mlx": 768,
     "multilingual-e5-large": 1024,
+    "multilingual-e5-large-mlx": 1024,
+    "snowflake-arctic-embed-l-v2.0-8bit": 1024,
+    "embeddinggemma-300m-4bit": 768,
+    "embeddinggemma-300m-8bit": 768,
     "text-embedding-3-small": 1536,
     "text-embedding-3-large": 3072,
     "text-embedding-ada-002": 1536,
@@ -86,6 +96,21 @@ class EmbeddingProvider:
     def embed_batch(self, texts: Sequence[str]) -> List[List[float]]:
         raise NotImplementedError
 
+    # ── optional: asymmetric models ───────────────────────────────────────
+    def embed_batch_for(
+        self, texts: Sequence[str], kind: str = "passage"
+    ) -> List[List[float]]:
+        """Embed for a *role*: ``"query"`` or ``"passage"``.
+
+        Most embedders are symmetric and ignore the role — the default here
+        does. The E5 family is not: it was trained with a literal ``query: ``
+        or ``passage: `` in front of the text, and dropping the instruction
+        costs real retrieval accuracy. ``POST /worker/embed`` already carries
+        the role (``kind``), so the one provider that needs it can have it
+        without every caller learning about instructions.
+        """
+        return self.embed_batch(texts)
+
     # ── derived (shared) ──────────────────────────────────────────────────
     def _model_id_with_dim(self, dim: int) -> str:
         """This provider's ``model_id`` restated at ``dim``.

package/latticeai/core/embedding_providers/profiles.py

@@ -10,6 +10,50 @@ from __future__ import annotations
 from typing import Any, Dict, List
 
 PRODUCTION_PROVIDER_PROFILES: Dict[str, Dict[str, Any]] = {
+    # ── one-click local profiles (v12.0.0) ────────────────────────────────
+    # These three carry `hf_repo_id` and `download_gb` because they are the
+    # ones a setup surface can *offer to fetch*: the id is what
+    # `huggingface_hub.snapshot_download` takes and what
+    # `autodetect.detect_local_mlx` looks for in the cache, so "offer",
+    # "download" and "detect" all name the same string. The rest of the table
+    # describes providers the user has to bring themselves (an Ollama server,
+    # an API key), which is why they have no repo id.
+    "local:multilingual-e5-small": {
+        "id": "local:multilingual-e5-small",
+        "provider": "mlx",
+        "model": "mlx-community/multilingual-e5-small-mlx",
+        "hf_repo_id": "mlx-community/multilingual-e5-small-mlx",
+        "download_gb": 0.24,
+        "dimensions": 384,
+        "grade": "production",
+        "family": "local",
+        "label": "Multilingual E5 Small (로컬)",
+        "detail": "한국어를 포함한 100여 개 언어. 240MB, 해시 임베더와 같은 384차원.",
+    },
+    "local:multilingual-e5-base": {
+        "id": "local:multilingual-e5-base",
+        "provider": "mlx",
+        "model": "mlx-community/multilingual-e5-base-mlx",
+        "hf_repo_id": "mlx-community/multilingual-e5-base-mlx",
+        "download_gb": 1.1,
+        "dimensions": 768,
+        "grade": "production",
+        "family": "local",
+        "label": "Multilingual E5 Base (로컬)",
+        "detail": "더 정확한 다국어 임베딩. 768차원이라 기존 색인은 다시 만들어야 합니다.",
+    },
+    "local:arctic-embed-l-v2": {
+        "id": "local:arctic-embed-l-v2",
+        "provider": "mlx",
+        "model": "mlx-community/snowflake-arctic-embed-l-v2.0-8bit",
+        "hf_repo_id": "mlx-community/snowflake-arctic-embed-l-v2.0-8bit",
+        "download_gb": 0.6,
+        "dimensions": 1024,
+        "grade": "production",
+        "family": "local",
+        "label": "Arctic Embed L v2 (로컬)",
+        "detail": "다국어 고품질 검색용 임베딩. 1024차원.",
+    },
     "local:bge-m3": {
         "id": "local:bge-m3",
         "provider": "mlx",

package/latticeai/core/embedding_providers/text.py

@@ -57,7 +57,32 @@ def _as_float_list(value: Any) -> List[Any]:
     return list(value)
 
 
+#: Longest token sequence an encoder-family embedding model accepts. BERT and
+#: XLM-R both stop at 512 including the two special tokens; a longer sequence
+#: is a hard failure inside the model, not a slow answer, so the ids are cut
+#: here rather than discovered at inference time.
+MLX_MAX_TOKENS = 512
+
+#: The E5 family was trained with these literal prefixes and loses accuracy
+#: without them. Keyed on the ``kind`` ``POST /worker/embed`` already sends.
+E5_PREFIXES: Dict[str, str] = {"query": "query: ", "passage": "passage: "}
+
+
+def _wants_e5_prefix(model: str) -> bool:
+    """Whether this model id names an E5-family checkpoint."""
+    return "e5" in str(model or "").lower()
+
+
 class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
+    """A local Apple-Silicon sentence embedder through ``mlx_embeddings``.
+
+    Nothing here reaches the network: the model must already be in the local
+    Hugging Face cache (that is exactly what
+    :func:`~.autodetect.detect_local_mlx` looks for). A missing package or a
+    missing snapshot is :class:`EmbeddingUnavailable`, which
+    :func:`resolve_embedder` turns into the honest hash fallback.
+    """
+
     provider = "mlx"
 
     def __init__(self, cfg: _RemoteConfig):
@@ -66,6 +91,7 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
             self.dim = _guess_dim(cfg.model, DEFAULT_EMBEDDING_DIM)
         self.model_id = f"mlx:{cfg.model}:{self.dim}"
         self._encoder: Optional[Tuple[str, Any, Any]] = None
+        self._prefixed = _wants_e5_prefix(cfg.model)
 
     def _load(self):
         if self._encoder is not None:
@@ -79,25 +105,37 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
         except Exception as exc:  # pragma: no cover - environment dependent
             raise EmbeddingUnavailable(f"MLX embedding model unavailable: {exc}") from exc
 
+    def embed_batch_for(
+        self, texts: Sequence[str], kind: str = "passage"
+    ) -> List[List[float]]:
+        """E5 asymmetry, honoured. Non-E5 models see the text unchanged."""
+        if not self._prefixed:
+            return self.embed_batch(texts)
+        prefix = E5_PREFIXES.get(str(kind or "passage").lower(), E5_PREFIXES["passage"])
+        return self.embed_batch([f"{prefix}{text}" for text in texts])
+
     def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
-        kind, model, tokenizer = self._load()
+        _, model, tokenizer = self._load()
         try:
             import mlx.core as mx  # type: ignore
 
             out: List[List[float]] = []
             for text in texts:
-                ids = tokenizer.encode(text)
-                tokens = mx.array([ids])
-                result = model(tokens)
-                pooled = result[0] if isinstance(result, (tuple, list)) else result
-                vec = mx.mean(pooled, axis=1)[0] if pooled.ndim == 3 else pooled[0]
-                out.append([float(x) for x in _as_float_list(vec.tolist())])
+                ids = list(tokenizer.encode(text))[:MLX_MAX_TOKENS]
+                result = model(mx.array([ids]))
+                out.append([float(x) for x in _pool(mx, result)])
             return out
         except EmbeddingUnavailable:
             raise
         except Exception as exc:  # pragma: no cover - environment dependent
             raise EmbeddingUnavailable(f"MLX embedding failed: {exc}") from exc
 
+    def metadata(self) -> Dict[str, Any]:
+        info = super().metadata()
+        info["instruction_prefixes"] = self._prefixed
+        info["max_tokens"] = MLX_MAX_TOKENS
+        return info
+
     def health(self) -> Dict[str, Any]:
         try:
             self._load()
@@ -106,6 +144,27 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
             return {"status": "unavailable", "detail": str(exc)}
 
 
+def _pool(mx: Any, result: Any) -> List[Any]:
+    """One sentence vector out of whatever shape the model handed back.
+
+    ``mlx_embeddings`` models return an output object carrying a pooled
+    ``text_embeds`` on newer versions and a bare hidden-state tensor on older
+    ones. Preferring the model's own pooled output matters: a checkpoint with a
+    trained pooler produces a better vector than a mean over its last layer,
+    and mean-pooling on top of an already-pooled row would be nonsense.
+    """
+    for attribute in ("text_embeds", "pooler_output"):
+        pooled = getattr(result, attribute, None)
+        if pooled is not None:
+            row = pooled[0] if pooled.ndim > 1 else pooled
+            return _as_float_list(row.tolist())
+    hidden = getattr(result, "last_hidden_state", None)
+    if hidden is None:
+        hidden = result[0] if isinstance(result, (tuple, list)) else result
+    row = mx.mean(hidden, axis=1)[0] if hidden.ndim == 3 else hidden[0]
+    return _as_float_list(row.tolist())
+
+
 class OllamaEmbeddingProvider(_NetworkEmbeddingProvider):
     provider = "ollama"
 
@@ -285,9 +344,13 @@ class ResolvedEmbedder:
     fell_back: bool
     health: Dict[str, Any]
     detail: str = ""
+    #: What :mod:`.autodetect` found on this machine, if anyone looked. It is
+    #: reported whether or not it was adopted, so a user running on the hash
+    #: fallback with a real embedder already downloaded can *see* that.
+    detected: Optional[Any] = None
 
     def as_dict(self) -> Dict[str, Any]:
-        return {
+        payload: Dict[str, Any] = {
             "requested_provider": self.requested,
             "active_provider": self.active,
             "fell_back": self.fell_back,
@@ -295,6 +358,9 @@ class ResolvedEmbedder:
             "detail": self.detail,
             **self.provider.metadata(),
         }
+        if self.detected is not None and hasattr(self.detected, "as_dict"):
+            payload["detected"] = self.detected.as_dict()
+        return payload
 
 
 def resolve_embedder(

package/latticeai/core/http_origin.py

@@ -18,9 +18,9 @@ Threat model, so the rule is checkable rather than felt:
   :mod:`latticeai.core.csrf` already trusts it.  Honouring a forwarded host from
   the same caller widens nothing that was not already open.
 * **Anyone else is not trusted.**  Off-loopback the header is honoured only from
-  a peer the operator listed in ``LATTICEAI_TRUSTED_PROXIES`` — the same
-  allowlist ``latticeai.core.security.client_ip`` uses for the same reason, and
-  empty by default.
+  a peer the operator listed in ``LATTICEAI_TRUSTED_PROXIES`` — the allowlist
+  ``latticeai.core.security.configure_trusted_proxies`` holds, mirrored by
+  ``lattice-auth`` at the front door for the same reason, and empty by default.
 
 The functions are pure: the caller supplies the headers and the peer address, so
 the policy is testable without an ASGI app or a socket.

package/latticeai/core/messages.py

@@ -181,11 +181,6 @@ MESSAGES: Dict[str, Dict[str, str]] = {
 }
 
 
-def bilingual(ko: str, en: str) -> Dict[str, str]:
-    """One Korean/English phrase pair, in the shape every caller renders."""
-    return {"ko": ko, "en": en}
-
-
 def resolve_language(request: Any, default: str = DEFAULT_LANGUAGE) -> str:
     """Language for this request: the product's choice, then the browser's.
 

package/latticeai/core/policy.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, Iterable, List, Set
+from typing import Dict, List, Set
 
 ROLE_CAPABILITIES: Dict[str, Set[str]] = {
     "owner": {"all"},
@@ -46,8 +46,3 @@ def role_has_capability(role: str, capability: str) -> bool:
 def require_capability(role: str, capability: str) -> None:
     if not role_has_capability(role, capability):
         raise PermissionError(f"role '{normalize_role(role)}' lacks capability '{capability}'")
-
-
-def policy_matrix(roles: Iterable[str] | None = None) -> List[Dict[str, object]]:
-    selected = list(roles or ROLE_CAPABILITIES.keys())
-    return [{"role": normalize_role(role), "caps": capabilities_for_role(role)} for role in selected]

package/latticeai/core/quiet.py

@@ -25,7 +25,6 @@ from __future__ import annotations
 
 import logging
 import sys
-import traceback
 from typing import Optional
 
 logger = logging.getLogger("latticeai.suppressed")
@@ -63,22 +62,4 @@ def quiet(reason: Optional[str] = None, *, level: int = logging.DEBUG) -> None:
         )
 
 
-def quiet_summary(reason: Optional[str] = None) -> str:
-    """One-line description of the live exception, for callers that report it."""
-    exc_type, exc, _ = sys.exc_info()
-    if exc is None:
-        return ""
-    name = getattr(exc_type, "__name__", "Exception")
-    text = str(exc).strip() or name
-    return f"{reason}: {text}" if reason else text
-
-
-def format_suppressed() -> str:
-    """Full traceback of the live exception as text (for diagnostics payloads)."""
-    exc_type, exc, tb = sys.exc_info()
-    if exc is None:
-        return ""
-    return "".join(traceback.format_exception(exc_type, exc, tb))
-
-
-__all__ = ["quiet", "quiet_summary", "format_suppressed"]
+__all__ = ["quiet"]