stacksats 0.1.0__tar.gz

stacksats-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hypertrial
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stacksats-0.1.0/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: stacksats
+Version: 0.1.0
+Summary: Bitcoin DCA model development, backtesting, and Modal deployment toolkit
+Author: StackSats Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/stacksats/stacksats
+Project-URL: Repository, https://github.com/stacksats/stacksats
+Project-URL: Documentation, https://github.com/stacksats/stacksats/tree/main/docs
+Keywords: bitcoin,dca,backtesting,quant,crypto
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: seaborn>=0.12.0
+Provides-Extra: deploy
+Requires-Dist: modal>=0.52.0; extra == "deploy"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "deploy"
+Requires-Dist: fastapi>=0.104.0; extra == "deploy"
+Requires-Dist: python-dotenv>=1.0.0; extra == "deploy"
+Requires-Dist: tenacity>=8.2.0; extra == "deploy"
+Requires-Dist: pyarrow>=13.0.0; extra == "deploy"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-bdd>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: freezegun>=1.2.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: vulture; extra == "dev"
+Dynamic: license-file
+
+# StackSats
+
+StackSats, developed by [Hypertrial](https://www.hypertrail.ai), is a Python package for developing and backtesting Bitcoin DCA ("stacking sats") allocation strategies.
+
+Learn more at [www.stackingsats.org](https://www.stackingsats.org)
+
+It provides:
+- A clean strategy interface (`WindowStrategy`)
+- Built-in and example strategies
+- A rolling-window backtest engine
+- Feature precomputation utilities
+- Validation checks for leakage, constraints, and win-rate
+
+## Installation
+
+Install core package for local model development:
+
+```bash
+pip install stacksats
+```
+
+For local development from source:
+
+```bash
+pip install -e .
+pip install -r requirements-dev.txt
+```
+
+Install deployment dependencies only if needed:
+
+```bash
+pip install "stacksats[deploy]"
+```
+
+## Quick Start (write your own strategy file)
+
+Create `my_strategy.py`:
+
+```python
+import numpy as np
+import pandas as pd
+
+from stacksats import run_backtest, validate_strategy
+
+
+class MyStrategy:
+    def compute_weights(
+        self,
+        features_df: pd.DataFrame,
+        start_date: pd.Timestamp,
+        end_date: pd.Timestamp,
+        current_date: pd.Timestamp,
+    ) -> pd.Series:
+        del current_date
+        window = features_df.loc[start_date:end_date]
+        if window.empty:
+            return pd.Series(dtype=float)
+
+        z = window.get("mvrv_zscore", pd.Series(0.0, index=window.index)).to_numpy()
+        ma = window.get("price_vs_ma", pd.Series(0.0, index=window.index)).to_numpy()
+        raw = np.exp((-1.2 * z) + (-0.8 * ma))
+        w = raw / raw.sum()
+        return pd.Series(w, index=window.index)
+
+
+if __name__ == "__main__":
+    strategy = MyStrategy()
+
+    validation = validate_strategy(strategy)
+    print(validation.summary())
+
+    result = run_backtest(strategy, strategy_label="my-strategy")
+    print(result.summary())
+    result.plot(output_dir="output")
+    result.to_json("output/backtest_result.json")
+```
+
+Run it directly:
+
+```bash
+python my_strategy.py
+```
+
+For a complete command reference using the included example file, see
+[`docs/commands.md`](docs/commands.md).
+
+## Public API
+
+Top-level package exports:
+
+- `run_backtest()`: Run a rolling-window backtest for any strategy
+- `validate_strategy()`: Run submission-style validation checks
+- `load_data()`: Load BTC market data (with local cache support)
+- `precompute_features()`: Build model features from BTC data
+- `load_strategy()`: Load a strategy from `module_or_path:ClassName`
+- `BacktestResult`: Result object with summary/plot/serialization helpers
+- `ValidationResult`: Structured validation output
+- `WindowStrategy`, `CallableWindowStrategy`, `MVRVStrategy`
+
+`load_data()` also supports cache controls via optional keyword args:
+- `cache_dir` (default `~/.stacksats/cache`, set to `None` to disable local cache)
+- `max_age_hours` (default `24`, refresh threshold for cached CoinMetrics CSV)
+
+## Writing a Strategy
+
+Implement `compute_weights()` with this interface:
+
+```python
+def compute_weights(
+    self,
+    features_df: pd.DataFrame,
+    start_date: pd.Timestamp,
+    end_date: pd.Timestamp,
+    current_date: pd.Timestamp,
+) -> pd.Series:
+    ...
+```
+
+Rules your strategy should satisfy:
+
+- Return a weight series indexed by dates in the selected window
+- Weights should be non-negative
+- Weights should sum to `1.0`
+- Avoid forward-looking data usage
+
+### Available Features
+
+Feature columns are generated by `precompute_features()` and typically include:
+
+- `PriceUSD_coinmetrics`
+- `price_ma`
+- `price_vs_ma`
+- `mvrv_zscore`
+- `mvrv_gradient`
+- `mvrv_percentile`
+- `mvrv_acceleration`
+- `mvrv_zone`
+- `mvrv_volatility`
+- `signal_confidence`
+
+## Built-in and Example Strategies
+
+### Built-in
+
+- `MVRVStrategy`: Default strategy from the package model.
+
+### Examples
+
+In `stacksats.strategies.examples`:
+
+- `UniformStrategy`
+- `SimpleZScoreStrategy`
+- `MomentumStrategy`
+
+These are lightweight templates for custom model development.
+
+## Backtesting
+
+Run the default built-in strategy:
+
+```bash
+stacksats-backtest
+```
+
+Run a custom strategy class from a file:
+
+```bash
+stacksats-backtest --strategy my_strategy.py:MyStrategy --start-date 2020-01-01 --end-date 2025-01-01
+```
+
+Use the Python API directly:
+
+```python
+from stacksats import MVRVStrategy, run_backtest
+
+result = run_backtest(MVRVStrategy(), strategy_label="default-mvrv")
+print(result.summary())
+```
+
+## Validation
+
+Validate built-in strategy:
+
+```bash
+stacksats-validate --start-date 2020-01-01 --end-date 2025-01-01
+```
+
+Validate a custom strategy class:
+
+```bash
+stacksats-validate --strategy my_strategy.py:MyStrategy --min-win-rate 50.0
+```
+
+## Command Line Tools
+
+Installed scripts:
+
+- `stacksats-backtest`
+- `stacksats-export`
+- `stacksats-plot-mvrv`
+- `stacksats-plot-weights`
+- `stacksats-validate`
+
+Custom-strategy flags:
+
+- `stacksats-backtest --strategy module_or_path:ClassName`
+- `stacksats-validate --strategy module_or_path:ClassName`
+- `stacksats-export --strategy module_or_path:ClassName`
+
+## Advanced: Deployment
+
+Deployment and infrastructure modules are optional:
+
+- `stacksats.export_weights`
+- `stacksats.modal_app`
+
+These require deployment extras:
+
+```bash
+pip install "stacksats[deploy]"
+```
+
+Deploy with built-in strategy:
+
+```bash
+modal deploy stacksats/modal_app.py
+```
+
+Deploy with custom strategy:
+
+```bash
+STACKSATS_STRATEGY=my_strategy.py:MyStrategy modal deploy stacksats/modal_app.py
+```
+
+## Development
+
+Run tests:
+
+```bash
+pytest tests/ -v
+```
+
+Verify documented command examples:
+
+```bash
+# Requires ./venv (for example: python -m venv venv && source venv/bin/activate && pip install -e .)
+python scripts/test_example_commands.py
+```
+
+Run lint:
+
+```bash
+ruff check .
+```
+
+Release process: see `docs/release.md`.
+
+## Contributors
+
+This project has benefited from contributions by researchers from the following universities:
+
+- Columbia University (Master of Data Science)
+- Cornell University (Master of Engineering in Management)
+- Georgia Institute of Technology (Master of Science in Analytics)
+- London School of Economics (Master of Science in Data Science)
+- University of British Columbia (Master of Data Science)
+- University of California, Davis (Master of Science in Business Analytics)
+- University of California, Irvine (Master of Data Science)
+- University of California, San Diego (Master of Quantitative Finance)

stacksats-0.1.0/README.md

@@ -0,0 +1,269 @@
+# StackSats
+
+StackSats, developed by [Hypertrial](https://www.hypertrail.ai), is a Python package for developing and backtesting Bitcoin DCA ("stacking sats") allocation strategies.
+
+Learn more at [www.stackingsats.org](https://www.stackingsats.org)
+
+It provides:
+- A clean strategy interface (`WindowStrategy`)
+- Built-in and example strategies
+- A rolling-window backtest engine
+- Feature precomputation utilities
+- Validation checks for leakage, constraints, and win-rate
+
+## Installation
+
+Install core package for local model development:
+
+```bash
+pip install stacksats
+```
+
+For local development from source:
+
+```bash
+pip install -e .
+pip install -r requirements-dev.txt
+```
+
+Install deployment dependencies only if needed:
+
+```bash
+pip install "stacksats[deploy]"
+```
+
+## Quick Start (write your own strategy file)
+
+Create `my_strategy.py`:
+
+```python
+import numpy as np
+import pandas as pd
+
+from stacksats import run_backtest, validate_strategy
+
+
+class MyStrategy:
+    def compute_weights(
+        self,
+        features_df: pd.DataFrame,
+        start_date: pd.Timestamp,
+        end_date: pd.Timestamp,
+        current_date: pd.Timestamp,
+    ) -> pd.Series:
+        del current_date
+        window = features_df.loc[start_date:end_date]
+        if window.empty:
+            return pd.Series(dtype=float)
+
+        z = window.get("mvrv_zscore", pd.Series(0.0, index=window.index)).to_numpy()
+        ma = window.get("price_vs_ma", pd.Series(0.0, index=window.index)).to_numpy()
+        raw = np.exp((-1.2 * z) + (-0.8 * ma))
+        w = raw / raw.sum()
+        return pd.Series(w, index=window.index)
+
+
+if __name__ == "__main__":
+    strategy = MyStrategy()
+
+    validation = validate_strategy(strategy)
+    print(validation.summary())
+
+    result = run_backtest(strategy, strategy_label="my-strategy")
+    print(result.summary())
+    result.plot(output_dir="output")
+    result.to_json("output/backtest_result.json")
+```
+
+Run it directly:
+
+```bash
+python my_strategy.py
+```
+
+For a complete command reference using the included example file, see
+[`docs/commands.md`](docs/commands.md).
+
+## Public API
+
+Top-level package exports:
+
+- `run_backtest()`: Run a rolling-window backtest for any strategy
+- `validate_strategy()`: Run submission-style validation checks
+- `load_data()`: Load BTC market data (with local cache support)
+- `precompute_features()`: Build model features from BTC data
+- `load_strategy()`: Load a strategy from `module_or_path:ClassName`
+- `BacktestResult`: Result object with summary/plot/serialization helpers
+- `ValidationResult`: Structured validation output
+- `WindowStrategy`, `CallableWindowStrategy`, `MVRVStrategy`
+
+`load_data()` also supports cache controls via optional keyword args:
+- `cache_dir` (default `~/.stacksats/cache`, set to `None` to disable local cache)
+- `max_age_hours` (default `24`, refresh threshold for cached CoinMetrics CSV)
+
+## Writing a Strategy
+
+Implement `compute_weights()` with this interface:
+
+```python
+def compute_weights(
+    self,
+    features_df: pd.DataFrame,
+    start_date: pd.Timestamp,
+    end_date: pd.Timestamp,
+    current_date: pd.Timestamp,
+) -> pd.Series:
+    ...
+```
+
+Rules your strategy should satisfy:
+
+- Return a weight series indexed by dates in the selected window
+- Weights should be non-negative
+- Weights should sum to `1.0`
+- Avoid forward-looking data usage
+
+### Available Features
+
+Feature columns are generated by `precompute_features()` and typically include:
+
+- `PriceUSD_coinmetrics`
+- `price_ma`
+- `price_vs_ma`
+- `mvrv_zscore`
+- `mvrv_gradient`
+- `mvrv_percentile`
+- `mvrv_acceleration`
+- `mvrv_zone`
+- `mvrv_volatility`
+- `signal_confidence`
+
+## Built-in and Example Strategies
+
+### Built-in
+
+- `MVRVStrategy`: Default strategy from the package model.
+
+### Examples
+
+In `stacksats.strategies.examples`:
+
+- `UniformStrategy`
+- `SimpleZScoreStrategy`
+- `MomentumStrategy`
+
+These are lightweight templates for custom model development.
+
+## Backtesting
+
+Run the default built-in strategy:
+
+```bash
+stacksats-backtest
+```
+
+Run a custom strategy class from a file:
+
+```bash
+stacksats-backtest --strategy my_strategy.py:MyStrategy --start-date 2020-01-01 --end-date 2025-01-01
+```
+
+Use the Python API directly:
+
+```python
+from stacksats import MVRVStrategy, run_backtest
+
+result = run_backtest(MVRVStrategy(), strategy_label="default-mvrv")
+print(result.summary())
+```
+
+## Validation
+
+Validate built-in strategy:
+
+```bash
+stacksats-validate --start-date 2020-01-01 --end-date 2025-01-01
+```
+
+Validate a custom strategy class:
+
+```bash
+stacksats-validate --strategy my_strategy.py:MyStrategy --min-win-rate 50.0
+```
+
+## Command Line Tools
+
+Installed scripts:
+
+- `stacksats-backtest`
+- `stacksats-export`
+- `stacksats-plot-mvrv`
+- `stacksats-plot-weights`
+- `stacksats-validate`
+
+Custom-strategy flags:
+
+- `stacksats-backtest --strategy module_or_path:ClassName`
+- `stacksats-validate --strategy module_or_path:ClassName`
+- `stacksats-export --strategy module_or_path:ClassName`
+
+## Advanced: Deployment
+
+Deployment and infrastructure modules are optional:
+
+- `stacksats.export_weights`
+- `stacksats.modal_app`
+
+These require deployment extras:
+
+```bash
+pip install "stacksats[deploy]"
+```
+
+Deploy with built-in strategy:
+
+```bash
+modal deploy stacksats/modal_app.py
+```
+
+Deploy with custom strategy:
+
+```bash
+STACKSATS_STRATEGY=my_strategy.py:MyStrategy modal deploy stacksats/modal_app.py
+```
+
+## Development
+
+Run tests:
+
+```bash
+pytest tests/ -v
+```
+
+Verify documented command examples:
+
+```bash
+# Requires ./venv (for example: python -m venv venv && source venv/bin/activate && pip install -e .)
+python scripts/test_example_commands.py
+```
+
+Run lint:
+
+```bash
+ruff check .
+```
+
+Release process: see `docs/release.md`.
+
+## Contributors
+
+This project has benefited from contributions by researchers from the following universities:
+
+- Columbia University (Master of Data Science)
+- Cornell University (Master of Engineering in Management)
+- Georgia Institute of Technology (Master of Science in Analytics)
+- London School of Economics (Master of Science in Data Science)
+- University of British Columbia (Master of Data Science)
+- University of California, Davis (Master of Science in Business Analytics)
+- University of California, Irvine (Master of Data Science)
+- University of California, San Diego (Master of Quantitative Finance)

stacksats-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stacksats"
+version = "0.1.0"
+description = "Bitcoin DCA model development, backtesting, and Modal deployment toolkit"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "StackSats Contributors" }]
+keywords = ["bitcoin", "dca", "backtesting", "quant", "crypto"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "pandas>=2.0.0",
+  "numpy>=1.24.0",
+  "scipy>=1.11.0",
+  "requests>=2.31.0",
+  "matplotlib>=3.7.0",
+  "seaborn>=0.12.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/stacksats/stacksats"
+Repository = "https://github.com/stacksats/stacksats"
+Documentation = "https://github.com/stacksats/stacksats/tree/main/docs"
+
+[project.optional-dependencies]
+deploy = [
+  "modal>=0.52.0",
+  "psycopg2-binary>=2.9.0",
+  "fastapi>=0.104.0",
+  "python-dotenv>=1.0.0",
+  "tenacity>=8.2.0",
+  "pyarrow>=13.0.0",
+]
+dev = [
+  "pytest>=7.0.0",
+  "pytest-bdd>=7.0.0",
+  "pytest-cov>=4.0.0",
+  "pytest-mock>=3.10.0",
+  "pytest-benchmark>=4.0.0",
+  "pytest-xdist>=3.0.0",
+  "responses>=0.23.0",
+  "freezegun>=1.2.0",
+  "hypothesis>=6.0.0",
+  "ruff>=0.1.0",
+  "vulture",
+]
+
+[project.scripts]
+stacksats-backtest = "stacksats.backtest:main"
+stacksats-export = "stacksats.export_weights:main"
+stacksats-plot-mvrv = "stacksats.plot_mvrv:main"
+stacksats-plot-weights = "stacksats.plot_weights:main"
+stacksats-validate = "stacksats.api:validate_strategy_cli"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stacksats", "stacksats.*"]
+
+[tool.setuptools.package-data]
+stacksats = ["py.typed"]

stacksats-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stacksats-0.1.0/stacksats/__init__.py

@@ -0,0 +1,21 @@
+"""StackSats package public API."""
+
+from .api import BacktestResult, ValidationResult, run_backtest, validate_strategy
+from .loader import load_strategy
+from .model_development import precompute_features
+from .prelude import load_data
+from .strategies.base import CallableWindowStrategy, WindowStrategy
+from .strategies.mvrv import MVRVStrategy
+
+__all__ = [
+    "BacktestResult",
+    "CallableWindowStrategy",
+    "MVRVStrategy",
+    "ValidationResult",
+    "WindowStrategy",
+    "load_strategy",
+    "load_data",
+    "precompute_features",
+    "run_backtest",
+    "validate_strategy",
+]