thetabook 2.2.3__tar.gz → 2.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {thetabook-2.2.3 → thetabook-2.3.0}/CHANGELOG.md +390 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/CLAUDE.md +7 -3
- {thetabook-2.2.3 → thetabook-2.3.0}/CONTRIBUTING.md +7 -6
- {thetabook-2.2.3 → thetabook-2.3.0}/PKG-INFO +2 -2
- {thetabook-2.2.3 → thetabook-2.3.0}/README.md +39 -3
- {thetabook-2.2.3 → thetabook-2.3.0}/ROADMAP.md +13 -2
- {thetabook-2.2.3 → thetabook-2.3.0}/pyproject.toml +10 -3
- thetabook-2.3.0/scripts/demo.sh +488 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/CLAUDE.md +14 -5
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/vrp.py +44 -9
- thetabook-2.3.0/src/thetabook/backtest/__init__.py +17 -0
- thetabook-2.3.0/src/thetabook/backtest/data.py +418 -0
- thetabook-2.3.0/src/thetabook/backtest/engine.py +123 -0
- thetabook-2.3.0/src/thetabook/backtest/grid.py +531 -0
- thetabook-2.3.0/src/thetabook/backtest/manifest.py +302 -0
- thetabook-2.3.0/src/thetabook/backtest/metrics.py +240 -0
- thetabook-2.3.0/src/thetabook/backtest/report.py +732 -0
- thetabook-2.3.0/src/thetabook/backtest/signals.py +112 -0
- thetabook-2.3.0/src/thetabook/backtest/strategies/__init__.py +122 -0
- thetabook-2.3.0/src/thetabook/backtest/strategies/dual_momentum.py +115 -0
- thetabook-2.3.0/src/thetabook/backtest/strategies/sector_rotation.py +173 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/__init__.py +3 -0
- thetabook-2.3.0/src/thetabook/cli/backtest.py +334 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/chain.py +5 -2
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/em.py +11 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/evaluate.py +8 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/hv.py +10 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/vrp.py +51 -3
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/adjust.py +371 -56
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/core.py +237 -13
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/evaluate_idea.py +445 -79
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/manage_ideas.py +7 -0
- thetabook-2.3.0/src/thetabook/leg_parse.py +368 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/_schwab.py +29 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/bars.py +127 -77
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/chains.py +75 -8
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/dividends.py +2 -2
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/prices.py +2 -2
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/vol_lookup.py +117 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/models.py +74 -8
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/accounts.py +220 -19
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/empower.py +4 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/fidelity.py +36 -9
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/schwab.py +6 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/options_book.py +156 -17
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/pricing/greeks.py +23 -3
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/policy.py +7 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/idea.md +10 -2
- thetabook-2.3.0/src/thetabook/tickers.py +429 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/wiki/render.py +15 -1
- {thetabook-2.2.3 → thetabook-2.3.0}/uv.lock +123 -148
- thetabook-2.2.3/src/thetabook/leg_parse.py +0 -201
- thetabook-2.2.3/src/thetabook/tickers.py +0 -218
- {thetabook-2.2.3 → thetabook-2.3.0}/.env.example +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/.git-blame-ignore-revs +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/.github/workflows/ci.yml +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/.github/workflows/publish.yml +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/.gitignore +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/.python-version +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/AGENTS.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/LICENSE +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/SECURITY.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/em.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/hv.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/scenarios.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/analysis/ta.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cache.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/CLAUDE.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/_shared.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/accounts.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/adjust.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/bars.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/bs.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/diff.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/dividends.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/earnings.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/greeks.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/ideas.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/import_csv.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/init.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/leg_mark.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/migrate_home.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/positions.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/price.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/refresh.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/roll.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/scenarios.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/skills.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/snapshot.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/ta.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/tickers.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/cli/wiki.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/config.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/ideas/roll_scenarios.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/log.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/earnings.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/market/leg_marks.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/paths.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/csv_parsers/_base.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/diff_snapshots.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/get_positions.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/import_csv_snapshot.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/portfolio/scaffold.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/preflight.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/pricing/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/pricing/bs.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/install.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/lint.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/models.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/parse.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/registry.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/skills/render.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/README.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/accounts.toml.example +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/config.toml.example +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/journal.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/learnings.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/skill.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/skills/setup-thetabook.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/index.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/log.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/overview.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/strategy.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/templates/wiki/underlying.md +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/wiki/__init__.py +0 -0
- {thetabook-2.2.3 → thetabook-2.3.0}/src/thetabook/wiki/lint.py +0 -0
|
@@ -5,6 +5,396 @@ All notable changes to this project are recorded here. Format loosely follows
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [2.3.0] — 2026-11-01
|
|
9
|
+
|
|
10
|
+
The first release since v2.2.3. It adds a backtester for systematic
|
|
11
|
+
strategies whose live signal is the backtest's own last row,
|
|
12
|
+
share legs in idea files, and a run of risk-correctness fixes that change
|
|
13
|
+
the numbers `evaluate` records.
|
|
14
|
+
|
|
15
|
+
**Expect existing ideas to move on their next `evaluate`.** PoP now
|
|
16
|
+
integrates a ±5σ grid instead of the ±2σ display domain
|
|
17
|
+
([#96](https://github.com/subsriram/thetabook/issues/96)); max gain / loss
|
|
18
|
+
are computed in closed form and can read `Unbounded`
|
|
19
|
+
([#99](https://github.com/subsriram/thetabook/issues/99)), with a one-time,
|
|
20
|
+
announced migration of budgets the old math got wrong; and a covered
|
|
21
|
+
structure keeps evaluating as naked until its shares are declared in
|
|
22
|
+
`## Structure` ([#102](https://github.com/subsriram/thetabook/issues/102)).
|
|
23
|
+
**Re-import Schwab or Empower CSV snapshots that hold options**: their
|
|
24
|
+
`averagePrice` was stored per contract, 100× too large
|
|
25
|
+
([#109](https://github.com/subsriram/thetabook/pull/109)).
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
- **`thetabook backtest`: hypothetical strategy backtests, with the live
|
|
30
|
+
signal on the same code path**
|
|
31
|
+
([#108](https://github.com/subsriram/thetabook/issues/108);
|
|
32
|
+
[#110](https://github.com/subsriram/thetabook/pull/110),
|
|
33
|
+
[#114](https://github.com/subsriram/thetabook/pull/114),
|
|
34
|
+
[#115](https://github.com/subsriram/thetabook/pull/115)). A new
|
|
35
|
+
workflow-layer `backtest/` package and a `backtest list | run | grid |
|
|
36
|
+
signal` sub-app, driven by `/backtest`. `run` builds a total-return panel
|
|
37
|
+
from the bars stitch plus cash dividends and enforces signal-at-close →
|
|
38
|
+
trade at close t+lag → earn from t+lag+1, with non-zero costs and short
|
|
39
|
+
borrow by default. It reports against the strategy's benchmark, the
|
|
40
|
+
equal-weight universe and cash, with t-stats on every active return.
|
|
41
|
+
`signal` is the last completed rebalance of that same simulation, not a
|
|
42
|
+
second implementation, so the weekly call can't drift from the backtest
|
|
43
|
+
that justified it. Two strategies ship: `sector-rotation` (11 SPDR sectors,
|
|
44
|
+
weekly) and `dual-momentum` (SPY / TLT / GLD vs BIL, monthly).
|
|
45
|
+
|
|
46
|
+
`grid` sweeps `--vary` over one data panel, prints how many configurations
|
|
47
|
+
were tried, ranks on in-sample Sharpe only, and reports the **deflated
|
|
48
|
+
Sharpe** (Bailey & López de Prado 2014) of the winner. The paper's §6
|
|
49
|
+
worked example is a known-answer test. `--prior-trials` counts searches
|
|
50
|
+
done elsewhere, and `--walk-forward` re-picks the best config per fold and
|
|
51
|
+
chains the tests into one out-of-sample series.
|
|
52
|
+
|
|
53
|
+
`--save` on `run` / `grid` writes an immutable manifest to
|
|
54
|
+
`$THETABOOK_HOME/backtests/`: the JSON payload plus the code version, git
|
|
55
|
+
SHA, argv, params, a panel fingerprint and a UTC timestamp. The file is
|
|
56
|
+
create-only and chmod 0444, an identical re-run is reported rather than
|
|
57
|
+
duplicated, and stdout is byte-identical with or without the flag. This is
|
|
58
|
+
the package's third write boundary, and `personal/backtests` is now a
|
|
59
|
+
reserved skill write path. Everything prints as *hypothetical backtested
|
|
60
|
+
performance*. Conventions are in
|
|
61
|
+
[docs/behaviors.md](docs/behaviors.md) "Backtests".
|
|
62
|
+
|
|
63
|
+
- **Share legs in idea files**
|
|
64
|
+
([#102](https://github.com/subsriram/thetabook/issues/102),
|
|
65
|
+
[#103](https://github.com/subsriram/thetabook/pull/103)). `## Structure`
|
|
66
|
+
now takes `TICKER shares qty=+100 cost_basis=150.00` beside option lines.
|
|
67
|
+
Shares were previously dropped on both the read and the `adjust --save`
|
|
68
|
+
write side, so every covered call, buy-write or collar evaluated as naked:
|
|
69
|
+
after #99 that meant a confident `Unbounded` on a position bounded at
|
|
70
|
+
−$14,772, printed beside a net delta of the wrong sign. `cost_basis` is
|
|
71
|
+
required, and a share line without it is refused rather than skipped,
|
|
72
|
+
since a zero default reports a profit as the max loss. `evaluate` gives
|
|
73
|
+
share legs their own Greeks and marks rows. `adjust` carries snapshot
|
|
74
|
+
shares through before and after, so `adjust --assign --save` writes a file
|
|
75
|
+
that evaluates as the covered position it modelled. A structure carrying
|
|
76
|
+
shares must sit on a single underlying. `accounts.check_idea` drops its
|
|
77
|
+
snapshot-derived cover guard and sizes off `evaluated_max_loss` alone.
|
|
78
|
+
Its unbounded-loss message names the share-line syntax.
|
|
79
|
+
|
|
80
|
+
- **`scripts/demo.sh`, a guided walkthrough**
|
|
81
|
+
([#109](https://github.com/subsriram/thetabook/pull/109)). It runs the
|
|
82
|
+
main loop (snapshot, diff, positions, Greeks, account rules,
|
|
83
|
+
vol/TA/scenarios, chain, ideas, evaluate, adjust/roll, wiki) against a
|
|
84
|
+
throwaway `$THETABOOK_HOME` seeded with a fictional book, so no real
|
|
85
|
+
account data appears on screen. Market data is live, borrowed from your
|
|
86
|
+
`.env` and Schwab token. It refuses to run against, inside, or around
|
|
87
|
+
your real home. Supports `--auto`, `--from N`, `--verbose` and `--reset`.
|
|
88
|
+
Dev checkout only, since `scripts/` isn't in the wheel.
|
|
89
|
+
|
|
90
|
+
- **Index options now work: `VIX`, `SPX`, `NDX` and 22 more CBOE roots**
|
|
91
|
+
([#91](https://github.com/subsriram/thetabook/issues/91)). Schwab's canonical
|
|
92
|
+
form for an index carries a `$` prefix. Bare `VIX` failed on the chains
|
|
93
|
+
endpoint with HTTP 400, and — worse — on the *quotes* endpoint with HTTP
|
|
94
|
+
**200 plus an `errors` payload**, so nothing raised and `thetabook price VIX`
|
|
95
|
+
degraded silently through Massive to yfinance. Meanwhile the expiration
|
|
96
|
+
endpoint accepts either form, so `chain VIX` listed 13 expirations and then
|
|
97
|
+
priced nothing, which reads as "VIX has no options". It does — cash-settled
|
|
98
|
+
European on the SOQ, carrying none of the roll decay that makes VXX a poor
|
|
99
|
+
substitute for expressing a vol view.
|
|
100
|
+
|
|
101
|
+
A new `INDEX_ALIASES` map covers 25 verified roots — 10 with listed options
|
|
102
|
+
(`SPX`, `NDX`, `RUT`, `DJX`, `OEX`, `XEO`, `XSP`, `MRUT`, `VIX`, `SPESG`)
|
|
103
|
+
and 15 quote-only vol/stat indices. Every entry was checked against live
|
|
104
|
+
Schwab: bare returns nothing, `$`-prefixed returns a real quote.
|
|
105
|
+
|
|
106
|
+
It is deliberately **separate from `TICKER_ALIASES`** and applied only at
|
|
107
|
+
the market-data boundary, via `tickers.market_symbol()`. `canonicalize` —
|
|
108
|
+
which feeds snapshot symbols, CSV imports, idea-file legs and OCC roots —
|
|
109
|
+
never sees the `$`. Folding the two together would have written
|
|
110
|
+
`$SPX 260116P05000000` on CSV import against the API's
|
|
111
|
+
`SPX 260116P05000000` (so `diff` reported a phantom close *and* a phantom
|
|
112
|
+
open for one position), silently dropped a `$VIX …` line from an idea's
|
|
113
|
+
`## Structure` block, and — worst — priced a genuine equity at the index
|
|
114
|
+
level had one ever listed under a root like `OEX`. The `$` now stays on the
|
|
115
|
+
wire and out of everything persisted.
|
|
116
|
+
|
|
117
|
+
`price` / `chain` / `em --source iv` / `hv` / `vrp` all work on index roots
|
|
118
|
+
now.
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
- **`evaluate` labels its probabilities as risk-neutral and reports
|
|
122
|
+
`E[payoff]`** ([#88](https://github.com/subsriram/thetabook/issues/88)).
|
|
123
|
+
`Prob. of profit` / `Expected profit` / `Expected loss` were printed with no
|
|
124
|
+
indication they're computed under the pricing measure — drift `r - q`, not
|
|
125
|
+
the instrument's actual expected return. On equities the gap is small; on
|
|
126
|
+
leveraged and volatility ETPs it's 2–3×. A VXX spread was written up as a
|
|
127
|
+
"~1-in-5" trade at PoP 21.1% when the real-world figure is nearer 1-in-10
|
|
128
|
+
with negative expected value. The conditional rows are now marked as
|
|
129
|
+
conditional, and the probability-weighted `E[payoff]` — the only one of the
|
|
130
|
+
three that carries information about edge — sits alongside them. It lands
|
|
131
|
+
≈ $0 for a fairly-priced structure, which is the signal.
|
|
132
|
+
|
|
133
|
+
The expectations integrate over their own ±5σ grid rather than the ±2σ
|
|
134
|
+
display domain the P&L table is drawn from. `pnl_price_domain` sizes the
|
|
135
|
+
latter for plotting, and at ±2σ the tails still hold ~5% of the mass — for
|
|
136
|
+
an undefined-risk short, exactly where the loss is unbounded. Clamping it to
|
|
137
|
+
the boundary doesn't blur the answer, it inverts it: a fairly-priced ATM
|
|
138
|
+
short call integrated over the display grid reported **+$9.77** against a
|
|
139
|
+
true **−$10.96**, phantom edge on a zero-edge trade. On the wider grid the
|
|
140
|
+
clamped mass is under one part in a million, and `E[payoff]` reproduces the
|
|
141
|
+
closed form `−qty·100·premium·(1 − e^{rT})` to the cent for naked calls,
|
|
142
|
+
puts, longs, and verticals alike.
|
|
143
|
+
|
|
144
|
+
- **`thetabook vrp --dte N`** ([#89](https://github.com/subsriram/thetabook/issues/89)
|
|
145
|
+
Part B). `vrp` sampled the front expiry, which on a liquid name is routinely
|
|
146
|
+
0–3 DTE — noisy and unrelated to any dated structure. QQQ's 0-DTE ratio read
|
|
147
|
+
**1.12 in the morning and 0.98 the same afternoon** while the Dec 101-DTE leg
|
|
148
|
+
actually being traded sat at **1.78**. `--dte N` selects the nearest expiry at
|
|
149
|
+
least N days out; the sampled DTE is now repeated on the `IV/HV` line (the one
|
|
150
|
+
people copy), a ≤ 7 DTE sample warns, and an unreachable horizon says what it
|
|
151
|
+
sampled instead.
|
|
152
|
+
|
|
153
|
+
- **Structural-decay warnings on `hv` / `em` / `vrp`**
|
|
154
|
+
([#89](https://github.com/subsriram/thetabook/issues/89) Part A). Realized
|
|
155
|
+
close-to-close vol on a rolling-futures or leveraged-reset product describes
|
|
156
|
+
the current regime rather than the risk being traded: VXX printed HV20 27.1%
|
|
157
|
+
at HV-rank 5.0% while its own ATM IV was ~60%. A static
|
|
158
|
+
`STRUCTURAL_DECAY_TICKERS` list (vol ETPs, leveraged index and single-stock
|
|
159
|
+
funds) drives an advisory warning in each command where its own output is the
|
|
160
|
+
misleading part. Static rather than inferred on purpose — classifying decay
|
|
161
|
+
from price history is its own problem, and a false positive on an ordinary
|
|
162
|
+
equity is worse than a missed exotic.
|
|
163
|
+
|
|
164
|
+
### Fixed
|
|
165
|
+
|
|
166
|
+
- **Max gain / loss were read off the display grid, understating tail
|
|
167
|
+
risk** ([#99](https://github.com/subsriram/thetabook/issues/99),
|
|
168
|
+
[#101](https://github.com/subsriram/thetabook/pull/101)). They were
|
|
169
|
+
`np.max` / `np.min` over the S ± 30% plotting domain, so any extreme
|
|
170
|
+
outside it was reported at the edge. A 182-DTE AAPL short 160 put read
|
|
171
|
+
−$3,285.62 against a true −$15,535.62, and that is the figure
|
|
172
|
+
`max_position_pct` enforces, so a position 4.7× over its limit passed
|
|
173
|
+
silently. Widening the grid isn't enough: a put bottoms out at S_T = 0,
|
|
174
|
+
which no lognormal grid reaches. P&L at expiry is piecewise-linear with
|
|
175
|
+
kinks only at the strikes, so evaluating at 0, at each strike and along
|
|
176
|
+
the final ray's slope is exact. Unbounded structures now report `±inf`,
|
|
177
|
+
render `Unbounded`, and raise a distinct `max_position_pct` violation.
|
|
178
|
+
`adjust` shows `unbounded → bounded` instead of a NaN delta. Budgets the
|
|
179
|
+
old math got wrong are re-seeded once, with a stderr warning, and stamped
|
|
180
|
+
`budget_basis: analytic`. Budgets it got right, including hand-declared
|
|
181
|
+
ones, are left alone.
|
|
182
|
+
|
|
183
|
+
- **The price behind a cushion or a PoP is now named**
|
|
184
|
+
([#100](https://github.com/subsriram/thetabook/issues/100),
|
|
185
|
+
[#101](https://github.com/subsriram/thetabook/pull/101)). `positions`
|
|
186
|
+
measured a VIX cushion against the forward while printing spot beside it,
|
|
187
|
+
so a row like "−7.7% cushion on a 17 call at $15.72 spot" was impossible
|
|
188
|
+
on its face. A `fwd` column now shows the reference, and only when some
|
|
189
|
+
row is forward-settled. `?` marks a forward that didn't resolve, such as
|
|
190
|
+
under `--no-fetch`. `adjust` tracks the forward per scenario, so a roll
|
|
191
|
+
across expiries renders `(fwd $18.42 → $19.05)` instead of naming only
|
|
192
|
+
the new leg's future.
|
|
193
|
+
|
|
194
|
+
- **CSV-imported option `averagePrice` was per contract, not per share**
|
|
195
|
+
([#109](https://github.com/subsriram/thetabook/pull/109)). The Schwab and
|
|
196
|
+
Empower importers divided total cost basis by contract count, so a short
|
|
197
|
+
call sold for $6.20 landed as `620`. Every consumer reads that field per
|
|
198
|
+
share, and `adjust` on such a snapshot reported a $123,170 realized P&L on
|
|
199
|
+
a $410 buyback. Fidelity reads the broker's own per-share column and is
|
|
200
|
+
unchanged. Snapshots imported before this fix keep the inflated value
|
|
201
|
+
until the CSVs are re-imported.
|
|
202
|
+
|
|
203
|
+
- **Deep bar history comes from yfinance when defeatbeta has no coverage**
|
|
204
|
+
([#111](https://github.com/subsriram/thetabook/issues/111),
|
|
205
|
+
[#112](https://github.com/subsriram/thetabook/pull/112)). The whole window
|
|
206
|
+
used to go through the live cascade, and Schwab's deep daily history
|
|
207
|
+
carries weekend-dated copies of Friday's close, missing sessions, bad
|
|
208
|
+
prints, and a pre-2020 XLE series 4–15% off. yfinance (defeatbeta's own
|
|
209
|
+
upstream) now serves everything older than 14 days, and the live cascade
|
|
210
|
+
only that tail. Weekend-dated daily rows are dropped from every source
|
|
211
|
+
with one warning, and the sources used are recorded on the frame.
|
|
212
|
+
|
|
213
|
+
- **defeatbeta history was 404ing for every uncached ticker**
|
|
214
|
+
([#113](https://github.com/subsriram/thetabook/pull/113)). The upstream
|
|
215
|
+
dataset moved its parquet files under `data/US/`, which defeatbeta-api
|
|
216
|
+
0.0.57 hard-coded the old way, so `hv` / `ta` / `scenarios` silently fell
|
|
217
|
+
back to the live cascade. The floor is now `defeatbeta-api>=0.0.63`, and
|
|
218
|
+
the output-silencing wrapper is updated for its new logging (nltk is gone).
|
|
219
|
+
|
|
220
|
+
- **Fidelity CSV edge cases**
|
|
221
|
+
([3385271](https://github.com/subsriram/thetabook/commit/3385271)).
|
|
222
|
+
Schwab-held options inside a Fidelity FullView export
|
|
223
|
+
(`PUT AMD$475 EXP 07/17/26`, no option root) warn and are skipped, with a
|
|
224
|
+
pointer to `thetabook refresh`, instead of mis-parsing. Header detection
|
|
225
|
+
is case-insensitive, and a missing `Average Cost Basis` column no longer
|
|
226
|
+
raises.
|
|
227
|
+
|
|
228
|
+
- **VIX options were priced off spot, not the futures curve they reference**
|
|
229
|
+
([#96](https://github.com/subsriram/thetabook/issues/96)). VIX options settle
|
|
230
|
+
to the SOQ and reference the VIX *future* for their expiry; no cash-and-carry
|
|
231
|
+
links future to spot, so no `r`/`q` choice bridges them. On 2026-09-08 spot
|
|
232
|
+
was 15.72 against an October forward of 18.42 — 17.2% contango — and pricing
|
|
233
|
+
off spot underpriced the chain by **56% at the money and 85% on the wings**,
|
|
234
|
+
while centring every probability on a price the contract never settles
|
|
235
|
+
against. "VIX above 18 at expiry" read **21.5%** off spot against **51.2%**
|
|
236
|
+
off the forward.
|
|
237
|
+
|
|
238
|
+
`VolResolver.resolve_forward()` derives the forward from put-call parity on
|
|
239
|
+
the chain already fetched — `F = K + (C − P)·e^{rT}`, median across strikes
|
|
240
|
+
carrying both legs, so one stale wing can't move it. Resolution is per leg,
|
|
241
|
+
since the forward is per expiry and a calendar spread carries a different one
|
|
242
|
+
on each. It feeds `compute_greeks`, `evaluate`'s PoP / `E[payoff]` /
|
|
243
|
+
expectation grid, `adjust`'s opening marks and scenario PoP, portfolio Greeks
|
|
244
|
+
aggregation, and `positions` cushion — where a VIX 20 call reads +27.2% OTM
|
|
245
|
+
off spot and **+8.6%** off the forward.
|
|
246
|
+
|
|
247
|
+
Pricing on that path uses **Black-76** (`q = r`), not Black-Scholes with the
|
|
248
|
+
spot swapped — the forward already embeds the carry, so leaving `q` at 0
|
|
249
|
+
applied it twice. The error is signed opposite by side: calls were overpriced
|
|
250
|
+
(+1.2% to +7.1%) and **puts underpriced** (−9.8% to −1.4%), so a short VIX 15
|
|
251
|
+
put — the position this work is built around — was marked 5.2% light.
|
|
252
|
+
|
|
253
|
+
`tickers.FORWARD_SETTLED` holds `VIX` alone: the other vol indices share the
|
|
254
|
+
structure but CBOE delisted their options. SPX / NDX / RUT are excluded for a
|
|
255
|
+
different reason — they settle on the index itself, so spot *is* the
|
|
256
|
+
underlying and ordinary carry already gives the forward. Every command-level
|
|
257
|
+
caller warns when parity can't be derived rather than silently using spot —
|
|
258
|
+
including `positions --no-fetch`, which can't derive one at all — and both
|
|
259
|
+
`evaluate` and `adjust` name the forward in their headers.
|
|
260
|
+
|
|
261
|
+
PoP now integrates the same ±5σ grid the expectations use, in both `evaluate`
|
|
262
|
+
and `adjust`. The old ±2σ display domain closed an unbounded profitable
|
|
263
|
+
*region* at its edge, so **recorded PoP moves for most structures**, not just
|
|
264
|
+
forward-settled ones. What matters is whether the profitable region is
|
|
265
|
+
bounded on both sides, not whether P&L is capped:
|
|
266
|
+
|
|
267
|
+
| structure | before | after |
|
|
268
|
+
| --- | ---: | ---: |
|
|
269
|
+
| AAPL 182-DTE short put | 62.5% | 73.3% |
|
|
270
|
+
| AAPL 6-month 170/180 debit call vertical | 38.7% | 49.5% |
|
|
271
|
+
| AAPL iron condor 150/160/190/200 | 36.6% | 36.6% |
|
|
272
|
+
|
|
273
|
+
A debit vertical's profit region is `[breakeven, ∞)` even though its P&L is
|
|
274
|
+
capped, so it moves; an iron condor is bounded on both sides and does not.
|
|
275
|
+
The new figures are the correct ones — the old domain simply stopped
|
|
276
|
+
integrating at `S ± 30%` — but expect existing ideas' recorded PoP to change
|
|
277
|
+
on the next `evaluate`.
|
|
278
|
+
|
|
279
|
+
Schwab's broker Greeks for VIX remain suspect — 10 of 36 October calls report
|
|
280
|
+
delta > 1.0 — and are untouched here; `--greeks-source bs` forces the
|
|
281
|
+
corrected path.
|
|
282
|
+
|
|
283
|
+
- **Schwab has never served option expirations**
|
|
284
|
+
([#91](https://github.com/subsriram/thetabook/issues/91)).
|
|
285
|
+
`list_expirations_schwab` read `year` / `month` / `day` out of
|
|
286
|
+
`expirationList`, keys the payload has never carried — it returns
|
|
287
|
+
`{"expirationDate": "2026-10-21", …}`. It therefore returned `None` for
|
|
288
|
+
*every* ticker and the cascade quietly fell through to yfinance:
|
|
289
|
+
15-minute-delayed, and empty for index roots, which is what made #91 look
|
|
290
|
+
like an entitlements problem. The test fixture encoded the same invented
|
|
291
|
+
shape, which is why it survived; it now pins a payload captured live.
|
|
292
|
+
|
|
293
|
+
- **Ticker aliases didn't reach the bars backbone**
|
|
294
|
+
([#91](https://github.com/subsriram/thetabook/issues/91)). `get_bars` never
|
|
295
|
+
canonicalized, so the alias map applied to the live price cascade but not to
|
|
296
|
+
history: `thetabook price BRKB` worked while `thetabook hv BRKB` silently
|
|
297
|
+
returned nothing. Canonicalization now happens at `get_bars` — the one
|
|
298
|
+
chokepoint every bars consumer passes through — matching what `prices.py`
|
|
299
|
+
and `chains.py` already do at their entry points.
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
- **Schwab HTTP errors now surface the response body**
|
|
303
|
+
([#91](https://github.com/subsriram/thetabook/issues/91)).
|
|
304
|
+
`raise_for_status()` renders only the status line, so a Schwab 400 arrived as
|
|
305
|
+
`Client error '400 Bad Request' for url ...` with no hint of what Schwab
|
|
306
|
+
objected to — and for a rejected symbol form the body is the whole diagnosis.
|
|
307
|
+
All six Schwab read call sites now append a truncated excerpt.
|
|
308
|
+
|
|
309
|
+
- **`chain` explains the listable-but-unpriceable case**
|
|
310
|
+
([#91](https://github.com/subsriram/thetabook/issues/91)). Schwab's two
|
|
311
|
+
endpoints disagree about symbology: `chain VIX` lists 13 expirations — implying
|
|
312
|
+
the symbol is fine — and then every strike lookup returns empty, so the
|
|
313
|
+
reasonable conclusion is "VIX has no options". It does; VIX options are
|
|
314
|
+
cash-settled European and carry none of the roll decay that cost a VXX
|
|
315
|
+
position 79.3% over three years while VIX itself rose 9.6%. The no-contracts
|
|
316
|
+
path now names index symbology as the likely cause, but only in that
|
|
317
|
+
contradictory case — a date that isn't listed gets different advice, and a
|
|
318
|
+
ticker with no options gets the plain message.
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
- **Idea frontmatter and the `## Evaluation` body could disagree about
|
|
323
|
+
max gain/loss** ([#92](https://github.com/subsriram/thetabook/issues/92)).
|
|
324
|
+
`update_idea_file` set `max_gain` / `max_loss` only when unset, while the
|
|
325
|
+
body section was regenerated on every run — so a re-evaluated idea carried a
|
|
326
|
+
frozen frontmatter and a fresh body contradicting each other in the same
|
|
327
|
+
file, with nothing marking which was current (observed: `max_gain: 4490.0`
|
|
328
|
+
against a body reading `$4,480.00`, both written by `evaluate` hours apart).
|
|
329
|
+
|
|
330
|
+
Beyond cosmetics: `accounts.check_idea` enforces `max_position_pct` off the
|
|
331
|
+
frontmatter, so the risk check read a figure the body had already moved past,
|
|
332
|
+
and nothing bounded the gap — an idea first evaluated months ago kept its
|
|
333
|
+
original numbers forever.
|
|
334
|
+
|
|
335
|
+
**The enforced number is deliberately unchanged.** `check_idea` still reads
|
|
336
|
+
the same frozen `max_loss` it always did; what the split fixes is that the
|
|
337
|
+
file no longer presents two contradictory figures under one name, and the
|
|
338
|
+
frozen one is now labelled as what it is. A position limit *should* bind on
|
|
339
|
+
the risk accepted at entry rather than on a mark that moves under you — so
|
|
340
|
+
don't expect `max_position_pct` to start tracking the live number.
|
|
341
|
+
|
|
342
|
+
Split into two pairs. `max_gain` / `max_loss` stay write-once and become the
|
|
343
|
+
**author-declared risk budget**; new `evaluated_max_gain` /
|
|
344
|
+
`evaluated_max_loss` refresh every run. `check_idea` enforces the budget and
|
|
345
|
+
falls back to the computed value only when none was set, so a position limit
|
|
346
|
+
binds on the risk accepted at entry rather than on a mark that moves under
|
|
347
|
+
you, and ideas predating the field stay checkable. Existing files keep
|
|
348
|
+
loading unchanged; the new keys appear on the next `evaluate`.
|
|
349
|
+
|
|
350
|
+
`thetabook evaluate --reseed-budget` re-declares the budget from the current
|
|
351
|
+
run. Write-once with no writer would be a trap: every value in a pre-split
|
|
352
|
+
file was machine-written (one reads `-1223.1980000000003`, float noise off
|
|
353
|
+
`np.min` rather than a number anyone declared), and freezing those forever
|
|
354
|
+
while making them the sole input to a risk rule needs a way out that isn't
|
|
355
|
+
hand-editing frontmatter the CLI otherwise owns.
|
|
356
|
+
|
|
357
|
+
`adjust --save` seeds both pairs, and the wiki ideas roll-up now shows
|
|
358
|
+
`evaluated_max_loss` — it's the cross-session review surface, so it should
|
|
359
|
+
carry what the position risks now rather than the frozen seed.
|
|
360
|
+
|
|
361
|
+
Also routes `evaluate`'s write notice through `log.note` to **stderr** —
|
|
362
|
+
stdout is reserved for parseable output, and a status line there is easy to
|
|
363
|
+
miss when output is piped or read by an agent.
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
- **`adjust`'s BS-estimated opening premium used flat vol, not chain IV at the
|
|
368
|
+
strike** ([#32](https://github.com/subsriram/thetabook/issues/32)). When
|
|
369
|
+
`--open` / `--add` got a leg with no `premium=` and the chain had no usable
|
|
370
|
+
quote, `resolve_opening_mark` priced it off the flat 25% default — while
|
|
371
|
+
`compute_greeks` priced the *same hypothetical leg in the same scenario* off
|
|
372
|
+
the chain's IV at that strike. The premium and the Greeks then disagreed
|
|
373
|
+
about what the position was worth inside a single invocation.
|
|
374
|
+
|
|
375
|
+
The two lookups diverge precisely where it hurts: a chain can cover a strike
|
|
376
|
+
for **IV** but not for a usable **quote** — an illiquid wing with no
|
|
377
|
+
bid/ask, a yfinance row carrying `implied_vol` and nothing else, or an
|
|
378
|
+
earnings-week wing where IV ramps. The BS fallback now resolves IV per-leg
|
|
379
|
+
through `VolResolver.resolve_leg_iv`, the same call the Greeks make, so one
|
|
380
|
+
sigma drives both. The error was not small on wings: a 45-DTE OTM call at a
|
|
381
|
+
62% chain IV prices at **$6.96** against **$0.53** at flat 25%, since option
|
|
382
|
+
value is sharply convex in vol when far OTM.
|
|
383
|
+
|
|
384
|
+
Priority is unchanged from the Greeks path — `--vol` override → chain IV at
|
|
385
|
+
the exact strike → flat default — and both the sigma and its provenance are
|
|
386
|
+
now recorded on the leg (`premium_iv`, `premium_iv_source`) and surfaced in
|
|
387
|
+
the comparison table as `bs @ 62% chain IV`, `bs @ 30% --vol override`, or
|
|
388
|
+
`bs @ 25% flat default`, so a BS-estimated premium is auditable instead of
|
|
389
|
+
an unattributed number. This applies under `--marks frozen` too: frozen
|
|
390
|
+
skips the live chain for *marks*, but the Greeks resolve per-leg chain IV in
|
|
391
|
+
a frozen run regardless, so exempting the premium there would have left the
|
|
392
|
+
same divergence alive. Only a resolver-less caller uses the flat vol.
|
|
393
|
+
|
|
394
|
+
The report header now reads `Vol: chain IV (per-leg)` instead of a single
|
|
395
|
+
flat number whenever `--vol` is absent — it previously printed `Vol: 25%`
|
|
396
|
+
above a table row reading `bs @ 62% chain IV`.
|
|
397
|
+
|
|
8
398
|
## [2.2.3] — 2026-09-08
|
|
9
399
|
|
|
10
400
|
Housekeeping release, plus the last uncovered corner of Schwab's 7-day
|
|
@@ -24,7 +24,8 @@ The name nods to **theta**, the daily decay that quietly drives most options P&L
|
|
|
24
24
|
- **When the CLI doesn't expose what you need, drop into Python** — but always call `thetabook.paths.load_env()` first. Without it, the Schwab client returns `None` and the data cascade silently falls through to a worse source (yfinance), producing answers that disagree with the CLI's. If the gap is reusable, file an issue to surface it via a flag or new subcommand rather than letting the Python escape hatch normalize.
|
|
25
25
|
- **For technical analysis, use `thetabook hv` / `ta` / `scenarios` / `bars`.** `thetabook ta TICKER` gives RSI/MACD/Bollinger with interpretive labels; `thetabook hv TICKER` gives realized vol + HV-rank/percentile (the IV-rank substitute — there's no historical option IV); `thetabook scenarios match TICKER` answers "has this regime happened before?" with forward-return outcomes (run both `--mode trajectory` and `--mode state`; when they disagree, present both rather than averaging). These read daily *closes* from a historical-bars backbone, not the live price cascade — see [docs/cli.md](docs/cli.md) for the full flag set and [docs/behaviors.md](docs/behaviors.md) for the stitch.
|
|
26
26
|
- **For vol-to-decision questions, use `thetabook em` / `vrp`.** `thetabook em TICKER --dte N` translates a vol figure into the ±1σ / ±2σ dollar range an option is pricing by expiry (`spot · σ · sqrt(DTE/365)`, calendar-day horizon — deliberately *not* `hv`'s `sqrt(252)`); sigma defaults to HV20, with `--iv` to override or `--source iv` to pull front-month ATM IV from the chain. `thetabook vrp TICKER` ratios that ATM IV against HV to answer "is implied richer than realized right now?" — a *point-in-time* IV-vs-HV read, **not** a historical IV-rank. Unlike the bars commands, both blend the live price/chain cascade (spot, IV) with bars-derived HV, so the IV paths need a Greeks-bearing source (Schwab or Massive) and exit non-zero on a yfinance-only fallback rather than printing a bogus number.
|
|
27
|
-
- **
|
|
27
|
+
- **For strategy research, use `thetabook backtest`** (`run` / `grid` / `signal`; `/backtest` drives it), not throwaway scripts over `market.bars`. Everything it prints is *hypothetical backtested performance*, so quote it that way and never as a recommendation. To compare configurations, run one `grid` rather than repeated `run`s, so the trial count and deflated Sharpe see the whole search. Pass `--prior-trials` for configs already tried by hand. Add `--save` only when the user wants a kept record; it writes an immutable manifest under `personal/backtests/`, which must never be edited. Read OOS, the DSR (< 0.95 = indistinguishable from selection luck) and `--walk-forward` rather than the top IS row, and treat |t| < 2 as noise. Conventions are in [docs/behaviors.md](docs/behaviors.md) "Backtests".
|
|
28
|
+
- **Know how fresh each source is before quoting a number.** The historical bars under `hv`/`ta`/`scenarios` are a stitch: defeatbeta (weekly HuggingFace dataset) covers history up to the **most recent Friday's close**, and the rolling tail through today is filled by the **same live cascade as the price pipeline — Schwab → Massive → yfinance** — so the latest *complete* indicator bar is usually last Friday, and intraday moves aren't reflected until the day closes. For a ticker defeatbeta doesn't cover, **yfinance** serves the deep history instead and the live cascade only the last 14 days (#111). In the live price cascade, **Massive returns the previous business day's close, not an intraday quote** (Polygon `get_previous_close_agg`; the bars tail instead uses Massive's date-range daily aggregates); only Schwab is real-time and yfinance is ~15-min delayed. When a figure comes from Massive or from the defeatbeta history, say so — don't present it as the current price.
|
|
28
29
|
|
|
29
30
|
## Repo layout
|
|
30
31
|
|
|
@@ -39,6 +40,7 @@ thetabook/
|
|
|
39
40
|
│ ├── analysis/ # derived signals: HV, TA, expected move, VRP, scenario lookup
|
|
40
41
|
│ ├── portfolio/ # snapshot I/O, CSV import, options book, per-account rules, scaffold
|
|
41
42
|
│ ├── ideas/ # trade-idea workflow (manage / evaluate / adjust / roll)
|
|
43
|
+
│ ├── backtest/ # hypothetical strategy backtests + live signal (one code path)
|
|
42
44
|
│ ├── wiki/ # personal/wiki/ lint + auto-rendered ideas roll-up
|
|
43
45
|
│ ├── skills/ # author-time tooling + registry installer for skill files
|
|
44
46
|
│ ├── templates/ # canonical templates, shipped inside the wheel (idea.md,
|
|
@@ -51,6 +53,7 @@ thetabook/
|
|
|
51
53
|
│ ├── ideas/ # trade ideas, one file per idea
|
|
52
54
|
│ ├── accounts.toml # per-account posture + rules
|
|
53
55
|
│ ├── config.toml # per-clone overrides ([market], [adjust], [schwab], [skills])
|
|
56
|
+
│ ├── backtests/ # immutable run manifests (`backtest run|grid --save`); never edit
|
|
54
57
|
│ └── wiki/ # LLM-maintained knowledge base — compounds over time
|
|
55
58
|
└── tests/ # pytest suite — mirrors src/thetabook/ (has its own CLAUDE.md)
|
|
56
59
|
```
|
|
@@ -83,7 +86,8 @@ The skills CLI (`thetabook skills lint/show/install/installed/sync/remove/render
|
|
|
83
86
|
- **Dates**: ISO format (`YYYY-MM-DD`) everywhere — filenames, frontmatter, tables.
|
|
84
87
|
- **Money**: show dollar amounts with commas and 2 decimals (`$12,345.67`).
|
|
85
88
|
- **Option contracts**: reference as `TICKER YYYY-MM-DD STRIKE C/P` (e.g. `AAPL 2026-01-16 180 C`).
|
|
86
|
-
- **
|
|
89
|
+
- **Share legs**: an idea's `## Structure` takes share lines beside option lines — `TICKER shares qty=+100 cost_basis=150.00`. `cost_basis` is per-share and required; a share line without it is refused rather than skipped. **Declare the shares for every covered structure** (covered call, buy-write, collar, assigned position) — omitting them is silent, and the position then evaluates as naked: `Max loss: Unbounded` on a structure bounded at −$14,772, and a net delta of the wrong sign. See [docs/behaviors.md](docs/behaviors.md) "Share legs in idea files".
|
|
90
|
+
- **Ideas** use frontmatter: `status: proposed | watching | opened | closed | rejected`, plus `opened_at`, `closed_at`, `thesis`, `outcome`. Dollar fields come in two flavours: `max_gain`/`max_loss` are the author-declared risk budget (seeded by the first `evaluate`, then write-once — the sole exception is a one-time #99 migration, per side, marked by `budget_basis`), while `evaluated_max_gain`/`evaluated_max_loss` refresh on every run. Both pairs are **closed-form extremes over `S_T >= 0`**, not grid reductions, and carry `±inf` (displayed `Unbounded`) for a structure with no bound. `max_position_pct` enforces against the budget, but reads *whether* the position is unbounded off `evaluated_max_loss`, so a frozen budget can't mask a naked short. See [docs/behaviors.md](docs/behaviors.md) "Max profit / max loss are closed form".
|
|
87
91
|
- **Journal entries** have sections: `Positions reviewed`, `Discussion`, `Ideas generated`, `Learnings`.
|
|
88
92
|
- **Assignment cost basis**: when a short put is assigned, record the basis components as distinct fields in idea outcomes, wiki trade arcs, and journal entries — **Assigned price (cost basis)** = strike, **Option income** = put premium, **Effective price (reference)** = strike − premium. The IRS-correct share basis for an assigned written put is the *effective price* (Pub 550 — the premium reduces the basis rather than being a separate gain), so don't double-count the premium as separate income on top of it. Quote the strike as the basis only when reconciling against a broker 1099-B that didn't adjust for the premium (`thetabook adjust --assign-basis strike`). See [docs/behaviors.md](docs/behaviors.md) "Assignment cost basis".
|
|
89
93
|
|
|
@@ -199,7 +203,7 @@ Configuration lives in `pyproject.toml`. Active rule packs: `E, W, F, I, B, UP,
|
|
|
199
203
|
|
|
200
204
|
## Mypy
|
|
201
205
|
|
|
202
|
-
Permissive baseline by default (no `disallow_untyped_defs`); strict in modules that are clean today (currently `bs.py` and `
|
|
206
|
+
Permissive baseline by default (no `disallow_untyped_defs`); strict in modules that are clean today (currently `bs.py`, `config.py` and `backtest/{engine,signals,metrics,manifest}.py` — list lives in `[[tool.mypy.overrides]]`). Tests are excluded from mypy. With pydantic models everywhere post-M17, fixture types are clear at the call site; ad-hoc test typing isn't worth the churn.
|
|
203
207
|
|
|
204
208
|
When mypy flags something, prefer fixing the underlying type over adding `# type: ignore`. If you do suppress, use a specific code (`# type: ignore[arg-type]`) and a one-line reason. Never invent fallback branches just to satisfy the type checker — if an upstream contract already excludes the unsafe case, prefer a walrus filter, an `assert` with rationale, or a typed ignore over a defensive code path that's dead at runtime.
|
|
205
209
|
|
|
@@ -16,17 +16,18 @@ uv sync
|
|
|
16
16
|
|
|
17
17
|
That's it — `uv sync` installs the project as an editable package, so `thetabook ...` and `uv run pytest` both work immediately.
|
|
18
18
|
|
|
19
|
-
## The
|
|
19
|
+
## The four gates
|
|
20
20
|
|
|
21
|
-
Every PR has to pass
|
|
21
|
+
Every PR has to pass four checks. Run them locally before you push — CI runs the same set ([.github/workflows/ci.yml](.github/workflows/ci.yml)):
|
|
22
22
|
|
|
23
23
|
```bash
|
|
24
|
-
uv run pytest
|
|
25
|
-
uv run ruff check .
|
|
26
|
-
uv run
|
|
24
|
+
uv run pytest # tests
|
|
25
|
+
uv run ruff check . # lint
|
|
26
|
+
uv run ruff format --check . # formatting
|
|
27
|
+
uv run mypy . # types
|
|
27
28
|
```
|
|
28
29
|
|
|
29
|
-
`ruff format` is the formatter. If
|
|
30
|
+
`ruff format` is the formatter. If the format check fails, run `uv run ruff format .` to fix.
|
|
30
31
|
|
|
31
32
|
## What lands easily
|
|
32
33
|
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: thetabook
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.3.0
|
|
4
4
|
Summary: A journal for options traders who think in Greeks — Schwab portfolio review and strategy log with an AI copilot.
|
|
5
5
|
License-File: LICENSE
|
|
6
6
|
Requires-Python: >=3.12
|
|
7
|
-
Requires-Dist: defeatbeta-api>=0.0.
|
|
7
|
+
Requires-Dist: defeatbeta-api>=0.0.63
|
|
8
8
|
Requires-Dist: massive>=2.5.0
|
|
9
9
|
Requires-Dist: numpy>=2.4.4
|
|
10
10
|
Requires-Dist: pandas>=2.2
|
|
@@ -138,6 +138,19 @@ thetabook import-csv schwab.csv fidelity.csv empower.csv
|
|
|
138
138
|
|
|
139
139
|
This produces the same snapshot format as the API path, so everything downstream works identically. Both option symbols and cash balances are handled.
|
|
140
140
|
|
|
141
|
+
### Guided demo
|
|
142
|
+
|
|
143
|
+
From a dev checkout, `scripts/demo.sh` walks the main loop — snapshot, diff, positions, Greeks, account rules, vol/TA/scenarios, chain, ideas, evaluate, adjust/roll, wiki — one step at a time:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
scripts/demo.sh # press Enter to advance
|
|
147
|
+
scripts/demo.sh --auto # no pauses (rehearsal)
|
|
148
|
+
scripts/demo.sh --from 7 # resume at step 7
|
|
149
|
+
scripts/demo.sh --reset # wipe the sandbox
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
It runs against a throwaway `$THETABOOK_HOME` (default `/tmp/thetabook-demo`, override with `DEMO_HOME`) seeded with a fictional book, so no real account data appears on screen, and it refuses to run against, inside, or around your real home. Market data is live: it borrows your `.env` and Schwab token, so run `thetabook refresh --reauth` first if the token is more than 7 days old. Without one it still runs off Massive/yfinance, and the tables flag the previous-close spot. `scripts/demo.sh --help` lists the environment overrides. `scripts/` isn't in the wheel, so this needs a clone.
|
|
153
|
+
|
|
141
154
|
## Daily / weekly workflow
|
|
142
155
|
|
|
143
156
|
In a Claude Code session inside this directory:
|
|
@@ -187,6 +200,7 @@ In between reviews, use **`/ideas`** to browse:
|
|
|
187
200
|
| `/diff [dates]` | Compare two snapshots: positions added/removed/changed, balance moves |
|
|
188
201
|
| `/accounts-init` | Scaffold `personal/accounts.toml` from latest snapshot (label each type)|
|
|
189
202
|
| `/wiki-lint` | Health check on the wiki (orphan ideas, stale stats, drift, missing) |
|
|
203
|
+
| `/backtest` | Hypothetical strategy backtest, parameter grid, or this period's signal |
|
|
190
204
|
|
|
191
205
|
> **Note on `/review`:** that name is taken by a Claude Code built-in (GitHub PR reviewer). Use `/portfolio` for portfolio review.
|
|
192
206
|
|
|
@@ -230,6 +244,12 @@ thetabook vrp AAPL # ATM IV vs realized HV, righ
|
|
|
230
244
|
thetabook scenarios match AAPL # historical analogues + forward returns
|
|
231
245
|
thetabook bars boundary AAPL # the defeatbeta/live stitch seam
|
|
232
246
|
|
|
247
|
+
# Backtests (hypothetical; stdout only unless --save)
|
|
248
|
+
thetabook backtest list # registered strategies + params
|
|
249
|
+
thetabook backtest run dual-momentum # vs benchmark / EW universe / cash, IS/OOS
|
|
250
|
+
thetabook backtest grid sector-rotation --vary n=2,3,4 --walk-forward # trials, deflated Sharpe
|
|
251
|
+
thetabook backtest signal sector-rotation # this period's book = last row of the run
|
|
252
|
+
|
|
233
253
|
# Accounts, tickers, wiki, skills
|
|
234
254
|
thetabook accounts check-portfolio --show-all --top 10
|
|
235
255
|
thetabook tickers add BRKB BRK/B
|
|
@@ -319,6 +339,10 @@ On transient failures (timeout / connection reset / 5xx), `fetch_prices_massive`
|
|
|
319
339
|
|
|
320
340
|
Option Greeks are far more price-sensitive than equity delta — a couple of dollars on a near-ATM strike flips the ITM flag and swings delta/theta — so `thetabook greeks` and `thetabook positions` **always re-price option underlyings live**, even when the snapshot is fresh. Equity-only tickers keep the cheaper gap-fill-only path. Both commands render a `Src` column and a freshness label (`live` / `prev-close` / `delayed` / `manual` / `snapshot <date>`) so a Massive previous-close or a snapshot fallback can't masquerade as a live quote. Details in [docs/behaviors.md](docs/behaviors.md).
|
|
321
341
|
|
|
342
|
+
### Backtests
|
|
343
|
+
|
|
344
|
+
`thetabook backtest` tests a systematic rule, such as sector rotation or SPY/TLT/GLD dual momentum, on total-return history built from the bars stitch. It enforces signal-at-close → trade-next-close timing, non-zero costs by default, and benchmarks with t-stats. The live `signal` is the last row of the same run, so the backtest and the weekly call can't drift apart. `backtest grid` sweeps parameters and prints how many configurations were tried. It ranks on in-sample results only, deflates the winner's Sharpe for the search (Bailey & López de Prado), and can chain a walk-forward out-of-sample series. Every output is stamped *hypothetical backtested performance*. Nothing is written to disk unless you pass `--save` to `run` or `grid`. That keeps an immutable manifest (payload, params, code version, data fingerprint) under `$THETABOOK_HOME/backtests/`, as a reproducible record for anything that might be shown to someone else. Flags are in [docs/cli.md](docs/cli.md) "Backtests"; conventions (TR basis, lag, costs, cash proxy, DSR, walk-forward timing) are in [docs/behaviors.md](docs/behaviors.md).
|
|
345
|
+
|
|
322
346
|
### Other runtime behaviors
|
|
323
347
|
|
|
324
348
|
Option-symbol parse failures (a one-time deduped warning rather than a silently dropped position), the share-asset filter that keeps `COLLECTIVE_INVESTMENT` ETFs like QQQ in scope, ticker aliases, Schwab token expiry and re-auth, per-account rules, and the idea-lifecycle CLI/Edit boundary are all covered in **[docs/behaviors.md](docs/behaviors.md)**.
|
|
@@ -395,6 +419,16 @@ thetabook/
|
|
|
395
419
|
│ │ ├── adjust.py # what-if adjustment modeling
|
|
396
420
|
│ │ └── roll_scenarios.py # roll scenario grid
|
|
397
421
|
│ │
|
|
422
|
+
│ ├── backtest/ # hypothetical strategy backtests + live signal (one code path)
|
|
423
|
+
│ │ ├── data.py # total-return panel: bars + dividends, holes, outlier screen
|
|
424
|
+
│ │ ├── engine.py # pure: targets → lagged, cost/borrow/cash-adjusted returns
|
|
425
|
+
│ │ ├── signals.py # pure: momentum, residual momentum, dispersion, rebalance dates
|
|
426
|
+
│ │ ├── metrics.py # pure: CAGR / Sharpe / MaxDD / active t / deflated Sharpe
|
|
427
|
+
│ │ ├── strategies/ # sector_rotation.py, dual_momentum.py + REGISTRY
|
|
428
|
+
│ │ ├── report.py # simulate() → backtest + signal reports
|
|
429
|
+
│ │ ├── grid.py # parameter sweeps: IS-only ranking, DSR, walk-forward
|
|
430
|
+
│ │ └── manifest.py # --save: run manifest + panel fingerprint; the only writer here
|
|
431
|
+
│ │
|
|
398
432
|
│ ├── wiki/ # personal/wiki/ health checks + auto-rendered ideas roll-up
|
|
399
433
|
│ │ ├── lint.py # compute_lint_report → render_lint_text/json (11 check IDs)
|
|
400
434
|
│ │ └── render.py # render_ideas_page (marker-region preservation)
|
|
@@ -419,7 +453,7 @@ thetabook/
|
|
|
419
453
|
│ │
|
|
420
454
|
│ └── cli/ # typer subcommands — `thetabook <cmd>` enters here
|
|
421
455
|
│ ├── CLAUDE.md # the add-a-subcommand checklist
|
|
422
|
-
│ ├── __init__.py # root Typer app (21 commands +
|
|
456
|
+
│ ├── __init__.py # root Typer app (21 commands + 8 sub-apps)
|
|
423
457
|
│ ├── _shared.py # shared option types (PricesOpt, MarksOpt, etc.)
|
|
424
458
|
│ └── <one file per command>
|
|
425
459
|
│
|
|
@@ -430,6 +464,7 @@ thetabook/
|
|
|
430
464
|
│ ├── journal/ # one markdown file per review session
|
|
431
465
|
│ ├── ideas/ # trade ideas (NNN-short-name.md)
|
|
432
466
|
│ ├── cache/bars/ # cached daily OHLCV (3-day TTL + version probe)
|
|
467
|
+
│ ├── backtests/ # immutable run manifests from `backtest run|grid --save`
|
|
433
468
|
│ ├── accounts.toml # per-account posture + rules (PII)
|
|
434
469
|
│ ├── config.toml # per-clone user overrides ([market], [adjust], [schwab], [skills])
|
|
435
470
|
│ ├── ticker_aliases.toml # user-added symbol aliases
|
|
@@ -464,15 +499,16 @@ thetabook/
|
|
|
464
499
|
├── .env.example # template for API credentials
|
|
465
500
|
│
|
|
466
501
|
└── .claude/
|
|
467
|
-
└── commands/ # project-level slash commands (
|
|
502
|
+
└── commands/ # project-level slash commands (18 commands)
|
|
468
503
|
├── setup.md / refresh.md / portfolio.md
|
|
469
504
|
├── idea.md / ideas.md / evaluate.md / adjust.md
|
|
470
505
|
├── open.md / close.md / roll.md / roll-scenarios.md
|
|
471
506
|
├── greeks.md / price.md / chain.md / diff.md
|
|
472
507
|
├── accounts-init.md / wiki-lint.md
|
|
508
|
+
├── backtest.md
|
|
473
509
|
```
|
|
474
510
|
|
|
475
|
-
The test
|
|
511
|
+
The current test count is pinned in [docs/README.md](docs/README.md) "Ownership rules". Four gates run on every change, all enforced in CI: `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy .`.
|
|
476
512
|
|
|
477
513
|
## Conventions
|
|
478
514
|
|