feat(providers): support common providers from models.dev

Repository metrics

Stars: (1 star)
PR merge metrics: (PR metrics pending)

Description

Problem

Maka hand-maintains provider and model facts across core, runtime, Desktop, CLI, and headless. Adding a provider requires changing parallel lists, which creates inconsistent behavior and makes provider support difficult to verify.

LiteLLM would add a routing dependency without fixing ownership.

Direction

Vendor a versioned models.dev snapshot and update it deterministically during releases or major upstream changes. Do not fetch models.dev at runtime or add models.dev/LiteLLM as runtime dependencies.

Expose one provider registry composed from:

models.dev provider and model facts;
Maka's shared runtime adapters;
minimal provider overrides for authentication, headers, endpoints, discovery, or request differences.

Provider /models responses are authoritative for account-specific availability. The checked-in snapshot is the fallback. Exact model ids must never be rewritten.

Azure, Bedrock, and Vertex remain out of scope because IAM, project, and region configuration require separate product work. LiteLLM remains available through the generic openai-compatible connection, but Maka does not ship a dedicated LiteLLM preset or introduce LiteLLM as a routing layer.

Invariants

Every provider checkbox below represents a complete product slice:

one stable persisted provider id;
registry-owned defaults, catalog placement, and runtime/discovery behavior;
credential configuration across relevant Desktop, CLI, and headless paths;
account-specific model discovery where supported, with snapshot fallback;
exact model-id preservation;
model selection and an agent tool-call run;
deterministic tests without secrets or raw provider responses;
a sanitized live smoke before support is marked complete.

Provider-specific behavior belongs only in the registry adapter/override layer.

Contributor guardrails

Before starting a slice, check the latest issue comments and open PRs. Do not duplicate an actively claimed provider; post or update a claim so parallel work can move to an unclaimed checklist item.

Brand assets are a merge gate:

Use a real, existing provider SVG from an official brand package or a trusted open-source source such as Lobe Icons. If Lobe Icons has no suitable mark, use the provider's official download or another established open-source repository.
Record the source repository, released package version and/or immutable commit, exact upstream path, license, and full SHA-256. Vendor the SVG byte-for-byte. Never hand-draw, trace, AI-generate, convert a raster image to SVG, or silently rewrite the upstream SVG to make it render.
Reuse the shared provider-logo path for catalog, detail, and first-run surfaces. Extend the packaged third-party notice inventory and keep a deterministic build check proving the notice survives into the renderer distribution; do not create another notice or header mechanism.
An external SVG loaded through <img> does not inherit the parent's currentColor. Preserve upstream bytes and use the existing theme-aware CSS mask/currentColor seam for monochrome marks. Verify the computed mask and color in the rendered catalog and detail states; DOM visibility alone is insufficient.

Implementation guardrails:

“OpenAI-compatible” does not prove identical authentication, discovery, request, or tool-call behavior. Confirm official documentation and exercise a deterministic two-stage loop: provider requests a tool, Maka executes it and returns the tool result, then the provider returns the final assistant response.
A no-auth provider must omit Authorization; do not inject a dummy API key. Keep exact model IDs unchanged through discovery, persistence, selection, both tool-call turns, and fallback.
Direct API, Coding Plan, Token Plan, and Agent Plan access paths from the same vendor remain separate persisted provider ids whenever endpoint, key, billing, model allowlist, or permitted use differs. Many subscription plans permit only interactive coding/agent tools; deterministic tests must stay fake, and any live smoke must use Maka interactively with a user-owned key.
Start each flat PR from the latest main. Give shared files and seams one owner, then rebase dependent slices instead of implementing parallel versions.
Local Desktop E2E may be deferred to CI; the CI E2E job remains a merge gate. When a local E2E run is needed for diagnosis or visual evidence, use one worker. Treat Electron/fixture startup timeouts as infrastructure only after log evidence and a clean serial rerun; do not change production code to mask a resource flake.

PR sizing

The checklist describes independently verifiable product slices, not mandatory one-PR phases.

Default to one provider or plan variant per PR. A small cohort may share one PR only when every member:

uses the exact same runtime adapter;
uses the same authentication and discovery behavior;
requires no provider-specific override;
can be tested and reverted as one unit.

Do not split a provider vertically into separate registry, runtime, UI, and test PRs. Each merged PR must leave the provider usable and independently revertible.

The current upper bound is 48 implementation PRs. The final number may be lower when implementation evidence proves that a small regional cohort is genuinely identical.

Delivery order

flowchart LR
  P1["Phase 1<br/>Tracer bullet"] --> P2["Phase 2<br/>Registry foundation"]
  P2 --> P3["Phase 3<br/>Hosted APIs"]
  P2 --> P4["Phase 4<br/>Model plans"]
  P2 --> P5["Phase 5<br/>Local runtimes"]
  P2 --> P6["Phase 6<br/>First run"]
  P2 --> P7["Phase 7<br/>Contract foundation"]
  P3 --> P8["Phase 8<br/>Release closeout"]
  P4 --> P8
  P5 --> P8
  P6 --> P8
  P7 --> P8

Phases 3–6 may proceed in parallel from the merged Phase 2 foundation. Phase 7 may begin once representative access paths exist for API keys, plans, aggregators, local no-auth or optional-auth runtimes, OAuth, regional endpoints, discovery and fallback, reasoning, and tool calls. Phase 7 stays additive: it may add registry- and capability-derived conformance coverage and gap reporting, but it must not remove compatibility paths or claim release completion. Phase 8 starts only after every remaining Phase 3–6 item is delivered or explicitly deferred out of the current acceptance scope.

Delivered

Phase 1: tracer bullet and SiliconFlow vertical slice: #863
Phase 2: generic registry foundation and migration of existing provider ids: #866

Existing providers retain their persisted ids and observable behavior.

Phase 3: Hosted APIs

Add the remaining direct API providers and OpenRouter.

Anthropic, OpenAI, Gemini, DeepSeek, Moonshot, MiniMax, and SiliconFlow already have registry/runtime paths. Phase 7 will include them in the final contract and smoke matrix.

Phase 4: Model plans

Kimi Coding Plan and Z.AI Coding Plan already exist and were migrated onto the shared registry path in Phase 2.

Add the remaining plan-specific variants with their own persisted ids, authentication, endpoints, and discovery behavior:

A direct API provider and its plan variant remain separate product slices even when one person implements both.

Phase 5: Local runtimes

Validate Ollama against the complete registry contract and make only demonstrated compatibility fixes: #874
Validate exact :cloud model aliases through a signed-in local Ollama daemon without adding another persisted provider id: #907
Add LM Studio, including no-auth configuration and local model discovery: #886
Add LocalAI with its default local endpoint, model discovery, optional authentication, and exact model aliases: #915

Phase 6: First run

Consume the registry-owned recommended provider set and route Browse all providers to the shared Settings catalog: #875

Do not maintain another onboarding provider list or redesign the connection-management flow.

Candidate watchlist (not part of Phase 3–6 acceptance)

These candidates remain intentionally outside the completion matrix until their lifecycle, public contract, or demand is strong enough:

Baidu Qianfan Coding/Token Plan personal migration, pending an authoritative current lifecycle contract;
Volcengine Ark Agent Plan;
JD Cloud Coding Plan, pending an auditable first-party endpoint contract;
Baseten, SambaNova Cloud, KUAE Cloud Coding Plan, CTYun Coding Token Plan, SCNet plans, PPIO, Infinigence GenStudio, and team-oriented Token Plans.

Explicit exclusions:

GitHub Models, which GitHub will fully retire on 2026-07-30;
Infini Coding Plan, which stopped service on 2026-06-26;
a dedicated ModelScope preset while it remains a no-SLA experimental inference service;
dedicated vLLM or arbitrary self-hosted deployment ids, which remain covered by openai-compatible;
Replicate, whose prediction contract is not Maka's agent chat/tool-call contract;
Baichuan and SenseNova until a current public two-stage tool-call contract exists.

Phase 7: Contract foundation

Phase 7 may begin before every Phase 3–4 provider is finished. It defines an open-world contract: provider rows may continue to be added, while shared behavior and provider-owned differences remain explicit and testable.

Generate deterministic conformance coverage from READY_PROVIDER_TYPES, registry metadata, and declared capabilities so future ready providers enter the matrix automatically: #974
Report missing or inapplicable contract dimensions explicitly without hard-coding a closed provider list: #974
Keep provider-specific behavior in the adapter/override layer while shared credential, discovery, persistence, and product surfaces remain registry-driven: #974

Do not use Phase 7 to remove compatibility paths, declare the release complete, or start Phase 8 cleanup.

Phase 8: Release closeout

Run Phase 8 only after the remaining Phase 3–6 scope is delivered or explicitly deferred out of the current acceptance matrix:

Confirm that every remaining in-scope provider is covered by the generated contract matrix
Remove replaced hand-written provider/model tables and temporary migration paths while retaining persisted-id compatibility

Final release gate:

Record a sanitized live smoke for every target provider using at least one real model

Secrets, credentials, raw provider responses, and sensitive account data must never be committed, logged, copied into fixtures, or posted to GitHub.

Acceptance

Contributor guide

Research direction: Review the Phase 3 checklist for unclaimed providers, pick one (e.g., Alibaba direct API), implement it following the contributor guardrails in the issue description, and submit a single provider PR.
Tech stack: typescript
Domain: backendapi
Issue type: Feature
Difficulty: 4
Estimated time: Over 1 week
Activity status: Active
Clarity: Mostly clear
Prerequisites: TypeScriptGit
Newbie friendliness: 40