feat: turnkey Qwen3 OpenAI-compatible embedding server + wire into runtime (slice C)

Makes the semantic embedding quality validated in semantic_bench actually
deployable in a running MemTrace service, not just benchmarked.

- app/embedding_server.py: a production OpenAI-compatible /v1/embeddings server
  backed by Qwen3-Embedding-0.6B (FP16, MPS/CUDA/CPU). Honors the OpenAI
  `dimensions` param via Matryoshka (MRL) truncation + L2 renormalize to the
  pgvector 256-dim column; lazy singleton model, warmed at startup (lifespan) so
  requests never cold-start; /health reports model/device/loaded.
- scripts/smoke-embedding-server.sh: opt-in end-to-end smoke that, through
  MemTrace's real OpenAIEmbeddingProvider, verifies (1) the server returns a
  256-dim vector and (2) a full retrieve_context wired to the provider recalls the
  semantically-matched memory for a paraphrase. Skips cleanly if the server is down.
- tests/api/test_embedding_server.py: structural tests (health + validation, no
  model load). docs/deployment.md: the serve + verify + wire recipe.

Live-verified: started the server (Qwen3 on MPS), smoke passed both checks
(256-dim via the provider; paraphrase recalled the Bun fact through the full
pipeline). Full pytest 1003 passed, 3 skipped. The provider still degrades to the
deterministic 256-dim embedding if the server is down, so retrieval never breaks.

Author: MicroYui

apps/api/app/embedding_server.py

@@ -0,0 +1,112 @@
+"""OpenAI-compatible /v1/embeddings server backed by Qwen3-Embedding-0.6B.
+
+Makes the semantic embeddings validated in ``app.benchmark.semantic_bench``
+deployable end-to-end: point ``MEMTRACE_EMBEDDING_PROVIDER=openai`` +
+``MEMTRACE_EMBEDDING_BASE_URL`` at this server and MemTrace's retrieval uses real
+semantic vectors instead of the deterministic hash default.
+
+It honors the OpenAI ``dimensions`` parameter via Matryoshka (MRL) truncation +
+L2 renormalize, so its output matches the pgvector ``vector(256)`` column that
+``MEMTRACE_EMBEDDING_DIM`` defaults to. The model is loaded once at startup (warm)
+so requests never pay a cold-start; loading is FP16 on MPS/CUDA/CPU as available.
+
+Heavy: needs ``sentence-transformers`` + ``torch`` and the model (~1.2GB). Run
+with an ephemeral install so nothing is added to the project deps:
+
+    uv run --with fastapi --with "uvicorn[standard]" --with sentence-transformers \
+      uvicorn app.embedding_server:app --host 0.0.0.0 --port 8090
+
+Config (env):
+  QWEN3_EMBEDDING_MODEL  (default Qwen/Qwen3-Embedding-0.6B)
+  QWEN3_EMBEDDING_DIM    (default 256; the MRL output dimension)
+  QWEN3_EMBEDDING_WARM   (default "1"; set "0" to defer model load to first request)
+"""
+from __future__ import annotations
+
+import os
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+_MODEL_ID = os.environ.get("QWEN3_EMBEDDING_MODEL", "Qwen/Qwen3-Embedding-0.6B")
+_DEFAULT_DIM = int(os.environ.get("QWEN3_EMBEDDING_DIM", "256"))
+
+
+class _ModelHolder:
+    """Lazy singleton so importing this module never loads torch/the model."""
+
+    _model: Any = None
+    _device: str = "unknown"
+
+    @classmethod
+    def get(cls) -> Any:
+        if cls._model is None:
+            import torch
+            from sentence_transformers import SentenceTransformer
+
+            if torch.backends.mps.is_available():
+                cls._device = "mps"
+            elif torch.cuda.is_available():
+                cls._device = "cuda"
+            else:
+                cls._device = "cpu"
+            cls._model = SentenceTransformer(
+                _MODEL_ID, model_kwargs={"torch_dtype": torch.float16}, device=cls._device
+            )
+        return cls._model
+
+
+def _embed(texts: list[str], dim: int) -> list[list[float]]:
+    import numpy as np
+
+    model = _ModelHolder.get()
+    vecs = model.encode(texts, convert_to_numpy=True, normalize_embeddings=False)
+    v = np.asarray(vecs, dtype="float32")
+    if 0 < dim < v.shape[1]:  # Matryoshka truncation to the requested dimension
+        v = v[:, :dim]
+    norms = np.linalg.norm(v, axis=1, keepdims=True)
+    norms[norms == 0] = 1.0
+    return (v / norms).tolist()
+
+
+class EmbeddingRequest(BaseModel):
+    input: str | list[str]
+    model: str = "qwen3-embedding-0.6b"
+    dimensions: int | None = None
+    encoding_format: str | None = None  # accepted for OpenAI-client compatibility; only "float" is produced
+
+
+def create_app() -> FastAPI:
+    @asynccontextmanager
+    async def _lifespan(_app: FastAPI):
+        if os.environ.get("QWEN3_EMBEDDING_WARM", "1") != "0":
+            _ModelHolder.get()  # warm so the first request isn't a cold start
+        yield
+
+    app = FastAPI(title="Qwen3 Embedding Server", lifespan=_lifespan)
+
+    @app.get("/health")
+    def health() -> dict[str, Any]:
+        return {"status": "ok", "model": _MODEL_ID, "default_dim": _DEFAULT_DIM,
+                "loaded": _ModelHolder._model is not None, "device": _ModelHolder._device}
+
+    @app.post("/v1/embeddings")
+    def embeddings(req: EmbeddingRequest) -> dict[str, Any]:
+        texts = [req.input] if isinstance(req.input, str) else list(req.input)
+        if not texts or any(not isinstance(t, str) for t in texts):
+            raise HTTPException(status_code=400, detail="input must be a non-empty string or list of strings")
+        dim = req.dimensions if (req.dimensions and req.dimensions > 0) else _DEFAULT_DIM
+        try:
+            vectors = _embed(texts, dim)
+        except Exception as exc:  # noqa: BLE001
+            raise HTTPException(status_code=500, detail=f"embedding failed: {type(exc).__name__}: {exc}")
+        data = [{"object": "embedding", "index": i, "embedding": vec} for i, vec in enumerate(vectors)]
+        return {"object": "list", "data": data, "model": req.model,
+                "usage": {"prompt_tokens": 0, "total_tokens": 0}}
+
+    return app
+
+
+app = create_app()

apps/api/tests/api/test_embedding_server.py

@@ -0,0 +1,26 @@
+"""Structural tests for the Qwen3 embedding server (no model download/load)."""
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from app.embedding_server import EmbeddingRequest, create_app
+
+
+def test_health_and_empty_input_validation(monkeypatch):
+    monkeypatch.setenv("QWEN3_EMBEDDING_WARM", "0")  # do not load torch/the model
+    app = create_app()
+    with TestClient(app) as client:
+        health = client.get("/health")
+        assert health.status_code == 200
+        body = health.json()
+        assert body["default_dim"] == 256
+        assert body["loaded"] is False  # warm disabled -> model not loaded
+        # empty input is rejected before any model work
+        resp = client.post("/v1/embeddings", json={"input": []})
+        assert resp.status_code == 400
+
+
+def test_request_model_shape():
+    req = EmbeddingRequest(input="hello", dimensions=256)
+    assert req.dimensions == 256
+    assert EmbeddingRequest(input=["a", "b"]).dimensions is None

docs/deployment.md

@@ -182,6 +182,34 @@ uv run python -m app.benchmark.llm_bench --output-dir reports
 
 Do not make real provider calls part of default CI or first-time quickstarts.
 
+### Real semantic embeddings — Qwen3 embedding server
+
+The default `deterministic` embedding is a lexical hash (~42% recall@1 on
+paraphrased queries); a real semantic model gets ~92% (see
+`app/benchmark/semantic_bench.py`). `app/embedding_server.py` is a turnkey
+OpenAI-compatible `/v1/embeddings` server backed by Qwen3-Embedding-0.6B (FP16),
+honoring the `dimensions` param via Matryoshka truncation to the pgvector 256-dim
+column. Start it (heavy; needs the model, ~1.2GB) and point the runtime at it:
+
+```bash
+# 1. serve Qwen3 as an OpenAI-compatible /v1/embeddings endpoint
+uv run --with fastapi --with "uvicorn[standard]" --with sentence-transformers \
+  uvicorn app.embedding_server:app --app-dir apps/api --host 0.0.0.0 --port 8090
+
+# 2. verify end-to-end through MemTrace's provider (skips if the server is down)
+MEMTRACE_EMBEDDING_BASE_URL=http://localhost:8090/v1 ./scripts/smoke-embedding-server.sh
+
+# 3. wire the running MemTrace service to it (real semantic retrieval)
+export MEMTRACE_EMBEDDING_PROVIDER=openai
+export MEMTRACE_EMBEDDING_BASE_URL=http://localhost:8090/v1
+export MEMTRACE_EMBEDDING_MODEL=qwen3-embedding-0.6b
+export MEMTRACE_EMBEDDING_API_KEY=local   # the server does not check auth; the provider sends a Bearer
+```
+
+The provider degrades to the deterministic 256-dim embedding on any failure, so
+retrieval never breaks if the server is down. For production, run the embedding
+server as its own scaled service (GPU or CPU) behind the same load balancer.
+
 ## Optional telemetry export
 
 OpenTelemetry/OpenInference-compatible export is default-off and must be enabled explicitly. Local JSONL output is the safest no-network smoke path:

scripts/smoke-embedding-server.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Opt-in end-to-end smoke for the Qwen3 OpenAI-compatible embedding server
+# (app/embedding_server.py). Start the server first, e.g.:
+#   uv run --with fastapi --with "uvicorn[standard]" --with sentence-transformers \
+#     uvicorn app.embedding_server:app --app-dir apps/api --port 8090
+# then:
+#   MEMTRACE_EMBEDDING_BASE_URL=http://localhost:8090/v1 ./scripts/smoke-embedding-server.sh
+# It verifies, through MemTrace's real OpenAIEmbeddingProvider, that (1) the server
+# returns 256-dim vectors and (2) a full retrieve_context wired to this provider
+# recalls the semantically-matched memory for a paraphrased query. Skips cleanly
+# when the server is unreachable. NOT part of default CI.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR/apps/api"
+
+echo "==> Qwen3 embedding-server smoke (${MEMTRACE_EMBEDDING_BASE_URL:-http://localhost:8090/v1})"
+
+uv run python - <<'PY'
+import asyncio
+import os
+import sys
+
+import httpx
+
+from app.providers.base import ProviderCapabilities, ProviderKind
+from app.providers.embedding import OpenAIEmbeddingProvider
+from app.providers.registry import ProviderRegistry
+from app.runtime.memory_runtime import MemoryRuntime
+from app.runtime.models import (
+    MemoryItem, MemoryScope, MemoryType, RetrievalRequest, RetrievalStrategy,
+    StartRunRequest, StartStepRequest,
+)
+from app.runtime.repository import InMemoryRepository
+
+BASE = os.environ.get("MEMTRACE_EMBEDDING_BASE_URL", "http://localhost:8090/v1").rstrip("/")
+ROOT = BASE[:-3] if BASE.endswith("/v1") else BASE  # derive the server root for /health
+
+FACTS = {
+    "runtime": "The project uses Bun as its JavaScript runtime.",
+    "db": "PostgreSQL is the primary relational database.",
+    "deploy": "We ship the service to a Kubernetes cluster.",
+    "cache": "Redis provides the in-memory caching layer.",
+    "auth": "Users authenticate with JSON Web Tokens.",
+}
+PARAPHRASE = "What executes the client-side script code in this repo?"  # -> runtime (Bun)
+
+
+async def main() -> int:
+    try:
+        httpx.get(f"{ROOT}/health", timeout=5).raise_for_status()
+    except Exception as exc:  # noqa: BLE001
+        print(f"  ⏭️  skip: embedding server not reachable at {ROOT}/health ({type(exc).__name__})")
+        print("advanced-embedding smoke skipped")
+        return 0
+
+    provider = OpenAIEmbeddingProvider(api_key="local", base_url=BASE,
+                                       model="qwen3-embedding-0.6b", dimensions=256, timeout_s=60)
+    try:
+        # 1) the server returns a finite 256-dim vector through MemTrace's provider
+        vec = await provider.embed_text(PARAPHRASE)
+        assert len(vec) == 256, f"expected 256 dims, got {len(vec)}"
+        print(f"  ✅ provider: server returned a {len(vec)}-dim vector via MemTrace's OpenAIEmbeddingProvider")
+
+        # 2) full retrieval wired to this provider recalls the paraphrase's semantic target
+        registry = ProviderRegistry()
+        registry.register(ProviderKind.embedding, provider, ProviderCapabilities(
+            provider_id="embedding.qwen3_server.v1", kind=ProviderKind.embedding,
+            deterministic=False, requires_network=True, model="qwen3-embedding-0.6b",
+            metadata={"dim": 256}))
+        repo = InMemoryRepository()
+        ws = "emb_smoke_ws"
+        for fid, text in FACTS.items():
+            fv = await provider.embed_text(text)  # store the real semantic vector
+            await repo.add_memory(MemoryItem(memory_id=f"m_{fid}", workspace_id=ws,
+                                             memory_type=MemoryType.project, scope=MemoryScope.workspace,
+                                             content=text, summary=text[:60], embedding_vector=fv))
+        rt = MemoryRuntime(repo, default_workspace_id=ws, provider_registry=registry)
+        run = await rt.start_run(StartRunRequest(session_id="emb", task="emb", workspace_id=ws))
+        step = await rt.start_step(StartStepRequest(run_id=run.run_id, intent="answer"))
+        ctx = await rt.retrieve_context(RetrievalRequest(
+            run_id=run.run_id, step_id=step.step_id, query=PARAPHRASE, strategy=RetrievalStrategy.variant_2))
+        text = " ".join((b.content or "") for b in ctx.context_blocks)
+        assert "Bun" in text, f"paraphrase did not recall the runtime fact; context={text[:200]!r}"
+        print("  ✅ retrieval: full retrieve_context via the real provider recalled the Bun fact for a paraphrase")
+    finally:
+        await provider.aclose()
+    print("advanced-embedding smoke passed")
+    return 0
+
+
+sys.exit(asyncio.run(main()))
+PY