---
title: Runtime Objects Overview
description: Overview of strategy, FeatureTimeSeries, and WeightTimeSeries runtime object model.
---

# Runtime Objects Overview

StackSats has three fundamental runtime objects:

- **FeatureTimeSeries**: validated input to a strategy (Polars-backed feature time series with schema and time-series validation).
- **BaseStrategy**: user intent and logic (hooks, identity, allocation intent).
- **WeightTimeSeries** / **WeightTimeSeriesBatch**: validated output of a strategy (weights, prices, metadata; framework invariants per [Framework](framework.md)).

!!! tip "Input → Strategy → Output"
    **FeatureTimeSeries** is the input (features, schema, no forward-looking). **BaseStrategy** consumes it and produces allocation intent. **WeightTimeSeries** is the output object that enforces budget, daily bounds, and validation guards.

## Fundamental objects

| Object | Role | Validation |
|--------|------|------------|
| **FeatureTimeSeries** | Input to strategy | Schema (required columns), sorted unique dates, optional no-future-data and finite-numeric checks. |
| **BaseStrategy** | Strategy logic | User-defined hooks; framework runs the allocation kernel. |
| **WeightTimeSeries** / **WeightTimeSeriesBatch** | Output of strategy | Framework invariants: weight sum = 1, min/max daily weight, no forward-looking at export, NaN/inf/range guards. See [Framework](framework.md). |

## Read in this order

1. [Strategy Object](reference/strategy-object.md)
2. [FeatureTimeSeries](reference/feature-timeseries.md)
3. [WeightTimeSeries](reference/strategy-timeseries.md)
4. [WeightTimeSeries Schema](reference/strategy-timeseries-schema.md)

## Why this split exists

- **FeatureTimeSeries** defines validated feature input (schema and time-series checks).
- **BaseStrategy** defines user-owned hooks and metadata.
- **WeightTimeSeries** defines framework-validated outputs and export contracts.
- Schema docs are generated from code and kept synchronized in CI.

## Comprehensive list of library objects

All public types and functions below are exported from the top-level `stacksats` package (see `stacksats/__init__.py`).

### Primary objects

| Object | Description |
|--------|-------------|
| `FeatureTimeSeries` | Validated input to strategy: Polars DataFrame with `date` column; feature columns; schema and time-series validation. Build via `from_dataframe(pl.DataFrame)`. |
| `BaseStrategy` | Abstract base class for defining strategy logic (hooks, identity, intent). |
| `WeightTimeSeries` | Single-window validated strategy output (weights, prices, metadata). Uses Polars internally; `to_dataframe()` returns `pl.DataFrame`; `from_dataframe` accepts Polars only. |
| `WeightTimeSeriesBatch` | Multi-window container of `WeightTimeSeries` (e.g. from export or backtest). `to_dataframe()` returns `pl.DataFrame`; `from_flat_dataframe` accepts Polars only. |

### Strategy input and context

| Object | Description |
|--------|-------------|
| `StrategyContext` | Input passed into strategy computation: `features` (`FeatureTimeSeries`), date range, `current_date`, optional `locked_weights`, column names. Build from a Polars DataFrame with **`StrategyContext.from_features_df(...)`**. |

### Results

| Object | Description |
|--------|-------------|
| `BacktestResult` | Result of a backtest run. |
| `ValidationResult` | Result of strategy validation. |
| `DailyRunResult` | Result of a single daily run. |
| `DailyOrderRequest` | Request for a daily order. |
| `DailyOrderReceipt` | Receipt for a daily order. |
| `StrategyRunResult` | Result of a strategy run. |

### Config

| Object | Description |
|--------|-------------|
| `BacktestConfig` | Backtest options (dates, labels, etc.). |
| `ExportConfig` | Export options for strategy outputs. |
| `RunDailyConfig` | Config for daily run. |
| `ValidationConfig` | Config for validation. |

### Strategy metadata and contract

| Object | Description |
|--------|-------------|
| `StrategyMetadata` | Strategy identity (id, version, description). |
| `StrategySpec` | Full public contract (metadata, intent_mode, params, required features). |
| `StrategySeriesMetadata` | Metadata on a `WeightTimeSeries` (strategy_id, version, run_id, window, etc.). |
| `StrategyArtifactSet` | Set of artifacts produced by a strategy. |

### Allocation and intent

| Object | Description |
|--------|-------------|
| `TargetProfile` | Target allocation profile returned by `build_target_profile`. |
| `DayState` | Per-day state used in allocation. |

### WeightTimeSeries schema

| Object | Description |
|--------|-------------|
| `ColumnSpec` | Spec for a column in the WeightTimeSeries schema. |

### Data and loading

| Object | Description |
|--------|-------------|
| `ColumnMapDataProvider` | Data provider that wraps a DataFrame and column map. Use `.load()` for an eager `pl.DataFrame` or `.load_lazy()` for a `pl.LazyFrame` before the final execution boundary. |
| `ColumnMapError` | Error raised when column mapping fails. |

### Example strategies

Canonical built-in strategy documentation (behavior, required columns, intent mode, and tuning defaults):

- [Strategies](reference/strategies.md)

### Runners and helpers

| Object | Description |
|--------|-------------|
| `StrategyRunner` | Orchestrates backtest, export, run, and validation. |
| `load_strategy` | Load a strategy (e.g. from JSON). |
| `load_data` | Load an eager runtime BRK-wide parquet frame (prelude helper). Runtime ingestion is lazy-first internally, but this helper returns a collected `pl.DataFrame`. Runtime resolution follows `STACKSATS_ANALYTICS_PARQUET`, managed default `~/.stacksats/data/bitcoin_analytics.parquet`, then legacy local fallback `./bitcoin_analytics.parquet`. Canonical source dataset is `merged_metrics*.parquet`; see [Merged Metrics Parquet Schema](reference/merged-metrics-parquet-schema.md). Use `ColumnMapDataProvider` or `StrategyRunner.from_dataframe` for custom DataFrames. |
| `precompute_features` | Precompute the built-in model feature set as an eager `pl.DataFrame`. Framework-owned providers keep a lazy-first path internally, then use a single vectorized enrichment boundary for rolling-rank features before final collection. |

Profile-mode strategies may also opt into lazy execution with `StrategyLazyContext`, `transform_features_lazy(...)`, `build_signal_exprs(...)`, and `build_target_profile_lazy(...)`. Eager hooks remain the default and `propose_weight(...)` stays eager-only.

### Removed aliases

These names are no longer part of the supported API:

- `TimeSeries` -> `WeightTimeSeries`
- `TimeSeriesBatch` -> `WeightTimeSeriesBatch`
- `StrategyTimeSeries` -> `WeightTimeSeries`
- `StrategyTimeSeriesBatch` -> `WeightTimeSeriesBatch`

## API pointers

- [API Index](reference/api/index.md)
- [strategy_types module](reference/api/strategy-types.md)
- [runner module](reference/api/runner.md)
