Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 132 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
# TradeNow: notes for Claude Code

A research and **paper-trading-only** system for gold and a small ETF universe.
It imports daily bars from Tiingo, tests rule-based strategies without
look-ahead, and trades an Alpaca **paper** account. There is no live mode.

The owner works on Windows (PowerShell) in
`C:\Users\muhammad tahub\Downloads\Projects\Tradenow`, runs the scheduled
`paper-auto` there, and prefers a plan in plain language before larger
changes. When asked for a plan only, do not implement.

## Rules that are never broken

1. **Paper only.** Never add a live endpoint or mode. `TRADENOW_MODE` accepts
only `paper`, and the Alpaca client accepts only the paper URL.
2. **The live-trading gate (ADR-008, `docs/decisions.md`).** No real money
unless a strategy beats plain buy-and-hold out of sample, after costs, over
enough trades, historically **and** in a year of forward paper trading.
Thresholds may be tightened, never loosened, without a new ADR written
before the results it would affect.
3. **Register before testing (ADR-010, ADR-011).** Candidates, parameters,
benchmarks, and pass criteria are fixed in an ADR before any result exists.
Never tune or re-run registered candidates after seeing their results; a
new idea needs a new ADR and counts as more trials.
4. **No look-ahead.** Strategies read history only through `History`
(`tradenow/strategies.py`), which cannot index past today. Features are
point-in-time and a test proves it.
5. **Secrets stay private.** Keys live in the ignored `.env.local`. They are
never written to logs (`logs.register_secret` redacts them), plans, reports,
commits, or notifications. `data/private/` and `artifacts/` are git-ignored.
6. **Be honest about odds.** The GLD strategies failed the gate. Do not present
anything as likely to make money, and do not give financial advice.

## Commands

```powershell
python -m pip install -e ".[dev,web]" # ruff and mypy are pinned in the dev extra
ruff check tradenow tests
mypy
python -m unittest discover -s tests -v # CI runs these three on Ubuntu and Windows
```

Main CLI (`python -m tradenow <command>`):

- Data: `tiingo-import --start D --end D [--symbols A,B | --universe]` and
`universe` (aligned six-ETF history).
- Research: `gld` (12 registered GLD candidates plus the gate verdict) and
`features --date D`.
- Paper trading: `paper-plan`, `paper-submit --approve ID`, `paper-status`,
`paper-report`, `paper-halt`, `paper-resume --confirm`, and
`paper-auto [--dry-run | --check]`.
- Other: `notify-test`, and `web` (the dashboard).
- `scripts/schedule-windows.ps1` registers the Windows scheduled tasks.

Every command appends one line to `data/private/logs/runs.jsonl`.

## Where things are

- `data/private/` (set with `TRADENOW_DATA_DIR`) holds `tiingo/` imports,
`alpaca/` (ledger, plans, kill switch, equity history, `live_gate.json`),
`logs/`, `experiments.jsonl`, and optional `risk.toml`. Copy
`risk.example.toml` to create it. Without it the defaults apply: 50%
position, 2% daily loss, 10% drawdown, `auto_submit = false`.
- Research core: `equity_types.py`, `features.py` (`gld_features_v2`),
`strategies.py` (interface and `GLD_CANDIDATES`), `selection.py` (single
selection rule, `RESEARCH_CONFIG` at the 100% cap), `equity.py`
(single-asset simulator), `gld_research.py` and `gld_evaluation.py`,
`metrics.py`, `live_gate.py`, and `experiments.py`.
- Multi-asset data: `tiingo.py` (`import_symbol`, `prune_imports`,
`latest_import`) and `universe.py` (`UNIVERSE`, adjusted prices,
`align`, `load_universe`).
- Paper trading: `alpaca_paper.py` (adapter), `paper_rules.py` (pure rules),
`paper_trading.py` (orchestration and store), `paper_auto.py`,
`risk_config.py`, `notify.py`, and `execution_quality.py`.
- The MGC futures files (`simulation.py`, `offline.py`, `stress.py`,
`market_data.py`, `synthetic.py`) are the older synthetic workflow. Leave
them alone unless asked.

## Conventions

- Money and prices are `Decimal`, never float. Pure rules are separate from
I/O so they can be tested without the network.
- Every change comes with tests. `tests/test_strategies.py` holds golden
SHA-256 hashes of pre-refactor outputs, so a failure there means a result
changed. Investigate; never simply re-bless the hashes.
- Identical inputs must give byte-identical reports (tested).
- Keep ruff and mypy clean and CI green on both operating systems.
- Commits have short imperative subjects with a body explaining why. Work on a
branch and merge through a pull request.

## Status (2026-09-27)

- Phases 0 to 5 are done. Phase 6 (unattended paper trading) is built and
running as a dry run on the owner's PC. It passes after 20 unattended
sessions with no reconciliation failures.
- **GLD research (ADR-010) failed the gate:** +15.6% compounded across 29
rolling windows against +158.7% for holding GLD. That is final.
- **Multi-asset research (ADR-011) is registered:** six ETFs (GLD, SLV, SPY,
EFA, IEF, DBC), dividend-adjusted prices from spring 2006, and 6 candidates
(`mom`, `trend`, `both` × `eq`, `iv35`). Rebalancing is monthly. The gate
is the strictest option: beat **both** an equal-weight buy-and-hold of the
six **and** SPY on return, with no larger drawdown (R1 to R5, then F1 to F4).
- MA1 (ADR-011) and MA2 (multi-symbol data pipeline) are done.

## Next: MA3, the portfolio simulator (read ADR-011 first)

Build `tradenow/portfolio.py`:

- Cash plus up to six positions in whole shares, never margin, total weight
at most 100%.
- Monthly rebalance: target weights from the month's last close, orders at
the next open. Sells before buys. An asset trades only if its target
differs by more than 1% of equity.
- $0.01 slippage per share, zero commission (stress test $0.10), and a 10%
portfolio drawdown halt checked daily.
- Per-asset and portfolio metrics through `metrics.py`.
- Benchmarks B1 (equal-weight buy-and-hold of the six, rebalanced monthly,
same costs) and B2 (100% SPY).
- Tests use synthetic data only. No multi-asset result on real data exists
until MA5.

Then:

- **MA4:** the six strategies (per-asset weights, inverse-volatility sizing
over 60-day volatility capped at 35%), selection and rolling windows
(504/126/126), gate checks R1 to R5, and a `multi` command writing a report
and an experiment record.
- **MA5:** the owner runs `multi` once on real data, and the result is
recorded in ADR-011.
- **MA6:** only if R1 to R5 pass, multi-asset paper trading (a new ADR),
then a year of forward testing. If they fail, stop or register Phase 7 in
a new ADR.
17 changes: 16 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,22 @@ the result is `UNCHANGED` and nothing is written. Revised history is refused,
and the earlier import is kept. The key is sent in an authorization header and never written to the
data files. The import command does not run a backtest or contact a broker.

Replay the newest private import without another Tiingo request:
For the multi-asset research (ADR-011), import all six registered ETFs (GLD,
SLV, SPY, EFA, IEF, DBC) with the same protections, then check that they align:

```powershell
python -m tradenow tiingo-import --universe --start 2004-11-18 --end 2026-09-25
python -m tradenow universe
```

`--symbols SPY,IEF` imports a chosen few. Several symbols make two requests
each; the first failure (for example a rate limit) stops the run and reports
what was already imported. After every import, only the newest three imports
of that symbol are kept, which caps disk use. `universe` uses dividend-adjusted
prices, trims the six histories to the dates they all cover, and refuses any
missing day inside that range.

Replay the newest private GLD import without another Tiingo request:

```powershell
python -m tradenow gld
Expand Down
123 changes: 123 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -378,6 +378,28 @@ Record the result. The next option is multi-asset trend-following, which
needs new data, a new simulator, and a new registration ADR. The other option
is to accept that a low-cost index fund is the better choice.

### Result (2026-09-27)

Evaluated once on the Tiingo GLD history, 5,497 daily bars (experiment
`cc6999fc32cd36f4`). **Verdict: FAIL.** Failing checks: R1, R2, R4. R3
passed.

| Rolling tests before the holdout (29 windows) | Registered process | 100% GLD buy-and-hold |
|---|---|---|
| Compounded return | +15.6% | +158.7% |
| Windows with a positive return | 9 of 29 | — |
| Windows beating same-cap buy-and-hold | 10 of 29 (18 needed) | — |
| Closed trades | 64 | — |

The final holdout selected `trend_200_volfilter`: +59.5% with an 8.3%
maximum drawdown, against +125.6% and 26.4% for buy-and-hold. It was in the
market 36% of the time. Holding about 45% GLD and 55% cash would have had the
same volatility and a similar return, so the timing added little. That
period had already been viewed and is not evidence.

No candidate trades real money. Next step: multi-asset trend-following
(ADR-011).

### Consequences

- Changing, adding, or removing a candidate requires a new ADR, and every
Expand All @@ -386,6 +408,107 @@ is to accept that a low-cost index fund is the better choice.

---

## ADR-011 — Registered Multi-Asset Trend-Following Research

**Status:** Accepted. Registered before any multi-asset code or result
existed.

### Context

Trend rules on GLD alone failed the gate (ADR-010). Published evidence for
time-series momentum is much stronger across many markets, because assets
that do not move together smooth out each other's whipsaws. This ADR fixes
the assets, rules, sizing, method, and pass criteria before anything is
built or run.

### Universe and data

- **Six ETFs:** GLD (gold), SLV (silver), SPY (US stocks), EFA
(international stocks), IEF (US government bonds), DBC (broad
commodities).
- **History:** from the first day all six have a Tiingo bar (spring 2006) to
the latest import. The six share one calendar; a missing day for any
symbol is an error, never filled in.
- **Prices:** Tiingo's dividend- and split-adjusted OHLC for signals,
simulated fills, and valuation, so the results include dividends as total
return. Raw prices are kept for execution checks.

### Rules and sizing (6 candidates)

Each rule is evaluated per asset at the last close of each month, using the
point-in-time features of ADR-010 computed on adjusted prices:

- **mom:** in when 12-1 month momentum is positive.
- **trend:** in when the close is above its 200-day average.
- **both:** in when both are true.

Two ways to size an asset that is in:

- **eq:** 1/6 of equity.
- **iv35:** inverse 60-day volatility, normalized across all six assets and
capped at 35% per asset, with any excess shared proportionally among the
uncapped assets.

Assets that are out hold cash. The candidates are `mom_eq`, `trend_eq`,
`both_eq`, `mom_iv35`, `trend_iv35`, and `both_iv35`.

### Simulation

- Rebalance monthly: signals at the month's last close, orders at the next
open. An asset trades only if its target differs from its holding by more
than 1% of equity.
- Whole shares, sells before buys, cash never negative, never margin, total
weight at most 100%.
- Costs: $0.01 slippage per share, zero commission. The stress test uses
$0.10.
- The 10% portfolio drawdown halt is checked daily: it sells everything and
blocks new entries for the rest of the run, as in the GLD research.

### Selection and tests

These are the same as ADR-010. A 60/20/20 chronological split is used, and
rolling windows before the final holdout: 504 development, 126 validation,
and 126 test bars, with test blocks that do not overlap. Each window selects
the candidate with the highest validation return minus maximum drawdown, or
cash if none is positive.

### Benchmarks and the gate (the strictest option)

The strategy must beat **both** benchmarks:

- **B1:** equal-weight buy-and-hold of the same six ETFs, rebalanced
monthly, with the same costs.
- **B2:** 100% SPY buy-and-hold, the "just buy an index fund" alternative.

| Check | Requirement |
|---|---|
| R1 | Compounded return across the rolling test windows exceeds both B1's and B2's |
| R2 | Beats both B1 and B2 in at least 60% of the rolling windows |
| R3 | At least 30 closed round trips, counted per asset |
| R4 | R1 still holds with slippage at $0.10 per share |
| R5 | Maximum drawdown of the chained rolling test returns is no larger than either benchmark's, chained the same way |
| F1 | At least 252 paper sessions on one frozen strategy version |
| F2 | Paper return exceeds both B1 and B2 over those sessions |
| F3 | Paper maximum drawdown is no larger than either benchmark's |
| F4 | Mean fill cost against the simulated fill of at most 10 bps, over at least 10 fills |

This is deliberately harder than ADR-008's single-asset gate. Trend-following
usually trails stocks in long bull markets and wins by losing less in
crashes, so beating SPY on return over 2006 onward is unlikely. That is
accepted: the rule exists to prevent investing in anything that an index
fund would beat.

### What happens after the run

- The result is recorded here and in the experiment log, pass or fail.
- **If R1 to R5 pass:** multi-asset paper trading is built (a separate ADR),
the dry run comes first, then a year of forward testing (F1 to F4).
- **If they fail:** stop, or register Phase 7 machine learning on this
dataset in a new ADR. The candidates and thresholds above are not tuned
and re-run.

---

## ADR Template

### ADR-XXX — Title
Expand Down
Loading
Loading