Kosha Model Discovery

kosha-discovery

エージェントやコードに、どのモデルを使うべきか、そのコストはいくらかを知らせます。

kosha は 46 のプロバイダーとローカルランタイムからモデルを検出し、API キーがすでに保存されている場所（環境変数、Claude CLI、Codex、gcloud ADC、AWS SSO）を探し、料金とコンテキスト上限を補完して、ツール利用と 128k のコンテキストに対応し、実際に自分の API キーを持っているモデルのうち、最も安いものといった質問に答えます。TypeScript ライブラリ、CLI、HTTP API、利用額台帳を備えた OpenAI 互換プロキシ、MCP サーバーとして提供されます。

API キーがまったくなくても動作します。検出では models.dev と LiteLLM の公開カタログにフォールバックするため、新しいマシンでも kosha list を活用できます。

インストール

npm install @sriinnu/kosha-discovery       # library / server
npm install -g @sriinnu/kosha-discovery    # global `kosha` CLI

Node.js 22 以降が必要です。

クイックスタート

ライブラリ

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)

すべてのコマンドで --json を指定できます。その他のコマンドは kosha --help に記載されています。

検出を実行するたびに、安定版 v1 マニフェストが ~/.kosha/registry.json に保存されます。

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

GitHub Action

コードで指定しているモデルが非推奨になった場合、まもなく提供終了となる場合、またはどのプロバイダーにも掲載されなくなった場合に、ビルドを失敗させます。

- uses: sriinnu/kosha-discovery@v1
  with:
    models: |
      claude-opus-5-5
      gpt-6-sol
      sonnet

他のアクションと同様に、変動するタグではなくコミット SHA に固定してください。このアクションは latest ではなく、リリース時の kosha のバージョンを実行するため、新しい npm 公開によって CI の実行内容が変わることはなく、ピンを更新するまで同じ状態が保たれます。

公開カタログを対象に kosha doctor --ci --model … を実行します（プロバイダーの API キーは不要です）。ジョブのサマリーに表を出力し、失敗した各モデルに注釈を付けます。再販業者が経由先のひとつを提供終了にしても、そのモデルを提供するプロバイダーが引き続き提供している限り、ビルドは失敗せず、その旨だけが報告されます。deprecation-window（デフォルトは 30 日）は、提供終了がどれだけ先の場合に対象とするかを設定します。

公開スナップショット

毎週の検出実行で、キーなしで kosha が確認できるすべてのプロバイダー、モデル、料金、上限を含む完全なスナップショットを、固定 URL で公開します。

curl -sL https://github.com/sriinnu/kosha-discovery/releases/download/snapshot-latest/kosha-latest.json \
  | jq '.modelCount, .providerCount'

リポジトリ内のファイルではなく、リリースアセットとして提供されます。プロバイダーが追加されるたびに約 2.8 MB ずつ増えるため、毎週コミットすると、クローンして使うことを想定したリポジトリに、すでに古くなったデータが年間およそ 150 MB 追加されてしまいます。差分確認用に日付付きの snapshot-YYYY-MM-DD プレリリースを 2 つだけ残し、より新しいスナップショットが存在する場合に限り、古いものを削除します。

各スナップショットのリリースノートには、前回からの変更点（新しいモデル、料金改定、新たな非推奨、削除）が記載されます。同じ差分はローカルでも 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

パラメーターとレスポンスの形式：docs/api.md。

プロキシ

kosha serve は、/proxy/v1 で OpenAI 互換のエンドポイントも公開します。任意の OpenAI SDK の接続先にこのエンドポイントを指定すると、プロキシがモデルまたはエイリアスを解決し、認証情報を保有するプロバイダーを選び、上流のキーを挿入してリクエストを転送し、支出台帳に行を記録します。

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 のフィルター構文（カンマ区切りで、組み合わせ可能）：

フィルター	例	意味
機能	tool_use、vision	モデルがこのタグを持つ必要があります
<N>k	128k、200k	最小コンテキストウィンドウ
provider:<id>	provider:groq	特定のプロバイダーに固定します

kosha:fastest、kosha:reliable、kosha:balanced も同じフィルターを受け付け、価格ではなく、観測されたレイテンシとサーキットブレーカーの状態に基づいて順位付けします。

すべてのレスポンスには x-kosha-model、x-kosha-provider、x-kosha-requested、x-kosha-attempt-chain、x-kosha-estimated-cost-usd が含まれます。ストリーミング以外のレスポンスでは、上流から usage ブロックが返された場合に x-kosha-actual-cost-usd も追加されます。

プロキシが転送できる内容：

上流のワイヤ形式	プロバイダー	サポート
OpenAI 互換	OpenAI、Ollama、OpenRouter、Vercel、Groq、Together、Fireworks、DeepInfra、…	パススルー。ストリーミングも含みます
Anthropic Messages	Anthropic	変換対応：ストリーミング、ツール、image_url、response_format、reasoning_effort。音声入力と関数以外のツールは、同じモデルの OpenAI 互換ルートにフェイルオーバーします
Cloud SDK	Google、Bedrock、Vertex	検出のみ。現時点ではプロキシ経由での転送には未対応です
非チャット／その他のワイヤ形式	TypeSafe、Thinking Machines	検出のみ。TypeSafe の System One エンドポイントはチャット API ではなく、Tinker の Anthropic ワイヤ経路は Anthropic 独自のものと異なります

公開する前に重要なデフォルト設定を確認してください。サーバーは 127.0.0.1 にバインドします。ネットワークインターフェイスで待ち受けるには --host 0.0.0.0（または KOSHA_HOST）を渡し、KOSHA_PROXY_TOKEN を設定すると、/proxy/* と POST /api/refresh に Authorization: Bearer <token> または x-kosha-token が必要になります。KOSHA_MONTHLY_BUDGET_USD は、暦月ごとの支出に上限を設定します。リファレンス：docs/api.md、docs/operations.md。

MCP サーバー

kosha-mcp は Model Context Protocol を介して stdio 上でレジストリを提供するため、エージェントは HTTP サーバーなしで kosha_query_models、kosha_cheapest_model、kosha_ranked_routes、kosha_model_detail、kosha_model_routes、kosha_resolve_alias、kosha_provider_health、kosha_context_strategy を呼び出せます。

claude mcp add kosha -- kosha-mcp

これは io.github.sriinnu/kosha-discovery として MCP レジストリ に公開されているため、レジストリを読み取るクライアントは手動コマンドなしでインストールできます。マニフェストは server.json です。

プロバイダーキーはすべて任意です。認証情報がまったくなくても、サーバーは公開されている models.dev と LiteLLM のカタログに加えて、厳選されたオフラインリストから応答するため、新しいマシンでも役立ちます。

ツールとプロトコルの詳細：docs/mcp.md。

対応プロバイダー

46 のプロバイダーに対応しています。それぞれに src/provider-catalog.ts の記述子があります。OpenAI 互換のプロバイダーの多くは、手書きのクラスではなく、src/discovery/generic-openai.ts の GENERIC_OPENAI_PROVIDERS を使って動作します。

プロバイダー	検出方法	認証情報の取得元
Anthropic	GET /v1/models（コンテキスト、出力上限、機能を API から読み取ります）	ANTHROPIC_API_KEY、Claude CLI、Codex CLI
OpenAI	GET /v1/models	OPENAI_API_KEY、GitHub Copilot トークン
Google	GET /v1beta/models	GOOGLE_API_KEY、GEMINI_API_KEY、Gemini CLI、gcloud
AWS Bedrock	SDK → CLI → 公開カタログ → 静的リスト	AWS_ACCESS_KEY_ID、~/.aws/credentials、SSO、IAM
Vertex AI	API → gcloud → 公開カタログ → 静的リスト	GOOGLE_APPLICATION_CREDENTIALS、ADC
Ollama、llama.cpp、LM Studio、vLLM	ローカル HTTP API	なし
OpenRouter	API	OPENROUTER_API_KEY（任意。認証なしの場合はレート制限があります）
Vercel AI Gateway	GET /v1/models	AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN（検出には不要ですが、実行にはどちらかが必要です）
NVIDIA、Together、Fireworks、Groq、Cerebras、Cohere、DeepInfra、Perplexity	OpenAI 互換 API	<PROVIDER>_API_KEY
DeepSeek、Mistral、Moonshot（Kimi）、GLM（Zhipu）、Z.AI、MiniMax	OpenAI 互換 API	<PROVIDER>_API_KEY
xAI（Grok）	GET /v1/models。Grok Imagine は画像用と動画用に分かれています	XAI_API_KEY
TypeSafe（System One / Jev）	GET /v1/models — チャットモデルではなく、judgment モデルを返します	TYPESAFE_API_KEY、JEV_API_KEY
Thinking Machines（Inkling）	Anthropic 形式のエンドポイント。モデル一覧なし — 公開カタログのみ	TINKER_API_KEY
Alibaba Model Studio（Qwen）、Volcengine Ark（Doubao）、Inception（Mercury）、AI21（Jamba）、Upstage（Solar）、StepFun、Meta（Muse Spark）	OpenAI 互換 API	DASHSCOPE_API_KEY、ARK_API_KEY、INCEPTION_API_KEY、AI21_API_KEY、UPSTAGE_API_KEY、STEPFUN_API_KEY、META_MODEL_API_KEY
Baseten、Nebius Token Factory、Novita AI、SiliconFlow、Hugging Face、Ollama Cloud	OpenAI 互換 API	<PROVIDER>_API_KEY、HF_TOKEN

地域ごとの組み合わせ

複数のプロバイダーでは、海外向けと中国本土向けに別々のホストがあり、キーと料金表も別々です。たとえば Qwen 2.5 72B の入力料金は、海外向けが $1.40/M、中国向けが $0.574/M です。統合すると、最後に応答したホストによってモデルの料金が変わってしまうため、地域ごとに独立したプロバイダーとして扱います。

海外向け	中国向け	相違点
moonshot（api.moonshot.ai）	moonshot-cn（api.moonshot.cn）	ホスト、キー
minimax（api.minimax.io）	minimax-cn（api.minimaxi.com）	ホスト、キー
alibaba（dashscope-intl）	alibaba-cn（dashscope）	ホスト、キー、料金
siliconflow（.com）	siliconflow-cn（.cn）	ホスト、キー、料金
stepfun（api.stepfun.ai）	stepfun-cn（api.stepfun.com）	ホスト、キー、料金
zai（api.z.ai）	glm（open.bigmodel.cn）	ホスト、キー、料金

kosha routes <model> を実行すると、モデルが提供されているすべての地域が一覧表示され、料金を直接比較できます。

キーがない場合、プロバイダーはまず models.dev と LiteLLM の公開モデルカタログを使用します。これらにアクセスできない場合は kosha 独自の週次スナップショットを使用し、それも利用できない場合は厳選された静的リストを使用します。そのため、新しいマシンでも kosha list が機能します。同じフォールバックは、キーが設定されていても拒否された場合にも適用されます。その場合、プロバイダーは公開カタログから一覧に表示され、未認証として示されます。エラーは kosha doctor 用に保持されます。環境変数の正確な名前については、docs/credentials.md を参照してください。

チャット以外のモード

ほとんどのモデルはchatですが、modeはembedding、image、video、 audio、moderation、rerank、judgmentも対象とします。judgmentモデル（TypeSafeの System Oneファミリー）は、テキストを生成する代わりに、型付きの値（選択肢とその 確率分布、確率、または説明された段階に基づくスコア）で質問に回答します。 意図的にchat機能は持たせていません。そこにプロンプトをルーティングするのは カテゴリの誤りになるためです。

kosha cheapest --role judgment    # rank judgment models by price
kosha model jev                   # mode: judgment, $0.042/M in, $0 out

仕組み

1. 検出 — プロバイダーごとに1つの検出器が並行して実行され（Promise.allSettled）、正規化されたModelCardを返します。失敗したプロバイダーはdiscoveryErrors()に記録され、ほかのプロバイダーの処理を妨げません。
2. 情報の補完 — プロバイダーのAPIで公開されていない場合、価格、コンテキストウィンドウ、出力上限をmodels.devとLiteLLMから補完します。各カードのpricingSourceで情報源を示します。また、カタログで公開されている場合、カードにはreleaseDateとライフサイクルのstatusも含まれます。
3. 耐障害性 — プロバイダーごとのサーキットブレーカーと指数的なクールダウンに加え、古いキャッシュへのフォールバックを備えているため、プロバイダーの停止時にはエラーではなくキャッシュデータが使われます。
4. キャッシュとマニフェスト — 結果は~/.kosha/cache/にキャッシュされ（TTLは24時間）、ほかのツールが読み取れるよう、バージョン管理されたスナップショットとして~/.kosha/registry.jsonにエクスポートされます。
5. プロキシ — レジストリに対して、指定されたモデルまたはkosha:<strategy>[filters]セレクターを解決し、候補のルートをランク付けして、フェイルオーバー付きで転送します。推定コストと精算後のコストは~/.kosha/ledger-YYYY-MM.jsonlに記録されます。

詳細：docs/architecture.md、docs/resilience.md。

開発

pnpm install
pnpm run build        # compile to dist/
pnpm run typecheck    # tsc --noEmit
pnpm run lint         # biome lint
pnpm test             # vitest run
pnpm run check        # lint + build + test

pnpm aliases:check snapshot.json        # built-in aliases that are dead or a generation behind
pnpm snapshot:diff old.json new.json    # what changed between two snapshots

src/aliases.tsのエイリアステーブルは、カタログ内で手作業で記述される唯一の部分です。aliases:checkはこれをスナップショットと照合し、毎週のスナップショット実行時にその結果を付記します。そのため、opusのような短いエイリアスの更新漏れは、バグ報告ではなくここで確認できます。

プロジェクト構成

src/
  cli.ts                 # CLI entry point and arg parsing
  cli-commands.ts        # command implementations (+ cli-cmd-*.ts for the larger ones)
  registry.ts            # ModelRegistry public API
  registry-runtime.ts    # discovery orchestration, enrichment, cache, manifest export
  registry-query.ts      # model / role / capability queries
  registry-selection.ts  # cheapest candidates, binding hints
  registry-routing.ts    # cheapest / fastest / reliable / balanced ranking
  discovery/             # one discoverer per provider + static and public-seed catalogs
  enrichment/            # models.dev + LiteLLM pricing enrichment
  credentials/           # credential resolution (env, CLI files, ADC, OAuth)
  provider-catalog.ts    # provider descriptors: base URLs, transport, env var names
  aliases.ts             # built-in short names → canonical model IDs
  claude-generation.ts   # which Claude generation accepts which API parameters
  model-features.ts      # tool dialect / structured-output inference per model
  proxy.ts               # OpenAI-compatible proxy: routing, failover, ledger
  wire-anthropic.ts      # OpenAI ↔ Anthropic request / response / SSE translation
  cost.ts                # spend ledger, budget gates, usage reconciliation
  tally.ts               # zero-dependency token usage + USD tally (also exported as ./tally)
  server.ts              # Hono HTTP API + operator token gate
  mcp-server.ts          # MCP stdio server
  types.ts               # shared types

プロバイダーの追加

OpenAI互換のプロバイダー（大半が該当します）の場合、テーブルに2つのエントリーを追加するだけです。

1. src/provider-catalog.tsのPROVIDER_CATALOGにディスクリプター（ID、ベースURL、トランスポート、認証情報の環境変数）を追加します。
2. src/discovery/generic-openai.tsのGENERIC_OPENAI_PROVIDERSにスペックを追加します。スペックは独自の検出器を登録し、ディスクリプターのcredentialEnvVarsから認証情報を解決します。キーがない場合は公開カタログにフォールバックします。
3. src/discovery/modelsdev-seed.tsとlitellm-seed.tsで、プロバイダーをmodels.dev／LiteLLMのスラッグにマッピングし、キーなしでもモデルを検出できるようにします。スラッグを確認してください。GLMはzhipuaiとして公開されています。マッピングがないと、キーなしで利用できるモデルがなくなります。
4. test/discovery/generic-openai.test.tsにケースを追加し、docs/credentials.mdに環境変数を記載します。

分類に本当にコードが必要な場合に限り、検出器クラスを作成します。たとえば、ルートごとの価格設定（OpenRouter）、OpenAIとは異なるレスポンス形式（TypeSafe）、オリジンの再マッピング（Vercel）などです。

1. BaseDiscovererまたはOpenAICompatibleDiscovererを拡張したsrc/discovery/<provider>.tsを作成します。fetchJSONとmakeCardは用意されています。
2. src/discovery/index.tsからエクスポートし、DISCOVERER_REGISTRYにファクトリーのエントリーを追加します。
3. 独自の検索順（CLIファイル、OAuth、ADC、SSO）が必要な場合に限り、src/credentials/resolver.tsにリゾルバーの分岐を追加します。環境変数に設定する通常のAPIキーには分岐は不要です。ディスクリプターで対応できます。
4. test/discovery/<provider>.test.tsを追加します（fetchをモックしてください。typesafe.test.tsを参照）。

ドキュメント

認証情報	各プロバイダーの環境変数、CLI ツール、設定ファイル
CLI	コマンド、フラグ、例
HTTP API	エンドポイント、パラメーター、レスポンススキーマ
MCP サーバー	ツール、プロトコルネゴシエーション、クライアントのセットアップ
設定	エイリアス、ルーティング、エンリッチメント、プログラムによる設定
アーキテクチャ	検出フロー、モジュールマップ、プロバイダーの追加
レジリエンス	サーキットブレーカー、古いキャッシュ、ヘルス
運用	デプロイのサイジング、メトリクス、支出台帳、復旧レシピ
セキュリティ	脅威カタログ、ランタイムスキャン、プリコミットフック
Discovery Plane v1	安定したデーモンコントラクト（差分、SSE ウォッチ、バインディングヒント）

同じページはウィキにもミラーされており、トラブルシューティングやリリース手順書など、ウィキにのみ掲載されているガイドもあります。docs/がソースです。ミラーはmainへのプッシュごとに再生成されるため、ウィキではなくこちらを編集してください。

リリース

1. package.jsonとserver.jsonの両方でversionを更新し、CHANGELOG.mdの[Unreleased]セクションに日付を記入して、PRとしてマージします。
2. タグを付けてプッシュします。

git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
gh workflow run release-npm.yml -f tag=vX.Y.Z

ワークフローでは、タグがpackage.jsonと一致することを確認し、lint／ビルド／テストを実行して、provenance 付きで npm に公開し、GitHub Release を作成します。公開時の認証には、このリポジトリとワークフローが npmjs.com で信頼できる発行元として設定されている場合は npm trusted publishing（OIDC）を使用し、そうでない場合はリポジトリシークレットのNPM_TOKENを使用します。

サポート

kosha は無料のオープンソースです。より安価なモデルを選ぶのに役立つ場合は、維持へのスポンサーをご検討ください。

• GitHub Sponsors
• Buy Me a Coffee

ライセンス

MIT