lynkr 9.7.3 → 9.9.1

package/src/routing/deescalator.js

@@ -0,0 +1,148 @@
+/**
+ * De-escalation policy (WS2.3).
+ *
+ * The routing pipeline today only ratchets *up* — risk / agentic minTier /
+ * context / vision / kNN-ambiguous all escalate; nothing ever demotes. That
+ * means once a request_type has been escalated for ANY reason (even a
+ * one-off), it stays over-provisioned forever.
+ *
+ * This module supplies the missing signal: for a given (tier, request_type),
+ * has the *lower* tier historically served ≥ N similar requests at quality
+ * ≥ Q with error rate < E? If yes, the caller may demote — cheaper AND
+ * evidence-backed.
+ *
+ * The check is a plain SELECT against routing_telemetry (cached 60s) so
+ * enabling it in-line does not add DB pressure at request rate.
+ *
+ * @module routing/deescalator
+ */
+
+const logger = require('../logger');
+const telemetry = require('./telemetry');
+
+const TIER_ORDER = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+
+// Fixed thresholds. Chosen conservatively so a demotion only fires when the
+// lower tier has demonstrable evidence: a full-week window, a meaningful
+// sample count, high average quality, and a low error rate.
+const MIN_SAMPLES = 30;
+const MIN_QUALITY = 70;
+const MAX_ERROR_RATE = 0.05;
+const WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const CACHE_TTL_MS = 60 * 1000;
+
+/** @type {Map<string, {value: string|null, ts: number}>} */
+const _cache = new Map();
+
+function _cacheKey(tier, requestType) {
+  return `${tier}::${requestType || '<none>'}`;
+}
+
+function _lowerTier(tier) {
+  const idx = TIER_ORDER.indexOf(tier);
+  if (idx <= 0) return null;
+  return TIER_ORDER[idx - 1];
+}
+
+/**
+ * Return the demoted tier if evidence supports it; null otherwise.
+ *
+ * @param {Object} args
+ * @param {string} args.tier - The tier the router currently plans to serve.
+ * @param {string|null} args.requestType - Complexity analyzer's request_type.
+ * @param {Object} [args.analysis] - Passed through for callers that want it;
+ *   currently unused by the rule, kept for signature stability.
+ * @param {Object} [args.deps] - Test-injectable dependencies.
+ * @param {Function} [args.deps.getQualityByTierAndType] - Override the telemetry query.
+ * @param {Function} [args.deps.now] - Override Date.now() for tests.
+ * @returns {string|null} The lower tier, or null if demotion is not warranted.
+ */
+function suggestDemotion({ tier, requestType, analysis, deps = {} } = {}) {
+  if (!tier || !requestType) return null;
+  const lower = _lowerTier(tier);
+  if (!lower) return null;
+
+  const now = typeof deps.now === 'function' ? deps.now() : Date.now();
+  const key = _cacheKey(tier, requestType);
+  const cached = _cache.get(key);
+  if (cached && now - cached.ts < CACHE_TTL_MS) {
+    return cached.value;
+  }
+
+  const query = deps.getQualityByTierAndType || telemetry.getQualityByTierAndType;
+  if (typeof query !== 'function') return null;
+
+  let rows = null;
+  try {
+    rows = query({
+      since: now - WINDOW_MS,
+      until: now,
+      tiers: [lower],
+    });
+  } catch (err) {
+    logger.debug({ err: err.message }, '[Deescalator] telemetry query failed');
+    return null;
+  }
+
+  const match = Array.isArray(rows)
+    ? rows.find((r) => r.tier === lower && r.request_type === requestType)
+    : null;
+
+  const ok = match
+    && match.count >= MIN_SAMPLES
+    && (match.avg_quality ?? 0) >= MIN_QUALITY
+    && (match.error_rate ?? 1) < MAX_ERROR_RATE;
+
+  const value = ok ? lower : null;
+  _cache.set(key, { value, ts: now });
+  return value;
+}
+
+/** Test helper — clear the memoized decisions. */
+function _clearCache() {
+  _cache.clear();
+}
+
+/**
+ * Shadow-mode policy. Wraps the live routing decision by delegating to
+ * `determineProviderSmart` and then applying `suggestDemotion` on the result.
+ * Registered with shadow-mode.js under name 'deescalate-v1' so operators can
+ * evaluate the projected cost/quality delta before enabling live demotion.
+ */
+async function shadowDeescalate(payload) {
+  // Late require to avoid the circular src/routing/index.js ↔ deescalator.js
+  // reference (index.js registers the shadow policy at module load).
+  const { determineProviderSmart } = require('./index');
+  const base = await determineProviderSmart(payload, { _shadow: true });
+  if (!base?.tier) return base;
+  const requestType = base?.analysis?.breakdown?.taskType?.reason
+    ?? base?.analysis?.taskType
+    ?? null;
+  const demoted = suggestDemotion({
+    tier: base.tier,
+    requestType,
+    analysis: base.analysis,
+  });
+  if (!demoted) return base;
+  try {
+    const { getModelTierSelector } = require('./model-tiers');
+    const selected = getModelTierSelector().selectModel(demoted, null);
+    return {
+      ...base,
+      provider: selected.provider,
+      model: selected.model,
+      tier: demoted,
+      method: (base.method || 'tier_config') + '+deescalated_shadow',
+      _shadowDemotedFrom: base.tier,
+    };
+  } catch {
+    return base;
+  }
+}
+
+module.exports = {
+  suggestDemotion,
+  shadowDeescalate,
+  TIER_ORDER,
+  _clearCache,
+};

package/src/routing/degradation.js

@@ -0,0 +1,109 @@
+/**
+ * Degradation Registry
+ *
+ * Tracks silent-fallback occurrences across the routing pipeline. Every catch
+ * block in the routing path that used to `logger.debug` and fall through now
+ * calls `record(component, err)` here instead, giving us:
+ *
+ *   - A counter per subsystem (visible via getRoutingStats)
+ *   - A warn-once-per-hour policy per component (so the first failure surfaces
+ *     in ops, but a wedged subsystem doesn't spam)
+ *   - The last error message and timestamp for postmortem
+ *
+ * @module routing/degradation
+ */
+
+const logger = require("../logger");
+
+// TODO(prometheus): expose these counters as Prometheus gauges once the
+// project ships a prom-client registry (no such registry today; the WS0 plan
+// authorised skipping this — getRoutingStats().degradation is the interim
+// signal).
+
+const KNOWN_COMPONENTS = new Set([
+  "risk",
+  "embeddings",
+  "agentic",
+  "tier_select",
+  "cost_optimize",
+  "context_validate",
+  "vision_guard",
+  "knn",
+  "bandit",
+  "deadline",
+  "tenant",
+  "feedback",
+  "calibration",
+]);
+
+const WARN_INTERVAL_MS = 60 * 60 * 1000;
+
+/** @type {Map<string, {count:number, lastError:string|null, lastAt:number, lastWarnedAt:number}>} */
+const counters = new Map();
+
+function _entry(component) {
+  let e = counters.get(component);
+  if (!e) {
+    e = { count: 0, lastError: null, lastAt: 0, lastWarnedAt: 0 };
+    counters.set(component, e);
+  }
+  return e;
+}
+
+/**
+ * Record a degradation event. Warns once per hour per component, otherwise
+ * increments the counter silently at debug level.
+ *
+ * @param {string} component - One of KNOWN_COMPONENTS. Unknown names are
+ *   accepted (kept for forward compatibility) but log a debug notice.
+ * @param {Error|{message?:string}|string} err
+ */
+function record(component, err) {
+  if (!component) return;
+  if (!KNOWN_COMPONENTS.has(component)) {
+    logger.debug({ component }, "[Degradation] Unknown component recorded");
+  }
+
+  const message = err == null
+    ? "unknown"
+    : typeof err === "string"
+      ? err
+      : (err.message || String(err));
+
+  const now = Date.now();
+  const e = _entry(component);
+  e.count += 1;
+  e.lastError = message;
+  e.lastAt = now;
+
+  if (now - e.lastWarnedAt >= WARN_INTERVAL_MS) {
+    e.lastWarnedAt = now;
+    logger.warn({ component, err: message, count: e.count }, "[Degradation] Subsystem failed, falling through");
+  } else {
+    logger.debug({ component, err: message, count: e.count }, "[Degradation] Subsystem failed, falling through");
+  }
+}
+
+/**
+ * Snapshot of per-component counters, safe to serialize into stats responses.
+ * @returns {Object<string, {count:number, lastError:string|null, lastAt:number}>}
+ */
+function getCounts() {
+  const out = {};
+  for (const [name, e] of counters.entries()) {
+    out[name] = { count: e.count, lastError: e.lastError, lastAt: e.lastAt };
+  }
+  return out;
+}
+
+/** Test helper — reset all counters. */
+function _clear() {
+  counters.clear();
+}
+
+module.exports = {
+  record,
+  getCounts,
+  KNOWN_COMPONENTS,
+  _clear,
+};

package/src/routing/difficulty-classifier.js

@@ -0,0 +1,219 @@
+/**
+ * Difficulty classifier — LLM-based 4-way classification of user prompts.
+ *
+ * WHY THIS EXISTS: The anchor-embedding scorer (intent-score.js) measures
+ * *topical* similarity to labeled difficulty exemplars. It confuses "list
+ * the exports from this file" (LOW difficulty, technical vocabulary) with
+ * hard problems. An LLM reading the actual sentence knows better.
+ *
+ * DESIGN:
+ *  - Uses whatever model is configured for the SIMPLE tier (fetched at call
+ *    time via getModelTierSelector). When the user later swaps in a
+ *    fine-tuned classifier as SIMPLE, this picks it up automatically.
+ *  - Structured JSON output; parse failure → null → caller falls back.
+ *  - Hard 2500ms timeout; on timeout → null → caller falls back.
+ *  - LRU cache keyed by sha256(text.trim().toLowerCase()); capacity 500.
+ *  - Skip conditions surface via classifyDifficulty returning null with
+ *    reason=skipped: text.length<15, force-pattern matched, risk=high,
+ *    cache hit is transparent (returns cached).
+ *  - Hardcoded kill-switch CLASSIFIER_ENABLED — no env var per user policy.
+ *
+ * Failure modes are all null: anchor+lexical scoring already handles the
+ * fallback. This module never blocks routing.
+ */
+
+const crypto = require('crypto');
+const logger = require('../logger');
+
+const CLASSIFIER_ENABLED = true;
+// Thinking models (minimax-m2.5) spend 1-4s in <thinking> before emitting
+// JSON — 2.5s is not enough. Raise to 10s and rely on skip conditions +
+// LRU cache to keep amortized latency low.
+const TIMEOUT_MS = 10000;
+const CACHE_CAPACITY = 500;
+const MIN_TEXT_LENGTH = 15;
+
+// Classifier model — decoupled from tier serving so SIMPLE tier can run a
+// more capable model for real traffic while the classifier stays fast and
+// cheap. Chosen 2026-07-19: qwen2.5:3b hit 87.3% hand-labeled accuracy at
+// ~500ms warm latency, zero cost-critical over-routes. Replace with your
+// fine-tuned classifier when you build one. Hardcoded per user directive
+// (no env var).
+const CLASSIFIER_PROVIDER = 'ollama';
+const CLASSIFIER_MODEL = 'qwen2.5:3b';
+
+const VALID_TIERS = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING'];
+
+// One-shot classification prompt. Kept in a const so drift is diffable.
+// Difficulty framing (not intent) — matches config B routing goals.
+const CLASSIFY_PROMPT = `You are a classifier for an LLM routing proxy. Classify the difficulty of the user prompt below into exactly one of four tiers. Reply with ONLY valid JSON on a single line, no other text.
+
+Tiers:
+- SIMPLE: casual acknowledgments, greetings, one-word answers, trivial factual lookups. Any tiny model handles.
+  examples: "hi", "ok thanks", "yes continue", "what time is it"
+- MEDIUM: one specific mechanical task or a focused explanation. Mid-size local model suffices.
+  examples: "list the exports from this file", "run the unit tests", "fix the linter warnings", "explain this regex", "add error handling to this block"
+- COMPLEX: multi-file design, systemic refactor, architecture review, debugging that requires broad code understanding. Needs a strong general model.
+  examples: "architecture review of the orchestrator", "refactor the entire ingestion pipeline", "debug this complex race condition across three services"
+- REASONING: formal proof, correctness verification, security audit, novel algorithm design, formal reasoning from first principles. Needs a frontier reasoning model.
+  examples: "prove the correctness of this lock-free queue", "security audit the auth middleware", "formally verify this state machine never deadlocks", "derive the optimal eviction policy and prove its competitive ratio"
+
+Reply format (strict): {"tier":"SIMPLE|MEDIUM|COMPLEX|REASONING","confidence":0.0-1.0}
+
+User prompt: `;
+
+// --- LRU cache --------------------------------------------------------------
+
+class LruCache {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.map = new Map();
+  }
+  get(key) {
+    if (!this.map.has(key)) return undefined;
+    const val = this.map.get(key);
+    this.map.delete(key);
+    this.map.set(key, val); // move to MRU
+    return val;
+  }
+  set(key, val) {
+    if (this.map.has(key)) this.map.delete(key);
+    else if (this.map.size >= this.capacity) {
+      const oldest = this.map.keys().next().value;
+      this.map.delete(oldest);
+    }
+    this.map.set(key, val);
+  }
+  stats() { return { size: this.map.size, capacity: this.capacity }; }
+}
+
+const _cache = new LruCache(CACHE_CAPACITY);
+
+function _cacheKey(text) {
+  return crypto.createHash('sha256').update(text.trim().toLowerCase()).digest('hex');
+}
+
+// --- Ollama dispatch (only supported provider for the SIMPLE tier today) ----
+
+async function _callOllama(text, opts) {
+  const config = require('../config');
+
+  // First cut supports ollama-family classifier only. Other providers can
+  // be wired later; today's classifier is qwen2.5:3b on ollama.
+  if (CLASSIFIER_PROVIDER !== 'ollama') {
+    logger.debug({ provider: CLASSIFIER_PROVIDER, model: CLASSIFIER_MODEL }, '[DifficultyClassifier] non-ollama classifier not yet supported');
+    return null;
+  }
+
+  const endpoint = config.ollama?.endpoint || 'http://localhost:11434';
+  const url = `${endpoint.replace(/\/$/, '')}/api/chat`;
+  const body = {
+    model: CLASSIFIER_MODEL,
+    messages: [{ role: 'user', content: CLASSIFY_PROMPT + '"""' + text + '"""' }],
+    stream: false,
+    format: 'json',
+    // num_predict generous because thinking models (minimax-m2.5) burn
+    // budget in message.thinking before producing message.content JSON.
+    options: { temperature: 0, num_predict: 512 },
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs || TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    // Thinking models put output in message.thinking; regular in message.content.
+    // /api/generate variants use `response`. Try all three, biggest first.
+    const candidates = [
+      json?.message?.content,
+      json?.message?.thinking,
+      json?.response,
+    ].filter(s => typeof s === 'string' && s.length > 0);
+    return candidates.join('\n') || null;
+  } catch (err) {
+    logger.debug({ err: err.message, textPreview: text.slice(0, 60) }, '[DifficultyClassifier] call failed');
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --- Parse & validate the model's JSON output -------------------------------
+
+function _parseResult(raw) {
+  if (!raw) return null;
+  // Ollama with format:'json' usually gives clean JSON, but the model can
+  // still surround it with junk — extract the first { ... } span.
+  const match = raw.match(/\{[\s\S]*?\}/);
+  if (!match) return null;
+  let obj;
+  try { obj = JSON.parse(match[0]); } catch { return null; }
+  const tier = String(obj.tier || '').toUpperCase().trim();
+  if (!VALID_TIERS.includes(tier)) return null;
+  const rawConf = Number(obj.confidence);
+  const confidence = Number.isFinite(rawConf) ? Math.max(0, Math.min(1, rawConf)) : 0.5;
+  return { tier, confidence };
+}
+
+// --- Public API -------------------------------------------------------------
+
+/**
+ * Classify difficulty of user text.
+ *
+ * @param {string} text — cleaned user prompt
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs] — override default 2500ms
+ * @param {boolean} [opts.forceMatched] — caller already matched a FORCE_* pattern; skip classifier
+ * @param {string} [opts.riskLevel] — 'high' | 'medium' | 'low'; skip when 'high'
+ * @returns {Promise<{tier:string,confidence:number,source:'cache'|'model'}|null>}
+ *   null when: disabled, skipped, model failure, parse failure, timeout.
+ */
+async function classifyDifficulty(text, opts = {}) {
+  if (!CLASSIFIER_ENABLED) return null;
+  if (typeof text !== 'string') return null;
+  const trimmed = text.trim();
+  if (trimmed.length < MIN_TEXT_LENGTH) return null;
+  if (opts.forceMatched) return null;
+  if (opts.riskLevel === 'high') return null;
+
+  const key = _cacheKey(trimmed);
+  const cached = _cache.get(key);
+  if (cached) return { ...cached, source: 'cache' };
+
+  const raw = await _callOllama(trimmed, opts);
+  const parsed = _parseResult(raw);
+  if (!parsed) return null;
+  _cache.set(key, parsed);
+  return { ...parsed, source: 'model' };
+}
+
+// --- Test helpers -----------------------------------------------------------
+
+function _clearCacheForTests() { _cache.map.clear(); }
+function _getCacheStats() { return _cache.stats(); }
+
+// Exposed metadata for the bootstrap module — keeps model choice in one file
+// so classifier-setup.js pulls exactly what the classifier will call.
+const CLASSIFIER_MODEL_INFO = Object.freeze({
+  provider: CLASSIFIER_PROVIDER,
+  model: CLASSIFIER_MODEL,
+  endpoint: process.env.OLLAMA_ENDPOINT || 'http://localhost:11434',
+});
+
+module.exports = {
+  classifyDifficulty,
+  CLASSIFIER_ENABLED,
+  CLASSIFIER_MODEL_INFO,
+  VALID_TIERS,
+  // internals for tests only
+  _parseResult,
+  _cacheKey,
+  _clearCacheForTests,
+  _getCacheStats,
+};

package/src/routing/feedback.js

@@ -0,0 +1,157 @@
+/**
+ * WS5.3 — feedback loop.
+ *
+ * Every routing decision produces an outcome (quality, cost, latency,
+ * status, error). Historically the bandit's `update()` was a dead export
+ * and `reward-pipeline.js` had no importer at all — the ML pipeline was
+ * built but never trained. This module closes that loop:
+ *
+ *   1. Compute the reward from the outcome (`reward-pipeline`).
+ *   2. If the decision came from a bandit pick, feed the reward back with
+ *      the same context vector the bandit saw (`bandit.update`).
+ *   3. If we captured the query embedding at decision time and the outcome
+ *      is conclusive (quality ≥ 70 or ≤ 40), add the entry to the kNN
+ *      index for online growth.
+ *
+ * Contracts:
+ *   - `recordOutcome()` NEVER throws. Every failure is swallowed into the
+ *     degradation registry so we never poison the response path.
+ *   - Work runs on `setImmediate` — the caller is invoking this from the
+ *     hot path right after `telemetry.record(...)`.
+ *   - Missing / partial routing metadata is acceptable: the function
+ *     records what it can and skips what it can't.
+ */
+
+const logger = require('../logger');
+const degradation = require('./degradation');
+const { getRewardPipeline } = require('./reward-pipeline');
+const { getBandit } = require('./bandit');
+const { getKnnRouter } = require('./knn-router');
+
+// Quality thresholds for kNN online growth. Above HIGH → positive exemplar;
+// below LOW → negative exemplar. The mid-band is intentionally excluded to
+// avoid polluting the index with ambiguous cases.
+const KNN_POSITIVE_QUALITY = 70;
+const KNN_NEGATIVE_QUALITY = 40;
+
+/**
+ * @param {object} args
+ * @param {object} args.routingResult — the decision returned by
+ *   `determineProviderSmart` (or `pickTierByIntent` — see call sites in
+ *   src/clients/databricks.js). Only underscored internals are consumed.
+ * @param {object} args.body — the original request body (unused today but
+ *   accepted so future signals — user id, workspace, task id — can be
+ *   threaded without a signature change).
+ * @param {object} args.outcome — {qualityScore, costUsd, latencyMs,
+ *   statusCode, errorType, wasFallback}.
+ * @returns {void}
+ */
+function recordOutcome(args) {
+  // Never trust the caller's shape. Any non-object gets silently dropped —
+  // the response path is not the place to surface a caller bug.
+  const safeArgs = (args && typeof args === 'object') ? args : {};
+  setImmediate(() => {
+    try {
+      _recordOutcomeSync(safeArgs);
+    } catch (err) {
+      // Absolute last-resort guard. Every sub-call inside _recordOutcomeSync
+      // already has its own try/catch → degradation.record(...); this catch
+      // exists so a truly unexpected throw (e.g. degradation itself blowing
+      // up) can never leak.
+      try { degradation.record('feedback', err); } catch (_) { /* nope */ }
+    }
+  });
+}
+
+function _recordOutcomeSync({ routingResult, outcome }) {
+  if (!routingResult || !outcome) return;
+
+  const {
+    qualityScore = null,
+    costUsd = null,
+    latencyMs = null,
+  } = outcome;
+
+  let reward = null;
+  try {
+    const pipeline = getRewardPipeline();
+    reward = pipeline.reward({
+      quality: qualityScore,
+      cost: costUsd ?? 0,
+      latency: latencyMs ?? 0,
+    });
+  } catch (err) {
+    degradation.record('feedback', err);
+    reward = null;
+  }
+
+  // Bandit update — only when the decision actually came from a bandit pick
+  // (i.e. we stashed the context vector on the decision). Without ctx, an
+  // update would be meaningless: LinUCB's A/b matrices require the same
+  // feature vector the arm was scored on.
+  if (routingResult._banditContext
+      && routingResult.provider
+      && routingResult.model
+      && routingResult.tier
+      && typeof reward === 'number') {
+    try {
+      const bandit = getBandit();
+      bandit.update(
+        routingResult.tier,
+        routingResult.provider,
+        routingResult.model,
+        routingResult._banditContext,
+        reward,
+      );
+    } catch (err) {
+      degradation.record('feedback', err);
+    }
+  }
+
+  // kNN online growth — conclusive quality only. We paid for the embedding
+  // at decision time (stashed on `_queryEmbedding`), so add() is essentially
+  // free. Skipping the mid-band (40 < q < 70) keeps the index from filling
+  // up with ambiguous exemplars that would only muddy future advice.
+  if (routingResult._queryEmbedding
+      && typeof qualityScore === 'number'
+      && (qualityScore >= KNN_POSITIVE_QUALITY || qualityScore <= KNN_NEGATIVE_QUALITY)) {
+    try {
+      const router = getKnnRouter();
+      router.add(routingResult._queryEmbedding, {
+        query: routingResult._queryText ?? null,
+        provider: routingResult.provider,
+        model: routingResult.model,
+        tier: routingResult.tier,
+        quality: qualityScore,
+        cost: costUsd ?? 0,
+        latency: latencyMs ?? 0,
+        // A negative exemplar is worth recording so future queries whose
+        // neighbours are these bad outcomes score poorly. The router's
+        // score function already blends quality naturally; no separate
+        // "polarity" flag is needed.
+      });
+    } catch (err) {
+      degradation.record('feedback', err);
+    }
+  }
+
+  if (reward != null) {
+    logger.debug({
+      reward: reward.toFixed(2),
+      tier: routingResult.tier,
+      provider: routingResult.provider,
+      model: routingResult.model,
+      hasBandit: !!routingResult._banditContext,
+      hasEmbedding: !!routingResult._queryEmbedding,
+      qualityScore,
+    }, '[Feedback] Outcome recorded');
+  }
+}
+
+module.exports = {
+  recordOutcome,
+  // Test-only export so unit tests can drive the sync path directly.
+  _recordOutcomeSync,
+  KNN_POSITIVE_QUALITY,
+  KNN_NEGATIVE_QUALITY,
+};