ltcai 2.2.7 → 3.0.1

package/latticeai/core/embedding_providers.py

@@ -0,0 +1,502 @@
+"""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.
+
+This module defines that :class:`EmbeddingProvider` interface and five concrete
+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.
+"""
+
+from __future__ import annotations
+
+import importlib
+import math
+import os
+import struct
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Sequence
+
+from latticeai.core.local_embeddings import DEFAULT_EMBEDDING_DIM, LocalEmbeddingModel
+
+
+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 = {
+    "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,
+    "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 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:
+        return float(sum(a * b for a, b in zip(left, right)))
+
+    # ── 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,
+        }
+
+
+# ── 1. Hash (offline fallback) ────────────────────────────────────────────────
+class HashEmbeddingProvider(EmbeddingProvider):
+    """Deterministic feature-hashing embedder — no network, always available."""
+
+    provider = "hash"
+    grade = "fallback"
+
+    def __init__(self, dim: int = DEFAULT_EMBEDDING_DIM):
+        self._model = LocalEmbeddingModel(dim=dim)
+        self.dim = self._model.dim
+        self.model_id = self._model.model_id
+
+    def embed(self, text: str) -> List[float]:
+        return self._model.embed(text)  # already L2-normalized
+
+    def embed_batch(self, texts: Sequence[str]) -> List[List[float]]:
+        return [self._model.embed(t) for t in texts]
+
+    def health(self) -> Dict[str, Any]:
+        return {"status": "ok", "detail": "deterministic local fallback"}
+
+
+# ── shared base for remote/model-backed providers ─────────────────────────────
+@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
+                self.dim = len(vec)
+            out.append(_l2_normalize(vec) if vec else [0.0] * self.dim)
+        return out
+
+
+# ── 2. MLX (local Apple-Silicon model) ────────────────────────────────────────
+class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
+    provider = "mlx"
+
+    def __init__(self, cfg: _RemoteConfig):
+        super().__init__(cfg)
+        self.model_id = f"mlx:{cfg.model}:{self.dim}"
+        self._encoder = None
+
+    def _load(self):
+        if self._encoder is not None:
+            return self._encoder
+        try:  # optional dependency; only imported when this provider is used
+            from mlx_embeddings.utils import load as mlx_load  # type: ignore
+
+            model, tokenizer = mlx_load(self._cfg.model)
+            self._encoder = ("mlx_embeddings", model, tokenizer)
+            return self._encoder
+        except Exception as exc:  # pragma: no cover - environment dependent
+            raise EmbeddingUnavailable(f"MLX embedding model unavailable: {exc}") from exc
+
+    def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        kind, 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 vec.tolist()])
+            return out
+        except EmbeddingUnavailable:
+            raise
+        except Exception as exc:  # pragma: no cover - environment dependent
+            raise EmbeddingUnavailable(f"MLX embedding failed: {exc}") from exc
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            self._load()
+            return {"status": "ok", "detail": f"MLX model {self._cfg.model} loaded"}
+        except Exception as exc:
+            return {"status": "unavailable", "detail": str(exc)}
+
+
+# ── 3. Ollama ─────────────────────────────────────────────────────────────────
+class OllamaEmbeddingProvider(_NetworkEmbeddingProvider):
+    provider = "ollama"
+
+    def __init__(self, cfg: _RemoteConfig):
+        super().__init__(cfg)
+        self._base = (cfg.base_url or "http://127.0.0.1:11434").rstrip("/")
+        if not cfg.dim:
+            self.dim = _guess_dim(cfg.model, DEFAULT_EMBEDDING_DIM)
+        self.model_id = f"ollama:{cfg.model}:{self.dim}"
+
+    def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        out: List[List[float]] = []
+        try:
+            import httpx
+
+            with httpx.Client(timeout=self._cfg.timeout) as client:
+                # /api/embed supports batching; fall back to /api/embeddings.
+                resp = client.post(
+                    f"{self._base}/api/embed",
+                    json={"model": self._cfg.model, "input": list(texts)},
+                )
+                if resp.status_code == 404:
+                    for text in texts:
+                        r = client.post(
+                            f"{self._base}/api/embeddings",
+                            json={"model": self._cfg.model, "prompt": text},
+                        )
+                        r.raise_for_status()
+                        out.append(r.json().get("embedding") or [])
+                    return out
+                resp.raise_for_status()
+                data = resp.json()
+                return data.get("embeddings") or [data.get("embedding") or []]
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"Ollama embedding failed: {exc}") from exc
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            import httpx
+
+            with httpx.Client(timeout=min(self._cfg.timeout, 5.0)) as client:
+                r = client.get(f"{self._base}/api/tags")
+                r.raise_for_status()
+            return {"status": "ok", "detail": f"Ollama reachable at {self._base}"}
+        except Exception as exc:
+            return {"status": "unavailable", "detail": f"Ollama unreachable: {exc}"}
+
+
+# ── 4. OpenAI-compatible (/v1/embeddings) ─────────────────────────────────────
+class OpenAICompatibleEmbeddingProvider(_NetworkEmbeddingProvider):
+    provider = "openai"
+
+    def __init__(self, cfg: _RemoteConfig):
+        super().__init__(cfg)
+        self._base = (cfg.base_url or "https://api.openai.com/v1").rstrip("/")
+        if not cfg.dim:
+            self.dim = _guess_dim(cfg.model, DEFAULT_EMBEDDING_DIM)
+        self.model_id = f"openai:{cfg.model}:{self.dim}"
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self._cfg.api_key:
+            headers["Authorization"] = f"Bearer {self._cfg.api_key}"
+        return headers
+
+    def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        try:
+            import httpx
+
+            with httpx.Client(timeout=self._cfg.timeout) as client:
+                r = client.post(
+                    f"{self._base}/embeddings",
+                    headers=self._headers(),
+                    json={"model": self._cfg.model, "input": list(texts)},
+                )
+                r.raise_for_status()
+                rows = sorted(r.json().get("data", []), key=lambda d: d.get("index", 0))
+                return [row.get("embedding") or [] for row in rows]
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"OpenAI-compatible embedding failed: {exc}") from exc
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            self._embed_raw(["ping"])
+            return {"status": "ok", "detail": f"{self._base} reachable"}
+        except Exception as exc:
+            return {"status": "unavailable", "detail": str(exc)}
+
+
+# ── 5. Custom (user-supplied callable) ────────────────────────────────────────
+class CustomEmbeddingProvider(_NetworkEmbeddingProvider):
+    """Loads a dotted ``module:callable`` (or ``module.callable``).
+
+    The callable receives ``List[str]`` and returns ``List[List[float]]``.
+    Configured via ``LATTICEAI_EMBEDDING_CUSTOM_TARGET``.
+    """
+
+    provider = "custom"
+
+    def __init__(self, cfg: _RemoteConfig):
+        super().__init__(cfg)
+        self._target_ref = str(cfg.extra.get("target") or os.getenv("LATTICEAI_EMBEDDING_CUSTOM_TARGET", ""))
+        self.model_id = f"custom:{cfg.model or self._target_ref or 'callable'}:{self.dim}"
+        self._fn = None
+
+    def _load(self):
+        if self._fn is not None:
+            return self._fn
+        ref = self._target_ref
+        if not ref:
+            raise EmbeddingUnavailable("custom embedding target not configured (LATTICEAI_EMBEDDING_CUSTOM_TARGET)")
+        module_name, _, attr = ref.replace(":", ".").rpartition(".")
+        if not module_name:
+            raise EmbeddingUnavailable(f"invalid custom embedding target: {ref}")
+        try:
+            module = importlib.import_module(module_name)
+            self._fn = getattr(module, attr)
+            return self._fn
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"custom embedding target unavailable: {exc}") from exc
+
+    def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        fn = self._load()
+        try:
+            return list(fn(list(texts)))
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"custom embedding failed: {exc}") from exc
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            self._load()
+            return {"status": "ok", "detail": f"custom target {self._target_ref} loaded"}
+        except Exception as exc:
+            return {"status": "unavailable", "detail": str(exc)}
+
+
+# ── factory + resolution ──────────────────────────────────────────────────────
+PROVIDER_TYPES = ("hash", "mlx", "ollama", "openai", "custom")
+
+
+def build_embedding_provider(
+    provider: str,
+    *,
+    model: str = "",
+    base_url: str = "",
+    api_key: str = "",
+    dim: int = 0,
+    timeout: float = 30.0,
+    extra: Optional[Dict[str, Any]] = None,
+) -> EmbeddingProvider:
+    """Construct a provider by name. Never makes a network call."""
+    kind = str(provider or "hash").strip().lower()
+    if kind in {"", "hash", "local", "fallback"}:
+        return HashEmbeddingProvider(dim=int(dim or DEFAULT_EMBEDDING_DIM))
+    cfg = _RemoteConfig(
+        model=model,
+        base_url=base_url,
+        api_key=api_key,
+        dim=int(dim or 0),
+        timeout=float(timeout or 30.0),
+        extra=dict(extra or {}),
+    )
+    if kind == "mlx":
+        return MLXEmbeddingProvider(cfg)
+    if kind == "ollama":
+        return OllamaEmbeddingProvider(cfg)
+    if kind in {"openai", "openai-compatible", "openai_compatible"}:
+        return OpenAICompatibleEmbeddingProvider(cfg)
+    if kind == "custom":
+        return CustomEmbeddingProvider(cfg)
+    raise ValueError(f"unknown embedding provider: {provider!r} (expected one of {PROVIDER_TYPES})")
+
+
+@dataclass
+class ResolvedEmbedder:
+    provider: EmbeddingProvider
+    requested: str
+    active: str
+    fell_back: bool
+    health: Dict[str, Any]
+    detail: str = ""
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "requested_provider": self.requested,
+            "active_provider": self.active,
+            "fell_back": self.fell_back,
+            "health": self.health,
+            "detail": self.detail,
+            **self.provider.metadata(),
+        }
+
+
+def resolve_embedder(
+    provider: str = "",
+    *,
+    model: str = "",
+    base_url: str = "",
+    api_key: str = "",
+    dim: int = 0,
+    timeout: float = 30.0,
+    extra: Optional[Dict[str, Any]] = None,
+    probe: bool = True,
+) -> ResolvedEmbedder:
+    """Build the requested provider, degrading to hash if it is unavailable.
+
+    Local-first guarantee: the app always gets a working embedder. When the
+    requested provider is unreachable we return the hash fallback but record
+    ``fell_back=True`` and the failing health detail so the UI shows it as
+    *Unavailable* — the system never pretends a down provider is live.
+    """
+    requested = str(provider or "hash").strip().lower() or "hash"
+    if requested in {"hash", "local", "fallback", ""}:
+        prov = HashEmbeddingProvider(dim=int(dim or DEFAULT_EMBEDDING_DIM))
+        return ResolvedEmbedder(prov, "hash", "hash", False, prov.health(), "deterministic local fallback")
+
+    try:
+        prov = build_embedding_provider(
+            requested, model=model, base_url=base_url, api_key=api_key, dim=dim, timeout=timeout, extra=extra
+        )
+    except Exception as exc:
+        fallback = HashEmbeddingProvider(dim=int(dim or DEFAULT_EMBEDDING_DIM))
+        return ResolvedEmbedder(
+            fallback, requested, "hash", True,
+            {"status": "unavailable", "detail": str(exc)},
+            f"could not construct {requested}; using hash fallback",
+        )
+
+    if probe:
+        try:
+            health = prov.health()
+        except Exception as exc:  # provider health must never crash startup
+            health = {"status": "unavailable", "detail": str(exc)}
+    else:
+        health = {"status": "unknown", "detail": "not probed"}
+    if probe and health.get("status") != "ok":
+        fallback = HashEmbeddingProvider(dim=int(dim or DEFAULT_EMBEDDING_DIM))
+        return ResolvedEmbedder(
+            fallback, requested, "hash", True, health,
+            f"{requested} unavailable ({health.get('detail', '')}); using hash fallback",
+        )
+    return ResolvedEmbedder(prov, requested, prov.provider, False, health, "")
+
+
+__all__ = [
+    "EmbeddingProvider",
+    "EmbeddingUnavailable",
+    "HashEmbeddingProvider",
+    "MLXEmbeddingProvider",
+    "OllamaEmbeddingProvider",
+    "OpenAICompatibleEmbeddingProvider",
+    "CustomEmbeddingProvider",
+    "ResolvedEmbedder",
+    "build_embedding_provider",
+    "resolve_embedder",
+    "PROVIDER_TYPES",
+]

package/latticeai/core/local_embeddings.py

@@ -0,0 +1,86 @@
+"""Local deterministic embeddings for Lattice AI search.
+
+The v3 backend needs a local-first vector signal without introducing a cloud
+runtime requirement. This module provides a small feature-hashing embedder that
+is deterministic, cheap to run, and good enough for indexing/search tests. A
+future runtime can swap the implementation behind the same interface when a
+local model server is available.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import os
+import re
+import struct
+from dataclasses import dataclass
+from typing import Iterable, List
+
+
+DEFAULT_EMBEDDING_DIM = int(os.getenv("LATTICEAI_VECTOR_DIM", "384"))
+EMBEDDING_MODEL_ID = f"lattice-local-hash-v1:{DEFAULT_EMBEDDING_DIM}"
+
+
+def _tokenize(text: str) -> List[str]:
+    raw = str(text or "").lower()
+    tokens = re.findall(r"[a-z0-9][a-z0-9_.:/+-]{1,}|[가-힣]{2,}", raw)
+    features: List[str] = []
+    for token in tokens:
+        features.append(f"tok:{token}")
+        if len(token) >= 5 and re.search(r"[a-z]", token):
+            for i in range(0, len(token) - 2):
+                features.append(f"tri:{token[i:i+3]}")
+        if re.search(r"[가-힣]", token) and len(token) >= 3:
+            for i in range(0, len(token) - 1):
+                features.append(f"ko:{token[i:i+2]}")
+    return features
+
+
+def _hash_to_index(feature: str, dim: int) -> tuple[int, float]:
+    digest = hashlib.blake2b(feature.encode("utf-8"), digest_size=8).digest()
+    value = int.from_bytes(digest, "big", signed=False)
+    sign = 1.0 if (value & 1) == 0 else -1.0
+    return value % dim, sign
+
+
+@dataclass(frozen=True)
+class LocalEmbeddingModel:
+    """Deterministic feature-hashing embedder.
+
+    The output vectors are L2-normalized, so cosine similarity is just a dot
+    product. No network access, model download, or global mutable state is
+    required.
+    """
+
+    dim: int = DEFAULT_EMBEDDING_DIM
+    model_id: str = EMBEDDING_MODEL_ID
+
+    def embed(self, text: str) -> List[float]:
+        vector = [0.0] * self.dim
+        features = _tokenize(text)
+        if not features:
+            return vector
+        for feature in features:
+            index, sign = _hash_to_index(feature, self.dim)
+            vector[index] += sign
+        norm = math.sqrt(sum(value * value for value in vector))
+        if norm <= 0:
+            return vector
+        return [value / norm for value in vector]
+
+    def similarity(self, left: Iterable[float], right: Iterable[float]) -> float:
+        return float(sum(a * b for a, b in zip(left, right)))
+
+    def encode(self, vector: Iterable[float]) -> bytes:
+        values = list(vector)
+        return struct.pack(f"<{len(values)}f", *values)
+
+    def decode(self, payload: bytes, dim: int | None = None) -> List[float]:
+        if not payload:
+            return []
+        count = int(dim or self.dim)
+        expected = count * 4
+        if len(payload) != expected:
+            count = len(payload) // 4
+        return list(struct.unpack(f"<{count}f", payload[: count * 4]))

package/latticeai/core/workspace_os.py

@@ -18,7 +18,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "2.2.7"
+WORKSPACE_OS_VERSION = "3.0.1"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/server_app.py

@@ -72,6 +72,9 @@ from latticeai.core.enterprise import (
 from latticeai.services.workspace_service import WorkspaceService
 from latticeai.services.model_service import ModelService
 from latticeai.services.chat_service import ChatService
+from latticeai.services.search_service import SearchService
+from latticeai.core.embedding_providers import resolve_embedder
+from latticeai.services.agent_runtime import AgentRuntime
 from latticeai.services.model_runtime import (
     CLOUD_VERIFY_TTL_SECONDS,
     ENGINE_MODEL_CATALOG,
@@ -105,6 +108,7 @@ from latticeai.api.realtime import create_realtime_router
 from latticeai.api.marketplace import create_marketplace_router
 from latticeai.api.models import create_models_router
 from latticeai.api.chat import create_chat_router
+from latticeai.api.search import create_search_router
 from latticeai.api.tools import create_tools_router
 from latticeai.api.static_routes import create_static_routes_router
 from latticeai.api.garden import create_garden_router
@@ -244,7 +248,26 @@ VPC_FILE = DATA_DIR / "vpc_config.json"
 MCP_FILE = DATA_DIR / "mcp_installs.json"
 AUDIT_FILE = DATA_DIR / "audit_log.json"
 SSO_FILE = DATA_DIR / "sso_config.json"
-KNOWLEDGE_GRAPH = KnowledgeGraphStore(DATA_DIR / "knowledge_graph.sqlite", DATA_DIR / "knowledge_graph_blobs") if ENABLE_GRAPH else None
+# Resolve the configured embedding provider once at startup. Degrades to the
+# offline hash fallback when the requested provider is unavailable, while
+# recording the requested-vs-active provider for the Embeddings status surface.
+EMBEDDER = resolve_embedder(
+    CONFIG.embedding_provider,
+    model=CONFIG.embedding_model,
+    base_url=CONFIG.embedding_base_url,
+    api_key=CONFIG.embedding_api_key,
+    dim=CONFIG.embedding_dim,
+    timeout=CONFIG.embedding_timeout,
+    extra={"target": CONFIG.embedding_custom_target},
+    probe=CONFIG.embedding_provider not in {"", "hash", "local", "fallback"},
+)
+if EMBEDDER.fell_back:
+    logging.warning("Embedding provider %s unavailable: %s", EMBEDDER.requested, EMBEDDER.detail)
+KNOWLEDGE_GRAPH = KnowledgeGraphStore(
+    DATA_DIR / "knowledge_graph.sqlite",
+    DATA_DIR / "knowledge_graph_blobs",
+    embedder=EMBEDDER.provider,
+) if ENABLE_GRAPH else None
 LOCAL_KG_WATCHER = LocalKnowledgeWatcher(lambda: KNOWLEDGE_GRAPH) if ENABLE_GRAPH else None
 # ── v2 Realtime bus: constructed first so the store can fan every timeline
 # event into the realtime feed via a single additive sink (no per-call wiring).
@@ -1171,6 +1194,9 @@ def _workspace_graph():
     return KNOWLEDGE_GRAPH if (ENABLE_GRAPH and KNOWLEDGE_GRAPH) else None
 
 
+SEARCH_SERVICE = SearchService(graph_store=_workspace_graph())
+
+
 # ── Workspace OS + Organization router (latticeai.api.workspace, v1.2.0) ──────
 app.include_router(create_workspace_router(
     service=WORKSPACE_SERVICE,
@@ -1217,6 +1243,14 @@ PLATFORM = PlatformRuntime(
     get_tool_permission=get_tool_permission,
 )
 
+# Single AgentRuntime boundary over the orchestrator + run store.
+AGENT_RUNTIME = AgentRuntime(
+    store=WORKSPACE_OS,
+    orchestrator_factory=PLATFORM.build_orchestrator,
+    workspace_graph=_workspace_graph,
+    append_audit_event=append_audit_event,
+)
+
 app.include_router(create_plugins_router(
     registry=PLUGIN_REGISTRY,
     require_user=require_user,
@@ -1252,6 +1286,7 @@ app.include_router(create_agents_router(
     append_audit_event=append_audit_event,
     ui_file_response=ui_file_response,
     static_dir=STATIC_DIR,
+    agent_runtime=AGENT_RUNTIME,
 ))
 
 app.include_router(create_marketplace_router(
@@ -1351,6 +1386,19 @@ app.include_router(create_chat_router(
     base_dir=BASE_DIR,
 ))
 
+def _embedding_info() -> dict:
+    from latticeai.core.embedding_providers import PROVIDER_TYPES
+    info = EMBEDDER.as_dict()
+    info["available_providers"] = list(PROVIDER_TYPES)
+    return info
+
+
+app.include_router(create_search_router(
+    service=SEARCH_SERVICE,
+    require_user=require_user,
+    embedding_info=_embedding_info,
+))
+
 app.include_router(create_tools_router(
     config=CONFIG,
     data_dir=DATA_DIR,