Configuration

Programmatic

const registry = new ModelRegistry({
  cacheDir: "~/.kosha",           // Cache directory (default: ~/.kosha)
  cacheTtlMs: 86400000,           // Cache TTL: 24 hours (default)
  providers: {
    anthropic: { enabled: true, apiKey: "sk-..." },
    ollama: { enabled: true, baseUrl: "http://localhost:11434" },
    openrouter: { enabled: false },
  },
  aliases: {
    "my-model": "claude-sonnet-5",
  },
});

Model Aliases

Built-in aliases for common models:

Alias	Resolves To	Notes
fable	claude-fable-5-1	Latest Anthropic Fable (most capable tier)
fable-5	claude-fable-5	Pinned Fable 5
mythos	claude-mythos-5-1	Project Glasswing counterpart of Fable 5.1
opus / opus-5.5	claude-opus-5-5	Latest Anthropic Opus
opus-5	claude-opus-5	Pinned Opus 5
opus-4 / opus-4.8	claude-opus-4-8	Pinned Opus 4.8
opus-4.7	claude-opus-4-7	Pinned Opus 4.7
sonnet / sonnet-5.5	claude-sonnet-5-5	Latest Anthropic Sonnet
sonnet-5	claude-sonnet-5	Pinned Sonnet 5
sonnet-4 / sonnet-4.6	claude-sonnet-4-6	Pinned Sonnet 4.6
haiku / haiku-4.5	claude-haiku-4-5	Latest Anthropic Haiku (bare ID, not date-suffixed)
kimi	kimi-k3	Latest Moonshot Kimi
gpt6 / gpt6-sol	gpt-6.1-sol	OpenAI GPT-6 mid tier (gpt6-astra, gpt6-luna also)
grok	grok-4.7	Latest xAI Grok (grok-4.6, grok-4.5, grok-4.3 pin)
gpt5	gpt-5	OpenAI GPT-5 (gpt5-mini, gpt5-nano, gpt5-pro also)
gpt4.1	gpt-4.1	OpenAI GPT-4.1
gpt4o	gpt-4o	OpenAI GPT-4o
o3	o3	OpenAI reasoning
gemini-pro	gemini-2.5-pro	Newest GA Gemini Pro (3.1 Pro is preview-only, so not aliased)
gemini-flash	gemini-3.8-flash	Newest GA Gemini Flash (gemini-flash-2.5 pins 2.5)
gemini-flash-lite	gemini-3.5-flash-lite	Newest GA Gemini Flash-Lite (gemini-flash-lite-2.5 pins 2.5)
qwen-max / qwen-plus	qwen3.8-max / qwen3.7-plus	Latest Alibaba Qwen tiers
nemotron-ultra	nvidia/llama-3.1-nemotron-ultra-253b-v1	NVIDIA Nemotron
mistral-large	mistral-large-latest	Mistral Large
groq-llama	llama-3.3-70b-versatile	Groq-hosted Llama
embed-small	text-embedding-3-small	OpenAI embedding
nomic	nomic-embed-text	Nomic embedding

Custom aliases:

import { ModelRegistry } from "kosha-discovery";
const registry = new ModelRegistry({ aliases: { "fast": "claude-haiku-4-5" } });

Provider vs Origin

Kosha distinguishes:

• provider: where you call the model (serving layer, e.g. openrouter)
• originProvider: who built the model (e.g. openai)

Example:

provider: openrouter
id: openai/gpt-5.3-codex
originProvider: openai

If a direct OpenAI route exists, route metadata marks it as preferred so assistants can call openai directly instead of openrouter.

Assistant Routing Flow

Kosha is designed to answer routing questions from assistants like Vaayu and Takumi:

1. Ask for capabilities: call GET /api/roles?role=embeddings.
2. Rank by cost: call GET /api/models/cheapest?role=embeddings.
3. If missingCredentials is non-empty, prompt the user for one of the listed env vars.
4. Route execution using the chosen provider/model pair.

Embeddings Quick Call

If your task is embeddings and you want the cheapest option:

kosha cheapest --role embeddings --price-metric input --limit 1

API equivalent:

curl "http://localhost:3000/api/models/cheapest?role=embeddings&priceMetric=input&limit=1"

Catalog Source

Without a key, kosha learns about models from two community catalogs it does not control, models.dev and LiteLLM. If one of them goes away or ships bad data, switch them off:

Mode	Keyless data comes from	Network
community (default)	models.dev, LiteLLM to fill gaps and enrich, kosha’s weekly snapshot if both are down	yes
pinned	kosha’s published weekly snapshot only	GitHub releases only
local	a catalog file you provide	none, for catalog data

Provider APIs called with your own key are official sources and run in every mode. In pinned and local the LiteLLM enricher is off; prices and limits missing from a provider’s API are filled from the active catalog instead.

KOSHA_CATALOG_SOURCE=pinned kosha list

kosha registry export --output ~/.kosha/catalog.json
KOSHA_CATALOG_SOURCE=local KOSHA_CATALOG_FILE=~/.kosha/catalog.json kosha list

Or in ~/.kosharc.json:

{ "catalogSource": "local", "catalogFile": "~/.kosha/catalog.json" }

• The env vars override config. An unknown mode is an error, not a fallback.
• local fails closed: a missing or invalid file stops discovery with an error. It never falls back to the network.
• kosha registry export writes the same envelope as the weekly snapshot (schemaVersion, kind: "kosha-catalog", fetchedAt, providers), so a downloaded snapshot works as a local catalog too.
• Each mode keeps its own disk cache, so switching never serves data cached under another mode.
• kosha doctor shows the mode, where it was set, and how old the catalog is.
• A project’s kosha.config.json may only set pinned; see credentials.

Pricing Enrichment

Model pricing is sourced from litellm’s model pricing database – a community-maintained dataset covering 300+ models. Kosha fetches this data and enriches discovered models with:

• Input/output token pricing
• Reasoning token pricing (when provided by upstream)
• Batch API pricing (async batch input/output discounts, when available)
• Context window sizes
• Cache read/write costs
• Capability flags (vision, function calling, etc.)
• Origin-provider reference pricing for proxied routes (e.g. OpenRouter vs direct provider)