@alexeiled/pi-model-router 0.5.1 → 0.6.0

package/extensions/routing.ts

@@ -1,76 +1,28 @@
-import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
-import type { Context, Message } from '@earendil-works/pi-ai';
-import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
-import { isRouterTier, parseCanonicalModelRef } from './config';
+import {
+  type Api,
+  getSupportedThinkingLevels,
+  type Model,
+} from '@earendil-works/pi-ai';
+import { parseCanonicalModelRef } from './config';
 import type {
+  ModelDefinition,
+  RoutePair,
   RouterPhase,
   RouterProfile,
   RouterThinkingByTier,
   RouterTier,
   RoutingDecision,
-  RoutingRule,
+  RoutingReasonCode,
 } from './types';
+import { ROUTER_TIERS } from './types';
 
-export const extractTextFromContent = (
-  content: string | Message['content'],
-): string => {
-  if (typeof content === 'string') {
-    return content;
-  }
-  return content
-    .map((part) => {
-      if (part.type === 'text') return part.text;
-      if (part.type === 'thinking') return part.thinking;
-      if (part.type === 'toolCall')
-        return `${part.name} ${JSON.stringify(part.arguments)}`;
-      return '';
-    })
-    .filter(Boolean)
-    .join('\n');
-};
-
-export const getLastUserText = (context: Context): string => {
-  for (let i = context.messages.length - 1; i >= 0; i--) {
-    const message = context.messages[i];
-    if (message.role === 'user') {
-      return extractTextFromContent(message.content).trim();
-    }
-  }
-  return '';
-};
-
-export const getRecentConversationText = (
-  context: Context,
-  limit = 6,
-): string => {
-  return context.messages
-    .slice(-limit)
-    .map((message) => extractTextFromContent(message.content).trim())
-    .filter(Boolean)
-    .join('\n')
-    .toLowerCase();
-};
-
-export const countToolResults = (context: Context): number => {
-  return context.messages.filter((message) => message.role === 'toolResult')
-    .length;
-};
-
-export const countWords = (text: string): number => {
-  return text.split(/\s+/).filter(Boolean).length;
-};
-
-export const hasImageAttachment = (context: Context): boolean => {
-  return context.messages.some(
-    (message) =>
-      Array.isArray(message.content) &&
-      message.content.some((part) => part.type === 'image'),
-  );
-};
-
-export const containsAny = (text: string, keywords: string[]): boolean => {
-  return keywords.some((keyword) => text.includes(keyword));
-};
+/** The configured default preference order when no baseline tier is supplied. */
+export const BASELINE_TIER_ORDER: readonly RouterTier[] = [
+  'medium',
+  'high',
+  'low',
+  'micro',
+] as const;
 
 export const phaseForTier = (tier: RouterTier): RouterPhase => {
   if (tier === 'high') return 'planning';
@@ -78,404 +30,249 @@ export const phaseForTier = (tier: RouterTier): RouterPhase => {
   return 'lightweight';
 };
 
-export const resolveAvailableTier = (
-  profile: RouterProfile,
-  preferred: RouterTier,
-): RouterTier => {
-  if (profile[preferred]) return preferred;
-  // Fall "up": low → medium → high
-  const order: RouterTier[] = ['low', 'medium', 'high'];
-  const startIdx = order.indexOf(preferred);
-  for (let i = startIdx + 1; i < order.length; i++) {
-    if (profile[order[i]]) return order[i];
-  }
-  // Fall "down" as last resort
-  for (let i = startIdx - 1; i >= 0; i--) {
-    if (profile[order[i]]) return order[i];
-  }
-  return preferred; // unreachable if profile has ≥1 tier
-};
-
-export const buildRoutingDecision = (
-  profileName: string,
+export const resolveRoutePair = (
   profile: RouterProfile,
   tier: RouterTier,
-  phase: RouterPhase,
-  reasoning: string,
   thinkingOverrides?: RouterThinkingByTier,
-  isClassifier?: boolean,
-): RoutingDecision => {
+): RoutePair => {
   const routed = profile[tier];
-  if (!routed) {
-    throw new Error(
-      `Profile "${profileName}" has no configuration for the ${tier} tier.`,
-    );
-  }
+  if (!routed)
+    throw new Error('No eligible route: selected tier is not configured.');
   const { provider, modelId } = parseCanonicalModelRef(routed.model);
-  const baseThinking =
-    routed.thinking ??
-    (tier === 'high' ? 'high' : tier === 'low' ? 'low' : 'medium');
-  const effectiveThinking = thinkingOverrides?.[tier] ?? baseThinking;
-
   return {
-    profile: profileName,
     tier,
-    phase,
-    targetProvider: provider,
-    targetModelId: modelId,
-    targetLabel: routed.model,
-    reasoning,
-    thinking: effectiveThinking,
-    timestamp: Date.now(),
-    isClassifier,
+    model: `${provider}/${modelId}`,
+    thinking:
+      thinkingOverrides?.[tier] ??
+      routed.thinking ??
+      (tier === 'micro' ? 'off' : tier),
   };
 };
 
-export const decideRouting = (
-  context: Context,
-  profileName: string,
+/**
+ * Revalidate the actual target against the live registry. A configured effort
+ * declaration is restrictive: it can reject a route, but never grants a
+ * capability the live model does not expose.
+ */
+export const validateRoutePair = (
+  pair: RoutePair,
+  findModel: (provider: string, modelId: string) => Model<Api> | undefined,
+  imageAttached: boolean,
+  declaredLevels?: ModelDefinition['thinkingLevels'],
+): boolean => {
+  try {
+    const { provider, modelId } = parseCanonicalModelRef(pair.model);
+    if (provider === 'router') return false;
+    const model = findModel(provider, modelId);
+    return Boolean(
+      model?.input.includes(imageAttached ? 'image' : 'text') &&
+        getSupportedThinkingLevels(model).includes(pair.thinking) &&
+        (!declaredLevels ||
+          pair.thinking === 'off' ||
+          declaredLevels.includes(pair.thinking)),
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Return all generation attempts that the active profile can serve. The first
+ * route for a tier is its primary; subsequent routes are explicit generation
+ * fallbacks and remain in their configured order.
+ *
+ * Tier and fallback references are normalized before this boundary. Parse them
+ * directly so a canonical-looking model reference cannot resolve as an alias a
+ * second time.
+ */
+export const availableRoutePairs = (
   profile: RouterProfile,
-  previousDecision: RoutingDecision | undefined,
-  pinnedTier?: RouterTier,
+  findModel: (provider: string, modelId: string) => Model<Api> | undefined,
+  imageAttached: boolean,
   thinkingOverrides?: RouterThinkingByTier,
-  phaseBias = 0.5,
-  rules?: RoutingRule[],
-  isBudgetExceeded = false,
-): RoutingDecision => {
-  if (previousDecision?.profile !== profileName) previousDecision = undefined;
-  const prompt = getLastUserText(context).toLowerCase();
-  const recentConversation = getRecentConversationText(context);
-  const toolResultCount = countToolResults(context);
-  const wordCount = countWords(prompt);
-  const multiLinePrompt = prompt.split('\n').length >= 4;
+): RoutePair[] =>
+  ROUTER_TIERS.flatMap((tier) => {
+    const config = profile[tier];
+    if (!config) return [];
+
+    let primary: RoutePair;
+    try {
+      primary = resolveRoutePair(profile, tier, thinkingOverrides);
+    } catch {
+      return [];
+    }
 
-  const explicitHighHints = [
-    'best',
-    'deep',
-    'deeply',
-    'carefully',
-    'thoroughly',
-    'robust',
-    'comprehensive',
-    'step by step',
-    'think hard',
-    'highest quality',
-    'ultrathink',
-  ];
-  const explicitLowHints = [
-    'fast',
-    'cheap',
-    'quick',
-    'quickly',
-    'brief',
-    'briefly',
-    'one sentence',
-    'one line',
-    'tiny',
-    'small',
-  ];
-  const planningKeywords = [
-    'plan',
-    'planning',
-    'architecture',
-    'architect',
-    'design',
-    'tradeoff',
-    'trade-off',
-    'research',
-    'investigate',
-    'root cause',
-    'analyze',
-    'analysis',
-    'migration',
-    'strategy',
-    'compare',
-    'options',
-    'approach',
-  ];
-  const summaryKeywords = [
-    'summarize',
-    'summary',
-    'changelog',
-    'rewrite',
-    'reformat',
-    'format',
-    'rename',
-    'explain briefly',
-    'recap',
-    'tl;dr',
-  ];
-  const implementationKeywords = [
-    'implement',
-    'code',
-    'fix',
-    'update',
-    'edit',
-    'write',
-    'refactor',
-    'add tests',
-    'patch',
-    'change',
-    'apply',
-    'continue',
-    'resume',
-    'make the changes',
-    'go ahead',
-  ];
-  const lookupKeywords = [
-    'where is',
-    'which file',
-    'show me',
-    'list',
-    'what files',
-    'find',
-    'grep',
-  ];
+    return [primary.model, ...(config.fallbacks ?? [])]
+      .flatMap((ref, index) => {
+        try {
+          const { provider, modelId } = parseCanonicalModelRef(ref);
+          const model = findModel(provider, modelId);
+          const ownConfig =
+            index === 0 ? config : config.resolvedFallbacks?.[index - 1];
+          // A non-reasoning model defaults to off, but explicit unsupported
+          // effort remains ineligible.
+          const thinking =
+            thinkingOverrides?.[tier] ??
+            ((config.thinkingExplicit ?? config.thinking !== undefined)
+              ? primary.thinking
+              : ownConfig?.reasoning === false || !model?.reasoning
+                ? 'off'
+                : primary.thinking);
+          const pair = { tier, model: `${provider}/${modelId}`, thinking };
+          return validateRoutePair(
+            pair,
+            findModel,
+            imageAttached,
+            ownConfig?.reasoning === false
+              ? []
+              : index === 0
+                ? (config.thinkingLevels ?? config.resolvedThinkingLevels)
+                : ownConfig?.thinkingLevels,
+          )
+            ? [pair]
+            : [];
+        } catch {
+          return [];
+        }
+      })
+      .filter(
+        (pair, index, pairs) =>
+          pairs.findIndex((other) => other.model === pair.model) === index,
+      );
+  });
+
+/**
+ * Keep at least one configured route usable for each input kind when a
+ * thinking override is accepted. This prevents an override from silently
+ * removing all generation options while still allowing partial profiles and
+ * explicit pins to fail at their normal capability check.
+ */
+export const preservesRouteCoverage = (
+  profile: RouterProfile,
+  findModel: (provider: string, modelId: string) => Model<Api> | undefined,
+  thinkingOverrides: RouterThinkingByTier,
+): boolean => {
+  for (const imageAttached of [false, true]) {
+    const configured = availableRoutePairs(profile, findModel, imageAttached);
+    const overridden = availableRoutePairs(
+      profile,
+      findModel,
+      imageAttached,
+      thinkingOverrides,
+    );
+    if (configured.length > 0 && overridden.length === 0) return false;
+  }
+  return [false, true].some(
+    (imageAttached) =>
+      availableRoutePairs(profile, findModel, imageAttached, thinkingOverrides)
+        .length > 0,
+  );
+};
 
-  let phase: RouterPhase = previousDecision?.phase ?? 'implementation';
-  let tier: RouterTier = 'medium';
-  let reasoning = 'Defaulted to medium tier for general coding work.';
-  let isRuleMatched = false;
+export interface BaselineSelection {
+  pair: RoutePair;
+  reasonCode: 'baseline' | 'pinned' | 'budget';
+  isBudgetForced: boolean;
+}
 
-  if (pinnedTier) {
-    phase = phaseForTier(pinnedTier);
-    tier = pinnedTier;
-    reasoning = `Pinned to ${pinnedTier} tier via /router-pin.`;
-  } else {
-    // Check custom rules first
-    if (rules) {
-      let highestTier: RouterTier | undefined;
-      let winningRule: RoutingRule | undefined;
-      const tierRank: Record<RouterTier, number> = {
-        low: 1,
-        medium: 2,
-        high: 3,
-      };
+const routeForTier = (
+  pairs: readonly RoutePair[],
+  tier: RouterTier,
+): RoutePair | undefined => pairs.find((pair) => pair.tier === tier);
 
-      for (const rule of rules) {
-        const matches = Array.isArray(rule.matches)
-          ? rule.matches
-          : [rule.matches];
-        const lowercaseMatches = matches.map((m) => m.toLowerCase());
-        if (containsAny(prompt, lowercaseMatches)) {
-          if (!highestTier || tierRank[rule.tier] > tierRank[highestTier]) {
-            highestTier = rule.tier;
-            winningRule = rule;
-          }
-        }
-      }
+const preferredOrder = (profile: RouterProfile): readonly RouterTier[] => {
+  const baseline = profile.baselineTier;
+  if (!baseline || !profile[baseline]) return BASELINE_TIER_ORDER;
+  return [baseline, ...BASELINE_TIER_ORDER.filter((tier) => tier !== baseline)];
+};
 
-      if (winningRule && highestTier) {
-        tier = highestTier;
-        phase = phaseForTier(tier);
-        const matches = Array.isArray(winningRule.matches)
-          ? winningRule.matches
-          : [winningRule.matches];
-        reasoning =
-          winningRule.reason ??
-          `Matched custom routing rule for: ${matches.join(', ')}`;
-        isRuleMatched = true;
-      }
-    }
+const chooseFromOrder = (
+  pairs: readonly RoutePair[],
+  order: readonly RouterTier[],
+): RoutePair | undefined => {
+  for (const tier of order) {
+    const pair = routeForTier(pairs, tier);
+    if (pair) return pair;
+  }
+  return undefined;
+};
 
-    if (!isRuleMatched) {
-      // Sticky phase adjustments
-      const highThreshold = Math.max(
-        40,
-        120 - (previousDecision?.phase === 'planning' ? phaseBias * 80 : 0),
-      );
-      const lowThreshold = Math.max(
-        4,
-        12 -
-          (previousDecision?.phase === 'implementation' ||
-          previousDecision?.phase === 'planning'
-            ? phaseBias * 8
-            : 0),
+/**
+ * Select the local route without inspecting prompt text. Eligibility has
+ * already been filtered by the registry/input/effort boundary.
+ */
+export const selectBaselineRoute = (
+  profileName: string,
+  profile: RouterProfile,
+  pairs: readonly RoutePair[],
+  pinnedTier?: RouterTier,
+  isBudgetExceeded = false,
+): BaselineSelection => {
+  if (pinnedTier) {
+    const pair = routeForTier(pairs, pinnedTier);
+    if (!pair) {
+      throw new Error(
+        `Pinned tier "${pinnedTier}" for profile "${profileName}" has no eligible model for the current input and thinking level.`,
       );
-
-      if (containsAny(prompt, explicitHighHints)) {
-        phase = 'planning';
-        tier = 'high';
-        reasoning =
-          'Detected an explicit request for deeper or higher-quality reasoning.';
-      } else if (containsAny(prompt, explicitLowHints)) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning =
-          'Detected an explicit request for a faster or lighter response.';
-      } else if (containsAny(prompt, summaryKeywords)) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning = 'Detected summary or lightweight transformation keywords.';
-      } else if (
-        containsAny(prompt, planningKeywords) ||
-        prompt.startsWith('why ') ||
-        wordCount >= highThreshold ||
-        multiLinePrompt
-      ) {
-        phase = 'planning';
-        tier = 'high';
-        reasoning =
-          previousDecision?.phase === 'planning'
-            ? 'Continued planning phase based on complexity or keywords.'
-            : 'Detected planning, broad analysis, or a high-complexity request.';
-      } else if (containsAny(prompt, implementationKeywords)) {
-        phase = 'implementation';
-        tier = 'medium';
-        reasoning =
-          'Detected implementation-oriented work with bounded execution scope.';
-      } else if (
-        containsAny(prompt, lookupKeywords) &&
-        wordCount <= 24 &&
-        toolResultCount === 0
-      ) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning = 'Detected a short read-only lookup request.';
-      } else if (
-        previousDecision?.phase === 'planning' &&
-        toolResultCount === 0 &&
-        wordCount > lowThreshold
-      ) {
-        phase = 'planning';
-        tier = 'high';
-        reasoning =
-          'Kept the planning-phase bias because the conversation still looks exploratory.';
-      } else if (
-        toolResultCount > 0 ||
-        previousDecision?.phase === 'implementation' ||
-        recentConversation.includes('plan:')
-      ) {
-        phase = 'implementation';
-        tier = 'medium';
-        reasoning =
-          'Detected active implementation work from prior tools or recent plan execution context.';
-      } else if (wordCount <= lowThreshold) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning = 'Detected a short bounded request.';
-      }
     }
+    return { pair, reasonCode: 'pinned', isBudgetForced: false };
   }
 
-  let isBudgetForced = false;
-  if (isBudgetExceeded && tier === 'high') {
-    tier = 'medium';
-    phase = 'implementation';
-    reasoning = `Budget exceeded. Downgraded from high to medium tier. (Original: ${reasoning})`;
-    isBudgetForced = true;
-  }
-
-  // Resolve to nearest available tier if the selected tier is disabled
-  const resolvedTier =
-    isBudgetForced && !profile.medium && profile.low
-      ? 'low'
-      : resolveAvailableTier(profile, tier);
-  if (resolvedTier !== tier) {
-    reasoning = `Resolved from ${tier} to ${resolvedTier} tier (${tier} tier is not configured). Original: ${reasoning}`;
-    phase = phaseForTier(resolvedTier);
-    tier = resolvedTier;
+  const order = preferredOrder(profile);
+  if (isBudgetExceeded) {
+    const budgetOrder = order.filter(
+      (tier) => tier === 'medium' || tier === 'low' || tier === 'micro',
+    );
+    const budgetPair = chooseFromOrder(pairs, budgetOrder);
+    if (budgetPair) {
+      return { pair: budgetPair, reasonCode: 'budget', isBudgetForced: true };
+    }
+    const configuredBaseline = chooseFromOrder(pairs, order);
+    if (configuredBaseline) {
+      return {
+        pair: configuredBaseline,
+        reasonCode: 'budget',
+        isBudgetForced: false,
+      };
+    }
+  } else {
+    const baseline = chooseFromOrder(pairs, order);
+    if (baseline)
+      return { pair: baseline, reasonCode: 'baseline', isBudgetForced: false };
   }
 
-  const decision = buildRoutingDecision(
-    profileName,
-    profile,
-    tier,
-    phase,
-    reasoning,
-    thinkingOverrides,
-    false,
+  throw new Error(
+    `No eligible route for profile "${profileName}": no configured model is available for the current input and thinking level.`,
   );
-  decision.isRuleMatched = isRuleMatched;
-  decision.isBudgetForced = isBudgetForced;
-  return decision;
 };
 
-export const runClassifier = async (
-  classifierModelRef: string,
-  modelRegistry: ExtensionContext['modelRegistry'],
-  context: Context,
-  currentPhase?: RouterPhase,
-  thinking?: ThinkingLevel,
-  signal?: AbortSignal,
-): Promise<{ tier: RouterTier; reasoning: string } | undefined> => {
-  try {
-    const { provider, modelId } = parseCanonicalModelRef(classifierModelRef);
-    const model = modelRegistry.find(provider, modelId);
-    if (!model || provider === 'router') return undefined;
-    signal?.throwIfAborted();
-
-    const promptText = getLastUserText(context);
-    const historyText = getRecentConversationText(context, 4);
-
-    const classifierPrompt = `You are a model router classifier. Your job is to categorize the user's latest request into one of three tiers: "high", "medium", or "low".
-
-Tiers:
-- high: Architecture, design, planning, tradeoff analysis, broad debugging, large refactors, codebase research.
-- medium: Implementation of a known plan, multi-file edits, normal coding work, focused debugging, tests/fixes.
-- low: Summaries, changelogs, formatting, quick explanations, small bounded transforms, simple read-only lookup.
-
-${currentPhase ? `Current conversation phase: ${currentPhase}\n` : ''}
-Recent history:
-${historyText}
-
-Latest user message:
-${promptText}
-
-Return your decision in exactly two lines:
-Tier: [high|medium|low]
-Reasoning: [one short sentence]
-
-${currentPhase === 'planning' ? 'Consider that the conversation is currently in a planning phase. Bias toward "high" unless the request is clearly a simple implementation or summary.' : ''}
-${currentPhase === 'implementation' ? 'Consider that the conversation is currently in an implementation phase. Bias toward "medium" unless the request is clearly planning or a simple summary.' : ''}`;
-
-    const classifierContext: Context = {
-      messages: [
-        { role: 'user', content: classifierPrompt, timestamp: Date.now() },
-      ],
-    };
-
-    const reasoningOption =
-      model.reasoning && thinking && thinking !== 'off' ? thinking : undefined;
-
-    const timeout = AbortSignal.timeout(10_000);
-    const stream = modelRegistry.streamSimple(model, classifierContext, {
-      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
-      maxTokens: 256,
-      ...(reasoningOption ? { reasoning: reasoningOption } : {}),
-    });
-    let fullText = '';
-    let completed = false;
-    for await (const event of stream) {
-      if (event.type === 'error') return undefined;
-      if (event.type === 'text_delta') fullText += event.delta;
-      if (event.type === 'done') {
-        completed = true;
-        fullText = extractTextFromContent(event.message.content);
-        break;
-      }
-    }
-    if (!completed) return undefined;
-
-    const lines = fullText.trim().split('\n');
-    const tierLine = lines.find((l) => l.toLowerCase().startsWith('tier:'));
-    const reasoningLine = lines.find((l) =>
-      l.toLowerCase().startsWith('reasoning:'),
+export const primaryRoutePairs = (
+  profile: RouterProfile,
+  pairs: readonly RoutePair[],
+): RoutePair[] =>
+  BASELINE_TIER_ORDER.flatMap((tier) => {
+    // Keep the effective effort already validated against the live registry.
+    const primary = pairs.find(
+      (pair) => pair.tier === tier && pair.model === profile[tier]?.model,
     );
+    return primary ? [primary] : [];
+  });
 
-    if (tierLine) {
-      const tierValue = tierLine.split(':')[1].trim().toLowerCase();
-      if (isRouterTier(tierValue)) {
-        return {
-          tier: tierValue,
-          reasoning: reasoningLine
-            ? reasoningLine.slice(reasoningLine.indexOf(':') + 1).trim()
-            : 'Classifier decision.',
-        };
-      }
-    }
-  } catch {
-    // Ignore classifier errors and fall back to heuristics
-  }
-  return undefined;
+export const decisionForPair = (
+  profile: string,
+  pair: RoutePair,
+  reasonCode: RoutingReasonCode,
+): RoutingDecision => {
+  const { provider, modelId } = parseCanonicalModelRef(pair.model);
+  return {
+    profile,
+    tier: pair.tier,
+    phase: phaseForTier(pair.tier),
+    targetProvider: provider,
+    targetModelId: modelId,
+    targetLabel: pair.model,
+    thinking: pair.thinking,
+    reasonCode,
+    timestamp: Date.now(),
+  };
 };