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

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

@@ -0,0 +1,308 @@
+"""Integration tests for ChannelStat rollup writes + reader fast-path.
+
+These exercise the actual Cypher running against a live Neo4j: the
+writer block in /index-internal-batch maintains (:ChannelStat) nodes
+on every store with contact_email metadata, and /aggregate-internal
+reads from those nodes when present (falling back to the edge walk
+when stats haven't been populated yet).
+
+Gated on NEO4J_TEST_URI + NEO4J_TEST_PASSWORD; skip cleanly when
+those env vars are absent so unit-only test runs stay fast.
+
+Run:
+
+    cd packages/memory-engine
+    NEO4J_TEST_URI=bolt://localhost:17687 \\
+    NEO4J_TEST_PASSWORD=testpassword \\
+    .venv/bin/python -m pytest tests/test_channel_stat_rollups.py -v
+"""
+from __future__ import annotations
+
+import os
+import uuid
+
+import pytest
+
+
+_NEO4J_URI = os.environ.get("NEO4J_TEST_URI")
+_NEO4J_USER = os.environ.get("NEO4J_TEST_USER", "neo4j")
+_NEO4J_PASSWORD = os.environ.get("NEO4J_TEST_PASSWORD")
+
+_skip_no_neo4j = pytest.mark.skipif(
+    not (_NEO4J_URI and _NEO4J_PASSWORD),
+    reason="set NEO4J_TEST_URI + NEO4J_TEST_PASSWORD to run integration tests",
+)
+
+
+@pytest.fixture
+def neo4j_driver():
+    """Per-test driver + cleanup. Two arenas so isolation tests can
+    run side by side without trampling each other."""
+    from neo4j import GraphDatabase
+
+    driver = GraphDatabase.driver(_NEO4J_URI, auth=(_NEO4J_USER, _NEO4J_PASSWORD))
+    arenas = [f"stat_a_{uuid.uuid4().hex[:8]}", f"stat_b_{uuid.uuid4().hex[:8]}"]
+    yield driver, arenas
+    with driver.session() as session:
+        for arena in arenas:
+            # ChannelStat lives alongside Person/Chunk in the arena;
+            # the per-arena DETACH DELETE catches all of them.
+            session.run(
+                "MATCH (n) WHERE n.arena = $arena DETACH DELETE n",
+                arena=arena,
+            )
+    driver.close()
+
+
+def _store_chunk_with_email(
+    session,
+    arena: str,
+    cid: str,
+    email: str,
+    channel: str,
+    direction: str,
+    occurred_at: str,
+) -> None:
+    """Mirror exactly the Cypher /index-internal-batch runs for the
+    email-keyed Person path, including the ChannelStat rollup. The
+    real call sites this is testing are inside that endpoint; this
+    helper lets the integration test exercise the same Cypher
+    without spinning up the FastAPI app."""
+    now_iso = "2026-05-10T00:00:00Z"
+    # Ensure the chunk exists (matches what /index-internal-batch
+    # does immediately before writing the Person edge).
+    session.run(
+        """
+        MERGE (c:Chunk {id: $cid})
+        SET c.text = 't', c.path = 'p', c.arena = $arena,
+            c.created_at = $now
+        """,
+        cid=cid, arena=arena, now=now_iso,
+    )
+    session.run(
+        """
+        MERGE (p:Entity:Person {arena: $arena, email: $email})
+        ON CREATE SET p.created_at = $now,
+                      p.first_seen = $occurred_at,
+                      p.last_seen = $occurred_at
+        ON MATCH SET p.last_seen = CASE
+              WHEN $occurred_at > coalesce(p.last_seen, '')
+                THEN $occurred_at
+              ELSE p.last_seen END
+        WITH p
+        MATCH (c:Chunk {arena: $arena, id: $cid})
+        MERGE (p)-[r:COMMUNICATED]->(c)
+        ON CREATE SET r.channel = $channel,
+                      r.direction = $direction,
+                      r.occurred_at = $occurred_at,
+                      r.weight = 1.0,
+                      r._counted = false
+        WITH p, r
+        FOREACH (_ IN CASE WHEN r._counted = false THEN [1] ELSE [] END |
+          MERGE (s:ChannelStat {arena: $arena, person_email: $email, channel: $channel})
+          ON CREATE SET s.count = 0,
+                        s.inbound = 0,
+                        s.outbound = 0,
+                        s.first_seen = $occurred_at,
+                        s.last_seen = $occurred_at,
+                        s.created_at = $now
+          SET s.count = s.count + 1,
+              s.inbound = s.inbound + (CASE WHEN $direction = 'inbound' THEN 1 ELSE 0 END),
+              s.outbound = s.outbound + (CASE WHEN $direction = 'outbound' THEN 1 ELSE 0 END),
+              s.first_seen = CASE
+                WHEN $occurred_at < coalesce(s.first_seen, $occurred_at)
+                  THEN $occurred_at
+                ELSE s.first_seen END,
+              s.last_seen = CASE
+                WHEN $occurred_at > coalesce(s.last_seen, '')
+                  THEN $occurred_at
+                ELSE s.last_seen END,
+              s.updated_at = $now
+          MERGE (p)-[:HAS_STAT]->(s)
+          SET r._counted = true
+        )
+        """,
+        arena=arena, email=email, cid=cid,
+        channel=channel, direction=direction,
+        occurred_at=occurred_at, now=now_iso,
+    )
+
+
+def _read_stats(session, arena: str, email: str) -> list[dict]:
+    return [
+        dict(rec)
+        for rec in session.run(
+            "MATCH (s:ChannelStat {arena: $arena, person_email: $email})\n"
+            "RETURN s.channel AS channel, s.count AS count,\n"
+            "       s.inbound AS inbound, s.outbound AS outbound,\n"
+            "       s.first_seen AS first_seen, s.last_seen AS last_seen\n"
+            "ORDER BY s.channel\n",
+            arena=arena, email=email,
+        )
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Writer behaviour.
+# ---------------------------------------------------------------------------
+
+
+@_skip_no_neo4j
+def test_first_store_creates_channelstat_with_count_one(neo4j_driver) -> None:
+    driver, (arena, _) = neo4j_driver
+    with driver.session() as session:
+        _store_chunk_with_email(
+            session, arena, cid="c1", email="alex@x.io",
+            channel="email", direction="inbound",
+            occurred_at="2026-05-09T10:00:00Z",
+        )
+        stats = _read_stats(session, arena, "alex@x.io")
+        assert len(stats) == 1
+        assert stats[0]["channel"] == "email"
+        assert stats[0]["count"] == 1
+        assert stats[0]["inbound"] == 1
+        assert stats[0]["outbound"] == 0
+        assert stats[0]["first_seen"] == "2026-05-09T10:00:00Z"
+        assert stats[0]["last_seen"] == "2026-05-09T10:00:00Z"
+
+
+@_skip_no_neo4j
+def test_repeated_stores_accumulate_counts_and_widen_time_bounds(neo4j_driver) -> None:
+    driver, (arena, _) = neo4j_driver
+    with driver.session() as session:
+        _store_chunk_with_email(
+            session, arena, cid="c1", email="alex@x.io",
+            channel="email", direction="inbound",
+            occurred_at="2026-05-08T09:00:00Z",
+        )
+        _store_chunk_with_email(
+            session, arena, cid="c2", email="alex@x.io",
+            channel="email", direction="outbound",
+            occurred_at="2026-05-09T10:00:00Z",
+        )
+        _store_chunk_with_email(
+            session, arena, cid="c3", email="alex@x.io",
+            channel="email", direction="inbound",
+            occurred_at="2026-05-07T08:00:00Z",  # earliest — should drive first_seen
+        )
+        stats = _read_stats(session, arena, "alex@x.io")
+        assert len(stats) == 1
+        assert stats[0]["count"] == 3
+        assert stats[0]["inbound"] == 2
+        assert stats[0]["outbound"] == 1
+        assert stats[0]["first_seen"] == "2026-05-07T08:00:00Z"
+        assert stats[0]["last_seen"] == "2026-05-09T10:00:00Z"
+
+
+@_skip_no_neo4j
+def test_per_channel_buckets_kept_separate(neo4j_driver) -> None:
+    driver, (arena, _) = neo4j_driver
+    with driver.session() as session:
+        _store_chunk_with_email(
+            session, arena, "c1", "alex@x.io",
+            "email", "inbound", "2026-05-09T10:00:00Z",
+        )
+        _store_chunk_with_email(
+            session, arena, "c2", "alex@x.io",
+            "slack", "outbound", "2026-05-09T11:00:00Z",
+        )
+        _store_chunk_with_email(
+            session, arena, "c3", "alex@x.io",
+            "slack", "inbound", "2026-05-09T12:00:00Z",
+        )
+        stats = sorted(_read_stats(session, arena, "alex@x.io"), key=lambda s: s["channel"])
+        assert [s["channel"] for s in stats] == ["email", "slack"]
+        email = next(s for s in stats if s["channel"] == "email")
+        slack = next(s for s in stats if s["channel"] == "slack")
+        assert email["count"] == 1
+        assert slack["count"] == 2
+        assert slack["inbound"] == 1
+        assert slack["outbound"] == 1
+
+
+@_skip_no_neo4j
+def test_replay_of_same_chunk_does_not_double_count(neo4j_driver) -> None:
+    """Idempotency under retry: storing the same (chunk_id, email)
+    twice should not double the count. Guarded by the r._counted
+    flag set on first edge creation."""
+    driver, (arena, _) = neo4j_driver
+    with driver.session() as session:
+        for _ in range(3):
+            _store_chunk_with_email(
+                session, arena, "c1", "alex@x.io",
+                "email", "inbound", "2026-05-09T10:00:00Z",
+            )
+        stats = _read_stats(session, arena, "alex@x.io")
+        assert len(stats) == 1
+        # Three identical stores → still count == 1.
+        assert stats[0]["count"] == 1
+        assert stats[0]["inbound"] == 1
+
+
+@_skip_no_neo4j
+def test_arena_isolation_on_channelstat(neo4j_driver) -> None:
+    """A's stats never reflect B's writes, even when both arenas
+    have the same email — the multi-tenancy invariant that #28
+    landed for Person/Chunk extends to ChannelStat."""
+    driver, (arena_a, arena_b) = neo4j_driver
+    with driver.session() as session:
+        _store_chunk_with_email(
+            session, arena_a, "c1", "shared@example.com",
+            "email", "inbound", "2026-05-09T10:00:00Z",
+        )
+        _store_chunk_with_email(
+            session, arena_b, "c2", "shared@example.com",
+            "email", "inbound", "2026-05-09T11:00:00Z",
+        )
+        _store_chunk_with_email(
+            session, arena_b, "c3", "shared@example.com",
+            "slack", "outbound", "2026-05-09T12:00:00Z",
+        )
+        a_stats = _read_stats(session, arena_a, "shared@example.com")
+        b_stats = _read_stats(session, arena_b, "shared@example.com")
+        # A only saw the email message.
+        assert len(a_stats) == 1
+        assert a_stats[0]["channel"] == "email"
+        assert a_stats[0]["count"] == 1
+        # B saw both.
+        assert len(b_stats) == 2
+
+
+@_skip_no_neo4j
+def test_communicated_edge_has_counted_flag_after_write(neo4j_driver) -> None:
+    """The idempotency flag must be true after the first store so
+    re-runs of the writer (which use the same MERGE pattern) skip
+    the increment subquery."""
+    driver, (arena, _) = neo4j_driver
+    with driver.session() as session:
+        _store_chunk_with_email(
+            session, arena, "c1", "alex@x.io",
+            "email", "inbound", "2026-05-09T10:00:00Z",
+        )
+        rec = session.run(
+            "MATCH (:Person {arena: $arena, email: $email})-[r:COMMUNICATED]->(:Chunk {arena: $arena, id: $cid})\n"
+            "RETURN r._counted AS counted",
+            arena=arena, email="alex@x.io", cid="c1",
+        ).single()
+        assert rec["counted"] is True
+
+
+@_skip_no_neo4j
+def test_has_stat_edge_links_person_to_channelstat(neo4j_driver) -> None:
+    """The Person→ChannelStat traversal exists for ops queries
+    ('show me all stat rollups for this person') and for cascade
+    deletes when a tenant is offboarded."""
+    driver, (arena, _) = neo4j_driver
+    with driver.session() as session:
+        _store_chunk_with_email(
+            session, arena, "c1", "alex@x.io",
+            "email", "inbound", "2026-05-09T10:00:00Z",
+        )
+        rows = list(session.run(
+            "MATCH (p:Person {arena: $arena, email: $email})-[:HAS_STAT]->(s:ChannelStat {arena: $arena})\n"
+            "RETURN s.channel AS channel, s.count AS count\n",
+            arena=arena, email="alex@x.io",
+        ))
+        assert len(rows) == 1
+        assert rows[0]["channel"] == "email"
+        assert rows[0]["count"] == 1

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"