feat: add OrcaRouter as a first-class LLM provider

[dulcestentaciones2920-debug]

Summary

Knowhere describes itself as "the memory layer between complex, dirty documents and AI agents." The agents consuming that memory make a steady stream of LLM/VLM calls through Knowhere's parsing, page-memory, and map-nav retrieval pipelines. Today those calls are routed to a handful of named providers — DeepSeek, DashScope/Qwen, Zhipu GLM, Volcengine ARK — by model-name prefix in OpenAICompatibleClientSync, with credentials supplied through AIConfig env vars. There is no way to run that traffic through a gateway without treating it as an anonymous custom base URL.

This PR adds OrcaRouter as a first-class named provider on exactly that same surface. A self-hoster sets ORCA_API_KEY, points NORMOL_MODEL (or any parse/retrieval model) at an orcarouter/* model, and every text and vision call routes through the OrcaRouter gateway — no application code changes, no base-URL plumbing.

OrcaRouter is an OpenAI-compatible AI gateway built for both models and agents. Like OpenRouter, it exposes a provider/model namespace across many models — but it also combines adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance behind the same endpoint. Adding orcarouter as a first-class provider means Knowhere users can use that stack directly, without treating OrcaRouter as an anonymous custom base URL.

It also runs gateway-level, zero-trust security for AI agents on the same endpoint — screening every prompt/response and governing every tool call on a default-deny basis, with no application code changes.

What changed

• packages/shared-python/shared/core/config/ai.py — new ORCA_API_KEY and ORCA_URL (default https://api.orcarouter.ai/v1) on AIConfig, mirroring DS_KEY/DS_URL.
• packages/shared-python/shared/services/ai/openai_compatible_client_sync.py — orcarouter/* model names resolve to the OrcaRouter base URL and ORCA_API_KEY, the same way the existing glm / doubao / ep- branches route to GLM and ARK. This covers the parsing summarizer, page-memory VLM calls, and the map-nav retrieval backend, all of which go through get_openai_client.
• apps/api/.env.example / apps/worker/.env.example — document ORCA_API_KEY and ORCA_URL.
• packages/shared-python/shared/tests/test_openai_client_routing.py — unit tests asserting orcarouter/* resolves to OrcaRouter credentials and that non-OrcaRouter models keep existing DeepSeek routing.

Verification

• ruff check apps packages — all checks passed.
• pyright --project pyproject.toml on the full CI path — 0 errors.
• pytest packages/shared-python/shared/tests/test_openai_client_routing.py (+ related test_nav_llm_backend.py, test_llm_config.py) — passed.
• Live test through the real code path (get_openai_client(model="orcarouter/fusion")) against https://api.orcarouter.ai/v1 with a real key returned content='OK' with token usage — HTTP 200.

Deployment Notes

• New optional environment variables: ORCA_API_KEY, ORCA_URL (defaults to https://api.orcarouter.ai/v1). No existing variable is changed; fully backwards compatible. No migrations, queue, or storage changes.

Checklist

• Tests were added or updated when behavior changed
• Public docs, examples, or OpenAPI contracts were updated when needed
• Database migrations are idempotent and safe to deploy
• Logs, errors, and validation paths avoid leaking secrets or user data
• The pull request description explains any breaking or user-visible change

---

To try it: set ORCA_API_KEY and e.g. NORMOL_MODEL=orcarouter/fusion in apps/api/.env / apps/worker/.env.

I'm an engineer on the OrcaRouter team. Feedback welcome — Discord: discord.gg/YEubt8enRA · X: https://x.com/OrcaRouter