@claude-flow/cli 3.32.1 → 3.32.3

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

@@ -1,182 +0,0 @@
-/**
- * neural-router.ts — Optional cost-optimal neural routing path (ADR-148).
- *
- * Wires `@metaharness/router` (pure-TS k-NN/KRR + optional FastGRNN via
- * `@ruvector/tiny-dancer`) into the model-routing path as a graceful, gated
- * addition. The shipped heuristic + Thompson bandit stays as the default;
- * this module only contributes a decision when:
- *
- *   1. `CLAUDE_FLOW_ROUTER_NEURAL=1` is set
- *   2. Either a trained artifact path resolves (`CLAUDE_FLOW_ROUTER_MODEL_PATH`)
- *      OR the bundled seed corpus loads
- *   3. The dynamic `import('@metaharness/router')` succeeds
- *
- * Otherwise `tryCostOptimalRoute(...)` returns `null` and the caller falls
- * back to the bandit path with `routedBy: 'bandit-fallback'`.
- *
- * Observability — `routedBy` is returned on every result and must never be
- * inferred from "did the import resolve?" (ADR-074, ADR-086). It carries
- * exactly one of:
- *   - 'metaharness-knn'  pure-TS k-NN, no training (uses raw seed examples)
- *   - 'metaharness-krr'  pure-TS KRR with LOO-CV λ (TrainedRouter JSON)
- *   - 'fastgrnn'         native FastGRNN via tiny-dancer (NativeRouter)
- *
- * Performance — module-level caches resolve the backend, seed corpus and
- * router once per process. Hot path is a single `route(embedding)` call.
- *
- * @module neural-router
- */
-import type { ClaudeModel } from './model-router.js';
-/** Backend identifier carried on every result (never inferred). */
-export type NeuralRoutedBy = 'metaharness-knn' | 'metaharness-krr' | 'fastgrnn';
-/** Cost-optimal route decision. */
-export interface NeuralRouteResult {
-    /** Chosen Claude tier label (back-compat). Derived from `modelId`. */
-    model: ClaudeModel;
-    /**
-     * Concrete picked model id — ADR-149. May be an Anthropic SDK id or an
-     * OpenRouter slug. Always a string; the closest tier label is in `model`
-     * for back-compat with consumers that still expect ClaudeModel.
-     */
-    modelId: string;
-    /** Predicted quality the chosen candidate is expected to achieve (0..1). */
-    predictedQuality: number;
-    /** Did the predicted quality clear the configured `qualityBar`? */
-    metBar: boolean;
-    /** Per-candidate predicted qualities, ordered cheapest-first. */
-    alternatives: Array<{
-        model: ClaudeModel;
-        modelId: string;
-        predictedQuality: number;
-        costPerMTok: number;
-    }>;
-    /** Backend that produced the decision. */
-    routedBy: NeuralRoutedBy;
-    /** Inference latency in microseconds. */
-    inferenceTimeUs: number;
-    /**
-     * ADR-149 iter 45 — ensemble disagreement diagnostic. Absolute difference
-     * in predicted quality for the PICKED model between the unified KRR and
-     * the bucket specialist (iter 16). Set only when both are loaded AND a
-     * complexityBucket was supplied. Operators tuning iter 44's
-     * `CLAUDE_FLOW_ROUTER_ENSEMBLE_UNCERTAINTY_THRESHOLD` need to observe
-     * realistic disagreement values to pick a sensible cutoff.
-     */
-    ensembleDisagreement?: number;
-}
-/** Module-level configuration. Read once at first call from env. */
-interface NeuralRouterConfig {
-    enabled: boolean;
-    modelPath?: string;
-    /** Bundled fallback artifact (KRR JSON). Used when `modelPath` is unset. */
-    bundledKrrPath: string;
-    qualityBar: number;
-    seedCorpusPath: string;
-    /** k for k-NN backend (default 5). */
-    k: number;
-    /**
-     * ADR-149 iter 12 — optional latency budget in ms. When > 0, candidates
-     * whose measured p50 latency exceeds the budget are filtered OUT before
-     * the cost-optimal selector runs. Default 0 (unbounded, cost-only).
-     * For interactive flows that need sub-second responses, set 1000.
-     */
-    latencyBudgetMs: number;
-    /**
-     * ADR-149 iter 22+24 — post-hoc isotonic calibration. When the bundled
-     * calibrator JSON is present, KRR predict() outputs are piped through
-     * IsotonicCalibrator.transform() before cost-optimal selection.
-     *
-     * DEFAULT ON (iter 24, ADR-149). Iter 23's out-of-sample LOO validation
-     * showed ECE drops from 0.1604 (POORLY-CALIBRATED) to 0.0335
-     * (WELL-CALIBRATED) — a 79% reduction with only a 0.0144 train/test gap,
-     * confirming the calibrator generalizes. Set
-     * `CLAUDE_FLOW_ROUTER_CALIBRATE=0` to opt out and recover iter 0-21 raw
-     * KRR behavior.
-     */
-    calibrateEnabled: boolean;
-    /** Path to the bundled calibrator JSON (iter 22). */
-    calibratorPath: string;
-    /**
-     * ADR-149 iter 29 — orthogonal selector mode: when > 0, filter candidates
-     * by blended price ≤ ceiling, then pick the HIGHEST predicted quality
-     * (not cheapest-above-bar). Lets ops with a hard budget cap ask "best
-     * model under $X" instead of "cheapest above quality threshold". Default
-     * 0 (disabled) preserves iter 0-28 cost-optimal-above-bar semantics.
-     */
-    costCeilingPerMTok: number;
-    /**
-     * ADR-149 iter 44 — ensemble-uncertainty-aware fallback. When > 0, the
-     * selector queries BOTH the unified KRR and the bucket specialist for
-     * the same query, then computes |unified_q - specialist_q| for the
-     * picked model. If the disagreement exceeds this threshold, returns null
-     * so the caller falls back to the bandit — same path as a 429/5xx API
-     * error today, but triggered by prediction uncertainty instead.
-     *
-     * Typical values: 0.10 (mild — only the most uncertain predictions
-     * fall back), 0.20 (aggressive — any meaningful ensemble disagreement
-     * triggers fallback). 0 disables (default — preserves iter 0-43 behavior).
-     */
-    ensembleUncertaintyThreshold: number;
-}
-/**
- * Cost-optimal route via the optional neural backend. Returns `null` when the
- * neural path is disabled (gate closed), unavailable (deps missing), or
- * unconfigured (no corpus / artifact). Callers must fall back to the
- * heuristic+bandit path on null and tag the result `routedBy: 'bandit-fallback'`.
- *
- * @param embedding 384-dim (or matching corpus dim) query embedding
- * @returns NeuralRouteResult on success, or `null` when the path is inactive
- */
-export declare function tryCostOptimalRoute(embedding: number[], opts?: {
-    complexityBucket?: 'low' | 'med' | 'high';
-}): Promise<NeuralRouteResult | null>;
-/**
- * Batch counterpart to `tryCostOptimalRoute`. Routes a list of embeddings
- * in one go, sharing backend resolution + (for the pure-TS paths)
- * candidate-view setup across the batch. The native FastGRNN path still
- * dispatches per-call (xenova's worker doesn't support array inputs for
- * tiny-dancer's Router.route).
- *
- * Order of the output array matches the input order. Each slot is either
- * a NeuralRouteResult or null (gate closed, backend unavailable, etc. —
- * mirrors the single-call contract).
- *
- * For harness-style callers (batch evals, GAIA runs, parallel agent
- * dispatch) this amortizes backend init across N queries — first-call
- * cold-load (~10 ms) becomes a fixed cost regardless of batch size.
- */
-export declare function tryCostOptimalRouteBatch(embeddings: number[][]): Promise<Array<NeuralRouteResult | null>>;
-/**
- * Diagnostic surface — returns the active backend without performing a route.
- * Used by the bench and by `claude-flow neural router status` (future CLI).
- */
-export declare function neuralRouterStatus(): Promise<{
-    enabled: boolean;
-    available: boolean;
-    routedBy: NeuralRoutedBy | null;
-    reason: string;
-    config: NeuralRouterConfig;
-}>;
-/**
- * ADR-149 iter 7 — fallback selector for retry-on-failure. Returns the
- * cheapest candidate predicted to clear the quality bar (or the best-
- * predicted if none do) that is NOT in `excludeModelIds`. Used by
- * `executeAgentTask` to retry with a different model after a 429/5xx.
- *
- * Returns `null` when:
- *   - the gate is closed (mirrors tryCostOptimalRoute)
- *   - the embedding is missing or empty
- *   - the backend isn't loadable
- *   - every candidate is excluded (all retries exhausted)
- *
- * Selection is per-candidate via predictAll, then filter by exclude,
- * then cheapest-clearing-bar (falling back to best-predicted).
- */
-export declare function nextCostOptimalAlternative(embedding: number[], excludeModelIds: Iterable<string>): Promise<NeuralRouteResult | null>;
-/**
- * Test seam — reset module-level caches so unit tests can simulate cold init.
- * Not exported from the package's barrel.
- */
-export declare function __resetNeuralRouterForTests(): void;
-export {};
-//# sourceMappingURL=neural-router.d.ts.map