@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/ruvector/model-prices.d.ts

@@ -0,0 +1,50 @@
+/**
+ * model-prices.ts — Single source of truth for per-model pricing.
+ *
+ * Iter 31 — Previously the price table existed in three scripts (train-
+ * bundled-krr.mjs, auto-retrain-router.mjs, calibration-check.mjs) AND was
+ * derived from the openrouter-alts.json sidecar for the bundled list. As
+ * cost-aware features land (trajectory outcomes, cost-savings observability,
+ * cost-ceiling routing), they need ONE canonical price lookup. This module
+ * is it.
+ *
+ * Prices are blended ($/Mtok) using a 1×input + 3×output mix, reflecting
+ * the average input/output token ratio for code tasks. To compute spend
+ * for a specific call:
+ *
+ *   const usd = costUsd(modelId, inputTokens, outputTokens);
+ *
+ * Unknown model ids fall back to a conservative $1/Mtok blended estimate
+ * so callers always get a number (cost-tracking doesn't silently drop).
+ *
+ * Source: OpenRouter price page snapshot, ADR-149 bench dates.
+ *
+ * @module model-prices
+ */
+/** Per-million-token input and output prices ($USD). */
+export interface ModelPrice {
+    in: number;
+    out: number;
+}
+/**
+ * Curated price table. Keys are concrete model ids matching either
+ * OpenRouter slugs or Anthropic SDK ids that the cost-optimal router can
+ * choose. New models added via the registry sidecar should be reflected
+ * here AS THEY ARE ADDED (no auto-sync); see ADR-149.
+ */
+export declare const MODEL_PRICES: Record<string, ModelPrice>;
+/**
+ * Blended $/Mtok using the 1× input + 3× output ratio. Used by the KRR
+ * trainer (scripts/train-bundled-krr.mjs and others) as the cost feature
+ * the cost-optimal selector divides quality by.
+ */
+export declare function blendedPrice(modelId: string): number;
+/**
+ * Compute USD spend for a single call. Cost = (input × $/Mtok_in +
+ * output × $/Mtok_out) / 1_000_000.
+ *
+ * Returns 0 on missing usage and falls back to a conservative blended
+ * estimate when the model is unknown — never returns undefined.
+ */
+export declare function costUsd(modelId: string | undefined, inputTokens: number | undefined, outputTokens: number | undefined): number;
+//# sourceMappingURL=model-prices.d.ts.map

package/dist/src/ruvector/model-prices.js

@@ -0,0 +1,72 @@
+/**
+ * model-prices.ts — Single source of truth for per-model pricing.
+ *
+ * Iter 31 — Previously the price table existed in three scripts (train-
+ * bundled-krr.mjs, auto-retrain-router.mjs, calibration-check.mjs) AND was
+ * derived from the openrouter-alts.json sidecar for the bundled list. As
+ * cost-aware features land (trajectory outcomes, cost-savings observability,
+ * cost-ceiling routing), they need ONE canonical price lookup. This module
+ * is it.
+ *
+ * Prices are blended ($/Mtok) using a 1×input + 3×output mix, reflecting
+ * the average input/output token ratio for code tasks. To compute spend
+ * for a specific call:
+ *
+ *   const usd = costUsd(modelId, inputTokens, outputTokens);
+ *
+ * Unknown model ids fall back to a conservative $1/Mtok blended estimate
+ * so callers always get a number (cost-tracking doesn't silently drop).
+ *
+ * Source: OpenRouter price page snapshot, ADR-149 bench dates.
+ *
+ * @module model-prices
+ */
+/**
+ * Curated price table. Keys are concrete model ids matching either
+ * OpenRouter slugs or Anthropic SDK ids that the cost-optimal router can
+ * choose. New models added via the registry sidecar should be reflected
+ * here AS THEY ARE ADDED (no auto-sync); see ADR-149.
+ */
+export const MODEL_PRICES = {
+    // Cheap tier
+    'inclusionai/ling-2.6-flash': { in: 0.01, out: 0.03 },
+    'google/gemini-2.5-flash-lite': { in: 0.10, out: 0.40 },
+    'meta-llama/llama-3.3-70b-instruct': { in: 0.13, out: 0.40 },
+    // Mid tier
+    'anthropic/claude-haiku-4.5': { in: 1.00, out: 5.00 },
+    'openai/gpt-4.1': { in: 2.00, out: 8.00 },
+    // Strong tier
+    'anthropic/claude-sonnet-4-6': { in: 3.00, out: 15.00 },
+    'anthropic/claude-opus-4': { in: 15.00, out: 75.00 },
+    // Tier-label fallbacks (when the trajectory only carries a coarse tier
+    // and not a concrete modelId — happens before iter 13 wiring landed).
+    haiku: { in: 1.00, out: 5.00 },
+    sonnet: { in: 3.00, out: 15.00 },
+    opus: { in: 15.00, out: 75.00 },
+    inherit: { in: 3.00, out: 15.00 },
+};
+/**
+ * Blended $/Mtok using the 1× input + 3× output ratio. Used by the KRR
+ * trainer (scripts/train-bundled-krr.mjs and others) as the cost feature
+ * the cost-optimal selector divides quality by.
+ */
+export function blendedPrice(modelId) {
+    const p = MODEL_PRICES[modelId] ?? { in: 1.0, out: 1.0 };
+    return p.in + 3 * p.out;
+}
+/**
+ * Compute USD spend for a single call. Cost = (input × $/Mtok_in +
+ * output × $/Mtok_out) / 1_000_000.
+ *
+ * Returns 0 on missing usage and falls back to a conservative blended
+ * estimate when the model is unknown — never returns undefined.
+ */
+export function costUsd(modelId, inputTokens, outputTokens) {
+    if (!inputTokens && !outputTokens)
+        return 0;
+    const p = (modelId ? MODEL_PRICES[modelId] : undefined) ?? { in: 1.0, out: 1.0 };
+    const inT = inputTokens ?? 0;
+    const outT = outputTokens ?? 0;
+    return (inT * p.in + outT * p.out) / 1_000_000;
+}
+//# sourceMappingURL=model-prices.js.map

package/dist/src/ruvector/model-router.d.ts

@@ -0,0 +1,408 @@
+/**
+ * Intelligent Model Router — lexical complexity heuristic + Thompson bandit
+ *
+ * Dynamically routes requests to the optimal Claude model (haiku/sonnet/opus)
+ * based on task complexity, uncertainty, and online-learned routing outcomes.
+ *
+ * Mechanism (shipped):
+ * - Complexity score = blend of lexical, semantic-depth, task-scope, and
+ *   uncertainty heuristics (see `computeLexicalComplexity` and friends).
+ *   Pure JS arithmetic — no model load, no tensor math.
+ * - Model selection = Thompson-sampling Beta-Bernoulli bandit with
+ *   complexity-bucketed Beta(α,β) priors, persisted to
+ *   `.swarm/model-router-state.json` and updated by `recordOutcome` after
+ *   each routing decision.
+ * - Uncertainty quantification + a circuit breaker drive escalation when
+ *   the bandit's confidence is low or downstream failures are observed.
+ *
+ * Routing Strategy:
+ * - Haiku: high confidence, low complexity (fast, cheap)
+ * - Sonnet: medium confidence, moderate complexity (balanced)
+ * - Opus: low confidence, high complexity (most capable)
+ *
+ * Note (#2329): An earlier design (ADR-026 + this file's previous header)
+ * described a Tiny-Dancer / FastGRNN neural router with embedding-based
+ * complexity scoring. That path was never wired in directly.
+ *
+ * Note (ADR-148, #2334): The cost-optimal neural router is now wired as an
+ * optional, gated addition via `./neural-router.ts` (which uses
+ * `@metaharness/router`, optionally accelerated by `@ruvector/tiny-dancer`).
+ * It is double-gated on `CLAUDE_FLOW_ROUTER_NEURAL=1` + an embedding being
+ * supplied + a corpus/artifact being loadable. When any gate is closed the
+ * shipped heuristic + bandit path runs unchanged and the result carries
+ * `routedBy: 'heuristic'` (default) or `'bandit-fallback'` (neural enabled
+ * but declined). When all gates are open and a backend resolves, the result
+ * carries `routedBy: 'metaharness-knn' | 'metaharness-krr' | 'fastgrnn'`.
+ *
+ * @module model-router
+ */
+/**
+ * Available Claude models for routing
+ */
+export type ClaudeModel = 'haiku' | 'sonnet' | 'opus' | 'inherit';
+/**
+ * Model capabilities and characteristics
+ */
+export declare const MODEL_CAPABILITIES: Record<ClaudeModel, {
+    maxComplexity: number;
+    costMultiplier: number;
+    speedMultiplier: number;
+    description: string;
+}>;
+/**
+ * Complexity indicators for task classification
+ */
+export declare const COMPLEXITY_INDICATORS: {
+    high: string[];
+    medium: string[];
+    low: string[];
+};
+/**
+ * Model router configuration
+ */
+export interface ModelRouterConfig {
+    /** Confidence threshold for model selection (default: 0.85) */
+    confidenceThreshold: number;
+    /** Maximum uncertainty before escalating (default: 0.15) */
+    maxUncertainty: number;
+    /** Enable circuit breaker (default: true) */
+    enableCircuitBreaker: boolean;
+    /** Failures before circuit opens (default: 5) */
+    circuitBreakerThreshold: number;
+    /** Path for router state persistence */
+    statePath: string;
+    /** Auto-save interval in decisions (default: 20) */
+    autoSaveInterval: number;
+    /** Enable cost optimization (default: true) */
+    enableCostOptimization: boolean;
+    /** Prefer faster models when confidence is high (default: true) */
+    preferSpeed: boolean;
+}
+/**
+ * Routing decision result
+ */
+export interface ModelRoutingResult {
+    /** Selected model */
+    model: ClaudeModel;
+    /** Confidence in the decision (0-1) */
+    confidence: number;
+    /** Uncertainty estimate (0-1) */
+    uncertainty: number;
+    /** Computed complexity score (0-1) */
+    complexity: number;
+    /** Reasoning for the selection */
+    reasoning: string;
+    /** Alternative models considered */
+    alternatives: Array<{
+        model: ClaudeModel;
+        score: number;
+    }>;
+    /** Inference time in microseconds */
+    inferenceTimeUs: number;
+    /** Estimated cost multiplier */
+    costMultiplier: number;
+    /**
+     * Which decision mechanism produced this result (ADR-148 / ADR-074 —
+     * observable, not inferred). Always one of:
+     *   'heuristic'        — neural disabled (default). Pure Thompson bandit.
+     *   'bandit-fallback'  — neural enabled but returned no decision (load fail).
+     *   'hybrid'           — neural enabled AND returned predictions; the
+     *                        bandit's Beta(α,β) priors were perturbed by the
+     *                        neural's predicted quality before sampling.
+     */
+    routedBy: 'hybrid' | 'bandit-fallback' | 'heuristic';
+    /**
+     * The neural backend that contributed to a `hybrid` decision, if any.
+     * Absent on `heuristic` and `bandit-fallback`. Tracked separately from
+     * `routedBy` so the decision mechanism and the model identity remain
+     * distinct observable surfaces.
+     */
+    neuralBackend?: 'metaharness-knn' | 'metaharness-krr' | 'fastgrnn';
+    /**
+     * Execution provider hint (ADR-148 phase 2). 'anthropic' = default
+     * Anthropic API path (MODEL_MAP). 'openrouter' = call through
+     * OpenRouter using `openrouterModel`. Resolved per-call from
+     * `CLAUDE_FLOW_ROUTER_PROVIDER` / `OPENROUTER_API_KEY`.
+     */
+    provider?: 'anthropic' | 'openrouter';
+    /**
+     * Concrete OpenRouter model slug for this tier when `provider==='openrouter'`,
+     * loaded from `assets/model-router/openrouter-alts.json` (overridable via
+     * `CLAUDE_FLOW_ROUTER_OPENROUTER_ALTS=<path>`). Downstream consumers can
+     * use this to override the default MODEL_MAP-derived Anthropic slug.
+     */
+    openrouterModel?: string;
+    /**
+     * ADR-149 — concrete picked model id (e.g. `openai/gpt-4.1`,
+     * `inclusionai/ling-2.6-flash`, `anthropic/claude-sonnet-4-6`). Set when
+     * the neural backend returned a per-model pick. The `model` field above
+     * remains the tier label for back-compat with Anthropic-API consumers
+     * that map tier → MODEL_MAP id.
+     */
+    modelId?: string;
+}
+/**
+ * Complexity analysis result
+ */
+export interface ComplexityAnalysis {
+    /** Overall complexity score (0-1) */
+    score: number;
+    /** Indicators found */
+    indicators: {
+        high: string[];
+        medium: string[];
+        low: string[];
+    };
+    /** Feature breakdown */
+    features: {
+        lexicalComplexity: number;
+        semanticDepth: number;
+        taskScope: number;
+        uncertaintyLevel: number;
+    };
+}
+/**
+ * Beta(α, β) prior for Thompson sampling. Each model carries one of these;
+ * outcomes update α (successes) and β (failures) so the router auto-balances
+ * cost/quality without manual threshold tuning. See ADR-101.
+ */
+export interface BetaPrior {
+    alpha: number;
+    beta: number;
+}
+/**
+ * Router state for persistence
+ */
+/**
+ * Complexity bucket for per-task bandit priors. Bands mirror
+ * MODEL_CAPABILITIES.maxComplexity (haiku 0.4, sonnet 0.7) so the taxonomy
+ * isn't arbitrary. Keying priors by bucket fixes the global-bandit defect where
+ * failures on one task type suppressed a model for ALL task types (audit
+ * docs/reviews/intelligence-system-audit-2026-05-29.md; see ADR-142).
+ */
+export type ComplexityBucket = 'low' | 'med' | 'high';
+declare function complexityBucket(score: number): ComplexityBucket;
+type BucketedPriors = Record<ComplexityBucket, Record<ClaudeModel, BetaPrior>>;
+/**
+ * ADR-149 — per-modelId Beta priors, keyed by complexity bucket. Shadow
+ * state that accumulates from recordOutcomeByModelId() so the bandit can
+ * distinguish e.g. `inclusionai/ling-2.6-flash` from
+ * `anthropic/claude-haiku-4-5-20251001` even though both collapse to the
+ * `haiku` tier in BucketedPriors. Selection still uses BucketedPriors;
+ * a future refactor switches to BucketedPriorsById when it has enough
+ * data to be trustworthy.
+ */
+type BucketedPriorsById = Record<ComplexityBucket, Record<string, BetaPrior>>;
+/**
+ * Sample θ ~ Beta(α, β) via the identity Beta(α,β) = X / (X+Y) where
+ * X ~ Gamma(α), Y ~ Gamma(β). Returns the mean for degenerate α+β=0
+ * (shouldn't happen in practice but defensive).
+ */
+export declare function sampleBeta(alpha: number, beta: number): number;
+/**
+ * Intelligent Model Router using complexity-based routing
+ */
+export declare class ModelRouter {
+    private config;
+    private state;
+    private decisionCount;
+    private consecutiveFailures;
+    /**
+     * ADR-148 — in-memory counters surfaced via `getStats()` and read by the
+     * `hooks_intelligence_stats` MCP tool. Process-local, not persisted (these
+     * are operational metrics, not authoritative state — see ADR-074/086).
+     */
+    private routedByCounts;
+    private neuralBackendCounts;
+    private abDisagreements;
+    private abComparisons;
+    constructor(config?: Partial<ModelRouterConfig>);
+    /**
+     * Route a task to the optimal model.
+     *
+     * When `embedding` is supplied and `CLAUDE_FLOW_ROUTER_NEURAL=1` is set,
+     * the cost-optimal neural backend (ADR-148) is consulted first; its
+     * decision is used when its `metBar` clears the configured quality bar
+     * and `routedBy` reflects which backend produced the decision. Otherwise
+     * the shipped heuristic + Thompson bandit path runs (byte-identical to
+     * the pre-ADR-148 behavior) and the result carries `routedBy:
+     * 'bandit-fallback'` (neural was enabled but declined) or
+     * `'heuristic'` (neural was disabled).
+     */
+    route(task: string, embedding?: number[]): Promise<ModelRoutingResult>;
+    /**
+     * Analyze task complexity
+     */
+    analyzeComplexity(task: string, embedding?: number[]): ComplexityAnalysis;
+    /**
+     * Compute lexical complexity from text features
+     */
+    private computeLexicalComplexity;
+    /**
+     * Compute semantic depth from indicators and embedding
+     */
+    private computeSemanticDepth;
+    /**
+     * Compute task scope from content analysis
+     */
+    private computeTaskScope;
+    /**
+     * Compute uncertainty level from task phrasing
+     */
+    private computeUncertaintyLevel;
+    /**
+     * Compute scores for each model
+     */
+    private computeModelScores;
+    /**
+     * Apply circuit breaker adjustments
+     */
+    private applyCircuitBreaker;
+    /**
+     * Select the best model from scores. Uses Thompson sampling (#1772):
+     * each model's deterministic complexity score is multiplied by a draw
+     * θ_m ~ Beta(α_m, β_m) from its bandit prior. Models with strong empirical
+     * track records get sampled higher; models with poor outcomes get sampled
+     * lower; the system auto-corrects against tier overuse without manual
+     * threshold tuning. Beta(1,1) = uniform on cold start so behavior matches
+     * the prior deterministic router until outcomes accumulate.
+     */
+    private selectModel;
+    /**
+     * Build human-readable reasoning
+     */
+    private buildReasoning;
+    /**
+     * Track routing decision for learning
+     */
+    private trackDecision;
+    /**
+     * Record outcome for learning
+     */
+    recordOutcome(task: string, model: ClaudeModel, outcome: 'success' | 'failure' | 'escalated'): void;
+    /**
+     * ADR-149 — record an outcome keyed by the CONCRETE model id (e.g.
+     * 'inclusionai/ling-2.6-flash') rather than the tier label. Updates the
+     * shadow `priorsById` state without affecting `priors` (tier priors).
+     *
+     * This is the per-model learning signal the bandit needs to eventually
+     * distinguish GPT-4.1 from Sonnet within the 'sonnet' tier. Selection
+     * currently still uses tier priors; this state accumulates so a future
+     * refactor can switch the selector over once there's enough data.
+     *
+     * Cost-adjusted reward semantics: cheap models get the highest reward on
+     * success (their successes are most cost-efficient). We map modelId to
+     * its closest tier for the reward table — the routing math doesn't have
+     * a per-modelId reward configuration yet.
+     */
+    recordOutcomeByModelId(task: string, modelId: string, outcome: 'success' | 'failure' | 'escalated'): void;
+    /**
+     * Get router statistics
+     */
+    getStats(): {
+        totalDecisions: number;
+        modelDistribution: Record<ClaudeModel, number>;
+        avgComplexity: number;
+        avgConfidence: number;
+        circuitBreakerTrips: number;
+        consecutiveFailures: Record<ClaudeModel, number>;
+        /** ADR-148: per-decision-mechanism counts (process-local, not persisted). */
+        routedByCounts: Record<ModelRoutingResult['routedBy'], number>;
+        /** ADR-148: per-neural-backend counts (process-local). */
+        neuralBackendCounts: Record<NonNullable<ModelRoutingResult['neuralBackend']>, number>;
+        /** ADR-148: A/B mode disagreement rate over the active process. */
+        ab: {
+            comparisons: number;
+            disagreements: number;
+            disagreementRate: number;
+        };
+        /**
+         * ADR-149: state schema version. 2 = bucketed tier priors only; 3 = also
+         * carries `priorsById` shadow state. Bumps on first recordOutcomeByModelId().
+         */
+        stateVersion: number;
+        /**
+         * ADR-149: per-modelId Beta priors per complexity bucket. Empty until
+         * recordOutcomeByModelId() fires. NOT consumed by selectModel() yet; this
+         * is shadow state for a future selection-by-modelId refactor.
+         */
+        priorsById?: BucketedPriorsById;
+    };
+    /**
+     * Load state from disk
+     */
+    private loadState;
+    /**
+     * Save state to disk
+     */
+    private saveState;
+    /**
+     * Reset router state
+     */
+    reset(): void;
+    /**
+     * Public read-only accessor for the bandit priors. Useful for tests,
+     * dashboards, and the pending hooks_intelligence_stats integration that
+     * surfaces convergence in the dashboard. Returns a copy.
+     */
+    getBanditPriors(bucket?: ComplexityBucket): Record<ClaudeModel, BetaPrior>;
+    /** All bucketed priors (copy) — for dashboards/tests. */
+    getBucketedPriors(): BucketedPriors;
+}
+/**
+ * Get or create the singleton ModelRouter instance
+ */
+export declare function getModelRouter(config?: Partial<ModelRouterConfig>): ModelRouter;
+/**
+ * Reset the singleton instance
+ */
+export declare function resetModelRouter(): void;
+/**
+ * Create a new ModelRouter instance (non-singleton)
+ */
+export declare function createModelRouter(config?: Partial<ModelRouterConfig>): ModelRouter;
+/**
+ * Quick route function for common use case
+ */
+export declare function routeToModel(task: string): Promise<ClaudeModel>;
+/**
+ * Route with full result
+ */
+export declare function routeToModelFull(task: string, embedding?: number[]): Promise<ModelRoutingResult>;
+/**
+ * Analyze task complexity without routing
+ */
+export declare function analyzeTaskComplexity(task: string): ComplexityAnalysis;
+/**
+ * Get model router statistics
+ */
+export declare function getModelRouterStats(): ReturnType<ModelRouter['getStats']>;
+/**
+ * Record routing outcome for learning
+ */
+export declare function recordModelOutcome(task: string, model: ClaudeModel, outcome: 'success' | 'failure' | 'escalated'): void;
+/**
+ * ADR-149 — record an outcome keyed by the concrete model id rather than
+ * the tier label. Updates the shadow `priorsById` state. Selection logic
+ * still uses tier priors; this data accumulates for a future per-modelId
+ * selector refactor.
+ *
+ * Safe to call alongside `recordModelOutcome` — they update independent
+ * state slices so double-counting is impossible.
+ */
+export declare function recordModelOutcomeByModelId(task: string, modelId: string, outcome: 'success' | 'failure' | 'escalated'): void;
+/**
+ * ADR-149 iter 14 — read-only access to the per-modelId Beta priors. The
+ * neural-router consumes this to apply per-model Thompson sampling on top
+ * of its predicted-quality vector when CLAUDE_FLOW_ROUTER_BANDIT_PER_MODEL=1.
+ * Returns the legacy bucketed priors (`priorsById[bucket][modelId]`) when
+ * present, else null.
+ */
+export declare function getModelRouterPriorsById(): Record<ComplexityBucket, Record<string, BetaPrior>> | null;
+/**
+ * Re-export the complexity-bucket helper so the neural-router (which gets
+ * the task text via the route() call) can map a complexity score to the
+ * matching bandit bucket.
+ */
+export { complexityBucket };
+//# sourceMappingURL=model-router.d.ts.map