From 0a89d3994288134183b0ceadf69f0d510dbaed45 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 01:22:04 +0000 Subject: [PATCH] Remove agent planning notes and tidy README and changelog Delete docs/superpowers/ and ignore it. Clarify which examples make figures, unwrap the walk-forward paragraph, drop CI trivia, explain the roadmap's execution-lag item, ignore the README CLI outputs and record the walk-forward example in an Unreleased changelog section. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016h2RvhZFj77hPxFn8TQUqq --- .gitignore | 7 ++++ CHANGELOG.md | 13 ++++++ README.md | 20 +++------- .../2026-10-25-walk-forward-risk-parity.md | 40 ------------------- ...6-10-25-walk-forward-risk-parity-design.md | 9 ----- 5 files changed, 26 insertions(+), 63 deletions(-) delete mode 100644 docs/superpowers/plans/2026-10-25-walk-forward-risk-parity.md delete mode 100644 docs/superpowers/specs/2026-10-25-walk-forward-risk-parity-design.md diff --git a/.gitignore b/.gitignore index dfce00e..eb50967 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,10 @@ htmlcov/ # Regenerated walk-forward example CSVs /walk-forward-output/ + +# Files the README's CLI examples write when run from the repository root +/prices.csv +/frontier.png + +# Local AI-agent planning notes +docs/superpowers/ diff --git a/CHANGELOG.md b/CHANGELOG.md index df73c5b..302ca50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,19 @@ All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## Unreleased + +The `quantkit` package itself is unchanged since 0.1.0. + +### Added + +- `examples/walk_forward_risk_parity.py`: a walk-forward example that rebuilds a + risk-parity portfolio each month from trailing returns, compares it with an + equal-weight benchmark and exports the results as CSVs. The walkthrough is in + `docs/WALK_FORWARD.md`. +- A release workflow that builds the wheel and sdist from a version tag and + attaches them, with SHA-256 checksums, to the GitHub release. + ## 0.1.0 - 2026-10-23 First release. diff --git a/README.md b/README.md index 5604861..54717d9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # quantkit -Options pricing, portfolio optimization and backtesting in Python — every model checked against closed-form results, textbook values or an independent method. +Options pricing, portfolio optimization and backtesting in Python. Every model is checked against closed-form results, textbook values or an independent method. [![CI](https://github.com/ult666666/quantkit/actions/workflows/ci.yml/badge.svg)](https://github.com/ult666666/quantkit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) @@ -197,7 +197,7 @@ Add `--plot frontier.png` to also save a chart (needs the `plot` extra), and, fo ### Examples and figures -The scripts in [`examples/`](examples) regenerate every figure below (`uv run python examples/.py`). +The scripts in [`examples/`](examples) regenerate the figures below (`uv run python examples/.py`). The walk-forward example writes CSVs instead of a figure. **Binomial convergence** ([`binomial_convergence.py`](examples/binomial_convergence.py)). CRR tree prices for Hull's call approach the Black–Scholes–Merton value with an error that shrinks like 1/steps, oscillating as tree nodes move relative to the strike. @@ -217,21 +217,13 @@ Seed 42 happens to be one of the 14. With no trends in the data, the crossover m ![Equity curves and drawdowns on synthetic data](docs/images/backtest_equity.png) -**Walk-forward portfolio construction** -([`walk_forward_risk_parity.py`](examples/walk_forward_risk_parity.py)). Connect -trailing-return estimation, risk-parity allocation and backtesting on fictional -prices. Each monthly allocation uses only closes preceding the rebalance date. -A monthly equal-weight benchmark shares the same cash warmup, dates and costs. +**Walk-forward portfolio construction** ([`walk_forward_risk_parity.py`](examples/walk_forward_risk_parity.py)), on **synthetic** data. This example connects trailing-return estimation, risk-parity allocation and backtesting. Each monthly allocation uses only closes before the rebalance date. A monthly equal-weight benchmark shares the same cash warmup, dates and costs. ```bash uv run python examples/walk_forward_risk_parity.py ``` -The command exports prices, both target tables, estimation windows, net wealth -and a common-period summary to `walk-forward-output/`. The -[walkthrough](docs/WALK_FORWARD.md) explains the timing, CSV fields, reproducible -inputs and limitations. These exports demonstrate mechanics, not investment -performance. +The command exports prices, both target tables, estimation windows, net wealth and a common-period summary to `walk-forward-output/`. The [walkthrough](docs/WALK_FORWARD.md) explains the timing, CSV fields, reproducible inputs and limitations. ## How it works @@ -296,9 +288,9 @@ uv run python examples/backtest_trend.py # regenerate a figure in docs/images **Backtesting.** Daily close-to-close only: trades fill at the same close that produced the signal, and the only friction is a proportional cost (no slippage, market impact, borrowing or financing costs). Idle cash earns nothing. Prices must be complete (no missing values and no assets entering mid-sample) and should already be adjusted for splits and dividends. The no-look-ahead guarantee covers the engine and the built-in strategies; custom strategies can be checked with `check_no_lookahead`. -**Data and verification.** There is deliberately no data downloader: bring your own CSV with ISO dates. CI runs lint, strict type checks and the full suite with README doctests on Python 3.11, 3.12 and 3.13. The 3.11 job installs NumPy 2.4 and older pandas type stubs; it caught three type annotations those stubs read differently, which were fixed in the source. +**Data and verification.** There is deliberately no data downloader: bring your own CSV with ISO dates. CI runs lint, strict type checks and the full suite with README doctests on Python 3.11, 3.12 and 3.13. -**Roadmap ideas:** per-asset and linear constraints, a vectorized BSM interface, Longstaff–Schwartz for American options, Black–Litterman expected returns, and walk-forward evaluation with execution lag in the backtester. +**Roadmap ideas:** per-asset and linear constraints, a vectorized BSM interface, Longstaff–Schwartz for American options, Black–Litterman expected returns, and an engine option to fill trades after the signal close. The walk-forward example lags its estimation window by one close, but its trades still fill at the signal close. ## References diff --git a/docs/superpowers/plans/2026-10-25-walk-forward-risk-parity.md b/docs/superpowers/plans/2026-10-25-walk-forward-risk-parity.md deleted file mode 100644 index 771e218..0000000 --- a/docs/superpowers/plans/2026-10-25-walk-forward-risk-parity.md +++ /dev/null @@ -1,40 +0,0 @@ -# Walk-Forward Risk-Parity Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Make a prior-information-only portfolio construction/backtest workflow runnable and exportable. - -**Architecture:** An additive example composes `compute_returns`, `ledoit_wolf_covariance`, `risk_parity`, `rebalance_days`, `backtest_weights` and `performance_summary`. Preserve the library APIs. - -**Tech Stack:** Python 3.11+, NumPy/pandas and existing quantkit APIs; no new dependencies. - -**Spec:** `docs/superpowers/specs/2026-10-25-walk-forward-risk-parity-design.md` - -## Global Constraints - -- Defaults: 1,260 fictional business days, 252-return window, seed 42, 10 bps costs, initial wealth 1. -- At date t use only closes ending t−1; trade at close t and hold during t+1. -- Shared monthly rebalance calendar, cash warmup and costs for risk parity/equal weight. -- Export prices, both target tables, wealth, summary and estimation-window CSVs. -- No optimization rewrite, live data, performance claim or execution capability. - -## Review Focus - -- Using date t's close in covariance must fail the current-close perturbation test. -- Insufficient history must produce a clear CLI failure before files are written. -- Both strategies must have identical trade dates and warmup treatment. -- Higher costs with unchanged targets must never improve wealth. -- Exported target blanks mean no trade, and summary excludes the shared cash warmup. - -### Task 1: Example and scenario - -**Files:** Create `examples/walk_forward_risk_parity.py`, `tests/test_walk_forward_example.py`, `docs/WALK_FORWARD.md`; modify `README.md` and `.gitignore` for the default output directory. - -**Interfaces:** `build_targets(prices: pd.DataFrame, lookback: int) -> TargetSchedule` with risk-parity/equal-weight frames and estimation windows; `run_example(output_dir: Path, *, n_days: int, lookback: int, cost_bps: float, seed: int) -> dict[str, Path]`; `main(argv: Sequence[str] | None = None) -> int`. - -- [ ] Write meaningful failing tests for prior-information invariance, feasible allocations, shared cash warmup, costs, windows and deterministic actual CLI files. -- [ ] Run `uv run pytest tests/test_walk_forward_example.py -q`; expect failure on the absent example. -- [ ] Implement the minimal typed composition and export workflow; rerun focused tests. -- [ ] Add README scenario, output contract, explicit timing and limits with the measured run dates. -- [ ] Run the full `uv run pytest --cov=quantkit --cov-fail-under=90`, existing ruff/format/mypy checks and the documented workflow. Expect all existing 333 tests plus new tests to pass. -- [ ] Fetch and preserve concurrent main additions, commit, push a scoped feature PR and attach it; parent reviews the exact head, no merge. diff --git a/docs/superpowers/specs/2026-10-25-walk-forward-risk-parity-design.md b/docs/superpowers/specs/2026-10-25-walk-forward-risk-parity-design.md deleted file mode 100644 index f42797e..0000000 --- a/docs/superpowers/specs/2026-10-25-walk-forward-risk-parity-design.md +++ /dev/null @@ -1,9 +0,0 @@ -# Walk-forward risk-parity example - -Add a runnable educational example joining existing portfolio estimation and backtesting APIs. Generate deterministic fictional AAA/BBB/CCC prices, estimate a trailing covariance at each monthly rebalance, construct risk-parity targets, and compare a monthly equal-weight benchmark on identical dates, initial capital, warmup and proportional costs. No statistical or optimization primitive changes. - -At the close of date t, the estimator uses exactly `lookback` simple returns from `lookback + 1` closes ending at t−1. The engine trades at close t and holds those targets during t+1. The extra one-close lag makes the information boundary explicit. Both strategies remain in zero-interest cash until the first monthly rebalance with sufficient history, then drift between rebalances. Long-only targets sum to one. - -Export fictional prices, both daily target tables (blank rows mean no trade), daily wealth, evaluation-period summary and estimation-window dates as CSVs. Summaries start on the shared first trade date, including its entry cost; full wealth includes the shared cash warmup. Defaults: 1,260 business days, 252-return window, seed 42, 10 bps costs, initial wealth 1. No plots or extra dependencies. - -Approaches considered: a new strategy class would expand the library API; a notebook adds tooling; a standalone example is selected to keep composition and its assumptions inspectable. Tests cover future/current-close shocks, feasible allocations, shared cash warmup, fixed-target cost monotonicity, auditable estimation windows and deterministic actual CLI exports. Document GBM assumptions, synthetic data, same-close fills, covariance-estimation risk and the absence of any performance or investment claim.