desic-okx-agent 0.2.1 → 0.3.0

package/dist/strategy/schema.js

@@ -0,0 +1,91 @@
+/**
+ * Storage for queued and completed strategy runs.
+ *
+ * The equity curve is stored as fixed-width little-endian float64 blocks rather
+ * than JSON rows. A 500k-bar curve is tens of megabytes as JSON objects and
+ * under a megabyte here, and every value round-trips bit-for-bit — decimal JSON
+ * text does not guarantee that.
+ */
+export const STRATEGY_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS strategy_runs (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  status TEXT NOT NULL,
+  strategy_name TEXT NOT NULL,
+  strategy_hash TEXT NOT NULL,
+  strategy_source TEXT NOT NULL,
+  inst_id TEXT NOT NULL,
+  request_json TEXT NOT NULL,
+  data_snapshot_id TEXT,
+  bar_count INTEGER NOT NULL DEFAULT 0,
+  preload_bars INTEGER NOT NULL DEFAULT 0,
+  progress_pct REAL NOT NULL DEFAULT 0,
+  eta_ms INTEGER,
+  metrics_json TEXT,
+  -- The assumptions the run actually used. Stored per run because settings can
+  -- change between runs, and a report that cannot say what it assumed is not
+  -- comparable to any other report.
+  assumptions_json TEXT,
+  error TEXT,
+  created_at INTEGER NOT NULL,
+  started_at INTEGER,
+  finished_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_strategy_runs_created
+  ON strategy_runs(created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_strategy_runs_status
+  ON strategy_runs(status, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS strategy_run_series (
+  run_id TEXT NOT NULL,
+  chunk_index INTEGER NOT NULL,
+  from_point INTEGER NOT NULL,
+  to_point INTEGER NOT NULL,
+  start_ms INTEGER NOT NULL,
+  step_ms INTEGER NOT NULL,
+  payload BLOB NOT NULL,
+  PRIMARY KEY(run_id, chunk_index)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS strategy_run_trades (
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  trade_json TEXT NOT NULL,
+  PRIMARY KEY(run_id, seq)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS strategy_run_actions (
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  action_json TEXT NOT NULL,
+  PRIMARY KEY(run_id, seq)
+) WITHOUT ROWID;
+
+-- One row per evaluated parameter combination of an optimize run.
+--
+-- Training and validation metrics are stored separately rather than merged into
+-- one figure. The gap between them is the finding: a candidate that earned its
+-- ranking and one that memorized the training segment are indistinguishable from
+-- a single number.
+CREATE TABLE IF NOT EXISTS strategy_optimization_candidates (
+  run_id TEXT NOT NULL,
+  candidate_index INTEGER NOT NULL,
+  params_json TEXT NOT NULL,
+  status TEXT NOT NULL,
+  train_metrics_json TEXT,
+  validation_metrics_json TEXT,
+  -- Validation-segment score. Null while queued, and for a candidate that failed.
+  rank_score REAL,
+  -- Which formula produced rank_score, because it is not always Calmar.
+  rank_basis TEXT,
+  verdict TEXT,
+  error TEXT,
+  PRIMARY KEY(run_id, candidate_index)
+) WITHOUT ROWID;
+
+-- Ranking reads this in score order, so it is indexed rather than sorted per read.
+CREATE INDEX IF NOT EXISTS idx_optimization_rank
+  ON strategy_optimization_candidates(run_id, rank_score DESC);
+`;
+//# sourceMappingURL=schema.js.map

package/dist/strategy/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/strategy/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFlC,CAAC"}

package/dist/strategy/service.d.ts

@@ -0,0 +1,138 @@
+import { type ToolResult } from "../core/types.js";
+import type { BarService } from "../bars/service.js";
+import type { MarketService } from "../market/service.js";
+import { type PythonStatus } from "./environment.js";
+import { type BacktestSettings } from "./settings.js";
+import { StrategyStore } from "./store.js";
+import { type ComparisonReport } from "../report/compare.js";
+import type { BacktestRequest, EquityPoint, OptimizationReport, OptimizeRequest, Page, RunStatus, RunSummary, ValidationResult } from "./types.js";
+export declare class StrategyService {
+    readonly store: StrategyStore;
+    private readonly bars;
+    /**
+     * Source of contract specifications. Optional so a test can construct the
+     * service without a market runtime; a run then fails with a clear message
+     * rather than falling back to a guessed contract size.
+     */
+    private readonly market?;
+    private readonly maxWorkers;
+    private readonly now;
+    /** Test seam: bypasses the settings file so a run is reproducible. */
+    private readonly injectedSettings?;
+    private readonly active;
+    private queue;
+    private running;
+    constructor(store: StrategyStore, bars: BarService, 
+    /**
+     * Source of contract specifications. Optional so a test can construct the
+     * service without a market runtime; a run then fails with a clear message
+     * rather than falling back to a guessed contract size.
+     */
+    market?: MarketService | undefined, maxWorkers?: number, now?: () => number, 
+    /** Test seam: bypasses the settings file so a run is reproducible. */
+    injectedSettings?: BacktestSettings | undefined);
+    /** Reports interpreter availability without changing anything. */
+    environment(): Promise<ToolResult<PythonStatus>>;
+    setupEnvironment(onLog?: (line: string) => void): Promise<ToolResult<Record<string, unknown>>>;
+    /** Saved settings, or the injected ones when a caller supplied them. */
+    settings(): BacktestSettings;
+    readSettings(): ToolResult<BacktestSettings>;
+    /**
+     * Applies saved settings. Unknown keys and out-of-range values are rejected
+     * rather than ignored: a silently dropped change means the next run uses
+     * assumptions the caller believes it changed.
+     */
+    updateSettings(values: Record<string, unknown>, reset?: boolean): ToolResult<BacktestSettings>;
+    /** Static policy check. Fast enough to run on every edit. */
+    validate(source: string): Promise<ToolResult<ValidationResult>>;
+    /**
+     * Queues a backtest and returns immediately.
+     *
+     * A run can take minutes, so the caller polls `getRun` rather than holding a
+     * request open and risking a client-side timeout.
+     */
+    startBacktest(request: BacktestRequest): Promise<ToolResult<{
+        runId: string;
+        status: RunStatus;
+    }>>;
+    /**
+     * Queues a parameter search and returns immediately.
+     *
+     * The space is validated against the strategy's own declared parameters before
+     * anything is queued, so a range naming a parameter the strategy never reads
+     * fails at the prompt rather than after every candidate has run identically.
+     */
+    startOptimize(request: OptimizeRequest): Promise<ToolResult<{
+        runId: string;
+        status: RunStatus;
+    }>>;
+    /**
+     * Ranked candidates for one optimize run.
+     *
+     * Ranking is by the held-back segment, never the searched one. The winner's
+     * ranking basis is reported alongside, because Calmar is unavailable on short
+     * windows and a column that silently changes meaning is worse than a labelled
+     * one.
+     */
+    optimization(id: string, top?: number): ToolResult<OptimizationReport>;
+    /**
+     * Compares completed runs.
+     *
+     * The equity curves are read whole here rather than paged: a comparison is
+     * summary-level, and the curves are downsampled before they leave. The response
+     * carries metrics, the assumptions that differ, and the warnings — not the
+     * curves, which would bury an agent's context for no benefit.
+     */
+    compareRuns(runIds: string[]): ToolResult<Omit<ComparisonReport, "series">>;
+    getRun(id: string): ToolResult<RunSummary>;
+    listRuns(options?: {
+        limit?: number;
+        status?: RunStatus;
+        instId?: string;
+    }): ToolResult<RunSummary[]>;
+    equity(id: string, offset?: number, limit?: number): ToolResult<Page<EquityPoint>>;
+    trades(id: string, offset?: number, limit?: number): ToolResult<Page<unknown>>;
+    actions(id: string, offset?: number, limit?: number): ToolResult<Page<unknown>>;
+    cancel(id: string): ToolResult<{
+        cancelled: boolean;
+    }>;
+    deleteRun(id: string): ToolResult<{
+        deleted: boolean;
+    }>;
+    /**
+     * Resolves the exact bar window a request describes.
+     *
+     * Preloaded history is context only: it warms up indicators and supplies the
+     * first decision point, and is excluded from every reported statistic.
+     */
+    resolveWindow(request: BacktestRequest): {
+        evaluationStart: number;
+        evaluationEnd: number;
+        preloadStart: number;
+        preloadBars: number;
+        totalBars: number;
+    };
+    private execute;
+    /**
+     * Runs one parameter search.
+     *
+     * The bars are loaded once and every candidate is measured against that single
+     * array. Batches go out one per worker rather than one per candidate: the
+     * payload is a small share of a candidate's cost, so nothing is gained by
+     * splitting further, while a process per candidate would hold the same
+     * multi-megabyte array once per candidate.
+     */
+    private executeOptimize;
+    /** Stores one batch's results, keyed by the candidate index the host assigned. */
+    private recordBatch;
+    /**
+     * Reads the instrument's contract specification.
+     *
+     * Refuses rather than defaulting: a backtest sized off a guessed contract value
+     * reports confident numbers for positions that could never have been taken.
+     */
+    private contractSpec;
+    private requireInterpreter;
+    private enqueue;
+    private drain;
+}