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.
Files changed (186) hide show
  1. {thetabook-2.1.2 → thetabook-2.2.1}/CHANGELOG.md +130 -1
  2. {thetabook-2.1.2 → thetabook-2.2.1}/CLAUDE.md +5 -1
  3. {thetabook-2.1.2 → thetabook-2.2.1}/PKG-INFO +1 -1
  4. {thetabook-2.1.2 → thetabook-2.2.1}/README.md +42 -6
  5. {thetabook-2.1.2 → thetabook-2.2.1}/ROADMAP.md +44 -14
  6. {thetabook-2.1.2 → thetabook-2.2.1}/pyproject.toml +4 -1
  7. thetabook-2.2.1/src/thetabook/analysis/em.py +118 -0
  8. thetabook-2.2.1/src/thetabook/analysis/vrp.py +145 -0
  9. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/__init__.py +10 -1
  10. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/_shared.py +21 -2
  11. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/bars.py +24 -17
  12. thetabook-2.2.1/src/thetabook/cli/em.py +149 -0
  13. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/import_csv.py +5 -3
  14. thetabook-2.2.1/src/thetabook/cli/positions.py +79 -0
  15. thetabook-2.2.1/src/thetabook/cli/vrp.py +80 -0
  16. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/bars.py +242 -47
  17. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/accounts.py +8 -1
  18. thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/__init__.py +55 -0
  19. thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/_base.py +118 -0
  20. thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/empower.py +208 -0
  21. thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/fidelity.py +161 -0
  22. thetabook-2.2.1/src/thetabook/portfolio/csv_parsers/schwab.py +152 -0
  23. thetabook-2.2.1/src/thetabook/portfolio/import_csv_snapshot.py +132 -0
  24. thetabook-2.2.1/src/thetabook/portfolio/options_book.py +431 -0
  25. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/accounts.toml.example +17 -0
  26. {thetabook-2.1.2 → thetabook-2.2.1}/uv.lock +1 -1
  27. thetabook-2.1.2/.claude/commands/accounts-init.md +0 -45
  28. thetabook-2.1.2/.claude/commands/adjust.md +0 -84
  29. thetabook-2.1.2/.claude/commands/chain.md +0 -57
  30. thetabook-2.1.2/.claude/commands/close.md +0 -51
  31. thetabook-2.1.2/.claude/commands/diff.md +0 -47
  32. thetabook-2.1.2/.claude/commands/evaluate.md +0 -48
  33. thetabook-2.1.2/.claude/commands/greeks.md +0 -35
  34. thetabook-2.1.2/.claude/commands/idea.md +0 -48
  35. thetabook-2.1.2/.claude/commands/ideas.md +0 -29
  36. thetabook-2.1.2/.claude/commands/open.md +0 -40
  37. thetabook-2.1.2/.claude/commands/portfolio.md +0 -59
  38. thetabook-2.1.2/.claude/commands/price.md +0 -28
  39. thetabook-2.1.2/.claude/commands/refresh.md +0 -9
  40. thetabook-2.1.2/.claude/commands/roll-scenarios.md +0 -72
  41. thetabook-2.1.2/.claude/commands/roll.md +0 -125
  42. thetabook-2.1.2/.claude/commands/setup.md +0 -98
  43. thetabook-2.1.2/.claude/commands/wiki-lint.md +0 -77
  44. thetabook-2.1.2/docs/architecture.md +0 -406
  45. thetabook-2.1.2/docs/behaviors.md +0 -138
  46. thetabook-2.1.2/docs/cli.md +0 -136
  47. thetabook-2.1.2/docs/hosted-service-proposal.md +0 -113
  48. thetabook-2.1.2/docs/m23-audit.md +0 -43
  49. thetabook-2.1.2/docs/skills-roadmap.md +0 -174
  50. thetabook-2.1.2/docs/skills.md +0 -91
  51. thetabook-2.1.2/src/thetabook/portfolio/import_csv_snapshot.py +0 -397
  52. thetabook-2.1.2/tests/analysis/test_hv.py +0 -133
  53. thetabook-2.1.2/tests/analysis/test_scenarios.py +0 -364
  54. thetabook-2.1.2/tests/analysis/test_ta.py +0 -310
  55. thetabook-2.1.2/tests/cli/test_analysis_cli.py +0 -658
  56. thetabook-2.1.2/tests/cli/test_bs_cli.py +0 -120
  57. thetabook-2.1.2/tests/cli/test_init.py +0 -480
  58. thetabook-2.1.2/tests/cli/test_migrate_home.py +0 -183
  59. thetabook-2.1.2/tests/conftest.py +0 -277
  60. thetabook-2.1.2/tests/ideas/test_adjust.py +0 -1739
  61. thetabook-2.1.2/tests/ideas/test_core.py +0 -288
  62. thetabook-2.1.2/tests/ideas/test_evaluate_idea.py +0 -1921
  63. thetabook-2.1.2/tests/ideas/test_manage_ideas.py +0 -759
  64. thetabook-2.1.2/tests/ideas/test_roll_scenarios.py +0 -729
  65. thetabook-2.1.2/tests/market/test_bars.py +0 -884
  66. thetabook-2.1.2/tests/market/test_chains.py +0 -654
  67. thetabook-2.1.2/tests/market/test_dividends.py +0 -780
  68. thetabook-2.1.2/tests/market/test_earnings.py +0 -321
  69. thetabook-2.1.2/tests/market/test_leg_marks.py +0 -106
  70. thetabook-2.1.2/tests/market/test_prices.py +0 -658
  71. thetabook-2.1.2/tests/market/test_schwab.py +0 -106
  72. thetabook-2.1.2/tests/market/test_vol_lookup.py +0 -372
  73. thetabook-2.1.2/tests/portfolio/test_accounts.py +0 -981
  74. thetabook-2.1.2/tests/portfolio/test_diff_snapshots.py +0 -356
  75. thetabook-2.1.2/tests/portfolio/test_get_positions.py +0 -495
  76. thetabook-2.1.2/tests/portfolio/test_import_csv_snapshot.py +0 -375
  77. thetabook-2.1.2/tests/portfolio/test_scaffold.py +0 -92
  78. thetabook-2.1.2/tests/pricing/test_bs.py +0 -254
  79. thetabook-2.1.2/tests/pricing/test_greeks.py +0 -828
  80. thetabook-2.1.2/tests/skills/__init__.py +0 -0
  81. thetabook-2.1.2/tests/skills/conftest.py +0 -52
  82. thetabook-2.1.2/tests/skills/test_install.py +0 -641
  83. thetabook-2.1.2/tests/skills/test_lint.py +0 -220
  84. thetabook-2.1.2/tests/skills/test_models.py +0 -96
  85. thetabook-2.1.2/tests/skills/test_parse.py +0 -70
  86. thetabook-2.1.2/tests/skills/test_policy.py +0 -54
  87. thetabook-2.1.2/tests/skills/test_registry.py +0 -388
  88. thetabook-2.1.2/tests/skills/test_render.py +0 -55
  89. thetabook-2.1.2/tests/test_cache.py +0 -149
  90. thetabook-2.1.2/tests/test_cli.py +0 -800
  91. thetabook-2.1.2/tests/test_config.py +0 -77
  92. thetabook-2.1.2/tests/test_factories.py +0 -92
  93. thetabook-2.1.2/tests/test_leg_parse.py +0 -228
  94. thetabook-2.1.2/tests/test_log.py +0 -42
  95. thetabook-2.1.2/tests/test_models.py +0 -412
  96. thetabook-2.1.2/tests/test_paths.py +0 -502
  97. thetabook-2.1.2/tests/test_tickers.py +0 -262
  98. thetabook-2.1.2/tests/wiki/test_lint.py +0 -1069
  99. thetabook-2.1.2/tests/wiki/test_render.py +0 -442
  100. {thetabook-2.1.2 → thetabook-2.2.1}/.env.example +0 -0
  101. {thetabook-2.1.2 → thetabook-2.2.1}/.github/workflows/ci.yml +0 -0
  102. {thetabook-2.1.2 → thetabook-2.2.1}/.github/workflows/publish.yml +0 -0
  103. {thetabook-2.1.2 → thetabook-2.2.1}/.gitignore +0 -0
  104. {thetabook-2.1.2 → thetabook-2.2.1}/.python-version +0 -0
  105. {thetabook-2.1.2 → thetabook-2.2.1}/CONTRIBUTING.md +0 -0
  106. {thetabook-2.1.2 → thetabook-2.2.1}/LICENSE +0 -0
  107. {thetabook-2.1.2 → thetabook-2.2.1}/SECURITY.md +0 -0
  108. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/__init__.py +0 -0
  109. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/__init__.py +0 -0
  110. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/hv.py +0 -0
  111. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/scenarios.py +0 -0
  112. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/analysis/ta.py +0 -0
  113. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cache.py +0 -0
  114. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/accounts.py +0 -0
  115. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/adjust.py +0 -0
  116. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/bs.py +0 -0
  117. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/chain.py +0 -0
  118. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/diff.py +0 -0
  119. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/dividends.py +0 -0
  120. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/earnings.py +0 -0
  121. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/evaluate.py +0 -0
  122. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/greeks.py +0 -0
  123. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/hv.py +0 -0
  124. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/ideas.py +0 -0
  125. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/init.py +0 -0
  126. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/leg_mark.py +0 -0
  127. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/migrate_home.py +0 -0
  128. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/price.py +0 -0
  129. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/refresh.py +0 -0
  130. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/roll.py +0 -0
  131. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/scenarios.py +0 -0
  132. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/skills.py +0 -0
  133. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/snapshot.py +0 -0
  134. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/ta.py +0 -0
  135. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/tickers.py +0 -0
  136. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/cli/wiki.py +0 -0
  137. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/config.py +0 -0
  138. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/__init__.py +0 -0
  139. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/adjust.py +0 -0
  140. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/core.py +0 -0
  141. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/evaluate_idea.py +0 -0
  142. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/manage_ideas.py +0 -0
  143. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/ideas/roll_scenarios.py +0 -0
  144. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/leg_parse.py +0 -0
  145. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/log.py +0 -0
  146. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/__init__.py +0 -0
  147. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/_schwab.py +0 -0
  148. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/chains.py +0 -0
  149. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/dividends.py +0 -0
  150. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/earnings.py +0 -0
  151. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/leg_marks.py +0 -0
  152. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/prices.py +0 -0
  153. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/market/vol_lookup.py +0 -0
  154. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/models.py +0 -0
  155. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/paths.py +0 -0
  156. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/__init__.py +0 -0
  157. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/diff_snapshots.py +0 -0
  158. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/get_positions.py +0 -0
  159. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/portfolio/scaffold.py +0 -0
  160. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/pricing/__init__.py +0 -0
  161. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/pricing/bs.py +0 -0
  162. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/pricing/greeks.py +0 -0
  163. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/__init__.py +0 -0
  164. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/install.py +0 -0
  165. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/lint.py +0 -0
  166. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/models.py +0 -0
  167. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/parse.py +0 -0
  168. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/policy.py +0 -0
  169. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/registry.py +0 -0
  170. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/skills/render.py +0 -0
  171. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/README.md +0 -0
  172. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/config.toml.example +0 -0
  173. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/idea.md +0 -0
  174. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/journal.md +0 -0
  175. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/learnings.md +0 -0
  176. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/skill.md +0 -0
  177. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/skills/setup-thetabook.md +0 -0
  178. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/index.md +0 -0
  179. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/log.md +0 -0
  180. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/overview.md +0 -0
  181. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/strategy.md +0 -0
  182. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/templates/wiki/underlying.md +0 -0
  183. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/tickers.py +0 -0
  184. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/wiki/__init__.py +0 -0
  185. {thetabook-2.1.2 → thetabook-2.2.1}/src/thetabook/wiki/lint.py +0 -0
  186. {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
- ## [Unreleased]
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
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: thetabook
3
- Version: 2.1.2
3
+ Version: 2.2.1
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
@@ -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. Both Schwab and Fidelity CSV formats are auto-detected:
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 Fidelity CSV exports
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
- │ │ └── dividends.py # yield + next ex-div lookup (7-day on-disk cache)
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 # Schwab/Fidelity CSV → snapshot
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
- │ │ └── test_dividends.py
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-26 | Current: v2.1.0 | Release notes: [CHANGELOG.md](CHANGELOG.md)
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` (Medium effort) — wait-and-see
101
- During /portfolio reviews the user has to reconstruct an options-only table by hand: read average premium and market value out of `refresh` stdout, divide for current mark, then re-pull live marks via `evaluate <id>` per idea. The data already exists across three callers — `greeks` (snapshot loader + grouping by underlying), `evaluate_idea` (per-leg live-mark loop with cascade fallback), and `leg-mark` (single-leg current bid/ask) — so the table itself is mostly stitching. Target shape:
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
- Cushion is moneyness for the short side: `(S − K)/S` for short calls, `(K − S)/S` for short puts (negative = ITM, danger). DTE is calendar days. Group by account.
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
- **Wait-and-see rationale:** Net plan items 1, 2, 3 + the `--show-all` flag landed in v1.7.x and meaningfully changed what /portfolio asks Claude to do. The previous workflow had Claude reconstructing this table because the commands one layer down (snapshot freshness, account totals, concentration ranking) were missing — now that those exist, Claude may be able to produce a serviceable options-book table by reading the snapshot + a single `evaluate` pass without a dedicated command. Hold one /portfolio cycle, see whether the friction resurfaces, then build.
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
- **Implementation sketch (when triggered):** new `cli/positions.py` typer command with `--options` / `--equity` / `--all` flags (default `--options` since that's the friction). Reuses `thetabook.ideas.evaluate_idea.resolve_market_data`-style live-mark logic factored out so it accepts a list of legs rather than an idea file. Or — likely simpler — add `--legs` to the existing `greeks` command since `greeks` already loads the snapshot and walks per-leg; the per-leg mark fetch + cushion/DTE columns become incremental.
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.2"
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)