ltcai 11.2.0 → 11.4.0

package/latticeai/core/agent/verification.py

@@ -0,0 +1,231 @@
+"""VERIFY — the critic's verdict, and the facts that outrank it.
+
+Fail-closed by construction. A critic whose output cannot be parsed (after one
+strict repair retry) never fabricates a PASS; a PASS over a transcript with no
+execution evidence is not a completion; and a PASS that leaves a *requested
+file* unwritten is a fact, not a judgement, so it is enforced rather than
+merely reported back to the critic.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from latticeai.core.agent_helpers import (
+    _truncate_strings,
+    artifact_checklist,
+    extract_action_details,
+    format_artifact_checklist,
+    format_requirement_coverage,
+    requirement_coverage,
+)
+from latticeai.core.agent_state import AgentState
+
+from ._contract import AgentCore as _Core
+from .context import AgentRunContext
+
+
+class _VerificationMixin(_Core):
+    """The VERIFY phase of :class:`SingleAgentRuntime`."""
+
+    # ── VERIFY ───────────────────────────────────────────────────────
+    def _has_execution_evidence(self, ctx: AgentRunContext) -> bool:
+        """Deterministic evidence check: at least one executing step actually
+        produced a result (tool ran, or a governed change was staged as a
+        proposal). ``final``/parse-error/blocked steps carry no result and do
+        not count — a critic PASS over an evidence-free transcript must not
+        become DONE."""
+        for step in ctx.transcript:
+            if step.get("state") != AgentState.EXECUTING.value:
+                continue
+            if step.get("action") in (None, "final", "parse_error"):
+                continue
+            if isinstance(step.get("result"), dict):
+                return True
+        return False
+
+    async def verify(
+        self, ctx: AgentRunContext, req: Any, lang_hint: str, current_user: str,
+        max_retry: int = 3, model_id: Optional[str] = None,
+    ) -> None:
+        """VERIFYING: Critic role evaluates transcript → DONE / EXECUTING (retry) / ROLLBACK / NEEDS_REVIEW / FAILED.
+
+        Fail-closed: a critic whose output cannot be parsed (after one strict
+        repair retry) never fabricates a PASS — the run terminates as
+        NEEDS_REVIEW so the user is told to check the result themselves.
+        """
+        d = self.deps
+        # The critic must see every step (evidence completeness), but not
+        # every byte of tool output — long bodies are capped per string so
+        # verification stays affordable on long runs (review Wave 0.3).
+        verify_transcript = _truncate_strings(
+            ctx.transcript, self.transcript_budget.verify_chars
+        )
+        # Deterministic artifact facts (review L4): the critic sees the
+        # sanitize/repair honesty flags per written file, not just prose.
+        checklist = artifact_checklist(ctx.transcript, d.file_create_actions)
+        checklist_hint = (
+            f"\n\n{format_artifact_checklist(checklist)}" if checklist else ""
+        )
+        # Requirement coverage (review 루프 §2): the critic previously judged
+        # "did this fulfill the request?" from prose alone. It now also sees
+        # which requested files actually exist and which requirements the user
+        # spelled out.
+        coverage = requirement_coverage(
+            req.message, ctx.transcript, d.file_create_actions
+        )
+        context = (
+            f"{d.critic_prompt}\n\n"
+            f"[LANGUAGE HINT: {lang_hint}]\n\n"
+            f"Original request: {req.message}\n"
+            f"Plan goal: {ctx.plan.get('goal', req.message)}{checklist_hint}"
+            f"{format_requirement_coverage(coverage)}\n\n"
+            f"Full transcript:\n{json.dumps(verify_transcript, ensure_ascii=False, indent=2)}"
+        )
+        raw = await d.generate_as(
+            model_id,
+            message="Review the execution transcript and return your verdict JSON.",
+            context=context, max_tokens=self.phase_budgets.verify_tokens, temperature=0.1,
+        )
+        ctx.trace.llm_call("verify", model=model_id)
+        verdict: Optional[Dict[str, Any]] = None
+        try:
+            verdict, verdict_repairs = extract_action_details(str(raw))
+            ctx.trace.repair("verify", repairs=verdict_repairs)
+        except ValueError as exc:
+            # One strict repair retry — re-ask the critic for the exact wire
+            # format instead of fabricating a verdict.
+            ctx.trace.parse_error("verify", error=str(exc), recovered=True)
+            strict_context = (
+                f"{context}\n\n"
+                "Your previous verdict was not parseable JSON. Reply with EXACTLY one "
+                'JSON object like {"action": "verdict", "verdict": "PASS", '
+                '"next_state": "DONE", "reason": "...", "corrections": []} '
+                "and nothing else. verdict must be PASS or FAIL; next_state must be "
+                "one of DONE, EXECUTING, ROLLBACK, FAILED."
+            )
+            raw = await d.generate_as(
+                model_id,
+                message="Return your verdict as one strict JSON object.",
+                context=strict_context, max_tokens=self.phase_budgets.verify_tokens,
+                temperature=0.0,
+            )
+            ctx.trace.llm_call("verify", model=model_id)
+            try:
+                verdict, verdict_repairs = extract_action_details(str(raw))
+                ctx.trace.repair("verify", repairs=verdict_repairs)
+            except ValueError as retry_exc:
+                ctx.trace.parse_error("verify", error=str(retry_exc), recovered=False)
+                verdict = None
+
+        has_evidence = self._has_execution_evidence(ctx)
+
+        if verdict is None:
+            # Verifier unavailable — fail closed, never DONE.
+            ctx.transcript.append({
+                "state": AgentState.VERIFYING.value,
+                "verdict": "UNAVAILABLE",
+                "reason": "critic output unparseable after strict retry",
+                "verifier_available": False,
+                "verdict_valid": False,
+                "evidence": has_evidence,
+            })
+            ctx.trace.decision(
+                "verify", decision="verification_unavailable",
+                verifier_available=False, verdict_valid=False, evidence=has_evidence,
+            )
+            self._emit_step(ctx, "verify", "verdict", verdict="UNAVAILABLE")
+            ctx.final_message = (
+                "검증을 완료하지 못했습니다 — 검증 모델의 응답을 해석할 수 없었습니다. "
+                "실행 결과를 직접 확인해 주시고, 필요하면 다시 시도해 주세요."
+            )
+            ctx.state = AgentState.NEEDS_REVIEW
+            return
+
+        ctx.corrections = verdict.get("corrections", [])
+        # Normalize legacy verdict next_state strings to current AgentState names
+        raw_next = verdict.get("next_state", "")
+        next_s = {"COMPLETE": "DONE", "RETRY": "EXECUTING"}.get(raw_next, raw_next)
+
+        ctx.transcript.append({
+            "state": AgentState.VERIFYING.value,
+            "verdict":     verdict.get("verdict", ""),
+            "reason":      verdict.get("reason", ""),
+            "corrections": ctx.corrections,
+            "confidence":  verdict.get("confidence", 0.9),
+            "next_state":  next_s,
+            "verifier_available": True,
+            "verdict_valid": True,
+            "evidence": has_evidence,
+        })
+
+        ctx.trace.decision(
+            "verify", decision=str(verdict.get("verdict", "")), next_state=next_s,
+            verifier_available=True, verdict_valid=True, evidence=has_evidence,
+        )
+        self._emit_step(
+            ctx, "verify", "verdict",
+            verdict=str(verdict.get("verdict", "")), next_state=next_s,
+        )
+        if verdict.get("verdict") == "PASS":
+            # DONE requires both: a validly parsed PASS verdict AND
+            # deterministic execution evidence in the transcript. A PASS over
+            # an evidence-free run is not a completion.
+            if not has_evidence:
+                ctx.trace.decision("verify", decision="needs_review_no_evidence")
+                ctx.final_message = (
+                    "검증자는 통과를 보고했지만 실제 실행 근거(도구 실행 기록)가 없어 "
+                    "완료로 처리하지 않았습니다. 결과를 직접 확인해 주세요."
+                )
+                ctx.state = AgentState.NEEDS_REVIEW
+                return
+            if not coverage["complete"]:
+                # A PASS that leaves a *requested file* unwritten is not a
+                # completion — this is a fact, not a judgement, so it is
+                # enforced rather than merely reported to the critic.
+                missing = ", ".join(coverage["missing_files"])
+                ctx.trace.decision(
+                    "verify", decision="needs_review_missing_files",
+                    missing=len(coverage["missing_files"]),
+                )
+                ctx.transcript.append({
+                    "state": AgentState.VERIFYING.value,
+                    "requirement_coverage": coverage,
+                })
+                ctx.final_message = (
+                    f"요청한 파일 중 일부가 만들어지지 않아 완료로 처리하지 않았습니다: {missing}"
+                )
+                ctx.state = AgentState.NEEDS_REVIEW
+                return
+            if not ctx.final_message:
+                ctx.final_message = verdict.get("reason", "작업이 완료되었습니다.")
+            ctx.state = AgentState.DONE
+        elif next_s == "ROLLBACK":
+            ctx.state = AgentState.ROLLBACK
+        elif next_s == "EXECUTING":
+            if ctx.retry_count >= max_retry:
+                ctx.final_message = "처리 중 문제가 발생했습니다. 다시 시도해 주세요."
+                ctx.state = AgentState.FAILED
+            else:
+                ctx.retry_count += 1
+                ctx.trace.retry("verify", attempt=ctx.retry_count)
+                ctx.transcript.append({
+                    "state": AgentState.EXECUTING.value,
+                    "retry_attempt": ctx.retry_count,
+                    "corrections": ctx.corrections,
+                })
+                ctx.state = AgentState.EXECUTING
+        elif next_s == "DONE":
+            # Contradictory verdict: the critic asked for DONE without a PASS.
+            # The loose "or next_state == DONE" success path is gone — this is
+            # a non-success that the user must review.
+            ctx.trace.decision("verify", decision="needs_review_inconsistent_verdict")
+            ctx.final_message = (
+                "검증 결과가 일관되지 않아 완료로 처리하지 않았습니다. "
+                "실행 결과를 직접 확인해 주세요."
+            )
+            ctx.state = AgentState.NEEDS_REVIEW
+        else:
+            ctx.final_message = verdict.get("reason", "검증자가 인식되지 않은 다음 상태를 반환했습니다.")
+            ctx.state = AgentState.FAILED

package/latticeai/core/embedding_providers/__init__.py

@@ -0,0 +1,151 @@
+"""Provider-backed embeddings for Lattice AI retrieval.
+
+The knowledge graph stores dense vectors keyed by ``(embedding_model,
+embedding_dim)`` and only ever compares vectors that share those keys
+(``knowledge_graph.vector_search``). That contract means the *embedder* can be
+swapped behind a single interface as long as every implementation agrees on:
+
+* ``model_id`` / ``dim`` — the index identity (a change forces a re-index, which
+  ``index_status`` already reports as ``stale``/``needs_reindex``);
+* ``encode`` / ``decode`` — the on-disk float32 codec (shared by all providers);
+* ``embed`` returns an **L2-normalized** vector, so ``similarity`` is a plain dot
+  product and equals cosine similarity regardless of provider.
+
+:mod:`.base` defines that :class:`EmbeddingProvider` interface; :mod:`.text`
+holds the five concrete text implementations:
+
+1. :class:`HashEmbeddingProvider`  — deterministic, offline, always-available
+   fallback (wraps the legacy :class:`~latticeai.core.local_embeddings.LocalEmbeddingModel`).
+2. :class:`MLXEmbeddingProvider`   — local Apple-Silicon embedding models.
+3. :class:`OllamaEmbeddingProvider` — a local/remote Ollama server.
+4. :class:`OpenAICompatibleEmbeddingProvider` — any ``/v1/embeddings`` endpoint
+   (OpenAI, LM Studio, vLLM, llama.cpp, Together, …).
+5. :class:`CustomEmbeddingProvider` — a user-supplied dotted callable.
+
+:func:`resolve_embedder` builds the configured provider and, when that provider
+is unavailable, degrades to the hash fallback while *reporting* the requested
+vs. active provider — nothing is silently faked. :mod:`.profiles` is the named
+list of supported provider/model/dimension combinations the setup surfaces
+offer.
+
+Vision seam (v11.1.0, Track 3)
+------------------------------
+Images join the same contract through :class:`VisionEmbeddingProvider` in
+:mod:`.vision`, with two deliberate differences from the text side:
+
+* **No fallback.** The hash embedder turns *text* into a real, if crude, cosine
+  signal. There is no equivalent for pixels: hashing a file path produces a
+  vector that says nothing about the picture, so an unavailable vision model is
+  reported as unavailable (:class:`EmbeddingUnavailable` /
+  ``ResolvedVisionEmbedder.available == False``) and the caller skips the
+  embedding instead of storing a decoy.
+* **A separate space by default.** A CLIP-family image vector is not comparable
+  with a BGE text vector, so ``space == "image"`` means "index these apart and
+  join them by late fusion". Only a genuinely shared-space model may declare
+  ``space == "shared"`` (opt-in), and only then can a *text* query be scored
+  against image vectors.
+
+:class:`VisionCaptioner` in :mod:`.captions` is the matching seam for
+descriptions. Its default implementation returns ``None``: a caption is what a
+vision-language model said about an image, so with no VLM loaded there is no
+caption — never a sentence assembled from the filename and passed off as one.
+
+Split into these submodules in v11.3.0 with no behaviour change. Every name the
+single module exposed still resolves from
+``latticeai.core.embedding_providers``.
+
+Stubbing note: a name rebound *here* changes only this module's binding — the
+submodule that calls it holds its own, so a test standing in for a helper
+patches the submodule that reads it.
+"""
+
+from __future__ import annotations
+
+# The single module had no ``__all__`` restriction on what callers could reach:
+# the two names it imported for its own use were part of its surface, and the
+# suite imports them from here. Re-exported in the redundant-alias form so they
+# read as deliberate rather than as leftover imports.
+from latticeai.core.local_embeddings import (
+    DEFAULT_EMBEDDING_DIM as DEFAULT_EMBEDDING_DIM,
+)
+from latticeai.core.local_embeddings import LocalEmbeddingModel as LocalEmbeddingModel
+
+from .base import _KNOWN_DIMS as _KNOWN_DIMS
+from .base import EmbeddingProvider as EmbeddingProvider
+from .base import EmbeddingUnavailable as EmbeddingUnavailable
+from .base import _guess_dim as _guess_dim
+from .base import _l2_normalize as _l2_normalize
+from .base import _load_dotted as _load_dotted
+from .base import _NetworkEmbeddingProvider as _NetworkEmbeddingProvider
+from .base import _RemoteConfig as _RemoteConfig
+from .captions import DEFAULT_CAPTION_PROMPT as DEFAULT_CAPTION_PROMPT
+from .captions import VISION_CAPTION_TARGET_ENV as VISION_CAPTION_TARGET_ENV
+from .captions import CustomVisionCaptioner as CustomVisionCaptioner
+from .captions import MLXVisionCaptioner as MLXVisionCaptioner
+from .captions import VisionCaptioner as VisionCaptioner
+from .captions import resolve_vision_captioner as resolve_vision_captioner
+from .captions import vision_caption_port as vision_caption_port
+from .profiles import PRODUCTION_PROVIDER_PROFILES as PRODUCTION_PROVIDER_PROFILES
+from .profiles import embedding_provider_profiles as embedding_provider_profiles
+from .profiles import resolve_embedding_profile as resolve_embedding_profile
+from .text import PROVIDER_TYPES as PROVIDER_TYPES
+from .text import CustomEmbeddingProvider as CustomEmbeddingProvider
+from .text import HashEmbeddingProvider as HashEmbeddingProvider
+from .text import MLXEmbeddingProvider as MLXEmbeddingProvider
+from .text import OllamaEmbeddingProvider as OllamaEmbeddingProvider
+from .text import OpenAICompatibleEmbeddingProvider as OpenAICompatibleEmbeddingProvider
+from .text import ResolvedEmbedder as ResolvedEmbedder
+from .text import _as_float_list as _as_float_list
+from .text import build_embedding_provider as build_embedding_provider
+from .text import resolve_embedder as resolve_embedder
+from .vision import _KNOWN_VISION_DIMS as _KNOWN_VISION_DIMS
+from .vision import DEFAULT_VISION_DIM as DEFAULT_VISION_DIM
+from .vision import VISION_PROVIDER_TYPES as VISION_PROVIDER_TYPES
+from .vision import VISION_SPACE_IMAGE as VISION_SPACE_IMAGE
+from .vision import VISION_SPACE_SHARED as VISION_SPACE_SHARED
+from .vision import VISION_SPACES as VISION_SPACES
+from .vision import VISION_TARGET_ENV as VISION_TARGET_ENV
+from .vision import CustomVisionEmbeddingProvider as CustomVisionEmbeddingProvider
+from .vision import MLXVisionEmbeddingProvider as MLXVisionEmbeddingProvider
+from .vision import ResolvedVisionEmbedder as ResolvedVisionEmbedder
+from .vision import VisionEmbeddingProvider as VisionEmbeddingProvider
+from .vision import _guess_vision_dim as _guess_vision_dim
+from .vision import _normalize_space as _normalize_space
+from .vision import build_vision_provider as build_vision_provider
+from .vision import resolve_vision_embedder as resolve_vision_embedder
+
+__all__ = [
+    "DEFAULT_CAPTION_PROMPT",
+    "DEFAULT_VISION_DIM",
+    "VISION_CAPTION_TARGET_ENV",
+    "VISION_PROVIDER_TYPES",
+    "VISION_SPACES",
+    "VISION_SPACE_IMAGE",
+    "VISION_SPACE_SHARED",
+    "VISION_TARGET_ENV",
+    "CustomVisionCaptioner",
+    "CustomVisionEmbeddingProvider",
+    "EmbeddingProvider",
+    "EmbeddingUnavailable",
+    "MLXVisionCaptioner",
+    "MLXVisionEmbeddingProvider",
+    "ResolvedVisionEmbedder",
+    "VisionCaptioner",
+    "VisionEmbeddingProvider",
+    "build_vision_provider",
+    "resolve_vision_captioner",
+    "resolve_vision_embedder",
+    "vision_caption_port",
+    "HashEmbeddingProvider",
+    "MLXEmbeddingProvider",
+    "OllamaEmbeddingProvider",
+    "OpenAICompatibleEmbeddingProvider",
+    "CustomEmbeddingProvider",
+    "ResolvedEmbedder",
+    "build_embedding_provider",
+    "resolve_embedder",
+    "resolve_embedding_profile",
+    "embedding_provider_profiles",
+    "PRODUCTION_PROVIDER_PROFILES",
+    "PROVIDER_TYPES",
+]

package/latticeai/core/embedding_providers/base.py

@@ -0,0 +1,199 @@
+"""The contract every embedder implements, and the machinery they share.
+
+``EmbeddingProvider`` is the interface: set ``model_id`` and ``dim``, implement
+``embed_batch``, and inherit the float32 codec plus the dot-product similarity
+that equals cosine because every ``embed`` returns an L2-normalized vector.
+``_NetworkEmbeddingProvider`` adds what any provider that calls a model or a
+server needs — input clamping, normalization, and locking the index identity to
+the width the model actually returned.
+
+Nothing here reaches a network or a model; the concrete providers in
+:mod:`.text` and :mod:`.vision` do.
+"""
+
+from __future__ import annotations
+
+import importlib
+import math
+import struct
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence
+
+from latticeai.core.local_embeddings import DEFAULT_EMBEDDING_DIM
+
+
+class EmbeddingUnavailable(RuntimeError):
+    """Raised when a configured provider cannot produce an embedding.
+
+    Callers in the hot path (``vector_search``) translate this into a clear
+    503/"provider unavailable" rather than a misleading empty result.
+    """
+
+
+# Best-known output dimensionality for common embedding models, so the index
+# identity is stable before the first (possibly remote) call. A configured
+# ``dim`` always wins; an unknown model falls back to a one-time live probe.
+_KNOWN_DIMS = {
+    "bge-m3": 1024,
+    "nomic-embed-text": 768,
+    "mxbai-embed-large": 1024,
+    "all-minilm": 384,
+    "all-minilm-l6-v2": 384,
+    "bge-small-en": 384,
+    "bge-base-en": 768,
+    "bge-large-en": 1024,
+    "gte-small": 384,
+    "gte-base": 768,
+    "gte-large": 1024,
+    "e5-large": 1024,
+    "multilingual-e5-large": 1024,
+    "text-embedding-3-small": 1536,
+    "text-embedding-3-large": 3072,
+    "text-embedding-ada-002": 1536,
+}
+
+
+def _guess_dim(model: str, default: int) -> int:
+    key = str(model or "").split("/")[-1].strip().lower()
+    key = key.split(":")[0]
+    return _KNOWN_DIMS.get(key, default)
+
+
+def _l2_normalize(vector: Sequence[float]) -> List[float]:
+    norm = math.sqrt(sum(float(v) * float(v) for v in vector))
+    if norm <= 0:
+        return [float(v) for v in vector]
+    return [float(v) / norm for v in vector]
+
+
+class EmbeddingProvider:
+    """Interface every embedder implements.
+
+    Subclasses must set ``model_id`` and ``dim`` and implement
+    :meth:`embed_batch`; the rest (single embed, codec, similarity) is shared.
+    """
+
+    #: stable identity stored alongside every vector — change ⇒ re-index
+    model_id: str = ""
+    #: vector dimensionality
+    dim: int = DEFAULT_EMBEDDING_DIM
+    #: short provider kind ("hash" | "mlx" | "ollama" | "openai" | "custom")
+    provider: str = "hash"
+    #: "fallback" (hash) | "production" (real semantic model)
+    grade: str = "production"
+
+    # ── required ──────────────────────────────────────────────────────────
+    def embed_batch(self, texts: Sequence[str]) -> List[List[float]]:
+        raise NotImplementedError
+
+    # ── derived (shared) ──────────────────────────────────────────────────
+    def _model_id_with_dim(self, dim: int) -> str:
+        """This provider's ``model_id`` restated at ``dim``.
+
+        Every provider spells its identity ``<kind>:<model>:<dim>``, so the
+        numeric tail is what moves when a live call reveals the model's true
+        width. An id without such a tail does not encode a dimension and is
+        returned unchanged — the index keys on ``model_id`` *and* ``dim``, so
+        nothing becomes ambiguous.
+        """
+        head, sep, tail = self.model_id.rpartition(":")
+        if sep and tail.isdigit():
+            return f"{head}:{dim}"
+        return self.model_id
+
+    def embed(self, text: str) -> List[float]:
+        result = self.embed_batch([text])
+        return result[0] if result else [0.0] * self.dim
+
+    def encode(self, vector: Iterable[float]) -> bytes:
+        values = [float(v) for v in vector]
+        return struct.pack(f"<{len(values)}f", *values)
+
+    def decode(self, payload: bytes, dim: Optional[int] = None) -> List[float]:
+        if not payload:
+            return []
+        count = int(dim or self.dim)
+        if len(payload) != count * 4:
+            count = len(payload) // 4
+        return list(struct.unpack(f"<{count}f", payload[: count * 4]))
+
+    def similarity(self, left: Iterable[float], right: Iterable[float]) -> float:
+        # strict=True: a dimension mismatch means the two vectors came from
+        # different embedding models. Truncating to the shorter one produces a
+        # plausible-looking similarity that is meaningless — exactly the silent
+        # wrongness this codebase keeps finding. Callers that can hit a model
+        # swap already handle failure and fall back to lexical search.
+        left_v, right_v = list(left), list(right)
+        if len(left_v) != len(right_v):
+            raise ValueError(
+                f"embedding dimension mismatch: {len(left_v)} vs {len(right_v)}; "
+                "the vector index was built with a different model"
+            )
+        return float(sum(a * b for a, b in zip(left_v, right_v, strict=True)))
+
+    # ── observability ─────────────────────────────────────────────────────
+    def health(self) -> Dict[str, Any]:
+        """Return ``{status, detail}``; status ∈ ok | unavailable."""
+        return {"status": "ok", "detail": "ready"}
+
+    def metadata(self) -> Dict[str, Any]:
+        return {
+            "provider": self.provider,
+            "model": self.model_id,
+            "model_id": self.model_id,
+            "dim": self.dim,
+            "grade": self.grade,
+        }
+
+
+@dataclass
+class _RemoteConfig:
+    model: str
+    base_url: str = ""
+    api_key: str = ""
+    dim: int = DEFAULT_EMBEDDING_DIM
+    timeout: float = 30.0
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+class _NetworkEmbeddingProvider(EmbeddingProvider):
+    """Common machinery for providers that call a model/server to embed."""
+
+    def __init__(self, cfg: _RemoteConfig):
+        self._cfg = cfg
+        self.dim = int(cfg.dim or DEFAULT_EMBEDDING_DIM)
+
+    # subclasses implement the raw call
+    def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        raise NotImplementedError
+
+    def embed_batch(self, texts: Sequence[str]) -> List[List[float]]:
+        clean = [str(t or "")[:50_000] for t in texts]
+        if not clean:
+            return []
+        vectors = self._embed_raw(clean)
+        out: List[List[float]] = []
+        for vec in vectors:
+            vec = [float(x) for x in (vec or [])]
+            if vec:
+                # lock the index identity to the true model dimensionality —
+                # the id carries that dimension, so it moves with it or the
+                # vectors end up filed under a width they do not have
+                self.dim = len(vec)
+                self.model_id = self._model_id_with_dim(self.dim)
+            out.append(_l2_normalize(vec) if vec else [0.0] * self.dim)
+        return out
+
+
+def _load_dotted(ref: str, env_name: str, label: str) -> Callable[..., Any]:
+    """Import ``module:callable`` (or ``module.callable``) or explain why not."""
+    if not ref:
+        raise EmbeddingUnavailable(f"{label} target not configured ({env_name})")
+    module_name, _, attr = ref.replace(":", ".").rpartition(".")
+    if not module_name:
+        raise EmbeddingUnavailable(f"invalid {label} target: {ref}")
+    try:
+        module = importlib.import_module(module_name)
+        return getattr(module, attr)  # type: ignore[no-any-return]
+    except Exception as exc:
+        raise EmbeddingUnavailable(f"{label} target unavailable: {exc}") from exc