opencandle 0.3.0 → 0.5.0

package/src/runtime/validation.ts

@@ -0,0 +1,214 @@
+import type { EvidenceRecord } from "./evidence.js";
+
+/** A single validation check result. */
+export interface ValidationEntry {
+  message: string;
+  evidenceLabel?: string;
+  detail?: string;
+}
+
+/** Result of running all deterministic validation checks. */
+export interface ValidationResult {
+  passes: ValidationEntry[];
+  failures: ValidationEntry[];
+  warnings: ValidationEntry[];
+}
+
+/** Create an empty validation result. */
+export function emptyValidationResult(): ValidationResult {
+  return { passes: [], failures: [], warnings: [] };
+}
+
+/** Check that market-sensitive evidence records have timestamps. */
+export function checkTimestamps(
+  evidence: EvidenceRecord[],
+  marketSensitiveLabels: Set<string>,
+): ValidationEntry[] {
+  const warnings: ValidationEntry[] = [];
+  for (const record of evidence) {
+    if (
+      marketSensitiveLabels.has(record.label) &&
+      record.provenance.source === "fetched" &&
+      !record.provenance.timestamp
+    ) {
+      warnings.push({
+        message: `Market-sensitive value '${record.label}' has no timestamp`,
+        evidenceLabel: record.label,
+      });
+    }
+  }
+  return warnings;
+}
+
+/** Check that options expiry dates are in the future. */
+export function checkOptionsExpiries(
+  evidence: EvidenceRecord[],
+  today: string,
+): ValidationEntry[] {
+  const failures: ValidationEntry[] = [];
+  for (const record of evidence) {
+    if (
+      record.label.toLowerCase().includes("expir") &&
+      typeof record.value === "string" &&
+      record.value < today
+    ) {
+      failures.push({
+        message: `Options expiry ${record.value} is in the past`,
+        evidenceLabel: record.label,
+        detail: `Today is ${today}`,
+      });
+    }
+  }
+  return failures;
+}
+
+/** Check that all required fields have evidence records. */
+export function checkRequiredFields(
+  evidence: EvidenceRecord[],
+  requiredLabels: string[],
+): ValidationEntry[] {
+  const present = new Set(evidence.map((e) => e.label));
+  const failures: ValidationEntry[] = [];
+  for (const label of requiredLabels) {
+    if (!present.has(label)) {
+      failures.push({
+        message: `Required field '${label}' has no evidence record`,
+        evidenceLabel: label,
+      });
+    }
+  }
+  return failures;
+}
+
+/** Default market-sensitive labels. */
+export const DEFAULT_MARKET_SENSITIVE_LABELS = new Set([
+  "Stock Price",
+  "Volume",
+  "Market Cap",
+  "52-Week High",
+  "52-Week Low",
+  "Bid",
+  "Ask",
+  "Day High",
+  "Day Low",
+  "Open",
+  "Previous Close",
+  "Crypto Price",
+  "Crypto Volume",
+]);
+
+/** Configuration for the runtime validator. */
+export interface ValidatorConfig {
+  marketSensitiveLabels?: Set<string>;
+  requiredFields?: string[];
+  toolResults?: Map<string, number>;
+  today?: string;
+}
+
+/**
+ * Orchestrates all deterministic validation checks on evidence records.
+ * Runs before LLM-based validation.
+ */
+export class RuntimeValidator {
+  private readonly config: ValidatorConfig;
+
+  constructor(config: ValidatorConfig = {}) {
+    this.config = config;
+  }
+
+  /** Run all validation checks and return a combined result. */
+  validate(evidence: EvidenceRecord[]): ValidationResult {
+    const result = emptyValidationResult();
+
+    // Timestamp checks
+    const timestampWarnings = checkTimestamps(
+      evidence,
+      this.config.marketSensitiveLabels ?? DEFAULT_MARKET_SENSITIVE_LABELS,
+    );
+    result.warnings.push(...timestampWarnings);
+
+    // Options expiry checks
+    const today = this.config.today ?? new Date().toISOString().slice(0, 10);
+    const expiryFailures = checkOptionsExpiries(evidence, today);
+    result.failures.push(...expiryFailures);
+
+    // Required field checks
+    if (this.config.requiredFields) {
+      const fieldFailures = checkRequiredFields(evidence, this.config.requiredFields);
+      result.failures.push(...fieldFailures);
+    }
+
+    // Number match checks
+    if (this.config.toolResults) {
+      const numberEntries = checkNumberMatch(evidence, this.config.toolResults);
+      for (const entry of numberEntries) {
+        if ((entry as any).type === "pass") {
+          result.passes.push(entry);
+        } else {
+          result.failures.push(entry);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /** Format validation results as a summary string for the LLM validation prompt. */
+  formatForLLM(result: ValidationResult): string {
+    const lines: string[] = ["## Deterministic Validation Results"];
+
+    if (result.failures.length > 0) {
+      lines.push(`\n### Failures (${result.failures.length})`);
+      for (const f of result.failures) {
+        lines.push(`- ${f.message}`);
+      }
+    }
+
+    if (result.warnings.length > 0) {
+      lines.push(`\n### Warnings (${result.warnings.length})`);
+      for (const w of result.warnings) {
+        lines.push(`- ${w.message}`);
+      }
+    }
+
+    if (result.passes.length > 0) {
+      lines.push(`\n### Verified (${result.passes.length})`);
+      for (const p of result.passes) {
+        lines.push(`- ${p.message}`);
+      }
+    }
+
+    if (result.failures.length === 0 && result.warnings.length === 0) {
+      lines.push("\nAll deterministic checks passed.");
+    }
+
+    return lines.join("\n");
+  }
+}
+
+/** Check that evidence values match expected tool result values. */
+export function checkNumberMatch(
+  evidence: EvidenceRecord[],
+  toolResults: Map<string, number>,
+): ValidationEntry[] {
+  const results: (ValidationEntry & { type: "pass" | "failure" })[] = [];
+  for (const record of evidence) {
+    if (typeof record.value !== "number") continue;
+    const expected = toolResults.get(record.label);
+    if (expected === undefined) continue;
+    if (record.value === expected) {
+      results.push({
+        type: "pass",
+        message: `${record.label}: ${record.value} matches tool result`,
+        evidenceLabel: record.label,
+      });
+    } else {
+      results.push({
+        type: "failure",
+        message: `${record.label} mismatch: evidence says ${record.value}, tool returned ${expected}`,
+        evidenceLabel: record.label,
+      });
+    }
+  }
+  return results;
+}

package/src/runtime/workflow-events.ts

@@ -0,0 +1,75 @@
+import type Database from "better-sqlite3";
+
+/** All workflow event types. */
+export type WorkflowEventType =
+  | "workflow_started"
+  | "slot_resolved"
+  | "clarification_asked"
+  | "clarification_answered"
+  | "step_started"
+  | "step_completed"
+  | "step_failed"
+  | "step_skipped"
+  | "tool_called"
+  | "tool_failed"
+  | "validation_passed"
+  | "validation_failed"
+  | "workflow_completed"
+  | "workflow_cancelled";
+
+/** A persisted workflow event row. */
+export interface WorkflowEvent {
+  id: number;
+  runId: string;
+  stepIndex: number;
+  eventType: WorkflowEventType;
+  payloadJson: string | null;
+  timestamp: string;
+}
+
+/** Append-only workflow event logger backed by SQLite. */
+export class WorkflowEventLogger {
+  constructor(private readonly db: Database.Database) {}
+
+  /** Append a workflow event. */
+  log(
+    runId: string,
+    stepIndex: number,
+    eventType: WorkflowEventType,
+    payload?: Record<string, unknown>,
+  ): void {
+    const now = new Date().toISOString();
+    const payloadJson = payload ? JSON.stringify(payload) : null;
+    this.db
+      .prepare(
+        `INSERT INTO workflow_events (run_id, step_index, event_type, payload_json, timestamp)
+         VALUES (?, ?, ?, ?, ?)`,
+      )
+      .run(runId, stepIndex, eventType, payloadJson, now);
+  }
+
+  /** Query all events for a given run ID, ordered by timestamp. */
+  getEventsByRunId(runId: string): WorkflowEvent[] {
+    const rows = this.db
+      .prepare(
+        "SELECT id, run_id, step_index, event_type, payload_json, timestamp FROM workflow_events WHERE run_id = ? ORDER BY id",
+      )
+      .all(runId) as Array<{
+        id: number;
+        run_id: string;
+        step_index: number;
+        event_type: string;
+        payload_json: string | null;
+        timestamp: string;
+      }>;
+
+    return rows.map((r) => ({
+      id: r.id,
+      runId: r.run_id,
+      stepIndex: r.step_index,
+      eventType: r.event_type as WorkflowEventType,
+      payloadJson: r.payload_json,
+      timestamp: r.timestamp,
+    }));
+  }
+}

package/src/runtime/workflow-runner.ts

@@ -0,0 +1,188 @@
+import type { WorkflowRun, StepOutput, WorkflowStep } from "./workflow-types.js";
+import {
+  createWorkflowRun,
+  transitionStepStatus,
+} from "./workflow-types.js";
+import type { WorkflowEventLogger } from "./workflow-events.js";
+import type { ProviderTracker } from "./provider-tracker.js";
+import type { EvidenceRecord } from "./evidence.js";
+
+/** Function that executes a single workflow step. */
+export type StepExecutor = (
+  step: WorkflowStep,
+  stepIndex: number,
+  priorEvidence: EvidenceRecord[],
+  context: StepExecutionContext,
+) => Promise<StepOutput>;
+
+/** Context passed to step executors. */
+export interface StepExecutionContext {
+  runId: string;
+  providerTracker: ProviderTracker;
+}
+
+/** Options for creating a WorkflowRunner. */
+export interface WorkflowRunnerOptions {
+  eventLogger?: WorkflowEventLogger;
+  providerTracker?: ProviderTracker;
+}
+
+let runCounter = 0;
+
+function generateRunId(): string {
+  runCounter += 1;
+  return `run_${Date.now()}_${runCounter}`;
+}
+
+/**
+ * Typed workflow execution engine with run IDs, step definitions,
+ * state transitions, cancellation, and event logging.
+ */
+export class WorkflowRunner {
+  private readonly eventLogger?: WorkflowEventLogger;
+  private readonly providerTracker?: ProviderTracker;
+  private activeRun: WorkflowRun | null = null;
+
+  constructor(options: WorkflowRunnerOptions = {}) {
+    this.eventLogger = options.eventLogger;
+    this.providerTracker = options.providerTracker;
+  }
+
+  /** Get the currently active run, if any. */
+  getActiveRun(): WorkflowRun | null {
+    return this.activeRun;
+  }
+
+  /**
+   * Start a new workflow run. If a run is already active, it is cancelled first.
+   */
+  async start(
+    workflowType: string,
+    stepDefinitions: Omit<WorkflowStep, "status">[],
+    executor: StepExecutor,
+  ): Promise<WorkflowRun> {
+    // Cancel any active run
+    if (this.activeRun && this.activeRun.status === "running") {
+      this.cancel();
+    }
+
+    const runId = generateRunId();
+    const run = createWorkflowRun(runId, workflowType, stepDefinitions);
+    this.activeRun = run;
+    run.status = "running";
+
+    this.providerTracker?.resetAll();
+
+    this.logEvent(runId, 0, "workflow_started", {
+      workflowType,
+      stepCount: stepDefinitions.length,
+    });
+
+    // Execute steps
+    await this.executeSteps(run, executor);
+
+    return run;
+  }
+
+  /** Cancel the active run. */
+  cancel(): void {
+    const run = this.activeRun;
+    if (!run || run.status !== "running") return;
+
+    for (let i = run.currentStepIndex; i < run.steps.length; i++) {
+      const step = run.steps[i];
+      if (step.status === "pending" || step.status === "running") {
+        step.status = transitionStepStatus(step.status, "skipped");
+        this.logEvent(run.runId, i, "step_skipped", {
+          stepType: step.stepType,
+          reason: "cancelled",
+        });
+      }
+    }
+
+    run.status = "cancelled";
+    this.logEvent(run.runId, run.currentStepIndex, "workflow_cancelled", {
+      cancelledAtStep: run.currentStepIndex,
+    });
+  }
+
+  private async executeSteps(
+    run: WorkflowRun,
+    executor: StepExecutor,
+  ): Promise<void> {
+    for (let i = 0; i < run.steps.length; i++) {
+      // Check if run was cancelled externally
+      if (run.status !== "running") return;
+
+      const step = run.steps[i];
+      run.currentStepIndex = i;
+
+      // Collect all prior evidence
+      const priorEvidence: EvidenceRecord[] = [];
+      for (const [, output] of run.stepOutputs) {
+        priorEvidence.push(...output.evidence);
+      }
+
+      // Transition to running
+      step.status = transitionStepStatus(step.status, "running");
+      this.logEvent(run.runId, i, "step_started", { stepType: step.stepType });
+
+      try {
+        const context: StepExecutionContext = {
+          runId: run.runId,
+          providerTracker: this.providerTracker!,
+        };
+
+        const output = await executor(step, i, priorEvidence, context);
+
+        // If run was cancelled during execution, stop without further transitions
+        if (run.status !== "running") return;
+
+        step.status = transitionStepStatus(step.status, "completed");
+        run.stepOutputs.set(i, output);
+
+        this.logEvent(run.runId, i, "step_completed", {
+          stepType: step.stepType,
+          evidenceCount: output.evidence.length,
+        });
+      } catch (error) {
+        // If run was cancelled during execution, stop without further transitions
+        if (run.status !== "running") return;
+
+        const message = error instanceof Error ? error.message : "unknown_error";
+
+        if (step.skippable) {
+          step.status = transitionStepStatus(step.status, "skipped");
+          this.logEvent(run.runId, i, "step_skipped", {
+            stepType: step.stepType,
+            reason: message,
+          });
+        } else {
+          step.status = transitionStepStatus(step.status, "failed");
+          this.logEvent(run.runId, i, "step_failed", {
+            stepType: step.stepType,
+            error: message,
+          });
+          run.status = "failed";
+          return;
+        }
+      }
+    }
+
+    if (run.status === "running") {
+      run.status = "completed";
+      this.logEvent(run.runId, run.steps.length - 1, "workflow_completed", {
+        workflowType: run.workflowType,
+      });
+    }
+  }
+
+  private logEvent(
+    runId: string,
+    stepIndex: number,
+    eventType: string,
+    payload: Record<string, unknown>,
+  ): void {
+    this.eventLogger?.log(runId, stepIndex, eventType as any, payload);
+  }
+}

package/src/runtime/workflow-types.ts

@@ -0,0 +1,102 @@
+import type { EvidenceRecord } from "./evidence.js";
+
+/** Status of a single workflow step. */
+export type StepStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+
+/** Overall status of a workflow run. */
+export type RunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
+
+/** Valid step status transitions. */
+const VALID_STEP_TRANSITIONS: Record<StepStatus, StepStatus[]> = {
+  pending: ["running", "skipped"],
+  running: ["completed", "failed", "skipped"],
+  completed: [],
+  failed: [],
+  skipped: [],
+};
+
+/** Check whether a step status transition is valid. */
+export function isValidStepTransition(from: StepStatus, to: StepStatus): boolean {
+  return VALID_STEP_TRANSITIONS[from].includes(to);
+}
+
+/** Transition a step status, throwing on invalid transitions. */
+export function transitionStepStatus(from: StepStatus, to: StepStatus): StepStatus {
+  if (!isValidStepTransition(from, to)) {
+    throw new Error(`Invalid step transition: ${from} → ${to}`);
+  }
+  return to;
+}
+
+/** Definition of a single workflow step. */
+export interface WorkflowStep {
+  stepType: string;
+  description: string;
+  requiredInputs: string[];
+  expectedOutputs: string[];
+  skippable: boolean;
+  status: StepStatus;
+}
+
+/** Output produced by a completed workflow step. */
+export interface StepOutput {
+  stepIndex: number;
+  stepType: string;
+  evidence: EvidenceRecord[];
+  rawText?: string;
+}
+
+/** Analyst signal direction. */
+export type AnalystSignal = "BUY" | "HOLD" | "SELL";
+
+/** Structured output from a single analyst role. */
+export interface AnalystOutput {
+  role: string;
+  signal: AnalystSignal;
+  conviction: number;
+  thesis: string;
+  evidence: EvidenceRecord[];
+  rawText?: string;
+}
+
+/** Debate side in bull/bear adversarial debate. */
+export type DebateSide = "bull" | "bear";
+
+/** Structured output from a debate step (eval/test only — not used in live path). */
+export interface DebateOutput {
+  side: DebateSide;
+  thesis: string;
+  keyRisk: string;
+  concessions: string[];
+  remainingConviction: number;
+  evidence: EvidenceRecord[];
+  rawText: string;
+}
+
+/** A complete workflow run definition and state. */
+export interface WorkflowRun {
+  runId: string;
+  workflowType: string;
+  steps: WorkflowStep[];
+  currentStepIndex: number;
+  status: RunStatus;
+  stepOutputs: Map<number, StepOutput>;
+  createdAt: string;
+}
+
+/** Create a new workflow run with all steps in pending state. */
+export function createWorkflowRun(
+  runId: string,
+  workflowType: string,
+  stepDefinitions: Omit<WorkflowStep, "status">[],
+): WorkflowRun {
+  return {
+    runId,
+    workflowType,
+    steps: stepDefinitions.map((def) => ({ ...def, status: "pending" as const })),
+    currentStepIndex: 0,
+    status: "pending",
+    stepOutputs: new Map(),
+    createdAt: new Date().toISOString(),
+  };
+}

package/src/sentiment/adapters/finnhub.ts

@@ -0,0 +1,44 @@
+import { randomUUID } from "node:crypto";
+import type { SentinelRecord } from "../types.js";
+import type { FinnhubArticle } from "../../providers/finnhub.js";
+import { extractEntities } from "../../routing/entity-extractor.js";
+
+const MAX_TICKERS = 3;
+
+export class FinnhubAdapter {
+  readonly source = "finnhub" as const;
+
+  mapToRecords(articles: FinnhubArticle[], query: string): SentinelRecord[] {
+    const fetchedAt = new Date().toISOString();
+    return articles.map((article) => ({
+      id: randomUUID(),
+      source: this.source,
+      sourceId: String(article.id),
+      query,
+      title: article.headline,
+      text: article.summary,
+      author: article.source,
+      url: article.url,
+      publishedAt: new Date(article.datetime * 1000).toISOString(),
+      fetchedAt,
+      engagement: {
+        score: 0,
+        replies: null,
+        shares: null,
+        views: null,
+      },
+      sentiment: {
+        score: 0,
+        confidence: 0,
+        method: "keyword" as const,
+        tickers: article.related ? article.related.split(",").map((t) => t.trim()).filter(Boolean) : [],
+      },
+      metadata: { category: article.category },
+    }));
+  }
+}
+
+export function extractTickersFromQuery(query: string): string[] {
+  const entities = extractEntities(query);
+  return entities.symbols.slice(0, MAX_TICKERS);
+}

package/src/sentiment/adapters/reddit.ts

@@ -0,0 +1,65 @@
+import { randomUUID } from "node:crypto";
+import type { SentinelRecord, SentimentAdapter } from "../types.js";
+import type { RedditSentimentResult } from "../../types/sentiment.js";
+import type { RedditComment } from "../../providers/reddit.js";
+
+export class RedditAdapter implements SentimentAdapter {
+  readonly source = "reddit" as const;
+
+  mapPostsToRecords(result: RedditSentimentResult, query: string): SentinelRecord[] {
+    const fetchedAt = result.fetchedAt;
+    return result.posts.map((post) => ({
+      id: randomUUID(),
+      source: this.source,
+      sourceId: post.id,
+      query,
+      title: post.title,
+      text: post.selftext ? `${post.title}\n${post.selftext}` : post.title,
+      author: post.author,
+      url: post.url,
+      publishedAt: post.created,
+      fetchedAt,
+      engagement: {
+        score: post.score,
+        replies: post.comments,
+        shares: null,
+        views: null,
+      },
+      sentiment: { score: 0, confidence: 0, method: "keyword" as const, tickers: [] },
+      metadata: { subreddit: result.subreddit },
+    }));
+  }
+
+  mapCommentsToRecords(
+    comments: RedditComment[],
+    parentId: string,
+    subreddit: string,
+    query: string,
+  ): SentinelRecord[] {
+    const fetchedAt = new Date().toISOString();
+    return comments.map((comment) => ({
+      id: randomUUID(),
+      source: this.source,
+      sourceId: comment.id,
+      query,
+      title: null,
+      text: comment.body,
+      author: comment.author,
+      url: comment.permalink,
+      publishedAt: null,
+      fetchedAt,
+      engagement: {
+        score: comment.score,
+        replies: null,
+        shares: null,
+        views: null,
+      },
+      sentiment: { score: 0, confidence: 0, method: "keyword" as const, tickers: [] },
+      metadata: { isComment: true, parentId, subreddit },
+    }));
+  }
+
+  async fetch(_query: string, _options?: { hours?: number }): Promise<SentinelRecord[]> {
+    throw new Error("Use pipeline.run() instead of adapter.fetch() directly");
+  }
+}