bytelyst/learning_ai_invt_trdg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4802f028fa
learning_ai_invt_trdg/web/dashboard-metrics-contract.md

9.9 KiB
Raw Blame History

Dashboard Metrics Contract

This contract formalizes each surface-level metric on the dashboard so that engineers and future agents can recompute and validate them without inspecting implementation details. Each definition below derives directly from the authoritative Dashboard Metric Validation Table you provided.

System Status (RUNNING/DEGRADED/UNHEALTHY)

  • Metric Name: System Status (RUNNING/DEGRADED/UNHEALTHY)
  • Business Definition: Signals the operational health tier of the bot service by combining capital invariants with the trading and reconciliation loop statuses so stakeholders immediately know whether the system is fully operational.
  • Canonical Source of Truth: botState.health
  • Exact Formula: const h = botState.health; status = h.capitalInvariantViolations > 0 ? 'Unhealthy' : (!h.tradingLoopHealthy || !h.reconciliationLoopHealthy) ? 'Degraded' : 'Running'
  • Lifecycle Boundary: Considered final once the latest botState.health payload is read and evaluated; the value stays fixed until the next health payload arrives.
  • Update Frequency: Per bot health emission (each trading/reconciliation loop that pushes botState.health).
  • Confidence Level: MEDIUM

Mode (Paper/Live)

  • Metric Name: Mode (Paper / Live)
  • Business Definition: Identifies whether the dashboard-connected bot is executing in sandbox/paper-trading or live-trading environments so users know what kind of capital interaction they are viewing.
  • Canonical Source of Truth: botState.settings.executionMode
  • Exact Formula: Direct reflection (value = botState.settings.executionMode).
  • Lifecycle Boundary: Final once the latest executionMode value is received; inferred to remain unchanged until an update arrives (typically when configuration changes or a reconnect occurs).
  • Update Frequency: Per bot loop (whenever botState.settings is refreshed during the websocket heartbeat).
  • Confidence Level: HIGH

Allocated Capital

  • Metric Name: Allocated Capital
  • Business Definition: Total capital that has been committed across every enabled profile, representing the supply ceiling before new exposures are permitted.
  • Canonical Source of Truth: capital_ledgers.allocated_capital
  • Exact Formula: SUM(allocated_capital) across every enabled profile row in capital_ledgers.
  • Lifecycle Boundary: Final once the latest capital ledger snapshot (reconciliation) completes; remains until the next ledger write.
  • Update Frequency: Per reconciliation (capital ledger refreshes when allocations change or on ledger rebuild).
  • Confidence Level: HIGH

Capital Used

  • Metric Name: Capital Used
  • Business Definition: Tracks working capital that is currently reserved either for pending exchange orders or for filled positions, reflecting locked-up funds.
  • Canonical Source of Truth: capital_ledgers.reserved_for_orders + capital_ledgers.reserved_for_positions
  • Exact Formula: SELECT SUM(reserved_for_orders + reserved_for_positions) FROM capital_ledgers.
  • Lifecycle Boundary: Final when the reconciliation cycle records the latest reservations; usage may change after order fills or cancellations update the ledger.
  • Update Frequency: Per reconciliation cycle (order/reservation adjustments persisted to capital_ledgers).
  • Confidence Level: HIGH

Remaining Capital

  • Metric Name: Remaining Capital
  • Business Definition: Represents the liquidity still available for new trades after subtracting both order reservations and filled exposure, while including realized profits/losses.
  • Canonical Source of Truth: Derived from the capital ledger invariant: allocated capital, current reservations, and realized P&L.
  • Exact Formula: SELECT SUM(allocated_capital - reserved_for_orders - reserved_for_positions + realized_pnl) FROM capital_ledgers.
  • Lifecycle Boundary: Final once the reconciliation writes the invariant for the latest ledger state; recalculated whenever capital reservation or realized P&L changes.
  • Update Frequency: Per reconciliation cycle (ledger snapshot update).
  • Confidence Level: HIGH

Realized P&L

  • Metric Name: Realized P&L
  • Business Definition: Cumulative profit and loss from exits that have already settled, indicating completed trade performance.
  • Canonical Source of Truth: capital_ledgers.realized_pnl (backed by trade_history).
  • Exact Formula: SUM(realized_pnl) from trade_history rows where state = 'EXIT_FILLED' (or using the mirrored ledger column).
  • Lifecycle Boundary: Final at the moment an EXIT_FILLED record is persisted; accumulates with each valid exit.
  • Update Frequency: Per trade exit (each reconciliation that records a filled exit).
  • Confidence Level: MEDIUM

Net P&L

  • Metric Name: Net P&L
  • Business Definition: Aggregates both realized gains/losses and current unrealized exposure so operators can assess total equity change in real time.
  • Canonical Source of Truth: Combination of capital_ledgers.realized_pnl and live botState.positions (unrealized data).
  • Exact Formula: realized_pnl (capital_ledgers.realized_pnl snapshot) + SUM(unrealizedPnl from botState.positions).
  • Lifecycle Boundary: Final when the latest ledger snapshot and position updates are combined; refreshed on every position update or reconciliation.
  • Update Frequency: Real-time (whenever position unrealized P&L or ledger realized P&L changes).
  • Confidence Level: MEDIUM

Win Rate (7D)

  • Metric Name: Win Rate (7D)
  • Business Definition: Percentage of profitable exits in the trailing 7-day window, helping teams evaluate recent execution effectiveness.
  • Canonical Source of Truth: trade_history (filtered to exits within the last 7 days).
  • Exact Formula: SUM(CASE WHEN pnl > 0 THEN 1 ELSE 0 END)::float / COUNT(*) over trade_history rows where state = 'EXIT_FILLED' AND ts >= NOW() - INTERVAL '7 days'.
  • Lifecycle Boundary: Final once a trade exit row is persisted; each exit event extends/updates the 7-day window.
  • Update Frequency: Per trade exit (or each time the 7-day slice is recalculated during reconciliation).
  • Confidence Level: MEDIUM

Trade Count

  • Metric Name: Trade Count
  • Business Definition: Total number of uniquely identified trades that have passed through the lifecycle pipeline, independent of wins or losses.
  • Canonical Source of Truth: trade_lifecycle
  • Exact Formula: SELECT COUNT(DISTINCT trade_id) FROM trade_lifecycle.
  • Lifecycle Boundary: Final once the lifecycle record for a trade is written; duplicates are deduped via trade_id.
  • Update Frequency: Per trade lifecycle update (entries written as trades progress).
  • Confidence Level: LOW

P&L Duration

  • Metric Name: P&L Duration
  • Business Definition: Timespan between the earliest entry and latest exit in the ledger, serving as a sanity check on the historical trade window that contributes to displayed P&L.
  • Canonical Source of Truth: trade_history timestamps (entry_ts, exit_ts).
  • Exact Formula: MAX(exit_ts) - MIN(entry_ts) over trade_history rows considered in the dashboard (typically the global scope used for realized P&L).
  • Lifecycle Boundary: Final when the latest exit timestamp is committed; extends as newer trade history data arrives.
  • Update Frequency: Per reconciliation (when trade history is aggregated for metrics).
  • Confidence Level: LOW

Uptime

  • Metric Name: Uptime
  • Business Definition: Measures how long the bot service has been running without a restart so users can correlate stability with performance.
  • Canonical Source of Truth: botState.uptime
  • Exact Formula: Direct reflection of botState.uptime (milliseconds since last restart or health reset).
  • Lifecycle Boundary: Final upon receipt of the latest uptime value; resets when the bot restarts or websocket reinitializes.
  • Update Frequency: Real-time (updated as the bot increments its uptime counter).
  • Confidence Level: MEDIUM

Broker Balance (Alpaca)

  • Metric Name: Broker Balance (Alpaca)
  • Business Definition: The actual cash and buying power reported by the Alpaca brokerage account. This is the source of truth for real-world liquidity and may differ from the bot’s internal allocated capital ledger.
  • Canonical Source of Truth: botState.accountSnapshot (from Alpaca API GET /v2/account).
  • Exact Formula: Display buying_power and cash fields directly from the snapshot.
  • Lifecycle Boundary: Updates whenever the bot polls Alpaca (typically on order fills or periodic syncs).
  • Update Frequency: Real-time (approx. every minute or on event).
  • Confidence Level: HIGH (Third-party authoritative).

Capital Coverage Status (Per Profile)

  • Metric Name: Capital Coverage (LP Health)
  • Business Definition: A health check comparison between a profile’s internal allocated_capital and the broker’s actual buying_power.
  • Display:
    • Covered (Green): allocated_capital <= buying_power
    • Insufficient Funds (Orange/Red): allocated_capital > buying_power
  • Canonical Source of Truth: Comparison of botState.accountSnapshot.buying_power vs profile.allocated_capital.
  • Exact Formula: IF (allocated <= buying_power) THEN 'Covered' ELSE 'Insufficient'
  • Lifecycle Boundary: Re-evaluated on every state update.
  • Update Frequency: Real-time.
  • Confidence Level: HIGH

Recent Order Failures

  • Metric Name: Recent Order Failures
  • Business Definition: A list of recent order rejections from the broker (e.g., "insufficient buying power", "pattern day trader protection").
  • Canonical Source of Truth: botState.orderFailures (in-memory circular buffer, capped at 30).
  • Exact Formula: Display list of {timestamp, symbol, reason}.
  • Lifecycle Boundary: Ephemeral; preserved in memory while bot is running. Cleared on restart.
  • Update Frequency: Event-driven (emitted immediately upon rejection).
  • Confidence Level: HIGH