opencandle 0.3.0 → 0.4.0

package/src/tools/technical/indicators.ts

@@ -0,0 +1,258 @@
+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 ema12 = computeEMA(closes, 12);
+    const ema26 = computeEMA(closes, 26);
+    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;

package/src/types/market.ts

@@ -0,0 +1,43 @@
+export interface StockQuote {
+  symbol: string;
+  price: number;
+  change: number;
+  changePercent: number;
+  open: number;
+  high: number;
+  low: number;
+  previousClose: number;
+  volume: number;
+  marketCap: number;
+  pe: number | null;
+  week52High: number;
+  week52Low: number;
+  timestamp: number;
+}
+
+export interface OHLCV {
+  date: string;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+}
+
+export interface CryptoPrice {
+  id: string;
+  symbol: string;
+  name: string;
+  price: number;
+  change24h: number;
+  changePercent24h: number;
+  marketCap: number;
+  volume24h: number;
+  high24h: number;
+  low24h: number;
+  ath: number;
+  athDate: string;
+  circulatingSupply: number;
+  totalSupply: number | null;
+  timestamp: number;
+}

package/src/types/options.ts

@@ -0,0 +1,35 @@
+export interface Greeks {
+  delta: number;
+  gamma: number;
+  theta: number;
+  vega: number;
+  rho: number;
+}
+
+export interface OptionContract {
+  contractSymbol: string;
+  type: "call" | "put";
+  strike: number;
+  expiration: string;
+  bid: number;
+  ask: number;
+  lastPrice: number;
+  volume: number;
+  openInterest: number;
+  impliedVolatility: number;
+  inTheMoney: boolean;
+  greeks: Greeks;
+}
+
+export interface OptionsChain {
+  symbol: string;
+  underlyingPrice: number;
+  expirationDate: string;
+  expirationDates: string[];
+  calls: OptionContract[];
+  puts: OptionContract[];
+  totalCallVolume: number;
+  totalPutVolume: number;
+  putCallRatio: number;
+  fetchedAt: string;
+}

package/src/types/portfolio.ts

@@ -0,0 +1,41 @@
+export interface Position {
+  symbol: string;
+  shares: number;
+  avgCost: number;
+  addedAt: string;
+}
+
+export interface PortfolioSummary {
+  positions: Array<
+    Position & {
+      currentPrice: number;
+      marketValue: number;
+      totalCost: number;
+      pnl: number;
+      pnlPercent: number;
+    }
+  >;
+  totalValue: number;
+  totalCost: number;
+  totalPnl: number;
+  totalPnlPercent: number;
+}
+
+export interface RiskMetrics {
+  symbol: string;
+  annualizedReturn: number;
+  annualizedVolatility: number;
+  sharpeRatio: number;
+  maxDrawdown: number;
+  var95: number; // 95% Value at Risk (daily)
+}
+
+export interface TechnicalIndicators {
+  symbol: string;
+  period: string;
+  sma: number[];
+  ema: number[];
+  rsi: number[];
+  macd: { macd: number; signal: number; histogram: number }[];
+  bollingerBands: { upper: number; middle: number; lower: number }[];
+}

package/src/types/sentiment.ts

@@ -0,0 +1,70 @@
+export interface FearGreedData {
+  value: number;
+  label: string; // "Extreme Fear" | "Fear" | "Neutral" | "Greed" | "Extreme Greed"
+  timestamp: number;
+  previousClose: number;
+  weekAgo: number | null;
+  monthAgo: number | null;
+}
+
+export interface TwitterTweet {
+  id: string;
+  text: string;
+  author: string;
+  likes: number;
+  retweets: number;
+  replies: number;
+  views: number | null;
+  url: string;
+  created: string;
+}
+
+export interface TwitterSentimentResult {
+  query: string;
+  tweetCount: number;
+  tweets: TwitterTweet[];
+  sentimentScore: number;   // -1.0 (fully bearish) to +1.0 (fully bullish)
+  bullishCount: number;
+  bearishCount: number;
+  topMentions: string[];
+  fetchedAt: string;
+}
+
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+  /** Domain extracted from url (e.g., "reuters.com") */
+  source: string;
+  /** ISO 8601 timestamp, null if unknown */
+  published: string | null;
+  category: "news" | "general";
+}
+
+export interface WebSearchEnvelope {
+  query: string;
+  results: WebSearchResult[];
+  resultCount: number;
+  fetchedAt: string;
+  provider: "ddg" | "brave" | "exa";
+}
+
+export interface RedditSentimentResult {
+  subreddit: string;
+  postCount: number;
+  posts: Array<{
+    id: string;
+    title: string;
+    selftext: string;
+    author: string;
+    score: number;
+    comments: number;
+    url: string;
+    created: string;
+  }>;
+  topMentions: string[];
+  sentimentScore: number;   // -1.0 (fully bearish) to +1.0 (fully bullish)
+  bullishCount: number;
+  bearishCount: number;
+  fetchedAt: string;
+}

package/src/workflows/compare-assets.ts

@@ -0,0 +1,39 @@
+import type { CompareAssetsSlots, SlotResolution } from "../routing/types.js";
+import { buildCompareAssetsPrompt } from "../prompts/workflow-prompts.js";
+import type { WorkflowPlan } from "./types.js";
+import type { WorkflowDefinition } from "../runtime/prompt-step.js";
+import { promptStep } from "../runtime/prompt-step.js";
+
+export function buildCompareAssetsWorkflowDefinition(
+  resolution: SlotResolution<CompareAssetsSlots>,
+): WorkflowDefinition {
+  const symbols = resolution.resolved.symbols.join(", ");
+
+  return {
+    workflowType: "compare_assets",
+    steps: [
+      promptStep("fetch_data", "Fetch data for all assets", buildCompareAssetsPrompt(resolution), {
+        requiredInputs: ["symbols"],
+        expectedOutputs: ["asset_data"],
+      }),
+      promptStep("compare_and_present", "Present side-by-side comparison", `Now present the side-by-side comparison for ${symbols}:
+- Keep any unavailable fundamentals marked as unavailable instead of retrying the same failed provider calls.
+- Use the price, technical, and risk data you already fetched to finish the comparison even if some fundamentals are missing.
+- End with a concise verdict on which asset looks strongest right now and why.`, {
+        requiredInputs: ["asset_data"],
+        expectedOutputs: ["comparison_summary"],
+      }),
+    ],
+  };
+}
+
+/** @deprecated Use buildCompareAssetsWorkflowDefinition instead */
+export function buildCompareAssetsWorkflow(
+  resolution: SlotResolution<CompareAssetsSlots>,
+): WorkflowPlan {
+  const def = buildCompareAssetsWorkflowDefinition(resolution);
+  return {
+    initialPrompt: def.steps[0].prompt,
+    followUps: def.steps.slice(1).map((s) => s.prompt),
+  };
+}

package/src/workflows/index.ts

@@ -0,0 +1,4 @@
+export { buildPortfolioWorkflow, buildPortfolioWorkflowDefinition } from "./portfolio-builder.js";
+export { buildCompareAssetsWorkflow, buildCompareAssetsWorkflowDefinition } from "./compare-assets.js";
+export { buildOptionsScreenerWorkflow, buildOptionsScreenerWorkflowDefinition } from "./options-screener.js";
+export type { WorkflowPlan } from "./types.js";

package/src/workflows/options-screener.ts

@@ -0,0 +1,49 @@
+import type { OptionsScreenerSlots, SlotResolution } from "../routing/types.js";
+import { buildOptionsScreenerPrompt } from "../prompts/workflow-prompts.js";
+import type { WorkflowPlan } from "./types.js";
+import type { WorkflowDefinition } from "../runtime/prompt-step.js";
+import { promptStep } from "../runtime/prompt-step.js";
+
+export function buildOptionsScreenerWorkflowDefinition(resolution: SlotResolution<OptionsScreenerSlots>): WorkflowDefinition {
+  const s = resolution.resolved;
+  const contractType = s.direction === "bullish" ? "calls" : "puts";
+
+  return {
+    workflowType: "options_screener",
+    steps: [
+      promptStep("fetch_chain", "Fetch option chain data", buildOptionsScreenerPrompt(resolution), {
+        requiredInputs: ["symbol"],
+        expectedOutputs: ["option_chain"],
+      }),
+      promptStep("rank_and_present", "Rank and present top contracts", `Now rank and present the top ${contractType} for ${s.symbol}. You MUST produce a final text response — never end this turn with only tool calls.
+
+1. From the option chain data already fetched, select the top 3-5 contracts matching: ${s.moneynessPreference} strikes, DTE near ${s.dteTarget}, with ${s.liquidityMinimum}.
+2. Rank by ${s.objective}: balance premium cost, delta exposure, and probability of profit. Only include contracts with |delta| >= 0.20.
+3. Present a table: strike, expiry, premium, delta, IV, open interest, bid-ask spread.
+4. Explain why the #1 pick is ranked highest.
+5. State all assumptions used (which were defaults vs user-specified vs saved preferences).
+6. Include risk caveats: max loss = premium, IV crush risk, time decay (theta).
+
+If some or all of the option chain fetches returned "⚠ Options chain unavailable" or similar gaps, do NOT abort. Instead:
+- Rank and present whatever contracts you did retrieve from the successful fetches, even if fewer than 3.
+- If no chain data is usable at all, still produce a text response: reproduce the Assumptions block, state which expirations failed, and commit to a next step (e.g. "retry nearest monthly expiration", "use price/technicals instead"). Never end the turn with only tool calls.
+
+Length constraints:
+- Max 1 sentence explaining the #1 pick.
+- Risk caveats: max 3 bullet points.
+- Keep total response under 30 lines.`, {
+        requiredInputs: ["option_chain"],
+        expectedOutputs: ["ranked_contracts"],
+      }),
+    ],
+  };
+}
+
+/** @deprecated Use buildOptionsScreenerWorkflowDefinition instead */
+export function buildOptionsScreenerWorkflow(resolution: SlotResolution<OptionsScreenerSlots>): WorkflowPlan {
+  const def = buildOptionsScreenerWorkflowDefinition(resolution);
+  return {
+    initialPrompt: def.steps[0].prompt,
+    followUps: def.steps.slice(1).map((s) => s.prompt),
+  };
+}