opencandle 0.2.0 → 0.4.0

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

@@ -0,0 +1,150 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { searchWeb } from "../../providers/web-search.js";
+import type { WebSearchEnvelope } from "../../types/sentiment.js";
+import { hasCredential } from "../../onboarding/providers.js";
+import { buildSoftDegradedTag } from "../../onboarding/tool-tags.js";
+
+const params = Type.Object({
+  query: Type.String({ description: "Search query — ticker, topic, or question" }),
+  category: Type.Optional(
+    Type.Union([Type.Literal("news"), Type.Literal("general")], {
+      description: 'Search category. "news" for recent articles, "general" for broader web. Default: "news"',
+    }),
+  ),
+  freshness: Type.Optional(
+    Type.Union(
+      [Type.Literal("hours"), Type.Literal("day"), Type.Literal("week"), Type.Literal("month")],
+      { description: 'Time range filter. Default: "day"' },
+    ),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Number of results (1-20). Default: 10", minimum: 1, maximum: 20 }),
+  ),
+  provider: Type.Optional(
+    Type.Union([Type.Literal("exa"), Type.Literal("brave"), Type.Literal("ddg")], {
+      description: "Override search provider (skip cascade). Default: auto (Exa → Brave → DDG)",
+    }),
+  ),
+});
+
+function escapeMd(text: string): string {
+  return text.replace(/([[\]|])/g, "\\$1");
+}
+
+function safeUrl(url: string): string {
+  if (url.startsWith("https://") || url.startsWith("http://")) return url;
+  return `https://${url}`;
+}
+
+/**
+ * Build soft-degradation tags for search providers whose credentials are
+ * missing at call time. Returns an empty string when nothing is degraded, or
+ * a newline-terminated block of `[OPENCANDLE_SOFT_DEGRADED ...]` tags ready to
+ * prepend to the tool result content. The extension's `tool_result` handler
+ * records these into the per-turn degradation accumulator; the system prompt
+ * instructs the LLM to surface them in a `**Data gaps**` section.
+ *
+ * Emission rules:
+ *   - Brave: if `hasCredential("brave") === false` AND the envelope's
+ *     provider is not `"brave"`, the cascade fell back from Brave.
+ *   - Exa:   if `hasCredential("exa") === false` AND the envelope's provider
+ *     is `"exa"`, the Exa provider used the keyless MCP path instead of the
+ *     keyed API. Envelopes served by `ddg` are NOT tagged for Exa (Exa was
+ *     tried first and failed for a reason unrelated to credentials).
+ */
+function buildSoftDegradedPrefix(data: WebSearchEnvelope): string {
+  const tags: string[] = [];
+
+  if (!hasCredential("brave") && data.provider !== "brave") {
+    tags.push(
+      buildSoftDegradedTag({
+        provider: "brave",
+        fallback: data.provider === "exa" ? "exa" : "ddg",
+        remediation: "run /connect search to enable Brave",
+      }),
+    );
+  }
+
+  if (!hasCredential("exa") && data.provider === "exa") {
+    tags.push(
+      buildSoftDegradedTag({
+        provider: "exa",
+        fallback: "keyless-mcp",
+        remediation: "run /connect search to enable keyed Exa",
+      }),
+    );
+  }
+
+  return tags.length === 0 ? "" : `${tags.join("\n")}\n\n`;
+}
+
+export const webSearchTool: AgentTool<typeof params, WebSearchEnvelope> = {
+  name: "search_web",
+  label: "Web Search",
+  description:
+    "Search the web for financial news, earnings context, company events, regulatory developments, or general information. " +
+    "NOT for real-time prices, historical data, fundamentals, macro data, SEC filings, or social sentiment — those have dedicated tools.",
+  parameters: params,
+
+  async execute(toolCallId, args) {
+    const query = args.query?.trim();
+    if (!query) {
+      return {
+        content: [{ type: "text", text: "⚠ Cannot search with an empty query." }],
+        details: null as any,
+      };
+    }
+
+    const category = args.category ?? "news";
+    const freshness = args.freshness ?? "day";
+    const limit = Math.max(1, Math.min(args.limit ?? 10, 20));
+
+    const provider = args.provider;
+    const result = await searchWeb(query, { category, freshness, limit, provider });
+
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Web search unavailable (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+
+    const data = result.data;
+
+    if (data.resultCount === 0) {
+      const zeroPrefix = buildSoftDegradedPrefix(data);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${zeroPrefix}No results found for "${query}" (${category}, past ${freshness}).`,
+          },
+        ],
+        details: data,
+      };
+    }
+
+    const stalePrefix = result.stale
+      ? `⚠ Using cached data from ${result.timestamp}\n\n`
+      : "";
+
+    const softDegradedPrefix = buildSoftDegradedPrefix(data);
+
+    const header = `**Web Search** — ${data.resultCount} results for "${query}" (${category}, past ${freshness}, via ${data.provider})`;
+    const items = data.results.map((r) => {
+      const title = escapeMd(r.title);
+      const snippet = escapeMd(r.snippet);
+      const url = safeUrl(r.url);
+      const pub = r.published ? `Published: ${r.published}` : "Published: unknown";
+      return `• [${title}](${url}) — ${r.source}\n  ${snippet}\n  ${pub}`;
+    });
+
+    const text = `${softDegradedPrefix}${stalePrefix}${header}\n\n${items.join("\n\n")}`;
+
+    return {
+      content: [{ type: "text", text }],
+      details: data,
+    };
+  },
+};

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,246 @@
+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" | "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);
+  const buyAndHoldReturn = closes.length > 1
+    ? (closes[closes.length - 1] - closes[0]) / closes[0]
+    : 0;
+
+  if (strategy === "sma_crossover") {
+    return backtestSMACrossover(bars, closes);
+  }
+  return backtestRSIMeanReversion(bars, closes);
+}
+
+function backtestSMACrossover(bars: OHLCV[], closes: number[]): BacktestResult {
+  const sma20 = computeSMA(closes, 20);
+  const sma50 = computeSMA(closes, 50);
+
+  if (sma50.length === 0) {
+    return emptyResult("sma_crossover", closes);
+  }
+
+  // Align: SMA(20) starts at index 19, SMA(50) at index 49
+  // sma20[i] corresponds to closes[i + 19], sma50[i] to closes[i + 49]
+  const offset20 = 19;
+  const offset50 = 49;
+
+  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 < sma50.length; i++) {
+    const barIdx = i + offset50;
+    const sma20Idx = i + (offset50 - offset20);
+    const s20 = sma20[sma20Idx];
+    const s50 = sma50[i];
+    const price = closes[barIdx];
+
+    if (!position && s20 > s50) {
+      // Buy signal
+      position = true;
+      entryPrice = price;
+      tradeLog.push({ type: "buy", date: bars[barIdx].date, price });
+    } else if (position && s20 < s50) {
+      // 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("sma_crossover", 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("rsi_mean_reversion")],
+    { description: "Strategy: sma_crossover (buy when SMA20 > SMA50, 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) 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;
+
+    if (bars.length < 60) {
+      return {
+        content: [{ type: "text", text: `Insufficient data for backtesting ${symbol} (need 60+ days, got ${bars.length})` }],
+        details: null,
+      };
+    }
+
+    const result = runBacktest(bars, args.strategy);
+
+    const outperformance = result.totalReturn - result.buyAndHoldReturn;
+    const lines = [
+      `**${symbol} Backtest: ${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,
+    };
+  },
+};