feat(router): provider-flexible /v1/embeddings with Azure Foundry path (A4)

[mrobinson2]

What

Kills the memory system's hard OpenAI-billing dependency: the router's /v1/embeddings passthrough is now provider-flexible with a documented, end-to-end Azure AI Foundry deployment path — and it bakes in the load-bearing LiteLLM provider-detection pin so forks can't rediscover the 400 unknown_model failure mode. Ported from the upstream private deployment's incident learnings.

Design

• openai/ LiteLLM prefix pin (_pin_embedding_provider, services/model-router/main.py) — when EMBEDDING_BASE_URL points at an azure.com host and the model string has no provider/ prefix, LiteLLM flips to its AZURE provider and authenticates with an api-key header; Foundry's OpenAI-compatible /openai/v1 endpoint rejects that with 400 unknown_model. The router now prefixes a bare EMBEDDING_MODEL with openai/ before the litellm.aembedding call, pinning detection to the Bearer-auth OpenAI-compatible path. An explicit provider/ prefix (e.g. azure/<deployment> for a classic Azure OpenAI resource) is honored unchanged.
• Operator-facing vs wire model split — _EMBED_MODEL stays the reported model name; only _EMBED_LITELLM_MODEL (pinned) goes upstream. Callers never see the routing prefix.
• Fail loud, stay optional — unchanged semantics, now documented: 503 until EMBEDDING_API_KEY (or the OPENAI_API_KEY fallback) is set, 502 on upstream failure with the real error logged server-side only. No new required config; a clean fork boots exactly as before.
• Config surface (env-driven, all optional): EMBEDDING_API_KEY, EMBEDDING_BASE_URL, EMBEDDING_MODEL (default text-embedding-3-small), EMBEDDING_TIMEOUT_SECONDS, EMBEDDING_MAX_INPUTS — wired through docker-compose.yml and .env.example.

Test evidence

pytest -q services/model-router/tests (same invocation as CI's model-router step): 200 passed locally on Python 3.13.

New/updated coverage in services/model-router/tests/test_embeddings.py (10 passed):

• prefix pin: bare model → openai/text-embedding-3-small; explicit azure/... and openai/... honored without stacking; import-time default is pinned
• Foundry-shaped end-to-end (mocked upstream): pinned model + azure.com api_base + key all reach litellm.aembedding
• response model field stays unprefixed when the upstream omits it
• fail-loud paths: 503 unconfigured, 400 missing/oversized input, 502 provider error

Docs

• docs/walkthroughs/azure-foundry-embeddings.md — end to end: create the Foundry text-embedding-3-small deployment (portal + az CLI), set the three env vars, verify a 1536-dim vector with curl, and a troubleshooting section that explains the unknown_model mechanism, plus 503/502/wrong-dimension cases.
• services/model-router/README.md — embeddings provider-config section + /v1/embeddings endpoint row.

🤖 Generated with Claude Code