@tokenbuddy/tokenbuddy 1.0.39 → 1.0.41

package/dist/src/seller-pool.d.ts

@@ -37,10 +37,10 @@ export interface PoolEntry {
     lastFailAt: number;
     /** 最近一次被 probe 的 unix 毫秒时间戳（即 cache.warmedAt） */
     lastProbeAt: number;
-    /** 综合健康分 0-100，热路径排序的主键 */
-    healthScore: number;
-    /** 平均延迟（毫秒） */
-    avgLatencyMs: number;
+    /** 综合健康分 0-100；registry-only fallback 尚未探测时为空 */
+    healthScore?: number;
+    /** 平均延迟（毫秒）；registry-only fallback 尚未探测时为空 */
+    avgLatencyMs?: number;
     /** health probe 延迟（毫秒），可选 */
     healthProbeLatencyMs?: number;
     /** TTFT（毫秒），可选 */
@@ -166,7 +166,7 @@ export declare class SellerPool {
      * may be selected before prewarm has produced a cache entry; failures
      * from that first live request still need to affect the next route plan.
      */
-    ensureRegistrySellers(sellers: RegistrySeller[], now?: number): void;
+    ensureRegistrySellers(sellers: RegistrySeller[]): void;
     /**
      * Pick up to `limit` candidates for a (model, protocol, payment) triple.
      * Sellers in the `open` circuit are skipped unless their open state has

package/dist/src/seller-pool.js

@@ -87,7 +87,7 @@ export class SellerPool {
      * may be selected before prewarm has produced a cache entry; failures
      * from that first live request still need to affect the next route plan.
      */
-    ensureRegistrySellers(sellers, now = this.now()) {
+    ensureRegistrySellers(sellers) {
         for (const seller of sellers) {
             const previous = this.entries.get(seller.id);
             if (previous) {
@@ -107,9 +107,7 @@ export class SellerPool {
                 recentFailures: [],
                 lastSuccessAt: 0,
                 lastFailAt: 0,
-                lastProbeAt: now,
-                healthScore: 60,
-                avgLatencyMs: 0
+                lastProbeAt: 0
             });
         }
     }
@@ -149,7 +147,7 @@ export class SellerPool {
         })
             .filter((row) => row.entry.circuit !== "open")
             .filter((row) => !isCapacityBlocked(row.entry, now))
-            .sort((a, b) => b.entry.healthScore - a.entry.healthScore)
+            .sort((a, b) => (b.entry.healthScore ?? 0) - (a.entry.healthScore ?? 0))
             .slice(0, limit);
         return {
             candidates,
@@ -173,7 +171,7 @@ export class SellerPool {
             consecutiveFailures: 0,
             recentFailures: [],
             lastSuccessAt: now,
-            healthScore: Math.min(100, Math.max(entry.healthScore, 60)),
+            healthScore: Math.min(100, Math.max(entry.healthScore ?? 0, 60)),
             capacityBlockedUntil: undefined
         };
         this.entries.set(sellerId, next);
@@ -196,7 +194,7 @@ export class SellerPool {
         const next = {
             ...entry,
             lastSuccessAt: now,
-            healthScore: Math.min(100, Math.max(entry.healthScore, 60)),
+            healthScore: Math.min(100, Math.max(entry.healthScore ?? 0, 60)),
             avgLatencyMs: avgInferenceMs ?? entry.avgLatencyMs,
             ttftMs: ttftMs ?? entry.ttftMs,
             avgInferenceMs: avgInferenceMs ?? entry.avgInferenceMs,

package/dist/src/seller-route-recommendations.d.ts

@@ -0,0 +1,110 @@
+import { type RegistrySeller, type RouteState } from "./seller-catalog.js";
+import { type SellerRouteMetric, type SellerRoutePlan, type SellerRoutePrewarmCandidate } from "./seller-route-planner.js";
+import type { SellerRoutingScorer } from "./seller-routing-strategy.js";
+export type RecommendationScope = {
+    type: "recommended";
+} | {
+    type: "custom";
+    sellerIds: string[];
+};
+export type UserNodeStatus = "ready" | "limited" | "unavailable";
+export type RecommendationReasonCode = "top_route" | "unique_route" | "failover_route" | "routable" | "no_recent_probe" | "not_compatible" | "runtime_blocked" | "empty_focus_set";
+export interface BlockedModelReason {
+    modelId: string;
+    reason: "runtime_blocked";
+}
+export interface SellerSetContribution {
+    setScore: number;
+    coverageCount: number;
+    top1Count: number;
+    topKCount: number;
+    uniqueModelCoverageCount: number;
+    averagePlannerRank?: number;
+    averagePlannerScore?: number;
+    healthPenalty: number;
+    missingMetricPenalty: number;
+}
+export interface RecommendationSellerMetrics {
+    healthScore?: number;
+    avgLatencyMs?: number;
+    ttftMs?: number;
+    avgInferenceMs?: number;
+    avgTokensPerSecond?: number;
+    discountRatio?: number;
+    routeStates: RouteState[];
+}
+export interface RecommendedSeller {
+    sellerId: string;
+    name?: string;
+    url: string;
+    rank: number;
+    status: UserNodeStatus;
+    reasonCode: RecommendationReasonCode;
+    reasonText: string;
+    routableModels: string[];
+    top1Models: string[];
+    topKModels: string[];
+    unsupportedModels: string[];
+    blockedModels: BlockedModelReason[];
+    aggregate: SellerSetContribution;
+    metrics: RecommendationSellerMetrics;
+}
+export interface ExcludedSeller {
+    sellerId: string;
+    name?: string;
+    url: string;
+    status: UserNodeStatus;
+    reasonCode: RecommendationReasonCode;
+    reasonText: string;
+    unsupportedModels: string[];
+    blockedModels: BlockedModelReason[];
+}
+export interface ModelRecommendationSummary {
+    modelId: string;
+    protocol: string;
+    routeCount: number;
+    topSellerId?: string;
+    hasRoutableSeller: boolean;
+    warningCode?: "no_routable_seller" | "only_limited_sellers" | "custom_missing_coverage";
+    routes: Array<{
+        sellerId: string;
+        rank: number;
+        status: UserNodeStatus;
+    }>;
+}
+export interface RecommendationDiagnostics {
+    registryVisibleCount: number;
+    candidateSellerCount: number;
+    focusModelCount: number;
+    unknownSellerIds: string[];
+    modelPlanCount: number;
+    unroutableModelIds: string[];
+}
+export interface SellerRouteRecommendations {
+    focusModelSet: string[];
+    protocol: string;
+    protocolByModelId: Record<string, string>;
+    paymentMethod: string;
+    scorer: SellerRoutingScorer;
+    scope: RecommendationScope;
+    sellers: RecommendedSeller[];
+    excludedSellers: ExcludedSeller[];
+    modelSummaries: ModelRecommendationSummary[];
+    plansByModelId: Record<string, SellerRoutePlan>;
+    diagnostics: RecommendationDiagnostics;
+}
+export interface BuildSellerRouteRecommendationsInput {
+    focusModelSet: string[];
+    protocol: string;
+    protocolByModelId?: Record<string, string>;
+    paymentMethod: string;
+    scorer: SellerRoutingScorer;
+    scope: RecommendationScope;
+    registrySellers: RegistrySeller[];
+    prewarmCandidatesForModel?: (modelId: string, protocol: string) => SellerRoutePrewarmCandidate[] | undefined;
+    sellerMetrics?: SellerRouteMetric[];
+    topK?: number;
+    now?: number;
+}
+export declare function buildSellerRouteRecommendations(input: BuildSellerRouteRecommendationsInput): SellerRouteRecommendations;
+//# sourceMappingURL=seller-route-recommendations.d.ts.map

package/dist/src/seller-route-recommendations.js

@@ -0,0 +1,334 @@
+import { isBuyerVisibleRegistrySeller } from "./seller-catalog.js";
+import { planSellerRouteSet } from "./seller-route-planner.js";
+export function buildSellerRouteRecommendations(input) {
+    const focusModelSet = uniqueStrings(input.focusModelSet);
+    const topK = Math.max(1, Math.floor(input.topK ?? 3));
+    const protocolByModelId = Object.fromEntries(focusModelSet.map((modelId) => [
+        modelId,
+        input.protocolByModelId?.[modelId]?.trim() || input.protocol
+    ]));
+    const visibleRegistrySellers = input.registrySellers
+        .filter((seller) => Boolean(seller?.id && seller.url))
+        .filter(isBuyerVisibleRegistrySeller);
+    const scopeSellerIds = input.scope.type === "custom"
+        ? new Set(input.scope.sellerIds.map(normalizeSellerId).filter(Boolean))
+        : undefined;
+    const candidateSellers = scopeSellerIds
+        ? visibleRegistrySellers.filter((seller) => scopeSellerIds.has(normalizeSellerId(seller.id)))
+        : visibleRegistrySellers;
+    const candidateOrder = new Map(candidateSellers.map((seller, index) => [seller.id, index]));
+    const unknownSellerIds = input.scope.type === "custom"
+        ? uniqueStrings(input.scope.sellerIds.map((sellerId) => sellerId.trim()).filter(Boolean))
+            .filter((sellerId) => !visibleRegistrySellers.some((seller) => normalizeSellerId(seller.id) === normalizeSellerId(sellerId)))
+        : [];
+    const accumulators = new Map();
+    const plansByModelId = {};
+    for (const seller of candidateSellers) {
+        accumulators.set(seller.id, {
+            seller,
+            routes: [],
+            unsupportedModels: new Set(),
+            blockedModels: []
+        });
+    }
+    const modelSummaries = [];
+    for (const modelId of focusModelSet) {
+        const protocol = protocolByModelId[modelId] ?? input.protocol;
+        const plan = planSellerRouteSet({
+            modelId,
+            protocol,
+            paymentMethod: input.paymentMethod,
+            registrySellers: candidateSellers,
+            routing: input.scope.type === "custom"
+                ? { mode: "fixedSet", scorer: input.scorer, sellerIds: input.scope.sellerIds }
+                : { mode: "fullAuto", scorer: input.scorer },
+            prewarmCandidates: input.prewarmCandidatesForModel?.(modelId, protocol),
+            sellerMetrics: input.sellerMetrics,
+            now: input.now
+        });
+        plansByModelId[modelId] = plan;
+        const routeSellerIds = new Set(plan.routes.map((route) => route.seller.id));
+        const blockedSellerIds = new Set(plan.diagnostics.blockedSellerIds);
+        plan.routes.forEach((route, index) => {
+            const accumulator = accumulators.get(route.seller.id);
+            if (!accumulator)
+                return;
+            accumulator.routes.push({
+                modelId,
+                route,
+                rank: index + 1,
+                status: statusFromRoute(route)
+            });
+        });
+        for (const seller of candidateSellers) {
+            if (routeSellerIds.has(seller.id))
+                continue;
+            const accumulator = accumulators.get(seller.id);
+            if (!accumulator)
+                continue;
+            if (blockedSellerIds.has(seller.id)) {
+                accumulator.blockedModels.push({ modelId, reason: "runtime_blocked" });
+            }
+            else {
+                accumulator.unsupportedModels.add(modelId);
+            }
+        }
+        const routeStatuses = plan.routes.map(statusFromRoute);
+        modelSummaries.push({
+            modelId,
+            protocol,
+            routeCount: plan.routes.length,
+            topSellerId: plan.routes[0]?.seller.id,
+            hasRoutableSeller: plan.routes.length > 0,
+            warningCode: warningCodeForModel(plan.routes.length, routeStatuses, input.scope.type),
+            routes: plan.routes.map((route, index) => ({
+                sellerId: route.seller.id,
+                rank: index + 1,
+                status: routeStatuses[index] ?? "limited"
+            }))
+        });
+    }
+    const uniqueTopSellerByModel = new Map(modelSummaries
+        .filter((summary) => summary.routeCount === 1 && summary.topSellerId)
+        .map((summary) => [summary.modelId, summary.topSellerId]));
+    const recommended = [];
+    const excluded = [];
+    for (const accumulator of accumulators.values()) {
+        if (accumulator.routes.length === 0) {
+            excluded.push(excludedSellerFromAccumulator(accumulator, focusModelSet));
+            continue;
+        }
+        recommended.push(recommendedSellerFromAccumulator({
+            accumulator,
+            focusModelSet,
+            topK,
+            uniqueTopSellerByModel,
+            registryOrder: candidateOrder.get(accumulator.seller.id) ?? Number.MAX_SAFE_INTEGER
+        }));
+    }
+    recommended.sort((left, right) => right.aggregate.setScore - left.aggregate.setScore ||
+        (candidateOrder.get(left.sellerId) ?? Number.MAX_SAFE_INTEGER) - (candidateOrder.get(right.sellerId) ?? Number.MAX_SAFE_INTEGER) ||
+        left.sellerId.localeCompare(right.sellerId));
+    recommended.forEach((seller, index) => {
+        seller.rank = index + 1;
+    });
+    excluded.sort((left, right) => (candidateOrder.get(left.sellerId) ?? Number.MAX_SAFE_INTEGER) - (candidateOrder.get(right.sellerId) ?? Number.MAX_SAFE_INTEGER) ||
+        left.sellerId.localeCompare(right.sellerId));
+    return {
+        focusModelSet,
+        protocol: input.protocol,
+        protocolByModelId,
+        paymentMethod: input.paymentMethod,
+        scorer: input.scorer,
+        scope: input.scope,
+        sellers: recommended,
+        excludedSellers: excluded,
+        modelSummaries,
+        plansByModelId,
+        diagnostics: {
+            registryVisibleCount: visibleRegistrySellers.length,
+            candidateSellerCount: candidateSellers.length,
+            focusModelCount: focusModelSet.length,
+            unknownSellerIds,
+            modelPlanCount: Object.keys(plansByModelId).length,
+            unroutableModelIds: modelSummaries
+                .filter((summary) => !summary.hasRoutableSeller)
+                .map((summary) => summary.modelId)
+        }
+    };
+}
+function recommendedSellerFromAccumulator(input) {
+    const { accumulator, focusModelSet, topK, uniqueTopSellerByModel } = input;
+    const routeStatuses = accumulator.routes.map((entry) => entry.status);
+    const status = aggregateStatus(routeStatuses);
+    const routableModels = accumulator.routes.map((entry) => entry.modelId);
+    const top1Models = accumulator.routes
+        .filter((entry) => entry.rank === 1)
+        .map((entry) => entry.modelId);
+    const topKModels = accumulator.routes
+        .filter((entry) => entry.rank <= topK)
+        .map((entry) => entry.modelId);
+    const uniqueModels = accumulator.routes
+        .filter((entry) => uniqueTopSellerByModel.get(entry.modelId) === accumulator.seller.id)
+        .map((entry) => entry.modelId);
+    const averagePlannerRank = average(accumulator.routes.map((entry) => entry.rank));
+    const averagePlannerScore = average(accumulator.routes.map((entry) => rankScore(entry.rank)));
+    const healthPenalty = status === "ready" ? 0 : status === "limited" ? 15 : 100;
+    const missingMetricPenalty = accumulator.routes.reduce((total, entry) => total + missingMetricPenaltyForRoute(entry.route), 0);
+    const aggregate = {
+        setScore: top1Models.length * 100 +
+            topKModels.length * 40 +
+            uniqueModels.length * 60 +
+            (averagePlannerScore ?? 0) * 0.5 +
+            routableModels.length * 10 -
+            healthPenalty -
+            missingMetricPenalty,
+        coverageCount: routableModels.length,
+        top1Count: top1Models.length,
+        topKCount: topKModels.length,
+        uniqueModelCoverageCount: uniqueModels.length,
+        averagePlannerRank,
+        averagePlannerScore,
+        healthPenalty,
+        missingMetricPenalty
+    };
+    const bestRoute = accumulator.routes
+        .slice()
+        .sort((left, right) => left.rank - right.rank)[0]?.route;
+    const reason = reasonForRecommendedSeller({
+        status,
+        top1Models,
+        topKModels,
+        uniqueModels,
+        routableModels,
+        focusModelSet,
+        routes: accumulator.routes
+    });
+    return {
+        sellerId: accumulator.seller.id,
+        name: accumulator.seller.name,
+        url: accumulator.seller.url,
+        rank: input.registryOrder + 1,
+        status,
+        reasonCode: reason.code,
+        reasonText: reason.text,
+        routableModels,
+        top1Models,
+        topKModels,
+        unsupportedModels: focusModelSet.filter((modelId) => accumulator.unsupportedModels.has(modelId)),
+        blockedModels: accumulator.blockedModels,
+        aggregate,
+        metrics: {
+            healthScore: bestRoute?.metrics.healthScore,
+            avgLatencyMs: bestRoute?.metrics.avgLatencyMs,
+            ttftMs: bestRoute?.metrics.ttftMs,
+            avgInferenceMs: bestRoute?.metrics.avgInferenceMs,
+            avgTokensPerSecond: bestRoute?.metrics.avgTokensPerSecond,
+            discountRatio: bestRoute?.metrics.discountRatio,
+            routeStates: uniqueRouteStates(accumulator.routes.map((entry) => entry.route.metrics.routeState))
+        }
+    };
+}
+function excludedSellerFromAccumulator(accumulator, focusModelSet) {
+    const blockedModels = accumulator.blockedModels;
+    const reasonCode = blockedModels.length > 0 ? "runtime_blocked" : "not_compatible";
+    return {
+        sellerId: accumulator.seller.id,
+        name: accumulator.seller.name,
+        url: accumulator.seller.url,
+        status: "unavailable",
+        reasonCode,
+        reasonText: reasonCode === "runtime_blocked"
+            ? `Unavailable for ${blockedModels.length} selected model${blockedModels.length === 1 ? "" : "s"} due to runtime limits`
+            : "Not compatible with the selected model set",
+        unsupportedModels: focusModelSet.filter((modelId) => accumulator.unsupportedModels.has(modelId)),
+        blockedModels
+    };
+}
+function statusFromRoute(route) {
+    const routeState = route.metrics.routeState;
+    if (routeState === "error" || routeState === "cooldown" || routeState === "full") {
+        return "unavailable";
+    }
+    if (routeState === "degraded" || routeState === "unknown") {
+        return "limited";
+    }
+    if (routeState === "ok") {
+        return "ready";
+    }
+    if (Number.isFinite(route.metrics.healthScore)) {
+        return route.metrics.healthScore >= 70 ? "ready" : "limited";
+    }
+    return "limited";
+}
+function aggregateStatus(statuses) {
+    if (statuses.length === 0)
+        return "unavailable";
+    if (statuses.some((status) => status === "ready"))
+        return "ready";
+    if (statuses.some((status) => status === "limited"))
+        return "limited";
+    return "unavailable";
+}
+function warningCodeForModel(routeCount, statuses, scopeType) {
+    if (routeCount === 0) {
+        return scopeType === "custom" ? "custom_missing_coverage" : "no_routable_seller";
+    }
+    if (statuses.length > 0 && statuses.every((status) => status !== "ready")) {
+        return "only_limited_sellers";
+    }
+    return undefined;
+}
+function reasonForRecommendedSeller(input) {
+    if (input.uniqueModels.length > 0) {
+        return {
+            code: "unique_route",
+            text: `Only route for ${formatModelList(input.uniqueModels)}`
+        };
+    }
+    if (input.top1Models.length > 0) {
+        return {
+            code: "top_route",
+            text: `Top route for ${formatModelList(input.top1Models)}`
+        };
+    }
+    if (input.topKModels.length > 0) {
+        return {
+            code: "failover_route",
+            text: `Failover route for ${formatModelList(input.topKModels)}`
+        };
+    }
+    if (input.status === "limited" && input.routes.every((entry) => entry.status === "limited")) {
+        return {
+            code: "no_recent_probe",
+            text: `Routable for ${input.routableModels.length}/${input.focusModelSet.length} selected models, but metrics are limited`
+        };
+    }
+    return {
+        code: "routable",
+        text: `Routable for ${input.routableModels.length}/${input.focusModelSet.length} selected models`
+    };
+}
+function missingMetricPenaltyForRoute(route) {
+    let missing = 0;
+    if (!Number.isFinite(route.metrics.healthScore))
+        missing += 1;
+    if (!Number.isFinite(route.metrics.ttftMs) && !Number.isFinite(route.metrics.avgLatencyMs))
+        missing += 1;
+    if (!Number.isFinite(route.metrics.discountRatio))
+        missing += 1;
+    return missing * 5;
+}
+function rankScore(rank) {
+    return Math.max(0, 100 - Math.max(0, rank - 1) * 25);
+}
+function average(values) {
+    const finite = values.filter(Number.isFinite);
+    if (finite.length === 0)
+        return undefined;
+    return finite.reduce((sum, value) => sum + value, 0) / finite.length;
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const trimmed = value.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        result.push(trimmed);
+    }
+    return result;
+}
+function uniqueRouteStates(values) {
+    return Array.from(new Set(values.filter((value) => Boolean(value))));
+}
+function normalizeSellerId(value) {
+    return value.trim().toLowerCase();
+}
+function formatModelList(modelIds) {
+    if (modelIds.length <= 2)
+        return modelIds.join(" and ");
+    return `${modelIds.slice(0, 2).join(", ")} +${modelIds.length - 2}`;
+}
+//# sourceMappingURL=seller-route-recommendations.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenbuddy/tokenbuddy",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "description": "TokenBuddy Client CLI and Daemon",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "@tokenbuddy/contracts": "^1.0.39",
+    "@tokenbuddy/contracts": "^1.0.41",
     "@tokenbuddy/logging": "^1.0.0",
     "cli-table3": "^0.6.4",
     "commander": "^12.0.0",