モデルが予告なく使えなくなる日に備える — 引退・撤回・過負荷を一つのステートマシンで扱うルーター設計

// availability-machine.ts
const OVERLOAD_COOLDOWN_MS = 10 * 60 * 1000; // 10分
 
interface Health {
  state: Availability;
  overloadedAt?: number;
  consecutive429: number;
}
 
const health = new Map<string, Health>(); // key: モデルID
 
export function noteResult(
  id: string,
  outcome: "ok" | "overloaded" | "retired" | "withdrawn",
) {
  const h = health.get(id) ?? { state: "available", consecutive429: 0 };
  if (outcome === "ok") {
    h.state = "available";
    h.consecutive429 = 0;
    h.overloadedAt = undefined;
  } else if (outcome === "overloaded") {
    h.consecutive429 += 1;
    if (h.consecutive429 >= 3) {
      h.state = "overloaded";
      h.overloadedAt = Date.now();
    }
  } else if (outcome === "retired") {
    h.state = "retired"; // 自動復帰しない
  } else if (outcome === "withdrawn") {
    h.state = "withdrawn"; // 運用者操作でのみ復帰
  }
  health.set(id, h);
}
 
export function effectiveState(id: string): Availability {
  const h = health.get(id);
  if (!h) return "available";
  // 過負荷だけは時間で自然回復させる
  if (h.state === "overloaded" && h.overloadedAt &&
      Date.now() - h.overloadedAt > OVERLOAD_COOLDOWN_MS) {
    return "available"; // クールダウン明け。次の成功で確定する
  }
  return h.state;
}

// router.ts
import Anthropic from "@anthropic-ai/sdk";
import { REGISTRY, Role } from "./model-registry";
import { noteResult, effectiveState } from "./availability-machine";
 
const client = new Anthropic(); // ANTHROPIC_API_KEY は環境変数から
 
function pickModel(role: Role): string {
  const candidates = REGISTRY[role]
    .filter((m) => effectiveState(m.id) === "available");
  if (candidates.length === 0) {
    throw new Error(`role ${role} に利用可能なモデルがありません`);
  }
  return candidates[0].id;
}
 
function classifyError(err: unknown): "overloaded" | "retired" | "withdrawn" | "other" {
  const e = err as { status?: number; error?: { type?: string } };
  if (e.status === 429 || e.status === 529) return "overloaded";
  // 恒久的なモデル未検出は引退とみなす
  if (e.error?.type === "not_found_error") return "retired";
  // 直前まで成功していたモデルが権限・検証で弾かれ始めたら撤回の疑い
  if (e.status === 403 || e.error?.type === "permission_error") return "withdrawn";
  return "other";
}
 
export async function route(role: Role, params: Omit<Anthropic.MessageCreateParams, "model">) {
  let lastErr: unknown;
  // 同ロール内の候補数だけ試す
  for (let attempt = 0; attempt < REGISTRY[role].length; attempt++) {
    const model = pickModel(role);
    try {
      const res = await client.messages.create({ ...params, model });
      noteResult(model, "ok");
      return { res, model };
    } catch (err) {
      lastErr = err;
      const kind = classifyError(err);
      if (kind === "other") throw err; // 想定外はそのまま投げる
      noteResult(model, kind);
      // overloaded はクールダウン後に同モデルが復帰しうるが、
      // この呼び出しでは次候補へ即フォールバックして応答を返す
    }
  }
  throw lastErr;
}

# preflight.py — 1 ロール 1 回の軽量 probe
import os
import anthropic
 
client = anthropic.Anthropic()  # ANTHROPIC_API_KEY は環境変数
 
PROBE_BY_ROLE = {
    "deep": "claude-opus-4-8",
    "balanced": "claude-sonnet-4-6",
    "fast": "claude-haiku-4-5",
}
 
def probe(model_id: str) -> str:
    try:
        client.messages.create(
            model=model_id,
            max_tokens=1,
            messages=[{"role": "user", "content": "ok"}],
        )
        return "available"
    except anthropic.APIStatusError as e:
        if e.status_code in (429, 529):
            return "overloaded"   # 一時的。バッチは通常どおり進めてよい
        if e.status_code == 404:
            return "retired"      # 後継へ切り替えが必要
        if e.status_code == 403:
            return "withdrawn"    # 縮退判断が必要
        raise
 
if __name__ == "__main__":
    blocking = []
    for role, model_id in PROBE_BY_ROLE.items():
        state = probe(model_id)
        print(f"{role:9s} {model_id:20s} -> {state}")
        if state in ("retired", "withdrawn"):
            blocking.append((role, model_id, state))
    # retired / withdrawn が見つかったロールはバッチ前に人へ通知
    if blocking:
        for role, model_id, state in blocking:
            print(f"::alert:: role={role} model={model_id} state={state}")

// cost.ts
import { REGISTRY } from "./model-registry";
 
export function recordCost(
  usedModelId: string,
  inputTokens: number,
  outputTokens: number,
): number {
  const entry = Object.values(REGISTRY).flat().find((m) => m.id === usedModelId);
  if (!entry) throw new Error(`未知のモデル: ${usedModelId}`);
  const usd =
    (inputTokens / 1_000_000) * entry.inputPer1M +
    (outputTokens / 1_000_000) * entry.outputPer1M;
  // 第一候補ではなく「実際に使われたモデル」の単価で計上する
  return usd;
}