opencandle 0.4.0 → 0.5.0

package/src/providers/yahoo-finance.ts

@@ -3,10 +3,12 @@ import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
 import { StealthBrowser } from "../infra/browser.js";
 import type { StockQuote, OHLCV } from "../types/market.js";
-import type { OptionsChain, OptionContract } from "../types/options.js";
+import type { OptionsChain, OptionContract, OptionsMarketSession, OptionsQuoteStatus } from "../types/options.js";
+import type { FundHoldings } from "../types/portfolio.js";
 import { computeGreeks } from "../tools/options/greeks.js";
 
 const BASE_URL = "https://query1.finance.yahoo.com/v8/finance/chart";
+const QUOTE_SUMMARY_URL = "https://query1.finance.yahoo.com/v10/finance/quoteSummary";
 
 interface YahooChartResponse {
   chart: {
@@ -28,6 +30,29 @@ interface YahooChartResponse {
   };
 }
 
+interface YahooQuoteSummaryResponse {
+  quoteSummary: {
+    result?: Array<{
+      price?: {
+        symbol?: string;
+        shortName?: string;
+        longName?: string;
+      };
+      topHoldings?: {
+        holdings?: Array<{
+          symbol?: string;
+          holdingName?: string;
+          holdingPercent?: number;
+        }>;
+        equityHoldings?: {
+          sectorWeightings?: Array<Record<string, number>>;
+        };
+      };
+    }>;
+    error?: { code?: string; description?: string } | null;
+  };
+}
+
 export async function getQuote(symbol: string): Promise<StockQuote> {
   const cacheKey = `yahoo:quote:${symbol}`;
   const cached = cache.get<StockQuote>(cacheKey);
@@ -128,6 +153,80 @@ export async function getHistory(
   }
 }
 
+export async function getFundHoldings(symbol: string): Promise<FundHoldings> {
+  const normalizedSymbol = symbol.toUpperCase();
+  const cacheKey = `yahoo:fund-holdings:${normalizedSymbol}`;
+  const cached = cache.get<FundHoldings>(cacheKey);
+  if (cached) return cached;
+
+  try {
+    await rateLimiter.acquire("yahoo");
+
+    const modules = encodeURIComponent("price,topHoldings");
+    const url = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(normalizedSymbol)}?modules=${modules}`;
+    const data = await httpGet<YahooQuoteSummaryResponse>(url, {
+      headers: { "User-Agent": "OpenCandle/1.0" },
+    });
+    const result = data.quoteSummary.result?.[0];
+    if (data.quoteSummary.error) {
+      throw new Error(`Yahoo Finance: ${data.quoteSummary.error.description ?? data.quoteSummary.error.code ?? "quoteSummary error"}`);
+    }
+    if (!result?.topHoldings?.holdings?.length) {
+      throw new Error(`Yahoo Finance: no fund holdings returned for ${normalizedSymbol}`);
+    }
+
+    const holdings: FundHoldings = {
+      symbol: result.price?.symbol?.toUpperCase() ?? normalizedSymbol,
+      name: result.price?.shortName ?? result.price?.longName,
+      provider: "yahoo",
+      holdings: result.topHoldings.holdings.flatMap((holding) => {
+        const holdingSymbol = holding.symbol?.trim().toUpperCase();
+        const weight = normalizeHoldingWeight(holding.holdingPercent);
+        if (!holdingSymbol || weight === undefined) return [];
+        return [{
+          symbol: holdingSymbol,
+          name: holding.holdingName?.trim() || holdingSymbol,
+          weight,
+        }];
+      }),
+      sectorWeights: normalizeSectorWeights(result.topHoldings.equityHoldings?.sectorWeightings),
+    };
+    if (holdings.holdings.length === 0) {
+      throw new Error(`Yahoo Finance: no weighted fund holdings returned for ${normalizedSymbol}`);
+    }
+
+    cache.set(cacheKey, holdings, TTL.FUNDAMENTALS);
+    return holdings;
+  } catch (error) {
+    const stale = cache.getStale<FundHoldings>(cacheKey, STALE_LIMIT.FUNDAMENTALS);
+    if (stale) return stale.value;
+    throw error;
+  }
+}
+
+function normalizeHoldingWeight(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) return undefined;
+  return value > 1 ? roundWeight(value / 100) : roundWeight(value);
+}
+
+function normalizeSectorWeights(
+  sectors: Array<Record<string, number>> | undefined,
+): Record<string, number> | undefined {
+  if (!sectors?.length) return undefined;
+  const weights: Record<string, number> = {};
+  for (const sector of sectors) {
+    for (const [name, rawWeight] of Object.entries(sector)) {
+      const weight = normalizeHoldingWeight(rawWeight);
+      if (weight !== undefined) weights[name] = weight;
+    }
+  }
+  return Object.keys(weights).length > 0 ? weights : undefined;
+}
+
+function roundWeight(value: number): number {
+  return Math.round(value * 10_000) / 10_000;
+}
+
 // --- Options Chain (v7 API with crumb+cookie auth) ---
 
 const BROWSER_UA =
@@ -227,7 +326,7 @@ export async function getOptionsChain(
     try {
       const browserData = await fetchOptionsViaBrowser(symbol, expiration);
       if (browserData) {
-        const chain = parseOptionsResponse(symbol, browserData);
+        const chain = parseOptionsResponse(browserData);
         cache.set(cacheKey, chain, TTL.OPTIONS_CHAIN);
         return chain;
       }
@@ -252,7 +351,7 @@ export async function getOptionsChain(
   }
 
   const data: YahooOptionsResponse = await res.json();
-  const chain = parseOptionsResponse(symbol, data);
+  const chain = parseOptionsResponse(data);
   cache.set(cacheKey, chain, TTL.OPTIONS_CHAIN);
   return chain;
 }
@@ -275,7 +374,73 @@ export function computeTimeToExpiry(expirationTs: number, nowMs: number = Date.n
   return Math.max(MIN_TIME_YEARS, remainingS / SECONDS_PER_YEAR);
 }
 
-function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): OptionsChain {
+function getUsOptionsMarketSession(now: Date = new Date()): OptionsMarketSession {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: "America/New_York",
+    weekday: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).formatToParts(now);
+  const part = (type: string): string => parts.find((p) => p.type === type)?.value ?? "";
+  const weekday = part("weekday");
+  if (weekday === "Sat" || weekday === "Sun") return "closed";
+
+  const hour = Number(part("hour"));
+  const minute = Number(part("minute"));
+  const minutes = hour * 60 + minute;
+  if (minutes < 9 * 60 + 30) return "pre_market";
+  if (minutes < 16 * 60) return "regular";
+  return "after_hours";
+}
+
+function buildOptionsQuoteStatus(
+  contracts: OptionContract[],
+  now: Date = new Date(),
+): OptionsQuoteStatus {
+  const marketSession = getUsOptionsMarketSession(now);
+  const totalContracts = contracts.length;
+  const zeroBidAskContracts = contracts.filter((c) => c.bid === 0 && c.ask === 0).length;
+  const allZeroBidAsk = totalContracts > 0 && zeroBidAskContracts === totalContracts;
+  const hasLiveBidAsk = contracts.some((c) => c.bid > 0 || c.ask > 0);
+
+  if (allZeroBidAsk && marketSession !== "regular") {
+    return {
+      marketSession,
+      bidAskState: "closed_market_or_stale_quotes",
+      zeroBidAskContracts,
+      totalContracts,
+      warning:
+        "All option contracts have $0.00/$0.00 bid/ask before regular options trading or outside market hours; treat bid/ask as closed-market or stale until the market opens.",
+    };
+  }
+
+  if (allZeroBidAsk) {
+    return {
+      marketSession,
+      bidAskState: "live_zero_bid_ask",
+      zeroBidAskContracts,
+      totalContracts,
+      warning:
+        "All option contracts have $0.00/$0.00 bid/ask during regular options trading hours; verify with a broker, but this may indicate live illiquidity.",
+    };
+  }
+
+  return {
+    marketSession,
+    bidAskState: hasLiveBidAsk ? "live_quotes" : "mixed_or_unknown",
+    zeroBidAskContracts,
+    totalContracts,
+    ...(marketSession !== "regular"
+      ? {
+          warning:
+            "Options bid/ask quotes may be stale outside regular options trading hours; verify live executable prices after the market opens.",
+        }
+      : {}),
+  };
+}
+
+function parseOptionsResponse(data: YahooOptionsResponse): OptionsChain {
   if (data.optionChain.error) {
     throw new Error(`Yahoo Finance options: ${JSON.stringify(data.optionChain.error)}`);
   }
@@ -314,6 +479,7 @@ function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): Optio
   const puts = (opts.puts ?? []).map((c: any) => mapContract(c, "put"));
   const totalCallVolume = calls.reduce((s, c) => s + c.volume, 0);
   const totalPutVolume = puts.reduce((s, c) => s + c.volume, 0);
+  const quoteStatus = buildOptionsQuoteStatus([...calls, ...puts]);
 
   return {
     symbol: result.underlyingSymbol,
@@ -325,6 +491,7 @@ function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): Optio
     totalCallVolume,
     totalPutVolume,
     putCallRatio: totalCallVolume > 0 ? totalPutVolume / totalCallVolume : 0,
+    quoteStatus,
     fetchedAt: new Date().toISOString(),
   };
 }

package/src/routing/classify-intent.ts

@@ -29,7 +29,21 @@ const RULES: Rule[] = [
         entities.symbols.length === 1 &&
         (/\bis\s+\S+\s+(?:attractive|undervalued|overvalued|cheap|expensive)/i.test(lower) ||
           /\bshould\s+i\s+buy\s+\$?[a-z]{1,5}\b/i.test(lower) ||
-          /\bwhat\s+do\s+you\s+think\s+(?:of|about)\s+\$?[a-z]{1,5}\b/i.test(lower))
+          /\bwhat\s+do\s+you\s+think\s+(?:of|about)\s+\$?[a-z]{1,5}\b/i.test(lower) ||
+          /\bbull\s+(?:and|or)\s+bear\s+case\b/i.test(lower))
+      );
+    },
+  },
+  // Portfolio risk for existing holdings must route before multi-symbol compare.
+  {
+    workflow: "watchlist_or_tracking",
+    confidence: 0.9,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      return (
+        entities.symbols.length >= 1 &&
+        (/\bi\s+own\b/.test(lower) || /\bmy\s+holdings\b/.test(lower)) &&
+        (/\bportfolio\s+risk\b/.test(lower) || /\bbiggest\s+risk\b/.test(lower) || /\bconcentration\b/.test(lower))
       );
     },
   },
@@ -56,6 +70,67 @@ const RULES: Rule[] = [
       return hasNewsKeyword;
     },
   },
+  // Tool-backed finance tasks that are not a structured multi-step workflow.
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.9,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      const hasOptionKeywords =
+        /\bcalls?\b/.test(lower) ||
+        /\bputs?\b/.test(lower) ||
+        /\boption(?:s)?\s*chain\b/.test(lower) ||
+        /\boptions?\b/.test(lower);
+      const hasCompareKeywords =
+        /\bcompare\b/.test(lower) ||
+        /\bvs\.?\b/.test(lower) ||
+        /\bversus\b/.test(lower) ||
+        /\bwhich\s+is\s+better\b/.test(lower);
+
+      if (hasOptionKeywords && entities.symbols.length >= 1) return false;
+      if (hasCompareKeywords && entities.symbols.length >= 2) return false;
+
+      return (
+        /\bbacktest\b/.test(lower) ||
+        /\bsentiment\b/.test(lower) ||
+        /\brate\s+cuts?\b/.test(lower)
+      );
+    },
+  },
+  // Broad market / sector / macro research that should receive the general
+  // analyst fallback rather than disappearing into an unclassified turn.
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.85,
+    test: (input) => {
+      const lower = input.toLowerCase();
+      const hasResearchVerb =
+        /\banaly[sz]e\b/.test(lower) ||
+        /\bevaluat(?:e|ion)\b/.test(lower) ||
+        /\breview\b/.test(lower) ||
+        /\bdiscuss\b/.test(lower) ||
+        /\bpredict\b/.test(lower) ||
+        /\bassess\b/.test(lower) ||
+        /^what\b/.test(lower);
+      const hasBroadFinanceTopic =
+        /\bmarket\s+structure\b/.test(lower) ||
+        /\b(?:sector|industry)\b/.test(lower) ||
+        /\bmacro\s+risks?\b/.test(lower) ||
+        /\bmonetary\s+policy\b/.test(lower) ||
+        /\bemerging\s+markets?\b/.test(lower) ||
+        /\bcapital\s+flows?\b/.test(lower) ||
+        /\bcurrency\s+fluctuations?\b/.test(lower) ||
+        /\binflation\b/.test(lower);
+      return hasResearchVerb && hasBroadFinanceTopic;
+    },
+  },
+  // Existing allocation / portfolio review. This is not portfolio construction
+  // and should not require a budget.
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.85,
+    test: (input) => isPortfolioEvaluationRequest(input),
+  },
   // Options: symbol + option keyword
   {
     workflow: "options_screener",
@@ -88,9 +163,10 @@ const RULES: Rule[] = [
   {
     workflow: "compare_assets",
     confidence: 0.85,
-    test: (input) => {
+    test: (input, entities) => {
       const lower = input.toLowerCase();
-      return /\bcompare\s+[a-z]{1,5}(?:\s*,?\s*(?:and\s+)?[a-z]{1,5})+/.test(lower);
+      return entities.symbols.length >= 2 &&
+        /\bcompare\s+[a-z]{1,5}\b(?:\s*,?\s*(?:and\s+)?[a-z]{1,5}\b)+/.test(lower);
     },
   },
   // Compare: 2+ uppercase symbols without explicit keyword
@@ -161,6 +237,9 @@ const RULES: Rule[] = [
   },
 ];
 
+/**
+ * @deprecated Use the LLM router (`route`) for new classification paths; keep this only for rules-mode fallback and deterministic safety nets.
+ */
 export function classifyIntent(input: string): ClassificationResult {
   const trimmed = input.trim();
   if (!trimmed) {
@@ -192,3 +271,15 @@ export function classifyIntent(input: string): ClassificationResult {
     entities,
   };
 }
+
+function isPortfolioEvaluationRequest(input: string): boolean {
+  const lower = input.toLowerCase();
+  const hasEvaluationIntent =
+    /\b(?:evaluat(?:e|ion)|review|assess|analy[sz]e|prospects?|risks?|opportunities?|mitigat(?:e|ion)|adjustment)\b/.test(lower);
+  const hasPortfolioObject =
+    /\b(?:portfolio|allocation|asset\s+allocation|60\/40|equity|fixed\s+income|bonds?)\b/.test(lower);
+  const hasConstructionIntent =
+    /\b(?:build|create|construct|put\s+together|invest|allocate)\b/.test(lower) &&
+    (/\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower));
+  return hasEvaluationIntent && hasPortfolioObject && !hasConstructionIntent;
+}

package/src/routing/defaults.ts

@@ -3,9 +3,9 @@ import type { PortfolioSlots, OptionsScreenerSlots } from "./types.js";
 export const PORTFOLIO_DEFAULTS: Omit<PortfolioSlots, "budget"> = {
   riskProfile: "balanced",
   timeHorizon: "1y_plus",
-  assetScope: "mixed_etf_and_large_cap_equities",
-  positionCount: 4,
-  maxSinglePositionPct: 35,
+  assetScope: "diversified_etf_building_blocks",
+  positionCount: 6,
+  maxSinglePositionPct: 20,
 };
 
 export const OPTIONS_SCREENER_DEFAULTS: Omit<OptionsScreenerSlots, "symbol" | "direction"> = {

package/src/routing/entity-extractor.ts

@@ -7,11 +7,13 @@ const COMMON_WORDS = new Set([
   "HIM", "HIS", "HOW", "ITS", "LET", "MAY", "NEW", "NOW", "OLD", "OUR", "OWN",
   "SAY", "SHE", "TOO", "USE", "WAY", "WHO", "BOY", "DID", "GET", "HAS", "HIM",
   "OUT", "PUT", "RUN", "SET", "TOP", "WHY", "BIG", "END", "FAR", "FEW",
-  "GOT", "LOW", "MAN", "OFF", "PAY", "TRY", "TWO", "BUY", "ETF", "ETFS",
+  "GOT", "LOW", "MAN", "OFF", "PAY", "TRY", "TWO", "BUY", "DOES", "ETF", "ETFS",
   // Technical analysis acronyms
   "SMA", "EMA", "RSI", "MACD", "OBV", "ATR", "ADX", "VWAP",
   // Fundamental analysis acronyms
   "DCF", "FCF", "ROE", "ROA", "ROI", "EPS", "NAV", "WACC", "EBIT",
+  // Regulatory / source acronyms that are not tickers in natural language
+  "SEC",
   "BEST", "WHAT", "WITH", "THAT", "THIS", "FROM", "HAVE", "BEEN", "SOME",
   "THEM", "THAN", "LIKE", "JUST", "OVER", "ALSO", "BACK", "MUCH", "MOST",
   "ONLY", "VERY", "WHEN", "COME", "MAKE", "FIND", "HERE", "KNOW", "TAKE",
@@ -19,22 +21,50 @@ const COMMON_WORDS = new Set([
   "NEXT", "SHOW", "LAST",
 ]);
 
+const AMBIGUOUS_CONCEPT_TICKERS = new Set(["AI", "CPI", "FRED", "GUI"]);
+const LOWERCASE_FINANCE_TERMS = new Set([
+  "bond", "bonds", "cash", "rate", "rates", "cuts", "gold", "oil", "stock", "stocks",
+  "fund", "funds", "etf", "etfs", "puts", "calls", "option", "options",
+]);
+
 export function extractEntities(input: string): ExtractedEntities {
+  const symbols = extractSymbols(input);
+  const heldSymbol = extractHeldSymbol(input, symbols);
+  const catalystSymbols = heldSymbol
+    ? symbols.filter((symbol) => symbol !== heldSymbol)
+    : [];
   return {
-    symbols: extractSymbols(input),
+    symbols,
     budget: extractBudget(input),
     maxPremium: extractMaxPremium(input),
+    costBasis: extractCostBasis(input),
+    shareQuantity: extractShareQuantity(input),
     direction: extractDirection(input),
     riskProfile: extractRiskProfile(input),
     dteHint: extractDteHint(input),
+    optionStrategy: extractOptionStrategy(input),
+    heldSymbol,
+    catalystSymbols: catalystSymbols.length > 0 ? catalystSymbols : undefined,
     timeHorizon: extractTimeHorizon(input),
+    assetScope: extractAssetScope(input),
+    compareMetrics: extractCompareMetrics(input),
   };
 }
 
 export function extractBudget(input: string): number | undefined {
+  if (
+    /\b(?:at|above|below|under|over|near)\s+\$\s*[\d,]+(?:\.\d+)?\s*([kK])?\b/i.test(input) &&
+    !hasBudgetContext(input)
+  ) {
+    return undefined;
+  }
+
   // Match $10,000 or $10000 or $10k
   const dollarSign = input.match(/\$\s*([\d,]+(?:\.\d+)?)\s*([kK])?\b/);
   if (dollarSign) {
+    if (isNonBudgetDollarAmount(input, dollarSign.index ?? 0, dollarSign[0].length)) {
+      return undefined;
+    }
     const base = parseFloat(dollarSign[1].replace(/,/g, ""));
     return dollarSign[2] ? base * 1000 : base;
   }
@@ -54,34 +84,88 @@ export function extractBudget(input: string): number | undefined {
   return undefined;
 }
 
+function hasBudgetContext(input: string): boolean {
+  return /\b(?:budget|invest|allocate|portfolio|cash|capital|with|have|spend|put\s+to\s+work)\b/i.test(input);
+}
+
+function isNonBudgetDollarAmount(input: string, start: number, length: number): boolean {
+  const before = input.slice(Math.max(0, start - 32), start);
+  const after = input.slice(start + length, start + length + 24);
+  return /\b(?:cost\s*basis|basis|entry(?:\s*price)?)\s*(?:is|at|of|:)?\s*$/i.test(before) ||
+    /^\s*(?:premium|max\s+premium|cost\s*basis|basis|entry(?:\s*price)?)\b/i.test(after);
+}
+
 function extractSymbols(input: string): string[] {
   const symbols: string[] = [];
+  const addSymbol = (raw: string | undefined, options: { lowercaseContext?: boolean } = {}) => {
+    const symbol = raw?.toUpperCase();
+    if (options.lowercaseContext && LOWERCASE_FINANCE_TERMS.has(String(raw || "").toLowerCase())) {
+      return;
+    }
+    if (
+      symbol &&
+      symbol.length >= 1 &&
+      symbol.length <= 5 &&
+      /^[A-Z]+$/.test(symbol) &&
+      !COMMON_WORDS.has(symbol) &&
+      !isAmbiguousConceptUsage(input, symbol) &&
+      !symbols.includes(symbol)
+    ) {
+      symbols.push(symbol);
+    }
+  };
 
   // Match $TICKER patterns
   const dollarTickers = input.matchAll(/\$([A-Za-z]{1,5})\b/g);
   for (const match of dollarTickers) {
-    symbols.push(match[1].toUpperCase());
+    addSymbol(match[1]);
+  }
+
+  // Match explicit lowercase ticker contexts without treating arbitrary short
+  // words as symbols.
+  const lowercaseCompare = input.match(/\bcompare\s+([a-z]{1,5})\s+(?:and|vs\.?|versus)\s+([a-z]{1,5})\b/i);
+  if (lowercaseCompare) {
+    addSymbol(lowercaseCompare[1], { lowercaseContext: true });
+    addSymbol(lowercaseCompare[2], { lowercaseContext: true });
+  }
+  const lowercaseTickerContext = input.matchAll(/\b(?:analy[sz]e|quote|ticker)\s+\$?([a-z]{1,5})\b|\b\$?([a-z]{1,5})\s+(?:ticker|stock|shares?|quote|options?|calls?|puts?)\b/gi);
+  for (const match of lowercaseTickerContext) {
+    addSymbol(match[1] ?? match[2], { lowercaseContext: true });
+  }
+  const lowercaseHeldPosition = input.matchAll(/\b(?:own|hold|holding|long|protect|hedge|have)\s+\d+(?:,\d{3})*\s+shares?\s+(?:of\s+)?\$?([a-z]{1,5})\b|\b\d+(?:,\d{3})*\s+shares?\s+of\s+\$?([a-z]{1,5})\b/gi);
+  for (const match of lowercaseHeldPosition) {
+    const raw = match[1] ?? match[2];
+    if (raw && raw !== raw.toUpperCase()) {
+      addSymbol(raw, { lowercaseContext: true });
+    }
   }
 
   // Match standalone uppercase tickers (1-5 chars, all caps)
   const words = input.split(/[\s,]+/);
   for (const word of words) {
     const cleaned = word.replace(/[^A-Za-z]/g, "");
-    if (
-      cleaned.length >= 1 &&
-      cleaned.length <= 5 &&
-      cleaned === cleaned.toUpperCase() &&
-      /^[A-Z]+$/.test(cleaned) &&
-      !COMMON_WORDS.has(cleaned) &&
-      !symbols.includes(cleaned)
-    ) {
-      symbols.push(cleaned);
+    if (cleaned === cleaned.toUpperCase()) {
+      addSymbol(cleaned);
     }
   }
 
   return symbols;
 }
 
+export function isAmbiguousConceptUsage(input: string, symbol: string): boolean {
+  if (!AMBIGUOUS_CONCEPT_TICKERS.has(symbol)) return false;
+  if (new RegExp(`\\$${symbol}\\b`).test(input)) return false;
+  if (
+    new RegExp(
+      `\\b(?:analyze|quote|ticker|stock|shares?|options?|calls?|puts?)\\s+${symbol}\\b|\\b${symbol}\\s+(?:ticker|stock|shares?|quote|options?|calls?|puts?)\\b`,
+      "i",
+    ).test(input)
+  ) {
+    return false;
+  }
+  return true;
+}
+
 function extractMaxPremium(input: string): number | undefined {
   const lower = input.toLowerCase();
   if (!/\bpremium\b/.test(lower)) return undefined;
@@ -103,6 +187,36 @@ function extractMaxPremium(input: string): number | undefined {
   return undefined;
 }
 
+function extractHeldSymbol(input: string, symbols: string[]): string | undefined {
+  const patterns = [
+    /\b(?:i\s+)?(?:have|own|hold|holding|long)\s+\d+(?:,\d{3})*\s+shares?\s+(?:of\s+)?\$?([A-Za-z]{1,5})\b/i,
+    /\b(?:my\s+)?\d+(?:,\d{3})*\s+\$?([A-Za-z]{1,5})\s+shares?\b/i,
+    /\b(?:i\s+)?(?:have|own|hold|holding|long)\s+\$?([A-Za-z]{1,5})\b/i,
+    /\bmy\s+\$?([A-Za-z]{1,5})\s+(?:position|shares?|stock)\b/i,
+  ];
+  for (const pattern of patterns) {
+    const match = input.match(pattern);
+    const symbol = match?.[1]?.toUpperCase();
+    if (symbol && symbols.includes(symbol)) return symbol;
+  }
+  return undefined;
+}
+
+function extractShareQuantity(input: string): number | undefined {
+  const match = input.match(/\b(\d{1,3}(?:,\d{3})*|\d{1,6})\s+shares?\b/i);
+  if (!match) return undefined;
+  const value = parseInt(match[1].replace(/,/g, ""), 10);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+function extractCostBasis(input: string): number | undefined {
+  const match = input.match(/\b(?:cost\s*basis|basis|entry(?:\s*price)?)\s*(?:is|at|of|:)?\s*\$?\s*([\d,]+(?:\.\d+)?)\b/i) ??
+    input.match(/\$\s*([\d,]+(?:\.\d+)?)\s*(?:cost\s*basis|basis|entry(?:\s*price)?)\b/i);
+  if (!match) return undefined;
+  const value = parseFloat(match[1].replace(/,/g, ""));
+  return Number.isFinite(value) ? value : undefined;
+}
+
 function extractDirection(input: string): "bullish" | "bearish" | undefined {
   const lower = input.toLowerCase();
   if (/\bcalls?\b/.test(lower) || /\bbullish\b/.test(lower)) return "bullish";
@@ -126,15 +240,52 @@ function extractRiskProfile(input: string): string | undefined {
 
 function extractDteHint(input: string): string | undefined {
   const lower = input.toLowerCase();
-  if (/\bleaps?\b/i.test(lower) || /\blong[\s-]*dated\b/.test(lower)) return "leaps";
+  const explicitDays = lower.match(/\b(\d+)\s*(?:-|to|or)\s*(\d+)\s*(?:dte|days?)\b/);
+  if (explicitDays) return `${explicitDays[1]}-${explicitDays[2]} days`;
   if (/\bmonth\b/.test(lower)) return "month";
+  if (/\bearnings?\b.*\b(?:today|tonight|this\s+week)\b|\b(?:today|tonight|this\s+week)\b.*\bearnings?\b/.test(lower)) return "event_week";
+  if (/\bleaps?\b/i.test(lower) || /\blong[\s-]*dated\b/.test(lower)) return "leaps";
   if (/\bweek(?:ly|s?)?\b/.test(lower)) return "week";
   return undefined;
 }
 
+function extractOptionStrategy(input: string): ExtractedEntities["optionStrategy"] | undefined {
+  const lower = input.toLowerCase();
+  if (/\bcovered\s+calls?\b/.test(lower)) return "covered_call";
+  if (/\b(?:protective|married)\s+puts?\b/.test(lower)) return "protective_put";
+  if (
+    /\b(?:hedge|protect|protection|insurance)\b/.test(lower) &&
+    /\bputs?\b/.test(lower) &&
+    /\b(?:own|hold|holding|long|shares?|position)\b/.test(lower)
+  ) {
+    return "protective_put";
+  }
+  return undefined;
+}
+
 function extractTimeHorizon(input: string): string | undefined {
   const lower = input.toLowerCase();
+  const explicitMonths = lower.match(/\b(\d+)\s*(?:month|months|mo|mos)\b/);
+  if (explicitMonths) return `${explicitMonths[1]}mo`;
+  const explicitYears = lower.match(/\b(\d+)\s*(?:year|years|yr|yrs)\b/);
+  if (explicitYears) return `${explicitYears[1]}_years`;
   if (/\bshort[\s-]*term\b/.test(lower) || /\bday[\s-]*trad/i.test(lower)) return "short";
   if (/\blong[\s-]*term\b/.test(lower) || /\bbuy[\s-]*and[\s-]*hold\b/.test(lower)) return "long";
   return undefined;
 }
+
+function extractAssetScope(input: string): string | undefined {
+  const lower = input.toLowerCase();
+  if (/\betfs?\b/.test(lower)) return "etf_focused";
+  return undefined;
+}
+
+function extractCompareMetrics(input: string): string[] | undefined {
+  const lower = input.toLowerCase();
+  const metrics: string[] = [];
+  if (/\bsentiment\b/.test(lower)) metrics.push("sentiment");
+  if (/\b(?:macro\s*)?hedg(?:e|ing)\b/.test(lower)) metrics.push("macro_hedge");
+  if (/\b(?:rates?|rate\s*cuts?|fed|federal\s+funds?|interest\s+rates?)\b/.test(lower)) metrics.push("interest_rates");
+  if (/\b(?:overlap|same\s+stuff|same\s+holdings|concentration|too\s+much\s+of\s+the\s+same)\b/.test(lower)) metrics.push("overlap");
+  return metrics.length > 0 ? metrics : undefined;
+}