Metadata-Version: 2.4
Name: stacksats
Version: 0.4.0
Summary: Bitcoin DCA model development and backtesting toolkit
Author: StackSats Contributors
Maintainer-email: StackSats Maintainers <team@hypertrial.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hypertrial/stacksats
Project-URL: Repository, https://github.com/hypertrial/stacksats
Project-URL: Source, https://github.com/hypertrial/stacksats
Project-URL: Documentation, https://hypertrial.github.io/stacksats/
Project-URL: Issues, https://github.com/hypertrial/stacksats/issues
Project-URL: Changelog, https://github.com/hypertrial/stacksats/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/hypertrial/stacksats/security/policy
Keywords: bitcoin,dca,backtesting,quant,crypto
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas==3.0.0
Requires-Dist: numpy==2.4.2
Requires-Dist: scipy==1.17.0
Requires-Dist: requests==2.32.5
Requires-Dist: matplotlib==3.10.8
Requires-Dist: seaborn==0.13.2
Requires-Dist: tenacity==9.1.4
Provides-Extra: deploy
Requires-Dist: psycopg2-binary==2.9.11; extra == "deploy"
Requires-Dist: python-dotenv==1.2.1; extra == "deploy"
Provides-Extra: dev
Requires-Dist: pytest==9.0.2; extra == "dev"
Requires-Dist: pytest-bdd==8.1.0; extra == "dev"
Requires-Dist: pytest-cov==7.0.0; extra == "dev"
Requires-Dist: pytest-mock==3.15.1; extra == "dev"
Requires-Dist: pytest-benchmark==5.2.3; extra == "dev"
Requires-Dist: pytest-xdist==3.8.0; extra == "dev"
Requires-Dist: responses==0.25.8; extra == "dev"
Requires-Dist: freezegun==1.5.5; extra == "dev"
Requires-Dist: hypothesis==6.151.6; extra == "dev"
Requires-Dist: ruff==0.15.0; extra == "dev"
Requires-Dist: vulture==2.14; extra == "dev"
Requires-Dist: mkdocs>=1.6.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.28.0; extra == "dev"
Requires-Dist: marimo==0.19.11; extra == "dev"
Requires-Dist: codespell>=2.3.0; extra == "dev"
Requires-Dist: pymarkdownlnt>=0.9.0; extra == "dev"
Dynamic: license-file

# StackSats

![StackSats Logo](https://raw.githubusercontent.com/hypertrial/stacksats/main/docs/assets/stacking-sats-logo.svg)

[![PyPI version](https://img.shields.io/pypi/v/stacksats.svg)](https://pypi.org/project/stacksats/)
[![Python versions](https://img.shields.io/pypi/pyversions/stacksats.svg)](https://pypi.org/project/stacksats/)
[![Package Check](https://github.com/hypertrial/stacksats/actions/workflows/package-check.yml/badge.svg)](https://github.com/hypertrial/stacksats/actions/workflows/package-check.yml)
[![License: MIT](https://img.shields.io/github/license/hypertrial/stacksats)](LICENSE)

StackSats, developed by [Hypertrial](https://www.hypertrial.ai), is a Python package for strategy-first Bitcoin dollar cost averaging (DCA) research and execution.

Learn more at [www.stackingsats.org](https://www.stackingsats.org).

## Start Here

Start with the hosted docs: <https://hypertrial.github.io/stacksats/>.

Local docs entry points:

- [`docs/index.md`](docs/index.md) for the full map
- [`docs/start/quickstart.md`](docs/start/quickstart.md) for five-minute setup
- [`docs/tasks.md`](docs/tasks.md) for task-first workflows
- [`docs/start/first-strategy-run.md`](docs/start/first-strategy-run.md) for a custom strategy walkthrough
- [`docs/start/minimal-strategy-examples.md`](docs/start/minimal-strategy-examples.md) for copyable minimal strategy templates
- [`docs/commands.md`](docs/commands.md) for canonical CLI command reference
- [`docs/migration.md`](docs/migration.md) for old-to-new breaking-change mappings
- [`docs/faq.md`](docs/faq.md) for recurring docs and integration questions
- [`docs/framework.md`](docs/framework.md) for the framework contract

## Framework Principles

- The framework owns budget math, iteration, feasibility clipping, and lock semantics.
- Users own features, signals, hyperparameters, and daily intent.
- Strategy hooks support either day-level intent (`propose_weight(state)`) or batch intent (`build_target_profile(...)`).
- The same sealed allocation kernel runs in local, backtest, and production.

See [`docs/framework.md`](docs/framework.md) for the canonical contract.

## Installation

```bash
pip install stacksats
```

For local development:

```bash
pip install -e .
pip install -r requirements-dev.txt
```

Optional deploy extras:

```bash
pip install "stacksats[deploy]"
```

## Quick Start

Run the packaged example strategy:

```bash
python -m stacksats.strategies.model_example
```

Artifacts are written under:

```text
output/<strategy_id>/<version>/<run_id>/
```

For full lifecycle commands (`validate`, `backtest`, `export`), see [`docs/commands.md`](docs/commands.md).
For task-first workflows, see [`docs/tasks.md`](docs/tasks.md).
For upgrades, see [`docs/migration.md`](docs/migration.md).
For a custom strategy template, see [`docs/start/first-strategy-run.md`](docs/start/first-strategy-run.md).

Export requires explicit date bounds:

```bash
stacksats strategy export \
  --strategy stacksats.strategies.model_example:ExampleMVRVStrategy \
  --start-date 2025-12-01 \
  --end-date 2027-12-31 \
  --output-dir output
```

## Public API

Top-level exports:

- `BaseStrategy`, `StrategyContext`, `DayState`, `TargetProfile`
- `BacktestConfig`, `ValidationConfig`, `ExportConfig`
- `StrategyArtifactSet`
- `StrategyTimeSeries`, `StrategyTimeSeriesBatch`
- `BacktestResult`, `ValidationResult`
- `load_strategy()`, `load_data()`, `precompute_features()`
- `MVRVStrategy`

## Development

```bash
pytest tests/ -v
ruff check .
bash scripts/check_docs_refs.sh
```

For command examples using the packaged strategy template, see `docs/commands.md`.
