opencandle 0.4.0 → 0.6.0

package/src/tools/portfolio/daily-report.ts

@@ -0,0 +1,101 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import {
+  getOrCreateDefaultWatchlistReportTemplate,
+  nextDailyReportRunAt,
+  recordDailyWatchlistReportRun,
+  targetsDefaultWatchlist,
+} from "../../market-state/daily-report.js";
+import { deliverPendingNotifications } from "../../market-state/notification-delivery.js";
+import { MarketStateService } from "../../market-state/service.js";
+import { initDefaultDatabase } from "../../memory/sqlite.js";
+
+const ACTION_DESCRIPTION = [
+  "One of: run, configure, history.",
+  "Use run to generate the daily watchlist report now.",
+  "Use configure to save schedule metadata such as timezone and local_time.",
+  "Use history to show prior report runs; do not use list or show_history.",
+].join(" ");
+
+const params = Type.Object({
+  action: Type.Union([Type.Literal("run"), Type.Literal("configure"), Type.Literal("history")], {
+    description: ACTION_DESCRIPTION,
+  }),
+  timezone: Type.Optional(
+    Type.String({ description: "IANA timezone for future scheduled morning reports" }),
+  ),
+  local_time: Type.Optional(
+    Type.String({ description: "Local time for future scheduled morning reports, HH:MM" }),
+  ),
+});
+
+export const dailyReportTool: AgentTool<typeof params> = {
+  name: "daily_watchlist_report",
+  label: "Daily Report",
+  description:
+    "Generate, configure, or show history for the local daily watchlist report. Actions are run, configure, and history. Reports can run manually and configured schedules run while an OpenCandle writer/monitor process is active.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const db = initDefaultDatabase();
+    const service = new MarketStateService(db);
+
+    try {
+      if (args.action === "configure") {
+        const templateParams = {
+          name: "Morning watchlist",
+          reportType: "watchlist_daily",
+          cadence: "daily",
+          timezone: args.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+          localTime: args.local_time ?? "08:00",
+          config: { targets: { default_watchlist: true } },
+          enabled: true,
+        };
+        const nextRunAt = nextDailyReportRunAt(templateParams.timezone, templateParams.localTime);
+        const existing = service
+          .listReportTemplates()
+          .find(
+            (template) =>
+              template.reportType === "watchlist_daily" &&
+              targetsDefaultWatchlist(template.configJson),
+          );
+        const template = existing
+          ? service.updateReportTemplate(existing.id, { ...templateParams, nextRunAt })
+          : service.createReportTemplate({ ...templateParams, nextRunAt });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Configured daily watchlist report for ${template.localTime} ${template.timezone}.`,
+            },
+          ],
+          details: template,
+        };
+      }
+
+      if (args.action === "history") {
+        const runs = service.listReportRuns();
+        if (runs.length === 0) {
+          return { content: [{ type: "text", text: "No daily report runs yet." }], details: [] };
+        }
+        const lines = ["**Daily Report History**", ""];
+        for (const run of runs.slice(0, 10)) {
+          lines.push(`  ${run.startedAt}: ${run.status}`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }], details: runs };
+      }
+
+      const template = getOrCreateDefaultWatchlistReportTemplate(service);
+      const { report, run } = await recordDailyWatchlistReportRun(service, {
+        templateId: template.id,
+        triggerType: "manual",
+      });
+      await deliverPendingNotifications(service);
+      return {
+        content: [{ type: "text", text: report.text }],
+        details: run,
+      };
+    } finally {
+      db.close();
+    }
+  },
+};

package/src/tools/portfolio/holdings-overlap.ts

@@ -0,0 +1,139 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getFundHoldings } from "../../providers/yahoo-finance.js";
+import type {
+  FundHolding,
+  FundHoldings,
+  FundHoldingsOverlap,
+  FundOverlapPair,
+  SharedFundHolding,
+} from "../../types/portfolio.js";
+
+const params = Type.Object({
+  symbols: Type.Array(Type.String(), {
+    description:
+      "Array of 2+ ETF or fund ticker symbols to compare holdings overlap, e.g. ['VOO','QQQ']",
+    minItems: 2,
+  }),
+});
+
+export const holdingsOverlapTool: AgentTool<typeof params, FundHoldingsOverlap | null> = {
+  name: "analyze_holdings_overlap",
+  label: "ETF Holdings Overlap",
+  description:
+    "Fetch top fund/ETF holdings and compute pairwise overlap by weight. Useful for ETF diversification and hidden concentration checks.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const symbols = [...new Set(args.symbols.map((symbol) => symbol.toUpperCase()))];
+    if (symbols.length < 2) {
+      throw new Error("Need at least 2 symbols for holdings overlap analysis.");
+    }
+
+    const results = await Promise.all(
+      symbols.map(async (symbol) => ({
+        symbol,
+        result: await wrapProvider("yahoo", () => getFundHoldings(symbol)),
+      })),
+    );
+    const unavailable = results.flatMap((entry) =>
+      entry.result.status === "unavailable"
+        ? [{ symbol: entry.symbol, reason: entry.result.reason }]
+        : [],
+    );
+    if (unavailable.length > 0) {
+      const missing = unavailable.map((entry) => `${entry.symbol}: ${entry.reason}`).join("; ");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `⚠ Holdings overlap unavailable for one or more funds (${missing}).`,
+          },
+        ],
+        details: null,
+      };
+    }
+
+    const funds = results.flatMap((entry) =>
+      entry.result.status === "ok" ? [entry.result.data] : [],
+    );
+    const overlap = computeHoldingsOverlap(funds);
+    return {
+      content: [{ type: "text", text: formatOverlap(overlap) }],
+      details: overlap,
+    };
+  },
+};
+
+export function computeHoldingsOverlap(funds: FundHoldings[]): FundHoldingsOverlap {
+  const pairs: FundOverlapPair[] = [];
+  for (let i = 0; i < funds.length; i += 1) {
+    for (let j = i + 1; j < funds.length; j += 1) {
+      pairs.push(computePairOverlap(funds[i], funds[j]));
+    }
+  }
+  return { funds, pairs };
+}
+
+function computePairOverlap(a: FundHoldings, b: FundHoldings): FundOverlapPair {
+  const aBySymbol = new Map(a.holdings.map((holding) => [holding.symbol, holding]));
+  const sharedHoldings: SharedFundHolding[] = [];
+  for (const bHolding of b.holdings) {
+    const aHolding = aBySymbol.get(bHolding.symbol);
+    if (!aHolding) continue;
+    const overlapWeight = roundWeight(Math.min(aHolding.weight, bHolding.weight));
+    sharedHoldings.push({
+      symbol: bHolding.symbol,
+      name: commonHoldingName(aHolding, bHolding),
+      weights: {
+        [a.symbol]: aHolding.weight,
+        [b.symbol]: bHolding.weight,
+      },
+      overlapWeight,
+    });
+  }
+  sharedHoldings.sort((left, right) => right.overlapWeight - left.overlapWeight);
+  return {
+    symbols: [a.symbol, b.symbol],
+    overlapWeight: roundWeight(
+      sharedHoldings.reduce((sum, holding) => sum + holding.overlapWeight, 0),
+    ),
+    sharedHoldings,
+  };
+}
+
+function formatOverlap(overlap: FundHoldingsOverlap): string {
+  const lines: string[] = ["**ETF/Fund Holdings Overlap**", ""];
+  for (const pair of overlap.pairs) {
+    lines.push(`${pair.symbols.join("/")} holdings overlap: ${formatPercent(pair.overlapWeight)}`);
+    const topShared = pair.sharedHoldings.slice(0, 5);
+    if (topShared.length > 0) {
+      lines.push(
+        `Top shared holdings: ${topShared
+          .map((holding) => `${holding.symbol} (${formatPercent(holding.overlapWeight)} overlap)`)
+          .join(", ")}`,
+      );
+    } else {
+      lines.push("No shared top holdings found in provider coverage.");
+    }
+    lines.push("");
+  }
+  lines.push(
+    "Provider note: overlap uses provider top-holdings coverage, not full portfolio look-through unless the provider returns all holdings.",
+  );
+  return lines.join("\n").trimEnd();
+}
+
+function commonHoldingName(a: FundHolding, b: FundHolding): string {
+  if (a.name && a.name !== a.symbol) return a.name;
+  if (b.name && b.name !== b.symbol) return b.name;
+  return a.symbol;
+}
+
+function formatPercent(value: number): string {
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function roundWeight(value: number): number {
+  return Math.round(value * 10_000) / 10_000;
+}

package/src/tools/portfolio/notifications.ts

@@ -0,0 +1,45 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import { MarketStateService } from "../../market-state/service.js";
+import { initDefaultDatabase } from "../../memory/sqlite.js";
+
+const params = Type.Object({
+  action: Type.Union([Type.Literal("list"), Type.Literal("acknowledge")], {
+    description: "One of: list, acknowledge. Use acknowledge with id to mark a notification read.",
+  }),
+  id: Type.Optional(Type.Number({ description: "Notification id for acknowledge." })),
+});
+
+export const notificationsTool: AgentTool<typeof params> = {
+  name: "manage_notifications",
+  label: "Notifications",
+  description:
+    "List durable OpenCandle notifications or acknowledge a notification by id. Use this for alert and report notification history.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const db = initDefaultDatabase();
+    const service = new MarketStateService(db);
+    try {
+      if (args.action === "acknowledge") {
+        if (args.id == null) throw new Error("id is required for acknowledge.");
+        const notification = service.acknowledgeNotificationEvent(args.id);
+        return {
+          content: [{ type: "text", text: `Acknowledged notification #${notification.id}.` }],
+          details: notification,
+        };
+      }
+
+      const notifications = service.listNotificationEvents();
+      if (notifications.length === 0) {
+        return { content: [{ type: "text", text: "No notifications yet." }], details: [] };
+      }
+      const lines = ["**Notifications**", ""];
+      for (const notification of notifications.slice(0, 20)) {
+        lines.push(`  #${notification.id} [${notification.status}] ${notification.title}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], details: notifications };
+    } finally {
+      db.close();
+    }
+  },
+};