@signal4/s4 2.6.1 → 2.8.0

package/dist/speed.js

@@ -0,0 +1,214 @@
+/** How long a call should take — one source for tool descriptions, CLI help, the
+ * progress notice a slow call sends before it starts, and the "took Ns" footer.
+ *
+ * Tiers, by the typical time (geometric mean of the range):
+ *   instant  < 0.5s     fast  0.5–2.5s     slow  > 2.5s
+ *
+ * Every number is measured, not guessed: the 100-plan replay against the live API
+ * (2026-10-15/16, ~/logs/search_eval/replay-2026-10-15.jsonl — per-tool p50/p90) and the
+ * VPS before/after runs for the counting engine (signal4#292, #296). Semantic tools pay
+ * ~1s for the query embedding before they scan; a scan costs roughly 0.15–0.35s per
+ * month of window over the whole corpus. Update the table when a tool gets faster. */
+const INSTANT_MAX = 0.5;
+const FAST_MAX = 2.5;
+/** Responses that took longer than this say how long. */
+export const REPORT_ELAPSED_OVER_S = 2.5;
+const EMBED_S = 1.0;
+export function tierOf(lo, hi) {
+    const typical = Math.sqrt(Math.max(lo, 0.01) * Math.max(hi, 0.01));
+    if (typical < INSTANT_MAX)
+        return "instant";
+    if (typical <= FAST_MAX)
+        return "fast";
+    return "slow";
+}
+function est(lo, hi, why) {
+    return { tier: tierOf(lo, hi), lo, hi, why };
+}
+/** Fixed-cost tools: [lo, hi] seconds from the replay (p50-ish, p90). */
+const BASE = {
+    get_segment: [0.1, 0.2],
+    get_segment_sentences: [0.1, 0.3],
+    get_thread: [0.1, 0.4],
+    get_claim: [0.1, 0.4],
+    list_collections: [0.1, 0.3],
+    manage_bookmarks: [0.1, 0.4],
+    find_speakers: [0.2, 0.8],
+    get_platform_stats: [0.2, 1],
+    get_collection_stats: [0.2, 1],
+    get_project_stats: [0.2, 1],
+    get_speaker: [0.2, 2.5],
+    claim_graph: [0.3, 1.6],
+    get_channel: [0.3, 1.2],
+    get_episode: [0.5, 2],
+    channel_dossier: [0.5, 1.6],
+    compare_channels: [0.7, 1.5],
+    get_top_channels: [0.5, 2.5],
+    analyze_claims: [0.8, 2.3],
+    contradict_claims: [0.8, 4.4],
+    compare_claims: [0.8, 4],
+    check_channel_contradictions: [0.8, 4],
+    find_entities: [0.1, 1.2],
+    trend_claims: [1, 3.5],
+    get_top_speakers: [1.5, 3.5],
+    get_speaker_network: [1, 5],
+    get_ad_analytics: [0.5, 3],
+    // Warm 0.2–2.8s; the largest entities (Donald Trump, Ukraine) up to ~6s cold (signal4#317).
+    entity_claims: [0.3, 6],
+    top_claims: [2, 8],
+    get_topics: [3, 19],
+    // Paid LLM pipelines (their own descriptions carry these ranges).
+    get_briefing: [2, 10],
+    analyze_topic: [15, 45],
+    compare_speakers: [15, 45],
+    build_dossier: [15, 45],
+    check_contradictions: [15, 45],
+    compare_frames: [30, 60],
+};
+/** Window length in months from days / start_date / end_date (YYYY, YYYY-MM, YYYY-MM-DD). */
+export function windowMonths(params, defaultDays = 30) {
+    const today = Date.now();
+    const parse = (v, edge) => {
+        if (typeof v !== "string" || !v)
+            return undefined;
+        const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?$/.exec(v.trim());
+        if (!m)
+            return undefined;
+        const y = Number(m[1]);
+        const mo = m[2] ? Number(m[2]) - 1 : edge === "start" ? 0 : 11;
+        const d = m[3] ? Number(m[3]) : edge === "start" ? 1 : 28;
+        return Date.UTC(y, mo, d);
+    };
+    const start = parse(params.start_date, "start");
+    const end = parse(params.end_date, "end") ?? today;
+    const days = start != null
+        ? (end - start) / 86400000
+        : Number(params.days ?? params.baseline_days ?? defaultDays) || defaultDays;
+    return Math.max(days / 30.4, 0.25);
+}
+/** Whole-corpus semantic scan cost for a window: ~0.2–0.35s per month up to two years,
+ * thin before that. Measured on the VPS: 1 month 0.2–0.7s, 12 months 2.4–3.6s, all time 5–8s. */
+function scanCost(months) {
+    const recent = Math.min(months, 24);
+    const older = Math.max(months - 24, 0);
+    const lo = 0.2 + 0.15 * recent;
+    // All time measured 4.7s warm, 7–8.5s just after cache churn (signal4#238).
+    const hi = Math.min(0.8 + 0.35 * recent + 0.02 * older, 9);
+    return [lo, hi];
+}
+function monthsLabel(months) {
+    if (months >= 120)
+        return "all time";
+    if (months >= 23)
+        return `${Math.round(months / 12)} years`;
+    if (months >= 1.5)
+        return `${Math.round(months)} months`;
+    return `${Math.max(1, Math.round(months * 30.4))} days`;
+}
+/** The estimate for one call. Unknown tools are "fast" with a wide range. */
+export function estimate(tool, params = {}) {
+    const speaker = params.speaker ?? params.speaker_name ?? params.speaker_id;
+    const keyword = params.mode === "keyword" || typeof params.keyword === "string";
+    switch (tool) {
+        case "search_quotes": {
+            if (params.full_history)
+                return est(2, 15, "exact scan of a speaker's whole history");
+            const m = windowMonths(params);
+            if (keyword) {
+                return est(0.3, speaker ? 4 : 1.5, `keyword search, newest first, ${monthsLabel(m)}`);
+            }
+            if (!params.topic)
+                return est(0.2, 2, "listing by speaker or channel");
+            const [lo, hi] = scanCost(m);
+            // Deep pages rerank more candidates: rank 1,000 ~+1s, rank 2,000 ~+3s (signal4#329).
+            const deep = Math.min(Number(params.offset ?? 0), 2000) / 2000 * 3;
+            return est(EMBED_S + lo + deep / 2, EMBED_S + hi + 0.5 + deep + (speaker ? 4 : 0), `semantic search over ${monthsLabel(m)}${speaker ? " for one speaker" : ""}${deep ? ", deep page" : ""}`);
+        }
+        case "count_mentions": {
+            if (params.group_by === "speaker") {
+                // Folding speaker rows onto people reads `speakers`: 0.1–3s warm, up to ~7s cold (signal4#318).
+                const base = estimate("count_mentions", { ...params, group_by: "none" });
+                return est(base.lo + 0.2, base.hi + 5, `${base.why}, ranked by speaker`);
+            }
+            const m = windowMonths(params);
+            if (keyword) {
+                const hi = m <= 3 ? 2 : m <= 12 ? 6 : 15;
+                return est(0.3, hi + (speaker ? 6 : 0), `exact keyword count over ${monthsLabel(m)} (very common words take longest)`);
+            }
+            if (!params.topic && !params.topics)
+                return est(0.3, m <= 3 ? 2 : 8, `count of everything in scope over ${monthsLabel(m)}`);
+            const [lo, hi] = scanCost(m);
+            return est(EMBED_S + lo, EMBED_S + hi + (speaker ? 10 : 0), `semantic count over ${monthsLabel(m)}${speaker ? " for one speaker" : ""}`);
+        }
+        case "get_timeline":
+        case "detect_trend": {
+            const m = windowMonths(params, tool === "detect_trend" ? Number(params.baseline_days ?? 30) || 30 : 30);
+            const [lo, hi] = scanCost(m);
+            return est(EMBED_S + lo, EMBED_S + hi + (speaker ? 10 : 0), `semantic count over ${monthsLabel(m)}`);
+        }
+        case "get_top_channels":
+            if (params.topic)
+                return est(1, 8, "which channels say the most about the topic, from the transcripts");
+            return est(BASE.get_top_channels[0], BASE.get_top_channels[1]);
+        case "get_top_speakers":
+            if (params.topic)
+                return est(1, 8, "who talks most about the topic, from the transcripts");
+            return est(BASE.get_top_speakers[0], BASE.get_top_speakers[1]);
+        case "get_claim":
+            return params.include_related ? est(0.3, 1.5, "claim detail plus related claims") : est(0.1, 0.4);
+        case "search_claims": {
+            if (params.entity)
+                return est(1, 5, "claims search filtered by entity");
+            if (keyword)
+                return est(0.3, 2, "claims keyword search");
+            return est(1.5, 10, "semantic claims search");
+        }
+        default: {
+            const b = BASE[tool];
+            return b ? est(b[0], b[1]) : est(0.5, 5);
+        }
+    }
+}
+/** 0.1–0.9 to one decimal, 1–10 to the half second, then whole seconds. */
+function secs(n) {
+    if (n < 1)
+        return Math.max(n, 0.1).toFixed(1);
+    return n < 10 ? String(Math.round(n * 2) / 2) : String(Math.round(n));
+}
+/** "instant" · "fast ~1–2s" · "slow ~3–8s". */
+export function label(e) {
+    if (e.tier === "instant")
+        return "instant";
+    return `${e.tier} ~${secs(e.lo)}–${secs(e.hi)}s`;
+}
+/** The speed line a tool description starts with, e.g. "[slow ~15–45s · paid LLM]".
+ * Tools whose time depends on the window carry a short scale ("…; 12 months ~3–6s"). */
+export function descriptionTag(tool, paid = false) {
+    const windowed = ["search_quotes", "count_mentions", "get_timeline", "detect_trend"].includes(tool);
+    // The usual call: a topic, default (30-day) window, semantic.
+    const base = estimate(tool, windowed ? { topic: "x" } : {});
+    let scale = "";
+    if (windowed) {
+        const year = estimate(tool, { days: 365, topic: "x" });
+        const all = estimate(tool, { start_date: "2010", topic: "x" });
+        scale = `; 12 months ${label(year).replace(/^\w+ /, "")}, all time ${label(all).replace(/^\w+ /, "")}`;
+    }
+    return `[${label(base)}${scale}${paid ? " · paid LLM" : ""}]`;
+}
+/** Replace the speed/price bracket a backend description starts with by ours,
+ * keeping the paid marker. */
+export function decorateDescription(tool, description) {
+    const m = /^\[([^\]]*)\]\s*/.exec(description);
+    const paid = m ? /paid/i.test(m[1]) : false;
+    const rest = m ? description.slice(m[0].length) : description;
+    return `${descriptionTag(tool, paid)} ${rest}`;
+}
+/** The notice a slow call sends before it starts (MCP progress, CLI stderr). */
+export function startNotice(e) {
+    return `Estimated ${secs(e.lo)}–${secs(e.hi)}s${e.why ? `: ${e.why}` : ""}.`;
+}
+/** Footer for a response that took longer than REPORT_ELAPSED_OVER_S. */
+export function elapsedFooter(ms) {
+    return ms / 1000 > REPORT_ELAPSED_OVER_S ? `\n_Took ${(ms / 1000).toFixed(1)}s._` : "";
+}
+//# sourceMappingURL=speed.js.map

package/dist/speed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speed.js","sourceRoot":"","sources":["../src/speed.ts"],"names":[],"mappings":"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"}

package/dist/surface.d.ts

@@ -0,0 +1,7 @@
+/** Which front end is rendering: next-step hints use CLI or MCP call syntax. */
+export type Surface = "cli" | "mcp";
+export declare function setSurface(s: Surface): void;
+export declare function getSurface(): Surface;
+/** Rewrite an MCP-style call hint (`get_segment seg:42`, `offset:20`) to CLI syntax when running as the CLI. */
+export declare function hint(mcp: string): string;
+//# sourceMappingURL=surface.d.ts.map

package/dist/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC;AAIpC,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAiB;AAC7D,wBAAgB,UAAU,IAAI,OAAO,CAAoB;AAEzD,gHAAgH;AAChH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWxC"}

package/dist/surface.js

@@ -0,0 +1,19 @@
+/** Which front end is rendering: next-step hints use CLI or MCP call syntax. */
+let current = "mcp";
+export function setSurface(s) { current = s; }
+export function getSurface() { return current; }
+/** Rewrite an MCP-style call hint (`get_segment seg:42`, `offset:20`) to CLI syntax when running as the CLI. */
+export function hint(mcp) {
+    if (current !== "cli")
+        return mcp;
+    return mcp
+        .replace(/get_segment seg:(\d+)/g, "s4 segment $1")
+        .replace(/get_speaker speaker_id:(\d+)/g, "s4 speaker $1")
+        .replace(/get_claim claim:(\d+)( include_observations:true)?/g, (_m, id, o) => `s4 claim ${id}${o ? " --observations" : ""}`)
+        .replace(/get_thread segment_id:(\d+)( max_chars:0)?/g, "s4 thread $1")
+        .replace(/get_episode content_id:(\S+?)( include_transcript:true)?(?=$|[\s·\]])/g, (_m, id, t) => `s4 episode ${id}${t ? " --transcript" : ""}`)
+        .replace(/search_quotes topic:("[^"]*") start_date:(\S+)/g, "s4 search $1 --since $2")
+        .replace(/\bobservations_offset:(\d+)/g, "--obs-offset $1")
+        .replace(/\boffset:(\d+)/g, "--offset $1");
+}
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAIhF,IAAI,OAAO,GAAY,KAAK,CAAC;AAE7B,MAAM,UAAU,UAAU,CAAC,CAAU,IAAU,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7D,MAAM,UAAU,UAAU,KAAc,OAAO,OAAO,CAAC,CAAC,CAAC;AAEzD,gHAAgH;AAChH,MAAM,UAAU,IAAI,CAAC,GAAW;IAC9B,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,GAAG;SACP,OAAO,CAAC,wBAAwB,EAAE,eAAe,CAAC;SAClD,OAAO,CAAC,+BAA+B,EAAE,eAAe,CAAC;SACzD,OAAO,CAAC,qDAAqD,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;SAC5H,OAAO,CAAC,6CAA6C,EAAE,cAAc,CAAC;SACtE,OAAO,CAAC,wEAAwE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;SAC/I,OAAO,CAAC,iDAAiD,EAAE,yBAAyB,CAAC;SACrF,OAAO,CAAC,8BAA8B,EAAE,iBAAiB,CAAC;SAC1D,OAAO,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;AAC/C,CAAC"}