@tokenbuddy/tokenbuddy 1.0.36 → 1.0.38

package/src/seller-route-planner.ts

@@ -1,513 +0,0 @@
-import { isBuyerVisibleRegistrySeller, type RegistrySeller } from "./seller-catalog.js";
-import {
-  planSellerRoutes,
-  type RoutingCandidate,
-  type SellerRoutingPlan,
-  type SellerRoutingStrategyConfig
-} from "./seller-routing-strategy.js";
-
-/**
- * `planSellerRouteSet` 候选来源：走了 prewarm cache 还是回退到 registry 顺序。
- */
-export type SellerRouteSource = "prewarm_cache" | "registry_fallback";
-/** 路由层使用的熔断状态枚举，与 `seller-pool.CircuitState` 语义一致。 */
-export type SellerCircuitState = "closed" | "half_open" | "open";
-
-/**
- * 路由规划器在合并多个数据源时使用的"实时指标"维度。
- * 由 `SellerPool` 快照聚合；可空字段表示该维度暂未采集。
- */
-export interface SellerRouteMetric {
-  /** seller ID */
-  sellerId: string;
-  /** 综合健康分 0-100，可选 */
-  healthScore?: number;
-  /** 平均延迟（毫秒），可选 */
-  avgLatencyMs?: number;
-  /** TTFT（毫秒），可选 */
-  ttftMs?: number;
-  /** 平均推理延迟（毫秒），可选 */
-  avgInferenceMs?: number;
-  /** 最近 10 分钟窗口内的平均输出吞吐（tokens/s），可选 */
-  avgTokensPerSecond?: number;
-  /** 折扣系数（0-1），可选；缺省时 scoring 视为"无折扣信息" */
-  discountRatio?: number;
-  /** 当前熔断状态，可选；`open` 的 seller 直接被剔除候选 */
-  circuit?: SellerCircuitState;
-  /** 临时容量避让截止时间；大于当前时间时直接剔除候选 */
-  capacityBlockedUntil?: number;
-  /** 当前 `tb-proxyd` 进程内该 seller 的活跃 lease 数。 */
-  localConcurrencyActive?: number;
-  /** 当前 `tb-proxyd` 进程内该 seller 的最大活跃 lease 数。 */
-  localConcurrencyLimit?: number;
-}
-
-/**
- * 路由规划器视角的 prewarm 候选：比 `PrewarmCandidate` 少调度内部状态，只保留打分需要的字段。
- */
-export interface SellerRoutePrewarmCandidate {
-  /** seller ID */
-  sellerId: string;
-  /** seller URL（去尾部斜杠） */
-  url: string;
-  /** 综合健康分，可选 */
-  healthScore?: number;
-  /** 平均延迟（毫秒），可选 */
-  avgLatencyMs?: number;
-  /** TTFT（毫秒），可选 */
-  ttftMs?: number;
-  /** 平均推理延迟（毫秒），可选 */
-  avgInferenceMs?: number;
-  /** 最近 10 分钟窗口内的平均输出吞吐（tokens/s），可选 */
-  avgTokensPerSecond?: number;
-}
-
-/**
- * 路由规划器视角的 seller 元数据：折扣系数和 manifest 刷新时间。
- * 用于在 `discount` 排序时把"无折扣"和"折扣已知"区分开。
- */
-export interface SellerRouteMetadata {
-  sellerId: string;
-  discountRatio?: number;
-  manifestVersion?: string;
-  lastRefreshAt?: number;
-  source: "manifest_selection";
-  errorMessage?: string;
-}
-
-/**
- * `planSellerRouteSet()` 的入参：把"模型 + 协议 + 支付" + 三类数据源（registry / prewarm / 指标）+ 路由策略打包传入。
- */
-export interface SellerRoutePlannerInput {
-  /** 目标模型 ID */
-  modelId: string;
-  /** 协议偏好（`chat_completions` / `responses` / `messages`） */
-  protocol: string;
-  /** 支付方式（`mock` / `clawtip`） */
-  paymentMethod: string;
-  /** seller 注册表快照 */
-  registrySellers: RegistrySeller[];
-  /** buyer 路由策略配置（fixed / fixedSet / fullAuto + 评分器） */
-  routing: SellerRoutingStrategyConfig;
-  /** 来自 prewarm cache 的候选（可选；提供时优先使用） */
-  prewarmCandidates?: SellerRoutePrewarmCandidate[];
-  /** seller 实时指标（可选；`circuit=open` 的 seller 被剔除） */
-  sellerMetrics?: SellerRouteMetric[];
-  /** 当前时间戳，用于判断容量避让窗口；默认 `Date.now()` */
-  now?: number;
-}
-
-/**
- * 单条规划后的路由：含 seller 描述、URL、聚合后的指标。
- */
-export interface PlannedSellerRoute {
-  /** seller 注册表描述（用于后续转发） */
-  seller: RegistrySeller;
-  /** seller URL（去尾部斜杠） */
-  url: string;
-  /** 聚合指标：健康分、平均延迟、折扣、registry 声明顺序 */
-  metrics: {
-    healthScore?: number;
-    avgLatencyMs?: number;
-    ttftMs?: number;
-    avgInferenceMs?: number;
-    avgTokensPerSecond?: number;
-    discountRatio?: number;
-    /** 在 registry 里的声明顺序（0-based，tie-breaker） */
-    registryOrder: number;
-  };
-}
-
-/**
- * `planSellerRouteSet()` 的返回结果：路由列表 + 来源 + 决策原因 + 模式 / 评分器。
- */
-export interface SellerRoutePlan {
-  /** 已排好序的可选 seller 列表（按路由策略打分） */
-  routes: PlannedSellerRoute[];
-  /** 候选来源：`prewarm_cache` 或 `registry_fallback` */
-  source: SellerRouteSource;
-  /** 候选来源的细化原因（用于诊断 / 稳定事件断言） */
-  sourceReason: string;
-  /** 路由策略输出的整体决策原因 */
-  reason: string;
-  /** 路由模式（`fixed` / `fixedSet` / `fullAuto`） */
-  mode: SellerRoutingPlan["mode"];
-  /** 使用的评分器（`speed` / `discount` / `balanced`） */
-  scorer: SellerRoutingPlan["scorer"];
-  /** 候选总数（prewarm 阶段剔除了不支持模型 / 协议 / 支付的 seller 之前） */
-  candidateCount: number;
-  /** 候选构造与排除摘要，用于日志解释本轮决策为什么只剩这些 seller。 */
-  diagnostics: SellerRouteDiagnostics;
-}
-
-export interface SellerRouteDiagnostics {
-  registryVisibleCount: number;
-  prewarmCandidateCount: number;
-  prewarmUsableCount: number;
-  prewarmMissingSellerIds: string[];
-  prewarmBlockedSellerIds: string[];
-  prewarmIncompatibleSellerIds: string[];
-  sourceCandidateCount: number;
-  blockedOpenCircuitCount: number;
-  blockedCapacityCount: number;
-  blockedLocalConcurrencyCount: number;
-  blockedSellerIds: string[];
-  incompatibleCount: number;
-  incompatibleSellerIds: string[];
-}
-
-interface CandidateSourceResult {
-  source: SellerRouteSource;
-  sourceReason: string;
-  candidates: RoutingCandidate[];
-  incompatibleSellerIds: string[];
-  prewarmDiagnostics: PrewarmSourceDiagnostics;
-}
-
-interface PrewarmSourceDiagnostics {
-  usableCount: number;
-  missingSellerIds: string[];
-  blockedSellerIds: string[];
-  incompatibleSellerIds: string[];
-}
-
-interface IndexedSeller {
-  seller: RegistrySeller;
-  registryOrder: number;
-}
-
-interface MetricIndex {
-  bySellerId: Map<string, SellerRouteMetric>;
-  blockedSellerIds: Set<string>;
-  blockedOpenCircuitSellerIds: Set<string>;
-  blockedCapacitySellerIds: Set<string>;
-  blockedLocalConcurrencySellerIds: Set<string>;
-}
-
-/**
- * 给定 (model, protocol, payment) + 三类数据源，规划出有序的 seller 路由列表。
- * 决策流程：
- * 1. 索引 registry sellers（按声明顺序）。
- * 2. 索引 `sellerMetrics`，把 `circuit=open` 的 seller 标记为剔除。
- * 3. 优先从 `prewarmCandidates` 构造候选；都不可用时回退 registry 顺序。
- * 4. 调 `planSellerRoutes`（`seller-routing-strategy`）做策略评分。
- * 5. 把 `RoutingCandidate` 转回 `PlannedSellerRoute`，加上 `registryOrder`。
- *
- * @param input 规划入参
- * @returns 规划后的路由计划
- */
-export function planSellerRouteSet(input: SellerRoutePlannerInput): SellerRoutePlan {
-  const indexed = indexRegistrySellers(input.registrySellers);
-  const metrics = indexMetrics(input.sellerMetrics, input.now ?? Date.now());
-  const source = chooseCandidateSource(input, indexed, metrics);
-  const strategyPlan = planSellerRoutes(source.candidates, input.routing);
-  const routes = strategyPlan.routes.map((candidate) => {
-    const seller = indexed.bySellerId.get(candidate.sellerId)?.seller;
-    if (!seller) {
-      throw new Error(`planned seller ${candidate.sellerId} is missing from registry index`);
-    }
-    return {
-      seller,
-      url: candidate.url,
-      metrics: {
-        healthScore: candidate.healthScore,
-        avgLatencyMs: candidate.avgLatencyMs,
-        ttftMs: candidate.ttftMs,
-        avgInferenceMs: candidate.avgInferenceMs,
-        avgTokensPerSecond: candidate.avgTokensPerSecond,
-        discountRatio: candidate.discountRatio,
-        registryOrder: candidate.registryOrder
-      }
-    };
-  });
-
-  return {
-    routes,
-    source: source.source,
-    sourceReason: source.sourceReason,
-    reason: strategyPlan.reason,
-    mode: strategyPlan.mode,
-    scorer: strategyPlan.scorer,
-    candidateCount: source.candidates.length,
-    diagnostics: buildDiagnostics(input, indexed, metrics, source)
-  };
-}
-
-function chooseCandidateSource(
-  input: SellerRoutePlannerInput,
-  indexed: ReturnType<typeof indexRegistrySellers>,
-  metrics: MetricIndex
-): CandidateSourceResult {
-  const prewarm = input.prewarmCandidates ?? [];
-  let prewarmDiagnostics: PrewarmSourceDiagnostics = emptyPrewarmDiagnostics();
-  const prewarmBySellerId = new Map(prewarm.map((candidate) => [candidate.sellerId, candidate]));
-  if (prewarm.length > 0) {
-    const missingSellerIds: string[] = [];
-    const blockedSellerIds: string[] = [];
-    const prewarmCandidatesBeforeCompatibility = prewarm
-      .map((candidate) => {
-        const indexedSeller = indexed.bySellerId.get(candidate.sellerId);
-        if (!indexedSeller) {
-          missingSellerIds.push(candidate.sellerId);
-          return undefined;
-        }
-        if (metrics.blockedSellerIds.has(indexedSeller.seller.id)) {
-          blockedSellerIds.push(candidate.sellerId);
-          return undefined;
-        }
-        return buildCandidate({
-          seller: indexedSeller.seller,
-          registryOrder: indexedSeller.registryOrder,
-          modelId: input.modelId,
-          protocol: input.protocol,
-          paymentMethod: input.paymentMethod,
-          metric: mergeMetric(metrics.bySellerId.get(candidate.sellerId), candidate)
-        });
-      })
-      .filter((candidate): candidate is RoutingCandidate => Boolean(candidate));
-    const prewarmCandidates = prewarmCandidatesBeforeCompatibility.filter(isSelectableCandidate);
-    prewarmDiagnostics = {
-      usableCount: prewarmCandidates.length,
-      missingSellerIds,
-      blockedSellerIds,
-      incompatibleSellerIds: incompatibleSellerIds(prewarmCandidatesBeforeCompatibility)
-    };
-
-    if (prewarmCandidates.length > 0) {
-      const registryCandidatesBeforeCompatibility = buildRegistryCandidates({
-        input,
-        indexed,
-        metrics,
-        prewarmBySellerId
-      });
-      return {
-        source: "prewarm_cache",
-        sourceReason: "prewarm_metrics_merged_with_registry",
-        candidates: registryCandidatesBeforeCompatibility.filter(isSelectableCandidate),
-        incompatibleSellerIds: incompatibleSellerIds(registryCandidatesBeforeCompatibility),
-        prewarmDiagnostics
-      };
-    }
-  }
-
-  const registryCandidatesBeforeCompatibility = buildRegistryCandidates({
-    input,
-    indexed,
-    metrics,
-    prewarmBySellerId
-  });
-
-  return {
-    source: "registry_fallback",
-    sourceReason: prewarm.length > 0 ? "prewarm_no_compatible_candidates" : "prewarm_missing",
-    candidates: registryCandidatesBeforeCompatibility.filter(isSelectableCandidate),
-    incompatibleSellerIds: incompatibleSellerIds(registryCandidatesBeforeCompatibility),
-    prewarmDiagnostics
-  };
-}
-
-function buildRegistryCandidates(input: {
-  input: SellerRoutePlannerInput;
-  indexed: ReturnType<typeof indexRegistrySellers>;
-  metrics: MetricIndex;
-  prewarmBySellerId: Map<string, SellerRoutePrewarmCandidate>;
-}): RoutingCandidate[] {
-  return input.indexed.ordered
-    .filter((entry) => !input.metrics.blockedSellerIds.has(entry.seller.id))
-    .map((entry) => buildCandidate({
-      seller: entry.seller,
-      registryOrder: entry.registryOrder,
-      modelId: input.input.modelId,
-      protocol: input.input.protocol,
-      paymentMethod: input.input.paymentMethod,
-      metric: mergeOptionalMetric(
-        input.metrics.bySellerId.get(entry.seller.id),
-        input.prewarmBySellerId.get(entry.seller.id)
-      )
-    }));
-}
-
-function buildCandidate(input: {
-  seller: RegistrySeller;
-  registryOrder: number;
-  modelId: string;
-  protocol: string;
-  paymentMethod: string;
-  metric?: SellerRouteMetric;
-}): RoutingCandidate {
-  return {
-    sellerId: input.seller.id,
-    url: trimTrailingSlashes(input.seller.url),
-    supportsModel: sellerSupportsModel(input.seller, input.modelId),
-    supportsProtocol: sellerSupportsProtocol(input.seller, input.protocol),
-    supportsPayment: sellerSupportsPayment(input.seller, input.paymentMethod),
-    healthScore: input.metric?.healthScore,
-    avgLatencyMs: input.metric?.avgLatencyMs,
-    ttftMs: input.metric?.ttftMs,
-    avgInferenceMs: input.metric?.avgInferenceMs,
-    avgTokensPerSecond: input.metric?.avgTokensPerSecond,
-    discountRatio: input.metric?.discountRatio,
-    registryOrder: input.registryOrder
-  };
-}
-
-function isSelectableCandidate(candidate: RoutingCandidate): boolean {
-  return candidate.supportsModel && candidate.supportsProtocol && candidate.supportsPayment;
-}
-
-function indexRegistrySellers(sellers: RegistrySeller[]): {
-  ordered: IndexedSeller[];
-  bySellerId: Map<string, IndexedSeller>;
-} {
-  const ordered = sellers
-    .filter((seller) => Boolean(seller?.id && seller.url))
-    .filter((seller) => isBuyerVisibleRegistrySeller(seller))
-    .map((seller, registryOrder) => ({ seller, registryOrder }));
-  return {
-    ordered,
-    bySellerId: new Map(ordered.map((entry) => [entry.seller.id, entry]))
-  };
-}
-
-function indexMetrics(metrics: SellerRouteMetric[] | undefined, now: number): MetricIndex {
-  const blockedOpenCircuitSellerIds = new Set((metrics ?? [])
-    .filter((metric) => metric.circuit === "open")
-    .map((metric) => metric.sellerId));
-  const blockedCapacitySellerIds = new Set((metrics ?? [])
-    .filter((metric) => isCapacityBlocked(metric, now))
-    .map((metric) => metric.sellerId));
-  const blockedLocalConcurrencySellerIds = new Set((metrics ?? [])
-    .filter(isLocalConcurrencyBlocked)
-    .map((metric) => metric.sellerId));
-  const blockedSellerIds = new Set([
-    ...blockedOpenCircuitSellerIds,
-    ...blockedCapacitySellerIds,
-    ...blockedLocalConcurrencySellerIds
-  ]);
-  return {
-    bySellerId: new Map((metrics ?? [])
-      .filter((metric) => !blockedSellerIds.has(metric.sellerId))
-      .map((metric) => [metric.sellerId, metric])),
-    blockedSellerIds,
-    blockedOpenCircuitSellerIds,
-    blockedCapacitySellerIds,
-    blockedLocalConcurrencySellerIds
-  };
-}
-
-function buildDiagnostics(
-  input: SellerRoutePlannerInput,
-  indexed: ReturnType<typeof indexRegistrySellers>,
-  metrics: MetricIndex,
-  source: CandidateSourceResult
-): SellerRouteDiagnostics {
-  const visibleOpenBlocked = Array.from(metrics.blockedOpenCircuitSellerIds)
-    .filter((sellerId) => indexed.bySellerId.has(sellerId));
-  const visibleCapacityBlocked = Array.from(metrics.blockedCapacitySellerIds)
-    .filter((sellerId) => indexed.bySellerId.has(sellerId));
-  const visibleLocalConcurrencyBlocked = Array.from(metrics.blockedLocalConcurrencySellerIds)
-    .filter((sellerId) => indexed.bySellerId.has(sellerId));
-  const visibleBlockedSellerIds = Array.from(new Set([
-    ...visibleOpenBlocked,
-    ...visibleCapacityBlocked,
-    ...visibleLocalConcurrencyBlocked
-  ])).sort();
-  return {
-    registryVisibleCount: indexed.ordered.length,
-    prewarmCandidateCount: input.prewarmCandidates?.length ?? 0,
-    prewarmUsableCount: source.prewarmDiagnostics.usableCount,
-    prewarmMissingSellerIds: [...source.prewarmDiagnostics.missingSellerIds].sort(),
-    prewarmBlockedSellerIds: [...source.prewarmDiagnostics.blockedSellerIds].sort(),
-    prewarmIncompatibleSellerIds: [...source.prewarmDiagnostics.incompatibleSellerIds].sort(),
-    sourceCandidateCount: source.candidates.length,
-    blockedOpenCircuitCount: visibleOpenBlocked.length,
-    blockedCapacityCount: visibleCapacityBlocked.length,
-    blockedLocalConcurrencyCount: visibleLocalConcurrencyBlocked.length,
-    blockedSellerIds: visibleBlockedSellerIds,
-    incompatibleCount: source.incompatibleSellerIds.length,
-    incompatibleSellerIds: [...source.incompatibleSellerIds].sort()
-  };
-}
-
-function incompatibleSellerIds(candidates: RoutingCandidate[]): string[] {
-  return candidates
-    .filter((candidate) => !isSelectableCandidate(candidate))
-    .map((candidate) => candidate.sellerId);
-}
-
-function emptyPrewarmDiagnostics(): PrewarmSourceDiagnostics {
-  return {
-    usableCount: 0,
-    missingSellerIds: [],
-    blockedSellerIds: [],
-    incompatibleSellerIds: []
-  };
-}
-
-function mergeMetric(
-  metric: SellerRouteMetric | undefined,
-  prewarm: SellerRoutePrewarmCandidate
-): SellerRouteMetric {
-  return {
-    sellerId: prewarm.sellerId,
-    healthScore: prewarm.healthScore ?? metric?.healthScore,
-    avgLatencyMs: prewarm.avgLatencyMs ?? metric?.avgLatencyMs,
-    ttftMs: metric?.ttftMs ?? prewarm.ttftMs,
-    avgInferenceMs: metric?.avgInferenceMs ?? prewarm.avgInferenceMs,
-    avgTokensPerSecond: metric?.avgTokensPerSecond ?? prewarm.avgTokensPerSecond,
-    discountRatio: metric?.discountRatio,
-    circuit: metric?.circuit,
-    capacityBlockedUntil: metric?.capacityBlockedUntil,
-    localConcurrencyActive: metric?.localConcurrencyActive,
-    localConcurrencyLimit: metric?.localConcurrencyLimit
-  };
-}
-
-function mergeOptionalMetric(
-  metric: SellerRouteMetric | undefined,
-  prewarm: SellerRoutePrewarmCandidate | undefined
-): SellerRouteMetric | undefined {
-  if (!prewarm) {
-    return metric;
-  }
-  return mergeMetric(metric, prewarm);
-}
-
-function isCapacityBlocked(metric: SellerRouteMetric, now: number): boolean {
-  return Number.isFinite(metric.capacityBlockedUntil) && (metric.capacityBlockedUntil as number) > now;
-}
-
-function isLocalConcurrencyBlocked(metric: SellerRouteMetric): boolean {
-  return Number.isFinite(metric.localConcurrencyActive) &&
-    Number.isFinite(metric.localConcurrencyLimit) &&
-    (metric.localConcurrencyActive as number) >= (metric.localConcurrencyLimit as number);
-}
-
-function sellerSupportsModel(seller: RegistrySeller, modelId: string): boolean {
-  const normalized = normalizeLookupValue(modelId);
-  return (seller.models ?? []).some((model) => normalizeLookupValue(model) === normalized);
-}
-
-function sellerSupportsProtocol(seller: RegistrySeller, protocol: string): boolean {
-  const normalized = normalizeLookupValue(protocol);
-  return protocolAliases(seller.supportedProtocols ?? []).some((entry) => normalizeLookupValue(entry) === normalized);
-}
-
-function sellerSupportsPayment(seller: RegistrySeller, paymentMethod: string): boolean {
-  const normalized = normalizeLookupValue(paymentMethod);
-  return (seller.paymentMethods ?? []).some((entry) => normalizeLookupValue(entry) === normalized);
-}
-
-function protocolAliases(protocols: string[]): string[] {
-  return protocols.includes("anthropic_messages") && !protocols.includes("messages")
-    ? [...protocols, "messages"]
-    : protocols;
-}
-
-function normalizeLookupValue(value: string): string {
-  return value.trim().toLowerCase();
-}
-
-function trimTrailingSlashes(value: string): string {
-  return value.replace(/\/+$/, "");
-}