majordomo/docs/adr/0026-kimi-builtin.md

ADR-0026: Kimi (Moonshot AI) built-in provider

Status: Accepted — 2026-07-18

Context

Moonshot AI's Kimi models (Kimi K2, moonshot-v1-*, and the vision variants) are served over an OpenAI-compatible Chat Completions API at https://api.moonshot.ai/v1 (https://api.moonshot.cn/v1 for China), authenticated with a bearer key. mort wants Kimi as a first-class failover tier, so kimi/kimi-k2-... should parse, chain, and alias out of the box with a dedicated KIMI_API_KEY env var — the same ergonomics as openai, anthropic, and google.

Two tensions:

• The wire protocol is byte-for-byte OpenAI Chat Completions, so a hand-rolled client would duplicate provider/openai for zero gain (ADR-0007 forbids it), exactly as ADR-0015 found for llama-swap.
• The README's current stance is that arbitrary OpenAI-compatible endpoints (Groq, Together, …) are consumer-registered, not baked in. Blessing Kimi as a built-in is a deliberate, narrow exception justified by the north star: mort names Kimi directly in its tiers, and a built-in with KIMI_API_KEY keeps mort's config free of boilerplate openai.New(WithName/WithBaseURL) wiring.

Decision

• No new package. The kimi built-in and kimi:// DSN scheme both construct provider/openai pointed at the Moonshot base URL — the chat path inherits every openai feature/fix automatically (like llama-swap's chat).
• The built-in reads its key through the registry's injected envLookup (KIMI_API_KEY only — no MOONSHOT_API_KEY alias, per the project owner) so it stays hermetically testable via WithEnvLookup.
• WithAPIKey is passed unconditionally, even when empty. openai.New defaults its key to OPENAI_API_KEY; without an explicit override an unset KIMI_API_KEY would silently authenticate Kimi with the OpenAI key. Passing the (possibly empty) lookup result severs that fallthrough.
• New openai.WithAPIKeyName("KIMI_API_KEY") option customizes only the synthetic-401 missing-key hint (default OPENAI_API_KEY), so a keyless kimi call tells the operator the right variable to set.
• The default endpoint is the international host (kimiBaseURL). The China endpoint (or any other host) is reachable with a kimi:// DSN, e.g. LLM_KCN=kimi://[email protected]/v1. The kimi:// scheme is an OpenAI-compatible target labeled kimi with the same key-name hint; it is intentionally near-identical to openai:// — its value is a clear name in specs and error reporting.

Consequences

• kimi/<model> is first-class in Parse, chains, aliases, and health/failover with no consumer wiring; model ids pass through verbatim (no catalog).
• Chat, streaming, tools, and structured output ride the openai client. Image inputs work at the client level but only the Moonshot vision models accept them (matrix footnote ³).
• WithAPIKeyName is a small, generally useful addition to provider/openai; the default preserves existing behavior for every other openai-compat target.
• Blessing one third-party endpoint as a built-in sets a precedent; future ones should clear the same bar (a named consumer needs it in-config), not be added reflexively — RegisterProvider/LLM_* remain the path for the rest.