opencandle 0.11.1 → 0.13.0

package/src/tool-kit.ts

@@ -1,69 +0,0 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { TSchema } from "@sinclair/typebox";
-import { agentToolToPiTool } from "./pi/tool-adapter.js";
-
-export type { AgentTool } from "@earendil-works/pi-agent-core";
-export type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-export { Type } from "@sinclair/typebox";
-// Re-exports for tool authors — import from "opencandle/tool-kit"
-export { Cache, cache, TTL } from "./infra/cache.js";
-export { type HttpClientOptions, HttpError, httpGet } from "./infra/http-client.js";
-export { RateLimiter, rateLimiter } from "./infra/rate-limiter.js";
-export { agentToolToPiTool } from "./pi/tool-adapter.js";
-
-// Module-level registry — all extensions run in the same Node.js process,
-// so keep a deduped index keyed by tool name.
-const addonToolRegistry = new Map<string, { name: string; description: string }>();
-
-export function getAddonToolDescriptions(): ReadonlyArray<{ name: string; description: string }> {
-  return Array.from(addonToolRegistry.values());
-}
-
-const SNAKE_CASE_VERB_RE =
-  /^(get|analyze|search|calculate|compare|compute|track|manage|backtest|list|fetch|check)_[a-z][a-z0-9_]*$/;
-
-export interface ToolConfig<TParams extends TSchema, TDetails = unknown> {
-  name: string;
-  label: string;
-  description: string;
-  parameters: TParams;
-  execute: AgentTool<TParams, TDetails>["execute"];
-}
-
-export function createTool<TParams extends TSchema, TDetails = unknown>(
-  config: ToolConfig<TParams, TDetails>,
-): AgentTool<TParams, TDetails> {
-  if (!config.name || !SNAKE_CASE_VERB_RE.test(config.name)) {
-    throw new Error(
-      `Invalid tool name "${config.name}": must be snake_case and start with a verb prefix ` +
-        `(get_, analyze_, search_, calculate_, compare_, compute_, track_, manage_, backtest_, list_, fetch_, check_)`,
-    );
-  }
-  if (!config.description || config.description.trim().length === 0) {
-    throw new Error(`Tool "${config.name}" requires a non-empty description`);
-  }
-  if (!config.parameters) {
-    throw new Error(`Tool "${config.name}" requires parameters (Typebox schema)`);
-  }
-  return {
-    name: config.name,
-    label: config.label,
-    description: config.description,
-    parameters: config.parameters,
-    execute: config.execute,
-  };
-}
-
-export function registerTools<TParams extends TSchema>(
-  pi: ExtensionAPI,
-  tools: AgentTool<TParams>[],
-): void {
-  for (const tool of tools) {
-    if (addonToolRegistry.has(tool.name)) {
-      console.warn(`[opencandle] Warning: tool "${tool.name}" already registered (overwriting)`);
-    }
-    pi.registerTool(agentToolToPiTool(tool));
-    addonToolRegistry.set(tool.name, { name: tool.name, description: tool.description });
-  }
-}

package/src/tools/AGENTS.md

@@ -1,36 +0,0 @@
-# TOOLS
-
-Market analysis tools organized by financial domain. Tools fetch data from `src/providers/`, return structured results for LLM synthesis.
-
-## STRUCTURE
-```
-src/tools/
-├── fundamentals/  # Earnings, financials, DCF, comps, SEC filings
-├── technical/     # Indicators (SMA, RSI, MACD), backtesting
-├── options/       # Options chains, Greeks computation
-├── macro/         # FRED economic data, fear & greed index
-├── sentiment/     # Reddit sentiment, news sentiment
-├── portfolio/     # Tracker, risk analysis, watchlist, correlation
-├── market/        # Stock quotes, history, crypto, ticker search
-└── index.ts       # getAllTools() registry — add new tools here
-```
-
-## LOOKUP
-| Domain | Location |
-|--------|----------|
-| P/E, EPS, balance sheets, DCF | `fundamentals/` |
-| RSI, MACD, SMA, backtest | `technical/` |
-| Put/call ratio, IV, Greeks | `options/` |
-| GDP, inflation, Fed rates | `macro/` |
-| Reddit buzz, news | `sentiment/` |
-| Positions, Sharpe, VaR, watchlist | `portfolio/` |
-| Quotes, OHLCV, crypto, search | `market/` |
-
-## ADDING A TOOL
-1. Create `src/tools/<domain>/my-tool.ts` with Typebox params + `AgentTool` export.
-2. Register in `src/tools/index.ts` (`getAllTools()` array).
-3. Add test in `tests/unit/tools/` with fixture-based fetch mocking.
-
-## ANTI-PATTERNS
-- Never hardcode mock data in tools; call providers.
-- Tools return structured data. The LLM analyzes it, not the tool.

package/src/tools/fundamentals/company-overview.ts

@@ -1,64 +0,0 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { Type } from "@sinclair/typebox";
-import { getConfig } from "../../config.js";
-import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
-import { getOverview } from "../../providers/alpha-vantage.js";
-import { wrapProvider } from "../../providers/wrap-provider.js";
-import type { CompanyOverview } from "../../types/fundamentals.js";
-
-const params = Type.Object({
-  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
-});
-
-export const companyOverviewTool: AgentTool<
-  typeof params,
-  CompanyOverview | { credentialRequired: unknown }
-> = {
-  name: "get_company_overview",
-  label: "Company Overview",
-  description:
-    "Get company fundamentals: P/E ratio, EPS, market cap, sector, dividend yield, profit margin, beta, and description. Requires Alpha Vantage.",
-  parameters: params,
-  async execute(_toolCallId, args) {
-    return withCredentialCheck("alpha_vantage", async () => {
-      const apiKey = getConfig().alphaVantageApiKey!;
-      const result = await wrapProvider("alphavantage", () =>
-        getOverview(args.symbol.toUpperCase(), apiKey),
-      );
-      if (result.status === "unavailable") {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `⚠ Company overview unavailable for ${args.symbol.toUpperCase()} (${result.reason}). Analysis will proceed without fundamentals.`,
-            },
-          ],
-          details: null as any,
-        };
-      }
-      const ov = result.data;
-      const text = [
-        `**${ov.name}** (${ov.symbol}) — ${ov.exchange}`,
-        `Sector: ${ov.sector} | Industry: ${ov.industry}`,
-        `Market Cap: $${formatLargeNumber(ov.marketCap)} | P/E: ${ov.pe ?? "N/A"} | Fwd P/E: ${ov.forwardPe ?? "N/A"}`,
-        `EPS: $${ov.eps ?? "N/A"} | Div Yield: ${ov.dividendYield ? `${(ov.dividendYield * 100).toFixed(2)}%` : "N/A"}`,
-        `Beta: ${ov.beta ?? "N/A"} | Profit Margin: ${ov.profitMargin ? `${(ov.profitMargin * 100).toFixed(1)}%` : "N/A"}`,
-        `52W: $${ov.week52Low.toFixed(2)} - $${ov.week52High.toFixed(2)}`,
-        ``,
-        `${ov.description.slice(0, 300)}${ov.description.length > 300 ? "..." : ""}`,
-      ].join("\n");
-
-      const prefix = result.stale
-        ? `⚠ Using cached fundamentals from ${result.timestamp} (Alpha Vantage rate limited)\n`
-        : "";
-      return { content: [{ type: "text", text: prefix + text }], details: ov };
-    });
-  },
-};
-
-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/fundamentals/comps.ts

@@ -1,180 +0,0 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { Type } from "@sinclair/typebox";
-import { getConfig } from "../../config.js";
-import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
-import { getOverview } from "../../providers/alpha-vantage.js";
-import { wrapProvider } from "../../providers/wrap-provider.js";
-import { getYahooCompanyOverview } from "../../providers/yahoo-finance.js";
-import type { CompanyOverview } from "../../types/fundamentals.js";
-
-export interface CompsMetric {
-  metric: string;
-  values: Record<string, number | null>;
-  median: number | null;
-  p25: number | null;
-  p75: number | null;
-  best: string;
-  worst: string;
-}
-
-export interface CompsResult {
-  companies: CompanyOverview[];
-  metrics: CompsMetric[];
-  unavailableSymbols: string[];
-  unavailableReasons: Record<string, string>;
-}
-
-type MetricDef = {
-  name: string;
-  extract: (c: CompanyOverview) => number | null;
-  lowerIsBetter: boolean;
-};
-
-const METRIC_DEFS: MetricDef[] = [
-  { name: "P/E", extract: (c) => c.pe, lowerIsBetter: true },
-  { name: "Forward P/E", extract: (c) => c.forwardPe, lowerIsBetter: true },
-  { name: "EPS", extract: (c) => c.eps, lowerIsBetter: false },
-  { name: "Profit Margin", extract: (c) => c.profitMargin, lowerIsBetter: false },
-  { name: "Revenue Growth", extract: (c) => c.revenueGrowth, lowerIsBetter: false },
-  { name: "Dividend Yield", extract: (c) => c.dividendYield, lowerIsBetter: false },
-  { name: "Beta", extract: (c) => c.beta, lowerIsBetter: true },
-];
-
-export function computeComps(companies: CompanyOverview[]): CompsResult {
-  const metrics: CompsMetric[] = METRIC_DEFS.map((def) => {
-    const values: Record<string, number | null> = {};
-    for (const c of companies) {
-      values[c.symbol] = def.extract(c);
-    }
-
-    const nonNull = Object.entries(values)
-      .filter(([, v]) => v != null)
-      .map(([sym, v]) => ({ sym, v: v! }));
-
-    const sorted = [...nonNull].sort((a, b) => a.v - b.v);
-    const sortedVals = sorted.map((s) => s.v);
-    const median = computeMedian(sortedVals);
-    const p25 = computePercentile(sortedVals, 0.25);
-    const p75 = computePercentile(sortedVals, 0.75);
-
-    const best = def.lowerIsBetter
-      ? (sorted[0]?.sym ?? "")
-      : (sorted[sorted.length - 1]?.sym ?? "");
-    const worst = def.lowerIsBetter
-      ? (sorted[sorted.length - 1]?.sym ?? "")
-      : (sorted[0]?.sym ?? "");
-
-    return { metric: def.name, values, median, p25, p75, best, worst };
-  });
-
-  return { companies, metrics, unavailableSymbols: [], unavailableReasons: {} };
-}
-
-function computeMedian(sorted: number[]): number | null {
-  if (sorted.length === 0) return null;
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
-}
-
-function computePercentile(sorted: number[], p: number): number | null {
-  if (sorted.length === 0) return null;
-  if (sorted.length === 1) return sorted[0];
-  const idx = p * (sorted.length - 1);
-  const lower = Math.floor(idx);
-  const upper = Math.ceil(idx);
-  if (lower === upper) return sorted[lower];
-  return sorted[lower] + (sorted[upper] - sorted[lower]) * (idx - lower);
-}
-
-const params = Type.Object({
-  symbols: Type.Array(Type.String(), {
-    description: "Array of 2-6 ticker symbols to compare (e.g. ['AAPL','MSFT','GOOGL'])",
-    minItems: 2,
-    maxItems: 6,
-  }),
-});
-
-export const compsTool: AgentTool<typeof params> = {
-  name: "compare_companies",
-  label: "Comparable Company Analysis",
-  description:
-    "Compare 2-6 companies side-by-side on key valuation and financial metrics: P/E, Forward P/E, EPS, Profit Margin, Revenue Growth, Dividend Yield, Beta. Identifies the cheapest and most expensive on each metric.",
-  parameters: params,
-  async execute(_toolCallId, args) {
-    return withCredentialCheck("alpha_vantage", async () => {
-      const config = getConfig();
-      const symbols = args.symbols.map((s) => s.toUpperCase());
-
-      const companies: CompanyOverview[] = [];
-      const unavailableSymbols: string[] = [];
-      const unavailableReasons: Record<string, string> = {};
-
-      for (const sym of symbols) {
-        const alphaResult = await wrapProvider("alphavantage", () =>
-          getOverview(sym, config.alphaVantageApiKey!),
-        );
-        if (alphaResult.status === "ok") {
-          companies.push(alphaResult.data);
-          continue;
-        }
-
-        const yahooResult = await wrapProvider("yahoo", () => getYahooCompanyOverview(sym));
-        if (yahooResult.status === "ok") {
-          companies.push(yahooResult.data);
-        } else {
-          unavailableSymbols.push(sym);
-          unavailableReasons[sym] =
-            `Alpha Vantage: ${alphaResult.reason}; Yahoo Finance: ${yahooResult.reason}`;
-        }
-      }
-
-      if (companies.length === 0) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `⚠ Company fundamentals unavailable for all symbols: ${symbols.join(", ")}. Alpha Vantage may be rate limited.`,
-            },
-          ],
-          details: null as any,
-        };
-      }
-
-      const result = computeComps(companies);
-      result.unavailableSymbols = unavailableSymbols;
-      result.unavailableReasons = unavailableReasons;
-
-      const availableSymbols = companies.map((company) => company.symbol);
-      const header = `**Comparable Company Analysis**: ${availableSymbols.join(" vs ")}`;
-      const rows = result.metrics.map((m) => {
-        const vals = availableSymbols.map((s) => {
-          const v = m.values[s];
-          if (v == null) return "N/A".padStart(10);
-          if (Math.abs(v) < 1) return `${(v * 100).toFixed(1)}%`.padStart(10);
-          return v.toFixed(2).padStart(10);
-        });
-        const medStr =
-          m.median != null
-            ? Math.abs(m.median) < 1
-              ? `${(m.median * 100).toFixed(1)}%`
-              : m.median.toFixed(2)
-            : "N/A";
-        return `  ${m.metric.padEnd(16)} ${vals.join("")}  Med: ${medStr}  Best: ${m.best}`;
-      });
-
-      const symHeader = `  ${"Metric".padEnd(16)} ${availableSymbols.map((s) => s.padStart(10)).join("")}`;
-      const noteLines =
-        unavailableSymbols.length > 0
-          ? ["", `Unavailable fundamentals: ${unavailableSymbols.join(", ")}`]
-          : [];
-      const reasonLines =
-        unavailableSymbols.length > 0
-          ? unavailableSymbols.map((symbol) => `  - ${symbol} (${unavailableReasons[symbol]})`)
-          : [];
-      const text = [header, "", symHeader, ...rows, ...noteLines].join("\n");
-      const textWithReasons = reasonLines.length > 0 ? `${text}\n${reasonLines.join("\n")}` : text;
-
-      return { content: [{ type: "text", text: textWithReasons }], details: result };
-    });
-  },
-};