agentic-qe 3.7.21 → 3.8.0

package/dist/routing/index.d.ts

@@ -18,8 +18,10 @@ export type { SignalSource, RoutingSignal, MergedAgentScore, SignalMergerConfig,
 export { RoutingFeedbackCollector, createRoutingFeedbackCollector, } from './routing-feedback.js';
 export { classifyTask, isSimpleTask, requiresOpus, getRecommendedModel, getComplexityScore, COMPLEX_DOMAINS, MODERATE_DOMAINS, COMPLEX_CAPABILITIES, COMPLEXITY_THRESHOLDS, COMPLEXITY_TO_MODEL, } from './task-classifier.js';
 export type { TaskComplexity, ClaudeModel, ComplexityFactor, ClassificationResult, ClassifiableTask, } from './task-classifier.js';
-export { TinyDancerRouter, createTinyDancerRouter, } from './tiny-dancer-router.js';
-export type { RouteResult, TinyDancerConfig, RoutingOutcome as TinyDancerRoutingOutcome, RouterStats, } from './tiny-dancer-router.js';
+export { TinyDancerRouter, createTinyDancerRouter, createSmartTinyDancerRouter, } from './tiny-dancer-router.js';
+export type { ITaskRouter, RouteResult, TinyDancerConfig, RoutingOutcome as TinyDancerRoutingOutcome, RouterStats, } from './tiny-dancer-router.js';
+export { NeuralTinyDancerRouter, SimpleNeuralRouter, createNeuralTinyDancerRouter, } from './neural-tiny-dancer-router.js';
+export type { NeuralTinyDancerConfig, ShadowDecisionLog, NeuralRouterStats, EmpiricalConfidenceBounds, ConformalBounds, } from './neural-tiny-dancer-router.js';
 export { DEFAULT_ROUTING_CONFIG, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_TIER_MAPPING, DEFAULT_COST_OPTIMIZATION, DEFAULT_FALLBACK_CONFIG, loadRoutingConfigFromEnv, mapComplexityToTier, getNextFallbackTier, tierToModel, estimateTaskCost, validateRoutingConfig, } from './routing-config.js';
 export type { AgentTier, ConfidenceThresholds, ComplexityTierMapping, CostOptimizationConfig, FallbackConfig, RoutingConfig, } from './routing-config.js';
 export { parseDependenciesFromFrontmatter, buildDependencyGraph, createSpawnPlan, getAgentDependencies, } from './agent-dependency-graph.js';

package/dist/routing/index.js

@@ -21,7 +21,9 @@ export { RoutingFeedbackCollector, createRoutingFeedbackCollector, } from './rou
 // Task Classifier (TD-002)
 export { classifyTask, isSimpleTask, requiresOpus, getRecommendedModel, getComplexityScore, COMPLEX_DOMAINS, MODERATE_DOMAINS, COMPLEX_CAPABILITIES, COMPLEXITY_THRESHOLDS, COMPLEXITY_TO_MODEL, } from './task-classifier.js';
 // TinyDancer Router (TD-003)
-export { TinyDancerRouter, createTinyDancerRouter, } from './tiny-dancer-router.js';
+export { TinyDancerRouter, createTinyDancerRouter, createSmartTinyDancerRouter, } from './tiny-dancer-router.js';
+// Neural TinyDancer Router (ADR-082)
+export { NeuralTinyDancerRouter, SimpleNeuralRouter, createNeuralTinyDancerRouter, } from './neural-tiny-dancer-router.js';
 // Routing Configuration (TD-004)
 export { DEFAULT_ROUTING_CONFIG, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_TIER_MAPPING, DEFAULT_COST_OPTIMIZATION, DEFAULT_FALLBACK_CONFIG, loadRoutingConfigFromEnv, mapComplexityToTier, getNextFallbackTier, tierToModel, estimateTaskCost, validateRoutingConfig, } from './routing-config.js';
 // Agent Dependency Graph (Issue #342 Item 2)

package/dist/routing/neural-tiny-dancer-router.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Neural TinyDancer Router - ADR-082
+ * Neural Model Routing via FastGRNN-style Network
+ *
+ * Replaces rule-based complexity thresholds with a lightweight neural network
+ * for routing decisions. Implements shadow mode for safe rollout, circuit
+ * breaker for reliability, and online learning from outcome feedback.
+ *
+ * Design:
+ * - Input features: [complexityScore, tokenEstimate, domainIndex, historicalSuccessRate]
+ * - Hidden layer: 32 units with ReLU activation
+ * - Output: softmax probability distribution over [Tier1/haiku, Tier2/sonnet, Tier3/opus]
+ * - Shadow mode: first 1000 decisions run both routers, tracks disagreement
+ * - Circuit breaker: falls back to rule-based if error rate exceeds threshold
+ *
+ * @module routing/neural-tiny-dancer-router
+ */
+import type { QETask } from './types.js';
+import { type ClassifiableTask, type ClaudeModel, type ClassificationResult } from './task-classifier.js';
+import { TinyDancerRouter, type RouteResult, type TinyDancerConfig } from './tiny-dancer-router.js';
+export { SimpleNeuralRouter } from './simple-neural-router.js';
+import { SimpleNeuralRouter } from './simple-neural-router.js';
+/**
+ * Neural router configuration extending TinyDancerConfig
+ */
+export interface NeuralTinyDancerConfig extends TinyDancerConfig {
+    /** Circuit breaker error rate threshold (default: 0.20) */
+    circuitBreakerThreshold?: number;
+    /** Learning rate for weight updates (default: 0.01) */
+    learningRate?: number;
+    /** Force shadow mode on/off (undefined = auto) */
+    forceShadowMode?: boolean;
+    /** Number of decisions for shadow mode (default: 1000) */
+    shadowModeDecisions?: number;
+    /** Max disagreement rate to exit shadow mode (default: 0.10) */
+    shadowModeMaxDisagreement?: number;
+}
+/**
+ * Shadow mode decision log entry
+ */
+export interface ShadowDecisionLog {
+    /** Task description (truncated) */
+    readonly taskDescription: string;
+    /** Rule-based router decision */
+    readonly ruleDecision: ClaudeModel;
+    /** Neural router decision */
+    readonly neuralDecision: ClaudeModel;
+    /** Whether both routers agreed */
+    readonly agreed: boolean;
+    /** Neural network confidence for chosen tier */
+    readonly neuralConfidence: number;
+    /** Timestamp */
+    readonly timestamp: Date;
+}
+/**
+ * Neural router statistics
+ */
+export interface NeuralRouterStats {
+    /** Whether shadow mode is active */
+    readonly shadowModeActive: boolean;
+    /** Total shadow mode decisions made */
+    readonly shadowDecisions: number;
+    /** Disagreement rate in shadow mode */
+    readonly disagreementRate: number;
+    /** Whether circuit breaker is tripped */
+    readonly circuitBreakerTripped: boolean;
+    /** Recent error rate (last N decisions) */
+    readonly recentErrorRate: number;
+    /** Total neural routing decisions */
+    readonly totalNeuralDecisions: number;
+    /** Total weight updates from feedback */
+    readonly totalWeightUpdates: number;
+    /** Whether neural routing is primary */
+    readonly neuralPrimary: boolean;
+}
+/**
+ * Empirical confidence bounds from historical calibration scores.
+ *
+ * Note: This is NOT proper conformal prediction (which requires exchangeability
+ * guarantees and per-class nonconformity scoring). These are quantile-based
+ * intervals from historical routing outcomes.
+ */
+export interface EmpiricalConfidenceBounds {
+    /** Lower bound of prediction interval */
+    readonly lower: number;
+    /** Upper bound of prediction interval */
+    readonly upper: number;
+    /** Coverage level (e.g. 0.90 = 90% prediction interval) */
+    readonly coverageLevel: number;
+    /** Calibration score (1 - max probability) */
+    readonly calibrationScore: number;
+}
+/** Backward-compatible alias */
+export type ConformalBounds = EmpiricalConfidenceBounds;
+/**
+ * Neural-enhanced TinyDancer Router
+ *
+ * Wraps the rule-based TinyDancerRouter with a lightweight neural network
+ * that learns optimal routing decisions from outcomes. Operates in shadow
+ * mode initially, then transitions to neural-primary when proven reliable.
+ *
+ * @example
+ * ```typescript
+ * const router = new NeuralTinyDancerRouter({ learningRate: 0.01 });
+ * const result = await router.route(task);
+ * // Later, record outcome for learning
+ * router.recordNeuralOutcome(task, result, true, 0.95);
+ * ```
+ */
+export declare class NeuralTinyDancerRouter {
+    /** Rule-based fallback router (always available) */
+    private readonly ruleRouter;
+    /** Neural network for routing decisions */
+    private readonly neuralNet;
+    /** Configuration */
+    private readonly circuitBreakerThreshold;
+    private readonly shadowModeDecisionLimit;
+    private readonly shadowModeMaxDisagreement;
+    /** Shadow mode state */
+    private shadowModeActive;
+    private shadowDecisions;
+    private shadowDisagreements;
+    /** Circuit breaker state */
+    private circuitBreakerTripped;
+    private recentOutcomes;
+    /** Tracking */
+    private totalNeuralDecisions;
+    private totalWeightUpdates;
+    private neuralPrimary;
+    /** Calibration scores for empirical confidence bounds */
+    private calibrationScores;
+    private readonly maxCalibrationScores;
+    /** Historical success rates by domain for feature extraction */
+    private domainSuccessRates;
+    /** Config passthrough */
+    private readonly config;
+    /** Whether native ruvector module is available */
+    private nativeRouterAvailable;
+    constructor(config?: NeuralTinyDancerConfig);
+    /**
+     * Check for native router availability.
+     *
+     * The `@ruvector/tiny-dancer` NAPI package exists but the ARM64 binary
+     * is missing from the published package (packaging bug upstream).
+     * The TypeScript `SimpleNeuralRouter` IS the production implementation —
+     * its 4→32→3 network is too small to benefit from native acceleration.
+     */
+    private tryLoadNativeRouter;
+    /**
+     * Route a task to the optimal Claude model.
+     *
+     * Behavior depends on current mode:
+     * - Shadow mode: uses rule-based result, logs neural decision alongside
+     * - Neural primary: uses neural decision with rule-based as validation
+     * - Circuit breaker tripped: uses rule-based only
+     *
+     * @param task - The task to route
+     * @returns Routing result with model recommendation and confidence
+     */
+    route(task: QETask | ClassifiableTask): Promise<RouteResult>;
+    /**
+     * Extract feature vector from a task for neural network input.
+     *
+     * Features:
+     *   [0] complexityScore: normalized classification score (0-1)
+     *   [1] tokenEstimate: estimated token count, normalized (0-1)
+     *   [2] domainIndex: domain-based complexity signal (0-1)
+     *   [3] historicalSuccessRate: domain success rate (0-1)
+     */
+    extractFeatures(task: QETask | ClassifiableTask, classification: ClassificationResult): number[];
+    /**
+     * Record the outcome of a routing decision for neural learning.
+     *
+     * Updates both the rule-based router (for stats) and the neural network
+     * weights (via policy gradient).
+     */
+    recordNeuralOutcome(task: QETask | ClassifiableTask, routeResult: RouteResult, success: boolean, qualityScore?: number, actualModelUsed?: ClaudeModel, durationMs?: number): void;
+    /**
+     * Compute empirical confidence bounds from historical calibration scores.
+     *
+     * Note: This is NOT proper conformal prediction (which requires exchangeability
+     * guarantees and per-class nonconformity scoring). These are quantile-based
+     * intervals from historical routing outcomes.
+     */
+    computeEmpiricalConfidenceBounds(probs: number[]): EmpiricalConfidenceBounds;
+    /**
+     * Backward-compatible alias for computeEmpiricalConfidenceBounds.
+     * @deprecated Use computeEmpiricalConfidenceBounds instead.
+     */
+    computeConformalBounds(probs: number[]): EmpiricalConfidenceBounds;
+    /**
+     * Check whether shadow mode should end.
+     * Exits when enough decisions made AND disagreement rate is acceptable.
+     */
+    private evaluateShadowModeExit;
+    /**
+     * Check circuit breaker and trip if error rate exceeds threshold.
+     */
+    private checkCircuitBreaker;
+    /**
+     * Trip the circuit breaker, falling back to rule-based routing.
+     */
+    private tripCircuitBreaker;
+    /**
+     * Build reasoning string for neural routing decision
+     */
+    private buildNeuralReasoning;
+    /**
+     * Get the index of the maximum value in an array.
+     */
+    private argmax;
+    /**
+     * Get neural router statistics
+     */
+    getNeuralStats(): NeuralRouterStats;
+    /**
+     * Get shadow mode decision logs
+     */
+    getShadowDecisionLogs(): readonly ShadowDecisionLog[];
+    /**
+     * Get the underlying rule-based router (for direct access if needed)
+     */
+    getRuleRouter(): TinyDancerRouter;
+    /**
+     * Get the underlying neural network (for serialization/deserialization)
+     */
+    getNeuralNet(): SimpleNeuralRouter;
+    /**
+     * Check if native ruvector router is available
+     */
+    isNativeRouterAvailable(): boolean;
+    /**
+     * Check if shadow mode is active
+     */
+    isShadowModeActive(): boolean;
+    /**
+     * Check if neural routing is primary
+     */
+    isNeuralPrimary(): boolean;
+    /**
+     * Check if circuit breaker is tripped
+     */
+    isCircuitBreakerTripped(): boolean;
+    /**
+     * Manually reset the circuit breaker
+     */
+    resetCircuitBreaker(): void;
+    /**
+     * Get the rule-based router's stats (delegates)
+     */
+    getStats(): import("./tiny-dancer-router.js").RouterStats;
+    /**
+     * Get the rule-based router's config (delegates)
+     */
+    getConfig(): TinyDancerConfig;
+    /**
+     * Reset all state (both rule-based and neural)
+     */
+    reset(): void;
+}
+/**
+ * Create a new Neural TinyDancer router instance
+ *
+ * @param config - Neural router configuration
+ * @returns Configured Neural TinyDancer router
+ */
+export declare function createNeuralTinyDancerRouter(config?: NeuralTinyDancerConfig): NeuralTinyDancerRouter;
+//# sourceMappingURL=neural-tiny-dancer-router.d.ts.map