@alexeiled/pi-model-router 0.6.5 → 0.7.0

package/extensions/provider.ts

@@ -25,7 +25,12 @@ import {
   resolveContextWindow,
   resolveMaxTokens,
 } from './config';
-import { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS } from './constants';
+import {
+  DEFAULT_CLASSIFIER_TIMEOUT_MS,
+  DEFAULT_CONTEXT_WINDOW,
+  DEFAULT_MAX_TOKENS,
+  MAX_TURN_CACHE_ENTRIES,
+} from './constants';
 import { extractTextFromContent, hasImageAttachment } from './context';
 import { createJevCandidate, runJevDetailed } from './jev';
 import {
@@ -69,8 +74,10 @@ const createJevFlightKey = (
     model: config.model,
     timeoutMs: config.timeoutMs,
     confidenceThreshold: config.confidenceThreshold,
+    probabilityThreshold: config.probabilityThreshold,
     maxStateTokens: config.maxStateTokens,
     context: config.context,
+    retry: config.retry,
   });
 
 const waitForAbortable = async <T>(
@@ -369,7 +376,7 @@ export const registerRouterProvider = (
   const rememberContinuation = (record: ContinuationRecord) => {
     continuations.delete(record.turn);
     continuations.set(record.turn, record);
-    while (continuations.size > 16) {
+    while (continuations.size > MAX_TURN_CACHE_ENTRIES) {
       const oldest = continuations.keys().next().value;
       if (oldest === undefined) break;
       continuations.delete(oldest);
@@ -383,7 +390,7 @@ export const registerRouterProvider = (
   ) => {
     advisedTurns.delete(turn);
     advisedTurns.set(turn, { policy, config, decision });
-    while (advisedTurns.size > 16) {
+    while (advisedTurns.size > MAX_TURN_CACHE_ENTRIES) {
       const oldest = advisedTurns.keys().next().value;
       if (oldest === undefined) break;
       advisedTurns.delete(oldest);
@@ -591,6 +598,18 @@ export const registerRouterProvider = (
             );
             decision.isBudgetForced = baseline.isBudgetForced;
             decision.advisor = advisorConfigured ? 'bypassed' : 'none';
+            if (advisorConfigured)
+              decision.bypassReason = pinnedTier
+                ? 'pinned'
+                : isBudgetExceeded
+                  ? 'budget'
+                  : toolContinuation
+                    ? 'tool-continuation'
+                    : !user || !turn
+                      ? 'no-user-turn'
+                      : advisedTurns.has(turn)
+                        ? 'turn-advised'
+                        : undefined;
           }
 
           // Tool results never invoke advisors, even when their prior route cannot be reused.
@@ -606,13 +625,18 @@ export const registerRouterProvider = (
           ) {
             const started = performance.now();
             const routingDeadline =
-              started + (useJev && jev ? jev.timeoutMs : 10_000);
+              started +
+              (useJev && jev
+                ? jev.timeoutMs
+                : (state.currentConfig.classifierModel?.timeoutMs ??
+                  DEFAULT_CLASSIFIER_TIMEOUT_MS));
             const candidates = primaryRoutePairs(profile, pairs).map(
               createJevCandidate,
             );
             // A single primary bypasses advice, not a baseline's eligible fallback.
             if (candidates.length <= 1) {
               decision.advisor = 'bypassed';
+              decision.bypassReason = 'single-candidate';
               rememberAdvisedDecision(
                 turn,
                 decision,
@@ -629,6 +653,8 @@ export const registerRouterProvider = (
                   context,
                   candidates,
                   profile: profile.jev,
+                  baselineTier: selectBaselineRoute(model.id, profile, pairs)
+                    .pair.tier,
                   routingDeadline,
                 },
               );

package/extensions/state.ts

@@ -16,7 +16,14 @@ import type {
   RouterPinByProfile,
   RoutingDecision,
 } from './types';
-import { isAdvisorOutcome, isRoutingReasonCode, JEV_OUTCOMES } from './types';
+import {
+  isAdvisorOutcome,
+  isBypassReason,
+  isRoutingReasonCode,
+  JEV_OUTCOMES,
+  JEV_RESPONSE_ISSUES,
+  JEV_SELECTION_BASES,
+} from './types';
 
 const LAST_PROFILE_STATE_FILE = 'model-router-state.json';
 
@@ -191,11 +198,27 @@ const snapshotJev = (value: unknown): JevDiagnostics | undefined => {
     result.resolvedModel = value.resolvedModel;
   if (isRouterTier(value.choice) || value.choice === 'uncertain')
     result.choice = value.choice;
-  for (const key of ['confidence', 'probability', 'threshold'] as const) {
+  if (isRouterTier(value.selectedTier))
+    result.selectedTier = value.selectedTier;
+  const basis = JEV_SELECTION_BASES.find(
+    (entry) => entry === value.selectionBasis,
+  );
+  if (basis) result.selectionBasis = basis;
+  for (const key of [
+    'confidence',
+    'probability',
+    'routeProbability',
+    'threshold',
+    'probabilityThreshold',
+  ] as const) {
     const number = value[key];
     if (isFiniteNumber(number) && number >= 0 && number <= 1)
       result[key] = number;
   }
+  const issue = JEV_RESPONSE_ISSUES.find(
+    (entry) => entry === value.responseIssue,
+  );
+  if (issue) result.responseIssue = issue;
   for (const key of [
     'startedAt',
     'timeoutMs',
@@ -203,6 +226,7 @@ const snapshotJev = (value: unknown): JevDiagnostics | undefined => {
     'estimatedInputTokens',
     'actualInputTokens',
     'httpStatus',
+    'attempts',
   ] as const) {
     const number = value[key];
     if (isFiniteNumber(number) && Number.isSafeInteger(number) && number >= 0)
@@ -234,6 +258,9 @@ export const snapshotDecision = (
       ? decision.errorClass
       : undefined,
   advisor: isAdvisorOutcome(decision.advisor) ? decision.advisor : undefined,
+  bypassReason: isBypassReason(decision.bypassReason)
+    ? decision.bypassReason
+    : undefined,
   jev: snapshotJev(decision.jev),
   reuse:
     decision.reuse === 'same-turn' ||

package/extensions/types.ts

@@ -22,6 +22,8 @@ export interface ModelDefinition {
 export interface ClassifierConfig {
   model: string;
   thinking?: ThinkingLevel | undefined;
+  /** Total classifier budget in ms; `DEFAULT_CLASSIFIER_TIMEOUT_MS` when omitted. */
+  timeoutMs?: number | undefined;
 }
 
 export interface RoutedTierConfig {
@@ -47,6 +49,12 @@ export interface JevContextConfig {
   toolResults: 'none' | 'last' | 'last-error';
   maxToolTokens: number;
 }
+export interface JevRetryConfig {
+  /** HTTP attempts in total; 1 disables retries. */
+  maxAttempts: number;
+  /** First backoff delay; doubled per attempt, raised by `Retry-After`. */
+  backoffMs: number;
+}
 export interface JevTextExcerpt {
   text: string;
   truncated: boolean;
@@ -72,8 +80,10 @@ export interface JevConfig {
   model: string;
   timeoutMs: number;
   confidenceThreshold: number;
+  probabilityThreshold: number;
   maxStateTokens: number;
   context?: JevContextConfig | undefined;
+  retry?: JevRetryConfig | undefined;
   mode: 'advisory';
 }
 
@@ -133,15 +143,32 @@ export interface JevRequest {
   context: Context;
   candidates: readonly JevRouteCandidate[];
   profile: JevProfileConfig | undefined;
+  /** Local fallback tier; abstention mass is assigned to it, never inferred remotely. */
+  baselineTier: RouterTier;
   /** Absolute monotonic deadline supplied by the routing orchestrator. */
   routingDeadline: number;
   signal?: AbortSignal | undefined;
 }
 
+export const JEV_SELECTION_BASES = ['choice', 'probability'] as const;
+export type JevSelectionBasis = (typeof JEV_SELECTION_BASES)[number];
+
+/** Local validation codes; remote error text is never retained. */
+export const JEV_RESPONSE_ISSUES = [
+  'unreadable-body',
+  'missing-answer',
+  'unexpected-answer-type',
+  'unknown-choice',
+  'invalid-confidence',
+  'distribution-keys',
+  'distribution-sum',
+  'distribution-argmax',
+] as const;
+export type JevResponseIssue = (typeof JEV_RESPONSE_ISSUES)[number];
+
 export const JEV_OUTCOMES = [
   'selected',
   'uncertain',
-  'low-confidence',
   'invalid-response',
   'http-error',
   'network-error',
@@ -161,14 +188,23 @@ export interface JevDiagnostics {
   model?: string | undefined;
   resolvedModel?: string | undefined;
   choice?: RouterTier | 'uncertain' | undefined;
+  /** Acted-on tier, which a conservative probability selection can raise above `choice`. */
+  selectedTier?: RouterTier | undefined;
+  selectionBasis?: JevSelectionBasis | undefined;
   confidence?: number | undefined;
   probability?: number | undefined;
+  /** Cumulative probability of the selected tier and every lower tier. */
+  routeProbability?: number | undefined;
   threshold?: number | undefined;
+  probabilityThreshold?: number | undefined;
   timeoutMs?: number | undefined;
   candidateCount?: number | undefined;
   estimatedInputTokens?: number | undefined;
   actualInputTokens?: number | undefined;
   httpStatus?: number | undefined;
+  /** HTTP attempts made, including the retry of a documented transient status. */
+  attempts?: number | undefined;
+  responseIssue?: JevResponseIssue | undefined;
 }
 export interface JevResult {
   advice?: JevAdvice | undefined;
@@ -224,6 +260,18 @@ export const ADVISOR_OUTCOMES = [
 export type AdvisorOutcome = (typeof ADVISOR_OUTCOMES)[number];
 export const isAdvisorOutcome = (value: unknown): value is AdvisorOutcome =>
   ADVISOR_OUTCOMES.some((outcome) => outcome === value);
+/** Why a configured advisor was not asked on this decision. */
+export const BYPASS_REASONS = [
+  'pinned',
+  'budget',
+  'single-candidate',
+  'tool-continuation',
+  'no-user-turn',
+  'turn-advised',
+] as const;
+export type BypassReason = (typeof BYPASS_REASONS)[number];
+export const isBypassReason = (value: unknown): value is BypassReason =>
+  BYPASS_REASONS.some((reason) => reason === value);
 
 export interface RoutingDecision {
   profile: string;
@@ -236,6 +284,7 @@ export interface RoutingDecision {
   routingLatencyMs?: number | undefined;
   errorClass?: RoutingErrorClass | undefined;
   advisor?: AdvisorOutcome | undefined;
+  bypassReason?: BypassReason | undefined;
   jev?: JevDiagnostics | undefined;
   reuse?: 'same-turn' | 'shared' | 'continuation' | undefined;
   thinking: ThinkingLevel;

package/extensions/ui.ts

@@ -25,6 +25,25 @@ export const formatDecisionSource = (decision: RoutingDecision): string =>
     ? decision.reasonCode
     : '';
 
+const formatBypassReason = (decision: RoutingDecision): string => {
+  switch (decision.bypassReason) {
+    case 'pinned':
+      return `pinned ${decision.tier}`;
+    case 'budget':
+      return 'over budget';
+    case 'single-candidate':
+      return `only ${decision.tier} eligible`;
+    case 'tool-continuation':
+      return 'tool turn';
+    case 'no-user-turn':
+      return 'no user turn';
+    case 'turn-advised':
+      return 'turn already advised';
+    default:
+      return '';
+  }
+};
+
 export const formatAdvisorLabel = (
   decision: RoutingDecision,
 ): string | undefined => {
@@ -32,8 +51,10 @@ export const formatAdvisorLabel = (
   switch (decision.advisor) {
     case 'none':
       return 'local baseline';
-    case 'bypassed':
-      return 'advice bypassed';
+    case 'bypassed': {
+      const reason = formatBypassReason(decision);
+      return reason ? `advice skipped: ${reason}` : 'advice bypassed';
+    }
     case 'jev':
       return '🧭 Jev ✓';
     case 'jev-fallback':
@@ -76,6 +97,11 @@ export const formatAdvisorDetail = (
     );
     if (metrics.choice && metrics.choice !== 'uncertain')
       parts.push(`choice=${metrics.choice}`);
+    if (metrics.selectedTier && metrics.selectedTier !== metrics.choice)
+      parts.push(`selected=${metrics.selectedTier}`);
+    if (metrics.selectionBasis) parts.push(`basis=${metrics.selectionBasis}`);
+    if (metrics.routeProbability !== undefined)
+      parts.push(`route-p=${(metrics.routeProbability * 100).toFixed(1)}%`);
     if (metrics.probability !== undefined)
       parts.push(
         `${metrics.outcome === 'uncertain' ? 'abstention-p' : 'p'}=${(metrics.probability * 100).toFixed(1)}%`,
@@ -86,6 +112,13 @@ export const formatAdvisorDetail = (
       );
     if (metrics.threshold !== undefined && metrics.outcome !== 'uncertain')
       parts.push(`threshold=${(metrics.threshold * 100).toFixed(1)}%`);
+    if (
+      metrics.probabilityThreshold !== undefined &&
+      metrics.selectionBasis === 'probability'
+    )
+      parts.push(
+        `route-threshold=${(metrics.probabilityThreshold * 100).toFixed(1)}%`,
+      );
     if (metrics.timeoutMs !== undefined)
       parts.push(`budget=${metrics.timeoutMs}ms`);
     if (metrics.candidateCount !== undefined)
@@ -102,6 +135,15 @@ export const formatAdvisorDetail = (
       parts.push(`Jev usage=${metrics.actualInputTokens} input tokens`);
     if (metrics.httpStatus !== undefined)
       parts.push(`HTTP ${metrics.httpStatus}`);
+    if (metrics.attempts !== undefined && metrics.attempts > 1)
+      parts.push(`attempts=${metrics.attempts}`);
+    if (metrics.responseIssue) parts.push(`response=${metrics.responseIssue}`);
+    if (metrics.httpStatus === 401)
+      parts.push('Check the user-config Jev API key.');
+    if (metrics.httpStatus === 422)
+      parts.push('Jev rejected the request shape.');
+    if (metrics.httpStatus === 429 || metrics.httpStatus === 529)
+      parts.push('Transient Jev limit; the router retried once within budget.');
   } else if (decision.errorClass) {
     parts.push(decision.errorClass);
   }
@@ -127,10 +169,10 @@ export const formatAdvisorFooter = (
   let summary: string;
   switch (metrics.outcome) {
     case 'selected':
-      summary = `→ ${metrics.choice ?? decision.tier}${confidence}`;
-      break;
-    case 'low-confidence':
-      summary = `${metrics.choice ?? 'choice'}${confidence}${metrics.threshold !== undefined ? ` <${Math.round(metrics.threshold * 100)}%` : ''} → baseline`;
+      summary =
+        metrics.selectionBasis === 'probability'
+          ? `${metrics.choice ?? 'choice'}${confidence}${metrics.threshold !== undefined ? ` <${Math.round(metrics.threshold * 100)}%` : ''} → ${metrics.selectedTier ?? decision.tier}`
+          : `→ ${metrics.choice ?? decision.tier}${confidence}`;
       break;
     case 'uncertain':
       summary = ': no tier chosen → baseline';
@@ -145,7 +187,7 @@ export const formatAdvisorFooter = (
       summary = ': network error → baseline';
       break;
     case 'invalid-response':
-      summary = ': invalid response → baseline';
+      summary = `: invalid response${metrics.responseIssue ? ` (${metrics.responseIssue})` : ''} → baseline`;
       break;
     case 'cancelled':
       summary = ': cancelled';

package/model-router.example.json

@@ -8,6 +8,7 @@
     "model": "jev-1.13.0",
     "timeoutMs": 1500,
     "confidenceThreshold": 0.65,
+    "probabilityThreshold": 0.8,
     "maxStateTokens": 3000,
     "context": {
       "previousTurns": 2,
@@ -15,6 +16,7 @@
       "toolResults": "last-error",
       "maxToolTokens": 250
     },
+    "retry": { "maxAttempts": 2, "backoffMs": 400 },
     "mode": "advisory"
   },
   "classifierModel": "flash",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-model-router",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "type": "module",
   "files": [
     "extensions",