Route cloud embeddings through native LiteLLM accounting

Own asynchronous embedding HTTP attempts, validate response identities before cache writes, and preserve model route families. Keep upstream provider credentials gateway-owned.

@codex review

Author: DMontgomery40

.env.example

@@ -2,14 +2,13 @@
 # Copy this file to .env and fill in the values
 
 # ===== API Keys =====
-OPENAI_API_KEY=sk-your-openai-key
 VOYAGE_API_KEY=your-voyage-key
 COHERE_API_KEY=your-cohere-key
 JINA_API_KEY=your-jina-key
 LANGTRACE_API_KEY=your-langtrace-key  # Optional (UI checks presence only)
 
-# Ragweld generation calls only the local LiteLLM gateway. Upstream provider
-# secrets belong in infra/litellm.env and are never loaded into the API.
+# Generation and OpenAI embeddings call the local LiteLLM gateway. Their upstream
+# provider secrets, including OPENAI_API_KEY, belong only in infra/litellm.env.
 LITELLM_BASE_URL=http://127.0.0.1:54000/v1
 LITELLM_API_KEY=sk-ragweld-local
 

README.md

@@ -229,29 +229,30 @@ Each search method compensates for the others' weaknesses. The result: **dramati
 
 ## Performance
 
-ragweld measures real pipeline latency and throughput via **Prometheus + Grafana** (see dashboards `tribrid-overview` and `tribrid-rag-metrics`). For reproducible local benchmarking (index + search), use the built-in benchmark runner.
+ragweld measures pipeline latency and throughput via **Prometheus + Grafana** (see dashboards `tribrid-overview` and `tribrid-rag-metrics`). The benchmark runner measures complete HTTP search requests against a running Ragweld API, including application processing and network time. Warmup requests are excluded from measured latency and throughput.
 
 ### Reproducible benchmark (index + search)
 
 Prereqs:
 
 ```bash
-docker compose up -d postgres neo4j
-# If using the docker-compose defaults:
-export NEO4J_PASSWORD=password
+# Run on LXC100 against the already running API and a registered corpus.
+uv run python -m scripts.benchmark_perf \
+  --api-base-url http://127.0.0.1:58012 \
+  --corpus-id ragweld --skip-index --iterations 5 --warmup 1 \
+  --query 'How does the indexing run fence prevent concurrent replacement?' \
+  --out-json /var/tmp/ragweld-benchmark.json
 ```
 
-Run:
+To include indexing, omit `--skip-index`. The server uses the registered corpus path unless `--corpus-path` supplies another path on that server. Indexing uses the normal run fence, validation and promotion lifecycle. `--force-reindex` permits changed embedding settings; semantic graph indexing also requires `--approved-graph-schema-hash` with the exact reviewed schema hash.
 
-```bash
-uv run scripts/benchmark_perf.py --corpus-id ragweld --corpus-path . --force-reindex --iterations 5 --warmup 1
-```
+The runner prints Markdown and writes JSON when `--out-json` is supplied. `--request-timeout` bounds each HTTP request (default 60 seconds); `--index-timeout` bounds waiting for the accepted run (default 3,600 seconds). A failed, cancelled or unfinished index produces no success report. A wait timeout leaves the server-owned job running, so inspect that corpus's run before starting another benchmark.
 
-This prints **Markdown + JSON** summary you can paste into docs/PRs.
+`--out-json` replaces the selected report: after input validation, the runner removes the previous report before making API requests and publishes a complete JSON file only on success. A failed rerun therefore leaves no stale metrics at that path. Concurrent invocations using the same output path are rejected without changing the active writer's report.
 
 ### Latest benchmark (local dev run)
 
-Generated on `2026-02-01` with the command above (vector+sparse+graph enabled, `final_k=10`).
+Historical internal-pipeline measurement from `2026-02-01` (vector+sparse+graph enabled, `final_k=10`); these values are not directly comparable to the current HTTP benchmark.
 
 | Operation | Performance | Notes |
 |---|---:|---|
@@ -281,7 +282,7 @@ Treat the mainline status section above as the architecture truth for modernizat
 - Docker & Docker Compose
 - Python 3.11+ with [uv](https://github.com/astral-sh/uv)
 - Node.js 18+
-- API keys for your preferred embedding provider (OpenAI, Voyage, etc.)
+- Provider credentials for the configured cloud workflows; OpenAI embedding credentials belong to LiteLLM
 
 ### 1. Clone and Configure
 
@@ -291,17 +292,37 @@ cd ragweld
 cp .env.example .env
 ```
 
-Edit `.env` with your API keys:
+The app's `.env` configures its gateway connection with `LITELLM_BASE_URL` and
+`LITELLM_API_KEY`. OpenAI embeddings and generation call LiteLLM; their upstream
+provider credentials belong in the gateway's private `infra/litellm.env`.
+
+For a new install without an existing gateway environment file:
+
 ```bash
-OPENAI_API_KEY=sk-...
-# or
-VOYAGE_API_KEY=pa-...
+cp infra/litellm.env.example infra/litellm.env
+chmod 600 infra/litellm.env
 ```
 
+Edit that private file to replace `OPENAI_API_KEY=disabled` when enabling OpenAI
+embeddings. Preserve existing gateway settings and Langfuse credentials when
+updating an installation. Do not put `OPENAI_API_KEY` in the app's `.env` or
+export it into the app process. Compose passes the app's `LITELLM_API_KEY` to
+the gateway as `LITELLM_MASTER_KEY`; this gateway client credential is separate
+from the upstream OpenAI key.
+
+On the Proxmox deployment, `.env` points to `/etc/ragweld/runtime.env` and
+`infra/litellm.env` points to `/etc/ragweld/litellm.env`. Update the existing
+owner-only files on LXC100 instead of replacing those symlinks. After changing
+the gateway environment, reconcile/recreate the `litellm` service through the
+deployment's Compose configuration during an idle interval. Restarting only the
+API does not reload the gateway environment. See
+[gateway credentials](docs/references/generation-gateway-catalog.md#gateway-credentials)
+and [Proxmox activation](docs/references/native-run-accounting.md#proxmox-activation).
+
 ### 2. Start Infrastructure
 
 ```bash
-docker compose up -d postgres neo4j
+docker compose --project-name ragweld up -d postgres neo4j qdrant litellm
 ```
 
 By default, Docker volumes are stored alongside the repo. To store DB data **outside** the repo (recommended for real corpora),
@@ -317,6 +338,7 @@ This starts:
 - **PostgreSQL** for corpus control/state rows and caches (port 5432)
 - **Qdrant** vector store for dense + sparse chunk vectors (port 56333)
 - **Neo4j** graph database (ports 7474, 7687)
+- **LiteLLM** gateway for generation and OpenAI embeddings (loopback port 54000)
 
 ### 2a. Start The Observability Overlay For This Branch
 
@@ -350,6 +372,9 @@ uv run uvicorn server.main:app --reload --port 58012
 Notes:
 - The backend will **auto-load** repo-root `.env` on startup (dev convenience).
 - If you change `.env` while the backend is running, you must **restart** the backend for changes to take effect.
+- `GET /api/secrets/check?keys=LITELLM_API_KEY` checks only whether the app's
+  gateway credential is present. It does not validate the key or inspect
+  `OPENAI_API_KEY` in LiteLLM; upstream provider keys are outside this endpoint.
 
 API available at http://localhost:58012
 OpenAPI docs at http://localhost:58012/docs

data/models.json

@@ -5952,6 +5952,8 @@
       "provider": "openai",
       "family": "text-embedding-3-large",
       "model": "text-embedding-3-large",
+      "gateway_alias": "openai.text-embedding-3-large",
+      "gateway_upstream": "openai/text-embedding-3-large",
       "components": [
         "EMB"
       ],
@@ -5969,6 +5971,8 @@
       "provider": "openai",
       "family": "text-embedding-3-small",
       "model": "text-embedding-3-small",
+      "gateway_alias": "openai.text-embedding-3-small",
+      "gateway_upstream": "openai/text-embedding-3-small",
       "components": [
         "EMB"
       ],

docker-compose.yml

@@ -258,7 +258,10 @@ services:
       - LITELLM_BASE_URL=http://litellm:4000/v1
       - LITELLM_API_KEY=${LITELLM_API_KEY:-sk-ragweld-local}
       - VLLM_BASE_URL=http://host.docker.internal:58080/v1
+      - OPENAI_API_KEY=
       - OPENROUTER_API_KEY=
+      - ANTHROPIC_API_KEY=
+      - GOOGLE_API_KEY=
     env_file:
       - .env
     extra_hosts:

docs/references/config-control-plane.md

@@ -72,4 +72,21 @@ OSS-composition branch.
 - `GET /api/secrets/check` now uses the registry-backed secret list rather than
   a hardcoded allowlist.
 - The workbench dependency panel is the operator-facing place to confirm whether
-  required credentials are present.
+  required app credentials are present.
+
+OpenAI embeddings and generation authenticate to LiteLLM using the app's
+`LITELLM_API_KEY`; Compose supplies that credential to the gateway as
+`LITELLM_MASTER_KEY`. Upstream keys such as `OPENAI_API_KEY` belong only in the
+gateway's private `infra/litellm.env`, outside the app registry and browser secret
+controls. See [gateway credentials](generation-gateway-catalog.md#gateway-credentials)
+for the Proxmox file mapping and required gateway recreation after an env change.
+
+For an app-side presence check on LXC100:
+
+```bash
+curl -sS "http://127.0.0.1:58012/api/secrets/check?keys=LITELLM_API_KEY" | jq .
+```
+
+This returns presence only, never a credential value or proof that the gateway
+accepts the key. Requesting `OPENAI_API_KEY` here returns an unsupported-secret
+error; it cannot check the gateway's upstream key or establish provider readiness.