Data Models

This document defines canonical data models used across the KEK ecosystem.

These models describe how strategy specifications, validation outputs, simulation performance, and monitoring signals are represented and stored. They are intended for developers, quantitative users, and integrations.

KEK's source of truth is persisted in a time-series database optimized for strategy evaluation, performance metrics, and continuous monitoring. Specific table names and storage choices may vary by deployment.

What this covers

Core entity types used across KEK
Typical API payload shapes
Key relationships between strategy, validation, simulation, and monitoring

Model relationships (overview)

At a high level:

A User owns one or more StrategyRecords
A StrategyRecord references a StrategySpec (machine-readable JSON)
Validation generates BacktestRuns and OptimizationRuns
Simulation generates PaperTradeRuns, Orders, Fills, and PerformanceSnapshots
Monitoring produces DriftEvents and RefinementJobs that can trigger new variants

Core Types

User

export interface User {
  id: string;                 // internal user id
  walletAddress: string;      // public wallet address (non-custodial identity)
  createdAt: string;          // ISO timestamp
  profile?: {
    username?: string;
    avatarUrl?: string;
  };
  settings?: UserSettings;
}

export interface UserSettings {
  persona?: "retail" | "quant" | "investor";
  riskDefaults?: RiskDefaults;
  notifications?: {
    enabled: boolean;
    channels?: Array<"email" | "telegram" | "in_app">;
  };
}

export interface RiskDefaults {
  maxLeverage?: number;
  maxPositionPct?: number;
  maxTotalExposurePct?: number;
  maxDrawdownPct?: number;
}

StrategyRecord (stored entity)

A stored record that ties a strategy spec to ownership, lifecycle state, and provenance.

export interface StrategyRecord {
  id: string;
  ownerUserId: string;

  name: string;
  version: string;

  status: StrategyStatus;     // lifecycle state in KEK
  createdAt: string;
  updatedAt: string;

  // The canonical machine-readable spec (see Strategy Specification doc)
  spec: StrategySpec;

  // Optional: variants generated from the same base spec
  variants?: StrategyVariantRecord[];

  // Optional: sharing / visibility controls
  visibility?: "private" | "shared" | "public";

  metadata?: {
    tags?: string[];
    notes?: string;
    generatedBy?: "kek_mix" | "user" | "import";
  };
}

export type StrategyStatus =
  | "draft"
  | "generated"
  | "validated"
  | "paper_trading"
  | "monitoring"
  | "ready_for_deploy"
  | "archived";

StrategySpec (machine-readable)

The machine-readable strategy JSON. This is included here as a type reference; the canonical spec is documented in Strategy Specification.

export interface StrategySpec {
  id: string;
  name: string;
  version: string;

  universe: {
    assets: string[];
    quote?: string;
    timeframe: string;                 // e.g. "1h", "4h", "1d"
    venue?: string;                    // e.g. "orderly"
    marketType?: "spot" | "perp";
  };

  indicators: Record<string, IndicatorSpec>;

  signals: {
    entry: ConditionSpec[];
    exit: ConditionSpec[];
  };

  sizing: SizingSpec;
  risk: RiskSpec;
  execution: ExecutionSpec;

  variants?: Array<{
    id: string;
    overrides: Record<string, unknown>;
  }>;

  metadata?: Record<string, unknown>;
}

export interface IndicatorSpec {
  type: string;                        // e.g. "rsi", "ema", "sma"
  inputs: Record<string, unknown>;
}

export interface ConditionSpec {
  when: string;                        // e.g. "crosses_above", "lt", "and"
  left?: string;
  right?: string;
  value?: number;
  conditions?: ConditionSpec[];        // for boolean compositions
}

export interface SizingSpec {
  mode: "percent_equity" | "fixed_notional" | "volatility_target";
  value: number;
  maxPositions?: number;
}

export interface RiskSpec {
  maxLeverage?: number;
  maxPositionPct?: number;
  maxTotalExposurePct?: number;
  maxDrawdownPct?: number;

  stopLoss?: { type: "percent" | "atr" | "price"; value: number };
  takeProfit?: { type: "percent" | "atr" | "price"; value: number };
}

export interface ExecutionSpec {
  mode: "paper" | "live";
  allowedVenues?: string[];
  maxOrdersPerHour?: number;
  slippageModel?: "basic" | "conservative" | "custom";
}

Validation Models

BacktestRun

Represents one historical simulation run of a given strategy spec (or variant).

export interface BacktestRun {
  id: string;
  strategyRecordId: string;
  variantId?: string;

  createdAt: string;
  timeframe: {
    start: string;   // ISO timestamp
    end: string;     // ISO timestamp
    candleInterval: string;  // e.g. "1h"
  };

  dataset: {
    provider?: string;       // e.g. "binance", "pyth", etc.
    symbolSet: string[];     // resolved symbols used in test
  };

  results: PerformanceSummary;
  diagnostics?: {
    warnings?: string[];     // e.g. missing data segments
    notes?: string[];
  };
}

OptimizationRun

Represents a parameter search / multi-variant evaluation.

export interface OptimizationRun {
  id: string;
  strategyRecordId: string;

  createdAt: string;
  method?: "grid" | "random" | "bayesian" | "evolutionary";

  objectives: Array<"net_profit" | "drawdown" | "sharpe" | "trade_count" | "profit_factor">;

  candidatesEvaluated: number;

  bestVariants: Array<{
    variantId: string;
    score: number;
    summary: PerformanceSummary;
  }>;
}

Paper Trading Models

Paper trading simulates execution under real market conditions without deploying capital.

PaperTradeRun

export interface PaperTradeRun {
  id: string;
  strategyRecordId: string;
  variantId?: string;

  createdAt: string;
  status: "running" | "paused" | "stopped" | "completed";

  executionContext?: {
    venue?: string;
    marketType?: "spot" | "perp";
    symbols?: string[];
  };

  latestSummary?: PerformanceSummary;
}

Order + Fill (simulation)

export interface SimOrder {
  id: string;
  paperTradeRunId: string;

  symbol: string;
  side: "buy" | "sell";
  type: "market" | "limit";
  requestedQty: number;

  createdAt: string;
  status: "open" | "filled" | "cancelled" | "rejected";

  riskSnapshot?: RiskSnapshot;
}

export interface SimFill {
  id: string;
  orderId: string;

  filledQty: number;
  fillPrice: number;
  feePaid?: number;
  slippage?: number;

  executedAt: string;
}

Position (simulation)

export interface SimPosition {
  id: string;
  paperTradeRunId: string;

  symbol: string;
  side: "long" | "short";
  size: number;
  entryPrice: number;

  unrealizedPnl?: number;
  realizedPnl?: number;

  updatedAt: string;
}

Monitoring / Meta-Learning Models

PerformanceSnapshot

A periodic snapshot used for monitoring, reporting, and drift detection.

export interface PerformanceSnapshot {
  id: string;
  strategyRecordId: string;
  variantId?: string;

  period: {
    start: string;
    end: string;
  };

  summary: PerformanceSummary;
  createdAt: string;
}

DriftEvent

Represents detected performance degradation or behavior change.

export interface DriftEvent {
  id: string;
  strategyRecordId: string;
  variantId?: string;

  detectedAt: string;

  type: "performance_drop" | "regime_mismatch" | "execution_change" | "data_shift";
  severity: "low" | "medium" | "high";

  description: string;

  evidence?: {
    metric?: keyof PerformanceSummary;
    baseline?: number;
    observed?: number;
    threshold?: number;
  };

  recommendedAction?: "review" | "reoptimize" | "pause_simulation";
}

RefinementJob

A record of a refinement cycle request (re-optimization, new variants, or strategy adjustment).

export interface RefinementJob {
  id: string;
  strategyRecordId: string;

  createdAt: string;
  status: "queued" | "running" | "completed" | "failed";

  reason: "drift_detected" | "user_request" | "scheduled_review";

  outputs?: {
    newVariantIds?: string[];
    notes?: string;
  };
}

Shared Utility Types

PerformanceSummary

export interface PerformanceSummary {
  netProfit?: number;
  returnsPct?: number;

  sharpeRatio?: number;
  maxDrawdownPct?: number;

  winRatePct?: number;
  tradeCount?: number;

  profitFactor?: number;

  // Optional: execution-aware metrics
  avgSlippage?: number;
  feesPaid?: number;
}

RiskSnapshot

export interface RiskSnapshot {
  leverage?: number;
  positionPct?: number;
  totalExposurePct?: number;
  drawdownPct?: number;
}