opencandle 0.4.0 → 0.5.0

package/src/prompts/workflow-prompts.ts

@@ -48,7 +48,11 @@ const DISPLAY_NAMES: Record<string, string> = {
   objective: "objective",
   moneynessPreference: "moneyness",
   liquidityMinimum: "liquidity",
+  optionStrategy: "option strategy",
+  costBasis: "cost basis",
+  shareQuantity: "share quantity",
   symbols: "symbols",
+  metrics: "metrics",
 };
 
 /**
@@ -62,6 +66,8 @@ export function buildDisclosureBlock(
 ): string {
   const userSpecified: string[] = [];
   const fromPreferences: string[] = [];
+  const fromPriorContext: string[] = [];
+  const fromMemory: string[] = [];
   const defaults: string[] = [];
 
   for (const [key, source] of Object.entries(slotSources)) {
@@ -75,6 +81,12 @@ export function buildDisclosureBlock(
       case "preference":
         fromPreferences.push(display);
         break;
+      case "prior_context":
+        fromPriorContext.push(display);
+        break;
+      case "memory":
+        fromMemory.push(display);
+        break;
       case "default":
         defaults.push(display);
         break;
@@ -85,6 +97,8 @@ export function buildDisclosureBlock(
   lines.push("Assumptions (reproduce this block exactly — do not relabel sources):");
   if (userSpecified.length > 0) lines.push(`  User-specified: ${userSpecified.join(", ")}`);
   if (fromPreferences.length > 0) lines.push(`  From saved preferences: ${fromPreferences.join(", ")}`);
+  if (fromPriorContext.length > 0) lines.push(`  From prior context: ${fromPriorContext.join(", ")}`);
+  if (fromMemory.length > 0) lines.push(`  From memory: ${fromMemory.join(", ")}`);
   if (defaults.length > 0) lines.push(`  Defaults: ${defaults.join(", ")}`);
   if (workflowConstraints && workflowConstraints.length > 0) {
     lines.push(`  Workflow constraints: ${workflowConstraints.join(", ")}`);
@@ -124,7 +138,8 @@ function formatSlotValue(value: unknown): string {
 
 export function buildPortfolioPrompt(resolution: SlotResolution<PortfolioSlots>): string {
   const { resolved: s, sources } = resolution;
-  const isEtfOnly = s.assetScope.toLowerCase().startsWith("etf");
+  const normalizedScope = s.assetScope.toLowerCase();
+  const isFundBuildingBlocks = normalizedScope.includes("etf") || normalizedScope.includes("fund") || normalizedScope.includes("building_blocks");
 
   const disclosureBlock = buildDisclosureBlock(
     {
@@ -138,12 +153,14 @@ export function buildPortfolioPrompt(resolution: SlotResolution<PortfolioSlots>)
     sources as Record<string, SlotSource | undefined>,
   );
 
-  const toolSteps = isEtfOnly
-    ? `1. Identify ${s.positionCount} diverse ETF candidates appropriate for a ${s.riskProfile} ${s.timeHorizon} portfolio.
+  const toolSteps = isFundBuildingBlocks
+    ? `1. Identify ${s.positionCount} diversified fund/ETF building-block candidates appropriate for a ${s.riskProfile} ${s.timeHorizon} portfolio.
+   Include distinct asset-class roles such as core domestic equity, international equity, fixed income, short-duration or cash-like stability, and inflation-sensitive ballast when appropriate.
 2. Use get_stock_quote for each candidate to get current prices.
 3. Use analyze_risk on each candidate for volatility, Sharpe, and max drawdown.
 4. Use analyze_correlation across all candidates to check diversification.`
     : `1. Identify ${s.positionCount} diverse candidates appropriate for a ${s.riskProfile} ${s.timeHorizon} portfolio.
+   Avoid over-concentration in individual equities unless the user explicitly asked for stock picks; use diversified funds where they better fit the requested horizon and risk profile.
 2. Use get_stock_quote for each candidate to get current prices.
 3. Use get_company_overview for fundamentals on each candidate.
 4. Use analyze_risk on each candidate for volatility, Sharpe, and max drawdown.
@@ -162,13 +179,22 @@ Build a draft portfolio under these parameters:
 Steps:
 ${toolSteps}
 
+Portfolio construction guardrails:
+- For broad balanced portfolio requests, prefer diversified building blocks over individual-company concentration unless the user explicitly asks for stocks.
+- For horizons under 5 years, include enough fixed-income, short-duration, cash-like, or inflation-sensitive ballast to make the drawdown risk match the horizon.
+- If a candidate's risk metrics undermine its role (for example materially negative risk-adjusted returns, high drawdown, or excessive correlation), lower the allocation, name a role-equivalent replacement, or explain why you are keeping it.
+- Keep rationale tied to each holding's role in this portfolio; do not paste company descriptions or generic issuer background.
+
 ${disclosureBlock}
 
 Response format:
 - Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
+- Then start the analysis with "Bottom line:" and directly say what portfolio you would build for the user.
 - Commit to the draft: give concrete percentages for each position, not ranges, and not "consider allocating X-Y%".
-- Present an allocation table: symbol, allocation %, dollar amount, and a one-line analyst rationale for each position (what the data showed).
+- Present an allocation table: symbol, allocation %, dollar amount, current price used, estimated shares, role, and a one-line analyst rationale for each position (what the data showed and why it belongs in this portfolio).
+- After the table, add a brief "Why this fits the horizon" summary explaining the growth/stability tradeoff and horizon-specific risks for the stated time horizon.
 - Include a risk summary (portfolio volatility, diversification quality) and an invalidation condition for the overall draft ("revisit if correlation exceeds 0.7 across the core ETFs" or equivalent).
+- Include practical implementation notes: rebalance cadence, low-cost/liquid implementation, and tax/account caveats where relevant.
 - Suggest what to change for more growth or more safety.`;
 }
 
@@ -216,11 +242,62 @@ For LEAPS / long-dated options:
       objective: s.objective,
       moneynessPreference: s.moneynessPreference,
       liquidityMinimum: s.liquidityMinimum,
+      ...(s.maxPremium !== undefined ? { maxPremium: formatBudget(s.maxPremium) } : {}),
+      ...(s.optionStrategy ? { optionStrategy: s.optionStrategy } : {}),
+      ...(s.costBasis !== undefined ? { costBasis: formatBudget(s.costBasis) } : {}),
+      ...(s.shareQuantity !== undefined ? { shareQuantity: `${s.shareQuantity} shares` } : {}),
+      ...(s.catalystSymbols?.length ? { catalystSymbols: s.catalystSymbols.join(", ") } : {}),
     },
     sources as Record<string, SlotSource | undefined>,
     workflowConstraints,
   );
 
+  const coveredCallContext = [
+    s.optionStrategy ? `\n- Option strategy: ${s.optionStrategy}${tag(sources.optionStrategy)}` : "",
+    s.costBasis !== undefined ? `\n- Cost basis: ${formatBudget(s.costBasis)} (Position cost basis: ${formatBudget(s.costBasis)})${tag(sources.costBasis)}` : "",
+    s.shareQuantity !== undefined ? `\n- Share quantity: ${s.shareQuantity} shares${tag(sources.shareQuantity)}` : "",
+    s.catalystSymbols?.length ? `\n- Catalyst/context tickers: ${s.catalystSymbols.join(", ")}${tag(sources.catalystSymbols)}` : "",
+  ].join("");
+
+  const isProtectivePutContext = s.optionStrategy === "protective_put";
+  const isCoveredCallContext = !isProtectivePutContext && (
+    s.optionStrategy === "covered_call" ||
+    s.costBasis !== undefined ||
+    (s.catalystSymbols?.length ?? 0) > 0
+  );
+  const coveredCallInstructions = isCoveredCallContext
+    ? `
+Covered-call sale guidance:
+- Treat this as selling covered calls against an existing ${s.symbol} share position, not buying calls.
+- Treat ${s.symbol} as the option-chain underlying.
+- Because the user phrased ${s.symbol} as an existing holding, briefly state that you are treating ${s.symbol} as the held ticker. If they meant memory exposure or a different ticker, tell them to clarify and do not silently switch to another underlying.
+- Do not substitute catalyst/context tickers as the option-chain underlying.
+- Use catalyst/context tickers only to frame event risk, sympathy moves, and whether a nearer expiration is appropriate.
+- Rank by premium collected, strike above cost basis, assignment risk, event risk, and live liquidity.
+- Do not describe max loss as the option premium paid. Covered-call sale risks are assignment/capped upside, share-price downside in the owned stock, IV/event risk, and poor exit liquidity.
+- If the option-chain tool reports closed_market_or_stale_quotes, do not treat zero bid/ask as confirmed live illiquidity; say the chain was checked outside regular options trading and recheck after regular options trading opens.
+- If retrieved contracts have zero bid/ask, zero open interest, or otherwise unusable live quotes, the final answer MUST still include "Best action:" and "Conditional candidate:".
+- In that fallback, "Best action:" should be no trade unless the user's broker shows a real bid, and "Conditional candidate:" should be a strike above cost basis labeled conditional on live bid/ask.
+`
+    : "";
+  const protectivePutInstructions = isProtectivePutContext
+    ? `
+Protective-put hedge guidance:
+- Treat this as buying puts to hedge an existing long ${s.symbol} share position, not buying calls.
+- Treat ${s.symbol} as the option-chain underlying.
+- Rank put contracts by protection per dollar of premium: expiration fit, hedge floor, moneyness, liquidity, and premium as a percent of the stock position.
+- For "doesn't cost too much" or similar cost-sensitive language, prefer liquid puts modestly below the current stock price before far-OTM lottery hedges; explain the tradeoff between cheaper premium and weaker protection.
+- If share quantity is provided, use 1 put contract per 100 shares when discussing coverage and contract count.
+- If share quantity is provided, state total premium for the required number of contracts in the ranked table or top-pick explanation.
+- Include the hedge floor: approximate protected stock value at strike, net of premium where possible.
+- Mention lower-cost alternatives such as a collar or put spread when outright put premium is high.
+- Long protective puts have premium/decay risk and exercise/exit choices; do not frame assignment risk like a short option sale.
+`
+    : "";
+  const topPickExplanation = isCoveredCallContext
+    ? `Explain why the top pick is ranked #1. For covered calls with a cost basis, include the effective assignment sale price (strike + premium collected) and compare it with the ${s.costBasis !== undefined ? formatBudget(s.costBasis) : "user's"} cost basis.`
+    : "Explain why the top pick is ranked #1.";
+
   return `Current date: ${dateStr}
 Do NOT invent or assume a different current date.${expirationSection}
 
@@ -229,51 +306,128 @@ Screen and rank options contracts for ${s.symbol}:
 - DTE target: ${s.dteTarget}${tag(sources.dteTarget)}
 - Objective: ${s.objective}${tag(sources.objective)}
 - Moneyness: ${s.moneynessPreference}${tag(sources.moneynessPreference)}
-- Liquidity: ${s.liquidityMinimum}${tag(sources.liquidityMinimum)}${s.budget ? `\n- Budget: ${formatBudget(s.budget)}` : ""}${s.maxPremium ? `\n- Max premium: ${formatBudget(s.maxPremium)}` : ""}
+- Liquidity: ${s.liquidityMinimum}${tag(sources.liquidityMinimum)}${coveredCallContext}${s.budget ? `\n- Budget: ${formatBudget(s.budget)}` : ""}${s.maxPremium ? `\n- Max premium: ${formatBudget(s.maxPremium)}` : ""}
 
 Steps:
 1. Use get_stock_quote for ${s.symbol} to get current price and recent movement.
 2. Use get_option_chain for ${s.symbol} to get the full chain with Greeks. If you filter by contract type, pass \`type: "call"\` or \`type: "put"\` in lowercase.
-3. Filter contracts matching: ${s.direction === "bullish" ? "calls" : "puts"}, DTE near ${s.dteTarget}, ${s.moneynessPreference} strikes.
-4. Rank by ${s.objective}: balance premium cost, delta exposure, and probability of profit.
+3. Filter contracts matching: ${s.direction === "bullish" && !isProtectivePutContext ? "calls" : "puts"}, DTE near ${s.dteTarget}, ${s.moneynessPreference} strikes.
+4. ${isProtectivePutContext ? "Rank by hedge quality: protection per dollar of premium, expiration fit, moneyness, liquidity, and hedge floor." : `Rank by ${s.objective}: balance premium cost, delta exposure, and probability of profit.`}${s.maxPremium !== undefined ? ` Do not rank contracts above the user's max premium of ${formatBudget(s.maxPremium)} unless no contracts under that cap are liquid; if so, say the cap could not be met.` : ""}
 5. Filter for ${s.liquidityMinimum}: high open interest and tight bid-ask spread.
+${s.optionStrategy === "covered_call" ? `6. Covered call framing: treat option premium as premium received, not paid. Use the user's cost basis when provided, and include return-if-assigned and assignment/downside risk instead of long-call max-loss framing.
+` : ""}${isCoveredCallContext && s.costBasis !== undefined ? `Cost-basis math: if assigned, share gain/loss is strike minus ${formatBudget(s.costBasis)} before premium. Total return if assigned is (strike - cost basis + premium received) / cost basis.
+` : ""}
 ${longDatedInstructions}
+${coveredCallInstructions}
+${protectivePutInstructions}
 ${rankingConstraints}
 ${disclosureBlock}
 
 Response format:
 - Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
-- Present top 3-5 ranked contracts in a table: strike, expiry, premium, delta, IV, OI, bid-ask spread.
-- Explain why the top pick is ranked #1.
-- Include risk caveats (max loss = premium, IV crush risk, time decay).`;
+- ${isCoveredCallContext ? `Start with an Interpretation line: "Interpretation: Treating ${s.symbol} as the held ticker because you phrased it as an existing position. If you meant ${s.symbol} as memory exposure or another ticker, clarify before trading."` : isProtectivePutContext ? `Start with an Interpretation line: "Interpretation: Treating this as buying protective puts on an existing long ${s.symbol} share position."` : "State the interpretation only if the user's requested underlying is ambiguous."}
+- Present top 3-5 ranked contracts in a table: strike, expiry, premium, delta, gamma, theta, vega, rho, IV, OI, bid-ask spread${isProtectivePutContext ? ", hedge floor, premium % of position" : ""}.
+- ${topPickExplanation}
+- Verify bid/ask and open interest in the user's broker before trading, even when OC shows live values.
+- Include ${isCoveredCallContext ? "covered-call sale risks (assignment/capped upside, share-price downside in the owned stock, IV/event risk, exit liquidity). Do not describe max loss as the option premium paid" : isProtectivePutContext ? "protective-put risks (premium decay/cost, imperfect hedge before the strike, liquidity, and opportunity cost). Do not discuss short-option assignment risk" : "risk caveats (max loss = premium, IV crush risk, time decay)"}.`;
 }
 
 export function buildCompareAssetsPrompt(resolution: SlotResolution<CompareAssetsSlots>): string {
   const symbols = resolution.resolved.symbols;
   const symbolList = symbols.join(", ");
+  const timeHorizon = resolution.resolved.timeHorizon;
+  const includeSentiment = resolution.resolved.metrics?.includes("sentiment") ?? false;
+  const isMacroHedge = resolution.resolved.metrics?.includes("macro_hedge") ?? false;
+  const isInterestRateSensitive = resolution.resolved.metrics?.includes("interest_rates") ?? false;
+  const isOverlapComparison = resolution.resolved.metrics?.includes("overlap") ?? false;
+  const sentimentStep = includeSentiment
+    ? `\n6. Use get_sentiment_summary for each of: ${symbolList} to compare retail/news sentiment and note source availability.`
+    : "";
+  const interestRateStep = isInterestRateSensitive
+    ? `\n${includeSentiment ? "7" : "6"}. Use get_economic_data for the current Fed funds backdrop. Treat this as historical/current context unless you also have explicit futures or forecast evidence.`
+    : "";
+  const sentimentMetric = includeSentiment ? ", sentiment score/summary" : "";
+  const interestRateGuidance = isInterestRateSensitive
+    ? `
+interest-rate comparison guidance:
+- Separate the user's conditional premise from observed data: if the prompt says rates "start falling," state that the recommendation depends on why rates fall and whether market pricing confirms it.
+- Give a compact scenario split: benign disinflation/soft landing, recession or earnings shock, and sticky inflation or renewed rate pressure. State which asset type should benefit in each case and why.
+- Connect rates to asset mechanics: duration-like sensitivity of future earnings, cost of capital, earnings resilience, valuation multiples, and risk appetite.
+- For ETF or fund comparisons, include concentration and sector-exposure risk when one asset is meaningfully narrower or more growth/technology-heavy than the other.
+- If forward valuation, earnings estimates, or rate-futures evidence is unavailable, say that directly and avoid treating historical Fed funds data as a forecast.`
+    : "";
+  const overlapGuidance = isOverlapComparison
+    ? `
+ETF overlap guidance:
+- Treat this as an ETF overlap and diversification question, not a generic return ranking.
+- Lead with whether adding the second ETF creates a mega-cap technology tilt, growth-factor tilt, or real diversification.
+- Explain that holdings overlap and sector concentration are not the same as correlation; correlation is supporting evidence, not the answer.
+- Use provider top holdings and overlap weights when available. If provider coverage is partial or unavailable, say so directly and fall back to plain-language fund structure.
+- Discuss top holdings, shared mega-cap names, sector concentration, and whether the position is a deliberate tilt or accidental duplication.
+- avoid treating price, RSI, or generic risk metrics as the main answer.`
+    : "";
+  const macroHedgeSteps = isMacroHedge
+    ? `
+macro hedge decision guidance:
+- Treat this as a hedge-role comparison, not a generic "which asset has better recent technicals" ranking.
+- Prioritize what each asset hedges: inflation, falling real yields, USD weakness, geopolitical/systemic shocks, liquidity stress, and risk-asset drawdowns.
+- Compare volatility, drawdown, and correlation regime stability. If a metric is unavailable for one asset, explain how that limits confidence instead of awarding the other asset by default.
+- Use current macro evidence where available: real yields or Fed-rate direction, inflation trend, USD/liquidity backdrop, and risk-on/risk-off conditions.
+- Include a compact scenario map for stagflation, rising real yields, liquidity crunch/risk-off, USD debasement, and geopolitical shock. State which asset is likely the better hedge in each scenario and why.
+- End with conditional guidance: prefer the steadier hedge for capital preservation; prefer the higher-volatility asset only for debasement/asymmetric-upside exposure.`
+    : "";
+  const tableInstruction = isMacroHedge
+    ? "- Present a comparison table with hedge-relevant columns: hedge role, macro drivers, volatility/drawdown evidence, correlation regime, liquidity/risk-on sensitivity, current data, and missing evidence."
+    : isOverlapComparison
+      ? "- Present an ETF overlap table with columns: fund role, shared top holdings/overlap weight from provider when available, sector concentration, what exposure is duplicated, what exposure is new, and diversification implication."
+    : `- Present a comparison table with key metrics: price, P/E, revenue growth, profit margin, RSI, Sharpe, max drawdown${sentimentMetric}.
+- Highlight which asset is stronger on each metric.`;
+  const technicalRiskSteps = isOverlapComparison
+    ? `3. Use analyze_holdings_overlap with symbols [${symbolList}] to fetch provider top holdings and compute pairwise overlap by weight.
+4. Use analyze_correlation across [${symbolList}] only as supporting diversification evidence; do not substitute correlation for holdings overlap.
+5. Skip momentum/risk tool calls unless the user asks about timing or trade setup; the core question is top holdings and sector overlap.`
+    : `3. Use get_technical_indicators for each to compare momentum and trend.
+4. Use analyze_risk for each to compare risk metrics.
+5. Use analyze_correlation across [${symbolList}] to check diversification.`;
+  const horizonLine = timeHorizon ? `\nTime horizon: ${timeHorizon}` : "";
+  const horizonSteps = timeHorizon
+    ? `
+6. Adapt the comparison to the ${timeHorizon} horizon: prioritize near-term catalysts, earnings/guidance, estimate revisions, sentiment, and forward-looking valuation evidence over long-term historical averages.
+7. Use historical risk and technical metrics as context, but explain what they do and do not imply over ${timeHorizon}.`
+    : "";
+  const horizonResponse = timeHorizon
+    ? `
+- Start the verdict by directly answering whether the assets should compare for a ${timeHorizon} horizon and why.
+- Prioritize the evidence that matters most over ${timeHorizon}: near-term catalysts, earnings/guidance, forward-looking valuation/estimates, sentiment, macro sensitivity, and company-specific risks.
+- Call out evidence that is missing or unavailable, especially forward-looking estimates or company-specific catalysts.`
+    : "";
 
   const disclosureBlock = buildDisclosureBlock(
-    { symbols: symbolList },
+    {
+      symbols: symbolList,
+      ...(timeHorizon ? { timeHorizon } : {}),
+      ...(resolution.resolved.metrics ? { metrics: resolution.resolved.metrics.join(", ") } : {}),
+    },
     resolution.sources as Record<string, SlotSource | undefined>,
   );
 
   return `Current date: ${todayStr()}
 
-Compare these assets side by side: ${symbolList}
+Compare these assets side by side: ${symbolList}${horizonLine}
 
 Steps:
 1. Use get_stock_quote for each of: ${symbolList}.
 2. Use compare_companies with symbols [${symbols.map((s) => `"${s}"`).join(", ")}] for peer metrics. If some fundamentals are unavailable, continue the comparison with the available symbols and mark missing metrics as unavailable.
-3. Use get_technical_indicators for each to compare momentum and trend.
-4. Use analyze_risk for each to compare risk metrics.
-5. Use analyze_correlation across [${symbolList}] to check diversification.
+${technicalRiskSteps}${sentimentStep}${interestRateStep}${horizonSteps}
+${macroHedgeSteps}
+${interestRateGuidance}
+${overlapGuidance}
 
 ${disclosureBlock}
 
 Response format:
 - Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
-- Present a comparison table with key metrics: price, P/E, revenue growth, profit margin, RSI, Sharpe, max drawdown.
-- Highlight which asset is stronger on each metric.
+${tableInstruction}
 - Provide a summary verdict: which is most attractive and why.
-- Note any caveats (different sectors, market cap disparity, unavailable fundamentals, etc.).`;
+- Note any caveats (different sectors, concentration, market cap disparity, unavailable fundamentals, unavailable forward-looking estimates, etc.).${horizonResponse}`;
 }

package/src/providers/alpha-vantage.ts

@@ -27,6 +27,23 @@ function buildUrl(fn: string, params: Record<string, string>, apiKey: string): s
   return `${BASE_URL}?${qs}`;
 }
 
+function throwIfApiMessage(data: unknown): void {
+  if (!data || typeof data !== "object") return;
+
+  const payload = data as Record<string, unknown>;
+  const message = payload.Note ?? payload.Information ?? payload["Error Message"];
+  if (typeof message !== "string" || message.length === 0) return;
+
+  const normalized = message.toLowerCase();
+  if (normalized.includes("api call frequency") || normalized.includes("rate limit")) {
+    throw new Error(`Alpha Vantage rate limited: ${message}`);
+  }
+  if (normalized.includes("invalid api")) {
+    throw new ProviderCredentialError("alpha_vantage", "stale");
+  }
+  throw new Error(`Alpha Vantage error: ${message}`);
+}
+
 export async function getOverview(
   symbol: string,
   apiKey: string,
@@ -44,6 +61,7 @@ export async function getOverview(
 
     const url = buildUrl("OVERVIEW", { symbol }, apiKey);
     const data = await httpGet<Record<string, string>>(url);
+    throwIfApiMessage(data);
 
     if (!data.Symbol) {
       cache.set(missingCacheKey, "missing", MISSING_OVERVIEW_TTL);
@@ -93,6 +111,7 @@ export async function getEarnings(
 
     const url = buildUrl("EARNINGS", { symbol }, apiKey);
     const data = await httpGet<{ quarterlyEarnings: any[] }>(url);
+    throwIfApiMessage(data);
 
     const quarterly = (data.quarterlyEarnings ?? []).slice(0, 8).map((e: any) => ({
       date: e.fiscalDateEnding,
@@ -178,7 +197,9 @@ export async function getFinancials(
 async function fetchStatement<T>(fn: string, symbol: string, apiKey: string): Promise<T> {
   await rateLimiter.acquire("alphavantage");
   const url = buildUrl(fn, { symbol }, apiKey);
-  return httpGet<T>(url);
+  const data = await httpGet<T>(url);
+  throwIfApiMessage(data);
+  return data;
 }
 
 export async function getGlobalQuote(
@@ -194,6 +215,7 @@ export async function getGlobalQuote(
 
     const url = buildUrl("GLOBAL_QUOTE", { symbol }, apiKey);
     const data = await httpGet<{ "Global Quote": Record<string, string> }>(url);
+    throwIfApiMessage(data);
     const gq = data["Global Quote"];
 
     if (!gq || !gq["05. price"]) {
@@ -245,6 +267,7 @@ export async function getDailyHistory(
     const outputsize = daysNeeded > 100 ? "full" : "compact";
     const url = buildUrl("TIME_SERIES_DAILY", { symbol, outputsize }, apiKey);
     const data = await httpGet<{ "Time Series (Daily)": Record<string, Record<string, string>> }>(url);
+    throwIfApiMessage(data);
 
     const timeSeries = data["Time Series (Daily)"];
     if (!timeSeries) {

package/src/providers/sec-edgar.ts

@@ -2,6 +2,8 @@ import { httpGet } from "../infra/http-client.js";
 import { cache, TTL } from "../infra/cache.js";
 
 const EFTS_BASE = "https://efts.sec.gov/LATEST/search-index";
+const COMPANY_TICKERS_URL = "https://www.sec.gov/files/company_tickers.json";
+const SUBMISSIONS_BASE = "https://data.sec.gov/submissions";
 
 export interface SECFiling {
   formType: string;
@@ -10,6 +12,14 @@ export interface SECFiling {
   entityName: string;
   accessionNumber: string;
   url: string;
+  primaryDocumentUrl?: string;
+  items?: string[];
+  evidenceSnippets?: string[];
+}
+
+export interface SearchFilingsOptions {
+  includeSnippets?: boolean;
+  snippetLimitPerFiling?: number;
 }
 
 interface EFTSResponse {
@@ -23,20 +33,52 @@ interface EFTSResponse {
         display_names: string[];
         period_ending: string;
         ciks: string[];
+        items?: string[];
       };
     }>;
   };
 }
 
+interface CompanyTickerEntry {
+  cik_str: number;
+  ticker: string;
+  title: string;
+}
+
+interface SubmissionsResponse {
+  name: string;
+  tickers?: string[];
+  filings: {
+    recent: {
+      accessionNumber: string[];
+      filingDate: string[];
+      reportDate: string[];
+      form: string[];
+      primaryDocument: string[];
+      items?: string[];
+    };
+  };
+}
+
 export async function searchFilings(
   ticker: string,
   formTypes: string[] = ["10-K", "10-Q", "8-K"],
   limit: number = 10,
+  options: SearchFilingsOptions = {},
 ): Promise<SECFiling[]> {
-  const cacheKey = `sec:${ticker}:${formTypes.join(",")}:${limit}`;
+  const cacheKey = `sec:${ticker}:${formTypes.join(",")}:${limit}:${options.includeSnippets ? "snippets" : "metadata"}`;
   const cached = cache.get<SECFiling[]>(cacheKey);
   if (cached) return cached;
 
+  if (options.includeSnippets) {
+    const submissions = await searchFilingsFromCompanySubmissions(ticker, formTypes, limit).catch(() => []);
+    if (submissions.length > 0) {
+      await enrichWithEvidenceSnippets(submissions, options.snippetLimitPerFiling ?? 3);
+      cache.set(cacheKey, submissions, TTL.FUNDAMENTALS);
+      return submissions;
+    }
+  }
+
   const params = new URLSearchParams({
     q: ticker,
     forms: formTypes.join(","),
@@ -60,12 +102,15 @@ export async function searchFilings(
     const src = hit._source;
     const accession = src.adsh;
     if (!accession || seen.has(accession)) continue;
+    if (!matchesTicker(src.display_names, ticker)) continue;
     seen.add(accession);
 
     const cik = src.ciks?.[0] ?? "";
     const displayName = src.display_names?.[0] ?? "";
     // Extract entity name from display format: "APPLE INC  (AAPL)  (CIK 0000320193)"
     const entityName = displayName.split("(")[0]?.trim() ?? displayName;
+    const archiveDir = buildEdgarArchiveDir(cik, accession);
+    const primaryDocumentUrl = buildPrimaryDocumentUrl(archiveDir, hit._id);
 
     filings.push({
       formType: src.form ?? "",
@@ -73,20 +118,102 @@ export async function searchFilings(
       periodOfReport: src.period_ending ?? "",
       entityName,
       accessionNumber: accession,
-      url: buildEdgarUrl(cik, accession),
+      url: `${archiveDir}/${accession}-index.htm`,
+      primaryDocumentUrl,
+      items: src.items ?? [],
     });
 
     if (filings.length >= limit) break;
   }
 
+  if (options.includeSnippets) {
+    await enrichWithEvidenceSnippets(filings, options.snippetLimitPerFiling ?? 3);
+  }
+
   cache.set(cacheKey, filings, TTL.FUNDAMENTALS);
   return filings;
 }
 
-function buildEdgarUrl(cik: string, accession: string): string {
+async function searchFilingsFromCompanySubmissions(
+  ticker: string,
+  formTypes: string[],
+  limit: number,
+): Promise<SECFiling[]> {
+  const company = await resolveCompanyTicker(ticker);
+  if (!company) return [];
+
+  const cik = String(company.cik_str).padStart(10, "0");
+  const data = await httpGet<SubmissionsResponse>(`${SUBMISSIONS_BASE}/CIK${cik}.json`, {
+    headers: { "User-Agent": "OpenCandle/1.0 (financial analysis agent)" },
+  });
+
+  const filings: SECFiling[] = [];
+  const recent = data.filings.recent;
+  for (let i = 0; i < recent.form.length && filings.length < limit; i++) {
+    const formType = recent.form[i] ?? "";
+    if (!formTypes.includes(formType)) continue;
+    const accession = recent.accessionNumber[i];
+    if (!accession) continue;
+    const archiveDir = buildEdgarArchiveDir(cik, accession);
+    const primaryDocument = recent.primaryDocument[i];
+    filings.push({
+      formType,
+      filedDate: recent.filingDate[i] ?? "",
+      periodOfReport: recent.reportDate[i] ?? "",
+      entityName: data.name || company.title,
+      accessionNumber: accession,
+      url: `${archiveDir}/${accession}-index.htm`,
+      primaryDocumentUrl: primaryDocument ? `${archiveDir}/${primaryDocument}` : undefined,
+      items: splitFilingItems(recent.items?.[i]),
+    });
+  }
+  return filings;
+}
+
+async function resolveCompanyTicker(ticker: string): Promise<CompanyTickerEntry | undefined> {
+  const cacheKey = "sec:company-tickers";
+  let companies = cache.get<CompanyTickerEntry[]>(cacheKey);
+  if (!companies) {
+    const data = await httpGet<Record<string, CompanyTickerEntry>>(COMPANY_TICKERS_URL, {
+      headers: { "User-Agent": "OpenCandle/1.0 (financial analysis agent)" },
+    });
+    companies = Object.values(data);
+    cache.set(cacheKey, companies, TTL.FUNDAMENTALS);
+  }
+  const normalized = ticker.toUpperCase();
+  return companies.find((company) => company.ticker.toUpperCase() === normalized);
+}
+
+function splitFilingItems(raw: string | undefined): string[] {
+  return raw
+    ? raw.split(",").map((item) => item.trim()).filter(Boolean)
+    : [];
+}
+
+function matchesTicker(displayNames: string[] | undefined, ticker: string): boolean {
+  const normalized = ticker.toUpperCase();
+  return (displayNames ?? []).some((name) => {
+    const tickerGroups = name.match(/\(([^)]*)\)/g) ?? [];
+    return tickerGroups.some((group) =>
+      group
+        .slice(1, -1)
+        .split(",")
+        .map((part) => part.trim().toUpperCase())
+        .includes(normalized),
+    );
+  });
+}
+
+function buildEdgarArchiveDir(cik: string, accession: string): string {
   const cikNum = cik.replace(/^0+/, "");
   const accessionNoDash = accession.replace(/-/g, "");
-  return `https://www.sec.gov/Archives/edgar/data/${cikNum}/${accessionNoDash}/${accession}-index.htm`;
+  return `https://www.sec.gov/Archives/edgar/data/${cikNum}/${accessionNoDash}`;
+}
+
+function buildPrimaryDocumentUrl(archiveDir: string, hitId: string): string | undefined {
+  const fileName = hitId.split(":")[1];
+  if (!fileName || !/\.(?:htm|html|txt)$/i.test(fileName)) return undefined;
+  return `${archiveDir}/${fileName}`;
 }
 
 function getDateYearsAgo(years: number): string {
@@ -94,3 +221,92 @@ function getDateYearsAgo(years: number): string {
   d.setFullYear(d.getFullYear() - years);
   return d.toISOString().split("T")[0];
 }
+
+async function enrichWithEvidenceSnippets(filings: SECFiling[], limitPerFiling: number): Promise<void> {
+  await Promise.all(
+    filings.map(async (filing) => {
+      if (!filing.primaryDocumentUrl) return;
+      try {
+        const raw = await fetchText(filing.primaryDocumentUrl);
+        filing.evidenceSnippets = extractEvidenceSnippets(raw, limitPerFiling);
+      } catch {
+        filing.evidenceSnippets = [];
+      }
+    }),
+  );
+}
+
+async function fetchText(url: string): Promise<string> {
+  const response = await fetch(url, {
+    headers: { "User-Agent": "OpenCandle/1.0 (financial analysis agent)" },
+  });
+  if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+  return response.text();
+}
+
+const EVIDENCE_KEYWORDS = [
+  "risk factor",
+  "legal proceedings",
+  "litigation",
+  "regulatory",
+  "regulation",
+  "revenue",
+  "concentration",
+  "management's discussion",
+  "management discussion",
+  "liquidity",
+  "outlook",
+  "guidance",
+  "material weakness",
+  "going concern",
+];
+
+function extractEvidenceSnippets(raw: string, limit: number): string[] {
+  const text = stripFilingMarkup(raw);
+  const snippets: string[] = [];
+  const lower = text.toLowerCase();
+
+  for (const keyword of EVIDENCE_KEYWORDS) {
+    let searchFrom = 0;
+    while (searchFrom < lower.length) {
+      const index = lower.indexOf(keyword, searchFrom);
+      if (index === -1) break;
+      searchFrom = index + keyword.length;
+
+      const start = Math.max(0, index - 220);
+      const end = Math.min(text.length, index + keyword.length + 420);
+      const snippet = text.slice(start, end).replace(/\s+/g, " ").trim();
+      if (
+        snippet &&
+        !isLikelyTableOfContentsSnippet(snippet) &&
+        !snippets.some((existing) => existing.includes(snippet.slice(0, 80)))
+      ) {
+        snippets.push(snippet);
+        break;
+      }
+    }
+    if (snippets.length >= limit) break;
+  }
+
+  return snippets;
+}
+
+function stripFilingMarkup(raw: string): string {
+  return raw
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&#160;/g, " ")
+    .replace(/&#8217;/g, "'")
+    .replace(/&#8220;|&#8221;/g, "\"")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function isLikelyTableOfContentsSnippet(snippet: string): boolean {
+  const lower = snippet.toLowerCase();
+  const itemHeadingCount = lower.match(/\bitem\s+\d+[a-z]?\b/g)?.length ?? 0;
+  return lower.includes("table of contents") && itemHeadingCount >= 2;
+}

package/src/providers/web-search.ts

@@ -1,5 +1,5 @@
 import { search, searchNews, SafeSearchType, SearchTimeType } from "duck-duck-scrape";
-import type { SearchResult, SearchResults } from "duck-duck-scrape";
+import type { SearchResult } from "duck-duck-scrape";
 import type { NewsResult } from "duck-duck-scrape";
 import { httpGet, HttpError } from "../infra/http-client.js";
 import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";