feat(providers): add OrcaRouter provider support

[Marc-oss-hub]

Summary

Adds OrcaRouter as a first-class provider in llmwiki. OrcaRouter is an OpenAI-compatible AI gateway whose API requires namespaced model ids (e.g. openai/gpt-4o-mini), so the provider's default model is openai/gpt-4o-mini.

What this changes

• src/providers/orcarouter.ts — new OrcaRouterProvider extending OpenAIProvider, with the fixed base URL https://api.orcarouter.ai/v1 and fail-closed embed/embedBatch (mirrors the existing MiniMax wiring).
• src/utils/provider.ts — orcarouter added to SUPPORTED_PROVIDERS and the buildProvider factory; getOrcaRouterProvider() reads ORCAROUTER_API_KEY and throws a clear error when it is missing.
• src/utils/constants.ts — PROVIDER_MODELS.orcarouter = "openai/gpt-4o-mini".
• src/utils/provider-guard.ts — ORCAROUTER_API_KEY entry in the credential key-var map.
• src/utils/embedding-provider.ts — comment updated to note orcarouter is embedding-incapable (fail-closed).
• test/provider-factory.test.ts, test/embed-batch-providers.test.ts, test/embedding-provider.test.ts — factory construction, missing-key error, fail-closed embeddings, and embedding-capability coverage, mirroring the MiniMax tests.
• docs/configuration/providers.mdx, docs/configuration/environment-variables.mdx, README.md — OrcaRouter provider tab, env-var reference, and provider table row.

Why a separate provider rather than the OpenAI-compatible escape hatch

OrcaRouter is OpenAI-compatible, but the generic openai provider defaults to a bare model id (gpt-4o), which OrcaRouter rejects — its API requires a namespaced id such as openai/gpt-4o-mini. A dedicated orcarouter provider ships the correct namespaced default and mirrors the existing MiniMax provider pattern (a hosted OpenAI-compatible gateway with its own base URL, key env var, and fail-closed embeddings), so users get a correct, discoverable setup instead of remembering to pair OPENAI_BASE_URL with a namespaced LLMWIKI_MODEL.

How to use it

export LLMWIKI_PROVIDER=orcarouter
export ORCAROUTER_API_KEY=sk-orca-...
llmwiki compile

Model override (any namespaced id):

export LLMWIKI_MODEL=openai/gpt-4o-mini

Verification

• Type-check (npx tsc --noEmit) passes; npm run build succeeds.
• Provider tests pass: provider-factory.test.ts, embed-batch-providers.test.ts, embedding-provider.test.ts, embedding-provider-guard.test.ts, embedding-provider-model.test.ts — 57 tests.
• Full suite: 4626 passed. The 227 failures are pre-existing Windows-environment issues (symlink EPERM, POSIX path separators, harness auth env) — reproduced on pristine main via git stash.
• fallow audit on the changed files reports no issues.
• L3 live test: getProvider() → OrcaRouterProvider.complete() with a real key against https://api.orcarouter.ai/v1 returned a valid completion.

Security: no secrets, credentials, or private data are introduced, transmitted, or exposed by this change.

I'm an engineer on the OrcaRouter team.

[ethanj]

Thanks for this, and welcome. The provider wiring is careful work. You found every registration point, including the two in docs/ where MiniMax isn't even listed, and mirroring the MiniMax pattern was the right call. I also appreciate you disclosing that you work on OrcaRouter.

I verified the central premise and it holds. GET /v1/models returns 192 models, 190 of them namespaced, and bare gpt-4o is absent, so the generic openai provider genuinely would fail out of the box. A dedicated provider is justified rather than redundant.

Two things to fix before I can merge.

1. The docs change breaks the MDX build.

The OrcaRouter tab was inserted before the GitHub Copilot tab's </Tab> rather than after it, so the file now has six <Tab> opens and five closes. Copilot is left unclosed when </Tabs> is reached. Compiling the file confirms it:

main:        COMPILES OK
this branch: Unexpected closing tag `</Tabs>`, expected corresponding
             closing tag for `<Tab>` (177:3-177:31)

Fix is placement only: emit </Tab> after the Copilot <Warning>, before <Tab title="OrcaRouter">.

2. The embeddings rationale isn't accurate.

The comment in src/utils/embedding-provider.ts now says orcarouter throws "because their APIs expose no embeddings endpoint", but OrcaRouter does expose one:

POST /v1/embeddings                  -> 401   (exists, needs auth)
POST /v1/definitely-not-a-real-path  -> 404   (control: unknown routes 404)

and /v1/models lists openai/text-embedding-3-small, -3-large, -ada-002, plus two Gemini embedding models.

Failing closed for a first cut is fine by me. Wiring embeddings up means touching EMBEDDING_CAPABLE_PROVIDERS, EMBEDDING_CREDENTIALS, EMBEDDING_BACKENDS and EMBEDDING_ENDPOINT_VARS, plus EMBEDDING_MODELS and EMBED_BATCH_SIZES in constants.ts, and that's reasonably a separate PR. But could you change the stated reason to "not wired up in llmwiki yet" rather than "the API has no endpoint"? Same for the "unverified" wording in providers.mdx. That comment is what the next person reads when deciding whether OrcaRouter embeddings are possible, and the current version closes the question wrongly.

(If you'd rather just wire them up here, that works too.)

Two smaller things, neither blocking:

• src/utils/provider.ts's header comment now reads "(Anthropic, OpenAI, Ollama, MiniMax, or OrcaRouter)" but the file also imports Copilot and the Agent SDK provider. It was already incomplete before you touched it. Since you're editing that line anyway, either complete it or drop the parenthetical.
• openai/gpt-4o-mini is the only "mini" default in the repo; every other provider defaults to a flagship. Compile runs structured tool-call extraction where model capability shows up directly in output quality, so I'd like a sentence on why mini is the right default, or pick something stronger. Happy to defer to you here since you know the gateway.

I've approved the CI run so you'll get checks on the next push. Let me know if any of this is unclear or you'd like a hand with the embeddings wiring.