opencandle 0.3.0 → 0.4.0

package/src/routing/slot-resolver.ts

@@ -0,0 +1,152 @@
+import type {
+  ExtractedEntities,
+  PortfolioSlots,
+  OptionsScreenerSlots,
+  SlotResolution,
+  SlotSource,
+} from "./types.js";
+import { PORTFOLIO_DEFAULTS, OPTIONS_SCREENER_DEFAULTS } from "./defaults.js";
+
+interface Preferences {
+  riskProfile?: string;
+  timeHorizon?: string;
+  assetScope?: string;
+  positionCount?: number;
+  maxSinglePositionPct?: number;
+  dteTarget?: string;
+  objective?: string;
+  moneynessPreference?: string;
+  liquidityMinimum?: string;
+}
+
+function mapDteHintToTarget(dteHint: string | undefined): string | undefined {
+  switch (dteHint) {
+    case "week":
+      return "7_to_14_days";
+    case "month":
+      return "25_to_45_days";
+    case "leaps":
+      return "180_plus_days";
+    default:
+      return undefined;
+  }
+}
+
+function resolve<T>(
+  userValue: T | undefined,
+  prefValue: T | undefined,
+  defaultValue: T,
+): { value: T; source: SlotSource } {
+  if (userValue !== undefined) return { value: userValue, source: "user" };
+  if (prefValue !== undefined) return { value: prefValue, source: "preference" };
+  return { value: defaultValue, source: "default" };
+}
+
+export function resolvePortfolioSlots(
+  entities: ExtractedEntities,
+  preferences: Preferences = {},
+): SlotResolution<PortfolioSlots> {
+  const sources = {} as Record<keyof PortfolioSlots, SlotSource>;
+  const defaultsUsed: string[] = [];
+  const missingRequired: string[] = [];
+
+  // Budget: required, no default
+  let budget = 0;
+  if (entities.budget !== undefined) {
+    budget = entities.budget;
+    sources.budget = "user";
+  } else {
+    missingRequired.push("budget");
+    sources.budget = "default";
+  }
+
+  const risk = resolve(entities.riskProfile, preferences.riskProfile, PORTFOLIO_DEFAULTS.riskProfile);
+  sources.riskProfile = risk.source;
+  if (risk.source === "default") defaultsUsed.push("riskProfile");
+
+  const horizon = resolve(entities.timeHorizon, preferences.timeHorizon, PORTFOLIO_DEFAULTS.timeHorizon);
+  sources.timeHorizon = horizon.source;
+  if (horizon.source === "default") defaultsUsed.push("timeHorizon");
+
+  const scope = resolve(undefined, preferences.assetScope, PORTFOLIO_DEFAULTS.assetScope);
+  sources.assetScope = scope.source;
+  if (scope.source === "default") defaultsUsed.push("assetScope");
+
+  const count = resolve(undefined, preferences.positionCount, PORTFOLIO_DEFAULTS.positionCount);
+  sources.positionCount = count.source;
+  if (count.source === "default") defaultsUsed.push("positionCount");
+
+  const maxPct = resolve(undefined, preferences.maxSinglePositionPct, PORTFOLIO_DEFAULTS.maxSinglePositionPct);
+  sources.maxSinglePositionPct = maxPct.source;
+  if (maxPct.source === "default") defaultsUsed.push("maxSinglePositionPct");
+
+  return {
+    resolved: {
+      budget,
+      riskProfile: risk.value,
+      timeHorizon: horizon.value,
+      assetScope: scope.value,
+      positionCount: count.value,
+      maxSinglePositionPct: maxPct.value,
+    },
+    sources,
+    defaultsUsed,
+    missingRequired,
+  };
+}
+
+export function resolveOptionsScreenerSlots(
+  entities: ExtractedEntities,
+  preferences: Preferences = {},
+): SlotResolution<OptionsScreenerSlots> {
+  const sources = {} as Record<keyof OptionsScreenerSlots, SlotSource>;
+  const defaultsUsed: string[] = [];
+  const missingRequired: string[] = [];
+
+  // Symbol: required, no default
+  let symbol = "";
+  if (entities.symbols.length > 0) {
+    symbol = entities.symbols[0];
+    sources.symbol = "user";
+  } else {
+    missingRequired.push("symbol");
+    sources.symbol = "default";
+  }
+
+  // Direction: default to bullish
+  const dir = resolve(entities.direction, undefined, "bullish" as const);
+  sources.direction = dir.source;
+  if (dir.source === "default") defaultsUsed.push("direction");
+
+  const dte = resolve(mapDteHintToTarget(entities.dteHint), preferences.dteTarget, OPTIONS_SCREENER_DEFAULTS.dteTarget);
+  sources.dteTarget = dte.source;
+  if (dte.source === "default") defaultsUsed.push("dteTarget");
+
+  const obj = resolve(undefined, preferences.objective, OPTIONS_SCREENER_DEFAULTS.objective);
+  sources.objective = obj.source;
+  if (obj.source === "default") defaultsUsed.push("objective");
+
+  const moneyness = resolve(undefined, preferences.moneynessPreference, OPTIONS_SCREENER_DEFAULTS.moneynessPreference);
+  sources.moneynessPreference = moneyness.source;
+  if (moneyness.source === "default") defaultsUsed.push("moneynessPreference");
+
+  const liquidity = resolve(undefined, preferences.liquidityMinimum, OPTIONS_SCREENER_DEFAULTS.liquidityMinimum);
+  sources.liquidityMinimum = liquidity.source;
+  if (liquidity.source === "default") defaultsUsed.push("liquidityMinimum");
+
+  return {
+    resolved: {
+      symbol,
+      direction: dir.value,
+      dteTarget: dte.value,
+      objective: obj.value,
+      moneynessPreference: moneyness.value,
+      liquidityMinimum: liquidity.value,
+      budget: entities.budget,
+      maxPremium: entities.maxPremium,
+    },
+    sources,
+    defaultsUsed,
+    missingRequired,
+  };
+}

package/src/routing/types.ts

@@ -0,0 +1,63 @@
+export type WorkflowType =
+  | "single_asset_analysis"
+  | "portfolio_builder"
+  | "options_screener"
+  | "compare_assets"
+  | "watchlist_or_tracking"
+  | "general_finance_qa"
+  | "unclassified";
+
+export interface ExtractedEntities {
+  symbols: string[];
+  budget?: number;
+  maxPremium?: number;
+  timeHorizon?: string;
+  riskProfile?: string;
+  direction?: "bullish" | "bearish";
+  dteHint?: string;
+}
+
+export interface ClassificationResult {
+  workflow: WorkflowType;
+  confidence: number;
+  tier: "rule" | "llm";
+  entities: ExtractedEntities;
+}
+
+export interface PortfolioSlots {
+  budget: number;
+  riskProfile: string;
+  timeHorizon: string;
+  assetScope: string;
+  positionCount: number;
+  maxSinglePositionPct: number;
+  excludeSectors?: string[];
+  incomeVsGrowth?: string;
+  accountType?: string;
+}
+
+export interface OptionsScreenerSlots {
+  symbol: string;
+  direction: "bullish" | "bearish";
+  dteTarget: string;
+  objective: string;
+  moneynessPreference: string;
+  liquidityMinimum: string;
+  budget?: number;
+  maxPremium?: number;
+  ivPreference?: string;
+}
+
+export interface CompareAssetsSlots {
+  symbols: string[];
+  metrics?: string[];
+}
+
+export type SlotSource = "user" | "preference" | "default";
+
+export interface SlotResolution<T> {
+  resolved: T;
+  sources: { [K in keyof T]?: SlotSource };
+  defaultsUsed: string[];
+  missingRequired: string[];
+}

package/src/runtime/evidence.ts

@@ -0,0 +1,77 @@
+/** Source of a value flowing through the runtime. */
+export type ProvenanceSource =
+  | "user"
+  | "preference"
+  | "default"
+  | "fetched"
+  | "computed"
+  | "unavailable"
+  | "stale_cache";
+
+/** Tracks where a value came from, when, and with what confidence. */
+export interface Provenance {
+  source: ProvenanceSource;
+  timestamp?: string;
+  provider?: string;
+  confidence?: number;
+  reason?: string;
+}
+
+/** A labeled data point with its provenance. */
+export interface EvidenceRecord {
+  label: string;
+  value: unknown;
+  provenance: Provenance;
+}
+
+/** Successful provider result. */
+export interface ProviderResultOk<T> {
+  status: "ok";
+  data: T;
+  timestamp: string;
+  stale?: boolean;
+}
+
+/** Failed/unavailable provider result. */
+export interface ProviderResultUnavailable {
+  status: "unavailable";
+  reason: string;
+  provider: string;
+}
+
+/** Union of provider outcomes — every provider call returns one of these. */
+export type ProviderResult<T> = ProviderResultOk<T> | ProviderResultUnavailable;
+
+/** Type guard for successful provider results. */
+export function isProviderOk<T>(result: ProviderResult<T>): result is ProviderResultOk<T> {
+  return result.status === "ok";
+}
+
+/** Convert a ProviderResult into an EvidenceRecord. */
+export function toEvidenceRecord<T>(
+  label: string,
+  result: ProviderResult<T>,
+  providerId?: string,
+): EvidenceRecord {
+  if (isProviderOk(result)) {
+    return {
+      label,
+      value: result.data,
+      provenance: {
+        source: result.stale ? "stale_cache" : "fetched",
+        timestamp: result.timestamp,
+        provider: providerId,
+        confidence: result.stale ? 0.5 : undefined,
+      },
+    };
+  }
+  return {
+    label,
+    value: null,
+    provenance: {
+      source: "unavailable",
+      reason: result.reason,
+      provider: result.provider,
+    },
+  };
+}

package/src/runtime/index.ts

@@ -0,0 +1,55 @@
+export type {
+  Provenance,
+  ProvenanceSource,
+  EvidenceRecord,
+  ProviderResult,
+  ProviderResultOk,
+  ProviderResultUnavailable,
+} from "./evidence.js";
+export { isProviderOk, toEvidenceRecord } from "./evidence.js";
+
+export type {
+  StepStatus,
+  RunStatus,
+  WorkflowStep,
+  StepOutput,
+  AnalystSignal,
+  AnalystOutput,
+  WorkflowRun,
+} from "./workflow-types.js";
+export {
+  isValidStepTransition,
+  transitionStepStatus,
+  createWorkflowRun,
+} from "./workflow-types.js";
+
+export type {
+  ValidationEntry,
+  ValidationResult,
+  ValidatorConfig,
+} from "./validation.js";
+export {
+  emptyValidationResult,
+  checkTimestamps,
+  checkOptionsExpiries,
+  checkRequiredFields,
+  checkNumberMatch,
+  RuntimeValidator,
+  DEFAULT_MARKET_SENSITIVE_LABELS,
+} from "./validation.js";
+
+export type { WorkflowEventType, WorkflowEvent } from "./workflow-events.js";
+export { WorkflowEventLogger } from "./workflow-events.js";
+
+export { ProviderTracker } from "./provider-tracker.js";
+
+export type { ProviderId } from "./provider-ids.js";
+export { PROVIDER_ID } from "./provider-ids.js";
+
+export { setRunContext, clearRunContext, getProviderTracker } from "./run-context.js";
+
+export type { StepExecutor, StepExecutionContext, WorkflowRunnerOptions } from "./workflow-runner.js";
+export { WorkflowRunner } from "./workflow-runner.js";
+
+export type { PromptStep, WorkflowDefinition } from "./prompt-step.js";
+export { promptStep, promptStepOutput, toStepDefinitions, toWorkflowPlan } from "./prompt-step.js";

package/src/runtime/prompt-step.ts

@@ -0,0 +1,75 @@
+import type { WorkflowStep, StepOutput } from "./workflow-types.js";
+
+/**
+ * A workflow step definition that carries its prompt text.
+ * In Pi's model, each step is a prompt sent to the LLM.
+ */
+export interface PromptStep extends Omit<WorkflowStep, "status"> {
+  prompt: string;
+}
+
+/**
+ * A complete workflow definition: typed step metadata + prompt text for each step.
+ * Replaces the old WorkflowPlan { initialPrompt, followUps }.
+ */
+export interface WorkflowDefinition {
+  workflowType: string;
+  steps: PromptStep[];
+}
+
+/**
+ * Create a prompt-based step definition.
+ */
+export function promptStep(
+  stepType: string,
+  description: string,
+  prompt: string,
+  options: {
+    skippable?: boolean;
+    requiredInputs?: string[];
+    expectedOutputs?: string[];
+  } = {},
+): PromptStep {
+  return {
+    stepType,
+    description,
+    prompt,
+    skippable: options.skippable ?? false,
+    requiredInputs: options.requiredInputs ?? [],
+    expectedOutputs: options.expectedOutputs ?? [],
+  };
+}
+
+/**
+ * Create a StepOutput for a prompt-based step (no structured evidence yet).
+ * Evidence will be captured separately via tool call hooks.
+ */
+export function promptStepOutput(stepIndex: number, stepType: string): StepOutput {
+  return {
+    stepIndex,
+    stepType,
+    evidence: [],
+  };
+}
+
+/**
+ * Extract just the WorkflowStep metadata from PromptStep definitions
+ * (dropping the prompt field) for passing to WorkflowRunner.
+ */
+export function toStepDefinitions(steps: PromptStep[]): Omit<WorkflowStep, "status">[] {
+  return steps.map(({ prompt: _prompt, ...step }) => step);
+}
+
+/**
+ * Convert a WorkflowDefinition to the old WorkflowPlan format for backward compatibility.
+ */
+export function toWorkflowPlan(definition: WorkflowDefinition): {
+  initialPrompt: string;
+  followUps: string[];
+} {
+  const [first, ...rest] = definition.steps;
+  return {
+    initialPrompt: first?.prompt ?? "",
+    followUps: rest.map((s) => s.prompt),
+  };
+}

package/src/runtime/provider-ids.ts

@@ -0,0 +1,15 @@
+/**
+ * Canonical provider IDs. These match the keys used in
+ * src/infra/rate-limiter.ts for providers that have rate limits.
+ */
+export const PROVIDER_ID = {
+  YAHOO: "yahoo",
+  ALPHA_VANTAGE: "alphavantage",
+  COINGECKO: "coingecko",
+  FRED: "fred",
+  SEC_EDGAR: "sec-edgar",
+  REDDIT: "reddit",
+  FEAR_GREED: "feargreed",
+} as const;
+
+export type ProviderId = (typeof PROVIDER_ID)[keyof typeof PROVIDER_ID];

package/src/runtime/provider-tracker.ts

@@ -0,0 +1,40 @@
+import type { ProviderResult } from "./evidence.js";
+
+/**
+ * Tracks provider failures within a workflow run and short-circuits
+ * calls to providers that have exceeded the failure threshold.
+ */
+export class ProviderTracker {
+  private readonly failures = new Map<string, number>();
+
+  constructor(private readonly maxFailures: number = 2) {}
+
+  /** Record a failure for a provider. */
+  recordFailure(provider: string): void {
+    this.failures.set(provider, (this.failures.get(provider) ?? 0) + 1);
+  }
+
+  /** Check whether a provider's circuit is open (too many failures). */
+  isCircuitOpen(provider: string): boolean {
+    return (this.failures.get(provider) ?? 0) >= this.maxFailures;
+  }
+
+  /** Get a short-circuit unavailable result for a provider. */
+  shortCircuit<T>(provider: string): ProviderResult<T> {
+    return {
+      status: "unavailable",
+      reason: "provider_circuit_open",
+      provider,
+    };
+  }
+
+  /** Reset failure count for a provider. */
+  reset(provider: string): void {
+    this.failures.delete(provider);
+  }
+
+  /** Reset all tracked failures. */
+  resetAll(): void {
+    this.failures.clear();
+  }
+}

package/src/runtime/run-context.ts

@@ -0,0 +1,22 @@
+import type { ProviderTracker } from "./provider-tracker.js";
+
+interface RunContext {
+  providerTracker: ProviderTracker;
+}
+
+let activeContext: RunContext | null = null;
+
+/** Set the active run context. Called by SessionCoordinator at workflow start. */
+export function setRunContext(ctx: RunContext): void {
+  activeContext = ctx;
+}
+
+/** Clear the active run context. Called when a workflow ends or is cancelled. */
+export function clearRunContext(): void {
+  activeContext = null;
+}
+
+/** Get the current run's ProviderTracker, or undefined outside a workflow. */
+export function getProviderTracker(): ProviderTracker | undefined {
+  return activeContext?.providerTracker;
+}