opencandle 0.2.0 → 0.4.0

package/src/memory/preference-extractor.ts

@@ -0,0 +1,106 @@
+export interface ExtractedPreference {
+  key: string;
+  value: string;
+  confidence: "high" | "medium" | "low";
+}
+
+interface PatternRule {
+  pattern: RegExp;
+  key: string;
+  value: string;
+  confidence: "high" | "medium" | "low";
+}
+
+const PREFERENCE_PATTERNS: PatternRule[] = [
+  // Asset scope
+  {
+    pattern: /\bprefer\s+etfs?\b/i,
+    key: "asset_scope",
+    value: "etf_focused",
+    confidence: "high",
+  },
+  {
+    pattern: /\betf[\s-]*(?:heavy|focused|only)\b/i,
+    key: "asset_scope",
+    value: "etf_focused",
+    confidence: "high",
+  },
+
+  // Risk profile
+  {
+    pattern: /\b(?:i'?m|i\s+am)\s+conservative\b/i,
+    key: "risk_profile",
+    value: "conservative",
+    confidence: "high",
+  },
+  {
+    pattern: /\brisk\s*averse\b/i,
+    key: "risk_profile",
+    value: "conservative",
+    confidence: "high",
+  },
+  {
+    pattern: /\b(?:i'?m|i\s+am)\s+aggressive\b/i,
+    key: "risk_profile",
+    value: "aggressive",
+    confidence: "high",
+  },
+  {
+    pattern: /\baggressive\s+growth\b/i,
+    key: "risk_profile",
+    value: "aggressive",
+    confidence: "high",
+  },
+  {
+    pattern: /\b(?:i'?m|i\s+am)\s+(?:moderate|balanced)\b/i,
+    key: "risk_profile",
+    value: "balanced",
+    confidence: "high",
+  },
+
+  // Time horizon
+  {
+    pattern: /\b(?:12\s*month|one\s*year|1\s*year)\s*horizon/i,
+    key: "time_horizon",
+    value: "1y_plus",
+    confidence: "high",
+  },
+  {
+    pattern: /\blong[\s-]*term\s+(?:invest|hold|horizon)/i,
+    key: "time_horizon",
+    value: "long",
+    confidence: "medium",
+  },
+  {
+    pattern: /\bshort[\s-]*term\s+(?:trad|invest|horizon)/i,
+    key: "time_horizon",
+    value: "short",
+    confidence: "medium",
+  },
+
+  // Options liquidity
+  {
+    pattern: /\b(?:only|prefer)\s+(?:trade\s+)?liquid\s+options?\b/i,
+    key: "options_liquidity",
+    value: "high",
+    confidence: "high",
+  },
+];
+
+export function extractPreferences(input: string): ExtractedPreference[] {
+  const preferences: ExtractedPreference[] = [];
+  const seenKeys = new Set<string>();
+
+  for (const rule of PREFERENCE_PATTERNS) {
+    if (rule.pattern.test(input) && !seenKeys.has(rule.key)) {
+      preferences.push({
+        key: rule.key,
+        value: rule.value,
+        confidence: rule.confidence,
+      });
+      seenKeys.add(rule.key);
+    }
+  }
+
+  return preferences;
+}

package/src/memory/retrieval.ts

@@ -0,0 +1,70 @@
+import type { MemoryStorage } from "./storage.js";
+
+const MAX_PREFERENCE_LINES = 15;
+const MAX_WORKFLOW_SUMMARY_LINES = 12;
+
+/** Slot name → preference key(s) mapping for suppression. */
+const SLOT_TO_PREF_KEYS: Record<string, string[]> = {
+  riskProfile: ["risk_profile"],
+  assetScope: ["asset_scope"],
+  timeHorizon: ["time_horizon"],
+  dteTarget: ["dte_target"],
+  moneynessPreference: ["moneyness_preference"],
+  liquidityMinimum: ["liquidity_minimum", "options_liquidity"],
+};
+
+/**
+ * Build compact memory context for agent injection.
+ * @param overriddenSlots Slot names whose values were overridden by current-turn user input.
+ *   The corresponding preference keys will be excluded from memory context to avoid
+ *   conflicting provenance signals.
+ */
+export function buildMemoryContext(
+  storage: MemoryStorage,
+  overriddenSlots?: string[],
+): string {
+  const sections: string[] = [];
+
+  // Build set of preference keys to suppress
+  const suppressedKeys = new Set<string>();
+  if (overriddenSlots) {
+    for (const slot of overriddenSlots) {
+      const keys = SLOT_TO_PREF_KEYS[slot];
+      if (keys) keys.forEach((k) => suppressedKeys.add(k));
+    }
+  }
+
+  // Preferences
+  const prefs = storage.getPreferencesByNamespace("global");
+  if (prefs.length > 0) {
+    const filtered = prefs.filter((p) => !suppressedKeys.has(String(p.key)));
+    if (filtered.length > 0) {
+      const lines = filtered.slice(0, MAX_PREFERENCE_LINES).map((p) => {
+        const value = tryParseJson(p.value_json as string);
+        return `- ${p.key}: ${value}`;
+      });
+      sections.push("User Preferences:\n" + lines.join("\n"));
+    }
+  }
+
+  // Recent workflow runs
+  const runs = storage.getRecentWorkflowRuns(3);
+  if (runs.length > 0) {
+    const lines = runs.slice(0, MAX_WORKFLOW_SUMMARY_LINES).map((r) => {
+      const summary = r.output_summary ? ` — ${r.output_summary}` : "";
+      return `- ${r.workflow_type} (${r.created_at})${summary}`;
+    });
+    sections.push("Recent Workflows:\n" + lines.join("\n"));
+  }
+
+  return sections.join("\n\n");
+}
+
+function tryParseJson(json: string): string {
+  try {
+    const parsed = JSON.parse(json);
+    return typeof parsed === "string" ? parsed : JSON.stringify(parsed);
+  } catch {
+    return json;
+  }
+}

package/src/memory/sqlite.ts

@@ -0,0 +1,172 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import Database from "better-sqlite3";
+import { getStateDbPath } from "../infra/opencandle-paths.js";
+
+const CURRENT_SCHEMA_VERSION = 4;
+
+const CURRENT_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS user_preferences (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    namespace TEXT NOT NULL DEFAULT 'global',
+    key TEXT NOT NULL,
+    value_json TEXT NOT NULL,
+    confidence TEXT DEFAULT 'medium',
+    source TEXT DEFAULT 'explicit',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    UNIQUE(namespace, key)
+  );
+
+  CREATE TABLE IF NOT EXISTS workflow_runs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    workflow_type TEXT NOT NULL,
+    input_slots_json TEXT,
+    resolved_slots_json TEXT,
+    defaults_used_json TEXT,
+    output_summary TEXT,
+    created_at TEXT NOT NULL,
+    turn_type TEXT NOT NULL DEFAULT 'workflow'
+  );
+
+  CREATE TABLE IF NOT EXISTS recommendations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    workflow_run_id INTEGER NOT NULL,
+    recommendation_type TEXT NOT NULL,
+    symbol TEXT,
+    payload_json TEXT,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (workflow_run_id) REFERENCES workflow_runs(id)
+  );
+
+  CREATE TABLE IF NOT EXISTS workflow_events (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    run_id TEXT NOT NULL,
+    step_index INTEGER NOT NULL,
+    event_type TEXT NOT NULL,
+    payload_json TEXT,
+    timestamp TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_workflow_events_run_id ON workflow_events(run_id);
+
+  CREATE TABLE IF NOT EXISTS tool_defaults (
+    tool_name TEXT NOT NULL,
+    param_path TEXT NOT NULL,
+    value_json TEXT NOT NULL,
+    set_at TEXT NOT NULL,
+    PRIMARY KEY (tool_name, param_path)
+  );
+`;
+
+export function initDatabase(path: string): Database.Database {
+  if (path !== ":memory:") {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const db = new Database(path);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  ensureCurrentSchema(db);
+
+  return db;
+}
+
+export function initDefaultDatabase(): Database.Database {
+  return initDatabase(getStateDbPath());
+}
+
+function ensureCurrentSchema(db: Database.Database): void {
+  const currentVersion = readSchemaVersion(db);
+
+  if (currentVersion === CURRENT_SCHEMA_VERSION) {
+    // Up to date — still run CREATE TABLE IF NOT EXISTS for any missing auxiliary
+    // tables (e.g. workflow_events added out-of-band).
+    db.exec(CURRENT_SCHEMA);
+    return;
+  }
+
+  if (currentVersion === 3) {
+    migrateV3ToV4(db);
+    return;
+  }
+
+  // Additive v2 → v3 → v4 migration without dropping data.
+  if (currentVersion === 2) {
+    migrateV2ToV3(db);
+    migrateV3ToV4(db);
+    return;
+  }
+
+  // Any other mismatch (null first-run, or a foreign schema): reset.
+  resetSchema(db);
+}
+
+function migrateV2ToV3(db: Database.Database): void {
+  const cols = (db.pragma("table_info(workflow_runs)") as Array<{ name: string }>).map(
+    (c) => c.name,
+  );
+
+  if (!cols.includes("turn_type")) {
+    db.exec(
+      `ALTER TABLE workflow_runs ADD COLUMN turn_type TEXT NOT NULL DEFAULT 'workflow'`,
+    );
+  }
+
+  // Ensure any tables or indexes added between versions are present.
+  db.exec(CURRENT_SCHEMA);
+
+  db.prepare("DELETE FROM schema_version").run();
+  db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(3);
+}
+
+function migrateV3ToV4(db: Database.Database): void {
+  db.exec(CURRENT_SCHEMA);
+
+  db.prepare("DELETE FROM schema_version").run();
+  db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(CURRENT_SCHEMA_VERSION);
+}
+
+function readSchemaVersion(db: Database.Database): number | null {
+  const table = db
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schema_version'")
+    .get() as { name: string } | undefined;
+  if (!table) {
+    return null;
+  }
+
+  const row = db.prepare("SELECT version FROM schema_version LIMIT 1").get() as
+    | { version: number }
+    | undefined;
+  return row?.version ?? null;
+}
+
+function resetSchema(db: Database.Database): void {
+  db.exec(`
+    DROP TABLE IF EXISTS recommendations;
+    DROP TABLE IF EXISTS workflow_runs;
+    DROP TABLE IF EXISTS user_preferences;
+    DROP TABLE IF EXISTS tool_defaults;
+    DROP TABLE IF EXISTS schema_version;
+  `);
+  db.exec(CURRENT_SCHEMA);
+  db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(CURRENT_SCHEMA_VERSION);
+}
+
+export function getTableNames(db: Database.Database): string[] {
+  const rows = db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+    .all() as Array<{ name: string }>;
+  return rows.map((r) => r.name);
+}
+
+export function getSchemaVersion(db: Database.Database): number {
+  const row = db.prepare("SELECT version FROM schema_version LIMIT 1").get() as
+    | { version: number }
+    | undefined;
+  return row?.version ?? 0;
+}

package/src/memory/storage.ts

@@ -0,0 +1,204 @@
+import type Database from "better-sqlite3";
+
+interface PreferenceInput {
+  namespace?: string;
+  key: string;
+  valueJson: string;
+  confidence?: string;
+  source?: string;
+}
+
+export interface WorkflowPreferences {
+  riskProfile?: string;
+  timeHorizon?: string;
+  assetScope?: string;
+  positionCount?: number;
+  maxSinglePositionPct?: number;
+  dteTarget?: string;
+  objective?: string;
+  moneynessPreference?: string;
+  liquidityMinimum?: string;
+}
+
+interface WorkflowRunInput {
+  sessionId: string;
+  workflowType: string;
+  inputSlotsJson: string;
+  resolvedSlotsJson: string;
+  defaultsUsedJson: string;
+  outputSummary?: string;
+  /**
+   * Router route verbatim. One of `"workflow"` or `"fallback"`. Defaults to
+   * `"workflow"` at the schema layer so legacy callers (rules-mode cascade)
+   * don't need to pass anything. Router-mode callers MUST pass this explicitly.
+   */
+  turnType?: "workflow" | "fallback";
+}
+
+interface RecommendationInput {
+  workflowRunId: number;
+  recommendationType: string;
+  symbol?: string;
+  payloadJson?: string;
+}
+
+export class MemoryStorage {
+  constructor(private readonly db: Database.Database) {}
+
+  // --- Preferences ---
+
+  upsertPreference(input: PreferenceInput): void {
+    const now = new Date().toISOString();
+    const ns = input.namespace ?? "global";
+    const confidence = input.confidence ?? "medium";
+    const source = input.source ?? "explicit";
+
+    this.db
+      .prepare(
+        `INSERT INTO user_preferences (namespace, key, value_json, confidence, source, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(namespace, key) DO UPDATE SET
+           value_json = excluded.value_json,
+           confidence = excluded.confidence,
+           source = excluded.source,
+           updated_at = excluded.updated_at`,
+      )
+      .run(ns, input.key, input.valueJson, confidence, source, now, now);
+  }
+
+  getPreference(
+    namespace: string,
+    key: string,
+  ): Record<string, string | number | null> | null {
+    return (
+      (this.db
+        .prepare("SELECT * FROM user_preferences WHERE namespace = ? AND key = ?")
+        .get(namespace, key) as Record<string, string | number | null>) ?? null
+    );
+  }
+
+  getPreferencesByNamespace(
+    namespace: string,
+  ): Array<Record<string, string | number | null>> {
+    return this.db
+      .prepare("SELECT * FROM user_preferences WHERE namespace = ?")
+      .all(namespace) as Array<Record<string, string | number | null>>;
+  }
+
+  getWorkflowPreferences(namespace: string = "global"): WorkflowPreferences {
+    const prefs = this.getPreferencesByNamespace(namespace);
+    const out: WorkflowPreferences = {};
+
+    for (const pref of prefs) {
+      const key = String(pref.key);
+      const raw = pref.value_json == null ? undefined : safeParseJson(String(pref.value_json));
+
+      switch (key) {
+        case "risk_profile":
+          if (typeof raw === "string") out.riskProfile = raw;
+          break;
+        case "time_horizon":
+          if (typeof raw === "string") out.timeHorizon = raw;
+          break;
+        case "asset_scope":
+          if (typeof raw === "string") out.assetScope = raw;
+          break;
+        case "position_count":
+          if (typeof raw === "number") out.positionCount = raw;
+          break;
+        case "max_single_position_pct":
+          if (typeof raw === "number") out.maxSinglePositionPct = raw;
+          break;
+        case "dte_target":
+          if (typeof raw === "string") out.dteTarget = raw;
+          break;
+        case "objective":
+          if (typeof raw === "string") out.objective = raw;
+          break;
+        case "moneyness_preference":
+          if (typeof raw === "string") out.moneynessPreference = raw;
+          break;
+        case "options_liquidity":
+        case "liquidity_minimum":
+          if (typeof raw === "string") {
+            out.liquidityMinimum =
+              raw === "high" ? "high_open_interest_and_tight_spread" : raw;
+          }
+          break;
+      }
+    }
+
+    return out;
+  }
+
+  // --- Workflow Runs ---
+
+  insertWorkflowRun(input: WorkflowRunInput): number {
+    const now = new Date().toISOString();
+    const result = this.db
+      .prepare(
+        `INSERT INTO workflow_runs (session_id, workflow_type, input_slots_json, resolved_slots_json, defaults_used_json, output_summary, created_at, turn_type)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        input.sessionId,
+        input.workflowType,
+        input.inputSlotsJson,
+        input.resolvedSlotsJson,
+        input.defaultsUsedJson,
+        input.outputSummary ?? null,
+        now,
+        input.turnType ?? "workflow",
+      );
+    return Number(result.lastInsertRowid);
+  }
+
+  getRecentWorkflowRuns(
+    limit: number,
+  ): Array<Record<string, string | number | null>> {
+    return this.db
+      .prepare("SELECT * FROM workflow_runs ORDER BY id DESC LIMIT ?")
+      .all(limit) as Array<Record<string, string | number | null>>;
+  }
+
+  updateWorkflowRunOutputSummary(workflowRunId: number, outputSummary: string): void {
+    this.db
+      .prepare("UPDATE workflow_runs SET output_summary = ? WHERE id = ?")
+      .run(outputSummary, workflowRunId);
+  }
+
+  // --- Recommendations ---
+
+  insertRecommendation(input: RecommendationInput): number {
+    const now = new Date().toISOString();
+    const result = this.db
+      .prepare(
+        `INSERT INTO recommendations (workflow_run_id, recommendation_type, symbol, payload_json, created_at)
+         VALUES (?, ?, ?, ?, ?)`,
+      )
+      .run(
+        input.workflowRunId,
+        input.recommendationType,
+        input.symbol ?? null,
+        input.payloadJson ?? null,
+        now,
+      );
+    return Number(result.lastInsertRowid);
+  }
+
+  getRecommendationsByRun(
+    workflowRunId: number,
+  ): Array<Record<string, string | number | null>> {
+    return this.db
+      .prepare("SELECT * FROM recommendations WHERE workflow_run_id = ? ORDER BY id")
+      .all(workflowRunId) as Array<Record<string, string | number | null>>;
+  }
+}
+
+function safeParseJson(json: string): unknown {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return json;
+  }
+}

package/src/memory/tool-defaults.ts

@@ -0,0 +1,87 @@
+import { initDefaultDatabase } from "./sqlite.js";
+
+export type ToolDefaults = Record<string, unknown>;
+type SqliteDb = ReturnType<typeof initDefaultDatabase>;
+
+export function getDefaults(toolName: string, db: SqliteDb = initDefaultDatabase()): ToolDefaults {
+  const rows = db
+    .prepare(
+      `SELECT param_path, value_json FROM tool_defaults WHERE tool_name = ? ORDER BY param_path`,
+    )
+    .all(toolName) as Array<{ param_path: string; value_json: string }>;
+
+  const defaults: ToolDefaults = {};
+  for (const row of rows) {
+    setPath(defaults, row.param_path, parseStoredValue(row.value_json));
+  }
+  return defaults;
+}
+
+export function getAllDefaults(db: SqliteDb = initDefaultDatabase()): Map<string, ToolDefaults> {
+  const rows = db
+    .prepare(
+      `SELECT tool_name, param_path, value_json FROM tool_defaults ORDER BY tool_name, param_path`,
+    )
+    .all() as Array<{ tool_name: string; param_path: string; value_json: string }>;
+
+  const groups = new Map<string, ToolDefaults>();
+  for (const row of rows) {
+    const defaults = groups.get(row.tool_name) ?? {};
+    setPath(defaults, row.param_path, parseStoredValue(row.value_json));
+    groups.set(row.tool_name, defaults);
+  }
+  return groups;
+}
+
+export function setDefault(
+  toolName: string,
+  paramPath: string,
+  value: unknown,
+  db: SqliteDb = initDefaultDatabase(),
+): void {
+  db.prepare(
+    `INSERT INTO tool_defaults (tool_name, param_path, value_json, set_at)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(tool_name, param_path) DO UPDATE SET
+       value_json = excluded.value_json,
+       set_at = excluded.set_at`,
+  ).run(toolName, paramPath, JSON.stringify(value), new Date().toISOString());
+}
+
+export function clearDefault(
+  toolName: string,
+  paramPath: string,
+  db: SqliteDb = initDefaultDatabase(),
+): void {
+  db.prepare(`DELETE FROM tool_defaults WHERE tool_name = ? AND param_path = ?`).run(
+    toolName,
+    paramPath,
+  );
+}
+
+function parseStoredValue(valueJson: string): unknown {
+  try {
+    return JSON.parse(valueJson);
+  } catch {
+    return valueJson;
+  }
+}
+
+function setPath(target: ToolDefaults, path: string, value: unknown): void {
+  const parts = path.split(".").filter(Boolean);
+  if (parts.length === 0) return;
+
+  let cursor: Record<string, unknown> = target;
+  for (const part of parts.slice(0, -1)) {
+    const existing = cursor[part];
+    if (!isPlainObject(existing)) {
+      cursor[part] = {};
+    }
+    cursor = cursor[part] as Record<string, unknown>;
+  }
+  cursor[parts[parts.length - 1]] = value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/memory/types.ts

@@ -0,0 +1,67 @@
+/** Memory categories for typed, selective retrieval. */
+export type MemoryCategory =
+  | "investor_profile"
+  | "interaction_feedback"
+  | "workflow_history"
+  | "references";
+
+/** A memory entry with category and freshness metadata. */
+export interface MemoryEntry {
+  key: string;
+  value: string;
+  category: MemoryCategory;
+  recordedAt: string;
+  confidence?: string;
+  source?: string;
+}
+
+/** Staleness thresholds in milliseconds per category. */
+export const STALENESS_THRESHOLDS: Record<MemoryCategory, number> = {
+  investor_profile: 90 * 24 * 60 * 60 * 1000,    // 90 days
+  interaction_feedback: 14 * 24 * 60 * 60 * 1000, // 14 days
+  workflow_history: 7 * 24 * 60 * 60 * 1000,      // 7 days
+  references: 30 * 24 * 60 * 60 * 1000,           // 30 days
+};
+
+/** Map preference keys to memory categories. */
+export const KEY_TO_CATEGORY: Record<string, MemoryCategory> = {
+  risk_profile: "investor_profile",
+  time_horizon: "investor_profile",
+  asset_scope: "investor_profile",
+  position_count: "investor_profile",
+  max_single_position_pct: "investor_profile",
+  account_type: "investor_profile",
+  income_vs_growth: "investor_profile",
+  dte_target: "investor_profile",
+  objective: "investor_profile",
+  moneyness_preference: "investor_profile",
+  liquidity_minimum: "investor_profile",
+};
+
+/** Categories relevant to each workflow type. */
+export const WORKFLOW_RELEVANT_CATEGORIES: Record<string, MemoryCategory[]> = {
+  portfolio_builder: ["investor_profile", "interaction_feedback", "workflow_history"],
+  options_screener: ["investor_profile", "interaction_feedback", "workflow_history"],
+  compare_assets: ["investor_profile", "workflow_history"],
+  comprehensive_analysis: ["investor_profile", "workflow_history"],
+  single_asset_analysis: ["investor_profile"],
+  general_finance_qa: ["investor_profile"],
+  unclassified: ["investor_profile"],
+};
+
+/** Check whether a memory entry is stale. */
+export function isStale(entry: MemoryEntry, now: Date = new Date()): boolean {
+  const threshold = STALENESS_THRESHOLDS[entry.category];
+  const age = now.getTime() - new Date(entry.recordedAt).getTime();
+  return age > threshold;
+}
+
+/** Keys whose values are market-sensitive and must never be trusted from memory. */
+export const NEVER_TRUST_FROM_MEMORY = new Set([
+  "stock_price",
+  "crypto_price",
+  "market_thesis",
+  "target_price",
+  "entry_price",
+  "stop_loss",
+]);