opencandle 0.11.0 → 0.12.0

package/src/routing/route-manifest.ts

@@ -1,308 +0,0 @@
-import type { MemoryCategory } from "../memory/types.js";
-import type { RouterOutput, RouterRoute, RouterRouteKind, ToolBundleName } from "./router-types.js";
-import type { ExtractedEntities, WorkflowType } from "./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",
-    "screen_stocks",
-    "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",
-    "manage_alerts",
-    "daily_watchlist_report",
-    "manage_notifications",
-    "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 &&
-      !slotHasSymbolListValue(slots.symbols, 2)
-    ) {
-      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 !== "";
-}
-
-function slotHasSymbolListValue(
-  slot: RouterOutput["slots"][string] | undefined,
-  minLength: number,
-): boolean {
-  if (!slot) return false;
-  if (Array.isArray(slot.value))
-    return slot.value.filter((value) => typeof value === "string").length >= minLength;
-  return false;
-}
-
-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 ?? [];
-  for (const bundle of routeBundles) {
-    bundles.add(bundle);
-  }
-
-  if (output.workflow) {
-    const workflow = WORKFLOW_CAPABILITY_MANIFEST[output.workflow];
-    if (workflow) {
-      for (const bundle of workflow.toolBundles) {
-        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

@@ -1,52 +0,0 @@
-import type { Model } from "@earendil-works/pi-ai";
-import { completeSimple } from "@earendil-works/pi-ai/compat";
-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

@@ -1,159 +0,0 @@
-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 or tracked positions",
-    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

@@ -1,84 +0,0 @@
-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;
-  details?: Record<string, unknown>;
-}
-
-/**
- * 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>;
-}