stacksats.api

stacksats.api

Result types for strategy lifecycle operations.

BacktestResult(spd_table: pl.DataFrame, exp_decay_percentile: float, win_rate: float, score: float, uniform_exp_decay_percentile: float = 0.0, strategy_id: str = 'unknown', strategy_version: str = '0.0.0', config_hash: str = '', run_id: str = '') dataclass

Structured backtest result.

exp_decay_multiple_vs_uniform: float | None property

Return dynamic-vs-uniform exp-decay ratio, or None when undefined.

animate(output_dir: str = 'output', *, fps: int = 20, width: int = 1920, height: int = 1080, max_frames: int = 240, filename: str = 'strategy_vs_uniform_hd.gif', window_mode: str = 'rolling', source_backtest_json: str | Path | None = None) -> dict[str, str]

Render an animated strategy-vs-uniform GIF and write a manifest JSON.

plot(output_dir: str = 'output') -> dict[str, str]

Export backtest metrics to JSON. Returns path to metrics file.

summary() -> str

Return a concise text summary of key metrics.

to_dataframe() -> pl.DataFrame

Return the SPD table.

to_json(path: str | Path | None = None) -> dict

Serialize result to a JSON-compatible dictionary.

DailyDecisionResult(status: str, strategy_id: str, strategy_version: str, run_date: str, decision_key: str, idempotency_hit: bool, forced_rerun: bool, weight_today: float | None, recommended_notional_usd: float | None, recommended_quantity_btc: float | None, reference_price_usd: float | None, btc_price_col: str, state_db_path: str, artifact_path: str | None, message: str, validation_receipt_id: int | None = None, validation_passed: bool | None = None, data_hash: str = '', feature_snapshot_hash: str = '', bootstrap: bool = False) dataclass

Structured result for a daily agent-facing decision.

summary() -> str

Return concise daily decision status summary.

to_json(path: str | Path | None = None) -> dict

Serialize to a JSON-compatible dictionary.

DailyOrderReceipt(status: str, external_order_id: str | None, filled_notional_usd: float, filled_quantity_btc: float, fill_price_usd: float, metadata: dict[str, str] = dict()) dataclass

Execution receipt for a submitted daily order.

DailyOrderRequest(strategy_id: str, strategy_version: str, run_date: str, mode: str, weight_today: float, notional_usd: float, price_usd: float, quantity_btc: float, btc_price_col: str) dataclass

Execution request for a single strategy daily order.

DailyRunResult(status: str, strategy_id: str, strategy_version: str, run_date: str, run_key: str, mode: str, idempotency_hit: bool, forced_rerun: bool, weight_today: float | None, order_notional_usd: float | None, btc_quantity: float | None, price_usd: float | None, adapter_name: str, state_db_path: str, artifact_path: str | None, message: str, order_receipt: DailyOrderReceipt | None = None, bootstrap: bool = False, validation_receipt_id: int | None = None, validation_passed: bool | None = None, data_hash: str = '', feature_snapshot_hash: str = '') dataclass

Structured result for a daily strategy execution.

summary() -> str

Return concise daily run status summary.

to_json(path: str | Path | None = None) -> dict

Serialize to a JSON-compatible dictionary.

ExecutionReceiptEvent(decision_key: str, event_id: str, event_type: str, event_time: str, broker_name: str | None = None, broker_account_ref: str | None = None, external_order_id: str | None = None, filled_notional_usd: float | None = None, filled_quantity_btc: float | None = None, fill_price_usd: float | None = None, message: str | None = None, metadata: dict[str, object] = dict()) dataclass

Append-only execution receipt event reported by an external agent.

to_json() -> dict

Serialize to a JSON-compatible dictionary.

ExecutionReceiptHistoryResult(decision_key: str, receipts: list[ExecutionReceiptEvent]) dataclass

Stored append-only execution receipt history for a decision.

to_json() -> dict

Serialize to a JSON-compatible dictionary.

ExecutionStatusResult(decision_key: str, strategy_id: str, run_date: str, decision_status: str, execution_status: str, reconciliation_status: str, recommended_notional_usd: float | None, recommended_quantity_btc: float | None, filled_notional_usd: float, filled_quantity_btc: float, average_fill_price_usd: float | None, receipt_count: int, latest_event_type: str | None, latest_event_time: str | None, message: str) dataclass

Current execution lifecycle and reconciliation summary for a decision.

summary() -> str

Return concise execution lifecycle summary.

to_json() -> dict

Serialize to a JSON-compatible dictionary.

ValidationResult(passed: bool, forward_leakage_ok: bool, weight_constraints_ok: bool, win_rate: float, win_rate_ok: bool, messages: list[str], strategy_id: str = '', min_win_rate: float = 50.0, diagnostics: dict[str, object] = dict()) dataclass

Structured validation result for a strategy.

summary() -> str

Return a concise validation summary string.