@pentatonic-ai/ai-agent-sdk 0.9.5 → 0.10.0

package/packages/memory-engine/compat/server.py

@@ -1,1255 +0,0 @@
-"""
-pentatonic-memory-engine compatibility shim.
-
-Exposes the same HTTP API as `pentatonic-memory` v0.5.x (POST /store,
-POST /search, GET /health) plus the v0.6 regression-fix endpoints
-(POST /store-batch, POST /forget). Internally routes every call through
-the 7-layer hybrid retrieval engine running in sibling containers
-(L0 BM25, L1 core files, L2 HybridRAG orchestrator, L3 Knowledge Graph,
-L4 vec, L5 Milvus, L6 doc-store).
-
-Drop-in replacement: change a single base URL in your existing
-pentatonic-memory SDK client and you get ~5x retrieval accuracy
-without touching anything else.
-
-Endpoints:
-
-    POST /store             { content, metadata }                       → { id, content, layerId }
-    POST /store-batch       { records: [{ id?, content, metadata }] }   → { inserted, ids[], embed_ms, insert_ms }
-    POST /search            { query, limit, min_score }                 → { results: [...] }
-    POST /forget            { metadata_contains } | { id }              → { deleted: N }
-    GET  /health                                                          → { status, layers: {...}, memories }
-
-Environment:
-
-    L0_URL                   default http://l0:8030
-    L2_PROXY_URL             default http://l2:8031
-    L3_KG_URL                default http://l3:8047
-    L5_MILVUS_URL            default http://l5:8035
-    L6_DOC_URL               default http://l6:8037
-    NV_EMBED_URL             default http://nv-embed:8041/v1/embeddings
-    PORT                     default 8099 (matches pentatonic-memory v0.5)
-"""
-
-import hashlib
-import os
-import sys
-import time
-from datetime import datetime, timezone
-from typing import Any, Optional
-
-import httpx
-from fastapi import FastAPI, HTTPException
-from pydantic import BaseModel, Field
-
-# Reach into the engine/services tree so we can reuse EmbedClient. The
-# tree isn't a real installed package; layer services and the compat
-# shim both side-load it the same way. Keeps the chunking + auto-detect
-# behaviour identical between the shim's pre-embed and the per-layer
-# embeds that previously did the same work N times.
-sys.path.insert(
-    0,
-    os.path.join(os.path.dirname(__file__), "..", "engine", "services"),
-)
-from _shared.embed_provider import EmbedClient  # noqa: E402
-
-# ----------------------------------------------------------------------
-# Config
-# ----------------------------------------------------------------------
-
-L0_URL = os.environ.get("L0_URL", "http://l0:8030")
-L2_PROXY_URL = os.environ.get("L2_PROXY_URL", "http://l2:8031")
-L3_KG_URL = os.environ.get("L3_KG_URL", "http://l3:8047")
-L5_MILVUS_URL = os.environ.get("L5_MILVUS_URL", "http://l5:8035")
-L6_DOC_URL = os.environ.get("L6_DOC_URL", "http://l6:8037")
-NV_EMBED_URL = os.environ.get("NV_EMBED_URL", "http://nv-embed:8041/v1/embeddings")
-
-# Neo4j has no /health endpoint, so the shim probes the HTTP transactional
-# API with a trivial RETURN 1 — that confirms Neo4j is actually answering
-# Cypher, not just serving HTTP. Auth shape is the same as L2 / docker-compose:
-# "user/pass" string. Default matches the local-dev compose default.
-NEO4J_AUTH = os.environ.get("NEO4J_AUTH", "neo4j/local-dev-pw")
-NEO4J_DB = os.environ.get("NEO4J_DB", "neo4j")
-
-PORT = int(os.environ.get("PORT", "8099"))
-
-# Shared-embed mode. When on, /store-batch computes embeddings once at
-# the shim level and forwards them to each layer's /index-batch so the
-# layer skips its own embed call. Cuts gateway RPC count by ~4× (L4 +
-# L5 + L6 + L2-internal all did the same embed work independently).
-# Default ON because all layers in this engine use the same NV-Embed
-# model; disable if you ever wire up per-layer differentiated embedders
-# (e.g. cohere on L5, openai on L4).
-SHARE_EMBEDDINGS = os.environ.get("PME_SHARE_EMBEDDINGS", "true").lower() == "true"
-
-_embed_client: EmbedClient | None = None
-
-
-def _get_embed_client() -> EmbedClient:
-    """Lazy-init the shim's EmbedClient using PME_-prefixed env vars
-    (matches L2's pattern). Cached for the process lifetime so the
-    auto-detect handshake only happens once."""
-    global _embed_client
-    if _embed_client is None:
-        _embed_client = EmbedClient.from_env(
-            prefix="PME_",
-            default_url=NV_EMBED_URL,
-        )
-    return _embed_client
-
-
-# Layer types we surface as the SDK 4-layer projection. Engine stores
-# everything as chunks tagged with arena + layer_type metadata; this
-# helper renders the legacy `ml_<arena>_<type>` layer-id from the
-# per-row arena, so the response reflects the actual data not a
-# deployment-wide constant. Falls back to "episodic" when arena or
-# layer_type is missing.
-def _layer_id(arena: Optional[str], layer_type: Optional[str] = None) -> str:
-    a = arena or "general"
-    t = layer_type or "episodic"
-    return f"ml_{a}_{t}"
-
-# Test/isolated mode: bypass the L2 HybridRAG orchestrator and query L6 directly.
-# Useful for bench harnesses where you want to validate the ingest+search
-# round-trip against an isolated test L6 instance, without the L2 proxy
-# pulling in production data from other layers.
-BYPASS_L2 = os.environ.get("BYPASS_L2_PROXY", "0") in ("1", "true", "yes")
-
-VERSION = "0.1.0"
-
-
-# ----------------------------------------------------------------------
-# Request / response models (match pentatonic-memory v0.5 wire format)
-# ----------------------------------------------------------------------
-
-class StoreRequest(BaseModel):
-    content: str
-    metadata: Optional[dict[str, Any]] = None
-
-
-class StoreBatchRequest(BaseModel):
-    records: list[dict[str, Any]] = Field(default_factory=list)
-    arena: Optional[str] = "general"
-
-
-class SearchRequest(BaseModel):
-    query: str
-    limit: Optional[int] = 10
-    min_score: Optional[float] = 0.001
-    # Tenant scope (single arena). Back-compat shape — single-arena callers
-    # can keep sending this. Treated as a one-element `arenas` list.
-    arena: Optional[str] = None
-    # Multi-arena scope. Used by callers that want to span both a tenant-
-    # wide arena ("acme") and a user-scoped arena ("acme:user-42") in one
-    # search — the SDK helper composes this list automatically when a
-    # `userId` is supplied. Authoritative when both `arena` and `arenas`
-    # are present; engine treats it as a set.
-    arenas: Optional[list[str]] = None
-    # Arbitrary metadata equality filters, applied as a post-filter on
-    # the shim. Useful for `kind`, `layer_type`, `source_repo`, etc.
-    # Keys not present on a result's metadata are treated as no-match.
-    # Each pair is exact string equality. Engine doesn't currently
-    # forward these to underlying stores, so over-fetch happens; the
-    # shim trims to the requested limit after filtering.
-    metadata_filter: Optional[dict[str, Any]] = None
-
-
-class ForgetRequest(BaseModel):
-    metadata_contains: Optional[dict[str, Any]] = None
-    id: Optional[str] = None
-
-
-class AggregateRequest(BaseModel):
-    """Public-facing /aggregate request.
-
-    Mirrors /aggregate-internal on the L2 proxy with arena scoping
-    enforced at the shim layer (multi-arena spans aren't allowed
-    here — pick a single arena per call). The relationships UI
-    queries this directly via TES; future callers will too.
-    """
-
-    arena: str
-    contact_email: Optional[str] = None
-    contact_name: Optional[str] = None
-    group_by: Optional[list[str]] = None
-
-
-class PeopleListRequest(BaseModel):
-    """Public-facing /people-list request.
-
-    Corpus-level "all people across these arenas" projection backing
-    the Pip Relationships UI list page. Distinct from /aggregate
-    (which is per-person): /people-list returns one row per Person
-    across the whole arena set, with per-channel breakdown nested.
-
-    Multi-arena is supported here (unlike /aggregate) because the
-    UI use case — "people known by Philip OR Jeanne" — is a
-    legitimate cross-user view. The L2 proxy does the dedup by
-    person_email.
-
-    `emails`: batched-mode filter. Return only these emails.
-    `search`: case-insensitive substring on person_name and
-              person_email.
-    `order_by`: whitelisted sort key; see the L2 proxy for the
-                allowlist.
-    """
-
-    arenas: list[str]
-    emails: Optional[list[str]] = None
-    search: Optional[str] = None
-    limit: int = 200
-    offset: int = 0
-    order_by: str = "last_seen_desc"
-
-
-# ----------------------------------------------------------------------
-# Engine clients (one per layer)
-# ----------------------------------------------------------------------
-
-_http: Optional[httpx.AsyncClient] = None
-
-# In-memory metadata sidecar — per-id stash so arbitrary client metadata
-# (e.g. {"bench_tag": "...", "doc_id": "..."}) survives the round-trip
-# even when the underlying L5/L6 schemas don't carry a JSON metadata column.
-# Bounded to the most recent 100k entries to avoid leaking memory in long-
-# running deployments. Resets on shim restart.
-from collections import OrderedDict
-_META_CACHE: "OrderedDict[str, dict[str, Any]]" = OrderedDict()
-_META_CACHE_MAX = 100_000
-
-def _stash_meta(rid: str, meta: dict[str, Any] | None) -> None:
-    if not rid:
-        return
-    _META_CACHE[rid] = meta or {}
-    while len(_META_CACHE) > _META_CACHE_MAX:
-        _META_CACHE.popitem(last=False)
-
-def _lookup_meta(rid: str) -> dict[str, Any]:
-    return _META_CACHE.get(rid, {}) if rid else {}
-
-
-def _stash_all_keys(rid: str, meta: dict[str, Any], arena: str = "general") -> None:
-    """Stash meta under every id-shape any of the 7 layers might echo back.
-
-    L4 sidecar:        rid                          (and `<rid>.md`)
-    L5 comms:          rid                          (path may be `.pentatonic/chats/<rid>.jsonl`)
-    L6 doc-store:      `l6:<rid>:0`, `<rid>.md`     (chunk_id, source_file)
-    L2 internal L0/L4-qmd: `bench/<arena>/<rid>.md`,
-                          `bench/<arena>/<doc_id>.md`
-    L3 graph chunk:    rid (Chunk.id) and doc_id
-    """
-    if not rid:
-        return
-    meta = meta or {}
-    keys = {
-        rid,
-        f"{rid}.md",
-        f"l6:{rid}:0",
-        f"bench/{arena}/{rid}.md",
-        f"bench/{arena}/{rid}",
-    }
-    doc_id = meta.get("doc_id")
-    if doc_id:
-        keys.update({
-            doc_id,
-            f"{doc_id}.md",
-            f"l6:{doc_id}:0",
-            f"bench/{arena}/{doc_id}.md",
-            f"bench/{arena}/{doc_id}",
-        })
-    path = meta.get("path")
-    if path:
-        keys.add(path)
-        keys.add(path.rsplit(".", 1)[0])
-    for k in keys:
-        if k:
-            _stash_meta(k, meta)
-
-
-def _client() -> httpx.AsyncClient:
-    global _http
-    if _http is None:
-        _http = httpx.AsyncClient(timeout=60.0)
-    return _http
-
-
-async def _embed_batch(texts: list[str]) -> list[list[float]]:
-    """One NV-Embed call for many texts. Returns vectors in input order."""
-    if not texts:
-        return []
-    resp = await _client().post(
-        NV_EMBED_URL,
-        json={"input": texts, "model": "nv-embed-v2"},
-        timeout=120.0,
-    )
-    resp.raise_for_status()
-    return [d["embedding"] for d in resp.json()["data"]]
-
-
-async def _index_l5(
-    records: list[dict[str, Any]],
-    arena: str = "general",
-    embeddings: list[list[float]] | None = None,
-) -> int:
-    """Index records into the L5 Milvus comms layer (chats collection).
-
-    arena is forwarded as a Milvus dynamic field so /search can filter
-    by arena natively (vs the shim's defence-in-depth post-filter).
-
-    When `embeddings` is supplied (parallel to records), L5 skips its
-    own embed call — the shim pre-computes vectors once at /store-batch
-    level and threads them through each layer to avoid 3× redundant
-    embed RPCs (L5 + L6 + L2-internal otherwise each re-embed the same
-    texts in parallel).
-    """
-    payload: dict[str, Any] = {
-        "collection": "chats",
-        "records": [
-            {
-                "id": r.get("id") or hashlib.sha1(r["content"].encode()).hexdigest()[:32],
-                "text": r["content"],
-                "source": (r.get("metadata") or {}).get("source", "shim"),
-                "channel": "pentatonic-memory",
-                "contact": (r.get("metadata") or {}).get("user", ""),
-                "arena": (r.get("metadata") or {}).get("arena") or arena,
-            }
-            for r in records
-        ],
-    }
-    if embeddings is not None:
-        payload["embeddings"] = embeddings
-    try:
-        resp = await _client().post(f"{L5_MILVUS_URL}/index-batch", json=payload, timeout=60.0)
-        resp.raise_for_status()
-        return resp.json().get("inserted", 0)
-    except Exception as exc:
-        # Best-effort: L5 is one of five redundant layers; failure here
-        # doesn't mean the record is unsearchable. L0 BM25 + L4 QMD +
-        # L6 doc-store all carry it independently.
-        print(f"[shim] L5 index-batch failed: {exc}")
-        return 0
-
-
-async def _index_l6(
-    records: list[dict[str, Any]],
-    arena: str = "general",
-    embeddings: list[list[float]] | None = None,
-) -> int:
-    """Index records into the L6 document store.
-
-    When `embeddings` is supplied (parallel to records), L6 skips its
-    own embed call — the shim pre-computes vectors once at /store-batch
-    level and threads them through each layer.
-    """
-    payload: dict[str, Any] = {
-        "arena": arena,
-        "records": [
-            {
-                "id": r.get("id") or hashlib.sha1(r["content"].encode()).hexdigest()[:32],
-                "text": r["content"],
-                "source_file": (r.get("metadata") or {}).get("path") or f"{r.get('id', 'doc')}.md",
-                "doc_type": (r.get("metadata") or {}).get("doc_type", "general"),
-                "heading": (r.get("metadata") or {}).get("heading", ""),
-            }
-            for r in records
-        ],
-    }
-    if embeddings is not None:
-        payload["embeddings"] = embeddings
-    try:
-        resp = await _client().post(f"{L6_DOC_URL}/index-batch", json=payload, timeout=120.0)
-        resp.raise_for_status()
-        return resp.json().get("inserted", 0)
-    except Exception as exc:
-        print(f"[shim] L6 index-batch failed: {exc}")
-        return 0
-
-
-async def _index_l2_internal(
-    records: list[dict[str, Any]],
-    arena: str = "general",
-    embeddings: list[list[float]] | None = None,
-) -> dict:
-    """Populate L2's internal stores: L0 BM25 + L4 QMD vec + L3 Neo4j KG.
-
-    Without this, L2's RRF fusion runs over empty L0/L4-qmd/L3 layers and
-    those zero-result rank lists pollute the score. The L2 proxy exposes
-    /index-internal-batch which writes to all three in one round-trip.
-
-    When `embeddings` is supplied (parallel to records), L2's internal
-    embed call (used for L4-QMD population) is skipped — the shim
-    pre-computes vectors once at /store-batch level and threads them
-    through to L4_QMD via this endpoint.
-    """
-    payload: dict[str, Any] = {
-        "arena": arena,
-        "records": [
-            {
-                "id": r.get("id") or hashlib.sha1(r["content"].encode()).hexdigest()[:32],
-                "content": r["content"],
-                "metadata": r.get("metadata") or {},
-            }
-            for r in records
-        ],
-    }
-    if embeddings is not None:
-        payload["embeddings"] = embeddings
-    try:
-        resp = await _client().post(f"{L2_PROXY_URL}/index-internal-batch",
-                                    json=payload, timeout=180.0)
-        resp.raise_for_status()
-        return resp.json()
-    except Exception as exc:
-        print(f"[shim] L2 internal index-batch failed: {exc}")
-        return {"l0": 0, "l4_qmd": 0, "l3_entities": 0, "l3_chunks": 0}
-
-
-# ----------------------------------------------------------------------
-# FastAPI app
-# ----------------------------------------------------------------------
-
-app = FastAPI(
-    title="pentatonic-memory-engine compat shim",
-    version=VERSION,
-    description="Drop-in API compat for pentatonic-memory v0.5; routed through the 7-layer engine.",
-)
-
-
-def _interpret_body_status(body: Any) -> str | None:
-    """Pull a layer's self-reported status out of its /health body.
-
-    Layers don't all use the same vocabulary — L4 says "ok"/"degraded",
-    L2 says "healthy"/"unavailable", some return nothing. Normalize to
-    "ok" or a short failure reason; None means the body didn't carry
-    a status field, in which case the HTTP code is the source of truth.
-    """
-    if not isinstance(body, dict):
-        return None
-    raw = body.get("status")
-    if raw is None:
-        return None
-    s = str(raw).lower()
-    if s in ("ok", "healthy"):
-        return "ok"
-    err = body.get("error") or body.get("reason") or ""
-    return f"{s}: {str(err)[:80]}" if err else s
-
-
-async def _probe(url: str) -> str:
-    """Probe a layer /health endpoint and return a single-string verdict
-    that surfaces both transport-level failure and self-reported status."""
-    try:
-        r = await _client().get(url, timeout=3.0)
-    except Exception as exc:
-        return f"unreachable: {type(exc).__name__}"
-    if r.status_code != 200:
-        return f"http {r.status_code}"
-    try:
-        body_status = _interpret_body_status(r.json())
-    except Exception:
-        body_status = None
-    return body_status or "ok"
-
-
-async def _probe_l3() -> str:
-    """Real Neo4j probe — POST a trivial Cypher via the HTTP transactional
-    API and require a 200 response. Confirms Neo4j is actually answering
-    queries, not just serving the Browser HTML on :7474.
-    """
-    user, _, password = NEO4J_AUTH.partition("/")
-    url = f"{L3_KG_URL}/db/{NEO4J_DB}/tx/commit"
-    try:
-        r = await _client().post(
-            url,
-            json={"statements": [{"statement": "RETURN 1"}]},
-            auth=(user, password),
-            timeout=3.0,
-        )
-    except Exception as exc:
-        return f"unreachable: {type(exc).__name__}"
-    if r.status_code != 200:
-        return f"http {r.status_code}"
-    try:
-        body = r.json()
-        # Neo4j tx/commit returns {"results":[...], "errors":[...]}.
-        # Any errors here means the DB is up but rejecting queries.
-        errs = body.get("errors") or []
-        if errs:
-            return f"cypher error: {str(errs[0])[:80]}"
-    except Exception:
-        return "non-json response"
-    return "ok"
-
-
-@app.get("/health")
-async def health():
-    """Aggregate health across all 7 layers.
-
-    Each layer's verdict is honest: it reflects whether the layer can
-    actually do its job, not just whether its HTTP server answers. The
-    shim reads the layer's body.status (when present) and degrades when
-    the layer self-reports a problem. L3 uses a real Cypher probe since
-    Neo4j has no /health route.
-    """
-    out = {
-        "status": "ok",
-        "version": VERSION,
-        "engine": "pentatonic-memory-engine",
-        "layers": {},
-    }
-    # NV-Embed (or the upstream gateway) exposes /health at the host root.
-    # Use urlparse so we swap *just* the path component instead of doing a
-    # string replace — that breaks the moment NV_EMBED_URL is /v1/embed,
-    # /v1/embeddings, or bare-host. The probe is informational only; gateways
-    # that return non-200 on root-/health don't block engine operation.
-    from urllib.parse import urlparse, urlunparse
-    _u = urlparse(NV_EMBED_URL)
-    nv_embed_health = urlunparse((_u.scheme, _u.netloc, "/health", "", "", ""))
-
-    import asyncio
-    l2_v, l5_v, l6_v, nv_v, l3_v = await asyncio.gather(
-        _probe(f"{L2_PROXY_URL}/health"),
-        _probe(f"{L5_MILVUS_URL}/health"),
-        _probe(f"{L6_DOC_URL}/health"),
-        _probe(nv_embed_health),
-        _probe_l3(),
-    )
-
-    # L0 BM25 (FTS5), L1 (always-loaded core files) and L4 QMD vec are
-    # all in-process inside the L2 proxy — L0+L1 in workspace.db / core
-    # files; L4 in qmd.sqlite which L2 opens directly. No separate runtime;
-    # if L2 is healthy, all three layers are usable. Tie their status to L2.
-    l2_ok = l2_v == "ok"
-    out["layers"] = {
-        "l0": "ok" if l2_ok else l2_v,
-        "l1": "ok" if l2_ok else l2_v,
-        "l2": l2_v,
-        "l3": l3_v,
-        "l4": "ok" if l2_ok else l2_v,
-        "l5": l5_v,
-        "l6": l6_v,
-        "nv_embed": nv_v,
-    }
-    failures = sum(1 for v in out["layers"].values() if v != "ok")
-    if failures:
-        out["status"] = "degraded" if failures < 3 else "down"
-
-    # Per-layer chunk counts. Replaces the previous single `memories` int
-    # which only reflected L6's vector chunk count — misleading because
-    # L0/L4/L5 hold different (overlapping) projections of the corpus.
-    # Each layer is independently probed; transient failure on one layer
-    # leaves its slot null rather than zeroing the whole field.
-    memories: dict[str, int | None] = {
-        "l0_bm25_chunks": None,
-        "l4_vectors": None,
-        "l5_chats_chunks": None,
-        "l6_vector_chunks": None,
-        "l6_fts_chunks": None,
-    }
-    # L0 and L4 both live inside L2 (workspace.db + qmd.sqlite directly
-    # opened by the L2 proxy). L2 exposes /index-internal-stats with both
-    # counts in one round-trip.
-    try:
-        r = await _client().get(f"{L2_PROXY_URL}/index-internal-stats", timeout=3.0)
-        if r.status_code == 200:
-            stats = r.json()
-            memories["l0_bm25_chunks"] = int(stats.get("l0_chunks") or 0)
-            memories["l4_vectors"] = int(stats.get("l4_qmd_chunks") or 0)
-    except Exception:
-        pass
-    # L5 reports per-collection counts on /health. We surface chats —
-    # the only collection currently populated; emails/contacts/memory
-    # collections coming back online with L5 collection bootstrap.
-    try:
-        r = await _client().get(f"{L5_MILVUS_URL}/health", timeout=3.0)
-        if r.status_code == 200:
-            colls = r.json().get("collections") or {}
-            chats = colls.get("chats") if isinstance(colls, dict) else None
-            if isinstance(chats, dict):
-                memories["l5_chats_chunks"] = int(chats.get("count") or 0)
-    except Exception:
-        pass
-    # L6 exposes vector vs fts splits on /stats.
-    try:
-        r = await _client().get(f"{L6_DOC_URL}/stats", timeout=3.0)
-        if r.status_code == 200:
-            stats = r.json()
-            memories["l6_vector_chunks"] = int(stats.get("vector_chunks") or 0)
-            memories["l6_fts_chunks"] = int(stats.get("fts_chunks") or 0)
-    except Exception:
-        pass
-    out["memories"] = memories
-    return out
-
-
-@app.get("/health/deep")
-async def health_deep():
-    """Aggregate functional probe — fans out to each layer's /health/deep
-    and reports per-layer ok/status.
-
-    Where /health checks "process up + port answering", /health/deep
-    actually exercises embed → write → search round-trips on each layer
-    that supports it. Catches the class of bug that masquerades as
-    "healthy" — request handlers 500'ing while the process stays up.
-
-    Slower than /health (~1–2s); intended for ops/monitoring/cron use,
-    not the deploy gate or compose healthcheck.
-    """
-    import asyncio
-    out: dict[str, Any] = {"status": "ok", "ok": True, "layers": {}}
-
-    async def _probe_deep(name: str, url: str) -> tuple[str, dict]:
-        try:
-            r = await _client().get(url, timeout=15.0)
-            if r.status_code != 200:
-                return name, {"ok": False, "status": f"http {r.status_code}"}
-            return name, r.json()
-        except Exception as exc:
-            return name, {"ok": False, "status": f"unreachable: {type(exc).__name__}"}
-
-    # L4 is in-process inside L2 (qmd.sqlite direct-read) — its deep
-    # round-trip is covered by L2's /health/deep, no separate probe needed.
-    results = await asyncio.gather(
-        _probe_deep("l5", f"{L5_MILVUS_URL}/health/deep"),
-        _probe_deep("l6", f"{L6_DOC_URL}/health/deep"),
-    )
-    for name, body in results:
-        out["layers"][name] = body
-        if not body.get("ok", False):
-            out["ok"] = False
-
-    if not out["ok"]:
-        out["status"] = "degraded"
-    return out
-
-
-def _arena_scoped_rid(arena: str, content: str) -> str:
-    """Stable, arena-scoped record id.
-
-    Same content in different arenas hashes to *different* ids — so two
-    tenants storing the byte-identical chunk get distinct primary keys
-    in the underlying stores (L4 sqlite-vec, L5 Milvus, L6 Milvus).
-    Without this, arena=tenant-b's write would overwrite arena=tenant-a's
-    row of the same content, silently breaking multi-tenant isolation
-    for any duplicated phrase.
-    """
-    return hashlib.sha1(f"{arena}:{content}".encode()).hexdigest()[:32]
-
-
-@app.post("/store")
-async def store(req: StoreRequest):
-    """Single-record ingest. Same wire format as pentatonic-memory v0.5."""
-    arena = (req.metadata or {}).get("arena", "general")
-    rid = (req.metadata or {}).get("id") or _arena_scoped_rid(arena, req.content)
-    record = {"id": rid, "content": req.content, "metadata": req.metadata or {}}
-
-    # Stash the full metadata under every key shape any layer could echo back.
-    # L5/L6 use derivatives of rid; L2-internal returns paths shaped like
-    # bench/<arena>/<id>.md (and <id> may be the SHA1 rid OR the caller's doc_id
-    # depending on which one was supplied).
-    _stash_all_keys(rid, req.metadata or {}, arena)
-
-    # Fan out to L5 + L6 + L2-internal (L0+L4qmd+L3) in parallel.
-    import asyncio
-    l5_count, l6_count, l2_internal = await asyncio.gather(
-        _index_l5([record], arena=arena),
-        _index_l6([record], arena=arena),
-        _index_l2_internal([record], arena=arena),
-    )
-
-    l4_qmd_count = l2_internal.get("l4_qmd", 0)
-    return {
-        "id": rid,
-        "content": req.content,
-        "layerId": _layer_id(arena, (req.metadata or {}).get("layer_type")),
-        "engine": {
-            "l0": l2_internal.get("l0", 0),
-            "l3_chunks": l2_internal.get("l3_chunks", 0),
-            "l3_entities": l2_internal.get("l3_entities", 0),
-            "l4_qmd": l4_qmd_count,
-            # `l4` is aliased to L4_QMD now that the standalone L4 sqlite-vec
-            # sidecar has been dropped. Kept in the response for wire-format
-            # back-compat with callers that read engine.l4.
-            "l4": l4_qmd_count,
-            "l5": l5_count,
-            "l6": l6_count,
-        },
-    }
-
-
-@app.post("/store-batch")
-async def store_batch(req: StoreBatchRequest):
-    """Batch ingest — 30-50× faster than calling /store N times."""
-    if not req.records:
-        return {"inserted": 0, "ids": []}
-
-    # Normalise each record to {id, content, metadata}.
-    arena = req.arena or "general"
-    normalised = []
-    for r in req.records:
-        content = r.get("content") or r.get("text") or ""
-        if not content:
-            continue
-        rid = r.get("id") or _arena_scoped_rid(arena, content)
-        normalised.append({"id": rid, "content": content, "metadata": r.get("metadata") or {}})
-
-    # Stash metadata for every record so /search can re-attach it.
-    for r in normalised:
-        _stash_all_keys(r["id"], r.get("metadata") or {}, arena)
-
-    t0 = time.perf_counter()
-    import asyncio
-
-    # Shared-embed mode: compute embeddings ONCE here, pass them down to
-    # every layer so they skip their own embed call. Previously L5 + L6
-    # + L2-internal each re-embedded the same texts in parallel, which
-    # fanned 3× the gateway RPCs. The gateway throttles at K≈10 concurrent
-    # requests, so 30-way fan-out serialised into ~3 rounds of ~850ms
-    # each = ~2.5s of pure embed time per /store-batch. With shared
-    # embeddings we issue one chunked embed pass (10 sub-calls for N=50
-    # records) and skip the per-layer redundant work entirely.
-    # Disabled via PME_SHARE_EMBEDDINGS=false for operators wiring up
-    # per-layer differentiated embedders.
-    shared_embeddings: list[list[float]] | None = None
-    embed_ms = 0.0
-    if SHARE_EMBEDDINGS and normalised:
-        texts = [r["content"] for r in normalised]
-        embed_t0 = time.perf_counter()
-        try:
-            shared_embeddings = await _get_embed_client().embed_batch_async(texts)
-        except Exception as exc:
-            # Fall back to per-layer embedding rather than failing the
-            # whole batch. The layers' /index-batch still works when
-            # `embeddings` is absent.
-            print(f"[shim] shared embed failed, falling back to per-layer: {exc}")
-            shared_embeddings = None
-        embed_ms = (time.perf_counter() - embed_t0) * 1000.0
-
-    l5_count, l6_count, l2_internal = await asyncio.gather(
-        _index_l5(normalised, arena=req.arena or "general", embeddings=shared_embeddings),
-        _index_l6(normalised, arena=req.arena or "general", embeddings=shared_embeddings),
-        _index_l2_internal(normalised, arena=req.arena or "general", embeddings=shared_embeddings),
-    )
-    dur_ms = (time.perf_counter() - t0) * 1000.0
-
-    l4_qmd_count = l2_internal.get("l4_qmd", 0)
-    return {
-        "status": "ok",
-        "inserted": max(l4_qmd_count, l5_count, l6_count),
-        "ids": [r["id"] for r in normalised],
-        "engine": {
-            "l0": l2_internal.get("l0", 0),
-            "l3_chunks": l2_internal.get("l3_chunks", 0),
-            "l3_entities": l2_internal.get("l3_entities", 0),
-            "l4_qmd": l4_qmd_count,
-            # `l4` aliased to L4_QMD — sidecar dropped, see /store handler.
-            "l4": l4_qmd_count,
-            "l5": l5_count,
-            "l6": l6_count,
-        },
-        "duration_ms": round(dur_ms, 1),
-    }
-
-
-def _arenas_for(req: SearchRequest) -> list[str]:
-    """Normalize req's single-arena + multi-arena fields into one list.
-
-    `arenas` is authoritative when set; otherwise `arena` is treated as
-    a one-element list; otherwise empty (= search is unscoped, dev/test).
-    """
-    if req.arenas:
-        return [a for a in req.arenas if a]
-    if req.arena:
-        return [req.arena]
-    return []
-
-
-def _apply_metadata_filters(results: list[dict[str, Any]], req: SearchRequest) -> list[dict[str, Any]]:
-    """Post-filter results by arena set + arbitrary metadata equality.
-
-    Many layer searches don't yet honour arena/metadata at the storage
-    level, so the shim enforces tenant isolation here as defence in
-    depth. Even if the underlying layer leaks across arenas, the shim
-    drops cross-arena rows before returning.
-
-    Multi-arena rule: a row passes if its arena tag is in the request's
-    arena set. So a user-scoped search (arenas=[acme, acme:u-42]) sees
-    both tenant-wide rows (arena=acme) and that user's own user-scoped
-    rows (arena=acme:u-42), but never another user's user-scoped rows
-    (arena=acme:u-99).
-    """
-    arenas = _arenas_for(req)
-    extra = req.metadata_filter or {}
-    if not arenas and not extra:
-        return results
-    arena_set = set(arenas)
-    out: list[dict[str, Any]] = []
-    for item in results:
-        meta = item.get("metadata") or {}
-        if arena_set:
-            row_arena = meta.get("arena") or item.get("arena")
-            if row_arena and row_arena not in arena_set:
-                continue
-            # If row has no arena tag at all, drop on multi-tenant
-            # safety: a row without arena predates the multi-tenant
-            # plumbing and could belong to anyone.
-            if not row_arena:
-                continue
-        ok = True
-        for k, v in extra.items():
-            if str(meta.get(k, "")) != str(v):
-                ok = False
-                break
-        if ok:
-            out.append(item)
-    return out
-
-
-def _search_overfetch(req: SearchRequest) -> int:
-    """Decide how many results to over-fetch from layers.
-
-    Post-filtering can drop many rows; we ask layers for more than the
-    user's limit so we have headroom after filtering. 5x is a balance
-    between accuracy and latency.
-    """
-    base = req.limit or 10
-    return base * 5 if (_arenas_for(req) or req.metadata_filter) else base * 3
-
-
-@app.post("/search")
-async def search(req: SearchRequest):
-    """
-    Hybrid retrieval over all 7 layers via the L2 HybridRAG proxy. The proxy
-    queries L0 BM25, L4 vec, L5 Milvus, L6 doc-store in parallel and fuses
-    the results with Reciprocal Rank Fusion. L3 KG adds entity-aware
-    boosting for graph queries.
-
-    Multi-tenancy: pass `arena` to scope results to a single tenant.
-    Underlying layers may or may not honour arena natively (L6 does;
-    L2/L4/L5 don't yet — engine TODO); the shim applies arena as a
-    post-filter regardless, so cross-tenant leakage is prevented even
-    when a layer is non-compliant.
-    """
-    if not req.query:
-        return {"results": []}
-
-    # The L2 proxy exposes hybrid search via GET /search?q=... and a strict
-    # OpenAI-compatible POST /v1/search. Try GET first (lower overhead, no
-    # JSON parsing on the proxy side); fall back to /v1/search; then to L6.
-    #
-    # When BYPASS_L2_PROXY is set, skip the proxy entirely and query L6
-    # directly. Useful for isolated bench/test runs.
-    data: dict[str, Any] | None = None
-    last_err: Exception | None = None
-    if BYPASS_L2:
-        # L6-only path: L6 already does vector + BM25 + cross-encoder
-        # reranker. Adding L4's pure vector via RRF actively hurt on
-        # product-catalogue (-5.6pp on the 84.6% baseline) by diluting
-        # the rerank ordering. Stick to L6 for now; the proper next
-        # step is wiring up the L2 7-layer proxy.
-        import asyncio
-        async def _q_l6(query: str):
-            try:
-                params: list = [
-                    ("q", query),
-                    ("limit", str(_search_overfetch(req))),
-                    ("method", "hybrid"),
-                ]
-                # L6 supports arena natively (l6-document-store.py).
-                # Forward all arenas in the search scope; L6 expands the
-                # filter to `arena IN (...)`. Multiple `arenas` query
-                # params on the wire = list-shaped server side.
-                for a in _arenas_for(req):
-                    params.append(("arenas", a))
-                r = await _client().get(
-                    f"{L6_DOC_URL}/search",
-                    params=params,
-                    timeout=30.0,
-                )
-                r.raise_for_status()
-                return [{"layer": "L6", **item} for item in r.json().get("results", [])]
-            except Exception as exc:
-                print(f"[shim] L6 search failed for {query!r}: {exc}")
-                return []
-
-        # Optional HyDE: if HYDE_ENABLED, also generate 2 hypothetical
-        # answers via the LLM, embed each, and run them as additional
-        # queries that we RRF-fuse with the original. Off by default;
-        # set HYDE_ENABLED=1 to try it. Runs in parallel with the main
-        # query so latency only grows by the LLM call (1-2s).
-        l6_hits = await _q_l6(req.query)
-        l4_hits: list[dict[str, Any]] = []  # kept empty intentionally
-
-        # Reciprocal Rank Fusion (RRF) — k=60 is the standard constant
-        # from Cormack et al. 2009. Score = 1/(k + rank). For each unique
-        # doc id we sum contributions from each layer that returned it.
-        #
-        # Critical: layers return items with different id shapes
-        # (L6 uses "l6:<rid>:0" chunk ids and "<rid>.md" source_file,
-        # L4 uses the raw rid as path), so we resolve a *canonical* id
-        # by walking the metadata cache for each candidate id form.
-        # That makes the same doc collapse into one rank entry across
-        # layers and lets RRF actually fuse instead of double-listing.
-        def _canonical_key(item: dict[str, Any]) -> str:
-            candidates = [
-                item.get("id"),
-                item.get("chunk_id"),
-                item.get("source_file"),
-                item.get("source_file", "").rsplit(".md", 1)[0] if item.get("source_file") else None,
-                item.get("path"),
-            ]
-            for cid in candidates:
-                if not cid:
-                    continue
-                m = _META_CACHE.get(cid)
-                if m and m.get("doc_id"):
-                    return m["doc_id"]
-            # Fallback: use first non-empty candidate as key.
-            for cid in candidates:
-                if cid:
-                    return cid
-            return hashlib.sha1((item.get("text") or item.get("content") or "").encode()).hexdigest()[:32]
-
-        K = 60
-        rrf_scores: dict[str, float] = {}
-        first_item: dict[str, dict[str, Any]] = {}
-        layer_provenance: dict[str, list[str]] = {}
-        for hits in (l6_hits, l4_hits):
-            for rank, item in enumerate(hits, start=1):
-                key = _canonical_key(item)
-                rrf_scores[key] = rrf_scores.get(key, 0.0) + 1.0 / (K + rank)
-                layer_provenance.setdefault(key, []).append(item.get("layer", "?"))
-                # Keep the richest version of the doc (prefer L6 — it
-                # carries cross-encoder reranker scores plus content).
-                if key not in first_item or item.get("layer") == "L6":
-                    first_item[key] = item
-
-        # Sort by fused score, take top-N.
-        ranked_keys = sorted(rrf_scores.keys(), key=lambda k: -rrf_scores[k])
-        top_keys = ranked_keys[: req.limit or 10]
-
-        out_results = []
-        for key in top_keys:
-            item = first_item[key]
-            attached_meta = _lookup_meta(key)
-            if not attached_meta:
-                # The canonical key may itself be a derived form; walk
-                # all known id shapes one more time as a safety net.
-                for cid in (item.get("id"), item.get("chunk_id"),
-                            item.get("source_file"), item.get("path")):
-                    if cid:
-                        m = _lookup_meta(cid)
-                        if m:
-                            attached_meta = m
-                            break
-            # Some layers surface arena/kind/layer_type as top-level
-            # fields on the raw item rather than nested under metadata.
-            # Pull them through into the formatted metadata so the
-            # post-filter can see them even on cache miss (e.g., after
-            # a compat container restart wipes _META_CACHE).
-            raw_top_level = {
-                k: item[k]
-                for k in ("arena", "kind", "layer_type", "doc_type", "source_file")
-                if item.get(k)
-            }
-            merged_meta = {**raw_top_level, **(attached_meta or item.get("metadata") or {})}
-            row_arena = merged_meta.get("arena")
-            row_layer_type = merged_meta.get("layer_type")
-            out_results.append({
-                "id": key,
-                "content": item.get("text") or item.get("content") or item.get("snippet") or "",
-                "metadata": merged_meta,
-                "similarity": float(rrf_scores[key]),
-                "layer_id": _layer_id(row_arena, row_layer_type),
-                "source": item.get("source_file") or item.get("path") or "",
-                "engine_layer": "+".join(sorted(set(layer_provenance.get(key, [])))),
-            })
-        # Defense-in-depth post-filter (arena + arbitrary metadata),
-        # then trim to the requested limit.
-        out_results = _apply_metadata_filters(out_results, req)
-        return {"results": out_results[: req.limit or 10]}
-    arenas = _arenas_for(req)
-    try:
-        get_params: list = [
-            ("q", req.query),
-            ("limit", str(_search_overfetch(req))),
-        ]
-        for a in arenas:
-            get_params.append(("arenas", a))
-        r = await _client().get(
-            f"{L2_PROXY_URL}/search",
-            params=get_params,
-            timeout=30.0,
-        )
-        r.raise_for_status()
-        data = r.json()
-    except Exception as exc:
-        last_err = exc
-        try:
-            post_body: dict[str, Any] = {
-                "query": req.query,
-                "limit": _search_overfetch(req),
-                "min_score": req.min_score or 0.001,
-            }
-            if arenas:
-                post_body["arenas"] = arenas
-            r = await _client().post(
-                f"{L2_PROXY_URL}/v1/search",
-                json=post_body,
-                timeout=30.0,
-            )
-            r.raise_for_status()
-            data = r.json()
-        except Exception as exc2:
-            last_err = exc2
-            try:
-                params: list = [
-                    ("q", req.query),
-                    ("limit", str(_search_overfetch(req))),
-                ]
-                # L6 supports arena natively; forward all in the search
-                # scope on the last-resort fallback path too.
-                for a in arenas:
-                    params.append(("arenas", a))
-                r = await _client().get(
-                    f"{L6_DOC_URL}/search",
-                    params=params,
-                    timeout=10.0,
-                )
-                r.raise_for_status()
-                data = r.json()
-            except Exception as exc3:
-                raise HTTPException(status_code=502,
-                                    detail=f"engine unreachable: {last_err}; L6 fallback: {exc3}")
-    if data is None:
-        raise HTTPException(status_code=502, detail=f"engine returned no data: {last_err}")
-
-    # Normalise to pentatonic-memory v0.5 result shape. Re-attach the
-    # client-supplied metadata via the in-memory cache (same logic as
-    # the BYPASS_L2 path). Bench adapters filter results by
-    # metadata.bench_tag, so the metadata MUST survive the L2 round-trip
-    # even though L2's response shape doesn't carry an arbitrary JSON
-    # metadata column.
-    out_results = []
-    for item in data.get("results", []):
-        candidate_ids = [
-            item.get("id"),
-            item.get("doc_id"),
-            item.get("path"),
-            item.get("source_file"),
-            item.get("chunk_id"),
-            item.get("source"),
-            # L5 returns paths like ".pentatonic/chats/<rid>.jsonl" — strip suffix
-            item.get("path", "").rsplit(".", 1)[0] if item.get("path") else None,
-            item.get("source_file", "").rsplit(".md", 1)[0] if item.get("source_file") else None,
-        ]
-        attached_meta: dict[str, Any] = {}
-        chosen_id = ""
-        for cid in candidate_ids:
-            if cid:
-                m = _lookup_meta(cid)
-                if m:
-                    attached_meta = m
-                    chosen_id = m.get("doc_id") or cid
-                    break
-        if not chosen_id:
-            chosen_id = (item.get("id") or item.get("doc_id")
-                         or item.get("path") or item.get("source_file") or "")
-        # Pull arena/kind/layer_type from raw item top-level if present
-        # (L6 returns these as top-level columns; cache may be empty).
-        raw_top_level = {
-            k: item[k]
-            for k in ("arena", "kind", "layer_type", "doc_type", "source_file")
-            if item.get(k)
-        }
-        merged_meta = {**raw_top_level, **(attached_meta or item.get("metadata") or {})}
-        row_arena = merged_meta.get("arena")
-        row_layer_type = merged_meta.get("layer_type")
-        out_results.append({
-            "id": chosen_id,
-            "content": item.get("text") or item.get("content") or item.get("snippet") or "",
-            "metadata": merged_meta,
-            "similarity": float(item.get("score") or item.get("similarity") or 0.0),
-            "layer_id": _layer_id(row_arena, row_layer_type),
-            "source": item.get("source", item.get("source_file", "")),
-            "engine_layer": item.get("layer", item.get("source_layer", "")),
-        })
-    # Defense-in-depth post-filter (arena + arbitrary metadata) on L2/L6
-    # fallback paths. Same logic as the BYPASS branch above.
-    out_results = _apply_metadata_filters(out_results, req)
-    return {"results": out_results[: req.limit or 10]}
-
-
-@app.post("/forget")
-async def forget(req: ForgetRequest):
-    """
-    Delete records by id or metadata filter. Restored from v0.4.x — was
-    removed in v0.5.x, causing test/bench pollution and blocking GDPR
-    deletion workflows.
-    """
-    if not req.id and not req.metadata_contains:
-        raise HTTPException(status_code=400, detail="provide id or metadata_contains")
-
-    deleted_total = 0
-    # Forward to layers that support deletion. L6 doc-store supports both.
-    try:
-        if req.id:
-            r = await _client().delete(
-                f"{L6_DOC_URL}/purge",
-                params={"source_file": req.id},
-                timeout=10.0,
-            )
-            if r.status_code == 200:
-                deleted_total += int(r.json().get("deleted", 1))
-        elif req.metadata_contains:
-            r = await _client().post(
-                f"{L6_DOC_URL}/forget",
-                json={"metadata_contains": req.metadata_contains},
-                timeout=10.0,
-            )
-            if r.status_code == 200:
-                deleted_total += int(r.json().get("deleted", 0))
-    except Exception as exc:
-        print(f"[shim] L6 /forget failed: {exc}")
-
-    # Also wipe L0 BM25 + L4 QMD + L3 KG so bench resets fully.
-    # No per-id forget for these — bench harness uses /forget once at
-    # start of each run with empty filters to reset state.
-    #
-    # Three forwarding rules:
-    #   - metadata_contains has `arena`  → tenant-scoped delete (forwards
-    #     the arena to the internal endpoint, which only wipes that
-    #     tenant's L3 data).
-    #   - metadata_contains is set, no arena → targeted L6-only delete;
-    #     do NOT call the internal wipe (we don't have arena scope and
-    #     a global wipe would be wildly wrong here).
-    #   - empty filters → bench-reset semantics; explicitly request the
-    #     unsafe global wipe via the new `confirm: GLOBAL_WIPE` gate.
-    arena_for_internal = None
-    if isinstance(req.metadata_contains, dict):
-        meta_arena = req.metadata_contains.get("arena")
-        if isinstance(meta_arena, str) and meta_arena:
-            arena_for_internal = meta_arena
-    try:
-        if arena_for_internal:
-            payload = {"arena": arena_for_internal}
-        elif req.metadata_contains:
-            payload = None  # skip — targeted delete shouldn't wipe shared layers
-        else:
-            payload = {"confirm": "GLOBAL_WIPE"}
-        if payload is not None:
-            r = await _client().post(
-                f"{L2_PROXY_URL}/forget-internal", json=payload, timeout=15.0,
-            )
-            if r.status_code == 200:
-                d = r.json().get("deleted", {})
-                deleted_total += sum(int(v or 0) for v in d.values())
-    except Exception as exc:
-        print(f"[shim] L2 /forget-internal failed: {exc}")
-
-    return {"deleted": deleted_total, "engine": "pentatonic-memory-engine"}
-
-
-@app.post("/aggregate")
-async def aggregate(req: AggregateRequest) -> dict[str, Any]:
-    """Aggregate communications history with one person.
-
-    Pass-through to the L2 proxy's /aggregate-internal which runs a
-    single Cypher query against L3's typed-Person graph
-    ((:Person)-[:COMMUNICATED]->(:Chunk)). Used by TES personFacets
-    once we cut over from the over-fetch v1.
-
-    The shim's job here is shape validation + arena enforcement; the
-    real aggregation lives in L3. No layer fan-out, no metadata
-    filter scanning — when the typed-Person nodes don't exist for
-    this contact (older memories, tenants pre-#28), the response is
-    `total: 0` and the caller falls back to whatever it had before.
-    """
-    arena = (req.arena or "").strip()
-    if not arena:
-        raise HTTPException(status_code=400, detail="arena is required")
-    if not (req.contact_email or req.contact_name):
-        raise HTTPException(
-            status_code=400,
-            detail="provide contact_email and/or contact_name to identify the Person",
-        )
-    payload: dict[str, Any] = {
-        "arena": arena,
-        "group_by": req.group_by or ["channel"],
-    }
-    if req.contact_email:
-        payload["contact_email"] = req.contact_email
-    if req.contact_name:
-        payload["contact_name"] = req.contact_name
-    try:
-        r = await _client().post(
-            f"{L2_PROXY_URL}/aggregate-internal", json=payload, timeout=15.0,
-        )
-        if r.status_code != 200:
-            raise HTTPException(
-                status_code=r.status_code,
-                detail=f"aggregate failed: {r.text[:200]}",
-            )
-        return r.json()
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise HTTPException(status_code=502, detail=f"aggregate upstream: {exc}")
-
-
-@app.post("/people-list")
-async def people_list(req: PeopleListRequest) -> dict[str, Any]:
-    """List all people across one or more arenas.
-
-    Pass-through to the L2 proxy's /people-list-internal which runs a
-    single Cypher pass over the ChannelStat denorm keyed on
-    (arena, person_email, channel). Returns paginated, filtered,
-    sorted rows with per-channel breakdown.
-
-    Shim's job: shape validation + arena enforcement. The real
-    aggregation lives in L3 over ChannelStat — see PRs #28-33 for
-    the writer side that maintains those nodes.
-
-    Multi-arena: legitimate here (unlike /aggregate). The UI
-    fetches "people known by Philip OR Jeanne" by passing both
-    arenas; the L2 proxy collapses duplicates by person_email.
-    """
-    arenas = [a.strip() for a in (req.arenas or []) if a and a.strip()]
-    if not arenas:
-        raise HTTPException(status_code=400, detail="at least one arena is required")
-    payload: dict[str, Any] = {
-        "arenas": arenas,
-        "limit": req.limit,
-        "offset": req.offset,
-        "order_by": req.order_by,
-    }
-    if req.emails:
-        # Lowercase here so the L2 path can rely on exact-match; the
-        # writer side also lowercases person_email on the ChannelStat
-        # node, so this stays consistent.
-        payload["emails"] = [e.strip().lower() for e in req.emails if e and e.strip()]
-    if req.search:
-        payload["search"] = req.search.strip()
-    try:
-        r = await _client().post(
-            f"{L2_PROXY_URL}/people-list-internal", json=payload, timeout=15.0,
-        )
-        if r.status_code != 200:
-            raise HTTPException(
-                status_code=r.status_code,
-                detail=f"people-list failed: {r.text[:200]}",
-            )
-        return r.json()
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise HTTPException(status_code=502, detail=f"people-list upstream: {exc}")
-
-
-# ----------------------------------------------------------------------
-# Entrypoint
-# ----------------------------------------------------------------------
-
-if __name__ == "__main__":
-    import uvicorn
-    uvicorn.run("server:app", host="0.0.0.0", port=PORT, log_level="info")