opencandle 0.6.0 → 0.7.0

package/src/runtime/tool-defaults-wrapper.ts

@@ -7,9 +7,19 @@ export function wrapWithDefaults<TParams extends TSchema, TDetails>(
 ): AgentTool<TParams, TDetails> {
   return {
     ...tool,
-    execute: async (toolCallId, params, signal, onUpdate) => {
+    execute: async (toolCallId, params, signal, onUpdate, ctx?: unknown) => {
       const merged = mergeDefaults(defaults, params as Record<string, unknown>);
-      return tool.execute(toolCallId, merged as typeof params, signal, onUpdate);
+      const executeWithContext = tool.execute as unknown as (
+        id: string,
+        params: unknown,
+        signal?: AbortSignal,
+        onUpdate?: unknown,
+        ctx?: unknown,
+      ) => ReturnType<typeof tool.execute>;
+      if (ctx === undefined) {
+        return executeWithContext(toolCallId, merged, signal, onUpdate);
+      }
+      return executeWithContext(toolCallId, merged, signal, onUpdate, ctx);
     },
   };
 }

package/src/sentiment/index.ts

@@ -1,6 +1,7 @@
 export { RedditAdapter } from "./adapters/reddit.js";
 export { TwitterAdapter } from "./adapters/twitter.js";
 export { WebAdapter } from "./adapters/web.js";
+export { buildSentimentInsight, labelForScore } from "./insights.js";
 export { BEARISH_TERMS, BULLISH_TERMS } from "./keywords.js";
 export { SentimentPipeline } from "./pipeline.js";
 export { keywordScore, scoreRecords } from "./scorer.js";

package/src/sentiment/insights.ts

@@ -0,0 +1,269 @@
+import type { SentimentConfig } from "../config.js";
+import type {
+  SentimentInsight,
+  SentimentInsightConfidence,
+  SentimentInsightDriver,
+  SentimentRepresentativeItem,
+} from "../types/sentiment.js";
+import type { SentimentSource, SentinelRecord } from "./types.js";
+
+const DEFAULT_MIN_SAMPLE = 10;
+const DEFAULT_DRIVER_CAP = 3;
+const DEFAULT_SOURCE_ITEM_CAP = 5;
+const DEFAULT_AGGREGATE_ITEM_CAP = 8;
+const DEFAULT_CLAIM_CAP = 5;
+
+export interface BuildSentimentInsightOptions {
+  query: string;
+  records: SentinelRecord[];
+  score?: number;
+  label?: string;
+  source?: SentimentSource | "aggregate";
+  missingSources?: string[];
+  sourceNotes?: string[];
+  config?: Partial<SentimentConfig>;
+  aggregate?: boolean;
+  extraCaveats?: string[];
+}
+
+interface TermBucket {
+  term: string;
+  count: number;
+  sourceIds: Set<string>;
+}
+
+export function buildSentimentInsight(options: BuildSentimentInsightOptions): SentimentInsight {
+  const records = options.records;
+  const scored = records.filter((record) => Math.abs(record.sentiment.score) > 0);
+  const score =
+    typeof options.score === "number"
+      ? options.score
+      : records.length > 0
+        ? records.reduce((sum, record) => sum + record.sentiment.score, 0) / records.length
+        : 0;
+  const sourceCounts = countBySource(records);
+  const positiveDrivers = driversFromTerms(records, "positive", options.config);
+  const negativeDrivers = driversFromTerms(records, "negative", options.config);
+  const caveats = buildCaveats(records, scored, sourceCounts, options);
+  const confidence = buildConfidence(records, scored, sourceCounts, caveats, options.config);
+  const representativeItems = representativeItemsFor(records, options);
+
+  return {
+    label: options.label ?? labelForScore(score),
+    score,
+    sampleSize: records.length,
+    scoredSampleSize: scored.length,
+    confidence,
+    positiveDrivers,
+    negativeDrivers,
+    mixedDrivers: buildMixedDrivers(positiveDrivers, negativeDrivers, score),
+    notableClaims: notableClaimsFor(records, options),
+    representativeItems,
+    sourceCoverage: {
+      sources: Object.keys(sourceCounts),
+      counts: sourceCounts,
+      missingSources: options.missingSources?.filter(Boolean),
+      notes: options.sourceNotes?.filter(Boolean),
+    },
+    caveats,
+    method: "deterministic-keyword-v1",
+  };
+}
+
+export function labelForScore(score: number): string {
+  if (score > 0.3) return "Bullish";
+  if (score < -0.3) return "Bearish";
+  if (score > 0) return "Leaning Bullish";
+  if (score < 0) return "Leaning Bearish";
+  return "Neutral";
+}
+
+function driversFromTerms(
+  records: SentinelRecord[],
+  polarity: "positive" | "negative",
+  config: Partial<SentimentConfig> | undefined,
+): SentimentInsightDriver[] {
+  const buckets = new Map<string, TermBucket>();
+  const metadataKey = polarity === "positive" ? "matchedBullishTerms" : "matchedBearishTerms";
+
+  for (const record of records) {
+    const terms = stringArray(record.metadata[metadataKey]);
+    for (const term of terms) {
+      const existing = buckets.get(term) ?? { term, count: 0, sourceIds: new Set<string>() };
+      existing.count += 1;
+      existing.sourceIds.add(record.sourceId);
+      buckets.set(term, existing);
+    }
+  }
+
+  return [...buckets.values()]
+    .sort((a, b) => b.count - a.count || a.term.localeCompare(b.term))
+    .slice(0, config?.maxInsightDriversPerPolarity ?? DEFAULT_DRIVER_CAP)
+    .map((bucket) => ({
+      label: bucket.term,
+      count: bucket.count,
+      polarity,
+      terms: [bucket.term],
+      sourceIds: [...bucket.sourceIds],
+    }));
+}
+
+function buildMixedDrivers(
+  positiveDrivers: SentimentInsightDriver[],
+  negativeDrivers: SentimentInsightDriver[],
+  score: number,
+): SentimentInsightDriver[] {
+  if (positiveDrivers.length === 0 || negativeDrivers.length === 0) return [];
+  if (Math.abs(score) > 0.3) return [];
+  return [
+    {
+      label: "offsetting bullish and bearish evidence",
+      count: Math.min(sumDriverCounts(positiveDrivers), sumDriverCounts(negativeDrivers)),
+      polarity: "mixed",
+      terms: [
+        ...positiveDrivers.flatMap((d) => d.terms),
+        ...negativeDrivers.flatMap((d) => d.terms),
+      ],
+      sourceIds: [
+        ...new Set([
+          ...positiveDrivers.flatMap((d) => d.sourceIds),
+          ...negativeDrivers.flatMap((d) => d.sourceIds),
+        ]),
+      ],
+    },
+  ];
+}
+
+function representativeItemsFor(
+  records: SentinelRecord[],
+  options: BuildSentimentInsightOptions,
+): SentimentRepresentativeItem[] {
+  const cap = options.aggregate
+    ? (options.config?.maxAggregateRepresentativeItems ?? DEFAULT_AGGREGATE_ITEM_CAP)
+    : (options.config?.maxRepresentativeItemsPerSource ?? DEFAULT_SOURCE_ITEM_CAP);
+
+  return [...records]
+    .sort((a, b) => itemRank(b) - itemRank(a))
+    .slice(0, cap)
+    .map((record) => ({
+      source: record.source,
+      sourceId: record.sourceId,
+      title: record.title,
+      excerpt: excerptFor(record),
+      url: record.url || null,
+      author: record.author,
+      publishedAt: record.publishedAt,
+      engagement: Number.isFinite(record.engagement.score) ? record.engagement.score : null,
+      score: record.sentiment.score,
+      matchedTerms: [
+        ...stringArray(record.metadata.matchedBullishTerms),
+        ...stringArray(record.metadata.matchedBearishTerms),
+      ],
+      metadata: record.metadata,
+    }));
+}
+
+function notableClaimsFor(
+  records: SentinelRecord[],
+  options: BuildSentimentInsightOptions,
+): string[] {
+  const cap = options.config?.maxNotableClaims ?? DEFAULT_CLAIM_CAP;
+  const claims = new Set<string>();
+  for (const record of representativeItemsFor(records, { ...options, aggregate: false })) {
+    const claim = record.title ?? record.excerpt;
+    if (claim) claims.add(claim);
+    if (claims.size >= cap) break;
+  }
+  return [...claims];
+}
+
+function buildConfidence(
+  records: SentinelRecord[],
+  scored: SentinelRecord[],
+  sourceCounts: Record<string, number>,
+  caveats: string[],
+  config: Partial<SentimentConfig> | undefined,
+): SentimentInsightConfidence {
+  const minSample = config?.minUsefulSampleSize ?? DEFAULT_MIN_SAMPLE;
+  const sampleRatio = Math.min(records.length / minSample, 1);
+  const scoredRatio = records.length === 0 ? 0 : scored.length / records.length;
+  const coverageRatio = Math.min(Object.keys(sourceCounts).length / 3, 1);
+  let score = sampleRatio * 0.4 + scoredRatio * 0.4 + coverageRatio * 0.2;
+  const reasons: string[] = [];
+
+  if (records.length < minSample) {
+    reasons.push(`low sample size (${records.length}/${minSample})`);
+  }
+  if (scoredRatio < 0.5) {
+    reasons.push("most records were neutral or had no keyword sentiment match");
+  }
+  if (Object.keys(sourceCounts).length <= 1) {
+    reasons.push("single-source sentiment coverage");
+  }
+  if (caveats.length > 0) {
+    score -= Math.min(0.2, caveats.length * 0.05);
+  }
+
+  score = clamp01(score);
+  return {
+    level: score >= 0.7 ? "high" : score >= 0.4 ? "medium" : "low",
+    score,
+    reasons,
+  };
+}
+
+function buildCaveats(
+  records: SentinelRecord[],
+  scored: SentinelRecord[],
+  sourceCounts: Record<string, number>,
+  options: BuildSentimentInsightOptions,
+): string[] {
+  const minSample = options.config?.minUsefulSampleSize ?? DEFAULT_MIN_SAMPLE;
+  const caveats = [...(options.extraCaveats ?? [])];
+  if (records.length < minSample) caveats.push(`Low sample size: ${records.length} records.`);
+  if (records.length > 0 && scored.length === 0)
+    caveats.push("No records contained keyword sentiment matches.");
+  if (records.length > 0 && scored.length / records.length < 0.5) {
+    caveats.push("Most records were neutral or unscored by keyword matching.");
+  }
+  if (Object.keys(sourceCounts).length <= 1) caveats.push("Single-source sentiment coverage.");
+  if (options.missingSources && options.missingSources.length > 0) {
+    caveats.push(`Missing sources: ${options.missingSources.join(", ")}.`);
+  }
+  return [...new Set(caveats)];
+}
+
+function countBySource(records: SentinelRecord[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const record of records) {
+    counts[record.source] = (counts[record.source] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function sumDriverCounts(drivers: SentimentInsightDriver[]): number {
+  return drivers.reduce((sum, driver) => sum + driver.count, 0);
+}
+
+function itemRank(record: SentinelRecord): number {
+  const sentimentWeight = Math.abs(record.sentiment.score) * 100;
+  const confidenceWeight = record.sentiment.confidence * 20;
+  const engagementWeight = Math.log10(Math.max(0, record.engagement.score) + 1);
+  return sentimentWeight + confidenceWeight + engagementWeight;
+}
+
+function excerptFor(record: SentinelRecord): string {
+  const raw = record.title ? `${record.title} ${record.text}` : record.text;
+  const normalized = raw.replace(/\s+/g, " ").trim();
+  return normalized.length > 220 ? `${normalized.slice(0, 219)}…` : normalized;
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}

package/src/sentiment/pipeline.ts

@@ -1,4 +1,5 @@
 import type { SentimentConfig } from "../config.js";
+import { buildSentimentInsight } from "./insights.js";
 import { scoreRecords } from "./scorer.js";
 import type { SentimentStore } from "./store.js";
 import { computeDivergence, computeTrend, type SourceStats } from "./trends.js";
@@ -65,7 +66,18 @@ export class SentimentPipeline {
       divergence = computeDivergence(sourceStats, this.config.divergenceThreshold);
     }
 
-    return { fresh: scored, trend, divergence, warnings };
+    return {
+      fresh: scored,
+      trend,
+      divergence,
+      warnings,
+      insight: buildSentimentInsight({
+        query,
+        records: scored,
+        config: this.config,
+        aggregate: true,
+      }),
+    };
   }
 }
 

package/src/sentiment/scorer.ts

@@ -7,6 +7,8 @@ interface ScoreResult {
   score: number;
   confidence: number;
   tickers: string[];
+  bullishTerms: string[];
+  bearishTerms: string[];
 }
 
 export function keywordScore(record: SentinelRecord): ScoreResult {
@@ -17,11 +19,14 @@ export function keywordScore(record: SentinelRecord): ScoreResult {
   let bearishWeight = 0;
   let bullishCount = 0;
   let bearishCount = 0;
+  const bullishTerms: string[] = [];
+  const bearishTerms: string[] = [];
 
   for (const term of BULLISH_TERMS) {
     if (lower.includes(term)) {
       bullishCount++;
       bullishWeight += engagement;
+      bullishTerms.push(term);
     }
   }
 
@@ -29,6 +34,7 @@ export function keywordScore(record: SentinelRecord): ScoreResult {
     if (lower.includes(term)) {
       bearishCount++;
       bearishWeight += engagement;
+      bearishTerms.push(term);
     }
   }
 
@@ -59,7 +65,7 @@ export function keywordScore(record: SentinelRecord): ScoreResult {
     }
   }
 
-  return { score, confidence, tickers };
+  return { score, confidence, tickers, bullishTerms, bearishTerms };
 }
 
 export function scoreRecords(records: SentinelRecord[]): SentinelRecord[] {
@@ -73,6 +79,11 @@ export function scoreRecords(records: SentinelRecord[]): SentinelRecord[] {
         method: "keyword" as const,
         tickers: result.tickers,
       },
+      metadata: {
+        ...record.metadata,
+        matchedBullishTerms: result.bullishTerms,
+        matchedBearishTerms: result.bearishTerms,
+      },
     };
   });
 }

package/src/sentiment/types.ts

@@ -1,3 +1,5 @@
+import type { SentimentInsight } from "../types/sentiment.js";
+
 export const SENTIMENT_SOURCES = ["twitter", "reddit", "web", "finnhub"] as const;
 export type SentimentSource = (typeof SENTIMENT_SOURCES)[number];
 
@@ -106,4 +108,5 @@ export interface SentimentSummary {
   trend: TrendResult[] | null;
   divergence: DivergenceResult | null;
   warnings: string[];
+  insight?: SentimentInsight;
 }

package/src/system-prompt.ts

@@ -20,7 +20,7 @@ You are an analyst, not a fiduciary advisor. When asked for entry levels, price
 - **Sentiment**: get_reddit_sentiment, get_twitter_sentiment, get_web_sentiment, get_sentiment_trend, get_sentiment_summary — retail and news sentiment from Reddit, Twitter/X, and web sources with historical trends
 - **Options**: get_option_chain — full options chain with strikes, bids/asks, volume, OI, IV, and computed Greeks (delta, gamma, theta, vega, rho)
 - **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, track_prediction, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, correlation matrix, and prediction tracking with accuracy scoring
-- **User Interaction**: ask_user — ask clarification questions; trigger_twitter_login — open a browser for Twitter/X login
+- **User Interaction**: ask_user — ask clarification questions and setup confirmations
 
 ## Analytical Framework
 When analyzing a stock, follow these steps in order:
@@ -80,12 +80,8 @@ Do NOT ask clarifying questions when:
 
 Keep questions concise and offer specific options when possible. Prefer select-type questions over open-ended text input to minimize user effort.
 
-## Twitter Authentication
-get_twitter_sentiment requires a one-time Twitter/X login. When the tool returns [LOGIN_NEEDED]:
-1. Use ask_user (confirm) to ask: "Twitter sentiment requires a one-time login. A browser will open — want to proceed?"
-2. If confirmed, call trigger_twitter_login. It opens a browser, waits for the user to log in, and returns success/failure.
-3. On success, retry get_twitter_sentiment with the original query.
-If the user declines, skip Twitter sentiment and continue with other available data sources.
+## Twitter/X External Tool Setup
+get_twitter_sentiment uses the external twitter-cli command and the user's normal browser session. If the tool says twitter-cli is missing, ask the user whether they want to install it with \`uv tool install twitter-cli\`, skip X for this query, or always skip X. If the tool says browser cookies or the X session are missing or stale, ask the user to log into or refresh x.com in a supported browser, then retry only after they confirm. Do not use the retired browser-login tool.
 
 ## After Clarification: Fetch Data Immediately
 CRITICAL: After ask_user answers come back, your NEXT action MUST be tool calls — not a text response. You are a data agent, not a chatbot. Never respond with generic investment categories or tell the user to come back with tickers. YOU pick the relevant assets and indicators based on what you learned, then fetch the data.

package/src/tools/index.ts

@@ -1,4 +1,5 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { AskUserHandler } from "../types/index.js";
 import { companyOverviewTool } from "./fundamentals/company-overview.js";
 import { compsTool } from "./fundamentals/comps.js";
 import { dcfTool } from "./fundamentals/dcf.js";
@@ -23,10 +24,10 @@ import { predictionsTool } from "./portfolio/predictions.js";
 import { riskAnalysisTool } from "./portfolio/risk-analysis.js";
 import { portfolioTrackerTool } from "./portfolio/tracker.js";
 import { watchlistTool } from "./portfolio/watchlist.js";
-import { redditSentimentTool } from "./sentiment/reddit-sentiment.js";
-import { sentimentSummaryTool } from "./sentiment/sentiment-summary.js";
+import { createRedditSentimentTool } from "./sentiment/reddit-sentiment.js";
+import { createSentimentSummaryTool } from "./sentiment/sentiment-summary.js";
 import { sentimentTrendTool } from "./sentiment/sentiment-trend.js";
-import { twitterSentimentTool } from "./sentiment/twitter-sentiment.js";
+import { createTwitterSentimentTool } from "./sentiment/twitter-sentiment.js";
 import { webSearchTool } from "./sentiment/web-search.js";
 import { webSentimentTool } from "./sentiment/web-sentiment.js";
 import { backtestTool } from "./technical/backtest.js";
@@ -57,7 +58,7 @@ export { riskAnalysisTool } from "./portfolio/risk-analysis.js";
 export { portfolioTrackerTool } from "./portfolio/tracker.js";
 export { watchlistTool } from "./portfolio/watchlist.js";
 export { redditSentimentTool } from "./sentiment/reddit-sentiment.js";
-export { sentimentSummaryTool } from "./sentiment/sentiment-summary.js";
+export { createSentimentSummaryTool, sentimentSummaryTool } from "./sentiment/sentiment-summary.js";
 export { sentimentTrendTool } from "./sentiment/sentiment-trend.js";
 export { twitterSentimentTool } from "./sentiment/twitter-sentiment.js";
 export { webSearchTool } from "./sentiment/web-search.js";
@@ -65,7 +66,7 @@ export { webSentimentTool } from "./sentiment/web-sentiment.js";
 export { backtestTool } from "./technical/backtest.js";
 export { technicalIndicatorsTool } from "./technical/indicators.js";
 
-export function getAllTools(): AgentTool<any>[] {
+export function getAllTools(options: { askUserHandler?: AskUserHandler } = {}): AgentTool<any>[] {
   return [
     searchTickerTool,
     stockQuoteTool,
@@ -81,8 +82,8 @@ export function getAllTools(): AgentTool<any>[] {
     secFilingsTool,
     fredDataTool,
     fearGreedTool,
-    redditSentimentTool,
-    twitterSentimentTool,
+    createRedditSentimentTool({ askUserHandler: options.askUserHandler }),
+    createTwitterSentimentTool({ askUserHandler: options.askUserHandler }),
     technicalIndicatorsTool,
     backtestTool,
     portfolioTrackerTool,
@@ -98,6 +99,6 @@ export function getAllTools(): AgentTool<any>[] {
     webSearchTool,
     webSentimentTool,
     sentimentTrendTool,
-    sentimentSummaryTool,
+    createSentimentSummaryTool({ askUserHandler: options.askUserHandler }),
   ];
 }

package/src/tools/sentiment/insight-format.ts

@@ -0,0 +1,50 @@
+import type { SentimentInsight } from "../../types/sentiment.js";
+import { renderUntrustedText } from "./untrusted-text.js";
+
+export function formatInsightSection(insight: SentimentInsight): string[] {
+  const lines: string[] = [];
+  lines.push("");
+  lines.push("Findings:");
+  lines.push(
+    `- Overall: ${insight.label} (${formatSigned(insight.score)}) from ${insight.sampleSize} records; ${insight.scoredSampleSize} had keyword sentiment evidence.`,
+  );
+  lines.push(
+    `- Confidence: ${insight.confidence.level} (${insight.confidence.score.toFixed(2)})${
+      insight.confidence.reasons.length > 0 ? ` — ${insight.confidence.reasons.join("; ")}` : ""
+    }`,
+  );
+  appendDrivers(lines, "Positive drivers", insight.positiveDrivers);
+  appendDrivers(lines, "Negative drivers", insight.negativeDrivers);
+  appendDrivers(lines, "Mixed drivers", insight.mixedDrivers);
+  if (insight.caveats.length > 0) {
+    lines.push(`- Caveats: ${insight.caveats.join("; ")}`);
+  }
+  if (insight.notableClaims.length > 0) {
+    lines.push("- Notable source claims:");
+    for (const claim of insight.notableClaims.slice(0, 3)) {
+      lines.push(`  - ${renderUntrustedText(claim, 140)}`);
+    }
+  }
+  if (insight.representativeItems.length > 0) {
+    lines.push(
+      `- Representative evidence preview: ${insight.representativeItems.length} shown from ${insight.scoredSampleSize} scored records (${insight.sampleSize} total records).`,
+    );
+  }
+  return lines;
+}
+
+function appendDrivers(
+  lines: string[],
+  label: string,
+  drivers: SentimentInsight["positiveDrivers"],
+): void {
+  if (drivers.length === 0) return;
+  const rendered = drivers
+    .map((driver) => `${renderUntrustedText(driver.label, 60)} (${driver.count})`)
+    .join(", ");
+  lines.push(`- ${label}: ${rendered}`);
+}
+
+function formatSigned(value: number): string {
+  return `${value >= 0 ? "+" : ""}${value.toFixed(2)}`;
+}

package/src/tools/sentiment/query-match.ts

@@ -0,0 +1,117 @@
+import { extractEntities } from "../../routing/entity-extractor.js";
+import type { SentinelRecord } from "../../sentiment/types.js";
+
+const STOP_TERMS = new Set([
+  "about",
+  "around",
+  "are",
+  "from",
+  "how",
+  "is",
+  "latest",
+  "mood",
+  "now",
+  "on",
+  "or",
+  "people",
+  "reddit",
+  "retail",
+  "right",
+  "say",
+  "saying",
+  "says",
+  "sentiment",
+  "social",
+  "stock",
+  "stocks",
+  "talking",
+  "the",
+  "think",
+  "thinking",
+  "to",
+  "tweet",
+  "tweets",
+  "twitter",
+  "what",
+  "with",
+]);
+
+export function sentimentQueryTerms(query: string): string[] {
+  const hasSp500 = /\bs\s*&\s*p\s*500\b/i.test(query) || /\bspx\b/i.test(query);
+
+  const symbols = hasSp500
+    ? ["sp500"]
+    : extractEntities(query).symbols.map((symbol) => symbol.toLowerCase());
+  const punctuationTerms = [...query.toLowerCase().matchAll(/\b([a-z])\s*[&/]\s*([a-z])\b/g)].map(
+    (match) => `${match[1]}${match[2]}`,
+  );
+  const terms = query.toLowerCase().match(/[a-z0-9]{2,}/g);
+  if (!terms) {
+    if (punctuationTerms.length > 0) return [...new Set(punctuationTerms)];
+    const compact = query.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (compact.length >= 2) return [compact];
+    return query.trim().length > 0 ? [query.trim().toLowerCase()] : [];
+  }
+
+  const stopTerms = hasSp500 ? new Set([...STOP_TERMS, "sp", "spx", "500"]) : STOP_TERMS;
+  const filtered = [
+    ...new Set([...punctuationTerms, ...terms.filter((term) => !stopTerms.has(term))]),
+  ].slice(0, 6);
+  if (symbols.length > 0) {
+    return [
+      ...new Set([
+        ...symbols,
+        ...filtered.filter((term) => !symbols.some((symbol) => symbol.startsWith(term))),
+      ]),
+    ].slice(0, 6);
+  }
+  if (filtered.length > 0) return filtered;
+  return query.trim().length > 0 ? [query.trim().toLowerCase()] : [];
+}
+
+export function recordMatchesSentimentQuery(
+  record: SentinelRecord,
+  terms: readonly string[],
+): boolean {
+  if (terms.length === 0) return true;
+  const text = `${record.title ?? ""}\n${record.text}`.toLowerCase();
+  const textTokens = new Set(text.match(/[a-z0-9]+/g) ?? []);
+  const metadataTokens = new Set<string>();
+  const subreddit = record.metadata.subreddit;
+  if (typeof subreddit === "string") {
+    metadataTokens.add(subreddit.toLowerCase());
+    metadataTokens.add(subreddit.toLowerCase().replace(/^r\//, ""));
+  }
+  if (/\bs\s*&\s*p\s*500\b/i.test(text) || /\bspx\b/i.test(text)) textTokens.add("sp500");
+  for (const match of text.matchAll(/\b([a-z])\s*[&/]\s*([a-z])\b/g)) {
+    textTokens.add(`${match[1]}${match[2]}`);
+  }
+  for (const match of text.matchAll(/\b([a-z]{1,5})[.-]([a-z])\b/g)) {
+    textTokens.add(`${match[1]}${match[2]}`);
+  }
+  const tickerTokens = new Set<string>();
+  for (const ticker of record.sentiment.tickers) {
+    const normalized = ticker.toLowerCase();
+    tickerTokens.add(normalized);
+    tickerTokens.add(normalized.replace(/[^a-z0-9]/g, ""));
+  }
+  const matchedTerms = terms.filter(
+    (term) => tickerTokens.has(term) || textTokens.has(term) || metadataTokens.has(term),
+  );
+  for (const term of terms) {
+    if (matchedTerms.includes(term) || !term.includes(" ")) continue;
+    if (text.includes(term)) matchedTerms.push(term);
+  }
+  for (const term of terms) {
+    if (matchedTerms.includes(term) || term.length < 4) continue;
+    if (textTokens.has(`${term}s`)) {
+      matchedTerms.push(term);
+      continue;
+    }
+    if (term.endsWith("s") && textTokens.has(term.slice(0, -1))) {
+      matchedTerms.push(term);
+    }
+  }
+  const requiredMatches = terms.length > 1 ? 2 : 1;
+  return matchedTerms.length >= requiredMatches;
+}