Skip to content

FAQ

This FAQ is sourced from recurring themes in docs feedback submissions and docs-related support questions.

For a structured index by symptom area, start with Troubleshooting.

Strategy authoring

Which hook should I implement: propose_weight or build_target_profile?

Use propose_weight(state) for day-by-day logic. Use build_target_profile(...) for vectorized, window-level logic.

See: Minimal Strategy Examples.

Do I need to implement both hooks?

No. Implement one intent path. The framework will enforce the same allocation invariants either way.

Why can’t I override compute_weights directly?

compute_weights is framework-owned and sealed to preserve invariant safety, lock semantics, and consistent runtime behavior.

See: Framework Boundary.

CLI and outputs

Use decide-daily when StackSats should emit a validated, execution-ready decision payload for an external AI agent or brokerage workflow. Use run-daily only when you intentionally want StackSats to submit through a configured execution adapter after generating that same decision.

When should I use stacksats serve agent-api?

Use the hosted agent API when your external agent needs a stable remote /v1 service instead of a local Python or CLI integration. The service exposes decision generation plus receipt ingestion and reconciliation on the same surface.

Where are artifacts written?

Backtest and export artifacts are written under:

output/<strategy_id>/<version>/<run_id>/

See: CLI Commands.

Why does export require --start-date and --end-date?

Export requires explicit date bounds to avoid accidental implicit ranges and to make outputs reproducible.

What files should I expect after a run?

Common files:

  • backtest: backtest_result.json, metrics.json, plot .svg files
  • export: weights.csv, timeseries_schema.md, artifacts.json

See: Backtest Runtime and WeightTimeSeries.

Migration and compatibility

My code used compute_weights_shared or a hardcoded backtest end. What do I use now?

Use explicit replacements from Migration Guide:

  • compute_weights_shared(...) -> compute_weights_with_features(..., features_df=...)
  • backtest end constant/override -> get_backtest_end() (canonical default is 2025-12-31)

My code used model_development.softmax or strategy.export_weights(...). What now?

Both compatibility APIs were removed:

  • stacksats.model_development.softmax(...) -> stacksats.model_development.helpers.softmax(...)
  • BaseStrategy.export_weights(...) -> BaseStrategy.export(...)

See: Migration Guide.

Did load_data(...) behavior change?

Yes. stacksats.load_data(...) now follows strict BTCDataProvider source-only semantics:

  • no synthetic "today" row
  • no historical gap filling
  • no MVRV fallback substitution
  • feature warmup history is retained by default (rows before backtest_start are included for feature computation)

The canonical source dataset is long-format merged_metrics*.parquet (see Merged Metrics Parquet Schema and BRK Data Source). Runtime commands read a derived BRK-wide parquet via STACKSATS_ANALYTICS_PARQUET, the managed default under ~/.stacksats/data/bitcoin_analytics.parquet, or the legacy local fallback ./bitcoin_analytics.parquet; for custom DataFrames use StrategyRunner.from_dataframe(df, column_map=...) or ColumnMapDataProvider. Treat the DataFrame path as an advanced integration option, not the default first-run workflow. Use end_date=... when you need an explicit end bound.

If you need a lazy integration point before the final execution boundary, use BTCDataProvider.load_lazy(...) or ColumnMapDataProvider.load_lazy(...). Strategy hooks themselves still receive eager pl.DataFrame inputs.

Does StackSats support the BRK project or Rust crate directly?

StackSats explicitly supports the Bitcoin Research Kit (BRK) project at the project and data-workflow level. That means StackSats documents BRK as the upstream project, links to the official BRK project surfaces, and supports BRK-derived canonical data workflows built around merged_metrics*.parquet.

That does not mean StackSats is a Rust wrapper, a BRK crate dependency contract, or a guarantee of crate-level API compatibility. The stable support promise remains the StackSats Python API, documented CLI subset, and documented hosted HTTP service.

Official BRK links:

Which modules are stable public API?

Use top-level stacksats exports, documented artifact payloads, the documented CLI subset, and the documented hosted /v1 HTTP service. Generated module pages are reference material, not a promise that the module import path is stable.

For canonical merged_metrics*.parquet exploration, use the stable public top-level exports open_merged_metrics() and load_metric_catalog() plus EDA Quickstart.

See: API Reference and Stability Policy.

Are stacksats-plot-mvrv and stacksats-plot-weights part of the stable CLI?

No. They are documented helper console scripts for plotting workflows, but the frozen stable 1.x CLI contract is the documented stacksats demo, stacksats data, stacksats strategy, and stacksats serve agent-api surface in the stability policy.

Treat the helper scripts as convenience entry points with optional extras:

  • stacksats-plot-mvrv requires stacksats[viz]
  • stacksats-plot-weights requires both stacksats[viz] and stacksats[deploy]

Does StackSats talk directly to my broker in hosted mode?

No. The hosted agent API remains broker-agnostic. It generates decisions and accepts append-only execution receipts from your external agent; it does not poll brokerage state or manage broker credentials.

Docs feedback workflow

How is this FAQ updated?

Maintainers periodically review docs feedback issues and fold recurring questions into this page.

How should I report a docs gap?

Open an issue using the docs feedback template and include:

  • page URL
  • what you were trying to do
  • what was unclear
  • suggested improvement

Feedback