stacksats.strategy_types

stacksats.strategy_types

Strategy-first domain types for StackSats.

BaseStrategy

Bases: ABC

Base class for strategy-first runtime behavior.

build_signals(ctx: StrategyContext, features_df: pd.DataFrame) -> dict[str, pd.Series]

Hook for user-defined signal formulas.

build_target_profile(ctx: StrategyContext, features_df: pd.DataFrame, signals: dict[str, pd.Series]) -> TargetProfile | pd.Series

Return daily preference scores or absolute target profile.

Default behavior vectorizes propose_weight over the active window.

compute_weights(ctx: StrategyContext) -> pd.Series

Framework-owned orchestration from hooks -> final weights.

propose_weight(state: DayState) -> float

Optional per-day weight proposal hook.

transform_features(ctx: StrategyContext) -> pd.DataFrame

Hook for user-defined feature transforms on the active window.

validate_weights(weights: pd.Series, ctx: StrategyContext) -> None

Optional strategy-specific weight checks.

DayState(current_date: pd.Timestamp, features: pd.Series, remaining_budget: float, day_index: int, total_days: int, uniform_weight: float) dataclass

Per-day user hook input for proposing today's weight.

StrategyArtifactSet(strategy_id: str, version: str, config_hash: str, run_id: str, output_dir: str, files: dict[str, str] = dict()) dataclass

Artifact bundle with strategy provenance metadata.

StrategyContext(features_df: pd.DataFrame, start_date: pd.Timestamp, end_date: pd.Timestamp, current_date: pd.Timestamp, locked_weights: np.ndarray | None = None, btc_price_col: str = 'PriceUSD_coinmetrics', mvrv_col: str = 'CapMVRVCur') dataclass

Normalized context passed into strategy computation.

TargetProfile(values: pd.Series, mode: Literal['preference', 'absolute'] = 'preference') dataclass

User-provided target profile or daily preference score.

strategy_hook_status(strategy_cls: type[BaseStrategy]) -> tuple[bool, bool]

Return whether strategy overrides propose/profile intent hooks.

validate_strategy_contract(strategy: BaseStrategy) -> tuple[bool, bool]

Enforce framework-owned compute kernel boundaries for strategies.