Kosha Model Discovery

kosha-discovery

Tells your agent — or your code — which model to use and what it costs.

Website: kosha.srinivas.dev

kosha discovers models across 46 providers and local runtimes, finds your API keys wherever they already live (env vars, Claude CLI, Codex, gcloud ADC, AWS SSO), fills in pricing and context limits, and answers questions like *the cheapest model with tool use and 128k context that I actually hold a key for*. It ships as a TypeScript library, a CLI, an HTTP API, an OpenAI-compatible proxy with a spend ledger, and an MCP server.

It works with no API keys at all — discovery falls back to the public models.dev and LiteLLM catalogs, so kosha list is useful on a fresh machine.

Install

npm install @sriinnu/kosha-discovery       # library / server

npm install -g @sriinnu/kosha-discovery # global kosha CLI brew install sriinnu/tap/kosha # same CLI and MCP server, via Homebrew

Requires Node.js 22+.

Quick start

Library

import { createKosha } from "@sriinnu/kosha-discovery";

const kosha = await createKosha();

const models = kosha.models(); // ModelCard[] across every provider const cheapest = kosha.cheapestModels({ role: "image" }); // ranked by price, with missingCredentials const sonnet = kosha.model("sonnet"); // alias → canonical ID; undefined if unknown console.log(sonnet?.pricing); // { inputPerMillion: 2, outputPerMillion: 10, cacheReadPerMillion: 0.2, ... }

CLI

kosha discover                       # query every provider; writes ~/.kosha/cache and the manifest

kosha list --provider anthropic # read from the local cache kosha model sonnet # one model, alias-aware kosha routes claude-opus-5-5 # every serving route for a model (direct, OpenRouter, Bedrock, …) kosha cheapest --role embeddings # rank by price for a role kosha doctor --ci --model opus,gpt6 # fail CI if a model you pin is deprecated, retiring, or gone kosha spend --since 2026-09-01 # roll up the proxy's spend ledger kosha refresh # bypass the cache and re-discover kosha serve --port 3000 # HTTP API + proxy; binds 127.0.0.1 (see Proxy below)

Every command takes --json. kosha --help lists the rest.

After each discovery, a stable v1 manifest lands at ~/.kosha/registry.json:

jq '.models[] | select(.pricing.inputPerMillion < 0.1) | .modelId' ~/.kosha/registry.json

GitHub Action

Fail a build when a model your code pins is deprecated, about to be retired, or listed by no provider any more:

- uses: sriinnu/kosha-discovery@v1

with: models: | claude-opus-5-5 gpt-6-sol sonnet

Pin it to a commit SHA rather than a moving tag, as you would any action. The action runs the kosha version it was released with, not latest, so a new npm publish does not change what your CI runs until you move the pin.

It runs kosha doctor --ci --model … against the public catalogs (no provider keys needed), writes a table to the job summary, and annotates each failing model. A reseller retiring one of its routes is reported but does not fail the build while the model's own provider still serves it; deprecation-window (default 30 days) sets how far ahead a sunset counts.

Public snapshot

A weekly discovery run publishes a full snapshot — every provider, model, price and limit kosha can see without your keys — at a stable URL:

curl -sL https://github.com/sriinnu/kosha-discovery/releases/download/snapshot-latest/kosha-latest.json \

| jq '.modelCount, .providerCount'

It is a release asset rather than a file in the repository: at ~2.8 MB growing with every provider added, committing it weekly would put roughly 150 MB of already-stale data a year into a repo people are meant to clone. Dated snapshot-YYYY-MM-DD pre-releases keep a short trail for diffing, pruned to the two most recent, and an older one is only removed once a newer one exists.

Each snapshot's release notes list what changed since the previous one — new models, repricings, new deprecations, removals. The same diff runs locally with pnpm snapshot:diff old.json new.json.

HTTP API

GET  /api/models?provider=&originProvider=&mode=&capability=

GET /api/models/:idOrAlias GET /api/models/:idOrAlias/routes GET /api/models/cheapest?role=… GET /api/capabilities GET /api/providers[/:id] GET /api/roles GET /api/resolve/:alias GET /api/discovery-errors GET /api/discovery[/delta|/watch|/cheapest|/binding] (stable v1 contract) POST /api/refresh GET /health GET /metrics GET /proxy/v1/models POST /proxy/v1/chat/completions

Parameters and response shapes: docs/api.md.

Proxy

kosha serve also exposes an OpenAI-compatible endpoint at /proxy/v1. Point any OpenAI SDK at it; the proxy resolves the model or alias, picks a provider you hold credentials for, injects the upstream key, forwards the request, and writes a row to the spend ledger.

kosha serve   # start on :3000

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "http://localhost:3000/proxy/v1", apiKey: "not-used", // kosha resolves credentials from env });

// Use any canonical model ID or alias const res = await client.chat.completions.create({ model: "sonnet", messages: [{ role: "user", content: "hello" }], });

// Let kosha pick the cheapest model you have a key for const cheap = await client.chat.completions.create({ model: "kosha:cheapest", messages: [{ role: "user", content: "hello" }], });

// Cheapest model with tool_use and at least 128k context const routed = await client.chat.completions.create({ model: "kosha:cheapest[tool_use,128k]", messages: [{ role: "user", content: "hello" }], });

`kosha:cheapest` filter syntax (comma-separated, combinable):

kosha:fastest, kosha:reliable, and kosha:balanced take the same filters and rank on observed latency and circuit-breaker state instead of price.

Every response carries x-kosha-model, x-kosha-provider, x-kosha-requested, x-kosha-attempt-chain, and x-kosha-estimated-cost-usd; non-streaming responses add x-kosha-actual-cost-usd when the upstream returned a usage block.

What the proxy can forward:

Defaults that matter before you expose it: the server binds 127.0.0.1. Pass --host 0.0.0.0 (or KOSHA_HOST) to listen on a network interface, and set KOSHA_PROXY_TOKEN so /proxy/* and POST /api/refresh require Authorization: Bearer or x-kosha-token. KOSHA_MONTHLY_BUDGET_USD caps spend per calendar month. Reference: docs/api.md, docs/operations.md.

MCP server

kosha-mcp serves the registry over the Model Context Protocol on stdio, so an agent can call kosha_query_models, kosha_cheapest_model, kosha_ranked_routes, kosha_model_detail, kosha_model_routes, kosha_resolve_alias, kosha_provider_health, and kosha_context_strategy without an HTTP server.

claude mcp add kosha -- kosha-mcp

It is published to the MCP registry as io.github.sriinnu/kosha-discovery, so clients that read the registry can install it without a manual command. The manifest is server.json.

Every provider key is optional. With no credentials at all the server still answers from the public models.dev and LiteLLM catalogs plus a curated offline list, so it is useful on a fresh machine.

Tools and protocol details: docs/mcp.md.

Supported providers

46 providers. Each has a descriptor in src/provider-catalog.ts; most OpenAI-compatible ones are driven from GENERIC_OPENAI_PROVIDERS in src/discovery/generic-openai.ts rather than a hand-written class.

Regional pairs

Several providers run separate hosts for international and mainland-China traffic, with separate keys and separate price sheets — Qwen 2.5 72B is $1.40/M input internationally against $0.574/M in China. Merging them would make a model's price depend on which host answered last, so each region is its own provider:

| stepfun (api.stepfun.ai) | stepfun-cn (api.stepfun.com) | host, key, prici