thetabook 2.1.2__tar.gz → 2.2.1__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.1.2 → thetabook-2.2.1}/CHANGELOG.md +130 -1
- {thetabook-2.1.2 → thetabook-2.2.1}/CLAUDE.md +5 -1
- {thetabook-2.1.2 → thetabook-2.2.1}/PKG-INFO +1 -1
- {thetabook-2.1.2 → thetabook-2.2.1}/README.md +42 -6
- {thetabook-2.1.2 → thetabook-2.2.1}/ROADMAP.md +44 -14
- {thetabook-2.1.2 → thetabook-2.2.1}/pyproject.toml +4 -1
- thetabook-2.2.1/src/thetabook/analysis/em.py +118 -0
- thetabook-2.2.1/src/thetabook/analysis/vrp.py +145 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/__init__.py +10 -1
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/_shared.py +21 -2
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/bars.py +24 -17
- thetabook-2.2.1/src/thetabook/cli/em.py +149 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/import_csv.py +5 -3
- thetabook-2.2.1/src/thetabook/cli/positions.py +79 -0
- thetabook-2.2.1/src/thetabook/cli/vrp.py +80 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/bars.py +242 -47
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/accounts.py +8 -1
- thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/__init__.py +55 -0
- thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/_base.py +118 -0
- thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/empower.py +208 -0
- thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/fidelity.py +161 -0
- thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/schwab.py +152 -0
- thetabook-2.2.1/src/thetabook/portfolio/import_csv_snapshot.py +132 -0
- thetabook-2.2.1/src/thetabook/portfolio/options_book.py +431 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/accounts.toml.example +17 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/uv.lock +1 -1
- thetabook-2.1.2/.claude/commands/accounts-init.md +0 -45
- thetabook-2.1.2/.claude/commands/adjust.md +0 -84
- thetabook-2.1.2/.claude/commands/chain.md +0 -57
- thetabook-2.1.2/.claude/commands/close.md +0 -51
- thetabook-2.1.2/.claude/commands/diff.md +0 -47
- thetabook-2.1.2/.claude/commands/evaluate.md +0 -48
- thetabook-2.1.2/.claude/commands/greeks.md +0 -35
- thetabook-2.1.2/.claude/commands/idea.md +0 -48
- thetabook-2.1.2/.claude/commands/ideas.md +0 -29
- thetabook-2.1.2/.claude/commands/open.md +0 -40
- thetabook-2.1.2/.claude/commands/portfolio.md +0 -59
- thetabook-2.1.2/.claude/commands/price.md +0 -28
- thetabook-2.1.2/.claude/commands/refresh.md +0 -9
- thetabook-2.1.2/.claude/commands/roll-scenarios.md +0 -72
- thetabook-2.1.2/.claude/commands/roll.md +0 -125
- thetabook-2.1.2/.claude/commands/setup.md +0 -98
- thetabook-2.1.2/.claude/commands/wiki-lint.md +0 -77
- thetabook-2.1.2/docs/architecture.md +0 -406
- thetabook-2.1.2/docs/behaviors.md +0 -138
- thetabook-2.1.2/docs/cli.md +0 -136
- thetabook-2.1.2/docs/hosted-service-proposal.md +0 -113
- thetabook-2.1.2/docs/m23-audit.md +0 -43
- thetabook-2.1.2/docs/skills-roadmap.md +0 -174
- thetabook-2.1.2/docs/skills.md +0 -91
- thetabook-2.1.2/src/thetabook/portfolio/import_csv_snapshot.py +0 -397
- thetabook-2.1.2/tests/analysis/test_hv.py +0 -133
- thetabook-2.1.2/tests/analysis/test_scenarios.py +0 -364
- thetabook-2.1.2/tests/analysis/test_ta.py +0 -310
- thetabook-2.1.2/tests/cli/test_analysis_cli.py +0 -658
- thetabook-2.1.2/tests/cli/test_bs_cli.py +0 -120
- thetabook-2.1.2/tests/cli/test_init.py +0 -480
- thetabook-2.1.2/tests/cli/test_migrate_home.py +0 -183
- thetabook-2.1.2/tests/conftest.py +0 -277
- thetabook-2.1.2/tests/ideas/test_adjust.py +0 -1739
- thetabook-2.1.2/tests/ideas/test_core.py +0 -288
- thetabook-2.1.2/tests/ideas/test_evaluate_idea.py +0 -1921
- thetabook-2.1.2/tests/ideas/test_manage_ideas.py +0 -759
- thetabook-2.1.2/tests/ideas/test_roll_scenarios.py +0 -729
- thetabook-2.1.2/tests/market/test_bars.py +0 -884
- thetabook-2.1.2/tests/market/test_chains.py +0 -654
- thetabook-2.1.2/tests/market/test_dividends.py +0 -780
- thetabook-2.1.2/tests/market/test_earnings.py +0 -321
- thetabook-2.1.2/tests/market/test_leg_marks.py +0 -106
- thetabook-2.1.2/tests/market/test_prices.py +0 -658
- thetabook-2.1.2/tests/market/test_schwab.py +0 -106
- thetabook-2.1.2/tests/market/test_vol_lookup.py +0 -372
- thetabook-2.1.2/tests/portfolio/test_accounts.py +0 -981
- thetabook-2.1.2/tests/portfolio/test_diff_snapshots.py +0 -356
- thetabook-2.1.2/tests/portfolio/test_get_positions.py +0 -495
- thetabook-2.1.2/tests/portfolio/test_import_csv_snapshot.py +0 -375
- thetabook-2.1.2/tests/portfolio/test_scaffold.py +0 -92
- thetabook-2.1.2/tests/pricing/test_bs.py +0 -254
- thetabook-2.1.2/tests/pricing/test_greeks.py +0 -828
- thetabook-2.1.2/tests/skills/__init__.py +0 -0
- thetabook-2.1.2/tests/skills/conftest.py +0 -52
- thetabook-2.1.2/tests/skills/test_install.py +0 -641
- thetabook-2.1.2/tests/skills/test_lint.py +0 -220
- thetabook-2.1.2/tests/skills/test_models.py +0 -96
- thetabook-2.1.2/tests/skills/test_parse.py +0 -70
- thetabook-2.1.2/tests/skills/test_policy.py +0 -54
- thetabook-2.1.2/tests/skills/test_registry.py +0 -388
- thetabook-2.1.2/tests/skills/test_render.py +0 -55
- thetabook-2.1.2/tests/test_cache.py +0 -149
- thetabook-2.1.2/tests/test_cli.py +0 -800
- thetabook-2.1.2/tests/test_config.py +0 -77
- thetabook-2.1.2/tests/test_factories.py +0 -92
- thetabook-2.1.2/tests/test_leg_parse.py +0 -228
- thetabook-2.1.2/tests/test_log.py +0 -42
- thetabook-2.1.2/tests/test_models.py +0 -412
- thetabook-2.1.2/tests/test_paths.py +0 -502
- thetabook-2.1.2/tests/test_tickers.py +0 -262
- thetabook-2.1.2/tests/wiki/test_lint.py +0 -1069
- thetabook-2.1.2/tests/wiki/test_render.py +0 -442
- {thetabook-2.1.2 → thetabook-2.2.1}/.env.example +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/.github/workflows/ci.yml +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/.github/workflows/publish.yml +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/.gitignore +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/.python-version +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/CONTRIBUTING.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/LICENSE +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/SECURITY.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/hv.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/scenarios.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/ta.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cache.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/accounts.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/adjust.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/bs.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/chain.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/diff.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/dividends.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/earnings.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/evaluate.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/greeks.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/hv.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/ideas.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/init.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/leg_mark.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/migrate_home.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/price.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/refresh.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/roll.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/scenarios.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/skills.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/snapshot.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/ta.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/tickers.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/wiki.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/config.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/adjust.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/core.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/evaluate_idea.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/manage_ideas.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/roll_scenarios.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/leg_parse.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/log.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/_schwab.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/chains.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/dividends.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/earnings.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/leg_marks.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/prices.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/vol_lookup.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/models.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/paths.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/diff_snapshots.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/get_positions.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/scaffold.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/pricing/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/pricing/bs.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/pricing/greeks.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/install.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/lint.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/models.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/parse.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/policy.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/registry.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/render.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/README.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/config.toml.example +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/idea.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/journal.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/learnings.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/skill.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/skills/setup-thetabook.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/index.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/log.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/overview.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/strategy.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/underlying.md +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/tickers.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/wiki/__init__.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/wiki/lint.py +0 -0
- {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/wiki/render.py +0 -0
|
@@ -3,7 +3,136 @@
|
|
|
3
3
|
All notable changes to this project are recorded here. Format loosely follows
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com). Dates are ISO 8601.
|
|
5
5
|
|
|
6
|
-
## [
|
|
6
|
+
## [2.2.1] — 2026-06-05
|
|
7
|
+
|
|
8
|
+
Two pending medium-priority roadmap items (M24 expected-move / VRP, M20
|
|
9
|
+
effective options book) close out, and the historical-bars backbone's rolling
|
|
10
|
+
tail is re-routed through the live price cascade so `hv` / `ta` / `scenarios`
|
|
11
|
+
stay numerically consistent with `price` / `chain` / `greeks`.
|
|
12
|
+
**1696 tests pass, ruff + mypy clean.**
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **`thetabook positions` — effective options book** (M20). Renders the
|
|
17
|
+
options-only table /portfolio reviews previously reconstructed by hand —
|
|
18
|
+
per-leg live mark (chain cascade), underlying spot, **cushion**, and
|
|
19
|
+
calendar DTE, grouped by account. Cushion is the short-seller OTM buffer,
|
|
20
|
+
signed so positive = out-of-the-money (safe) and negative = in-the-money
|
|
21
|
+
(danger) for both legs (`call: (K−S)/S`, `put: (S−K)/S`). Defaults to the
|
|
22
|
+
options view; `--equity` lists share-like holdings, `--all` shows both.
|
|
23
|
+
`--no-fetch` uses snapshot marks only; `--prices TICKER=X` overrides spot;
|
|
24
|
+
`--mark-mode` picks conservative vs mid. Spot resolution reuses the live
|
|
25
|
+
price cascade — Schwab (real-time) → Massive (previous-day close) →
|
|
26
|
+
yfinance (~15-min delayed) — under the same stale-snapshot policy as
|
|
27
|
+
`greeks`: a stale snapshot refreshes every underlying, a fresh one only
|
|
28
|
+
fills the gaps (option-only underlyings, which carry no snapshot share
|
|
29
|
+
price, always fetch). Per-leg marks come from the chain cascade and fall
|
|
30
|
+
back to the snapshot's stored mark when a strike has no live quote. Non-live
|
|
31
|
+
spot provenance (Massive previous-close, yfinance delayed) is flagged in a
|
|
32
|
+
footnote, the same convention `greeks` uses. New
|
|
33
|
+
`portfolio/options_book.py` stitches the snapshot loader + spot fetch from
|
|
34
|
+
`pricing.greeks`, the per-leg re-mark from `market.leg_marks`, and account
|
|
35
|
+
labels from `portfolio.accounts`; pure extract/cushion/render functions
|
|
36
|
+
keep the math hermetically testable.
|
|
37
|
+
|
|
38
|
+
- **`thetabook em` — expected move** ([#64](https://github.com/subsriram/thetabook/pull/64)).
|
|
39
|
+
Translates a vol figure into the ±1σ / ±2σ dollar range an option is pricing
|
|
40
|
+
by expiry: `spot · σ · sqrt(DTE/365)` (calendar-day horizon, the straddle
|
|
41
|
+
convention — deliberately *not* `hv`'s `sqrt(252)` annualization). Sigma
|
|
42
|
+
defaults to HV20, with `--iv` to override or `--source iv` to pull
|
|
43
|
+
front-month ATM IV off the chain (expiry auto-picked nearest the target DTE).
|
|
44
|
+
Pure math lives in `analysis/em.py`.
|
|
45
|
+
- **`thetabook vrp` — vol-risk-premium** ([#64](https://github.com/subsriram/thetabook/pull/64)).
|
|
46
|
+
Ratios front-month ATM implied vol against realized HV to answer "is implied
|
|
47
|
+
richer than realized right now?" — a *point-in-time* IV-vs-HV read, **not** a
|
|
48
|
+
historical IV-rank (no source ships historical option IV). Needs a
|
|
49
|
+
Greeks-bearing source (Schwab/Massive) for IV; exits non-zero on a
|
|
50
|
+
yfinance-only fallback rather than printing a bogus ratio. The ATM picker
|
|
51
|
+
(`analysis/vrp.atm_iv`) skips strikes with no usable IV and averages the
|
|
52
|
+
call+put IV at the nearest populated strike, and is shared with `em --source iv`.
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
|
|
56
|
+
- **Bars tail-fill now rides the live price cascade** ([#66](https://github.com/subsriram/thetabook/pull/66), closes #65).
|
|
57
|
+
The historical-bars backbone (`market/bars.py`) stitched defeatbeta deep
|
|
58
|
+
history with a **yfinance-only** rolling tail. yfinance is ~15-min delayed
|
|
59
|
+
and created a source-disagreement seam between `price` (Schwab → Massive →
|
|
60
|
+
yfinance) and `hv` / `ta` / `scenarios` (yfinance-only tail). The tail now
|
|
61
|
+
flows through the **same cascade as the live price pipeline — Schwab →
|
|
62
|
+
Massive → yfinance** (first source with tail data wins); defeatbeta stays the
|
|
63
|
+
deep-history source, only the tail changed. New `_fetch_schwab`
|
|
64
|
+
(`get_price_history_every_day`), `_fetch_massive` (Polygon `get_aggs`
|
|
65
|
+
date-range daily aggregates — not the single-bar `get_previous_close_agg`),
|
|
66
|
+
a shared `_normalize_epoch_ohlcv` (volume kept int64 so the stitched frame
|
|
67
|
+
doesn't promote to float on concat), and `_fetch_tail` returning
|
|
68
|
+
`(frame, source)`. `bars compare TICKER` now diffs defeatbeta vs the live
|
|
69
|
+
cascade and surfaces which source served the tail (`_yf` columns renamed
|
|
70
|
+
`_live`, plus a `source` column). Validated live: AAPL (non-payer) and O
|
|
71
|
+
(dividend payer) both served by Schwab with 0 rows flagged, and again with
|
|
72
|
+
Schwab disabled so Massive serves the tail — 0.000% close drift across O's
|
|
73
|
+
ex-dividend days, confirming the split-only (`adjusted=True`) close matches
|
|
74
|
+
defeatbeta with no off-by-one in the epoch-ms normalization.
|
|
75
|
+
|
|
76
|
+
## [2.2.0] — 2026-06-04
|
|
77
|
+
|
|
78
|
+
Multi-broker CSV import. The Schwab/Fidelity CSV importer is rebuilt as a
|
|
79
|
+
format-agnostic parser registry, **Empower** (employer 401(k) / EquatePlus)
|
|
80
|
+
joins the supported brokers, and adding the next broker is now a subclass +
|
|
81
|
+
one-line registration. No changes to the trading/analysis CLIs.
|
|
82
|
+
**1604 tests pass, ruff + mypy clean.**
|
|
83
|
+
|
|
84
|
+
### Added
|
|
85
|
+
|
|
86
|
+
- **Empower Holdings CSV import** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
87
|
+
`import-csv` now recognizes Empower's multi-account holdings export
|
|
88
|
+
(equities, ETFs, mutual funds, and options) alongside Schwab and Fidelity.
|
|
89
|
+
- **Extensible broker CSV parser registry** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
90
|
+
The monolithic `import_csv_snapshot.py` is split into a `portfolio/csv_parsers/`
|
|
91
|
+
package: a `BrokerCsvParser` ABC (`detect()` / `parse()`), one module per
|
|
92
|
+
broker, and a `REGISTRY` walked by `detect_and_parse()` (first match wins,
|
|
93
|
+
most-specific first). A new broker is a subclass + a line in `REGISTRY` — no
|
|
94
|
+
changes to the importer or CLI. Format is auto-detected per file, so one
|
|
95
|
+
`import-csv` invocation can mix exports from different brokers.
|
|
96
|
+
- **`instrument_symbol` per-account override** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
97
|
+
For single-stock employer plans (e.g. EquatePlus) whose Fidelity rows carry
|
|
98
|
+
no ticker, `accounts.toml` can map the account to a symbol so the shares
|
|
99
|
+
import with the right underlying. Documented in `accounts.toml.example`.
|
|
100
|
+
|
|
101
|
+
### Changed
|
|
102
|
+
|
|
103
|
+
- **Account numbers stored as the broker exposes them** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
104
|
+
Fidelity and Empower numbers are now stored verbatim; Schwab stays masked to
|
|
105
|
+
`****<last4>` because the export only carries the last four (a broker
|
|
106
|
+
limitation, not a masking decision). `import-csv` warns when a now-verbatim
|
|
107
|
+
number no longer matches a masked `****<last4>` key left in `accounts.toml`,
|
|
108
|
+
so per-account rules don't silently stop matching — re-key or re-run
|
|
109
|
+
`/accounts-init`.
|
|
110
|
+
- **Empower account subtype feeds `/accounts-init`** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
111
|
+
Empower exports tell us Roth vs. traditional, so `accounts totals` surfaces a
|
|
112
|
+
`roth-401k` / `traditional-401k` suggestion for unconfigured accounts instead
|
|
113
|
+
of a bare `?` — unlike Schwab, which can't distinguish IRA from taxable.
|
|
114
|
+
- **`import_csv_snapshot.py` reduced to a thin entry point** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
115
|
+
The legacy `parse_schwab_csv` / `parse_fidelity_csv` shim functions were
|
|
116
|
+
removed; callers use the `csv_parsers` package directly.
|
|
117
|
+
- **sdist excludes `personal/`, `.claude/`, `tests/`, `docs/`** ([#62](https://github.com/subsriram/thetabook/pull/62)).
|
|
118
|
+
Smaller source distribution that no longer risks shipping local PII fixtures.
|
|
119
|
+
|
|
120
|
+
### Fixed
|
|
121
|
+
|
|
122
|
+
- **`parse_money` handles the `$-114.50` ordering** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
123
|
+
A negative sign after the currency symbol is now parsed as negative (only the
|
|
124
|
+
`-$114.50` and `($114.50)` forms worked before).
|
|
125
|
+
- **Empower import fails cleanly on a malformed file** ([#56](https://github.com/subsriram/thetabook/pull/56)).
|
|
126
|
+
A Holdings CSV missing a required column now warns and skips the file instead
|
|
127
|
+
of raising `KeyError` mid-parse.
|
|
128
|
+
|
|
129
|
+
### Docs
|
|
130
|
+
|
|
131
|
+
- Documented Empower support, the `csv_parsers/` package, and the `import-csv`
|
|
132
|
+
command across README, `docs/cli.md`, and `docs/architecture.md`
|
|
133
|
+
([#56](https://github.com/subsriram/thetabook/pull/56)); documented the
|
|
134
|
+
v2.1.x technical-analysis stack across the reference docs
|
|
135
|
+
([#63](https://github.com/subsriram/thetabook/pull/63)).
|
|
7
136
|
|
|
8
137
|
## [2.1.2] — 2026-06-01
|
|
9
138
|
|
|
@@ -22,6 +22,9 @@ The name nods to **theta**, the daily decay that quietly drives most options P&L
|
|
|
22
22
|
|
|
23
23
|
- **Use the `thetabook` CLI as much as possible** to fetch data, answer questions, and run analysis. The CLI loads `.env`, applies the source cascade (Schwab → Massive → yfinance), and uses consistent IV/rate/yield conventions. Examples: `thetabook chain ... --greeks`, `thetabook evaluate <id>`, `thetabook greeks`, `thetabook price`, `thetabook dividends -v`. Don't reach for `uv run python -c "from thetabook... import"` when a CLI command exists for the same job.
|
|
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
|
+
- **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
|
+
- **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
|
+
- **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. 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.
|
|
25
28
|
|
|
26
29
|
## Repo layout
|
|
27
30
|
|
|
@@ -54,12 +57,13 @@ For the rationale behind the layers, the data-flow diagram, the source cascade,
|
|
|
54
57
|
|
|
55
58
|
## Running things
|
|
56
59
|
|
|
57
|
-
After `uv sync`, every CLI lives under a single `thetabook` umbrella. The full subcommand list grouped by area (snapshots, evaluate/adjust, ideas lifecycle, Greeks, chain, earnings/dividends, accounts, tickers, wiki, skills) lives in [docs/cli.md](docs/cli.md). The typical loop:
|
|
60
|
+
After `uv sync`, every CLI lives under a single `thetabook` umbrella. The full subcommand list grouped by area (snapshots, evaluate/adjust, ideas lifecycle, Greeks, chain, technical analysis, earnings/dividends, accounts, tickers, wiki, skills) lives in [docs/cli.md](docs/cli.md). The typical loop:
|
|
58
61
|
|
|
59
62
|
```bash
|
|
60
63
|
thetabook refresh # pull positions from Schwab → personal/snapshots/YYYY-MM-DD.json
|
|
61
64
|
thetabook snapshot # show latest snapshot freshness
|
|
62
65
|
thetabook greeks # portfolio Greeks from latest snapshot
|
|
66
|
+
thetabook positions # effective options book (live mark, spot, cushion, DTE) by account
|
|
63
67
|
thetabook evaluate <id> # P&L, PoP, Greeks for an idea (live re-marks)
|
|
64
68
|
thetabook chain AAPL 2026-06-20 --type put # browse a chain
|
|
65
69
|
thetabook ideas record-fill <id> --price 2.95 --qty -1 # status transitions go through the CLI
|
|
@@ -107,7 +107,7 @@ This is a one-shot move of `.env` + `schwab_token.json` into `personal/` so the
|
|
|
107
107
|
|
|
108
108
|
### Bootstrapping from a CSV instead of the Schwab API
|
|
109
109
|
|
|
110
|
-
If you want to try thetabook before going through Schwab dev-app approval, export positions as CSV and import them.
|
|
110
|
+
If you want to try thetabook before going through Schwab dev-app approval, export positions as CSV and import them. Schwab, Fidelity, and Empower CSV formats are auto-detected:
|
|
111
111
|
|
|
112
112
|
```bash
|
|
113
113
|
# Schwab: Positions tab → Export
|
|
@@ -116,8 +116,11 @@ thetabook import-csv path/to/Individual-Positions-*.csv path/to/Joint-Positions-
|
|
|
116
116
|
# Fidelity: Positions → Download
|
|
117
117
|
thetabook import-csv path/to/Portfolio_Positions.csv
|
|
118
118
|
|
|
119
|
+
# Empower: Holdings → Export
|
|
120
|
+
thetabook import-csv path/to/holdings.csv
|
|
121
|
+
|
|
119
122
|
# Mixed: multiple brokers in one snapshot
|
|
120
|
-
thetabook import-csv schwab.csv fidelity.csv
|
|
123
|
+
thetabook import-csv schwab.csv fidelity.csv empower.csv
|
|
121
124
|
```
|
|
122
125
|
|
|
123
126
|
This produces the same snapshot format as the API path, so everything downstream works identically. Both option symbols and cash balances are handled.
|
|
@@ -183,7 +186,7 @@ Every workflow runs through the unified `thetabook` console script (installed by
|
|
|
183
186
|
thetabook refresh # fetch & snapshot from Schwab API
|
|
184
187
|
thetabook snapshot # path | fetched_at | age | fresh|stale | counts
|
|
185
188
|
thetabook snapshot --path # absolute path only (for shell substitution)
|
|
186
|
-
thetabook import-csv <csv> [<csv> ...] # import Schwab or
|
|
189
|
+
thetabook import-csv <csv> [<csv> ...] # import Schwab, Fidelity, or Empower CSV exports
|
|
187
190
|
thetabook migrate # one-time: move pre-v1 dirs under personal/
|
|
188
191
|
|
|
189
192
|
# Snapshot diff
|
|
@@ -224,6 +227,11 @@ thetabook greeks --vol 0.30 --rate 0.05 # flat --vol override
|
|
|
224
227
|
thetabook greeks --prices AAPL=185 NVDA=800 # manual price overrides
|
|
225
228
|
thetabook greeks --no-fetch # skip auto price fetch
|
|
226
229
|
|
|
230
|
+
# Effective options book (live mark, spot, cushion, DTE, by account)
|
|
231
|
+
thetabook positions # options book (default view)
|
|
232
|
+
thetabook positions --equity # share-like holdings
|
|
233
|
+
thetabook positions --all # both tables
|
|
234
|
+
|
|
227
235
|
# Stock prices (Schwab → Massive → yfinance cascade)
|
|
228
236
|
thetabook price AAPL SPY
|
|
229
237
|
|
|
@@ -248,6 +256,16 @@ thetabook dividends AAPL # yield + next ex-div for one
|
|
|
248
256
|
thetabook dividends AAPL T VZ # multiple; exit 1 if none paying
|
|
249
257
|
thetabook dividends AAPL --no-cache # force a fresh yfinance fetch
|
|
250
258
|
|
|
259
|
+
# Technical analysis on historical bars (defeatbeta deep history + yfinance tail)
|
|
260
|
+
thetabook hv AAPL # realized vol + HV-rank/percentile (IV-rank substitute)
|
|
261
|
+
thetabook ta AAPL # RSI / MACD / Bollinger with interpretive labels
|
|
262
|
+
thetabook ta AAPL --indicator rsi --series # one indicator, full rolling series
|
|
263
|
+
thetabook scenarios features AAPL # today's 4-feature regime vector + reading
|
|
264
|
+
thetabook scenarios match AAPL # trajectory analogues + forward returns (5/20/60/120d)
|
|
265
|
+
thetabook scenarios match AAPL --mode state # match current regime instead of recent-move shape
|
|
266
|
+
thetabook bars boundary AAPL # defeatbeta's last date (the stitch seam — usually last Fri)
|
|
267
|
+
thetabook bars actions AAPL --type split # corporate actions (splits / dividends)
|
|
268
|
+
|
|
251
269
|
# Per-account rules + tax notes (reads personal/accounts.toml)
|
|
252
270
|
thetabook accounts show # posture line per account (nickname + last4)
|
|
253
271
|
thetabook accounts totals # NLV / cash table per account, sorted by liquidation desc
|
|
@@ -378,11 +396,23 @@ thetabook/
|
|
|
378
396
|
│ │ ├── vol_lookup.py # per-leg IV, ATM IV, leg marks (shared cache)
|
|
379
397
|
│ │ ├── leg_marks.py # fetch_leg_mark + pick_mark (conservative/mid)
|
|
380
398
|
│ │ ├── earnings.py # upcoming-earnings lookup (7-day on-disk cache)
|
|
381
|
-
│ │
|
|
399
|
+
│ │ ├── dividends.py # yield + next ex-div lookup (7-day on-disk cache)
|
|
400
|
+
│ │ └── bars.py # historical daily OHLCV (defeatbeta deep history + yfinance tail, stitched)
|
|
401
|
+
│ │
|
|
402
|
+
│ ├── analysis/ # derived signals computed on historical bars
|
|
403
|
+
│ │ ├── hv.py # realized vol + HV-rank/percentile (the IV-rank substitute)
|
|
404
|
+
│ │ ├── ta.py # RSI / MACD / Bollinger Bands (pure functions on a close series)
|
|
405
|
+
│ │ └── scenarios.py # historical-analogue lookup (trajectory + state) with forward returns
|
|
382
406
|
│ │
|
|
383
407
|
│ ├── portfolio/ # snapshot I/O + per-account rules
|
|
384
408
|
│ │ ├── get_positions.py # Schwab API → snapshot (OAuth via schwab-py)
|
|
385
|
-
│ │ ├── import_csv_snapshot.py #
|
|
409
|
+
│ │ ├── import_csv_snapshot.py # broker CSV → snapshot (entry point; delegates to csv_parsers/)
|
|
410
|
+
│ │ ├── csv_parsers/ # per-broker CSV format handlers (extensible via BrokerCsvParser)
|
|
411
|
+
│ │ │ ├── __init__.py # REGISTRY + detect_and_parse() dispatch
|
|
412
|
+
│ │ │ ├── _base.py # BrokerCsvParser ABC + shared helpers
|
|
413
|
+
│ │ │ ├── schwab.py # Schwab positions export
|
|
414
|
+
│ │ │ ├── fidelity.py # Fidelity FullView export
|
|
415
|
+
│ │ │ └── empower.py # Empower Holdings export
|
|
386
416
|
│ │ ├── diff_snapshots.py # compare two snapshots
|
|
387
417
|
│ │ ├── accounts.py # per-account risk rules + tax notes
|
|
388
418
|
│ │ └── migrate_to_personal.py # one-time migration from pre-v1 layout
|
|
@@ -445,7 +475,13 @@ thetabook/
|
|
|
445
475
|
│ │ ├── test_vol_lookup.py
|
|
446
476
|
│ │ ├── test_leg_marks.py
|
|
447
477
|
│ │ ├── test_earnings.py
|
|
448
|
-
│ │
|
|
478
|
+
│ │ ├── test_dividends.py
|
|
479
|
+
│ │ └── test_bars.py
|
|
480
|
+
│ │
|
|
481
|
+
│ ├── analysis/
|
|
482
|
+
│ │ ├── test_hv.py
|
|
483
|
+
│ │ ├── test_ta.py
|
|
484
|
+
│ │ └── test_scenarios.py
|
|
449
485
|
│ │
|
|
450
486
|
│ ├── portfolio/
|
|
451
487
|
│ │ ├── test_get_positions.py
|
|
@@ -4,7 +4,7 @@ Single source of truth for enhancement work. Supersedes the separate `IMPROVEMEN
|
|
|
4
4
|
|
|
5
5
|
> "Ideas" in this file means *project enhancements*. Trade ideas live in `personal/ideas/`.
|
|
6
6
|
|
|
7
|
-
Last updated: 2026-05
|
|
7
|
+
Last updated: 2026-06-05 | Current: v2.2.1 | Release notes: [CHANGELOG.md](CHANGELOG.md)
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
@@ -12,6 +12,37 @@ Last updated: 2026-05-26 | Current: v2.1.0 | Release notes: [CHANGELOG.md](CHANG
|
|
|
12
12
|
|
|
13
13
|
Items shipped with their originating commit. Listed newest first.
|
|
14
14
|
|
|
15
|
+
### v2.2.1 — vol-to-decision pair (M24) + effective options book (M20) + bars live-cascade tail-fill
|
|
16
|
+
Two pending medium-priority items closed out plus a bars-backbone consistency fix. The vol-to-decision pair (`em` / `vrp`) shipped first ([PR #64](https://github.com/subsriram/thetabook/pull/64), [9c58ba1](https://github.com/subsriram/thetabook/commit/9c58ba1)); the effective options-book table (`positions`) followed ([#67](https://github.com/subsriram/thetabook/pull/67)); and the historical-bars rolling tail was re-routed through the live price cascade ([#66](https://github.com/subsriram/thetabook/pull/66)). **1696 tests pass, ruff + mypy clean.**
|
|
17
|
+
|
|
18
|
+
- **M24 — expected move + vol-risk-premium.** `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); sigma defaults to HV20 with `--iv` / `--source iv` overrides. `thetabook vrp TICKER` ratios front-month ATM IV against realized HV — a point-in-time IV-vs-HV read (not a historical IV-rank), exiting non-zero on a yfinance-only fallback rather than printing a bogus ratio. Pure math in `analysis/em.py`; the ATM picker (`analysis/vrp.atm_iv`, shared with `em --source iv`) skips IV-less strikes and averages call+put at the nearest populated strike.
|
|
19
|
+
|
|
20
|
+
- **M20 — effective options book.** `thetabook positions --options` (the default view; `--equity` / `--all` for the others) renders the options-only table /portfolio reviews previously reconstructed by hand: per-leg live mark (chain cascade), underlying spot, **cushion** (the short-seller OTM buffer — positive = OTM/safe, negative = ITM/danger, computed `call:(K−S)/S` / `put:(S−K)/S` so the danger sign reads correctly for both legs), and calendar DTE, grouped by account. New `portfolio/options_book.py` stitches the snapshot loader + spot fetch from `pricing.greeks`, the per-leg live re-mark from `market.leg_marks`, and account labels from `portfolio.accounts`; pure extract/cushion/render functions keep the math testable and the fetch helpers (`resolve_spots` / `resolve_marks`) are the monkeypatch surface. Non-live spot provenance (Massive previous-close, yfinance delayed) is flagged in a footnote the same way `greeks` does. `--no-fetch` / `--prices` honored. The cushion sign deliberately follows the ROADMAP's stated "negative = ITM, danger" intent rather than its loosely-computed worked example. A review-found bug — the per-leg mark dedup keyed on the option series without the long/short side, so the same series held long in one account and short in another collapsed to one conservative-mode pick — was fixed by keying the picked mark on `(series, qty ≥ 0)`.
|
|
21
|
+
|
|
22
|
+
- **Bars live-cascade tail-fill ([#66](https://github.com/subsriram/thetabook/pull/66), closes #65).** The historical-bars rolling tail moved from a yfinance-only fill to the **same cascade as the live price pipeline — Schwab → Massive → yfinance** (first source with tail data wins); defeatbeta stays the deep-history source. Removes the source-disagreement seam between `price` and `hv`/`ta`/`scenarios`. `bars compare` now surfaces which live source served the tail. Validated live (AAPL + O) with both Schwab and Massive serving the tail: 0 rows flagged, 0.000% close drift across ex-dividend days.
|
|
23
|
+
|
|
24
|
+
### v2.2.0 — multi-broker CSV import: Empower + format-agnostic parser registry
|
|
25
|
+
The Schwab/Fidelity CSV importer rebuilt as a format-agnostic parser registry, with **Empower** (employer 401(k) / EquatePlus) joining the supported brokers. Adding the next broker is now a subclass + one-line registration. No changes to the trading/analysis CLIs. Shipped as [PR #56](https://github.com/subsriram/thetabook/pull/56) ([fd9664a](https://github.com/subsriram/thetabook/commit/fd9664a)), closing #54. **1604 tests pass, ruff + mypy clean.**
|
|
26
|
+
|
|
27
|
+
- **Extensible broker CSV parser registry.** The monolithic `import_csv_snapshot.py` is split into a `portfolio/csv_parsers/` package: a `BrokerCsvParser` ABC (`detect()` / `parse()`), one module per broker (`schwab.py`, `fidelity.py`, `empower.py`), and a `REGISTRY` walked by `detect_and_parse()` (first match wins, most-specific first). A new broker is a subclass + a line in `REGISTRY` — no edits to the importer or CLI. Format is auto-detected per file, so a single `import-csv` invocation can mix exports from different brokers. `import_csv_snapshot.py` is reduced to a thin entry point; the legacy `parse_schwab_csv` / `parse_fidelity_csv` shim functions were removed (callers use the `csv_parsers` package directly).
|
|
28
|
+
|
|
29
|
+
- **Empower Holdings CSV import.** `import-csv` recognizes Empower's multi-account holdings export (equities, ETFs, mutual funds, options) alongside Schwab and Fidelity. Because Empower exports carry the account subtype, `accounts totals` surfaces a `roth-401k` / `traditional-401k` suggestion for unconfigured accounts instead of a bare `?` (unlike Schwab, which can't distinguish IRA from taxable). Malformed files (missing a required column) warn and skip rather than raising `KeyError` mid-parse.
|
|
30
|
+
|
|
31
|
+
- **`instrument_symbol` per-account override.** For single-stock employer plans (e.g. EquatePlus) whose Fidelity rows carry no ticker, `accounts.toml` can map the account to a symbol so the shares import with the right underlying. Documented in `accounts.toml.example`.
|
|
32
|
+
|
|
33
|
+
- **Account numbers stored as the broker exposes them.** Fidelity and Empower numbers are stored verbatim; Schwab stays masked to `****<last4>` because the export only carries the last four (a broker limitation, not a masking decision). `import-csv` warns when a now-verbatim number no longer matches a masked `****<last4>` key left in `accounts.toml`, so per-account rules don't silently stop matching — re-key or re-run `/accounts-init`.
|
|
34
|
+
|
|
35
|
+
- **`parse_money` handles the `$-114.50` ordering.** A negative sign after the currency symbol now parses as negative (previously only `-$114.50` and `($114.50)` worked).
|
|
36
|
+
|
|
37
|
+
- **Packaging + docs.** sdist now excludes `personal/`, `.claude/`, `tests/`, `docs/` ([#62](https://github.com/subsriram/thetabook/pull/62)) — smaller distribution that no longer risks shipping local PII fixtures. Empower support, the `csv_parsers/` package, and the `import-csv` command are documented across README, `docs/cli.md`, `docs/architecture.md` ([#56](https://github.com/subsriram/thetabook/pull/56)); the v2.1.x technical-analysis stack is documented across the reference docs ([#63](https://github.com/subsriram/thetabook/pull/63)).
|
|
38
|
+
|
|
39
|
+
### v2.1.2 — ship v2.1.x to PyPI + first-run setup fixes
|
|
40
|
+
First-time-setup bug fixes plus a CI hardening so releases stop being hostage to the GitHub Actions artifact-storage quota. No changes to the trading/analysis CLIs. **1564 tests pass, ruff + mypy clean.** v2.1.1's tag push had failed to publish on the pre-#59 artifact-handoff layout (storage quota); 2.1.2 supersedes it and is the first PyPI release after 2.0.0 to carry the v2.1.x feature set.
|
|
41
|
+
|
|
42
|
+
- **`thetabook init` / `/setup-thetabook` setup flow** ([#58](https://github.com/subsriram/thetabook/pull/58)). Three bugs broke first-time setup end to end: (1) the skill installer mirrored the source's flat form into `.claude/skills/<slug>.md`, but Claude Code only discovers folder form (`<slug>/SKILL.md`) — the installer now always normalizes to folder form at the destination and treats a pre-existing flat file as a prior install of the same slug; (2) `init --non-interactive` hit EOF on schwab-py's "Press ENTER" prompt because `--app-secret-stdin` consumes stdin — `_run_oauth` now passes `interactive=False`; (3) `init` wrote `SCHWAB_APP_KEY` while the rest of the app reads `SCHWAB_API_KEY` — the `.env` writer now emits the canonical key.
|
|
43
|
+
|
|
44
|
+
- **`publish.yml` — build + publish merged into one job** ([#59](https://github.com/subsriram/thetabook/pull/59)). The two-job layout handed `dist/` between jobs via `upload-artifact` → `download-artifact`, making every release hostage to the account-level artifact-storage quota (exactly what blocked the v2.1.1 publish). Build and publish now share one runner; `dist/` stays on disk and goes straight to PyPI. OIDC trusted publishing unchanged.
|
|
45
|
+
|
|
15
46
|
### v2.1.1 — test-coverage backfill for v2.1.0 + defeatbeta stdout-noise polish
|
|
16
47
|
Two threads. (1) Test-coverage audit on the v2.1.0 release surfaced that the four new CLI modules (`hv`, `ta`, `bars`, `scenarios`) had zero integration coverage and that several internal paths (non-daily intervals, the `indicators()` wrapper integration, the 4-feature state-vector boundary clipping) were under-tested; this release fills those gaps. (2) The defeatbeta fetcher printed banner + nltk + DuckDB chatter on first per-ticker import that polluted CLI streams; new `_quiet_defeatbeta()` context manager scopes the suppressions to the wrapper boundary. **1561 tests pass (+74 net since v2.1.0), ruff + mypy clean.**
|
|
17
48
|
|
|
@@ -97,22 +128,21 @@ Useful but not urgent.
|
|
|
97
128
|
### ~~M23. PyPI distribution + `thetabook init` wizard + `$THETABOOK_HOME`~~ — **shipped in v2.0.0**
|
|
98
129
|
Headline summary in [CHANGELOG.md](CHANGELOG.md#200--2026-05-13). As-shipped audit (what matched the design, what diverged, what's still open) lives at [docs/m23-audit.md](docs/m23-audit.md). Two follow-up items (`--with-accounts` flag, Homebrew tap) tracked under Deferred → "M23 follow-ups".
|
|
99
130
|
|
|
100
|
-
### M20. Effective options book table — `thetabook positions --options
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
```
|
|
104
|
-
$ thetabook positions --options
|
|
105
|
-
contract qty entry mark spot cushion DTE account
|
|
106
|
-
QQQ 2026-06-20 670 P -2 $4.50 $2.30 $666 -0.6% 54 main-margin
|
|
107
|
-
AAPL 2026-05-16 180 C +1 $3.50 $5.20 $185 2.7% 19 main-margin
|
|
108
|
-
…
|
|
109
|
-
```
|
|
131
|
+
### ~~M20. Effective options book table — `thetabook positions --options`~~ — **shipped in v2.2.1**
|
|
132
|
+
Built as a new `cli/positions.py` + `portfolio/options_book.py` after one wait-and-see /portfolio cycle confirmed the friction (reconstructing an options-only table by hand from `refresh` + per-idea `evaluate`) didn't resolve itself. Default `--options` view (plus `--equity` / `--all`); per-leg live mark, spot, cushion, calendar DTE, grouped by account. The cushion sign follows the stated "negative = ITM, danger" intent — `call:(K−S)/S` / `put:(S−K)/S` — correcting the original sketch's worked example, which computed the short-call sign backwards. See the v2.2.1 entry under Done above and [CHANGELOG.md](CHANGELOG.md).
|
|
110
133
|
|
|
111
|
-
|
|
134
|
+
### ~~M24. Expected move + vol-risk-premium — the two TA additions that extend the vol→dollars / theta-edge core~~ — **shipped in v2.2.1 ([#64](https://github.com/subsriram/thetabook/pull/64))**
|
|
135
|
+
Headline summary in [CHANGELOG.md](CHANGELOG.md) (`[2.2.1]`); as-shipped detail in the v2.2.1 entry under Done above.
|
|
112
136
|
|
|
113
|
-
|
|
137
|
+
### M25. Remaining TA candidates from the 2026-06-04 review (Low–medium effort each) — build on demand
|
|
138
|
+
The same TA-capabilities review that produced M24 surfaced a second tier — useful but lower-leverage than expected-move / VRP, logged here so they're not re-derived from scratch. Roughly ordered by options-relevance:
|
|
114
139
|
|
|
115
|
-
**
|
|
140
|
+
- **ATR (Average True Range) + range-based sizing.** The one true gap in the vol layer: all current realized-vol is close-to-close, so there's no read on intraday range. `get_bars` already returns full OHLC, so `atr(ticker, window=14)` in `analysis/ta.py` is a few lines (`max(H−L, |H−Cprev|, |L−Cprev|)` then Wilder-smoothed). Useful for stop placement, comparing a strike's distance to "a normal day's move", and gut-checking the M24 expected move. Lowest effort, true gap.
|
|
141
|
+
- **Volatility cone.** Realized vol across multiple windows (10/20/30/60/90d) with historical percentile bands per window — the classic options-desk "is vol high or low *for the horizon I'm trading*" tool, and a natural aggregation over `hv_series` called at several windows. Directly informs DTE selection. Everything needed is already in `analysis/hv.py`; this is a presentation/aggregation layer (`thetabook hv --cone` or `thetabook vol-cone TICKER`).
|
|
142
|
+
- **Earnings-aware / event vol.** The package already resolves earnings dates (`cli/earnings.py`). De-earnings the HV (strip the known event-day jump) so the baseline vol quoted during a review isn't inflated by a scheduled catalyst — helps decide whether elevated IV (per M24's VRP) is event premium or a genuine regime shift.
|
|
143
|
+
- **Beta / correlation to SPY.** Portfolio-level, not single-ticker: helps `greeks`/`/portfolio` answer "how much of my delta is really one SPY bet" — concentration in disguise. Complements the existing delta aggregation; needs a two-ticker return regression over `get_bars` closes.
|
|
144
|
+
- **Support/resistance (pivot points, recent swing highs/lows).** Concrete price anchors for strike selection. Modest lift, modest payoff — build when a real review session reaches for it.
|
|
145
|
+
- **Generic directional indicators (ADX/trend strength, SMA/EMA crossovers, Stochastics, Ichimoku, Keltner/Donchian).** Standard but weak options tie-in — completeness rather than edge for a Greeks-first journal. Add only if a specific review actually calls for one; not worth a speculative build.
|
|
116
146
|
|
|
117
147
|
### M8. Windows symlink handling for `latest.json` (Low-medium effort) — defer
|
|
118
148
|
`personal/snapshots/latest.json` is a POSIX symlink written by `get_positions.py`. On Windows, symlink creation requires Developer Mode or admin rights; without them the symlink write fails silently. **Deferred until first Windows contributor:** the user is solo on macOS; no symptom observed. When revisited, implement option 3 (read-resolver preferring newest dated file, treating `latest.json` as optional cache) — most robust across symlink states.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "thetabook"
|
|
3
|
-
version = "2.1
|
|
3
|
+
version = "2.2.1"
|
|
4
4
|
description = "A journal for options traders who think in Greeks — Schwab portfolio review and strategy log with an AI copilot."
|
|
5
5
|
requires-python = ">=3.12"
|
|
6
6
|
dependencies = [
|
|
@@ -27,6 +27,9 @@ build-backend = "hatchling.build"
|
|
|
27
27
|
[tool.hatch.build.targets.wheel]
|
|
28
28
|
packages = ["src/thetabook"]
|
|
29
29
|
|
|
30
|
+
[tool.hatch.build.targets.sdist]
|
|
31
|
+
exclude = ["personal/", ".claude/", "tests/", "docs/"]
|
|
32
|
+
|
|
30
33
|
[dependency-groups]
|
|
31
34
|
dev = [
|
|
32
35
|
"mypy>=1.13.0",
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
"""Expected move — translate a vol figure into the dollar range an option
|
|
2
|
+
is pricing in by a given expiry.
|
|
3
|
+
|
|
4
|
+
This is the bridge between the realized-vol layer (:mod:`thetabook.analysis.hv`)
|
|
5
|
+
/ live option IV and a strike-selection decision: "how far OTM should my
|
|
6
|
+
short strike sit?" is the same question as "how big is the ±1σ move the
|
|
7
|
+
market is pricing by expiry?".
|
|
8
|
+
|
|
9
|
+
Convention
|
|
10
|
+
----------
|
|
11
|
+
- **Formula**: ``move_1σ = S · σ · sqrt(t)``, the standard one-standard-
|
|
12
|
+
deviation expected move (the same approximation behind the ATM-straddle
|
|
13
|
+
rule of thumb).
|
|
14
|
+
- **Horizon**: ``t = dte_days / 365`` — *calendar* days to expiry over 365.
|
|
15
|
+
This is the practitioner / straddle convention and is a **deliberate
|
|
16
|
+
mismatch** with :mod:`thetabook.analysis.hv`'s ``sqrt(252)`` (trading-day)
|
|
17
|
+
annualization. The two layers answer different questions: ``hv`` annualizes
|
|
18
|
+
a per-trading-day realized vol to a comparable yearly number; ``em`` prices
|
|
19
|
+
a move over a fixed calendar span to a known expiry date, and option DTE is
|
|
20
|
+
quoted in calendar days. Mixing the two conventions (calendar DTE with a
|
|
21
|
+
trading-day annualization, or vice versa) is the common footgun; keeping
|
|
22
|
+
``em`` purely calendar-based matches how the move is quoted on a desk.
|
|
23
|
+
- **Sigma units**: annualized vol as a decimal (``0.24`` == 24%) — the same
|
|
24
|
+
units ``hv()`` and the chain's ``implied_vol`` field already emit, so a
|
|
25
|
+
caller can feed either straight in.
|
|
26
|
+
|
|
27
|
+
This module is pure math: no I/O, no data fetch. The CLI decides where
|
|
28
|
+
``sigma`` comes from (HV, a manual ``--iv``, or ATM IV pulled from the chain
|
|
29
|
+
via :func:`thetabook.analysis.vrp.atm_iv`).
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
from __future__ import annotations
|
|
33
|
+
|
|
34
|
+
import math
|
|
35
|
+
from dataclasses import dataclass
|
|
36
|
+
|
|
37
|
+
# Calendar days per year — the expected-move horizon denominator. See the
|
|
38
|
+
# module docstring for why this is 365 (calendar) and not 252 (trading).
|
|
39
|
+
CALENDAR_DAYS_PER_YEAR = 365.0
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
# NOTE: plain frozen dataclasses, not pydantic models, on purpose. These are
|
|
43
|
+
# within-feature, CLI-only display shapes that never cross a load/save boundary
|
|
44
|
+
# — consistent with the rest of analysis/ (hv/scenarios return floats/Series/
|
|
45
|
+
# DataFrames). CLAUDE.md's "cross-module shapes live in models.py as pydantic"
|
|
46
|
+
# rule is about serialized / boundary-crossing data. If a future caller needs to
|
|
47
|
+
# persist or validate one of these (e.g. writing an EM reading into idea
|
|
48
|
+
# frontmatter), promote it to a pydantic model in models.py at that point.
|
|
49
|
+
@dataclass(frozen=True)
|
|
50
|
+
class MoveBand:
|
|
51
|
+
"""One ±Nσ band of an expected move."""
|
|
52
|
+
|
|
53
|
+
n: float
|
|
54
|
+
"""Number of standard deviations (1.0, 2.0, ...)."""
|
|
55
|
+
move: float
|
|
56
|
+
"""The ±dollar move at this band (always non-negative)."""
|
|
57
|
+
pct: float
|
|
58
|
+
"""``move / spot`` — the move as a fraction of spot."""
|
|
59
|
+
low: float
|
|
60
|
+
"""``spot - move`` — bottom of the band."""
|
|
61
|
+
high: float
|
|
62
|
+
"""``spot + move`` — top of the band."""
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
@dataclass(frozen=True)
|
|
66
|
+
class ExpectedMove:
|
|
67
|
+
"""Result of :func:`expected_move`: the spot/sigma/horizon inputs plus
|
|
68
|
+
one :class:`MoveBand` per requested sigma multiple."""
|
|
69
|
+
|
|
70
|
+
spot: float
|
|
71
|
+
sigma: float
|
|
72
|
+
dte_days: int
|
|
73
|
+
t_years: float
|
|
74
|
+
bands: tuple[MoveBand, ...]
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def expected_move(
|
|
78
|
+
spot: float,
|
|
79
|
+
sigma: float,
|
|
80
|
+
dte_days: int,
|
|
81
|
+
*,
|
|
82
|
+
sigmas: tuple[float, ...] = (1.0, 2.0),
|
|
83
|
+
) -> ExpectedMove:
|
|
84
|
+
"""±Nσ expected move of ``spot`` over ``dte_days`` calendar days.
|
|
85
|
+
|
|
86
|
+
``sigma`` is annualized vol as a decimal (``0.24`` == 24%). The 1σ move
|
|
87
|
+
is ``spot · sigma · sqrt(dte_days / 365)``; higher bands scale linearly
|
|
88
|
+
(the ``n``-σ move is ``n`` times the 1σ move), so the ~68% / ~95% /
|
|
89
|
+
~99.7% normal-distribution coverage of 1σ / 2σ / 3σ applies.
|
|
90
|
+
|
|
91
|
+
Raises ``ValueError`` on negative inputs (a negative DTE means the
|
|
92
|
+
expiry is in the past; the caller should handle that before reaching
|
|
93
|
+
here). ``dte_days == 0`` and ``sigma == 0`` are valid degenerate inputs
|
|
94
|
+
and produce zero-width bands.
|
|
95
|
+
"""
|
|
96
|
+
if spot <= 0:
|
|
97
|
+
raise ValueError(f"spot must be positive (got {spot})")
|
|
98
|
+
if sigma < 0:
|
|
99
|
+
raise ValueError(f"sigma must be non-negative (got {sigma})")
|
|
100
|
+
if dte_days < 0:
|
|
101
|
+
raise ValueError(f"dte_days must be non-negative (got {dte_days})")
|
|
102
|
+
if not sigmas:
|
|
103
|
+
raise ValueError("sigmas must contain at least one multiple")
|
|
104
|
+
|
|
105
|
+
t_years = dte_days / CALENDAR_DAYS_PER_YEAR
|
|
106
|
+
one_sigma = spot * sigma * math.sqrt(t_years)
|
|
107
|
+
|
|
108
|
+
bands = tuple(
|
|
109
|
+
MoveBand(
|
|
110
|
+
n=n,
|
|
111
|
+
move=n * one_sigma,
|
|
112
|
+
pct=n * one_sigma / spot,
|
|
113
|
+
low=spot - n * one_sigma,
|
|
114
|
+
high=spot + n * one_sigma,
|
|
115
|
+
)
|
|
116
|
+
for n in sigmas
|
|
117
|
+
)
|
|
118
|
+
return ExpectedMove(spot=spot, sigma=sigma, dte_days=dte_days, t_years=t_years, bands=bands)
|