pi-research 1.3.1 → 1.4.0

package/lib/router-annotation.js

@@ -0,0 +1,192 @@
+export const ANNOTATION_LABELS = {
+  conflict: ["no_conflict", "resolved_by_authority", "resolved_by_recency", "needs_review"],
+  sufficiency: ["sufficient", "need_authority", "need_more_sources", "need_recency", "need_version_context"],
+};
+
+export function parseJsonl(text = "") {
+  return String(text)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function stableHash(input = "") {
+  let hash = 2166136261;
+  const text = String(input);
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function deriveAnnotationId(task, row = {}) {
+  return stableHash(JSON.stringify([task || "unknown", row.query || "", row.inputText || "", row.meta?.mode || null]));
+}
+
+function isTemporalQuery(query = "") {
+  return /\b(current|latest|today|status|support|supported|lts|2024|2025|2026|release)\b/i.test(query);
+}
+
+function isVersionQuery(query = "") {
+  return /\b(version|v\d+|migration|upgrade|compatibility|compatible|build flag)\b/i.test(query);
+}
+
+function isProceduralDocQuery(query = "") {
+  return /\b(readme|issue|repo|repository|docs|documentation|file|csv|json|run|how to|how evaluation works|spreadsheet|columns|api|abortcontroller|promise\.all|browsecomp_eval\.py)\b/i.test(query);
+}
+
+function hasBlockedMarker(text = "") {
+  return /attention required!|cloudflare|access denied|temporarily unavailable/i.test(text);
+}
+
+function sourceTypeCounts(text = "") {
+  const tags = ["official_doc", "paper", "github_readme", "github_repo", "forum", "blog", "other"];
+  const counts = Object.fromEntries(tags.map((tag) => [tag, 0]));
+  for (const tag of tags) {
+    const matches = text.match(new RegExp(`\\[${tag}\\]`, "gi"));
+    counts[tag] = matches ? matches.length : 0;
+  }
+  return counts;
+}
+
+function hasAuthorityMarkers(text = "") {
+  const counts = sourceTypeCounts(text);
+  return counts.official_doc + counts.paper + counts.github_readme + counts.github_repo > 0;
+}
+
+function hasFreshnessMarkers(text = "") {
+  return /\b(current|latest|today|2024|2025|2026|lts|release|support status)\b/i.test(text);
+}
+
+function countStrongAuthority(counts) {
+  return counts.official_doc + counts.paper + counts.github_readme;
+}
+
+export function suggestAnnotation(task, row = {}) {
+  const query = String(row.query || "");
+  const candidateLabel = String(row.candidateLabel || row.label || "");
+  const inputText = String(row.inputText || "");
+  const meta = row.meta && typeof row.meta === "object" ? row.meta : {};
+  const sourceCount = Number(meta.sourceCount || 0);
+  const counts = sourceTypeCounts(inputText);
+  const blocked = hasBlockedMarker(inputText);
+  const authoritative = !blocked && (Boolean(meta.authoritativeSourcesFound) || hasAuthorityMarkers(inputText));
+  const strongAuthority = countStrongAuthority(counts);
+  const temporal = isTemporalQuery(query);
+  const versioned = isVersionQuery(query);
+  const procedural = isProceduralDocQuery(query);
+  const freshness = hasFreshnessMarkers(inputText);
+
+  if (task === "conflict") {
+    if (candidateLabel === "no_conflict") {
+      return { label: "no_conflict", rationale: "The snippets do not show a clear factual contradiction on the same claim." };
+    }
+    if (procedural && authoritative) {
+      return { label: "no_conflict", rationale: "Repository, README, and documentation sources are more likely complementary than contradictory here." };
+    }
+    if (temporal && authoritative) {
+      return { label: "resolved_by_recency", rationale: "This looks time-sensitive, so the more current authoritative source should decide the conflict." };
+    }
+    if (authoritative) {
+      return { label: "resolved_by_authority", rationale: "Prefer the authoritative source over weaker secondary evidence." };
+    }
+    return { label: "needs_review", rationale: "The snippets suggest disagreement, but there is no clear authoritative or fresher winner." };
+  }
+
+  if (!authoritative) {
+    return { label: "need_authority", rationale: "The available sources are not authoritative enough to treat this as fully answered." };
+  }
+  if (temporal && !freshness) {
+    return { label: "need_recency", rationale: "This query is time-sensitive, but the snippets do not clearly establish current status." };
+  }
+  if (versioned) {
+    return { label: "need_version_context", rationale: "This answer depends on version-specific behavior that should be confirmed explicitly." };
+  }
+  if (candidateLabel === "insufficient" && sourceCount <= 1) {
+    return { label: "need_more_sources", rationale: "There is some evidence, but a single source is not enough for a robust answer here." };
+  }
+  if (candidateLabel === "insufficient" && strongAuthority >= 2 && sourceCount >= 3 && !temporal && !versioned) {
+    return { label: "sufficient", rationale: "The sources appear authoritative enough and broad enough to answer the query reliably." };
+  }
+  if (sourceCount <= 2 && !procedural) {
+    return { label: "need_more_sources", rationale: "There is some evidence, but not enough independent coverage yet." };
+  }
+  return { label: "sufficient", rationale: "The sources appear authoritative enough and broadly cover the query." };
+}
+
+export function buildAnnotationItems(task, draftRows = [], reviewedRows = []) {
+  const reviewedById = new Map(
+    reviewedRows.map((row) => [deriveAnnotationId(task, row), row]),
+  );
+
+  return draftRows.map((row) => {
+    const id = deriveAnnotationId(task, row);
+    const reviewed = reviewedById.get(id);
+    const finalLabel = reviewed?.label || "";
+    const rationale = reviewed?.rationale || row.rationale || "";
+    const suggestion = suggestAnnotation(task, row);
+
+    return {
+      id,
+      task,
+      query: row.query || "",
+      candidateLabel: row.candidateLabel || row.label || "",
+      finalLabel,
+      rationale,
+      suggestedLabel: suggestion.label,
+      suggestedRationale: suggestion.rationale,
+      inputText: row.inputText || "",
+      meta: row.meta && typeof row.meta === "object" ? row.meta : {},
+      status: finalLabel ? "reviewed" : "pending",
+    };
+  });
+}
+
+export function upsertAnnotationReview(items = [], id, patch = {}) {
+  return items.map((item) => {
+    if (item.id !== id) return item;
+    const finalLabel = patch.finalLabel ?? item.finalLabel ?? "";
+    const rationale = patch.rationale ?? item.rationale ?? "";
+    return {
+      ...item,
+      finalLabel,
+      rationale,
+      status: finalLabel ? "reviewed" : "pending",
+    };
+  });
+}
+
+export function summarizeAnnotationProgress(items = []) {
+  const byLabel = {};
+  let reviewed = 0;
+
+  for (const item of items) {
+    if (item?.status === "reviewed" && item.finalLabel) {
+      reviewed += 1;
+      byLabel[item.finalLabel] = (byLabel[item.finalLabel] || 0) + 1;
+    }
+  }
+
+  return {
+    total: items.length,
+    reviewed,
+    pending: Math.max(0, items.length - reviewed),
+    byLabel,
+  };
+}
+
+export function exportReviewedJsonl(items = []) {
+  return items
+    .filter((item) => item?.status === "reviewed" && item.finalLabel)
+    .map((item) => JSON.stringify({
+      query: item.query,
+      label: item.finalLabel,
+      rationale: item.rationale || "",
+      inputText: item.inputText,
+      candidateLabel: item.candidateLabel,
+      meta: item.meta && typeof item.meta === "object" ? item.meta : {},
+    }))
+    .join("\n");
+}

package/lib/router-structured-features.js

@@ -0,0 +1,134 @@
+import { PLACEHOLDER_PATTERNS } from "./research-policy.js";
+
+const AUTHORITATIVE_TYPES = new Set(["official_doc", "paper", "github_readme", "github_repo", "file"]);
+const POSITIVE_PATTERN = /\b(supported|works|available|recommended|stable|benchmark|comprehensive|practical)\b/i;
+const NEGATIVE_PATTERN = /\b(not supported|unsupported|does not|no support|broken|incompatible|removed|blocked|denied)\b/i;
+const KNOWN_SOURCE_TYPES = new Set(["official_doc", "paper", "github_readme", "github_repo", "forum", "blog", "other", "file"]);
+
+export function parseStructuredSources(inputText = "") {
+  const marker = "Sources:";
+  const index = String(inputText).indexOf(marker);
+  if (index === -1) return [];
+  const body = String(inputText).slice(index + marker.length).trim();
+  if (!body) return [];
+
+  return body
+    .split(/\n\s*\n/)
+    .map((chunk) => chunk.trim())
+    .filter(Boolean)
+    .map((chunk, idx) => {
+      const match = chunk.match(/^\[([^\]]+)\]\s*(.*)$/s);
+      const sourceType = match?.[1] || "other";
+      const text = (match?.[2] || chunk).replace(/\s+/g, " ").trim();
+      return {
+        index: idx,
+        sourceType,
+        title: text,
+        text,
+        authoritative: AUTHORITATIVE_TYPES.has(sourceType),
+        blocked: PLACEHOLDER_PATTERNS.some((p) => p.test(text)),
+        positive: POSITIVE_PATTERN.test(text),
+        negative: NEGATIVE_PATTERN.test(text),
+      };
+    });
+}
+
+export function structuredSourceFromPage(page = {}, index = 0) {
+  const sourceType = KNOWN_SOURCE_TYPES.has(page.sourceType) ? page.sourceType : "other";
+  const text = `${page.title || ""} ${page.snippet || page.text || ""}`.replace(/\s+/g, " ").trim();
+  const blocked = Boolean(page.quality?.blocked) || PLACEHOLDER_PATTERNS.some((p) => p.test(text));
+  const authoritative = !blocked && (Boolean(page.authoritative) || AUTHORITATIVE_TYPES.has(sourceType));
+
+  return {
+    index,
+    sourceType,
+    title: page.title || text,
+    text,
+    authoritative,
+    blocked,
+    positive: POSITIVE_PATTERN.test(text),
+    negative: NEGATIVE_PATTERN.test(text),
+  };
+}
+
+export function structuredSourcesFromPages(pages = []) {
+  return Array.isArray(pages) ? pages.map((page, index) => structuredSourceFromPage(page, index)) : [];
+}
+
+export function extractQueryAspectFlags(query = "") {
+  const text = String(query || "");
+  return {
+    temporal: /\b(current|latest|today|status|support|supported|lts|2024|2025|2026|release)\b/i.test(text) ? 1 : 0,
+    versioned: /\b(version|v\d+|migration|upgrade|compatibility|compatible|build flag)\b/i.test(text) ? 1 : 0,
+    comparison: /\b(vs\.?|versus|compare|comparison|compared to)\b/i.test(text) ? 1 : 0,
+    academic: /\b(paper|papers|study|studies|arxiv|doi|research|benchmark)\b/i.test(text) ? 1 : 0,
+    procedural: /\b(readme|issue|repo|repository|docs|documentation|file|csv|json|run|how to|api)\b/i.test(text) ? 1 : 0,
+  };
+}
+
+function countBySourceType(sources = []) {
+  const keys = ["official_doc", "paper", "github_readme", "github_repo", "forum", "blog", "other", "file"];
+  const counts = Object.fromEntries(keys.map((key) => [key, 0]));
+  for (const source of sources) counts[source.sourceType] = (counts[source.sourceType] || 0) + 1;
+  return counts;
+}
+
+function baseStructuredFeatures(query, sources) {
+  const flags = extractQueryAspectFlags(query);
+  const counts = countBySourceType(sources);
+  const authoritativeSources = sources.filter((source) => source.authoritative && !source.blocked);
+  return {
+    query_temporal: flags.temporal,
+    query_versioned: flags.versioned,
+    query_comparison: flags.comparison,
+    query_academic: flags.academic,
+    query_procedural: flags.procedural,
+    source_count: sources.length,
+    authoritative_source_count: authoritativeSources.length,
+    blocked_source_count: sources.filter((source) => source.blocked).length,
+    positive_signal_sources: sources.filter((source) => source.positive).length,
+    negative_signal_sources: sources.filter((source) => source.negative).length,
+    official_doc_count: counts.official_doc,
+    paper_count: counts.paper,
+    github_readme_count: counts.github_readme,
+    github_repo_count: counts.github_repo,
+    forum_count: counts.forum,
+    blog_count: counts.blog,
+    other_count: counts.other,
+    file_count: counts.file,
+  };
+}
+
+export function extractConflictStructuredFeaturesFromSources(query = "", sources = [], candidateLabel = "") {
+  return {
+    ...baseStructuredFeatures(query, sources),
+    candidate_conflict: String(candidateLabel || "").includes("conflict") ? 1 : 0,
+    has_authority_resolution_path: sources.some((source) => source.authoritative && !source.blocked) ? 1 : 0,
+  };
+}
+
+export function extractConflictStructuredFeatures(row = {}) {
+  const sources = parseStructuredSources(row.inputText || "");
+  return extractConflictStructuredFeaturesFromSources(row.query || "", sources, row.candidateLabel || row.label || "");
+}
+
+export function extractConflictStructuredFeaturesFromPages(query = "", pages = [], candidateLabel = "") {
+  return extractConflictStructuredFeaturesFromSources(query, structuredSourcesFromPages(pages), candidateLabel);
+}
+
+export function extractSufficiencyStructuredFeaturesFromSources(query = "", sources = []) {
+  return {
+    ...baseStructuredFeatures(query, sources),
+    has_authority: sources.some((source) => source.authoritative && !source.blocked) ? 1 : 0,
+    has_only_one_good_source: sources.filter((source) => source.authoritative && !source.blocked).length === 1 ? 1 : 0,
+  };
+}
+
+export function extractSufficiencyStructuredFeatures(row = {}) {
+  const sources = parseStructuredSources(row.inputText || "");
+  return extractSufficiencyStructuredFeaturesFromSources(row.query || "", sources);
+}
+
+export function extractSufficiencyStructuredFeaturesFromPages(query = "", pages = []) {
+  return extractSufficiencyStructuredFeaturesFromSources(query, structuredSourcesFromPages(pages));
+}

package/lib/tiny-router.js

@@ -0,0 +1,338 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  extractConflictStructuredFeaturesFromPages,
+  extractSufficiencyStructuredFeaturesFromPages,
+} from "./router-structured-features.js";
+
+const HIGH_RISK_DOMAINS = new Set(["security", "papers", "specs"]);
+const MIN_DEFAULT_DOMAIN_THRESHOLD = 0.35;
+const MIN_HIGH_RISK_DOMAIN_THRESHOLD = 0.55;
+const SUFFICIENCY_VETO_DECISIONS = new Set([
+  "need_authority",
+  "need_more_sources",
+  "need_recency",
+  "need_version_context",
+  "need_conflict_resolution",
+]);
+
+let daemonProcess = null;
+let isReady = false;
+let messageQueue = [];
+let pendingRequests = new Map();
+let requestIdCounter = 1;
+const domainCalibrationCache = new Map();
+
+function envFlag(env, name, defaultValue = false) {
+  const value = env[name];
+  if (value === undefined) return defaultValue;
+  return value === "1" || value === "true";
+}
+
+function modelExists(modelDir, name) {
+  return existsSync(join(modelDir, name, "model.joblib"));
+}
+
+export function resolveTinyRouterConfig(env = process.env) {
+  const enabled = envFlag(env, "PI_RESEARCH_TINY_ROUTER");
+  const modelDir = env.PI_RESEARCH_TINY_ROUTER_MODEL || join(dirname(fileURLToPath(import.meta.url)), "..", "ml", "models");
+  const pythonPath = env.PI_RESEARCH_TINY_ROUTER_PYTHON || join(process.cwd(), ".venv-router", "bin", "python");
+  const daemonAvailable = enabled && existsSync(pythonPath);
+
+  return {
+    enabled: daemonAvailable,
+    modelDir,
+    pythonPath,
+    timeoutMs: Number(env.PI_RESEARCH_TINY_ROUTER_TIMEOUT_MS || 50),
+    tasks: {
+      domain: daemonAvailable && envFlag(env, "PI_RESEARCH_TINY_ROUTER_DOMAIN", true) && modelExists(modelDir, "domain"),
+      followup: daemonAvailable && envFlag(env, "PI_RESEARCH_TINY_ROUTER_FOLLOWUP") && modelExists(modelDir, "followup"),
+      conflict: daemonAvailable && envFlag(env, "PI_RESEARCH_TINY_ROUTER_CONFLICT") && modelExists(modelDir, "conflict-structured"),
+      sufficiency: daemonAvailable && envFlag(env, "PI_RESEARCH_TINY_ROUTER_SUFFICIENCY") && modelExists(modelDir, "sufficiency-structured"),
+    },
+  };
+}
+
+function startDaemon(config) {
+  if (daemonProcess) return;
+
+  const daemonScript = join(dirname(fileURLToPath(import.meta.url)), "..", "ml", "router", "daemon.py");
+  daemonProcess = spawn(config.pythonPath, [daemonScript, config.modelDir], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  let buffer = "";
+
+  daemonProcess.stdout.on("data", (chunk) => {
+    buffer += chunk.toString();
+    const lines = buffer.split("\n");
+    buffer = lines.pop();
+
+    for (const line of lines) {
+      if (line.trim() === "READY") {
+        isReady = true;
+        for (const msg of messageQueue) {
+          msg.startInferenceTimer();
+          daemonProcess.stdin.write(`${msg.payload}\n`);
+        }
+        messageQueue = [];
+        continue;
+      }
+
+      try {
+        const parsed = JSON.parse(line);
+        const pending = pendingRequests.get(parsed.id);
+        if (pending) {
+          pendingRequests.delete(parsed.id);
+          pending.resolve(parsed);
+        }
+      } catch {
+        // ignore malformed JSON
+      }
+    }
+  });
+
+  daemonProcess.stderr.on("data", () => {
+    // ignore stderr warnings for now
+  });
+
+  const currentProcess = daemonProcess;
+
+  daemonProcess.on("exit", () => {
+    if (daemonProcess === currentProcess) {
+      daemonProcess = null;
+      isReady = false;
+      for (const { resolve } of pendingRequests.values()) {
+        resolve({ error: "Daemon exited" });
+      }
+      pendingRequests.clear();
+    }
+  });
+}
+
+export function stopTinyRouterDaemon() {
+  if (daemonProcess) {
+    daemonProcess.kill();
+    daemonProcess = null;
+  }
+  isReady = false;
+  messageQueue = [];
+  for (const { resolve } of pendingRequests.values()) {
+    resolve({ error: "Daemon stopped manually" });
+  }
+  pendingRequests.clear();
+}
+
+function requestTinyRouter(config, taskPayload, signal, finalize) {
+  startDaemon(config);
+
+  const id = requestIdCounter++;
+  const payload = JSON.stringify({ id, ...taskPayload });
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener?.("abort", abort);
+      pendingRequests.delete(id);
+      resolve(finalize(result));
+    };
+
+    const abort = () => finish(null);
+
+    pendingRequests.set(id, { resolve: finish });
+
+    const startInferenceTimer = () => {
+      timer = setTimeout(abort, config.timeoutMs);
+      timer.unref?.();
+    };
+
+    if (signal?.aborted) {
+      abort();
+    } else {
+      signal?.addEventListener?.("abort", abort, { once: true });
+      if (isReady) {
+        startInferenceTimer();
+        daemonProcess.stdin.write(`${payload}\n`);
+      } else {
+        messageQueue.push({ payload, startInferenceTimer });
+      }
+    }
+  });
+}
+
+export function chooseTinyRouterDomain(heuristicDomain, tinyDomain) {
+  if (!tinyDomain) return heuristicDomain;
+  if (HIGH_RISK_DOMAINS.has(heuristicDomain) && tinyDomain === "web") return heuristicDomain;
+  return tinyDomain;
+}
+
+function loadDomainCalibration(modelDir) {
+  if (domainCalibrationCache.has(modelDir)) return domainCalibrationCache.get(modelDir);
+  const path = join(modelDir, "domain", "calibration.json");
+  let calibration = {
+    defaultThreshold: 0.80,
+    highRiskThreshold: 0.75,
+    domainThresholds: {},
+  };
+
+  try {
+    if (existsSync(path)) {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      calibration = {
+        defaultThreshold: Number(parsed.defaultThreshold || 0.80),
+        highRiskThreshold: Number(parsed.highRiskThreshold || 0.75),
+        domainThresholds: parsed.domainThresholds && typeof parsed.domainThresholds === "object" ? parsed.domainThresholds : {},
+      };
+    }
+  } catch {
+    // keep safe defaults
+  }
+
+  domainCalibrationCache.set(modelDir, calibration);
+  return calibration;
+}
+
+export function resolveTinyRouterDomainThreshold(domain, calibration = {}) {
+  const floor = HIGH_RISK_DOMAINS.has(domain) ? MIN_HIGH_RISK_DOMAIN_THRESHOLD : MIN_DEFAULT_DOMAIN_THRESHOLD;
+  if (domain && calibration.domainThresholds && Number.isFinite(Number(calibration.domainThresholds[domain]))) {
+    return Math.max(Number(calibration.domainThresholds[domain]), floor);
+  }
+  if (HIGH_RISK_DOMAINS.has(domain)) return Math.max(Number(calibration.highRiskThreshold || 0.75), floor);
+  return Math.max(Number(calibration.defaultThreshold || 0.80), floor);
+}
+
+export function acceptTinyRouterDomainPrediction(result, calibration = {}) {
+  if (!result || result.error || !result.domain) return null;
+  return result.confidence >= resolveTinyRouterDomainThreshold(result.domain, calibration) ? result.domain : null;
+}
+
+export async function classifyDomainWithTinyRouter(query, mode = "fast", signal, env = process.env) {
+  const config = resolveTinyRouterConfig(env);
+  if (!config.tasks.domain) return null;
+  const calibration = loadDomainCalibration(config.modelDir);
+
+  return requestTinyRouter(
+    config,
+    { task: "domain", query, mode },
+    signal,
+    (result) => acceptTinyRouterDomainPrediction(result, calibration),
+  );
+}
+
+export function classifyFollowupWithStrongRules(query, mode = "fast", conflict = "none", sources = {}) {
+  const text = String(query || "").toLowerCase();
+  const sourceCount = Number(sources.source_count || 0);
+  const hasAuthority = Boolean(sources.has_authority);
+  const hasRecent = Boolean(sources.has_recent);
+  const isRecencyQuery = /\b(latest|current|today|release|changelog|new)\b/.test(text);
+
+  if (conflict === "severe") return "need_conflict_resolution";
+  if (conflict === "minor" && !(mode === "fast" && hasAuthority && sourceCount >= 4)) return "need_conflict_resolution";
+  if (isRecencyQuery && !hasRecent) return "need_recency";
+  if (!hasAuthority && sourceCount === 0) return "need_more_sources";
+  return null;
+}
+
+export function applyConflictTinyRouterDecision(heuristicConflictDetected, structuredDecision, options = {}) {
+  const allowClear = options.allowClear === true;
+
+  if (structuredDecision === "open_conflict" || structuredDecision === "needs_review") return true;
+  if (heuristicConflictDetected && !allowClear) return true;
+  if (heuristicConflictDetected && ["resolved_by_authority", "resolved_by_recency", "no_conflict"].includes(structuredDecision)) {
+    return false;
+  }
+  return Boolean(heuristicConflictDetected);
+}
+
+export function applySufficiencyTinyRouterDecision(currentSufficient, structuredDecision) {
+  if (!currentSufficient) return false;
+  if (SUFFICIENCY_VETO_DECISIONS.has(structuredDecision)) return false;
+  return true;
+}
+
+export function classifyFollowupHeuristically(query, mode = "fast", conflict = "none", sources = {}) {
+  const text = String(query || "").toLowerCase();
+  const sourceCount = Number(sources.source_count || 0);
+  const hasAuthority = Boolean(sources.has_authority);
+  const isAcademicQuery = /\b(paper|papers|arxiv|doi|publisher|survey|review|research)\b/.test(text);
+
+  const strongRule = classifyFollowupWithStrongRules(query, mode, conflict, sources);
+  if (strongRule) return strongRule;
+
+  if (mode === "academic" || isAcademicQuery) {
+    if (isAcademicQuery) return "need_primary_source";
+    if (!hasAuthority) return "need_authority";
+    if (sourceCount < 4) return "need_more_sources";
+    return "stop";
+  }
+
+  if (mode === "deep") {
+    if (!hasAuthority) return "need_authority";
+    if (sourceCount <= 1) return "need_more_sources";
+    if (sourceCount < 3) return "need_more_sources";
+    return "stop";
+  }
+
+  if (mode === "fast" || mode === "code") {
+    if (hasAuthority && sourceCount >= 1) return "stop";
+    if (sourceCount >= 3) return "stop";
+    return null;
+  }
+
+  if (!hasAuthority) return "need_authority";
+  if (sourceCount === 0) return "need_more_sources";
+  return "stop";
+}
+
+export async function classifyFollowupWithTinyRouter(query, mode, conflict, sources, signal, env = process.env) {
+  if (!envFlag(env, "PI_RESEARCH_TINY_ROUTER_FOLLOWUP")) return null;
+
+  const strongRule = classifyFollowupWithStrongRules(query, mode, conflict, sources);
+  if (strongRule) return strongRule;
+
+  const config = resolveTinyRouterConfig(env);
+  if (!config.tasks.followup) return classifyFollowupHeuristically(query, mode, conflict, sources);
+
+  return requestTinyRouter(
+    config,
+    { task: "followup", query, mode, conflict, sources },
+    signal,
+    (result) => (result && !result.error && result.action && result.confidence >= 0.75
+      ? result.action
+      : classifyFollowupHeuristically(query, mode, conflict, sources)),
+  );
+}
+
+export async function classifyConflictWithTinyRouter(query, pages = [], signal, env = process.env) {
+  const config = resolveTinyRouterConfig(env);
+  if (!config.tasks.conflict) return null;
+
+  const features = extractConflictStructuredFeaturesFromPages(query, pages);
+  return requestTinyRouter(
+    config,
+    { task: "conflict", features },
+    signal,
+    (result) => (result && !result.error && result.decision && result.confidence >= 0.60 ? result.decision : null),
+  );
+}
+
+export async function classifySufficiencyWithTinyRouter(query, pages = [], signal, env = process.env) {
+  const config = resolveTinyRouterConfig(env);
+  if (!config.tasks.sufficiency) return null;
+
+  const features = extractSufficiencyStructuredFeaturesFromPages(query, pages);
+  return requestTinyRouter(
+    config,
+    { task: "sufficiency", features },
+    signal,
+    (result) => (result && !result.error && result.decision && result.confidence >= 0.75 ? result.decision : null),
+  );
+}