ltcai 11.9.0 → 12.0.0

package/lattice_brain/graph/_kg_common/sections.py

@@ -0,0 +1,107 @@
+"""Heading paths for a document, so a fact can say *where* it came from.
+
+The typed chunker already computes a `" > "`-joined heading path per chunk and
+files it on the Chunk node (`heading_path`). Extraction ran on the whole
+document text and had no idea which section a sentence sat in, so an edge could
+say "이 문장이 근거다" but never "그 문장은 「아키텍처 > 저장소」 절에 있다".
+
+This module closes that gap with the *same* rule the chunker uses — a line
+matching `^#{1,6} ` opens a section — so the heading a triple names and the
+heading its chunk carries are the same string.
+
+Character offsets throughout, because Python slices `str` by code point and the
+rest of the pipeline (chunk `start_char`, the Rust port) does too.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Sequence, Tuple
+
+#: `^(#{1,6}) (.*)$` under `re.MULTILINE` — the chunker's heading rule.
+_HEADING = re.compile(r"^(#{1,6}) (.*)$", re.MULTILINE)
+
+#: `(start, end, heading_path)`; `end` is exclusive.
+Span = Tuple[int, int, str]
+
+
+def heading_spans(text: str) -> List[Span]:
+    """Every heading's span and its `" > "`-joined path, in document order.
+
+    Text before the first heading belongs to no section and is deliberately
+    absent from the result — an honest "no heading" beats inventing one from
+    the filename.
+
+    >>> heading_spans("# A\\nintro\\n## B\\nbody")
+    [(0, 12, 'A'), (12, 20, 'A > B')]
+    """
+    matches = list(_HEADING.finditer(text or ""))
+    spans: List[Span] = []
+    stack: List[Tuple[int, str]] = []
+    for index, match in enumerate(matches):
+        level = len(match.group(1))
+        title = match.group(2).strip()
+        while stack and stack[-1][0] >= level:
+            stack.pop()
+        stack.append((level, title))
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
+        spans.append((match.start(), end, " > ".join(part for _, part in stack)))
+    return spans
+
+
+def heading_at(spans: Sequence[Span], offset: int) -> str:
+    """The heading path covering ``offset``, or `""` when there is none."""
+    for start, end, path in spans:
+        if start <= offset < end:
+            return path
+    return ""
+
+
+def with_section(context: str, section: str) -> str:
+    """``context`` prefixed with the section it came from, when there is one.
+
+    ``"[아키텍처 > 저장소] 쓰기는 GraphWriter가 담당한다."`` — one string,
+    because `TripleSpec.context` is the only free-text channel an extracted
+    edge has. Blank sections leave the context untouched rather than adding an
+    empty bracket.
+    """
+    section = (section or "").strip()
+    if not section:
+        return context
+    return f"[{section}] {context}"
+
+
+def sentence_offsets(text: str, pattern: "re.Pattern[str]") -> List[Tuple[int, str]]:
+    """``(offset, sentence)`` for a split that keeps each piece's position.
+
+    ``re.split`` throws the offsets away, and the offset is exactly what maps a
+    sentence back to its heading. Walking the separators keeps both.
+    """
+    out: List[Tuple[int, str]] = []
+    cursor = 0
+    for match in pattern.finditer(text or ""):
+        out.append((cursor, text[cursor : match.start()]))
+        cursor = match.end()
+    out.append((cursor, (text or "")[cursor:]))
+    return out
+
+
+def leading_offset(raw: str, stripped: str) -> Optional[int]:
+    """How many characters ``str.strip()`` removed from the front of ``raw``.
+
+    ``None`` when ``stripped`` is empty — there is no position to report for a
+    piece that stripped away entirely.
+    """
+    if not stripped:
+        return None
+    return raw.index(stripped)
+
+
+__all__ = [
+    "Span",
+    "heading_at",
+    "heading_spans",
+    "leading_offset",
+    "sentence_offsets",
+    "with_section",
+]

package/lattice_brain/graph/_kg_constants.py

@@ -28,6 +28,13 @@ LOCAL_CODE_EXTENSIONS = {
     ".tsx",
     ".jsx",
     ".html",
+    # v12.0.0: `.htm` sat beside `.html` in every other table (the chunker's
+    # prose list, the parser matrix) and was missing only here, so a folder of
+    # `.htm` pages was scanned past in silence. `.rs` was missing outright —
+    # this repository's own Rust half was invisible to its own folder ingest.
+    ".htm",
+    ".rs",
+    ".go",
     ".css",
     ".json",
     ".yaml",

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "11.9.0"
+__version__ = "12.0.0"

package/latticeai/api/agent_worker_seam.py

@@ -81,6 +81,13 @@ MAX_TEMPERATURE = 2.0
 #: How many stop strings one completion may name. The kernel sends two.
 MAX_STOP_STRINGS = 8
 
+#: Longest forced completion prefix one call may name (v12.0.0). The prefix is
+#: prepended to the prompt, so an unbounded one is an unbounded prompt. The
+#: kernel sends two, and both are short: the executor's opening brace
+#: (``{"thoughts": "``) and the guided menu's answer label — a few dozen
+#: characters between them, and nothing legitimate needs a paragraph.
+MAX_PREFIX_CHARS = 256
+
 #: Rate-limit bucket. Deliberately *not* the ``"agent"`` bucket ``/agent`` uses:
 #: that one is sized per *run* (10 burst, one refill per 10s) because one HTTP
 #: call there is a whole agent run. Here one call is a single loop step, and a
@@ -111,6 +118,19 @@ class AgentLLMRequest(BaseModel):
     #: truncate any reply carrying file content. Bounded so a caller cannot make
     #: the sampler check a thousand needles per token.
     stop: Optional[List[str]] = Field(default=None, max_length=MAX_STOP_STRINGS)
+    #: Characters the reply is **forced to begin with** (v12.0.0).
+    #:
+    #: The cheapest structural guarantee the seam can offer: instead of asking
+    #: a weak model to start at ``{`` and repairing the markdown fence it emits
+    #: instead, the worker prefills those characters and the model continues
+    #: from them. The response's ``text`` always starts with the prefix, so a
+    #: caller reads one shape whether the local prefill or a cloud provider's
+    #: assistant-prefill message produced it.
+    #:
+    #: Bounded because it is prepended to the prompt: an unbounded prefix would
+    #: be an unbounded prompt on the single MLX executor. The kernel sends
+    #: fourteen characters.
+    prefix: Optional[str] = Field(default=None, max_length=MAX_PREFIX_CHARS)
 
 
 class AgentToolRequest(BaseModel):
@@ -258,6 +278,17 @@ def create_agent_worker_seam_router(
             max_tokens=req.max_tokens,
             temperature=req.temperature,
             stop=req.stop or None,
+            prefix=req.prefix or None,
+            # **The seam's ``context`` is a prompt, not a corpus** (v12.0.0).
+            # ``_compose_system`` appends the citation mandate to any non-empty
+            # context, which is right for chat (where it really is retrieved
+            # passages) and wrong here: the Rust kernel sends its whole executor
+            # prompt as ``context``, so every agent turn was being told its own
+            # instructions were sources to "cite inline as [1], [2]". Small
+            # models obey that — a 0.5B wrote ``[1] …`` into a file and a 2B
+            # answered a tool call with the citation instruction. A caller that
+            # wants citations puts them in its own prompt.
+            cite_sources=False,
         )
         return {"text": str(text)}
 
@@ -316,6 +347,7 @@ def create_agent_worker_seam_router(
 
 __all__ = [
     "MAX_MAX_TOKENS",
+    "MAX_PREFIX_CHARS",
     "MAX_TEMPERATURE",
     "MIN_MAX_TOKENS",
     "MIN_TEMPERATURE",

package/latticeai/api/worker_compute.py

@@ -19,7 +19,7 @@ here opens a database, writes a file, or reaches a store. Each handler is a
 function of its request body, so a caller can retry it, cache it, or run two of
 them at once without asking who else is writing.
 
-The eight seams, and what each was extracted from:
+The nine seams, and what each was extracted from:
 
 ``POST /worker/embed``
     ``EmbeddingProvider.embed_batch`` on the *resolved* provider — the same
@@ -53,6 +53,12 @@ The eight seams, and what each was extracted from:
     consume, already classified. Rust writes the Concept/Task/Decision subgraph;
     this seam never opens a store.
 
+``POST /worker/vector/query``
+    Approximate nearest-neighbour over the ``.hnsw`` sidecar next to the
+    brain database. The one compute seam that *reads* the store (row count
+    + embeddings, never a write) so it can refresh the sidecar and say
+    ``index: "none"`` when there is nothing to serve.
+
 Gating is the seam gate the rest of the worker uses — ``LATTICEAI_AGENT_TOOL_SEAM``
 read per request through :func:`latticeai.api.agent_worker_seam._seam_open`,
 then ``require_user`` and the ``agent_seam`` rate bucket. Off ⇒ 404. Mounted
@@ -108,6 +114,12 @@ EXTRACT_LIMITS: Dict[str, int] = {"message": 12, "document": 15}
 #: write-side module would tie this compute seam to a module W1 is replacing.
 PASSAGE_MAX_CHARS = 50_000
 
+#: Upper bound on ``texts`` for one ``POST /worker/embed``. Ingest already
+#: batches; a caller that dumps a whole vault into one request is a bug, not
+#: a use case. 256 sits in the 128–256 band G-RAG-A recommended. Additive:
+#: the request/response shape is unchanged.
+EMBED_MAX_BATCH = 256
+
 #: The CJK-capable fonts ``create_pdf`` looks for, as a module attribute so a
 #: test can point the probe at a font that exists (and at one that does not)
 #: instead of asserting whatever the host machine happens to have installed.
@@ -154,6 +166,14 @@ WORKER_COMPUTE_MESSAGES: Dict[str, Dict[str, str]] = {
         "ko": "'{kind}' 은(는) 추출 종류가 아닙니다. {allowed} 중 하나여야 합니다.",
         "en": "'{kind}' is not an extraction kind. Use one of {allowed}.",
     },
+    "worker_compute.embed_batch_too_large": {
+        "ko": "임베딩 배치가 {count}개입니다. 한 번에 {limit}개까지입니다.",
+        "en": "The embed batch has {count} texts; the limit is {limit}.",
+    },
+    "worker_compute.vector_query_invalid": {
+        "ko": "벡터 질의는 embedding_model, embedding_dim, vector 가 필요합니다.",
+        "en": "A vector query needs embedding_model, embedding_dim, and vector.",
+    },
 }
 
 
@@ -436,6 +456,16 @@ class ExtractRequest(BaseModel):
     kind: str = "message"
 
 
+class VectorQueryRequest(BaseModel):
+    """Approximate neighbours from the HNSW sidecar. ``k`` is capped at 200."""
+
+    workspace: Optional[str] = None
+    embedding_model: str
+    embedding_dim: int
+    vector: List[float] = Field(default_factory=list)
+    k: int = 10
+
+
 def build_extract_reply(text: str, kind: str) -> Dict[str, Any]:
     """The structures ``ingest_message`` / ``ingest_document`` / ``ingest_source`` consume.
 
@@ -490,8 +520,9 @@ def create_worker_compute_router(
     transcriber: Optional[Callable[[str], str]] = None,
     require_user: Callable[[Request], Any],
     enforce_rate_limit: Callable[[str, str], None],
+    db_path: Any = None,
 ) -> APIRouter:
-    """The eight compute seams, wired to what this worker actually resolved.
+    """The nine compute seams, wired to what this worker actually resolved.
 
     ``embedder`` is the :class:`~latticeai.core.embedding_providers.text.ResolvedEmbedder`
     ``phase_brain`` built (``None`` ⇒ 503, because a worker with no embedder is
@@ -580,15 +611,37 @@ def create_worker_compute_router(
             )
         provider = embedder.provider
         texts = list(req.texts)
+        if len(texts) > EMBED_MAX_BATCH:
+            raise http_error(
+                422,
+                "worker_compute.embed_batch_too_large",
+                language,
+                count=str(len(texts)),
+                limit=str(EMBED_MAX_BATCH),
+            )
         if kind == "passage":
             texts = [text[:PASSAGE_MAX_CHARS] for text in texts]
-        vectors = await asyncio.to_thread(provider.embed_batch, texts)
+        # `embed_batch_for` rather than `embed_batch`: an asymmetric model (the
+        # E5 family) needs to know whether this text is the question or the
+        # answer, and `kind` is exactly that. Symmetric providers ignore it.
+        # Resolved by name because the embedder arrives injected: a stand-in
+        # that predates the role-aware method still embeds, it just cannot be
+        # told which role it is embedding for.
+        role_aware = getattr(provider, "embed_batch_for", None)
+        vectors = (
+            await asyncio.to_thread(role_aware, texts, kind)
+            if callable(role_aware)
+            else await asyncio.to_thread(provider.embed_batch, texts)
+        )
         return {
             "vectors": vectors,
             "dim": provider.dim,
             "provider": embedder.active,
             "model_id": provider.model_id,
             "kind": kind,
+            # Additive (v12.0.0): `fallback` means these vectors are feature
+            # hashes, not meaning. A caller that stores them can say so.
+            "grade": getattr(provider, "grade", "fallback"),
         }
 
     @router.post("/worker/parse")
@@ -758,12 +811,33 @@ def create_worker_compute_router(
             )
         return await asyncio.to_thread(build_extract_reply, req.text, kind)
 
+    @router.post("/worker/vector/query")
+    async def worker_vector_query(req: VectorQueryRequest, request: Request):
+        """Top-k ids from the HNSW sidecar, or ``index: "none"`` honestly."""
+        _require_seam(request)
+        _admit(request)
+        language = resolve_language(request)
+        if not req.embedding_model or req.embedding_dim <= 0 or not req.vector:
+            raise http_error(422, "worker_compute.vector_query_invalid", language)
+        from latticeai.core.vector_index import query_sidecar
+
+        return await asyncio.to_thread(
+            query_sidecar,
+            workspace=req.workspace,
+            embedding_model=req.embedding_model,
+            embedding_dim=req.embedding_dim,
+            vector=req.vector,
+            k=req.k,
+            db_path=db_path,
+        )
+
     return router
 
 
 __all__ = [
     "CJK_FONT_CANDIDATES",
     "EMBED_KINDS",
+    "EMBED_MAX_BATCH",
     "EXTRACT_KINDS",
     "EXTRACT_LIMITS",
     "PASSAGE_MAX_CHARS",
@@ -772,6 +846,7 @@ __all__ = [
     "EmbedRequest",
     "ExtractRequest",
     "ParseRequest",
+    "VectorQueryRequest",
     "RenderDocxRequest",
     "RenderPdfRequest",
     "RenderPptxRequest",

package/latticeai/core/embedding_providers/__init__.py

@@ -68,6 +68,14 @@ from __future__ import annotations
 from lattice_brain.embeddings import DEFAULT_EMBEDDING_DIM as DEFAULT_EMBEDDING_DIM
 from lattice_brain.embeddings import LocalEmbeddingModel as LocalEmbeddingModel
 
+from .autodetect import AUTO_PROVIDER as AUTO_PROVIDER
+from .autodetect import AUTODETECT_ENV as AUTODETECT_ENV
+from .autodetect import LOCAL_MLX_MODELS as LOCAL_MLX_MODELS
+from .autodetect import Detection as Detection
+from .autodetect import detect_embedder as detect_embedder
+from .autodetect import detect_local_mlx as detect_local_mlx
+from .autodetect import detect_ollama as detect_ollama
+from .autodetect import resolve_auto_provider as resolve_auto_provider
 from .base import _KNOWN_DIMS as _KNOWN_DIMS
 from .base import EmbeddingProvider as EmbeddingProvider
 from .base import EmbeddingUnavailable as EmbeddingUnavailable
@@ -113,6 +121,14 @@ from .vision import build_vision_provider as build_vision_provider
 from .vision import resolve_vision_embedder as resolve_vision_embedder
 
 __all__ = [
+    "AUTODETECT_ENV",
+    "AUTO_PROVIDER",
+    "LOCAL_MLX_MODELS",
+    "Detection",
+    "detect_embedder",
+    "detect_local_mlx",
+    "detect_ollama",
+    "resolve_auto_provider",
     "DEFAULT_CAPTION_PROMPT",
     "DEFAULT_VISION_DIM",
     "VISION_CAPTION_TARGET_ENV",

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",
+]