Module: Clacky::Providers

Defined in:
lib/clacky/providers.rb

Overview

Built-in model provider presets Provides default configurations for supported AI model providers

Constant Summary collapse

PRESETS =

Provider preset definitions Each preset includes:

  • name: Human-readable provider name
  • base_url: Default API endpoint
  • api: API type (anthropic-messages, openai-responses, openai-completions)
  • default_model: Recommended default model
  • capabilities (optional): provider-level capability hash (e.g. { "vision" => false }). Applies to all models under this provider unless overridden by model_capabilities below.
  • model_capabilities (optional): per-model capability override map, { "<model_name>" => { "" => bool, ... } }. Use this when a single provider hosts models with different capabilities (e.g. openclacky hosts both vision-capable Claude and text-only DeepSeek).
  • model_api_overrides (optional): per-model API-type override map, { <Regexp|String> => "anthropic-messages" | "openai-completions" | ... }. Keys can be a plain model name or a Regexp matched against the model. The first key that matches wins; if none match, the provider's top-level "api" is used. Used so e.g. OpenRouter can keep "openai-responses" as its default while routing Claude models through the native Anthropic endpoint (which preserves cache_control fidelity).
{
  "openclacky" => {
    "name" => "OpenClacky",
    "base_url" => "https://api.openclacky.com",
    "api" => "bedrock",
    "default_model" => "abs-claude-sonnet-5",
    "models" => [
      "abs-claude-fable-5",
      "abs-claude-opus-5",
      "abs-claude-opus-4-8",
      "abs-claude-opus-4-7",
      "abs-claude-opus-4-6",
      "abs-claude-sonnet-5",
      "abs-claude-sonnet-4-6",
      "abs-claude-sonnet-4-5",
      "abs-claude-haiku-4-5",
      "dsk-deepseek-v4-pro",
      "dsk-deepseek-v4-flash",
      "or-gemini-3-1-pro",
      "or-gemini-3-5-flash"
    ],
    # Image generation models served by the openclacky platform
    # gateway. The gateway exposes a standard OpenAI-compatible
    # /v1/images/generations endpoint, so the same OpenAICompat
    # provider class handles them. `or-` prefix is a routing alias
    # only — the platform may dispatch to OpenRouter or Vertex AI
    # (Gemini Nano Banana family) depending on the model.
    "image_models" => [
      "or-gemini-3-pro-image",
      "or-gemini-3-1-flash-image",
      "or-gpt-image-2"
    ],
    "image_model_aliases" => {
      "or-gemini-3-pro-image"      => "Nano Banana Pro",
      "or-gemini-3-1-flash-image"  => "Nano Banana 2",
      "or-gpt-image-2"             => "GPT Image 2"
    },
    "default_image_model" => "or-gemini-3-1-flash-image",
    # Video generation models served by the openclacky gateway, which
    # routes them to Vertex AI Veo (async predictLongRunning under the
    # hood; the gateway hides the polling and returns the MP4 inline).
    "video_models" => [
      "or-veo-3-1",
      "or-veo-3-1-fast",
      "or-veo-3",
      "or-veo-3-fast"
    ],
    "video_model_aliases" => {
      "or-veo-3-1"      => "Veo 3.1",
      "or-veo-3-1-fast" => "Veo 3.1 Fast",
      "or-veo-3"        => "Veo 3",
      "or-veo-3-fast"   => "Veo 3 Fast"
    },
    "default_video_model" => "or-veo-3-1",
    # Text-to-speech models served by the openclacky gateway, which
    # routes them to Vertex AI Gemini 2.5 (responseModalities=["AUDIO"]).
    # The gateway returns WAV inline as base64.
    "audio_models" => [
      "or-tts-gemini-2-5-flash",
      "or-tts-gemini-2-5-pro"
    ],
    "audio_model_aliases" => {
      "or-tts-gemini-2-5-flash" => "Gemini 2.5 Flash TTS",
      "or-tts-gemini-2-5-pro"   => "Gemini 2.5 Pro TTS"
    },
    "default_audio_model" => "or-tts-gemini-2-5-flash",
    # Speech-to-text models served by the openclacky gateway, which
    # routes them to Vertex AI Gemini (generateContent with inline
    # audio parts). The gateway returns transcription text.
    "stt_models" => [
      "or-stt-gemini-3-5-flash",
      "or-stt-gemini-1-5-pro"
    ],
    "stt_model_aliases" => {
      "or-stt-gemini-3-5-flash" => "Gemini 3.5 Flash STT",
      "or-stt-gemini-1-5-pro"   => "Gemini 1.5 Pro STT"
    },
    "default_stt_model" => "or-stt-gemini-3-5-flash",
    # Video understanding models served by the openclacky gateway, which
    # routes video frames to Gemini (generateContent with inline image
    # parts). The gateway returns analysis text.
    "video_understanding_models" => [
      "or-gemini-3-5-flash",
      "or-gemini-3-1-pro"
    ],
    "video_understanding_model_aliases" => {
      "or-gemini-3-5-flash" => "Gemini 3.5 Flash",
      "or-gemini-3-1-pro"   => "Gemini 3.1 Pro"
    },
    "default_video_understanding_model" => "or-gemini-3-5-flash",
    # Default OCR sidecar — used when the primary model is text-only.
    # Candidates are derived from the provider's vision-capable models;
    # this just picks the cheap+fast default to surface in "auto" mode.
    "default_ocr_model" => "or-gemini-3-5-flash",
    # Provider-level default: the Claude family served here is vision-capable.
    "capabilities" => { "vision" => true }.freeze,
    # Model-level overrides: DeepSeek models routed through this provider
    # are text-only; images uploaded for them must be downgraded to disk refs.
    # Gemini 3.1 Pro keeps the provider-default vision=true (it accepts
    # image/audio/video input natively via OpenRouter).
    "model_capabilities" => {
      "dsk-deepseek-v4-pro"   => { "vision" => false }.freeze,
      "dsk-deepseek-v4-flash" => { "vision" => false }.freeze
    }.freeze,
    # Per-primary lite pairing: keys are "strong" primary models, values
    # are the lite sidekick to auto-inject when that primary is the
    # default. Lite is consumed by some subagents for cheap/fast work;
    # weak models (haiku / v4-flash / 3-5-flash) ARE the lite tier
    # themselves, so they're intentionally not listed here as keys —
    # no injection happens when the default model is already lite-class.
    "lite_models" => {
      "abs-claude-fable-5"    => "abs-claude-haiku-4-5",
      "abs-claude-opus-5"     => "abs-claude-haiku-4-5",
      "abs-claude-opus-4-8"   => "abs-claude-haiku-4-5",
      "abs-claude-opus-4-7"   => "abs-claude-haiku-4-5",
      "abs-claude-opus-4-6"   => "abs-claude-haiku-4-5",
      "abs-claude-sonnet-5"   => "abs-claude-haiku-4-5",
      "abs-claude-sonnet-4-6" => "abs-claude-haiku-4-5",
      "abs-claude-sonnet-4-5" => "abs-claude-haiku-4-5",
      "dsk-deepseek-v4-pro"   => "dsk-deepseek-v4-flash",
      "or-gemini-3-1-pro"     => "or-gemini-3-5-flash"
    },
    # Fallback chain: if a model is unavailable, try the next one in order.
    # Keys are primary model names; values are the fallback model to use instead.
    "fallback_models" => {
      "abs-claude-fable-5"    => "abs-claude-opus-5",
      "abs-claude-opus-5"     => "abs-claude-opus-4-8",
      "abs-claude-sonnet-5"   => "abs-claude-sonnet-4-6",
      "abs-claude-sonnet-4-6" => "abs-claude-sonnet-4-5"
    },
    # Secondary gateway URL used when the primary base_url is unreachable
    # after max retries. The model name stays the same — only the endpoint
    # changes. Nil / absent means no URL fallback for this provider.
    "fallback_base_url" => "https://llm.1024code.com",
    # Two selectable endpoints exposed in the Base URL dropdown:
    #   Primary   — global CDN, lowest latency for most regions.
    #   Secondary — China-optimised relay (1024code.com), useful when
    #               the primary is unreachable from mainland China.
    "endpoint_variants" => [
      { "label" => "Primary (Global)",  "label_key" => "settings.models.baseurl.variant.openclacky_primary",   "base_url" => "https://api.openclacky.com" }.freeze,
      { "label" => "Secondary (China)", "label_key" => "settings.models.baseurl.variant.openclacky_secondary", "base_url" => "https://llm.1024code.com"   }.freeze
    ].freeze,
    "website_url" => "https://www.openclacky.com/ai-keys"
  }.freeze,

  "openrouter" => {
    "name" => "OpenRouter",
    "base_url" => "https://openrouter.ai/api/v1",
    "api" => "openai-responses",
    "default_model" => "anthropic/claude-sonnet-4-6",
    # Curated default lineup. OpenRouter's full catalogue is enormous
    # (hundreds of models) and the live /models endpoint isn't always
    # reachable from every region — shipping a small list of the
    # mainstream Claude + GPT entries gives users a working dropdown
    # out of the box. Users can still type any other OpenRouter model
    # ID manually; this list only seeds the picker.
    "models" => [
      "anthropic/claude-sonnet-4-6",
      "anthropic/claude-opus-4-8",
      "anthropic/claude-opus-4-7",
      "anthropic/claude-opus-4-6",
      "anthropic/claude-haiku-4-5",
      "openai/gpt-5.5",
      "openai/gpt-5.4",
      "openai/gpt-5.4-mini"
    ],
    # Per-primary lite pairing — Claude family pairs with Haiku, GPT
    # family pairs with the mini variant. Mirrors the openclacky and
    # openai presets above so subagents on OpenRouter get a sensible
    # cheap/fast sidekick automatically.
    "lite_models" => {
      "anthropic/claude-sonnet-4-6" => "anthropic/claude-haiku-4-5",
      "anthropic/claude-opus-4-8"   => "anthropic/claude-haiku-4-5",
      "anthropic/claude-opus-4-7"   => "anthropic/claude-haiku-4-5",
      "anthropic/claude-opus-4-6"   => "anthropic/claude-haiku-4-5",
      "openai/gpt-5.5"              => "openai/gpt-5.4-mini",
      "openai/gpt-5.4"              => "openai/gpt-5.4-mini"
    },
    # Per-model API type overrides. Matched by Regexp against the model name.
    # Why this exists: OpenRouter proxies Claude via both its OpenAI-compatible
    # /chat/completions endpoint AND a native Anthropic /v1/messages endpoint.
    # The OpenAI shim is lossy for Claude's cache_control semantics — prefix
    # rewrites inside the proxy cause ~10% prompt-cache misses. Pinning
    # "anthropic/*" (and any direct "claude-*" alias) to the native Anthropic
    # endpoint preserves cache_control byte-for-byte and matches what Claude
    # Code CLI does internally. Non-Claude models (Gemini, GPT, etc.) keep
    # the OpenAI shim — that's what OpenRouter documents as their primary.
    "model_api_overrides" => {
      /\Aanthropic\// => "anthropic-messages",
      /\Aclaude[-.]/  => "anthropic-messages"
    }.freeze,
    # Image generation via OpenRouter is currently routed through the
    # openclacky platform gateway (see "openclacky" provider above) which
    # handles the OpenRouter chat-completions + modalities translation.
    # Direct OpenRouter image config is not exposed here — leave empty
    # until we ship a dedicated client-side adapter for that protocol.
    "image_models" => [],
    "default_image_model" => nil,
    "default_ocr_model" => "google/gemini-2.5-flash",
    "website_url" => "https://openrouter.ai/keys"
  }.freeze,

  "deepseekv4" => {
    "name" => "DeepSeek V4",
    # DeepSeek API is compatible with both OpenAI and Anthropic formats.
    # We use the OpenAI-compatible endpoint here (matches kimi/minimax/glm style).
    # For Anthropic-format usage, point base_url at https://api.deepseek.com/anthropic
    # and change "api" to "anthropic-messages".
    "base_url" => "https://api.deepseek.com",
    "api" => "openai-completions",
    "default_model" => "deepseek-v4-pro",
    "lite_model" => "deepseek-v4-flash",
    # Note: deepseek-chat and deepseek-reasoner are legacy aliases being
    # deprecated on 2026-07-24; they map to deepseek-v4-flash's non-thinking
    # and thinking modes respectively. Prefer deepseek-v4-flash / deepseek-v4-pro.
    "models" => [
      "deepseek-v4-flash",
      "deepseek-v4-pro",
    ],
    # DeepSeek V4 API does not accept image inputs — text-only across all models.
    "capabilities" => { "vision" => false }.freeze,
    "website_url" => "https://platform.deepseek.com/api_keys"
  }.freeze,

  "minimax" => {
    "name" => "Minimax",
    "base_url" => "https://api.minimaxi.com/v1",
    "api" => "openai-completions",
    "default_model" => "MiniMax-M3",
    "models" => ["MiniMax-M3", "MiniMax-M2.7", "MiniMax-M2.5"],
    # MiniMax operates two regional endpoints with identical APIs & model
    # lineup — mainland China (.com) and international (.io). Listing both
    # lets find_by_base_url identify either one as provider "minimax",
    # so capability checks (vision=false) fire correctly regardless of
    # which endpoint the user configured.
    "endpoint_variants" => [
      { "label" => "Mainland China", "label_key" => "settings.models.baseurl.variant.mainland_cn",   "base_url" => "https://api.minimaxi.com/v1", "region" => "cn"   }.freeze,
      { "label" => "International",  "label_key" => "settings.models.baseurl.variant.international", "base_url" => "https://api.minimax.io/v1",   "region" => "intl" }.freeze
    ].freeze,
    # MiniMax M2.5/M2.7 are text-only on this endpoint. M3 (released 2026-06-01)
    # is natively multimodal — it accepts image input via OpenAI-style
    # image_url content parts — so it overrides the provider-level
    # vision=false below. M3 exposes a 1,000,000-token context window
    # (M2.7: 204,800; M2.5: 40,960).
    "capabilities" => { "vision" => false }.freeze,
    "model_capabilities" => {
      "MiniMax-M3" => { "vision" => true }.freeze
    }.freeze,
    "default_ocr_model" => "MiniMax-M3",
    "website_url" => "https://platform.minimax.io/"
  }.freeze,

  "kimi" => {
    "name" => "Kimi (Moonshot)",
    "base_url" => "https://api.moonshot.cn/v1",
    "api" => "openai-completions",
    "default_model" => "kimi-k3",
    "models" => ["kimi-k3", "kimi-k2.7-code", "kimi-k2.7-code-highspeed", "kimi-k2.6", "kimi-k2.5"],
    # Moonshot operates two regional endpoints with identical APIs & model
    # lineup — mainland China (.cn) and international (.ai). These are the
    # pay-as-you-go Open Platform endpoints; the subscription-billed
    # Coding Plan lives at api.kimi.com/coding with the unified
    # `kimi-for-coding` model alias and is exposed as a separate
    # top-level "kimi-coding" preset (different domain, distinct billing
    # model, marketed by Moonshot as the standalone Kimi Code product).
    # Listing both PAYG variants here lets find_by_base_url identify
    # either one as provider "kimi", so downstream capability checks,
    # fallback chains, and provider-specific behaviours work regardless
    # of which endpoint the user configured.
    "endpoint_variants" => [
      { "label" => "Mainland China", "label_key" => "settings.models.baseurl.variant.mainland_cn",   "base_url" => "https://api.moonshot.cn/v1", "region" => "cn"   }.freeze,
      { "label" => "International",  "label_key" => "settings.models.baseurl.variant.international", "base_url" => "https://api.moonshot.ai/v1", "region" => "intl" }.freeze
    ].freeze,
    # k3 / k2.7-code / k2.5 / k2.6 are multimodal; legacy k2 text-only models need model_capabilities override if added.
    "capabilities" => { "vision" => true }.freeze,
    "default_ocr_model" => "kimi-k3",
    "website_url" => "https://platform.moonshot.cn/console/api-keys"
  }.freeze,

  "kimi-coding" => {
    "name" => "Kimi Code (Coding Plan)",
    # Subscription-billed Kimi Code endpoint — separate product from the
    # PAYG Moonshot Open Platform (api.moonshot.cn/v1 / .ai/v1). Uses the
    # unified `kimi-for-coding` model alias which the Coding Plan backend
    # routes to the appropriate K2 variant (Kimi-k2.6 today; 262K context,
    # 32K max output, supports vision/video/reasoning).
    #
    # Why anthropic-messages: Moonshot exposes the Coding Plan via two
    # URLs on the same domain — an Anthropic-format endpoint at
    # api.kimi.com/coding/ (used by Claude Code via ANTHROPIC_BASE_URL)
    # and an OpenAI-compatible endpoint at api.kimi.com/coding/v1 (used
    # by Roo Code etc.). We route through anthropic-messages so
    # cache_control fields round-trip byte-for-byte (the OpenAI shim is
    # lossy for cache_control semantics — see OpenRouter preset above
    # for the same reason). Verified against the live endpoint: response
    # payload includes cache_creation_input_tokens / cache_read_input_tokens,
    # so the cache layer is real on this backend.
    #
    # User-Agent gate: this endpoint enforces a UA-prefix whitelist
    # limited to first-party coding agents (Kimi CLI, Claude Code, Roo
    # Code, Kilo Code, ...). Requests carrying openclacky's default
    # Faraday UA are rejected with HTTP 403 access_terminated_error.
    # Client#anthropic_connection injects a Claude Code-shaped UA when
    # @provider_id == "kimi-coding" — see the comment in client.rb for
    # the policy rationale.
    #
    # Source: https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html
    "base_url" => "https://api.kimi.com/coding",
    "api" => "anthropic-messages",
    "default_model" => "kimi-for-coding",
    "models" => ["kimi-for-coding"],
    # K2.6 backend behind the alias is multimodal (image + video input,
    # reasoning). Same vision capability as the PAYG kimi preset.
    "capabilities" => { "vision" => true }.freeze,
    "website_url" => "https://www.kimi.com/code"
  }.freeze,

  "anthropic" => {
    "name" => "Anthropic (Claude)",
    "base_url" => "https://api.anthropic.com",
    "api" => "anthropic-messages",
    "default_model" => "claude-sonnet-4-6",
    "models" => ["claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"],
    "default_ocr_model" => "claude-haiku-4-5",
    "website_url" => "https://console.anthropic.com/settings/keys"
  }.freeze,

  "mimo" => {
    "name" => "MiMo (Xiaomi)",
    "base_url" => "https://api.xiaomimimo.com/v1",
    "api" => "openai-completions",
    "default_model" => "mimo-v2.5-pro",
    # The MiMo-V2 family (mimo-v2-pro / mimo-v2-omni) was retired on
    # 2026-06-30 and the model ids are no longer accepted by the API. The
    # current lineup is the V2.5 series:
    #   - mimo-v2.5-pro: text reasoning flagship, no vision
    #   - mimo-v2.5: native omni-modal (image/video/audio/text), vision-capable
    # Source: https://platform.xiaomimimo.com/docs/zh-CN/model
    "models" => ["mimo-v2.5-pro", "mimo-v2.5"],
    "capabilities" => { "vision" => false }.freeze,
    "model_capabilities" => {
      "mimo-v2.5" => { "vision" => true }.freeze
    }.freeze,
    "default_ocr_model" => "mimo-v2.5",
    # Xiaomi serves the same V2.5 lineup from two billing endpoints: the
    # pay-as-you-go API (api.xiaomimimo.com) and the Token Plan subscription
    # endpoint (token-plan-cn.xiaomimimo.com). Both accept identical model
    # ids and share one capability profile, so a single preset with
    # endpoint_variants recognises both. Without this, users on the Token
    # Plan endpoint fell through to "unknown provider" and the conservative
    # vision=true default applied to every model — sending images to the
    # text-only mimo-v2.5-pro, which rejects image input.
    "endpoint_variants" => [
      { "label" => "Pay-as-you-go", "label_key" => "settings.models.baseurl.variant.mimo_payg",        "base_url" => "https://api.xiaomimimo.com/v1",          "region" => "cn" }.freeze,
      { "label" => "Token Plan",    "label_key" => "settings.models.baseurl.variant.mimo_token_plan", "base_url" => "https://token-plan-cn.xiaomimimo.com/v1", "region" => "cn" }.freeze
    ].freeze,
    "website_url" => "https://platform.xiaomimimo.com/"
  }.freeze,

  "glm" => {
    "name" => "GLM (Z.ai / Zhipu)",
    "base_url" => "https://open.bigmodel.cn/api/paas/v4",
    "api" => "openai-completions",
    "default_model" => "glm-5.2",
    "models" => ["glm-5.2", "glm-5.1", "glm-5", "glm-5-turbo", "glm-5v-turbo", "glm-4.7"],
    # Zhipu / Z.ai expose four functionally-equivalent endpoints:
    # two regional sites (mainland open.bigmodel.cn + international api.z.ai)
    # each with a general-billing and a Coding-Plan subpath. They share the
    # same model lineup & identical capability profile, so a single preset
    # with endpoint_variants is the right shape — one source of truth for
    # vision/model_capabilities, four URLs recognised by find_by_base_url.
    # Without this, users pointing at api.z.ai or the /coding/ path fell
    # through to the conservative "assume vision=true" default and got
    # hallucinated image descriptions on text-only GLM models (C-5563).
    "endpoint_variants" => [
      { "label" => "Mainland · Pay-as-you-go",      "label_key" => "settings.models.baseurl.variant.mainland_cn_payg",    "base_url" => "https://open.bigmodel.cn/api/paas/v4",        "region" => "cn"   }.freeze,
      { "label" => "Mainland · Coding Plan",        "label_key" => "settings.models.baseurl.variant.mainland_cn_coding",  "base_url" => "https://open.bigmodel.cn/api/coding/paas/v4", "region" => "cn"   }.freeze,
      { "label" => "International · Pay-as-you-go", "label_key" => "settings.models.baseurl.variant.international_payg",  "base_url" => "https://api.z.ai/api/paas/v4",                "region" => "intl" }.freeze,
      { "label" => "International · Coding Plan",   "label_key" => "settings.models.baseurl.variant.international_coding","base_url" => "https://api.z.ai/api/coding/paas/v4",         "region" => "intl" }.freeze
    ].freeze,
    # GLM models are text-only except glm-5v-turbo which is vision-capable ("v" = visual).
    "capabilities" => { "vision" => false }.freeze,
    "model_capabilities" => {
      "glm-5v-turbo" => { "vision" => true }.freeze
    }.freeze,
    "default_ocr_model" => "glm-5v-turbo",
    "website_url" => "https://open.bigmodel.cn/usercenter/apikeys"
  }.freeze,

  # Volcengine Ark (Doubao) — ByteDance's model platform, OpenAI-compatible.
  # Exposes three functionally-equivalent endpoints (Pay-as-you-go / Coding
  # Plan / Agent Plan) that share the same model lineup and capability
  # profile, so a single preset with endpoint_variants is the right shape.
  # Without a preset match, base_urls like /api/coding/v3 fell through to the
  # conservative "assume vision=true" default and inlined images into
  # text-only models (e.g. glm-5.2), which Ark rejects. The vision matrix
  # below is the source of truth so text-only models route through the OCR
  # sidecar instead.
  "volcengine-ark" => {
    "name" => "Volcengine Ark (Doubao)",
    "name_key" => "provider.name.volcengine_ark",
    "base_url" => "https://ark.cn-beijing.volces.com/api/v3",
    "api" => "openai-completions",
    "default_model" => "doubao-seed-2.0-pro",
    "models" => [
      "doubao-seed-evolving",
      "doubao-seed-2.1-pro",
      "doubao-seed-2.1-turbo",
      "doubao-seed-2.0-code",
      "doubao-seed-2.0-pro",
      "doubao-seed-2.0-lite",
      "minimax-m3",
      "minimax-m2.7",
      "kimi-k2.7-code",
      "kimi-k2.6",
      "glm-5.2",
      "deepseek-v4-pro",
      "deepseek-v4-flash"
    ],
    "endpoint_variants" => [
      { "label" => "Pay-as-you-go", "label_key" => "settings.models.baseurl.variant.ark_payg",   "base_url" => "https://ark.cn-beijing.volces.com/api/v3", "alias_group" => "payg" }.freeze,
      { "label" => "Coding Plan",   "label_key" => "settings.models.baseurl.variant.ark_coding", "base_url" => "https://ark.cn-beijing.volces.com/api/coding/v3" }.freeze,
      { "label" => "Agent Plan",    "label_key" => "settings.models.baseurl.variant.ark_agent",  "base_url" => "https://ark.cn-beijing.volces.com/api/plan/v3" }.freeze
    ].freeze,
    # Pay-as-you-go billing endpoint requires versioned model ids, while the
    # Coding/Agent Plan endpoints accept the short display names. Users pick
    # the intuitive short name; on the payg endpoint we transparently swap
    # it for the versioned id the billing API expects. Only models whose ids
    # actually differ are listed here.
    "api_model_aliases" => {
      "payg" => {
        "glm-5.2"            => "glm-5-2-260617",
        "deepseek-v4-pro"    => "deepseek-v4-pro-260425",
        "deepseek-v4-flash"  => "deepseek-v4-flash-260425",
        "doubao-seed-2.1-pro"   => "doubao-seed-2-1-pro-260628",
        "doubao-seed-2.1-turbo" => "doubao-seed-2-1-turbo-260628",
        "doubao-seed-2.0-pro"   => "doubao-seed-2-0-pro-260215",
        "doubao-seed-2.0-lite"  => "doubao-seed-2-0-lite-260428",
        "doubao-seed-2.0-code"  => "doubao-seed-2-0-code-preview-260215"
      }.freeze
    }.freeze,
    # Most Doubao/multimodal models accept image input; GLM-5.2 and
    # DeepSeek-V4 on Ark are text-only.
    "capabilities" => { "vision" => true }.freeze,
    "model_capabilities" => {
      "glm-5.2"           => { "vision" => false }.freeze,
      "deepseek-v4-pro"   => { "vision" => false }.freeze,
      "deepseek-v4-flash" => { "vision" => false }.freeze
    }.freeze,
    "default_ocr_model" => "doubao-seed-2.0-lite",
    "website_url" => "https://console.volcengine.com/ark/region:cn-beijing/overview"
  }.freeze,

  "ollama" => {
    "name" => "Ollama (Cloud)",
    # Ollama Cloud API — OpenAI-compatible endpoint serving both local and
    # cloud models. Cloud models are available immediately without pulling.
    # Authentication: API key via Authorization: Bearer <key> header.
    # Create API keys at: https://ollama.com/settings/keys
    "base_url" => "https://ollama.com",
    "api" => "openai-completions",
    "default_model" => "deepseek-v4-flash",
    # Curated list of cloud-enabled models from the Ollama library.
    # Users can type any Ollama model name manually; this list seeds the picker.
    "models" => [
      "glm-5.2",
      "kimi-k3",
      "gemma4",
      "qwen3.5",
      "glm-5.1",
      "minimax-m2.7",
      "nemotron-3-super",
      "minimax-m3",
      "kimi-k2.7-code",
      "kimi-k2.6",
      "deepseek-v4-flash",
      "deepseek-v4-pro",
      "nemotron-3-ultra",
      "gemini-3-flash-preview",
      "nemotron-3-nano",
      "mistral-large-3",
      "gpt-oss"
    ],
    # Provider-level default: many Ollama cloud models are vision-capable.
    "capabilities" => { "vision" => true }.freeze,
    # Model-level overrides: text-only models that don't accept image input.
    "model_capabilities" => {
      "glm-5.2"             => { "vision" => false }.freeze,
      "glm-5.1"             => { "vision" => false }.freeze,
      "minimax-m2.7"        => { "vision" => false }.freeze,
      "deepseek-v4-pro"     => { "vision" => false }.freeze,
      "deepseek-v4-flash"   => { "vision" => false }.freeze,
      "nemotron-3-super"    => { "vision" => false }.freeze,
      "nemotron-3-ultra"    => { "vision" => false }.freeze,
      "nemotron-3-nano"     => { "vision" => false }.freeze,
      "gpt-oss"             => { "vision" => false }.freeze
    }.freeze,
    # Per-primary lite pairing: subagents use smaller models for cheap/fast work.
    "lite_models" => {
      "glm-5.2"                => "glm-5.1",
      "kimi-k3"                => "kimi-k2.6",
      "gemma4"                 => "nemotron-3-nano",
      "qwen3.5"                => "gemini-3-flash-preview",
      "minimax-m3"             => "minimax-m2.7",
      "kimi-k2.7-code"         => "kimi-k2.6",
      "deepseek-v4-pro"        => "deepseek-v4-flash",
      "mistral-large-3"        => "nemotron-3-nano",
      "gpt-oss"                => "nemotron-3-nano",
      "gemini-3-flash-preview"  => "nemotron-3-nano"
    },
    "default_ocr_model" => "kimi-k2.7-code",
    "website_url" => "https://ollama.com/settings/keys"
  }.freeze,

  "openai" => {
    "name" => "OpenAI (GPT)",
    "base_url" => "https://api.openai.com/v1",
    "api" => "openai-completions",
    "default_model" => "gpt-5.5",
    "models" => [
      "gpt-5.5",
      "gpt-5.4",
      "gpt-5.4-mini",
      "gpt-5.4-nano",
      "o4-mini",
      "o3"
    ],
    # GPT-5.x and o-series models are multimodal (text + image input).
    "capabilities" => { "vision" => true }.freeze,
    # Per-primary lite pairing: subagents use mini/nano for cheap/fast work.
    # o4-mini and o3 are reasoning models without a lite-tier sibling here.
    "lite_models" => {
      "gpt-5.5" => "gpt-5.4-mini",
      "gpt-5.4" => "gpt-5.4-mini"
    },
    # OpenAI's image generation model — same /v1/images/generations
    # endpoint, so the OpenAICompat image provider handles it.
    "image_models" => [
      "gpt-image-2"
    ],
    "default_image_model" => "gpt-image-2",
    "default_ocr_model" => "gpt-5.4-mini",
    "website_url" => "https://platform.openai.com/api-keys"
  }.freeze,

  "qwen" => {
    "name" => "Qwen (Alibaba)",
    "base_url" => "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api" => "openai-completions",
    "default_model" => "qwen3.7-max",
    "models" => [
      "qwen3.7-max",
      "qwen3.6-plus",
      "qwen3.6-max",
      "qwen3.6-27b",
      "qwen3.6-flash",
      "qwen-plus-latest",
    ],
    "endpoint_variants" => [
      { "label" => "Mainland China",  "label_key" => "settings.models.baseurl.variant.mainland_cn",   "base_url" => "https://dashscope.aliyuncs.com/compatible-mode/v1",     "region" => "cn"   }.freeze,
      { "label" => "Singapore",       "label_key" => "settings.models.baseurl.variant.international", "base_url" => "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", "region" => "intl" }.freeze,
      { "label" => "US (Virginia)",   "label_key" => "settings.models.baseurl.variant.us",            "base_url" => "https://dashscope-us.aliyuncs.com/compatible-mode/v1",   "region" => "us"   }.freeze
    ].freeze,
    "capabilities" => { "vision" => true }.freeze,
    "model_capabilities" => {
      "qwen3.7-max" => { "vision" => false }.freeze
    }.freeze,
    "default_ocr_model" => "qwen3.6-flash",
    "lite_models" => {
      "qwen3.7-max"      => "qwen3.6-flash",
      "qwen3.6-plus"     => "qwen3.6-flash",
      "qwen3.6-max"      => "qwen3.6-flash",
      "qwen3.6-27b"      => "qwen3.6-flash",
      "qwen-plus-latest" => "qwen3.6-flash"
    },
    "website_url" => "https://bailian.console.aliyun.com/?apiKey=1"
  }.freeze

}.freeze
MEDIA_KINDS = 
%w[image video audio stt video_understanding].freeze
MODEL_MAX_OUTPUT =

Per-model maximum output token limits.

The Agent global default (@max_tokens = 16_384) is tuned for the lowest common denominator. Strong reasoning models (GLM-5.2, Kimi-K3, MiMo-V2.5) support 64K–128K output but are artificially throttled to 16K, causing truncation on long reasoning chains and code generation.

Entries are matched top-to-bottom; the first match wins. Models not listed here fall back to the global default.

[
  { pattern: /glm/i,           limit: 65_536 }, # GLM-5.2: 128K output ceiling; 64K ample for reasoning+answer
  { pattern: /kimi-k3/i,       limit: 65_536 }, # Kimi K3: max_completion_tokens=131072 (max 1M); 64K ample
  { pattern: /mimo-v2\.5-pro/i, limit: 65_536 }, # MiMo-V2.5-Pro: max_completion_tokens=131072; 64K ample
  { pattern: /mimo/i,           limit: 32_768 }  # MiMo-V2.5: max_completion_tokens=32768; full default ceiling
].freeze

Class Method Summary collapse

Class Method Details

.alias_group_for_base_url(preset, base_url) ⇒ Object

Find which alias group the given base_url belongs to by matching it against the preset's endpoint_variants. Uses exact base_url equality (after normalising trailing slash) so "/api/v3" never leaks into the "/api/coding/v3" match.



1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
 
# File 'lib/clacky/providers.rb', line 1025

def alias_group_for_base_url(preset, base_url)
  return nil if base_url.nil?
  variants = preset["endpoint_variants"]
  return nil unless variants.is_a?(Array)

  normalized = base_url.to_s.chomp("/")
  variant = variants.find do |v|
    v.is_a?(Hash) && v["base_url"].to_s.chomp("/") == normalized
  end
  variant && variant["alias_group"]
end

.anthropic_format_for_model?(provider_id, model_name) ⇒ Boolean

Returns true when the provider+model should be talked to using the native Anthropic /v1/messages format. This is the single source of truth for deciding anthropic_format at Client construction time.

Parameters:

  • provider_id (String) —

    The provider identifier

  • model_name (String, nil) —

    The specific model name

Returns:

  • (Boolean) 


717
718
719
 
# File 'lib/clacky/providers.rb', line 717

def anthropic_format_for_model?(provider_id, model_name)
  api_type_for_model(provider_id, model_name) == "anthropic-messages"
end

.api_type(provider_id) ⇒ String?

Get the API type for a provider

Parameters:

  • provider_id (String) —

    The provider identifier

Returns:

  • (String, nil) —

    The API type or nil if provider not found



659
660
661
662
 
# File 'lib/clacky/providers.rb', line 659

def api_type(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("api")
end

.api_type_for_model(provider_id, model_name) ⇒ String?

Resolve the API type for a specific provider+model pair.

Resolution order:

1. PRESETS[provider_id]["model_api_overrides"] — first key (String or
 Regexp) that matches the model name wins.
2. PRESETS[provider_id]["api"] — the provider-wide default.
3. nil — unknown provider.

Use this instead of api_type when you need the precise transport for a given model (e.g. routing OpenRouter's Claude requests to the native /v1/messages endpoint to preserve prompt-cache fidelity).

Parameters:

  • provider_id (String) —

    The provider identifier

  • model_name (String, nil) —

    The specific model name

Returns:

  • (String, nil) —

    The API type (e.g. "anthropic-messages")



691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
 
# File 'lib/clacky/providers.rb', line 691

def api_type_for_model(provider_id, model_name)
  preset = PRESETS[provider_id]
  return nil unless preset

  overrides = preset["model_api_overrides"]
  if overrides.is_a?(Hash) && model_name
    name = model_name.to_s
    matched = overrides.find do |pattern, _api|
      case pattern
      when Regexp then pattern.match?(name)
      when String then pattern == name
      else false
      end
    end
    return matched[1] if matched
  end

  preset["api"]
end

.audio_model_aliases(provider_id) ⇒ Object 



761
762
763
764
 
# File 'lib/clacky/providers.rb', line 761

def audio_model_aliases(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("audio_model_aliases") || {}
end

.audio_models(provider_id) ⇒ Object

Audio generation models — same placeholder pattern as video_models.



806
807
808
809
 
# File 'lib/clacky/providers.rb', line 806

def audio_models(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("audio_models") || []
end

.base_url(provider_id) ⇒ String?

Get the base URL for a provider

Parameters:

  • provider_id (String) —

    The provider identifier

Returns:

  • (String, nil) —

    The base URL or nil if provider not found



651
652
653
654
 
# File 'lib/clacky/providers.rb', line 651

def base_url(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("base_url")
end

.capabilities(provider_id, model_name: nil) ⇒ Hash

Resolution order (most specific wins):

1. PRESETS[provider_id]["model_capabilities"][model_name] — per-model
 override, used when a single provider hosts a mix of capabilities
 (e.g. openclacky serves both Claude [vision] and DeepSeek [text]).
2. PRESETS[provider_id]["capabilities"] — provider-wide defaults,
 used when the whole lineup shares the same capabilities.
3. {} — no declaration; callers get the conservative default (true)
 via `supports?`.

Returns a plain Hash (always safe to inspect; never nil).

Parameters:

  • provider_id (String) —

    The provider identifier

  • model_name (String, nil) (defaults to: nil) —

    Optional specific model for override lookup

Returns:

  • (Hash) —

    capabilities mapping (e.g. { "vision" => true })



1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
 
# File 'lib/clacky/providers.rb', line 1050

def capabilities(provider_id, model_name: nil)
  preset = PRESETS[provider_id]
  return {} unless preset

  provider_caps = preset["capabilities"] || {}
  return provider_caps.dup unless model_name

  model_caps = preset.dig("model_capabilities", model_name) || {}
  provider_caps.merge(model_caps)
end

.default_media_model(provider_id, kind) ⇒ Object

Default media model for a kind under a provider. Falls back to the first declared model when no explicit default is set in the preset. Used by AgentConfig#derive_media_models! to pick which model to surface when the user is on "auto" mode.



855
856
857
858
859
860
861
 
# File 'lib/clacky/providers.rb', line 855

def default_media_model(provider_id, kind)
  preset = PRESETS[provider_id]
  return nil unless preset
  explicit = preset["default_#{kind}_model"]
  return explicit if explicit
  media_models(provider_id, kind).first
end

.default_model(provider_id) ⇒ String?

Get the default model for a provider

Parameters:

  • provider_id (String) —

    The provider identifier

Returns:

  • (String, nil) —

    The default model name or nil if provider not found



643
644
645
646
 
# File 'lib/clacky/providers.rb', line 643

def default_model(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("default_model")
end

.default_ocr_model(provider_id) ⇒ String?

Default OCR sidecar model for a provider. Falls back to the first vision-capable model if the preset doesn't pin an explicit default.

Parameters:

  • provider_id (String)

Returns:

  • (String, nil) —

    nil when the provider has zero vision-capable models



828
829
830
831
832
833
834
 
# File 'lib/clacky/providers.rb', line 828

def default_ocr_model(provider_id)
  preset = PRESETS[provider_id]
  return nil unless preset
  explicit = preset["default_ocr_model"]
  return explicit if explicit && ocr_models(provider_id).include?(explicit)
  ocr_models(provider_id).first
end

.exists?(provider_id) ⇒ Boolean

Check if a provider preset exists

Parameters:

  • provider_id (String) —

    The provider identifier (e.g., "anthropic", "openrouter")

Returns:

  • (Boolean) —

    True if the preset exists



629
630
631
 
# File 'lib/clacky/providers.rb', line 629

def exists?(provider_id)
  PRESETS.key?(provider_id)
end

.fallback_base_url(provider_id) ⇒ String?

Get the fallback base URL for a provider (used when primary endpoint is unreachable). Returns nil if the provider has no secondary gateway configured.

Parameters:

  • provider_id (String) —

    The provider identifier

Returns:

  • (String, nil) —

    The fallback base URL or nil



912
913
914
915
916
 
# File 'lib/clacky/providers.rb', line 912

def fallback_base_url(provider_id)
  preset = PRESETS[provider_id]
  url = preset&.dig("fallback_base_url")
  url&.empty? ? nil : url
end

.fallback_model(provider_id, model) ⇒ String?

Get the fallback model for a given model within a provider. Returns nil if no fallback is defined for that model.

Parameters:

  • provider_id (String) —

    The provider identifier

  • model (String) —

    The primary model name

Returns:

  • (String, nil) —

    The fallback model name or nil



903
904
905
906
 
# File 'lib/clacky/providers.rb', line 903

def fallback_model(provider_id, model)
  preset = PRESETS[provider_id]
  preset&.dig("fallback_models", model)
end

.find_by_base_url(base_url) ⇒ String?

Find provider ID by base URL. Matches if the given URL starts with the provider's base_url (after normalisation), so both exact matches and sub-path variants (e.g. "/v1") are recognised.

Also scans endpoint_variants (when present) so providers that operate multiple regional / billing-plan endpoints under the same identity (e.g. GLM on open.bigmodel.cn + api.z.ai, MiniMax on .com + .io) are all recognised as that single provider — one capability definition, N entry URLs. Without this, users configured with a non-default variant fall back to the "unknown provider" path and miss capability enforcement (see C-5563).

Parameters:

  • base_url (String) —

    The base URL to look up

Returns:

  • (String, nil) —

    The provider ID or nil if not found



931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
 
# File 'lib/clacky/providers.rb', line 931

def find_by_base_url(base_url)
  return nil if base_url.nil? || base_url.empty?
  normalized = base_url.to_s.chomp("/")
  PRESETS.find do |_id, preset|
    # Collect every URL this preset claims: the canonical base_url plus
    # any declared endpoint_variants. Dedup so the canonical one showing
    # up in both lists doesn't change behaviour.
    candidates = [preset["base_url"]]
    variants = preset["endpoint_variants"]
    if variants.is_a?(Array)
      variants.each { |v| candidates << v["base_url"] if v.is_a?(Hash) }
    end
    candidates.compact.uniq.any? do |candidate|
      preset_base = candidate.to_s.chomp("/")
      next false if preset_base.empty?
      normalized == preset_base || normalized.start_with?("#{preset_base}/")
    end
  end&.first
end

.get(provider_id) ⇒ Hash?

Get a provider preset by ID

Parameters:

  • provider_id (String) —

    The provider identifier

Returns:

  • (Hash, nil) —

    The preset configuration or nil if not found



636
637
638
 
# File 'lib/clacky/providers.rb', line 636

def get(provider_id)
  PRESETS[provider_id]
end

.image_model_aliases(provider_id) ⇒ Object 



751
752
753
754
 
# File 'lib/clacky/providers.rb', line 751

def image_model_aliases(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("image_model_aliases") || {}
end

.image_models(provider_id) ⇒ Array<String>

Get available image generation models for a provider. Returns an empty array when the provider doesn't declare any — callers should treat that as "image generation not supported by this provider".

Parameters:

  • provider_id (String) —

    The provider identifier

Returns:

  • (Array<String>) —

    List of image model names



746
747
748
749
 
# File 'lib/clacky/providers.rb', line 746

def image_models(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("image_models") || []
end

.list ⇒ Array<Array(String, String)>

List all available providers with their names

Returns:

  • (Array<Array(String, String)>) —

    Array of [id, name] pairs



729
730
731
 
# File 'lib/clacky/providers.rb', line 729

def list
  PRESETS.map { |id, config| [id, config["name"]] }
end

.lite_model(provider_id, primary_model = nil) ⇒ String?

Get the lite model for a provider.

Parameters:

  • provider_id (String) —

    The provider identifier

  • primary_model (String, nil) (defaults to: nil) —

    The currently-selected primary model name. When given, look it up in the provider's lite_models table first (so one provider can host multiple model families, each with its own lite sidekick — e.g. Claude Opus/Sonnet → Haiku, DeepSeek Pro → Flash). Falls back to the global lite_model field for old-style presets (e.g. deepseekv4) that declare a single provider-wide lite.

Returns:

  • (String, nil) —

    The lite model name, or nil when the primary is already lite-class (no entry) and no global lite_model is defined.



880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
 
# File 'lib/clacky/providers.rb', line 880

def lite_model(provider_id, primary_model = nil)
  preset = PRESETS[provider_id]
  return nil unless preset

  if primary_model && preset["lite_models"].is_a?(Hash)
    mapped = preset["lite_models"][primary_model]
    return mapped if mapped
    # When a `lite_models` table is defined but the current primary
    # isn't listed, it means the primary is already a lite-class model
    # (e.g. haiku / v4-flash) — do NOT fall back to the legacy single
    # field, because that would incorrectly inject a lite for a model
    # that doesn't need one.
    return nil if preset["lite_models"].any?
  end

  preset["lite_model"]
end

.max_output_for(model_name) ⇒ Integer?

Resolve the per-model maximum output token limit. Returns nil when no MODEL_MAX_OUTPUT entry matches — callers should then fall back to the global default (@max_tokens).

Parameters:

  • model_name (String) —

    The model name (e.g. "glm-5.2")

Returns:

  • (Integer, nil) —

    The max output limit, or nil if undeclared



670
671
672
673
674
 
# File 'lib/clacky/providers.rb', line 670

def max_output_for(model_name)
  return nil if model_name.nil? || model_name.to_s.empty?
  entry = MODEL_MAX_OUTPUT.find { |e| model_name.to_s.match?(e[:pattern]) }
  entry&.[](:limit)
end

.media_kinds ⇒ Object

The set of media kinds Clacky knows about. Drives UI rendering and derivation loops — adding a new modality means listing it here plus adding the corresponding generator class.



866
867
868
 
# File 'lib/clacky/providers.rb', line 866

def media_kinds
  MEDIA_KINDS
end

.media_model_aliases(provider_id, kind) ⇒ Object 



786
787
788
789
790
791
792
793
794
795
 
# File 'lib/clacky/providers.rb', line 786

def media_model_aliases(provider_id, kind)
  case kind.to_s
  when "image" then image_model_aliases(provider_id)
  when "video" then video_model_aliases(provider_id)
  when "audio" then audio_model_aliases(provider_id)
  when "stt"   then stt_model_aliases(provider_id)
  when "video_understanding" then video_understanding_model_aliases(provider_id)
  else {}
  end
end

.media_models(provider_id, kind) ⇒ Array<String>

Unified entry for media model lookup by kind.

Parameters:

  • provider_id (String)
  • kind (String) —

    one of "image" / "video" / "audio" / "stt"

Returns:

  • (Array<String>) 


840
841
842
843
844
845
846
847
848
849
 
# File 'lib/clacky/providers.rb', line 840

def media_models(provider_id, kind)
  case kind.to_s
  when "image" then image_models(provider_id)
  when "video" then video_models(provider_id)
  when "audio" then audio_models(provider_id)
  when "stt"   then stt_models(provider_id)
  when "video_understanding" then video_understanding_models(provider_id)
  else []
  end
end

.models(provider_id) ⇒ Array<String>

Get available models for a provider

Parameters:

  • provider_id (String) —

    The provider identifier

Returns:

  • (Array<String>) —

    List of model names (empty if dynamic)



736
737
738
739
 
# File 'lib/clacky/providers.rb', line 736

def models(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("models") || []
end

.ocr_models(provider_id) ⇒ Array<String>

OCR sidecar candidates: every chat model under this provider that's vision-capable. Derived from vision capability so we don't have to maintain a parallel list — a model that can see is by definition a candidate for "describe an image as text". Image-generation models are excluded (they take prompts and return pixels, not the other way).

Parameters:

  • provider_id (String)

Returns:

  • (Array<String>) 


818
819
820
821
822
 
# File 'lib/clacky/providers.rb', line 818

def ocr_models(provider_id)
  preset = PRESETS[provider_id]
  return [] unless preset
  (preset["models"] || []).select { |m| supports?(provider_id, :vision, model_name: m) }
end

.provider_ids ⇒ Array<String>

List all available provider IDs

Returns:

  • (Array<String>) —

    List of provider identifiers



723
724
725
 
# File 'lib/clacky/providers.rb', line 723

def provider_ids
  PRESETS.keys
end

.resolve_api_model(base_url:, api_key: nil, model:) ⇒ String?

Translate a display model name into the real model id the target endpoint expects. Some providers expose the same model under different ids per billing endpoint (e.g. Volcengine Ark's pay-as-you-go API needs versioned ids like "doubao-seed-2-0-pro-260215" while the Coding/Agent Plan endpoints accept the short "doubao-seed-2.0-pro"). Users always see and pick the short name; this swaps it just before the request goes out.

Returns the original model unchanged when no alias applies (unknown provider, endpoint without an alias group, or model not in the map).

Parameters:

  • base_url (String, nil) —

    the configured base_url (identifies endpoint)

  • api_key (String, nil) (defaults to: nil) —

    the configured api_key (provider fallback)

  • model (String, nil) —

    the display model name

Returns:

  • (String, nil) —

    the real model id to send, or the input unchanged



1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
 
# File 'lib/clacky/providers.rb', line 1005

def resolve_api_model(base_url:, api_key: nil, model:)
  return model if model.nil?

  provider_id = resolve_provider(base_url: base_url, api_key: api_key)
  return model unless provider_id

  preset = PRESETS[provider_id]
  aliases = preset && preset["api_model_aliases"]
  return model unless aliases.is_a?(Hash)

  group = alias_group_for_base_url(preset, base_url)
  return model unless group

  aliases.dig(group, model.to_s) || model
end

.resolve_provider(base_url: nil, api_key: nil) ⇒ String?

Resolve the provider id for a model entry, trying base_url first and then falling back to an api_key hint for the openclacky family.

Why the api_key fallback exists:

For local-debug / self-hosted proxy setups, users sometimes point
an "abs-claude-*" or "dsk-deepseek-*" model at http://localhost:XXXX
while still using a real `clacky-...` api key. Pure base_url matching
would report "unknown provider" and downstream logic (lite pairing,
fallback_models, capability detection) silently degrades. Recognising
the `clacky-` key prefix keeps those flows working without forcing
the user to edit base_url.

Not generalised to other providers: the sk-... prefix is used by OpenAI, DeepSeek, Moonshot, and many others, so it can't uniquely identify a provider. We only special-case clacky- because it's unique to us and the debug-proxy scenario is specifically ours.

Parameters:

  • base_url (String, nil) (defaults to: nil) —

    the configured base_url

  • api_key (String, nil) (defaults to: nil) —

    the configured api_key

Returns:

  • (String, nil) —

    provider id or nil if unresolvable



971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
 
# File 'lib/clacky/providers.rb', line 971

def resolve_provider(base_url: nil, api_key: nil)
  id = find_by_base_url(base_url)
  return id if id

  # Local-debug fallback: clacky-* api keys belong to the openclacky
  # family. Both "openclacky" and "clackyai-sea" share the same key
  # namespace and an identical model lineup/lite mapping, so picking
  # "openclacky" is equivalent for downstream lookups.
  if api_key.is_a?(String) && api_key.start_with?("clacky-")
    return "openclacky"
  end

  if base_url.is_a?(String) &&
     base_url.match?(%r{\Ahttps?://(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|/|\z)}i)
    return "openclacky"
  end

  nil
end

.stt_model_aliases(provider_id) ⇒ Object 



771
772
773
774
 
# File 'lib/clacky/providers.rb', line 771

def stt_model_aliases(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("stt_model_aliases") || {}
end

.stt_models(provider_id) ⇒ Object 



766
767
768
769
 
# File 'lib/clacky/providers.rb', line 766

def stt_models(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("stt_models") || []
end

.supports?(provider_id, capability, model_name: nil) ⇒ Boolean

Check if a provider+model supports a capability. Unknown provider / missing capability declaration → returns true (conservative default: assume supported unless we explicitly say otherwise). This keeps custom base_urls working and avoids over-aggressive downgrades.

Parameters:

  • provider_id (String) —

    The provider identifier

  • capability (String, Symbol) —

    The capability name (e.g. :vision, "vision")

  • model_name (String, nil) (defaults to: nil) —

    Optional specific model name

Returns:

  • (Boolean) —

    true unless the preset explicitly says false



1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
 
# File 'lib/clacky/providers.rb', line 1070

def supports?(provider_id, capability, model_name: nil)
  preset = PRESETS[provider_id]
  return true unless preset

  key = capability.to_s
  caps = capabilities(provider_id, model_name: model_name)
  # When the capability is not declared at either level, default to true.
  return true unless caps.key?(key)
  caps[key] != false
end

.video_model_aliases(provider_id) ⇒ Object 



756
757
758
759
 
# File 'lib/clacky/providers.rb', line 756

def video_model_aliases(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("video_model_aliases") || {}
end

.video_models(provider_id) ⇒ Object

Video generation models — placeholder. No provider supports video via Clacky yet; once they do, declare "video_models" alongside "image_models" in the relevant PRESETS entry and this returns it.



800
801
802
803
 
# File 'lib/clacky/providers.rb', line 800

def video_models(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("video_models") || []
end

.video_understanding_model_aliases(provider_id) ⇒ Object 



781
782
783
784
 
# File 'lib/clacky/providers.rb', line 781

def video_understanding_model_aliases(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("video_understanding_model_aliases") || {}
end

.video_understanding_models(provider_id) ⇒ Object 



776
777
778
779
 
# File 'lib/clacky/providers.rb', line 776

def video_understanding_models(provider_id)
  preset = PRESETS[provider_id]
  preset&.dig("video_understanding_models") || []
end