@pentatonic-ai/ai-agent-sdk 0.7.13 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.7.13",
+  "version": "0.8.0",
   "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
   "type": "module",
   "main": "./dist/index.cjs",

package/packages/memory/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "pentatonic-memory",
   "name": "Pentatonic Memory",
   "description": "Persistent, searchable memory with multi-signal retrieval and HyDE query expansion. Local (Docker + Ollama) or hosted (Pentatonic TES).",
-  "version": "0.5.3",
+  "version": "0.8.4",
   "kind": "context-engine",
   "configSchema": {
     "type": "object",

package/packages/memory/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/openclaw-memory-plugin",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Pentatonic Memory plugin for OpenClaw — persistent, searchable memory with multi-signal retrieval and HyDE query expansion",
   "type": "module",
   "main": "index.js",

package/packages/memory-engine/docker-compose.yml

@@ -88,8 +88,8 @@ services:
   l4:
     <<: *engine-base
     build:
-      context: ./engine/services/l4
-      dockerfile: Dockerfile
+      context: ./engine/services
+      dockerfile: l4/Dockerfile
     container_name: pme-l4
     # Default 18042 to avoid port collisions on 8042.
     # Override via PME_L4_PORT for bench setups that intentionally replace it.
@@ -98,6 +98,8 @@ services:
       L4_NV_EMBED_URL: ${NV_EMBED_URL:-http://host.docker.internal:8041/v1/embeddings}
       L4_EMBED_MODEL: ${EMBED_MODEL_NAME:-nv-embed-v2}
       L4_EMBED_API_KEY: ${EMBED_API_KEY:-}
+      L4_EMBED_PROVIDER: ${EMBED_PROVIDER:-openai}
+      L4_EMBED_AUTODETECT: ${EMBED_AUTODETECT:-true}
       L4_EMBED_DIM: ${EMBED_DIM:-4096}
       L4_DB_PATH: /data/vec.db
     extra_hosts:
@@ -116,8 +118,8 @@ services:
   l5:
     <<: *engine-base
     build:
-      context: ./engine/services/l5
-      dockerfile: Dockerfile
+      context: ./engine/services
+      dockerfile: l5/Dockerfile
     container_name: pme-l5
     # Default 18034 to avoid port collisions on 8034.
     # Override via PME_L5_PORT for bench setups that intentionally replace it.
@@ -126,6 +128,8 @@ services:
       L5_NV_EMBED_URL: ${NV_EMBED_URL:-http://host.docker.internal:8041/v1/embeddings}
       L5_EMBED_MODEL: ${EMBED_MODEL_NAME:-nv-embed-v2}
       L5_EMBED_API_KEY: ${EMBED_API_KEY:-}
+      L5_EMBED_PROVIDER: ${EMBED_PROVIDER:-openai}
+      L5_EMBED_AUTODETECT: ${EMBED_AUTODETECT:-true}
       L5_EMBED_DIM: ${EMBED_DIM:-4096}
       L5_OLLAMA_DIM: ${OLLAMA_DIM:-768}
       L5_OLLAMA_EMBED_URL: ${L5_OLLAMA_EMBED_URL:-http://host.docker.internal:11434/api/embed}
@@ -143,8 +147,8 @@ services:
   l6:
     <<: *engine-base
     build:
-      context: ./engine/services/l6
-      dockerfile: Dockerfile
+      context: ./engine/services
+      dockerfile: l6/Dockerfile
     container_name: pme-l6
     # Default 18037 to avoid colliding with Spark Core L6 doc-store on 8037.
     # Override via PME_L6_PORT for bench setups that intentionally replace it.
@@ -153,6 +157,8 @@ services:
       L6_NV_EMBED_URL: ${NV_EMBED_URL:-http://host.docker.internal:8041/v1/embeddings}
       L6_EMBED_MODEL: ${EMBED_MODEL_NAME:-nv-embed-v2}
       L6_EMBED_API_KEY: ${EMBED_API_KEY:-}
+      L6_EMBED_PROVIDER: ${EMBED_PROVIDER:-openai}
+      L6_EMBED_AUTODETECT: ${EMBED_AUTODETECT:-true}
       L6_EMBED_DIM: ${EMBED_DIM:-4096}
       L6_DATA_DIR: /data
     extra_hosts:
@@ -166,12 +172,16 @@ services:
   l2:
     <<: *engine-base
     build:
-      context: ./engine/services/l2
-      dockerfile: Dockerfile
+      context: ./engine/services
+      dockerfile: l2/Dockerfile
     container_name: pme-l2
     ports: ["127.0.0.1:${PME_L2_PORT:-8131}:8031"]
     environment:
       PME_NV_EMBED_URL: ${NV_EMBED_URL:-http://host.docker.internal:8041/v1/embeddings}
+      PME_EMBED_API_KEY: ${EMBED_API_KEY:-}
+      PME_EMBED_PROVIDER: ${EMBED_PROVIDER:-openai}
+      PME_EMBED_AUTODETECT: ${EMBED_AUTODETECT:-true}
+      PME_NV_EMBED_MODEL: ${EMBED_MODEL_NAME:-nv-embed-v2}
       PME_NEO4J_URI: bolt://l3:7687
       PME_NEO4J_PASSWORD: ${NEO4J_PASSWORD:-local-dev-pw}
       NEO4J_PASSWORD: ${NEO4J_PASSWORD:-local-dev-pw}

package/packages/memory-engine/engine/services/_shared/__init__.py

@@ -0,0 +1 @@
+"""Shared utilities used across the memory-engine layer services."""

package/packages/memory-engine/engine/services/_shared/embed_provider.py

@@ -0,0 +1,431 @@
+"""Embedding provider abstraction for memory-engine layer services.
+
+Different embedding gateways disagree on three things:
+  1. Auth scheme    (Authorization: Bearer ... vs X-API-Key: ...)
+  2. URL path       (/v1/embeddings vs /v1/embed vs vendor-specific)
+  3. Request shape  (OpenAI {"input": [...]} vs Cohere {"texts": [...], "input_type": ...})
+  4. Response shape ({"data": [{"embedding": ...}]} vs {"embeddings": [...]})
+
+`EmbedProvider` captures all four for one gateway. Built-in profiles cover
+OpenAI-compatible, Pentatonic AI Gateway, and Cohere. A "custom" profile lets
+you override auth + path via env without code changes.
+
+Auto-detect: when the configured provider returns 401, the client probes the
+other built-in profiles once and caches the winner for the rest of the
+process. Disabled with `EMBED_AUTODETECT=false` per layer.
+
+Usage from a layer service:
+
+    from _shared.embed_provider import EmbedClient
+
+    embed = EmbedClient.from_env(prefix="L4_")
+    vectors = embed.embed_batch(["hello", "world"])
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Callable
+from urllib.parse import urlparse, urlunparse
+
+import httpx
+
+log = logging.getLogger("embed_provider")
+
+
+# ----------------------------------------------------------------------
+# Body builders + response parsers
+# ----------------------------------------------------------------------
+
+def _openai_body(texts: list[str], model: str) -> dict[str, Any]:
+    return {"input": texts, "model": model}
+
+
+def _openai_response(payload: dict[str, Any]) -> list[list[float]]:
+    return [d["embedding"] for d in payload["data"]]
+
+
+def _pentatonic_response(payload: dict[str, Any]) -> list[list[float]]:
+    """Pentatonic AI Gateway returns {"embeddings": [...]} on /v1/embed
+    and OpenAI-shaped {"data": [{"embedding": ...}]} on /v1/embeddings.
+    Accept either."""
+    if "data" in payload:
+        return [d["embedding"] for d in payload["data"]]
+    return payload["embeddings"]
+
+
+def _cohere_body(texts: list[str], model: str) -> dict[str, Any]:
+    return {"texts": texts, "model": model, "input_type": "search_document"}
+
+
+def _cohere_response(payload: dict[str, Any]) -> list[list[float]]:
+    return payload["embeddings"]
+
+
+_BODY_BUILDERS: dict[str, Callable[[list[str], str], dict[str, Any]]] = {
+    "openai": _openai_body,
+    "cohere": _cohere_body,
+}
+
+_RESPONSE_PARSERS: dict[str, Callable[[dict[str, Any]], list[list[float]]]] = {
+    "openai": _openai_response,
+    "pentatonic": _pentatonic_response,
+    "cohere": _cohere_response,
+}
+
+
+# ----------------------------------------------------------------------
+# Provider profiles
+# ----------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class EmbedProvider:
+    name: str
+    auth_header: str
+    auth_format: str  # f-string-ish; "{key}" placeholder substituted at request time
+    path_default: str
+    body_builder: Callable[[list[str], str], dict[str, Any]]
+    response_parser: Callable[[dict[str, Any]], list[list[float]]]
+
+
+PROVIDERS: dict[str, EmbedProvider] = {
+    "openai": EmbedProvider(
+        name="openai",
+        auth_header="Authorization",
+        auth_format="Bearer {key}",
+        path_default="/v1/embeddings",
+        body_builder=_openai_body,
+        response_parser=_openai_response,
+    ),
+    "pentatonic-gateway": EmbedProvider(
+        name="pentatonic-gateway",
+        auth_header="X-API-Key",
+        auth_format="{key}",
+        path_default="/v1/embed",
+        body_builder=_openai_body,
+        response_parser=_pentatonic_response,
+    ),
+    "cohere": EmbedProvider(
+        name="cohere",
+        auth_header="Authorization",
+        auth_format="Bearer {key}",
+        path_default="/v1/embed",
+        body_builder=_cohere_body,
+        response_parser=_cohere_response,
+    ),
+}
+
+
+def _build_custom_provider(env_prefix: str) -> EmbedProvider:
+    """Build a custom provider from env vars.
+
+    Env vars (env_prefix is e.g. 'L4_'):
+        {prefix}EMBED_AUTH_HEADER     default Authorization
+        {prefix}EMBED_AUTH_FORMAT     default Bearer {key}
+        {prefix}EMBED_PATH_DEFAULT    default /v1/embeddings
+        {prefix}EMBED_BODY_SHAPE      "openai" | "cohere"  default openai
+        {prefix}EMBED_RESPONSE_SHAPE  "openai" | "pentatonic" | "cohere"  default openai
+    """
+    body_shape = os.environ.get(f"{env_prefix}EMBED_BODY_SHAPE", "openai")
+    response_shape = os.environ.get(f"{env_prefix}EMBED_RESPONSE_SHAPE", "openai")
+    return EmbedProvider(
+        name="custom",
+        auth_header=os.environ.get(f"{env_prefix}EMBED_AUTH_HEADER", "Authorization"),
+        auth_format=os.environ.get(f"{env_prefix}EMBED_AUTH_FORMAT", "Bearer {key}"),
+        path_default=os.environ.get(f"{env_prefix}EMBED_PATH_DEFAULT", "/v1/embeddings"),
+        body_builder=_BODY_BUILDERS.get(body_shape, _openai_body),
+        response_parser=_RESPONSE_PARSERS.get(response_shape, _openai_response),
+    )
+
+
+def resolve_provider(name: str, env_prefix: str = "") -> EmbedProvider:
+    """Look up a built-in provider, or build a custom one from env."""
+    if name in PROVIDERS:
+        return PROVIDERS[name]
+    if name == "custom":
+        return _build_custom_provider(env_prefix)
+    raise ValueError(
+        f"Unknown EMBED_PROVIDER {name!r}. "
+        f"Built-ins: {sorted(PROVIDERS)} or 'custom'."
+    )
+
+
+# ----------------------------------------------------------------------
+# URL helpers
+# ----------------------------------------------------------------------
+
+def _swap_path(url: str, new_path: str) -> str:
+    """Replace the path component of `url` with `new_path`. Empty path on the
+    input URL is treated as 'no path provided' and gets `new_path` appended."""
+    p = urlparse(url)
+    return urlunparse((p.scheme, p.netloc, new_path, "", p.query, p.fragment))
+
+
+def _resolved_url(url: str, provider: EmbedProvider) -> str:
+    """If `url` has no path, append the provider's default path; otherwise
+    leave as-is (operator chose a specific path)."""
+    p = urlparse(url)
+    if not p.path or p.path == "/":
+        return _swap_path(url, provider.path_default)
+    return url
+
+
+# ----------------------------------------------------------------------
+# Client
+# ----------------------------------------------------------------------
+
+class EmbedAuthError(RuntimeError):
+    """Raised when every candidate provider returns 401."""
+
+
+class EmbedHTTPError(RuntimeError):
+    """Raised on non-401 HTTP errors from the embedding endpoint."""
+
+    def __init__(self, status: int, body: str):
+        super().__init__(f"HTTP {status}: {body[:200]}")
+        self.status = status
+        self.body = body
+
+
+class EmbedClient:
+    """Sync + async embedding client with provider auto-detection.
+
+    Construct via `EmbedClient.from_env(prefix="L4_")` so each layer service
+    reads its own env-var namespace; or call the constructor directly for
+    tests.
+
+    The client is stateful: after a successful auto-detect, the winning
+    provider is cached for the rest of the process lifetime. Set
+    `autodetect=False` (or env `{prefix}EMBED_AUTODETECT=false`) to disable.
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        api_key: str,
+        model: str,
+        provider: EmbedProvider,
+        autodetect: bool = True,
+        timeout: float = 120.0,
+        env_prefix: str = "",
+    ) -> None:
+        self._configured_provider = provider
+        self._provider = provider
+        self._configured_url = url
+        self._url = _resolved_url(url, provider)
+        self._api_key = api_key
+        self._model = model
+        self._timeout = timeout
+        self._autodetect = autodetect
+        self._env_prefix = env_prefix
+        self._detected = False
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_env(
+        cls,
+        prefix: str,
+        *,
+        url_var: str | None = None,
+        key_var: str | None = None,
+        model_var: str | None = None,
+        default_url: str = "",
+        default_model: str = "nv-embed-v2",
+    ) -> "EmbedClient":
+        """Build an EmbedClient from layer-prefixed env vars.
+
+        Layer services use `EmbedClient.from_env(prefix="L4_")` and the
+        client reads:
+          {prefix}NV_EMBED_URL  (override with `url_var=...`)
+          {prefix}EMBED_API_KEY
+          {prefix}EMBED_MODEL
+          {prefix}EMBED_PROVIDER     default 'openai'
+          {prefix}EMBED_AUTODETECT   default 'true'
+          {prefix}EMBED_TIMEOUT      default '120'
+        """
+        url_var = url_var or f"{prefix}NV_EMBED_URL"
+        key_var = key_var or f"{prefix}EMBED_API_KEY"
+        model_var = model_var or f"{prefix}EMBED_MODEL"
+
+        url = os.environ.get(url_var, default_url)
+        api_key = os.environ.get(key_var, "")
+        model = os.environ.get(model_var, default_model)
+        provider_name = os.environ.get(f"{prefix}EMBED_PROVIDER", "openai")
+        autodetect = os.environ.get(f"{prefix}EMBED_AUTODETECT", "true").lower() == "true"
+        timeout = float(os.environ.get(f"{prefix}EMBED_TIMEOUT", "120"))
+
+        provider = resolve_provider(provider_name, env_prefix=prefix)
+        return cls(
+            url=url,
+            api_key=api_key,
+            model=model,
+            provider=provider,
+            autodetect=autodetect,
+            timeout=timeout,
+            env_prefix=prefix,
+        )
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _headers(self, provider: EmbedProvider) -> dict[str, str]:
+        if not self._api_key:
+            return {}
+        return {provider.auth_header: provider.auth_format.format(key=self._api_key)}
+
+    def _candidate_url(self, provider: EmbedProvider) -> str:
+        """URL to try for this provider. The configured provider keeps the
+        operator's chosen URL; auto-detect candidates swap in their own
+        path_default since the operator's path was wrong for them."""
+        if provider.name == self._configured_provider.name:
+            return self._url
+        return _swap_path(self._configured_url, provider.path_default)
+
+    def _switch_to(self, provider: EmbedProvider) -> None:
+        """Make `provider` the active provider for future requests."""
+        log.warning(
+            "embed_provider auto-detect switched: configured=%s -> active=%s. "
+            "Set %sEMBED_PROVIDER=%s to silence this.",
+            self._configured_provider.name,
+            provider.name,
+            self._env_prefix,
+            provider.name,
+        )
+        self._provider = provider
+        self._url = self._candidate_url(provider)
+        self._detected = True
+
+    # ------------------------------------------------------------------
+    # Sync API
+    # ------------------------------------------------------------------
+
+    def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Embed a list of texts. Empty list returns empty list."""
+        if not texts:
+            return []
+        return self._post_with_autodetect(texts, async_mode=False)
+
+    def embed_one(self, text: str) -> list[float]:
+        return self.embed_batch([text])[0]
+
+    # ------------------------------------------------------------------
+    # Async API
+    # ------------------------------------------------------------------
+
+    async def embed_batch_async(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        return await self._post_with_autodetect_async(texts)
+
+    async def embed_one_async(self, text: str) -> list[float]:
+        out = await self.embed_batch_async([text])
+        return out[0]
+
+    # ------------------------------------------------------------------
+    # Request paths
+    # ------------------------------------------------------------------
+
+    def _post_with_autodetect(self, texts: list[str], *, async_mode: bool) -> list[list[float]]:
+        del async_mode  # kept for symmetry; sync path is its own method
+        body = self._provider.body_builder(texts, self._model)
+        headers = self._headers(self._provider)
+        try:
+            r = httpx.post(self._url, json=body, headers=headers, timeout=self._timeout)
+        except httpx.HTTPError as exc:
+            raise EmbedHTTPError(0, str(exc)) from exc
+
+        if r.status_code == 401 and self._autodetect and not self._detected:
+            return self._autodetect_and_retry(texts, last_body=r.text)
+
+        if r.status_code == 401:
+            raise EmbedAuthError(r.text)
+        if not r.is_success:
+            raise EmbedHTTPError(r.status_code, r.text)
+        return self._provider.response_parser(r.json())
+
+    async def _post_with_autodetect_async(self, texts: list[str]) -> list[list[float]]:
+        body = self._provider.body_builder(texts, self._model)
+        headers = self._headers(self._provider)
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                r = await client.post(self._url, json=body, headers=headers)
+        except httpx.HTTPError as exc:
+            raise EmbedHTTPError(0, str(exc)) from exc
+
+        if r.status_code == 401 and self._autodetect and not self._detected:
+            return await self._autodetect_and_retry_async(texts, last_body=r.text)
+
+        if r.status_code == 401:
+            raise EmbedAuthError(r.text)
+        if not r.is_success:
+            raise EmbedHTTPError(r.status_code, r.text)
+        return self._provider.response_parser(r.json())
+
+    # ------------------------------------------------------------------
+    # Auto-detect
+    # ------------------------------------------------------------------
+
+    def _candidates(self) -> list[EmbedProvider]:
+        return [p for p in PROVIDERS.values() if p.name != self._provider.name]
+
+    def _autodetect_and_retry(self, texts: list[str], *, last_body: str) -> list[list[float]]:
+        for candidate in self._candidates():
+            url = self._candidate_url(candidate)
+            body = candidate.body_builder(texts, self._model)
+            headers = (
+                {candidate.auth_header: candidate.auth_format.format(key=self._api_key)}
+                if self._api_key
+                else {}
+            )
+            try:
+                r = httpx.post(url, json=body, headers=headers, timeout=self._timeout)
+            except httpx.HTTPError:
+                continue
+            if r.is_success:
+                self._switch_to(candidate)
+                return candidate.response_parser(r.json())
+        raise EmbedAuthError(
+            f"all providers returned auth or transport errors. "
+            f"last 401 body: {last_body[:200]}"
+        )
+
+    async def _autodetect_and_retry_async(self, texts: list[str], *, last_body: str) -> list[list[float]]:
+        for candidate in self._candidates():
+            url = self._candidate_url(candidate)
+            body = candidate.body_builder(texts, self._model)
+            headers = (
+                {candidate.auth_header: candidate.auth_format.format(key=self._api_key)}
+                if self._api_key
+                else {}
+            )
+            try:
+                async with httpx.AsyncClient(timeout=self._timeout) as client:
+                    r = await client.post(url, json=body, headers=headers)
+            except httpx.HTTPError:
+                continue
+            if r.is_success:
+                self._switch_to(candidate)
+                return candidate.response_parser(r.json())
+        raise EmbedAuthError(
+            f"all providers returned auth or transport errors. "
+            f"last 401 body: {last_body[:200]}"
+        )
+
+    # ------------------------------------------------------------------
+    # Introspection (handy for /health and tests)
+    # ------------------------------------------------------------------
+
+    @property
+    def active_provider(self) -> str:
+        return self._provider.name
+
+    @property
+    def active_url(self) -> str:
+        return self._url

package/packages/memory-engine/engine/services/l2/Dockerfile

@@ -15,8 +15,10 @@ RUN pip install --no-cache-dir \
         "sentence-transformers" \
         "torch" --extra-index-url https://download.pytorch.org/whl/cpu
 
-COPY l2-hybridrag-proxy.py /app/server.py
-COPY init_databases.py /app/init_databases.py
+# Shared embed_provider module (build context is engine/services).
+COPY _shared /app/_shared
+COPY l2/l2-hybridrag-proxy.py /app/server.py
+COPY l2/init_databases.py /app/init_databases.py
 
 # Pre-create empty L0 BM25 SQLite + empty workspace
 RUN mkdir -p /data/workspace /data/.pentatonic/memory /data/.cache && \

package/packages/memory-engine/engine/services/l2/l2-hybridrag-proxy.py

@@ -17,6 +17,7 @@ import json
 import logging
 import os
 import sqlite3
+import sys
 import time
 from datetime import datetime
 from pathlib import Path
@@ -30,6 +31,10 @@ from neo4j.time import DateTime as Neo4jDateTime, Date as Neo4jDate
 from pydantic import BaseModel
 import uvicorn
 
+# Shared embed client lives at engine/services/_shared/.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from _shared.embed_provider import EmbedClient  # noqa: E402
+
 
 def _serialize_neo4j_value(v: Any) -> Any:
     """Convert neo4j-specific types to JSON-serialisable equivalents.
@@ -93,10 +98,27 @@ QMD_DB_PATH = _resolve_qmd_db()
 OLLAMA_URL = os.environ.get("PME_OLLAMA_URL", "http://localhost:11434/api/embeddings")
 EMBEDDING_MODEL = os.environ.get("PME_EMBED_MODEL", "nomic-embed-text")
 
-# NV-Embed-v2 service (primary, 4096-dim)
-NV_EMBED_URL = os.environ.get("PME_NV_EMBED_URL", "http://localhost:8041/v1/embeddings")
+# NV-Embed-v2 service (primary, 4096-dim). URL/auth/path/body/response are
+# managed by the shared EmbedClient; PME_EMBED_PROVIDER (default openai)
+# selects auth scheme (Bearer vs X-API-Key) and request shape.
 NV_EMBED_ENABLED = os.environ.get("PME_NV_EMBED_ENABLED", "true").lower() == "true"
 
+_embed: EmbedClient | None = None
+
+
+def _embed_client() -> EmbedClient:
+    """Lazily build the shared EmbedClient for L2."""
+    global _embed
+    if _embed is None:
+        _embed = EmbedClient.from_env(
+            prefix="PME_",
+            url_var="PME_NV_EMBED_URL",
+            key_var="PME_EMBED_API_KEY",
+            model_var="PME_NV_EMBED_MODEL",
+            default_url="http://localhost:8041/v1/embeddings",
+        )
+    return _embed
+
 # Sequential processing weights - OPTIMIZED FOR QUALITY
 GRAPH_PRIORITY_BOOST = 0.5  # Extra score for graph-derived results (↑ for better entity/relationship context)
 VECTOR_BASE_WEIGHT = 0.5     # Base weight for vector results (↓ balanced for accuracy over speed)
@@ -389,12 +411,11 @@ def search_neo4j_sequential(query: str, entities: List[str], limit: int = 12) ->
 
 def get_embedding(text: str) -> List[float]:
     """Get embedding — tries NV-Embed-v2 (4096-dim) first, falls back to Ollama."""
-    # Try NV-Embed-v2 service first
+    # Try NV-Embed-v2 service first via the shared EmbedClient (handles
+    # provider selection, auth scheme, path, and 401 auto-detect).
     if NV_EMBED_ENABLED:
         try:
-            r = requests.post(NV_EMBED_URL, json={"input": text}, timeout=30)
-            r.raise_for_status()
-            return r.json()["data"][0]["embedding"]
+            return _embed_client().embed_one(text)
         except Exception as e:
             log.warning(f"NV-Embed-v2 failed, falling back to Ollama: {e}")
 
@@ -1073,17 +1094,23 @@ async def list_models() -> dict:
 @app.post("/v1/embeddings")
 async def create_embeddings(request: EmbeddingRequest) -> dict:
     """Pass-through to NV-Embed-v2 (4096-dim). Batch-native — forwards the full
-    input list in a single HTTP call instead of looping one-at-a-time."""
+    input list in a single HTTP call instead of looping one-at-a-time.
+
+    Returns OpenAI-shaped response regardless of upstream provider, so
+    callers (including L4 search and external clients) get a consistent
+    contract from this proxy."""
     try:
-        import httpx
         inputs = [request.input] if isinstance(request.input, str) else request.input
-        async with httpx.AsyncClient(timeout=60) as client:
-            resp = await client.post(
-                NV_EMBED_URL,
-                json={"input": inputs, "model": request.model or "nv-embed-v2"}
-            )
-            resp.raise_for_status()
-            return resp.json()
+        embeddings = await _embed_client().embed_batch_async(inputs)
+        return {
+            "object": "list",
+            "model": request.model or "nv-embed-v2",
+            "data": [
+                {"object": "embedding", "embedding": e, "index": i}
+                for i, e in enumerate(embeddings)
+            ],
+            "usage": {"prompt_tokens": 0, "total_tokens": 0},
+        }
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -1319,17 +1346,11 @@ def _extract_entities_for_kg(text: str, max_entities: int = 32) -> List[str]:
 
 
 def _embed_batch_local(texts: List[str]) -> List[List[float]]:
-    """Batch embed via NV-Embed. Returns vectors in input order."""
+    """Batch embed via the shared EmbedClient. Returns vectors in input order."""
     if not texts:
         return []
     try:
-        r = requests.post(NV_EMBED_URL,
-                          json={"input": texts, "model": "nv-embed-v2"},
-                          timeout=120)
-        r.raise_for_status()
-        data = r.json().get("data", [])
-        # NV-Embed returns [{embedding: [...]}, ...]
-        return [d["embedding"] for d in data]
+        return _embed_client().embed_batch(texts)
     except Exception as e:
         log.warning(f"NV-Embed batch failed: {e}; trying singletons")
         return [get_embedding(t) for t in texts]

package/packages/memory-engine/engine/services/l4/Dockerfile

@@ -4,7 +4,11 @@ WORKDIR /app
 
 RUN pip install --no-cache-dir fastapi 'uvicorn[standard]' httpx pydantic
 
-COPY server.py /app/server.py
+# Build context is engine/services so the shared embed_provider module is
+# COPYable. server.py adds engine/services to sys.path at startup, then
+# imports from `_shared.embed_provider`.
+COPY _shared /app/_shared
+COPY l4/server.py /app/server.py
 
 RUN mkdir -p /data
 ENV L4_DB_PATH=/data/vec.db

package/packages/memory-engine/engine/services/l4/server.py

@@ -23,27 +23,25 @@ import hashlib
 import os
 import sqlite3
 import struct
+import sys
 import time
 from pathlib import Path
 from typing import Any
 
-import httpx
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel
 
+# Shared embedding client lives at engine/services/_shared/. Add the parent of
+# the service dir to sys.path so `from _shared.embed_provider import ...` works
+# regardless of how the service is launched (uvicorn, python server.py, etc.).
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from _shared.embed_provider import EmbedClient  # noqa: E402
+
 # ----------------------------------------------------------------------
 # Config
 # ----------------------------------------------------------------------
 
 DB_PATH = os.environ.get("L4_DB_PATH", "/data/vec.db")
-NV_EMBED_URL = os.environ.get("L4_NV_EMBED_URL", "http://nv-embed:8041/v1/embeddings")
-# Embedding model name sent in /v1/embeddings request body. Defaults to
-# the production NV-Embed-v2 name; override via env when pointing at a
-# different OpenAI-compat endpoint (e.g. Ollama with nomic-embed-text).
-EMBED_MODEL_NAME = os.environ.get("L4_EMBED_MODEL", "nv-embed-v2")
-# Optional Authorization: Bearer <key> for the embedding endpoint.
-# Set when calling a hosted gateway (e.g. pentatonic-ai-gateway). Empty = no auth.
-EMBED_API_KEY = os.environ.get("L4_EMBED_API_KEY", "")
 EMBED_DIM = int(os.environ.get("L4_EMBED_DIM", "4096"))
 
 
@@ -96,59 +94,23 @@ def _get_db() -> sqlite3.Connection:
 # Embedding client
 # ----------------------------------------------------------------------
 
-_http: httpx.AsyncClient | None = None
+_embed: EmbedClient | None = None
 
 
-def _client() -> httpx.AsyncClient:
-    global _http
-    if _http is None:
-        _http = httpx.AsyncClient(timeout=120.0)
-    return _http
+def _embed_client() -> EmbedClient:
+    """Lazily build the embed client so env vars are read at first use."""
+    global _embed
+    if _embed is None:
+        _embed = EmbedClient.from_env(
+            prefix="L4_",
+            default_url="http://nv-embed:8041/v1/embeddings",
+        )
+    return _embed
 
 
 async def _embed_batch(texts: list[str]) -> list[list[float]]:
-    """Embed a batch of texts.
-
-    Tries OpenAI-compatible shape first (POST <url>, Bearer auth,
-    response data[i].embedding). On failure, falls back to the
-    Pentatonic-AI gateway's native shape (POST .../v1/embed, X-API-Key
-    auth, response embeddings[i]). When the gateway eventually adds an
-    OpenAI-compat /v1/embeddings alias, the primary path will succeed
-    and the fallback will never fire — no code change needed.
-    """
-    if not texts:
-        return []
-    payload = {"input": texts, "model": EMBED_MODEL_NAME}
-    # Primary: OpenAI-compat
-    try:
-        resp = await _client().post(
-            NV_EMBED_URL,
-            headers=_openai_headers(),
-            json=payload,
-            timeout=120.0,
-        )
-        resp.raise_for_status()
-        return [d["embedding"] for d in resp.json()["data"]]
-    except Exception:
-        pass
-    # Fallback: lambda-gateway native shape
-    fallback_url = NV_EMBED_URL.replace("/v1/embeddings", "/v1/embed").replace("/embeddings", "/embed")
-    resp = await _client().post(
-        fallback_url,
-        headers=_lambda_headers(),
-        json=payload,
-        timeout=120.0,
-    )
-    resp.raise_for_status()
-    return resp.json()["embeddings"]
-
-
-def _openai_headers() -> dict:
-    return {"Authorization": f"Bearer {EMBED_API_KEY}"} if EMBED_API_KEY else {}
-
-
-def _lambda_headers() -> dict:
-    return {"X-API-Key": EMBED_API_KEY} if EMBED_API_KEY else {}
+    """Embed a batch of texts via the shared EmbedClient."""
+    return await _embed_client().embed_batch_async(texts)
 
 
 # ----------------------------------------------------------------------

package/packages/memory-engine/engine/services/l5/Dockerfile

@@ -1,7 +1,9 @@
 FROM python:3.12-slim
 WORKDIR /app
 RUN pip install --no-cache-dir fastapi "uvicorn[standard]" httpx "pymilvus[milvus_lite]" "setuptools<70" pydantic
-COPY l5-comms-layer.py /app/server.py
+# Shared embed_provider module (build context is engine/services).
+COPY _shared /app/_shared
+COPY l5/l5-comms-layer.py /app/server.py
 RUN mkdir -p /data
 ENV L5_DB_PATH=/data/comms.db
 EXPOSE 8034

package/packages/memory-engine/engine/services/l5/l5-comms-layer.py

@@ -23,6 +23,7 @@ import os
 import glob
 import hashlib
 import json
+import sys
 import time
 from datetime import datetime
 from pathlib import Path
@@ -30,6 +31,10 @@ from pathlib import Path
 import httpx
 from pymilvus import MilvusClient, DataType, CollectionSchema, FieldSchema
 
+# Shared embed client lives at engine/services/_shared/.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from _shared.embed_provider import EmbedClient  # noqa: E402
+
 # --- Config ---
 DB_PATH = os.environ.get(
     "L5_DB_PATH",
@@ -43,43 +48,30 @@ PEOPLE_DIR = WORKSPACE / "memory" / "people"
 CONTACTS_DIR = WORKSPACE / "memory" / "contacts"
 MEMORY_DIR = WORKSPACE / "memory"
 
-NV_EMBED_URL = os.environ.get("L5_NV_EMBED_URL", "http://localhost:8041/v1/embeddings")
-# Embedding model name sent in /v1/embeddings request body. Defaults to
-# the production NV-Embed-v2 name; override when pointing at a different
-# OpenAI-compat endpoint (e.g. Ollama with nomic-embed-text).
-EMBED_MODEL_NAME = os.environ.get("L5_EMBED_MODEL", "nv-embed-v2")
-# Optional Authorization: Bearer <key> for the primary embedding endpoint.
-EMBED_API_KEY = os.environ.get("L5_EMBED_API_KEY", "")
+_embed: EmbedClient | None = None
+
+
+def _embed_client() -> EmbedClient:
+    """Lazily build the shared EmbedClient for L5."""
+    global _embed
+    if _embed is None:
+        _embed = EmbedClient.from_env(
+            prefix="L5_",
+            default_url="http://localhost:8041/v1/embeddings",
+        )
+    return _embed
+
 
 def _embed_post(texts):
-    """POST to the configured embedding endpoint. Tries OpenAI-compat
-    shape first; falls back to Pentatonic-AI lambda-gateway native shape
-    on any failure. When the gateway adds an /v1/embeddings alias the
-    primary path will succeed and the fallback never fires.
+    """Embed a batch of texts via the shared EmbedClient.
+
+    Provider profile (auth scheme + URL path + body/response shape) is
+    chosen by L5_EMBED_PROVIDER env var (openai | pentatonic-gateway |
+    cohere | custom). Auto-detects on 401 unless L5_EMBED_AUTODETECT=false.
 
     Returns: list[list[float]] (one embedding per input text).
     """
-    payload = {"input": texts, "model": EMBED_MODEL_NAME}
-    try:
-        r = httpx.post(
-            NV_EMBED_URL,
-            headers={"Authorization": f"Bearer {EMBED_API_KEY}"} if EMBED_API_KEY else {},
-            json=payload,
-            timeout=120,
-        )
-        r.raise_for_status()
-        return [d["embedding"] for d in r.json()["data"]]
-    except Exception:
-        pass
-    fallback_url = NV_EMBED_URL.replace("/v1/embeddings", "/v1/embed").replace("/embeddings", "/embed")
-    r = httpx.post(
-        fallback_url,
-        headers={"X-API-Key": EMBED_API_KEY} if EMBED_API_KEY else {},
-        json=payload,
-        timeout=120,
-    )
-    r.raise_for_status()
-    return r.json()["embeddings"]
+    return _embed_client().embed_batch(texts)
 
 # Ollama fallback path. URL/model can be overridden so the L5 container can
 # reach an Ollama instance running on the docker host (host.docker.internal)

package/packages/memory-engine/engine/services/l6/Dockerfile

@@ -3,7 +3,9 @@ WORKDIR /app
 RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
 RUN pip install --no-cache-dir fastapi "uvicorn[standard]" httpx "pymilvus[milvus_lite]" "setuptools<70" pydantic spacy
 RUN python -m spacy download en_core_web_sm
-COPY l6-document-store.py /app/server.py
+# Shared embed_provider module (build context is engine/services).
+COPY _shared /app/_shared
+COPY l6/l6-document-store.py /app/server.py
 RUN mkdir -p /data
 ENV L6_DATA_DIR=/data
 EXPOSE 8037

package/packages/memory-engine/engine/services/l6/l6-document-store.py

@@ -20,6 +20,7 @@ import logging
 import os
 import re
 import sqlite3
+import sys
 import time
 from datetime import datetime, timezone
 from pathlib import Path
@@ -29,6 +30,10 @@ import httpx
 from pymilvus import MilvusClient, DataType, CollectionSchema, FieldSchema
 from pymilvus.milvus_client.index import IndexParams
 
+# Shared embed client lives at engine/services/_shared/.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from _shared.embed_provider import EmbedClient  # noqa: E402
+
 # ---------------------------------------------------------------------------
 # Config
 # ---------------------------------------------------------------------------
@@ -37,39 +42,29 @@ DATA_DIR = Path(os.environ.get("L6_DATA_DIR", str(Path.home() / "l6-document-sto
 MILVUS_DB = str(DATA_DIR / "documents.db")
 FTS_DB = str(DATA_DIR / "documents_fts.db")
 OLLAMA_URL = os.environ.get("L6_OLLAMA_URL", "http://localhost:11434")
-EMBED_MODEL = os.environ.get("L6_EMBED_MODEL", "nomic-embed-text")
-NV_EMBED_URL = os.environ.get("L6_NV_EMBED_URL", "http://localhost:8041/v1/embeddings")
 NV_EMBED_ENABLED = os.environ.get("L6_NV_EMBED_ENABLED", "true").lower() == "true"
 EMBED_DIM = int(os.environ.get("L6_EMBED_DIM", "4096"))
-# Optional Authorization: Bearer <key> for the embedding endpoint.
-EMBED_API_KEY = os.environ.get("L6_EMBED_API_KEY", "")
 
-def _embed_post(texts):
-    """POST to embedding endpoint. Tries OpenAI-compat shape first;
-    falls back to Pentatonic-AI lambda-gateway native shape on failure.
-    See L4 / L5 for the same pattern."""
-    import httpx as _httpx
-    payload = {"input": texts, "model": EMBED_MODEL}
-    try:
-        r = _httpx.post(
-            NV_EMBED_URL,
-            headers={"Authorization": f"Bearer {EMBED_API_KEY}"} if EMBED_API_KEY else {},
-            json=payload,
-            timeout=120,
+_embed: EmbedClient | None = None
+
+
+def _embed_client() -> EmbedClient:
+    """Lazily build the shared EmbedClient for L6."""
+    global _embed
+    if _embed is None:
+        _embed = EmbedClient.from_env(
+            prefix="L6_",
+            default_url="http://localhost:8041/v1/embeddings",
+            default_model="nomic-embed-text",
         )
-        r.raise_for_status()
-        return [d["embedding"] for d in r.json()["data"]]
-    except Exception:
-        pass
-    fallback_url = NV_EMBED_URL.replace("/v1/embeddings", "/v1/embed").replace("/embeddings", "/embed")
-    r = _httpx.post(
-        fallback_url,
-        headers={"X-API-Key": EMBED_API_KEY} if EMBED_API_KEY else {},
-        json=payload,
-        timeout=120,
-    )
-    r.raise_for_status()
-    return r.json()["embeddings"]
+    return _embed
+
+
+def _embed_post(texts):
+    """Embed a batch of texts via the shared EmbedClient. Provider profile
+    chosen by L6_EMBED_PROVIDER env (openai | pentatonic-gateway | cohere
+    | custom). See engine/services/_shared/embed_provider.py for details."""
+    return _embed_client().embed_batch(texts)
 
 COLLECTION_NAME = "documents"
 RRF_K = 60

package/packages/memory-engine/tests/test_embed_provider.py

@@ -0,0 +1,354 @@
+"""Unit tests for engine/services/_shared/embed_provider.py.
+
+Run with:
+    cd packages/memory-engine
+    python -m pytest tests/test_embed_provider.py -v
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Make the engine/services tree importable for tests without packaging it.
+ROOT = Path(__file__).parent.parent / "engine" / "services"
+sys.path.insert(0, str(ROOT))
+
+import json  # noqa: E402
+
+import httpx  # noqa: E402
+import pytest  # noqa: E402
+
+from _shared.embed_provider import (  # noqa: E402
+    PROVIDERS,
+    EmbedAuthError,
+    EmbedClient,
+    EmbedHTTPError,
+    EmbedProvider,
+    resolve_provider,
+)
+
+
+# ----------------------------------------------------------------------
+# Helpers — stub httpx so we can assert the request shape.
+# ----------------------------------------------------------------------
+
+class _FakeResponse:
+    def __init__(self, status_code: int, payload: dict | str = ""):
+        self.status_code = status_code
+        if isinstance(payload, dict):
+            self._json = payload
+            self.text = json.dumps(payload)
+        else:
+            self._json = None
+            self.text = payload
+
+    @property
+    def is_success(self) -> bool:
+        return 200 <= self.status_code < 300
+
+    def json(self) -> dict:
+        if self._json is None:
+            raise ValueError("not json")
+        return self._json
+
+
+class _Recorder:
+    """Records every httpx.post call and returns canned responses keyed by URL."""
+
+    def __init__(self):
+        self.calls: list[dict] = []
+        self.responses: dict[str, _FakeResponse] = {}
+
+    def respond(self, url: str, response: _FakeResponse) -> None:
+        self.responses[url] = response
+
+    def __call__(self, url, *, json, headers, timeout):
+        self.calls.append({"url": url, "json": json, "headers": headers, "timeout": timeout})
+        if url in self.responses:
+            return self.responses[url]
+        # default: 401 to flush out unmatched URLs
+        return _FakeResponse(401, "no stub for this url")
+
+
+@pytest.fixture
+def recorder(monkeypatch):
+    rec = _Recorder()
+    monkeypatch.setattr(httpx, "post", rec)
+    return rec
+
+
+# ----------------------------------------------------------------------
+# Provider resolution
+# ----------------------------------------------------------------------
+
+def test_resolve_built_in_providers():
+    for name in ("openai", "pentatonic-gateway", "cohere"):
+        p = resolve_provider(name)
+        assert p.name == name
+
+
+def test_resolve_unknown_provider_raises():
+    with pytest.raises(ValueError):
+        resolve_provider("not-a-provider")
+
+
+def test_resolve_custom_provider_from_env(monkeypatch):
+    monkeypatch.setenv("L4_EMBED_AUTH_HEADER", "X-Custom-Auth")
+    monkeypatch.setenv("L4_EMBED_AUTH_FORMAT", "Token {key}")
+    monkeypatch.setenv("L4_EMBED_PATH_DEFAULT", "/embed")
+    monkeypatch.setenv("L4_EMBED_BODY_SHAPE", "cohere")
+    monkeypatch.setenv("L4_EMBED_RESPONSE_SHAPE", "cohere")
+    p = resolve_provider("custom", env_prefix="L4_")
+    assert p.auth_header == "X-Custom-Auth"
+    assert p.auth_format == "Token {key}"
+    assert p.path_default == "/embed"
+    # body shape produces Cohere-style "texts" field
+    body = p.body_builder(["hi"], "model-x")
+    assert body == {"texts": ["hi"], "model": "model-x", "input_type": "search_document"}
+
+
+# ----------------------------------------------------------------------
+# Request shape
+# ----------------------------------------------------------------------
+
+def test_openai_provider_request_shape(recorder):
+    recorder.respond(
+        "https://gw/v1/embeddings",
+        _FakeResponse(200, {"data": [{"embedding": [0.1, 0.2]}]}),
+    )
+    client = EmbedClient(
+        url="https://gw/v1/embeddings",
+        api_key="k",
+        model="m",
+        provider=PROVIDERS["openai"],
+    )
+    out = client.embed_batch(["hello"])
+    assert out == [[0.1, 0.2]]
+    call = recorder.calls[0]
+    assert call["url"] == "https://gw/v1/embeddings"
+    assert call["json"] == {"input": ["hello"], "model": "m"}
+    assert call["headers"] == {"Authorization": "Bearer k"}
+
+
+def test_pentatonic_provider_request_shape(recorder):
+    recorder.respond(
+        "https://lambda-gateway.pentatonic.com/v1/embed",
+        _FakeResponse(200, {"data": [{"embedding": [1.0, 2.0]}]}),
+    )
+    client = EmbedClient(
+        url="https://lambda-gateway.pentatonic.com/v1/embed",
+        api_key="secret",
+        model="nv-embed-v2",
+        provider=PROVIDERS["pentatonic-gateway"],
+    )
+    out = client.embed_batch(["t1"])
+    assert out == [[1.0, 2.0]]
+    call = recorder.calls[0]
+    assert call["url"] == "https://lambda-gateway.pentatonic.com/v1/embed"
+    assert call["json"] == {"input": ["t1"], "model": "nv-embed-v2"}
+    assert call["headers"] == {"X-API-Key": "secret"}
+
+
+def test_pentatonic_response_parser_handles_both_shapes(recorder):
+    """Pentatonic Gateway has historically returned both {"data":[...]} and
+    {"embeddings":[...]} on different endpoints. Parser accepts either."""
+    p = PROVIDERS["pentatonic-gateway"]
+    assert p.response_parser({"data": [{"embedding": [1.0]}]}) == [[1.0]]
+    assert p.response_parser({"embeddings": [[1.0]]}) == [[1.0]]
+
+
+def test_cohere_provider_request_shape(recorder):
+    recorder.respond(
+        "https://api.cohere.ai/v1/embed",
+        _FakeResponse(200, {"embeddings": [[3.0, 4.0]]}),
+    )
+    client = EmbedClient(
+        url="https://api.cohere.ai/v1/embed",
+        api_key="cohere-key",
+        model="embed-english-v3.0",
+        provider=PROVIDERS["cohere"],
+    )
+    out = client.embed_batch(["hi"])
+    assert out == [[3.0, 4.0]]
+    call = recorder.calls[0]
+    assert call["json"] == {
+        "texts": ["hi"],
+        "model": "embed-english-v3.0",
+        "input_type": "search_document",
+    }
+    assert call["headers"] == {"Authorization": "Bearer cohere-key"}
+
+
+# ----------------------------------------------------------------------
+# Auto-detect
+# ----------------------------------------------------------------------
+
+def test_autodetect_on_401_falls_back_to_pentatonic(recorder):
+    """Operator configured openai but the URL+key actually belong to
+    Pentatonic Gateway. First call 401s, auto-detect probes pentatonic
+    and succeeds."""
+    recorder.respond(
+        "https://lambda-gateway.pentatonic.com/v1/embeddings",
+        _FakeResponse(401, '{"error":"Invalid or missing API key"}'),
+    )
+    recorder.respond(
+        "https://lambda-gateway.pentatonic.com/v1/embed",
+        _FakeResponse(200, {"data": [{"embedding": [9.0]}]}),
+    )
+    client = EmbedClient(
+        url="https://lambda-gateway.pentatonic.com/v1/embeddings",
+        api_key="k",
+        model="nv-embed-v2",
+        provider=PROVIDERS["openai"],
+    )
+    out = client.embed_batch(["x"])
+    assert out == [[9.0]]
+    assert client.active_provider == "pentatonic-gateway"
+    # First call uses configured (openai) shape, second uses pentatonic
+    assert recorder.calls[0]["headers"] == {"Authorization": "Bearer k"}
+    assert recorder.calls[1]["headers"] == {"X-API-Key": "k"}
+
+
+def test_autodetect_caches_after_first_success(recorder):
+    """Once auto-detect picks a winner, subsequent calls go straight to it
+    without retrying the original 401."""
+    recorder.respond(
+        "https://gw/v1/embeddings",
+        _FakeResponse(401, "wrong scheme"),
+    )
+    recorder.respond(
+        "https://gw/v1/embed",
+        _FakeResponse(200, {"data": [{"embedding": [1.0]}]}),
+    )
+    client = EmbedClient(
+        url="https://gw/v1/embeddings",
+        api_key="k",
+        model="m",
+        provider=PROVIDERS["openai"],
+    )
+    client.embed_batch(["a"])  # triggers detect
+    n_after_first = len(recorder.calls)
+    client.embed_batch(["b"])  # should go straight to /v1/embed
+    assert len(recorder.calls) == n_after_first + 1
+    assert recorder.calls[-1]["url"] == "https://gw/v1/embed"
+
+
+def test_autodetect_disabled_raises(recorder):
+    recorder.respond("https://gw/v1/embeddings", _FakeResponse(401, "no auth"))
+    client = EmbedClient(
+        url="https://gw/v1/embeddings",
+        api_key="k",
+        model="m",
+        provider=PROVIDERS["openai"],
+        autodetect=False,
+    )
+    with pytest.raises(EmbedAuthError):
+        client.embed_batch(["x"])
+    # Only one call: no probing happened.
+    assert len(recorder.calls) == 1
+
+
+def test_autodetect_all_fail_raises(recorder):
+    """Every candidate also 401s — raise EmbedAuthError."""
+    recorder.respond("https://gw/v1/embeddings", _FakeResponse(401, "x"))
+    recorder.respond("https://gw/v1/embed", _FakeResponse(401, "x"))
+    client = EmbedClient(
+        url="https://gw/v1/embeddings",
+        api_key="k",
+        model="m",
+        provider=PROVIDERS["openai"],
+    )
+    with pytest.raises(EmbedAuthError):
+        client.embed_batch(["x"])
+
+
+# ----------------------------------------------------------------------
+# Error handling
+# ----------------------------------------------------------------------
+
+def test_non_401_http_error_does_not_trigger_autodetect(recorder):
+    recorder.respond(
+        "https://gw/v1/embeddings",
+        _FakeResponse(503, "upstream down"),
+    )
+    client = EmbedClient(
+        url="https://gw/v1/embeddings",
+        api_key="k",
+        model="m",
+        provider=PROVIDERS["openai"],
+    )
+    with pytest.raises(EmbedHTTPError) as exc:
+        client.embed_batch(["x"])
+    assert exc.value.status == 503
+    assert len(recorder.calls) == 1
+
+
+def test_empty_input_returns_empty(recorder):
+    client = EmbedClient(
+        url="https://gw/v1/embeddings",
+        api_key="k",
+        model="m",
+        provider=PROVIDERS["openai"],
+    )
+    assert client.embed_batch([]) == []
+    assert recorder.calls == []
+
+
+# ----------------------------------------------------------------------
+# from_env construction
+# ----------------------------------------------------------------------
+
+def test_from_env_reads_layer_prefix(monkeypatch, recorder):
+    monkeypatch.setenv("L4_NV_EMBED_URL", "https://lambda-gateway.pentatonic.com/v1/embed")
+    monkeypatch.setenv("L4_EMBED_API_KEY", "real-key")
+    monkeypatch.setenv("L4_EMBED_MODEL", "nv-embed-v2")
+    monkeypatch.setenv("L4_EMBED_PROVIDER", "pentatonic-gateway")
+    recorder.respond(
+        "https://lambda-gateway.pentatonic.com/v1/embed",
+        _FakeResponse(200, {"data": [{"embedding": [42.0]}]}),
+    )
+    client = EmbedClient.from_env(prefix="L4_")
+    out = client.embed_batch(["t"])
+    assert out == [[42.0]]
+    assert client.active_provider == "pentatonic-gateway"
+    assert recorder.calls[0]["headers"] == {"X-API-Key": "real-key"}
+
+
+def test_from_env_default_provider_is_openai(monkeypatch):
+    monkeypatch.setenv("L5_NV_EMBED_URL", "https://gw/v1/embeddings")
+    monkeypatch.setenv("L5_EMBED_API_KEY", "k")
+    client = EmbedClient.from_env(prefix="L5_")
+    assert client.active_provider == "openai"
+
+
+def test_from_env_autodetect_opt_out(monkeypatch, recorder):
+    monkeypatch.setenv("L4_NV_EMBED_URL", "https://gw/v1/embeddings")
+    monkeypatch.setenv("L4_EMBED_API_KEY", "k")
+    monkeypatch.setenv("L4_EMBED_AUTODETECT", "false")
+    recorder.respond("https://gw/v1/embeddings", _FakeResponse(401, "x"))
+    client = EmbedClient.from_env(prefix="L4_")
+    with pytest.raises(EmbedAuthError):
+        client.embed_batch(["x"])
+    assert len(recorder.calls) == 1
+
+
+# ----------------------------------------------------------------------
+# URL handling
+# ----------------------------------------------------------------------
+
+def test_url_without_path_gets_provider_default(recorder):
+    """If operator provides only a base URL, the provider's path_default
+    is appended."""
+    recorder.respond(
+        "https://lambda-gateway.pentatonic.com/v1/embed",
+        _FakeResponse(200, {"data": [{"embedding": [0.0]}]}),
+    )
+    client = EmbedClient(
+        url="https://lambda-gateway.pentatonic.com",
+        api_key="k",
+        model="m",
+        provider=PROVIDERS["pentatonic-gateway"],
+    )
+    client.embed_batch(["x"])
+    assert recorder.calls[0]["url"] == "https://lambda-gateway.pentatonic.com/v1/embed"