opencandle 0.3.0 → 0.4.0

package/src/tools/market/stock-history.ts

@@ -0,0 +1,79 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getHistory } from "../../providers/yahoo-finance.js";
+import { getDailyHistory } from "../../providers/alpha-vantage.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { withFallback } from "../../providers/with-fallback.js";
+import { getConfig } from "../../config.js";
+import type { OHLCV } from "../../types/market.js";
+import type { ProviderResult } from "../../runtime/evidence.js";
+
+const DAILY_INTERVALS = new Set(["1d", "1wk", "1mo"]);
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
+  range: Type.Optional(
+    Type.String({
+      description: "Time range: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, max. Default: 6mo",
+    }),
+  ),
+  interval: Type.Optional(
+    Type.String({
+      description: "Data interval: 1m, 5m, 15m, 1h, 1d, 1wk, 1mo. Default: 1d",
+    }),
+  ),
+});
+
+export const stockHistoryTool: AgentTool<typeof params, OHLCV[]> = {
+  name: "get_stock_history",
+  label: "Stock History",
+  description: "Get historical OHLCV (open, high, low, close, volume) data for a stock",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const range = args.range ?? "6mo";
+    const interval = args.interval ?? "1d";
+    const apiKey = getConfig().alphaVantageApiKey;
+
+    let result: ProviderResult<OHLCV[]>;
+
+    if (DAILY_INTERVALS.has(interval) && apiKey) {
+      // Daily or above — can fall back to Alpha Vantage
+      result = await withFallback([
+        { provider: "yahoo", fn: () => getHistory(symbol, range, interval) },
+        { provider: "alphavantage", fn: () => getDailyHistory(symbol, apiKey, range) },
+      ]);
+    } else {
+      // Intraday — no cross-provider fallback
+      result = await wrapProvider("yahoo", () => getHistory(symbol, range, interval));
+    }
+
+    if (result.status === "unavailable") {
+      const intradayNote = !DAILY_INTERVALS.has(interval)
+        ? ` No alternate source for ${interval} data.`
+        : "";
+      return {
+        content: [{ type: "text", text: `⚠ Stock history unavailable for ${symbol} (${result.reason}).${intradayNote}` }],
+        details: [],
+      };
+    }
+    const bars = result.data;
+
+    const summary = [
+      `${symbol} — ${bars.length} bars (${range}, ${interval})`,
+      `Period: ${bars[0]?.date} to ${bars[bars.length - 1]?.date}`,
+    ];
+
+    // Include last 10 bars as sample
+    const recent = bars.slice(-10);
+    const table = recent
+      .map(
+        (b) =>
+          `${b.date} | O:${b.open.toFixed(2)} H:${b.high.toFixed(2)} L:${b.low.toFixed(2)} C:${b.close.toFixed(2)} V:${b.volume.toLocaleString()}`,
+      )
+      .join("\n");
+
+    const text = [...summary, "", "Recent bars:", table].join("\n");
+    return { content: [{ type: "text", text }], details: bars };
+  },
+};

package/src/tools/market/stock-quote.ts

@@ -0,0 +1,64 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getQuote } from "../../providers/yahoo-finance.js";
+import { getGlobalQuote } from "../../providers/alpha-vantage.js";
+import { withFallback } from "../../providers/with-fallback.js";
+import { getConfig } from "../../config.js";
+import type { StockQuote } from "../../types/market.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT, TSLA)" }),
+});
+
+export const stockQuoteTool: AgentTool<typeof params, StockQuote> = {
+  name: "get_stock_quote",
+  label: "Stock Quote",
+  description:
+    "Get real-time stock price, volume, market cap, and 52-week range for a ticker symbol",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const apiKey = getConfig().alphaVantageApiKey;
+
+    const entries = [
+      { provider: "yahoo" as const, fn: () => getQuote(symbol) },
+      ...(apiKey
+        ? [{ provider: "alphavantage" as const, fn: () => getGlobalQuote(symbol, apiKey) }]
+        : []),
+    ];
+
+    const result = await withFallback(entries);
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Stock quote unavailable for ${symbol} (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+    const quote = result.data;
+    const sign = quote.changePercent >= 0 ? "+" : "";
+
+    const week52 = quote.week52High > 0 && quote.week52Low > 0
+      ? `$${quote.week52Low.toFixed(2)} - $${quote.week52High.toFixed(2)}`
+      : "N/A";
+    const marketCapStr = quote.marketCap > 0 ? `$${formatLargeNumber(quote.marketCap)}` : "N/A";
+
+    const text = [
+      `${quote.symbol}: $${quote.price.toFixed(2)} (${sign}${quote.changePercent.toFixed(2)}%)`,
+      `Open: $${quote.open.toFixed(2)} | High: $${quote.high.toFixed(2)} | Low: $${quote.low.toFixed(2)}`,
+      `Volume: ${quote.volume.toLocaleString()} | Market Cap: ${marketCapStr}`,
+      `52W Range: ${week52}`,
+    ].join("\n");
+
+    const prefix = result.stale
+      ? `⚠ Using cached quote from ${result.timestamp} (provider rate limited)\n`
+      : "";
+    return { content: [{ type: "text", text: prefix + text }], details: quote };
+  },
+};
+
+function formatLargeNumber(n: number): string {
+  if (n >= 1e12) return `${(n / 1e12).toFixed(2)}T`;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+  return n.toLocaleString();
+}

package/src/tools/options/greeks.ts

@@ -0,0 +1,82 @@
+import type { Greeks } from "../../types/options.js";
+
+interface GreeksInput {
+  type: "call" | "put";
+  spot: number;       // underlying price
+  strike: number;     // strike price
+  timeYears: number;  // time to expiration in years
+  iv: number;         // implied volatility (e.g. 0.30 for 30%)
+  riskFreeRate: number; // risk-free rate (e.g. 0.05 for 5%)
+}
+
+/**
+ * Compute option Greeks using the Black-Scholes model.
+ */
+export function computeGreeks(input: GreeksInput): Greeks {
+  const { type, spot, strike, timeYears, iv, riskFreeRate: r } = input;
+
+  // At expiration: return intrinsic values
+  if (timeYears <= 0) {
+    const isCall = type === "call";
+    const itm = isCall ? spot >= strike : spot <= strike;
+    return {
+      delta: itm ? (isCall ? 1 : -1) : 0,
+      gamma: 0,
+      theta: 0,
+      vega: 0,
+      rho: 0,
+    };
+  }
+
+  const sqrtT = Math.sqrt(timeYears);
+  const d1 = (Math.log(spot / strike) + (r + (iv * iv) / 2) * timeYears) / (iv * sqrtT);
+  const d2 = d1 - iv * sqrtT;
+
+  const nd1 = cdf(d1);
+  const nd2 = cdf(d2);
+  const npd1 = pdf(d1);
+
+  const expRT = Math.exp(-r * timeYears);
+
+  if (type === "call") {
+    return {
+      delta: nd1,
+      gamma: npd1 / (spot * iv * sqrtT),
+      theta: (-(spot * npd1 * iv) / (2 * sqrtT) - r * strike * expRT * nd2) / 365,
+      vega: (spot * npd1 * sqrtT) / 100, // per 1% change in IV
+      rho: (strike * timeYears * expRT * nd2) / 100, // per 1% change in rate
+    };
+  } else {
+    const nMinusD1 = cdf(-d1);
+    const nMinusD2 = cdf(-d2);
+    return {
+      delta: nd1 - 1,
+      gamma: npd1 / (spot * iv * sqrtT),
+      theta: (-(spot * npd1 * iv) / (2 * sqrtT) + r * strike * expRT * nMinusD2) / 365,
+      vega: (spot * npd1 * sqrtT) / 100,
+      rho: -(strike * timeYears * expRT * nMinusD2) / 100,
+    };
+  }
+}
+
+/** Standard normal cumulative distribution function */
+function cdf(x: number): number {
+  // Abramowitz and Stegun approximation 26.2.17
+  const a1 = 0.254829592;
+  const a2 = -0.284496736;
+  const a3 = 1.421413741;
+  const a4 = -1.453152027;
+  const a5 = 1.061405429;
+  const p = 0.3275911;
+
+  const sign = x < 0 ? -1 : 1;
+  const absX = Math.abs(x);
+  const t = 1 / (1 + p * absX);
+  const y = 1 - ((((a5 * t + a4) * t + a3) * t + a2) * t + a1) * t * Math.exp(-absX * absX / 2);
+  return 0.5 * (1 + sign * y);
+}
+
+/** Standard normal probability density function */
+function pdf(x: number): number {
+  return Math.exp(-0.5 * x * x) / Math.sqrt(2 * Math.PI);
+}

package/src/tools/options/option-chain.ts

@@ -0,0 +1,91 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getOptionsChain } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { OptionsChain, OptionContract } from "../../types/options.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, TSLA, SPY, MSFT)" }),
+  expiration: Type.Optional(
+    Type.String({
+      description:
+        "Expiration date as YYYY-MM-DD. If omitted, uses the nearest expiration.",
+    }),
+  ),
+  type: Type.Optional(
+    Type.Union([Type.Literal("call"), Type.Literal("put"), Type.Literal("CALL"), Type.Literal("PUT")], {
+      description: "Filter by option type. Omit for both calls and puts.",
+    }),
+  ),
+});
+
+export const optionChainTool: AgentTool<typeof params, OptionsChain> = {
+  name: "get_option_chain",
+  label: "Options Chain",
+  description:
+    "Get the full options chain for a stock with strikes, bids, asks, volume, open interest, implied volatility, and computed Greeks (Delta, Gamma, Theta, Vega, Rho via Black-Scholes). No API key required.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const normalizedType = args.type?.toLowerCase();
+    const expirationTs = args.expiration
+      ? Math.floor(new Date(args.expiration).getTime() / 1000)
+      : undefined;
+
+    const result = await wrapProvider("yahoo", () => getOptionsChain(symbol, expirationTs));
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Options chain unavailable for ${symbol} (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+    const chain = result.data;
+
+    const lines: string[] = [
+      `**${chain.symbol} Options Chain** — Expiry: ${chain.expirationDate}`,
+      `Underlying: $${chain.underlyingPrice.toFixed(2)}`,
+      `Available expirations: ${formatAvailableExpirations(chain.expirationDates)}`,
+      "",
+    ];
+
+    const showCalls = !normalizedType || normalizedType === "call";
+    const showPuts = !normalizedType || normalizedType === "put";
+
+    if (showCalls && chain.calls.length > 0) {
+      lines.push(`**CALLS** (${chain.calls.length} contracts, volume: ${chain.totalCallVolume.toLocaleString()})`);
+      lines.push("Strike | Bid/Ask | Last | Vol | OI | IV | Delta | Theta");
+      const topCalls = sortByVolume(chain.calls).slice(0, 10);
+      for (const c of topCalls) {
+        lines.push(formatContract(c));
+      }
+      lines.push("");
+    }
+
+    if (showPuts && chain.puts.length > 0) {
+      lines.push(`**PUTS** (${chain.puts.length} contracts, volume: ${chain.totalPutVolume.toLocaleString()})`);
+      lines.push("Strike | Bid/Ask | Last | Vol | OI | IV | Delta | Theta");
+      const topPuts = sortByVolume(chain.puts).slice(0, 10);
+      for (const c of topPuts) {
+        lines.push(formatContract(c));
+      }
+      lines.push("");
+    }
+
+    lines.push(`Put/Call Ratio: ${chain.putCallRatio.toFixed(2)}`);
+
+    return { content: [{ type: "text", text: lines.join("\n") }], details: chain };
+  },
+};
+
+function sortByVolume(contracts: OptionContract[]): OptionContract[] {
+  return [...contracts].sort((a, b) => b.volume - a.volume);
+}
+
+function formatAvailableExpirations(expirationDates: string[]): string {
+  return expirationDates.join(", ");
+}
+
+function formatContract(c: OptionContract): string {
+  const itm = c.inTheMoney ? "*" : " ";
+  return `${itm}$${c.strike.toFixed(2)} | $${c.bid.toFixed(2)}/$${c.ask.toFixed(2)} | $${c.lastPrice.toFixed(2)} | ${c.volume} | ${c.openInterest} | ${(c.impliedVolatility * 100).toFixed(1)}% | ${c.greeks.delta.toFixed(3)} | ${c.greeks.theta.toFixed(3)}`;
+}

package/src/tools/portfolio/correlation.ts

@@ -0,0 +1,162 @@
+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 { computeDailyReturns } from "./risk-analysis.js";
+import type { OHLCV } from "../../types/market.js";
+
+export function computeCorrelation(returnsA: number[], returnsB: number[]): number {
+  const n = Math.min(returnsA.length, returnsB.length);
+  if (n === 0) return 0;
+
+  let sumA = 0, sumB = 0;
+  for (let i = 0; i < n; i++) {
+    sumA += returnsA[i];
+    sumB += returnsB[i];
+  }
+  const meanA = sumA / n;
+  const meanB = sumB / n;
+
+  let cov = 0, varA = 0, varB = 0;
+  for (let i = 0; i < n; i++) {
+    const dA = returnsA[i] - meanA;
+    const dB = returnsB[i] - meanB;
+    cov += dA * dB;
+    varA += dA * dA;
+    varB += dB * dB;
+  }
+
+  if (varA === 0 || varB === 0) return 0;
+  return cov / Math.sqrt(varA * varB);
+}
+
+const DEFAULT_MIN_OVERLAP = 20;
+
+export function alignReturnsByDate(
+  historiesBySymbol: Map<string, OHLCV[]>,
+  minOverlap: number = DEFAULT_MIN_OVERLAP,
+): Map<string, number[]> {
+  // Build date → close price maps for each symbol
+  const priceByDate = new Map<string, Map<string, number>>();
+  for (const [symbol, bars] of historiesBySymbol) {
+    const dateMap = new Map<string, number>();
+    for (const bar of bars) {
+      dateMap.set(bar.date, bar.close);
+    }
+    priceByDate.set(symbol, dateMap);
+  }
+
+  // Find common dates across all symbols
+  const symbols = [...historiesBySymbol.keys()];
+  const firstDates = priceByDate.get(symbols[0])!;
+  const commonDates = [...firstDates.keys()].filter((date) =>
+    symbols.every((s) => priceByDate.get(s)!.has(date)),
+  ).sort();
+
+  if (commonDates.length < minOverlap) {
+    throw new Error(
+      `Insufficient date overlap for correlation: ${commonDates.length} common dates (need ${minOverlap}+). Symbols may trade on different exchanges or have sparse history.`,
+    );
+  }
+
+  // Extract aligned close prices, then compute returns
+  const result = new Map<string, number[]>();
+  for (const symbol of symbols) {
+    const dateMap = priceByDate.get(symbol)!;
+    const alignedCloses = commonDates.map((d) => dateMap.get(d)!);
+    result.set(symbol, computeDailyReturns(alignedCloses));
+  }
+
+  return result;
+}
+
+const params = Type.Object({
+  symbols: Type.Array(Type.String(), {
+    description: "Array of 2+ ticker symbols to compute correlation matrix (e.g. ['AAPL','MSFT','GOOGL'])",
+    minItems: 2,
+  }),
+  period: Type.Optional(
+    Type.String({ description: "Historical period: 6mo, 1y, 2y. Default: 1y" }),
+  ),
+});
+
+export const correlationTool: AgentTool<typeof params> = {
+  name: "analyze_correlation",
+  label: "Correlation Matrix",
+  description:
+    "Compute pairwise return correlations between 2+ stocks. Identifies highly correlated positions (|r| > 0.7) as concentration risk. Useful for portfolio diversification analysis.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const symbols = args.symbols.map((s) => s.toUpperCase());
+    const period = args.period ?? "1y";
+
+    if (symbols.length < 2) {
+      throw new Error("Need at least 2 symbols for correlation analysis.");
+    }
+
+    // Fetch history for all symbols in parallel
+    const results = await Promise.all(
+      symbols.map(async (s) => ({
+        symbol: s,
+        result: await wrapProvider("yahoo", () => getHistory(s, period, "1d")),
+      })),
+    );
+
+    const unavailable = results.filter((r) => r.result.status === "unavailable");
+    if (unavailable.length === results.length) {
+      return {
+        content: [{ type: "text", text: `⚠ Correlation analysis unavailable — could not fetch history for any symbol.` }],
+        details: null as any,
+      };
+    }
+
+    const historiesBySymbol = new Map<string, OHLCV[]>();
+    for (const { symbol: sym, result: r } of results) {
+      if (r.status === "ok") historiesBySymbol.set(sym, r.data);
+    }
+
+    const returnsBySymbol = alignReturnsByDate(historiesBySymbol);
+
+    // Build correlation matrix
+    const matrix: Record<string, Record<string, number>> = {};
+    const warnings: string[] = [];
+
+    for (const a of symbols) {
+      matrix[a] = {};
+      for (const b of symbols) {
+        if (a === b) {
+          matrix[a][b] = 1.0;
+        } else if (matrix[b]?.[a] != null) {
+          matrix[a][b] = matrix[b][a];
+        } else {
+          const r = computeCorrelation(returnsBySymbol.get(a)!, returnsBySymbol.get(b)!);
+          matrix[a][b] = r;
+          if (Math.abs(r) > 0.7 && a < b) {
+            warnings.push(`${a}/${b}: r=${r.toFixed(2)} — high correlation, concentration risk`);
+          }
+        }
+      }
+    }
+
+    // Format output
+    const header = `**Correlation Matrix** (${period} daily returns)`;
+    const colHeader = `${"".padEnd(8)} ${symbols.map((s) => s.padStart(8)).join("")}`;
+    const rows = symbols.map((a) => {
+      const cells = symbols.map((b) => matrix[a][b].toFixed(2).padStart(8));
+      return `${a.padEnd(8)} ${cells.join("")}`;
+    });
+
+    const lines = [header, "", colHeader, ...rows];
+    if (warnings.length > 0) {
+      lines.push("", "**Concentration Warnings:**");
+      for (const w of warnings) lines.push(`  - ${w}`);
+    } else {
+      lines.push("", "No high-correlation pairs detected. Portfolio appears diversified.");
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { matrix, warnings },
+    };
+  },
+};