opencandle 0.3.0 → 0.5.0

package/src/routing/route-manifest.ts

@@ -0,0 +1,287 @@
+import type {
+  ExtractedEntities,
+  WorkflowType,
+} from "./types.js";
+import type {
+  RouterOutput,
+  RouterRoute,
+  RouterRouteKind,
+  ToolBundleName,
+} from "./router-types.js";
+import type { MemoryCategory } from "../memory/types.js";
+
+export const ROUTE_KINDS: readonly RouterRouteKind[] = [
+  "workflow_dispatch",
+  "agent_task",
+  "clarification",
+  "pass_through",
+];
+
+export const TOOL_BUNDLE_TOOLS: Record<ToolBundleName, readonly string[]> = {
+  core_market: [
+    "search_ticker",
+    "get_stock_quote",
+    "get_stock_history",
+    "get_crypto_price",
+    "get_crypto_history",
+    "get_company_overview",
+    "get_financials",
+    "get_earnings",
+    "compare_companies",
+    "compute_dcf",
+    "get_technical_indicators",
+    "backtest_strategy",
+    "analyze_risk",
+    "analyze_correlation",
+    "analyze_holdings_overlap",
+    "track_portfolio",
+    "manage_watchlist",
+    "track_prediction",
+    "search_web",
+  ],
+  options: ["get_option_chain", "get_stock_quote", "search_ticker", "search_web"],
+  macro: ["get_economic_data", "get_fear_greed", "search_web"],
+  sentiment: [
+    "get_reddit_sentiment",
+    "get_twitter_sentiment",
+    "get_web_sentiment",
+    "get_sentiment_trend",
+    "get_sentiment_summary",
+    "get_fear_greed",
+    "search_web",
+  ],
+  sec: ["get_sec_filings", "get_company_overview", "search_web"],
+  clarification: ["ask_user"],
+};
+
+export type PromptPlaybookId =
+  | "workflow_dispatch"
+  | "agent_task"
+  | "clarification"
+  | "pass_through";
+
+interface RouteCapability {
+  routeKind: RouterRouteKind;
+  legacyRoute: RouterRoute;
+  promptPlaybook: PromptPlaybookId;
+  toolBundles: ToolBundleName[];
+  memoryScopes: MemoryCategory[];
+  allowWorkflow: boolean;
+}
+
+interface WorkflowCapability {
+  workflow: Exclude<WorkflowType, "unclassified">;
+  dispatchable: boolean;
+  requiredSlots: string[];
+  toolBundles: ToolBundleName[];
+  memoryScopes: MemoryCategory[];
+  promptPlaybook: PromptPlaybookId;
+}
+
+export const ROUTE_CAPABILITY_MANIFEST: Record<RouterRouteKind, RouteCapability> = {
+  workflow_dispatch: {
+    routeKind: "workflow_dispatch",
+    legacyRoute: "workflow",
+    promptPlaybook: "workflow_dispatch",
+    toolBundles: ["core_market"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    allowWorkflow: true,
+  },
+  agent_task: {
+    routeKind: "agent_task",
+    legacyRoute: "fallback",
+    promptPlaybook: "agent_task",
+    toolBundles: ["core_market"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    allowWorkflow: false,
+  },
+  clarification: {
+    routeKind: "clarification",
+    legacyRoute: "fallback",
+    promptPlaybook: "clarification",
+    toolBundles: ["clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    allowWorkflow: true,
+  },
+  pass_through: {
+    routeKind: "pass_through",
+    legacyRoute: "fallback",
+    promptPlaybook: "pass_through",
+    toolBundles: [],
+    memoryScopes: [],
+    allowWorkflow: false,
+  },
+};
+
+export const WORKFLOW_CAPABILITY_MANIFEST: Record<
+  Exclude<WorkflowType, "unclassified">,
+  WorkflowCapability
+> = {
+  portfolio_builder: {
+    workflow: "portfolio_builder",
+    dispatchable: true,
+    requiredSlots: ["budget"],
+    toolBundles: ["core_market", "macro", "sentiment", "clarification"],
+    memoryScopes: ["investor_profile", "interaction_feedback", "workflow_history"],
+    promptPlaybook: "workflow_dispatch",
+  },
+  options_screener: {
+    workflow: "options_screener",
+    dispatchable: true,
+    requiredSlots: ["symbol"],
+    toolBundles: ["core_market", "options", "sentiment", "clarification"],
+    memoryScopes: ["investor_profile", "interaction_feedback", "workflow_history"],
+    promptPlaybook: "workflow_dispatch",
+  },
+  compare_assets: {
+    workflow: "compare_assets",
+    dispatchable: true,
+    requiredSlots: ["symbols"],
+    toolBundles: ["core_market", "macro", "sentiment", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "workflow_dispatch",
+  },
+  single_asset_analysis: {
+    workflow: "single_asset_analysis",
+    dispatchable: false,
+    requiredSlots: ["symbol"],
+    toolBundles: ["core_market", "options", "sentiment", "sec", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "agent_task",
+  },
+  watchlist_or_tracking: {
+    workflow: "watchlist_or_tracking",
+    dispatchable: false,
+    requiredSlots: [],
+    toolBundles: ["core_market", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "agent_task",
+  },
+  general_finance_qa: {
+    workflow: "general_finance_qa",
+    dispatchable: false,
+    requiredSlots: [],
+    toolBundles: ["core_market", "macro", "sentiment", "sec", "clarification"],
+    memoryScopes: ["investor_profile", "workflow_history"],
+    promptPlaybook: "agent_task",
+  },
+};
+
+export function isRouteKind(value: string): value is RouterRouteKind {
+  return ROUTE_KINDS.includes(value as RouterRouteKind);
+}
+
+export function isToolBundleName(value: string): value is ToolBundleName {
+  return Object.hasOwn(TOOL_BUNDLE_TOOLS, value);
+}
+
+export function legacyRouteForRouteKind(routeKind: RouterRouteKind): RouterRoute {
+  return ROUTE_CAPABILITY_MANIFEST[routeKind].legacyRoute;
+}
+
+export function isDispatchableWorkflow(
+  workflow: Exclude<WorkflowType, "unclassified"> | undefined,
+): boolean {
+  if (!workflow) return false;
+  return WORKFLOW_CAPABILITY_MANIFEST[workflow]?.dispatchable === true;
+}
+
+export function routeKindFromLegacyRoute(
+  route: RouterRoute,
+  missingRequired: readonly string[] = [],
+): RouterRouteKind {
+  if (missingRequired.length > 0) return "clarification";
+  return route === "workflow" ? "workflow_dispatch" : "agent_task";
+}
+
+export function workflowRequiredSlots(
+  workflow: Exclude<WorkflowType, "unclassified"> | undefined,
+): string[] {
+  if (!workflow) return [];
+  return WORKFLOW_CAPABILITY_MANIFEST[workflow]?.requiredSlots ?? [];
+}
+
+export function computeMissingRequiredSlots(
+  workflow: Exclude<WorkflowType, "unclassified"> | undefined,
+  entities: ExtractedEntities,
+  slots: RouterOutput["slots"] = {},
+  existingMissing: readonly string[] = [],
+): string[] {
+  const missing = new Set<string>();
+  const existing = new Set(existingMissing);
+  for (const slot of workflowRequiredSlots(workflow)) {
+    if (slot === "budget" && entities.budget === undefined && !slotHasValue(slots.budget)) {
+      missing.add("budget");
+    }
+    if (slot === "symbol" && entities.symbols.length === 0 && !slotHasValue(slots.symbol)) {
+      missing.add("symbol");
+    }
+    if (slot === "symbols" && entities.symbols.length < 2 && !slotHasValue(slots.symbols)) {
+      missing.add("symbols");
+    }
+    existing.delete(slot);
+  }
+  for (const slot of existing) {
+    if (!slotHasValue(slots[slot])) missing.add(slot);
+  }
+  return Array.from(missing);
+}
+
+function slotHasValue(slot: RouterOutput["slots"][string] | undefined): boolean {
+  if (!slot) return false;
+  if (Array.isArray(slot.value)) return slot.value.length > 0;
+  return slot.value !== undefined && slot.value !== null && slot.value !== "";
+}
+
+export function selectToolBundles(output: Pick<RouterOutput, "routeKind" | "workflow" | "entities">): ToolBundleName[] {
+  if (output.routeKind === "pass_through") return [];
+  if (output.routeKind === "clarification") return ["clarification"];
+
+  const bundles = new Set<ToolBundleName>();
+  const routeBundles = ROUTE_CAPABILITY_MANIFEST[output.routeKind]?.toolBundles ?? [];
+  routeBundles.forEach((bundle) => bundles.add(bundle));
+
+  if (output.workflow) {
+    const workflow = WORKFLOW_CAPABILITY_MANIFEST[output.workflow];
+    workflow?.toolBundles.forEach((bundle) => bundles.add(bundle));
+  }
+
+  const metrics = output.entities.compareMetrics ?? [];
+  const horizon = output.entities.timeHorizon ?? "";
+  if (metrics.includes("macro_hedge") || metrics.includes("interest_rates") || /\b(?:macro|rate|inflation)\b/i.test(horizon)) {
+    bundles.add("macro");
+  }
+
+  if (output.entities.symbols.length > 0) {
+    bundles.add("core_market");
+  }
+  if (output.entities.optionStrategy) {
+    bundles.add("options");
+  }
+
+  return Array.from(bundles);
+}
+
+export function activeToolsForBundles(
+  bundles: readonly ToolBundleName[],
+  availableToolNames?: readonly string[],
+): string[] {
+  const selected = new Set<string>();
+  for (const bundle of bundles) {
+    for (const tool of TOOL_BUNDLE_TOOLS[bundle] ?? []) {
+      selected.add(tool);
+    }
+  }
+
+  if (!availableToolNames) return Array.from(selected);
+  const available = new Set(availableToolNames);
+  return Array.from(selected).filter((tool) => available.has(tool));
+}
+
+export function memoryScopesForRoute(
+  routeKind: RouterRouteKind,
+  workflow?: Exclude<WorkflowType, "unclassified">,
+): MemoryCategory[] {
+  if (workflow) return WORKFLOW_CAPABILITY_MANIFEST[workflow]?.memoryScopes ?? [];
+  return ROUTE_CAPABILITY_MANIFEST[routeKind]?.memoryScopes ?? [];
+}

package/src/routing/router-llm-client.ts

@@ -0,0 +1,51 @@
+import { completeSimple, type Model } from "@earendil-works/pi-ai";
+import type { RouterLlmClient } from "./router-types.js";
+
+/**
+ * Build a router LLM client backed by pi-ai's `completeSimple`. The client
+ * is intentionally thin: prompt in, raw text out. Schema validation and
+ * retry logic live in `router.ts`.
+ *
+ * Zero tools are passed — the router operates on text alone. Temperature
+ * is pinned low for structured-output stability.
+ */
+export function createPiAiRouterClient(model: Model<"anthropic-messages"> | Model<any>): RouterLlmClient {
+  return {
+    async complete(prompt: string): Promise<string> {
+      const response = await completeSimple(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: prompt,
+              timestamp: Date.now(),
+            },
+          ],
+          // Explicitly no tools — spec requirement.
+          tools: [],
+        },
+        {
+          temperature: 0,
+          maxTokens: 2000,
+          reasoning: "minimal",
+        },
+      );
+
+      if (response.stopReason === "error" || response.stopReason === "aborted") {
+        throw new Error(
+          `router LLM call failed: ${response.errorMessage ?? response.stopReason}`,
+        );
+      }
+
+      const text = response.content
+        .filter((c): c is { type: "text"; text: string } => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+      if (!text) {
+        throw new Error("router LLM call returned no text content");
+      }
+      return text;
+    },
+  };
+}

package/src/routing/router-prompt.ts

@@ -0,0 +1,163 @@
+import {
+  ROUTE_CAPABILITY_MANIFEST,
+  WORKFLOW_CAPABILITY_MANIFEST,
+} from "./route-manifest.js";
+import type { RouterInputContext } from "./router-types.js";
+
+/**
+ * Privacy note — priorTurns rendering:
+ * Conversational text rendered into the router prompt via `priorTurns` is NOT
+ * filtered by `src/memory/types.ts::NEVER_TRUST_FROM_MEMORY` (which governs
+ * structured market-sensitive memory keys such as `stock_price` and
+ * `target_price`). A future `/forget` command is the designated scrubbing
+ * primitive for removing or masking matching entries from the session branch
+ * so they no longer reach the router. See
+ * `openspec/changes/router-context-and-observability/` for the follow-up.
+ */
+
+function renderCatalog(): string {
+  const descriptions: Record<string, string> = {
+    portfolio_builder: "user asks to build/allocate a portfolio, invest a budget across positions",
+    options_screener: "user asks for options trades / calls / puts on a specific ticker",
+    compare_assets: "user asks to compare two or more symbols (vs / versus / which is better)",
+    single_asset_analysis: "user asks for a full analysis / deep dive / 'is X attractive' on ONE symbol",
+    watchlist_or_tracking: "user manages or asks about their saved watchlist / prediction history",
+    general_finance_qa: "definitional / conceptual questions plus broad market structure, sector, industry, monetary policy, and emerging markets research",
+  };
+
+  return Object.values(WORKFLOW_CAPABILITY_MANIFEST).map((w) => {
+    const required = w.requiredSlots.length > 0
+      ? ` [required: ${w.requiredSlots.join(", ")}]`
+      : "";
+    const mode = w.dispatchable ? "dispatchable workflow" : "agent-task workflow label";
+    return `- "${w.workflow}" (${mode}): ${descriptions[w.workflow]}${required}`;
+  }).join("\n");
+}
+
+function renderRouteKinds(): string {
+  return Object.values(ROUTE_CAPABILITY_MANIFEST)
+    .map((route) => `- "${route.routeKind}" -> legacy route "${route.legacyRoute}"`)
+    .join("\n");
+}
+
+function renderProfile(profile: Record<string, unknown>): string {
+  const entries = Object.entries(profile);
+  if (entries.length === 0) return "(empty)";
+  return entries.map(([k, v]) => `- ${k}: ${JSON.stringify(v)}`).join("\n");
+}
+
+function renderPriorTurns(
+  turns: Array<{ role: "user" | "assistant"; text: string }>,
+): string {
+  if (turns.length === 0) return "(none)";
+  return turns
+    .map((t) => `[${t.role}] ${t.text.replace(/\n+/g, " ").slice(0, 400)}`)
+    .join("\n");
+}
+
+function renderRecentRuns(
+  runs: Array<{
+    workflowType: string;
+    turnType: string;
+    resolvedSlots?: Record<string, unknown>;
+    createdAt: string;
+  }>,
+): string {
+  if (runs.length === 0) return "(none)";
+  return runs
+    .map(
+      (r) =>
+        `- ${r.createdAt} ${r.turnType}/${r.workflowType} ${r.resolvedSlots ? JSON.stringify(r.resolvedSlots) : ""}`,
+    )
+    .join("\n");
+}
+
+const SCHEMA_SPEC = `You MUST respond with a SINGLE JSON object and nothing else (no markdown fences, no prose outside the JSON). The object MUST conform to this TypeScript interface exactly:
+
+interface RouterOutput {
+  routeKind: "workflow_dispatch" | "agent_task" | "clarification" | "pass_through";
+  route: "workflow" | "fallback";
+  workflow?: "portfolio_builder" | "options_screener" | "compare_assets" | "single_asset_analysis" | "watchlist_or_tracking" | "general_finance_qa";
+  entities: {
+    symbols: string[];               // UPPERCASE tickers the user mentioned or implied
+    budget?: number;                 // dollar amount if user stated one
+    maxPremium?: number;
+    timeHorizon?: string;            // e.g. "6mo", "1y_plus", "short", "long"
+    riskProfile?: string;            // "conservative" | "balanced" | "aggressive"
+    direction?: "bullish" | "bearish";
+    dteHint?: string;
+    optionStrategy?: "covered_call" | "protective_put";  // set when user explicitly asks for a known option strategy
+    heldSymbol?: string;              // for covered calls/protective puts: ticker the user owns/holds
+    catalystSymbols?: string[];        // tickers mentioned as event/catalyst context, not the option-chain underlying
+    costBasis?: number;                // per-share basis when user says "cost basis is $X"
+    shareQuantity?: number;            // number of shares owned when stated, e.g. "200 shares"
+    compareMetrics?: string[];        // optional compare focus tags, e.g. "sentiment", "macro_hedge"
+  };
+  slots: Record<string, {
+    value: unknown;
+    source: "user" | "preference" | "default" | "prior_context" | "memory";
+    confidence: "high" | "medium" | "low";
+  }>;
+  preference_updates: Array<{
+    key: string;                      // e.g. "risk_profile", "time_horizon", "asset_scope", "options_liquidity"
+    value: string;
+    confidence: "high" | "medium" | "low";
+    source: "inferred";
+  }>;
+  missing_required: string[];         // required slot names the turn/profile/defaults did not fill
+  tool_bundles: Array<"core_market" | "options" | "macro" | "sentiment" | "sec" | "clarification">;
+  diagnostics: Array<{ code: string; message: string }>;
+  reasoning: string;                  // one or two short sentences; used for debugging only
+}`;
+
+const ROUTING_RULES = `Routing rules:
+- Choose routeKind = "workflow_dispatch" ONLY when the turn clearly matches a dispatchable workflow (portfolio_builder, options_screener, or compare_assets) AND required slots are filled from the turn, trusted prior context, or profile snapshot.
+- For single_asset_analysis, watchlist_or_tracking, and general_finance_qa, set routeKind = "agent_task" even when you set the workflow label. These are workflow labels for prompt/tool policy, not structured workflow dispatch.
+- Choose routeKind = "agent_task" for in-scope finance work that should be answered by the main agent, including simple data fetches like "AAPL quote" and open-ended questions like "entry levels on ASTS for 6 months".
+- Choose routeKind = "clarification" when required slots are missing (e.g. options workflow needs a symbol, portfolio needs a budget). List specific slot names in missing_required. The main agent will use ask_user to collect them.
+- Choose routeKind = "pass_through" when the request is outside OpenCandle's finance task surface.
+- Set legacy route = "workflow" only for routeKind = "workflow_dispatch"; otherwise set legacy route = "fallback".
+- DO NOT invent a "direct_tool" route. Tool execution belongs to the main agent.
+- For covered call prompts, distinguish the owned underlying from catalyst tickers. Put the owned symbol first in symbols, set heldSymbol to the owned symbol, put event/context tickers in catalystSymbols, set workflow="options_screener", and preserve costBasis if stated.
+- For protective put prompts, treat the owned/held ticker as the option-chain underlying, set optionStrategy="protective_put", direction="bearish", and preserve shareQuantity if stated. This is a hedge on an existing long share position, not a bullish call screen.
+- Source attribution rules (per-slot source field):
+  - source = "user": the value came from THIS turn's text.
+  - source = "preference": the value came from profileSnapshot (not this turn).
+  - source = "default": a sensible default was applied (workflow fallback).
+  - source = "prior_context": the value came from prior conversation turns.
+  - source = "memory": the value came from retrieved non-profile memory.
+- Preference updates:
+  - Emit preference_updates ONLY for stable user-dispositions stated (or very strongly implied) in the current turn. E.g. "I'm aggressive" → risk_profile=aggressive, high.
+  - Do NOT emit preference_updates that merely echo profileSnapshot.
+  - Only confidence="high" updates will be persisted; medium/low are logged but dropped.
+- You have NO tools. Do not request tool execution. Classify on text alone.`;
+
+export function buildRouterPrompt(input: RouterInputContext): string {
+  return `You are OpenCandle's routing agent. Your job is to classify the user's turn into one of the known workflows (or fallback), extract entities + per-slot provenance, and surface any stable preferences the user expressed. Your output feeds the main analyst agent — it does NOT go to the user.
+
+ROUTE KINDS:
+${renderRouteKinds()}
+
+WORKFLOW CATALOG:
+${renderCatalog()}
+
+${SCHEMA_SPEC}
+
+${ROUTING_RULES}
+
+--- CONTEXT ---
+
+Profile snapshot (persisted preferences from prior sessions):
+${renderProfile(input.profileSnapshot)}
+
+Recent workflow runs (most recent last):
+${renderRecentRuns(input.recentWorkflowRuns)}
+
+Prior conversation turns (most recent last):
+${renderPriorTurns(input.priorTurns)}
+
+--- CURRENT TURN ---
+${input.text}
+
+Respond with the JSON object. Nothing else.`;
+}

package/src/routing/router-types.ts

@@ -0,0 +1,87 @@
+import type { ExtractedEntities, SlotSource, WorkflowType } from "./types.js";
+
+export type RouterRoute = "workflow" | "fallback";
+export type RouterRouteKind =
+  | "workflow_dispatch"
+  | "agent_task"
+  | "clarification"
+  | "pass_through";
+
+export type ToolBundleName =
+  | "core_market"
+  | "options"
+  | "macro"
+  | "sentiment"
+  | "sec"
+  | "clarification";
+
+export type RouterConfidence = "high" | "medium" | "low";
+
+export interface RouterSlot {
+  value: unknown;
+  source: SlotSource;
+  confidence: RouterConfidence;
+}
+
+export interface RouterPreferenceUpdate {
+  key: string;
+  value: string;
+  confidence: RouterConfidence;
+  source: "inferred";
+}
+
+export interface RouterDiagnostic {
+  code: string;
+  message: string;
+}
+
+/**
+ * Structured output from the LLM router. Mirrors existing types
+ * (`ClassificationResult`, `ExtractedEntities`, `SlotSource`) so downstream
+ * consumers can branch without a new vocabulary.
+ *
+ * `workflow` is only meaningful when `route === "workflow"`. For `fallback`
+ * routes, `workflow_type` at the storage layer is the sentinel `"fallback"`.
+ */
+export interface RouterOutput {
+  routeKind: RouterRouteKind;
+  route: RouterRoute;
+  workflow?: Exclude<WorkflowType, "unclassified">;
+  entities: ExtractedEntities;
+  slots: Record<string, RouterSlot>;
+  preference_updates: RouterPreferenceUpdate[];
+  missing_required: string[];
+  tool_bundles: ToolBundleName[];
+  diagnostics: RouterDiagnostic[];
+  reasoning: string;
+}
+
+/** Context passed into the router on each turn. */
+export interface RouterInputContext {
+  /** Raw user text from `pi.on("input")`. */
+  text: string;
+  /** Last 5 user/assistant turns (most recent last). */
+  priorTurns: Array<{ role: "user" | "assistant"; text: string }>;
+  /** Current investor_profile snapshot retrieved from preferences storage. */
+  profileSnapshot: Record<string, unknown>;
+  /** Last 3 workflow_runs, compact summaries. */
+  recentWorkflowRuns: Array<{
+    workflowType: string;
+    turnType: string;
+    resolvedSlots?: Record<string, unknown>;
+    createdAt: string;
+  }>;
+}
+
+/**
+ * Abstract LLM client used by the router. Injected by callers so unit tests
+ * can supply a deterministic mock. The real implementation (see
+ * `src/routing/router-llm-client.ts`) wraps pi-ai's `completeSimple`.
+ */
+export interface RouterLlmClient {
+  /**
+   * Run a single prompt → text completion. Router parses the returned text
+   * as JSON; the client is not responsible for structured-output parsing.
+   */
+  complete(prompt: string): Promise<string>;
+}