opencandle 0.3.0 → 0.5.0

package/src/tools/sentiment/web-sentiment.ts

@@ -0,0 +1,76 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { searchWeb } from "../../providers/web-search.js";
+import { WebAdapter } from "../../sentiment/adapters/web.js";
+import { getSentimentPipeline } from "../../sentiment/index.js";
+
+const params = Type.Object({
+  query: Type.String({ description: "Ticker or topic to search for web/news sentiment" }),
+  freshness: Type.Optional(
+    Type.Union([Type.Literal("day"), Type.Literal("week"), Type.Literal("month")], {
+      description: "Time window for results. Default: day",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Max results. Default: 10, max: 20" }),
+  ),
+});
+
+export const webSentimentTool: AgentTool<typeof params> = {
+  name: "get_web_sentiment",
+  label: "Web/News Sentiment",
+  description:
+    "Analyze sentiment from web and news search results for a ticker or topic. Returns scored results with aggregate sentiment.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const freshness = args.freshness ?? "day";
+    const limit = Math.min(args.limit ?? 10, 20);
+
+    const providerResult = await searchWeb(args.query, { freshness, limit, category: "news" });
+
+    if (providerResult.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Web sentiment unavailable for "${args.query}" (${providerResult.reason}).` }],
+        details: null as any,
+      };
+    }
+
+    const adapter = new WebAdapter();
+    const records = adapter.mapToRecords(providerResult.data, args.query);
+    const pipeline = getSentimentPipeline();
+    const result = await pipeline.processRecords(records, args.query);
+
+    const lines: string[] = [];
+    if (result.fresh.length === 0) {
+      lines.push(`No web results found for "${args.query}".`);
+    } else {
+      const avgScore = result.fresh.reduce((s, r) => s + r.sentiment.score, 0) / result.fresh.length;
+      const label = sentimentLabel(avgScore);
+      lines.push(`**Web sentiment for "${args.query}"** — ${result.fresh.length} results (${label}, ${avgScore.toFixed(2)})`);
+      lines.push("");
+
+      for (const rec of result.fresh.slice(0, limit)) {
+        const indicator = rec.sentiment.score > 0 ? "🟢" : rec.sentiment.score < 0 ? "🔴" : "⚪";
+        lines.push(`${indicator} [${rec.title}](${rec.url}) — *${rec.author}*`);
+        lines.push(`  ${rec.text.slice(0, 150)}`);
+        lines.push(`  Score: ${rec.sentiment.score.toFixed(2)} | Confidence: ${rec.sentiment.confidence.toFixed(2)}`);
+      }
+
+      if (result.trend) {
+        lines.push("");
+        const t = result.trend[0];
+        lines.push(`Trend: ${t.sparkline} ${t.direction} (${t.count} records)`);
+      }
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }], details: result };
+  },
+};
+
+function sentimentLabel(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";
+}

package/src/tools/technical/backtest.ts

@@ -0,0 +1,267 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getHistory } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { computeSMA, computeRSI } from "./indicators.js";
+import type { OHLCV } from "../../types/market.js";
+
+export type Strategy = "sma_crossover" | "sma_50_200_crossover" | "rsi_mean_reversion";
+
+export interface BacktestResult {
+  strategy: string;
+  totalReturn: number;
+  buyAndHoldReturn: number;
+  trades: number;
+  wins: number;
+  winRate: number;
+  maxDrawdown: number;
+  tradeLog: Array<{ type: "buy" | "sell"; date: string; price: number; pnl?: number }>;
+}
+
+export function runBacktest(bars: OHLCV[], strategy: Strategy): BacktestResult {
+  const closes = bars.map((b) => b.close);
+
+  if (strategy === "sma_crossover") {
+    return backtestSMACrossover(bars, closes, 20, 50, strategy);
+  }
+  if (strategy === "sma_50_200_crossover") {
+    return backtestSMACrossover(bars, closes, 50, 200, strategy);
+  }
+  return backtestRSIMeanReversion(bars, closes);
+}
+
+function backtestSMACrossover(
+  bars: OHLCV[],
+  closes: number[],
+  shortWindow: number,
+  longWindow: number,
+  strategyName: Strategy,
+): BacktestResult {
+  const shortSma = computeSMA(closes, shortWindow);
+  const longSma = computeSMA(closes, longWindow);
+
+  if (longSma.length === 0) {
+    return emptyResult(strategyName, closes);
+  }
+
+  const shortOffset = shortWindow - 1;
+  const longOffset = longWindow - 1;
+
+  let position = false;
+  let entryPrice = 0;
+  const tradeLog: BacktestResult["tradeLog"] = [];
+  let equity = 1.0;
+  let peak = 1.0;
+  let maxDd = 0;
+
+  for (let i = 0; i < longSma.length; i++) {
+    const barIdx = i + longOffset;
+    const shortSmaIdx = i + (longOffset - shortOffset);
+    const sShort = shortSma[shortSmaIdx];
+    const sLong = longSma[i];
+    const price = closes[barIdx];
+
+    if (!position && sShort > sLong) {
+      // Buy signal
+      position = true;
+      entryPrice = price;
+      tradeLog.push({ type: "buy", date: bars[barIdx].date, price });
+    } else if (position && sShort < sLong) {
+      // Sell signal
+      const pnl = (price - entryPrice) / entryPrice;
+      equity *= 1 + pnl;
+      tradeLog.push({ type: "sell", date: bars[barIdx].date, price, pnl });
+      position = false;
+    }
+
+    // Track mark-to-market equity for accurate drawdown
+    const currentEquity = position
+      ? equity * (1 + (price - entryPrice) / entryPrice)
+      : equity;
+    if (currentEquity > peak) peak = currentEquity;
+    const dd = (peak - currentEquity) / peak;
+    if (dd > maxDd) maxDd = dd;
+  }
+
+  // Close open position at end
+  if (position) {
+    const lastPrice = closes[closes.length - 1];
+    const pnl = (lastPrice - entryPrice) / entryPrice;
+    equity *= 1 + pnl;
+    tradeLog.push({ type: "sell", date: bars[bars.length - 1].date, price: lastPrice, pnl });
+  }
+
+  return buildResult(strategyName, equity - 1, closes, tradeLog, maxDd);
+}
+
+function backtestRSIMeanReversion(bars: OHLCV[], closes: number[]): BacktestResult {
+  const rsi = computeRSI(closes, 14);
+
+  if (rsi.length === 0) {
+    return emptyResult("rsi_mean_reversion", closes);
+  }
+
+  // RSI starts at index 14 (after 14 periods of data)
+  const rsiOffset = 14;
+  let position = false;
+  let entryPrice = 0;
+  const tradeLog: BacktestResult["tradeLog"] = [];
+  let equity = 1.0;
+  let peak = 1.0;
+  let maxDd = 0;
+
+  for (let i = 0; i < rsi.length; i++) {
+    const barIdx = i + rsiOffset;
+    const r = rsi[i];
+    const price = closes[barIdx];
+
+    if (!position && r < 30) {
+      // RSI oversold → buy
+      position = true;
+      entryPrice = price;
+      tradeLog.push({ type: "buy", date: bars[barIdx].date, price });
+    } else if (position && r > 70) {
+      // RSI overbought → sell
+      const pnl = (price - entryPrice) / entryPrice;
+      equity *= 1 + pnl;
+      tradeLog.push({ type: "sell", date: bars[barIdx].date, price, pnl });
+      position = false;
+    }
+
+    // Track mark-to-market equity for accurate drawdown
+    const currentEquity = position
+      ? equity * (1 + (price - entryPrice) / entryPrice)
+      : equity;
+    if (currentEquity > peak) peak = currentEquity;
+    const dd = (peak - currentEquity) / peak;
+    if (dd > maxDd) maxDd = dd;
+  }
+
+  // Close open position at end
+  if (position) {
+    const lastPrice = closes[closes.length - 1];
+    const pnl = (lastPrice - entryPrice) / entryPrice;
+    equity *= 1 + pnl;
+    tradeLog.push({ type: "sell", date: bars[bars.length - 1].date, price: lastPrice, pnl });
+  }
+
+  return buildResult("rsi_mean_reversion", equity - 1, closes, tradeLog, maxDd);
+}
+
+function buildResult(
+  strategy: string,
+  totalReturn: number,
+  closes: number[],
+  tradeLog: BacktestResult["tradeLog"],
+  maxDrawdown: number,
+): BacktestResult {
+  const sellTrades = tradeLog.filter((t) => t.type === "sell" && t.pnl != null);
+  const wins = sellTrades.filter((t) => t.pnl! > 0).length;
+  const buyAndHoldReturn = closes.length > 1
+    ? (closes[closes.length - 1] - closes[0]) / closes[0]
+    : 0;
+
+  return {
+    strategy,
+    totalReturn,
+    buyAndHoldReturn,
+    trades: sellTrades.length,
+    wins,
+    winRate: sellTrades.length > 0 ? wins / sellTrades.length : 0,
+    maxDrawdown,
+    tradeLog,
+  };
+}
+
+function emptyResult(strategy: string, closes: number[]): BacktestResult {
+  return {
+    strategy,
+    totalReturn: 0,
+    buyAndHoldReturn: closes.length > 1
+      ? (closes[closes.length - 1] - closes[0]) / closes[0]
+      : 0,
+    trades: 0,
+    wins: 0,
+    winRate: 0,
+    maxDrawdown: 0,
+    tradeLog: [],
+  };
+}
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT, SPY)" }),
+  strategy: Type.Union(
+    [Type.Literal("sma_crossover"), Type.Literal("sma_50_200_crossover"), Type.Literal("rsi_mean_reversion")],
+    { description: "Strategy: sma_crossover (buy when SMA20 > SMA50, sell on reverse), sma_50_200_crossover (buy when SMA50 > SMA200, sell on reverse), or rsi_mean_reversion (buy when RSI < 30, sell when RSI > 70)" },
+  ),
+  period: Type.Optional(
+    Type.String({ description: "Historical period to backtest: 1y, 2y, 5y. Default: 2y" }),
+  ),
+});
+
+export const backtestTool: AgentTool<typeof params> = {
+  name: "backtest_strategy",
+  label: "Backtest Strategy",
+  description:
+    "Backtest a simple trading strategy against historical data. Supported strategies: SMA crossover (SMA20/SMA50), standard long-term SMA crossover (SMA50/SMA200), and RSI mean-reversion (buy <30, sell >70). Returns total return, win rate, max drawdown, and comparison to buy-and-hold.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const period = args.period ?? "2y";
+    const historyResult = await wrapProvider("yahoo", () => getHistory(symbol, period, "1d"));
+    if (historyResult.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Backtest unavailable for ${symbol} (${historyResult.reason}).` }],
+        details: null as any,
+      };
+    }
+    const bars = historyResult.data;
+
+    const minBars = requiredBarsForStrategy(args.strategy);
+    if (bars.length < minBars) {
+      return {
+        content: [{ type: "text", text: `Insufficient data for backtesting ${symbol} (need ${minBars}+ days, got ${bars.length})` }],
+        details: null,
+      };
+    }
+
+    const result = runBacktest(bars, args.strategy);
+
+    const outperformance = result.totalReturn - result.buyAndHoldReturn;
+    const lines = [
+      `**${symbol} Backtest: ${strategyLabel(args.strategy)}** (${bars[0].date} to ${bars[bars.length - 1].date}, ${bars.length} days)`,
+      ``,
+      `Strategy Return: ${(result.totalReturn * 100).toFixed(2)}%`,
+      `Buy & Hold Return: ${(result.buyAndHoldReturn * 100).toFixed(2)}%`,
+      `Outperformance: ${outperformance >= 0 ? "+" : ""}${(outperformance * 100).toFixed(2)}%`,
+      ``,
+      `Trades: ${result.trades} | Wins: ${result.wins} | Win Rate: ${(result.winRate * 100).toFixed(0)}%`,
+      `Max Drawdown: ${(result.maxDrawdown * 100).toFixed(2)}%`,
+      ``,
+      result.totalReturn > result.buyAndHoldReturn
+        ? `Strategy outperformed buy-and-hold by ${(outperformance * 100).toFixed(2)}%.`
+        : `Buy-and-hold outperformed the strategy by ${(-outperformance * 100).toFixed(2)}%.`,
+    ];
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: result,
+    };
+  },
+};
+
+function requiredBarsForStrategy(strategy: Strategy): number {
+  if (strategy === "sma_50_200_crossover") return 200;
+  return 60;
+}
+
+function strategyLabel(strategy: Strategy): string {
+  switch (strategy) {
+    case "sma_crossover":
+      return "SMA 20/50 Crossover";
+    case "sma_50_200_crossover":
+      return "SMA 50/200 Crossover";
+    case "rsi_mean_reversion":
+      return "RSI Mean Reversion";
+  }
+}

package/src/tools/technical/indicators.ts

@@ -0,0 +1,256 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getHistory } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { OHLCV } from "../../types/market.js";
+
+// --- Volume-based indicators ---
+
+export function computeOBV(bars: OHLCV[]): number[] {
+  const obv: number[] = [0];
+  for (let i = 1; i < bars.length; i++) {
+    if (bars[i].close > bars[i - 1].close) {
+      obv.push(obv[i - 1] + bars[i].volume);
+    } else if (bars[i].close < bars[i - 1].close) {
+      obv.push(obv[i - 1] - bars[i].volume);
+    } else {
+      obv.push(obv[i - 1]);
+    }
+  }
+  return obv;
+}
+
+export function computeVWAP(bars: OHLCV[]): number[] {
+  const vwap: number[] = [];
+  let cumPV = 0;
+  let cumVol = 0;
+  for (const bar of bars) {
+    const tp = (bar.high + bar.low + bar.close) / 3;
+    cumPV += tp * bar.volume;
+    cumVol += bar.volume;
+    vwap.push(cumVol === 0 ? 0 : cumPV / cumVol);
+  }
+  return vwap;
+}
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
+  range: Type.Optional(
+    Type.String({ description: "Time range for data: 3mo, 6mo, 1y, 2y. Default: 1y" }),
+  ),
+});
+
+export const technicalIndicatorsTool: AgentTool<typeof params> = {
+  name: "get_technical_indicators",
+  label: "Technical Indicators",
+  description:
+    "Compute technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands) from historical price data. All computed locally — no API dependency.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const range = args.range ?? "1y";
+    const result = await wrapProvider("yahoo", () => getHistory(symbol, range, "1d"));
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Technical indicators unavailable for ${symbol} (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+    const bars = result.data;
+    const closes = bars.map((b) => b.close);
+
+    if (closes.length < 26) {
+      return {
+        content: [{ type: "text", text: `Insufficient data for ${symbol} (need 26+ bars, got ${closes.length})` }],
+        details: null,
+      };
+    }
+
+    const sma20 = computeSMA(closes, 20);
+    const sma50 = computeSMA(closes, 50);
+    const rsi = computeRSI(closes, 14);
+    const macd = computeMACD(closes);
+    const bb = computeBollingerBands(closes, 20, 2);
+    const obv = computeOBV(bars);
+    const vwap = computeVWAP(bars);
+
+    const latest = closes[closes.length - 1];
+    const latestRsi = rsi[rsi.length - 1];
+    const latestMacd = macd[macd.length - 1];
+    const latestBB = bb[bb.length - 1];
+    const latestVwap = vwap[vwap.length - 1];
+    const obvTrend = obv.length >= 20
+      ? (obv[obv.length - 1] > obv[obv.length - 20] ? "Rising" : "Falling")
+      : "N/A";
+
+    const lines = [
+      `**${symbol} Technical Analysis** (${bars[0].date} to ${bars[bars.length - 1].date})`,
+      `Price: $${latest.toFixed(2)}`,
+      ``,
+      `SMA(20): $${sma20[sma20.length - 1]?.toFixed(2) ?? "N/A"} | SMA(50): $${sma50[sma50.length - 1]?.toFixed(2) ?? "N/A"}`,
+      `RSI(14): ${latestRsi?.toFixed(1) ?? "N/A"} ${rsiSignal(latestRsi)}`,
+      `MACD: ${latestMacd?.macd.toFixed(2) ?? "N/A"} | Signal: ${latestMacd?.signal.toFixed(2) ?? "N/A"} | Histogram: ${latestMacd?.histogram.toFixed(2) ?? "N/A"}`,
+      `Bollinger Bands: Upper $${latestBB?.upper.toFixed(2) ?? "N/A"} | Mid $${latestBB?.middle.toFixed(2) ?? "N/A"} | Lower $${latestBB?.lower.toFixed(2) ?? "N/A"}`,
+      `OBV Trend: ${obvTrend} | VWAP (cumulative): $${latestVwap?.toFixed(2) ?? "N/A"}`,
+      ``,
+      trendSummary(latest, sma20, sma50, latestRsi, latestMacd, obvTrend, latestVwap),
+    ];
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: {
+        symbol,
+        range,
+        prices: closes,
+        dates: bars.map((b) => b.date),
+        sma20, sma50, rsi, macd, bb, obv, vwap,
+      },
+    };
+  },
+};
+
+// --- Indicator computations (all pure functions) ---
+
+export function computeSMA(data: number[], period: number): number[] {
+  const result: number[] = [];
+  for (let i = period - 1; i < data.length; i++) {
+    let sum = 0;
+    for (let j = i - period + 1; j <= i; j++) sum += data[j];
+    result.push(sum / period);
+  }
+  return result;
+}
+
+export function computeEMA(data: number[], period: number): number[] {
+  const k = 2 / (period + 1);
+  const result: number[] = [];
+  // Seed with SMA of first `period` values
+  let sum = 0;
+  for (let i = 0; i < period; i++) sum += data[i];
+  let ema = sum / period;
+  result.push(ema);
+  for (let i = period; i < data.length; i++) {
+    ema = data[i] * k + ema * (1 - k);
+    result.push(ema);
+  }
+  return result;
+}
+
+export function computeRSI(data: number[], period: number = 14): number[] {
+  const result: number[] = [];
+  const gains: number[] = [];
+  const losses: number[] = [];
+
+  for (let i = 1; i < data.length; i++) {
+    const diff = data[i] - data[i - 1];
+    gains.push(diff > 0 ? diff : 0);
+    losses.push(diff < 0 ? -diff : 0);
+  }
+
+  if (gains.length < period) return result;
+
+  let avgGain = gains.slice(0, period).reduce((a, b) => a + b, 0) / period;
+  let avgLoss = losses.slice(0, period).reduce((a, b) => a + b, 0) / period;
+
+  const rs = avgLoss === 0 ? 100 : avgGain / avgLoss;
+  result.push(100 - 100 / (1 + rs));
+
+  for (let i = period; i < gains.length; i++) {
+    avgGain = (avgGain * (period - 1) + gains[i]) / period;
+    avgLoss = (avgLoss * (period - 1) + losses[i]) / period;
+    const rs = avgLoss === 0 ? 100 : avgGain / avgLoss;
+    result.push(100 - 100 / (1 + rs));
+  }
+
+  return result;
+}
+
+export function computeMACD(
+  data: number[],
+  fastPeriod = 12,
+  slowPeriod = 26,
+  signalPeriod = 9,
+): { macd: number; signal: number; histogram: number }[] {
+  if (data.length < slowPeriod + signalPeriod) return [];
+
+  const emaFast = computeEMA(data, fastPeriod);
+  const emaSlow = computeEMA(data, slowPeriod);
+
+  // Align: emaFast starts at index fastPeriod-1, emaSlow at slowPeriod-1
+  const offset = slowPeriod - fastPeriod;
+  const macdLine: number[] = [];
+  for (let i = 0; i < emaSlow.length; i++) {
+    macdLine.push(emaFast[i + offset] - emaSlow[i]);
+  }
+
+  if (macdLine.length < signalPeriod) return [];
+
+  const signalLine = computeEMA(macdLine, signalPeriod);
+  const signalOffset = signalPeriod - 1;
+
+  const result: { macd: number; signal: number; histogram: number }[] = [];
+  for (let i = 0; i < signalLine.length; i++) {
+    const m = macdLine[i + signalOffset];
+    const s = signalLine[i];
+    result.push({ macd: m, signal: s, histogram: m - s });
+  }
+
+  return result;
+}
+
+export function computeBollingerBands(
+  data: number[],
+  period: number = 20,
+  stdDev: number = 2,
+): { upper: number; middle: number; lower: number }[] {
+  const result: { upper: number; middle: number; lower: number }[] = [];
+  for (let i = period - 1; i < data.length; i++) {
+    const slice = data.slice(i - period + 1, i + 1);
+    const mean = slice.reduce((a, b) => a + b, 0) / period;
+    const variance = slice.reduce((a, b) => a + (b - mean) ** 2, 0) / period;
+    const sd = Math.sqrt(variance);
+    result.push({
+      upper: mean + stdDev * sd,
+      middle: mean,
+      lower: mean - stdDev * sd,
+    });
+  }
+  return result;
+}
+
+function rsiSignal(rsi: number | undefined): string {
+  if (rsi == null) return "";
+  if (rsi >= 70) return "(Overbought)";
+  if (rsi <= 30) return "(Oversold)";
+  return "(Neutral)";
+}
+
+function trendSummary(
+  price: number,
+  sma20: number[],
+  sma50: number[],
+  rsi: number | undefined,
+  macd: { macd: number; signal: number; histogram: number } | undefined,
+  obvTrend?: string,
+  vwap?: number,
+): string {
+  const signals: string[] = [];
+
+  const latestSma20 = sma20[sma20.length - 1];
+  const latestSma50 = sma50[sma50.length - 1];
+
+  if (latestSma20 && price > latestSma20) signals.push("Price above SMA(20) — short-term bullish");
+  if (latestSma20 && price < latestSma20) signals.push("Price below SMA(20) — short-term bearish");
+  if (latestSma20 && latestSma50 && latestSma20 > latestSma50) signals.push("Golden cross pattern (SMA20 > SMA50)");
+  if (latestSma20 && latestSma50 && latestSma20 < latestSma50) signals.push("Death cross pattern (SMA20 < SMA50)");
+  if (rsi != null && rsi >= 70) signals.push("RSI overbought — potential reversal");
+  if (rsi != null && rsi <= 30) signals.push("RSI oversold — potential bounce");
+  if (macd && macd.histogram > 0) signals.push("MACD bullish (histogram positive)");
+  if (macd && macd.histogram < 0) signals.push("MACD bearish (histogram negative)");
+  if (obvTrend === "Rising" && price > (latestSma20 ?? 0)) signals.push("Volume confirming price advance (OBV rising)");
+  if (obvTrend === "Falling" && price < (latestSma20 ?? Infinity)) signals.push("Volume confirming price decline (OBV falling)");
+  if (vwap != null && price > vwap) signals.push("Price above cumulative VWAP — bullish volume-weighted bias");
+  if (vwap != null && price < vwap) signals.push("Price below cumulative VWAP — bearish volume-weighted bias");
+
+  return signals.length > 0 ? "Signals: " + signals.join(" | ") : "No strong signals";
+}

package/src/types/fundamentals.ts

@@ -0,0 +1,46 @@
+export interface CompanyOverview {
+  symbol: string;
+  name: string;
+  description: string;
+  exchange: string;
+  sector: string;
+  industry: string;
+  marketCap: number;
+  pe: number | null;
+  forwardPe: number | null;
+  eps: number | null;
+  dividendYield: number | null;
+  beta: number | null;
+  week52High: number;
+  week52Low: number;
+  avgVolume: number;
+  profitMargin: number | null;
+  revenueGrowth: number | null;
+}
+
+export interface EarningsData {
+  symbol: string;
+  quarterly: Array<{
+    date: string;
+    reportedEPS: number;
+    estimatedEPS: number;
+    surprise: number;
+    surprisePercent: number;
+  }>;
+}
+
+export interface FinancialStatement {
+  fiscalDate: string;
+  revenue: number;
+  grossProfit: number;
+  operatingIncome: number;
+  netIncome: number;
+  eps: number;
+  totalAssets: number;
+  totalLiabilities: number;
+  totalEquity: number;
+  operatingCashFlow: number;
+  freeCashFlow: number;
+  totalDebt?: number;
+  cashAndEquivalents?: number;
+}

package/src/types/index.ts

@@ -0,0 +1,20 @@
+export type { StockQuote, OHLCV, CryptoPrice } from "./market.js";
+export type { CompanyOverview, EarningsData, FinancialStatement } from "./fundamentals.js";
+export type { FredObservation, FredSeries } from "./macro.js";
+export { FRED_SERIES } from "./macro.js";
+export type { Greeks, OptionContract, OptionsChain } from "./options.js";
+export type { Position, PortfolioSummary, RiskMetrics, TechnicalIndicators } from "./portfolio.js";
+export type { FearGreedData, RedditSentimentResult, WebSearchResult, WebSearchEnvelope } from "./sentiment.js";
+
+/**
+ * Handler for `ask_user` tool invocations in non-UI contexts (e.g. test harness).
+ * When provided to `createOpenCandleSession`, the ask-user tool calls this handler
+ * instead of `ctx.ui.*` methods.
+ */
+export type AskUserHandler = (params: {
+  question: string;
+  questionType: "select" | "text" | "confirm";
+  options?: string[];
+  placeholder?: string;
+  reason?: string;
+}) => Promise<{ answer: string | null; cancelled: boolean }>;

package/src/types/macro.ts

@@ -0,0 +1,27 @@
+export interface FredObservation {
+  date: string;
+  value: number;
+}
+
+export interface FredSeries {
+  id: string;
+  title: string;
+  observations: FredObservation[];
+  units: string;
+  frequency: string;
+  lastUpdated: string;
+}
+
+// Common FRED series IDs
+export const FRED_SERIES = {
+  FED_FUNDS: "FEDFUNDS",
+  TREASURY_10Y: "DGS10",
+  TREASURY_2Y: "DGS2",
+  TREASURY_30Y: "DGS30",
+  CPI: "CPIAUCSL",
+  UNEMPLOYMENT: "UNRATE",
+  GDP: "GDP",
+  YIELD_SPREAD_10Y2Y: "T10Y2Y",
+  INFLATION_EXPECTATION: "T5YIE",
+  MORTGAGE_30Y: "MORTGAGE30US",
+} as const;