Skip to content

Revive AutoMoonBot: point-in-time graph store, data layer and backtester (stages 1–3) - #84

Open
SnowCheetos wants to merge 18 commits into
mainfrom
claude/project-thread-11tt3o
Open

SnowCheetos wants to merge 18 commits into
mainfrom
claude/project-thread-11tt3o

Conversation

@SnowCheetos

Copy link
Copy Markdown
Owner

This PR holds the first three revival stages, one commit each. It's best reviewed commit by commit. The goal of these stages is to make leakage impossible by construction before any model is trained. Later stages (baselines with PGPerceptron re-measured out of sample, the graph transformer, offline LLM enrichment, spillover validation) will follow in separate PRs. See docs/ROADMAP.md.

Stage 1: moonrs rebuilt as a bitemporal point-in-time graph store (2a27786)

  • Time model. Every node, observation and edge carries a valid time and a known time (i64 ns UTC). A snapshot as_of(known_at, valid_at) returns only what was knowable at that moment. Restatements, retractions and delistings are versioned rather than overwritten.
  • Strict ingestion. Schemas validate values, dimensions and bounds. A conflicting fact with the same key and known time is rejected. Batches are atomic with rollback, and replays are idempotent.
  • Snapshots. Snapshots are deterministic, with rows sorted by key. They expose:
    • [N, K, D] history tensors with presence masks and per-slot timestamps
    • per-relation edge arrays
    • a homogeneous token view (type ids, CSR) for graph transformers
  • Persistence. Files are checksummed, saved atomically and fully re-validated on load.
  • Python bindings. pyo3/numpy, zero-copy, with the GIL released. There are PyG adapters (to_hetero_data, to_token_graph).
  • Leakage tests. Property tests compare the store against a naive reference model and probe at knowledge-time boundaries. Deliberately injected off-by-one leaks are all caught.
  • Performance. On a benchmark of 3k securities × 10 years, with fundamentals, 30k edges and 200k articles: about 6.5M bar rows/s ingest, and a snapshot takes about 3 ms (K=1) to 9 ms (K=64).

Stage 2: point-in-time data layer (026f6c4)

  • Provider abstraction. Each provider declares a knowledge policy. The Alpha Vantage client is removed.
  • Parquet store. Bitemporal, with content-hashed parts, conflict detection and atomic publish.
  • SEC EDGAR provider. Knowledge time is the SEC acceptance timestamp, read conservatively. The User-Agent must come from the user or the environment; the code never invents one.
  • Quarterly fundamentals. Derived bitemporally from as-reported XBRL. Q4 is computed as FY minus 9M or minus the three quarters, YTD cash flows are differenced, and restatements become new observations.

Stage 3: point-in-time backtester (34414f1)

  • Rust execution simulator.
    • Timing: decide after the close, execute at the next open. ADV and volatility are lagged.
    • Costs: commission, spread, square-root impact, participation cap, borrow and financing.
    • Corporate actions: splits and dividends. Halts freeze positions; delistings force an exit with a haircut.
  • Python side. Market panels, multi-horizon total-return labels, and walk-forward splits with purge and embargo.
  • Risk-first metrics. Log-growth, CVaR, max drawdown, and probabilistic and deflated Sharpe.

Testing

  • Rust: unit tests plus property tests (PROPTEST_CASES=2048 in CI), clippy -D warnings, fmt, and an MSRV 1.88 check.
  • Python: ruff, strict mypy, and pytest on 3.10 and 3.13. The PyG adapter is tested with CPU torch.
  • The EDGAR adapter is tested on synthetic fixtures only, because the dev container's network blocks sec.gov.

Generated by Claude Code

Stage 1 of the revival (see docs/ROADMAP.md).

The 2024 prototype could not support leakage-free research: timestamps
were process-local `std::time::Instant`s, `to_pyg` copied one sample
node's features into every row, export order came from HashSet
iteration, covariance edges centred on row means, and `get_symbols` was
a `todo!()`. It is replaced rather than patched.

moonrs (Rust):
- UTC-nanosecond timestamps and half-open validity intervals; every fact
  carries a valid time and a known time.
- Runtime, append-only schema: node kinds (entity or windowed event),
  fixed-width f32 feature channels with nullability and bounds, typed
  relations.
- Interval-versioned node lifetimes and edges resolved by latest
  knowledge time, so corrections, delistings and ended relationships
  appear exactly when they became knowable.
- Revision-aware observation series with block-min skipping for K-step
  history lookups.
- Strict, atomic, idempotent batch ingestion with rollback.
- Deterministic snapshots (rows sorted by key) with [N, K, D] history
  tensors, presence masks and per-slot valid/known times, plus a
  homogeneous token view (type ids, CSR) for graph transformers.
- Checksummed, versioned, atomically written store files, fully
  re-validated on load.
- Property tests against an independent reference model: exact
  agreement, causality (future facts cannot change a snapshot), order
  independence, round-trip, batch atomicity; probes concentrate on
  knowledge-time boundaries.
- pyo3 0.30 / numpy bindings that read inputs in place, move outputs to
  NumPy without copies and release the GIL.

Python package (maturin, python/automoonbot): typed wrapper with strict
time conversion (naive datetimes rejected), PyG HeteroData and
graph-transformer token-graph conversion, tests, CI.

Removes the stub moonpy package, the Alpha Vantage client and the Redis
streamer; they remain in history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Stage 2 of the revival (see docs/ROADMAP.md).

- Canonical Arrow schemas for entities, identifiers, filings, XBRL facts,
  unadjusted bars, corporate actions, articles and relations; every row
  carries known_time and source.
- ParquetStore: append-only, partitioned by known_time year, atomic
  multi-partition writes, idempotent replays, conflicting versions
  rejected (within a batch and against stored data), as-of and
  latest-version reads, compaction, cross-process writer lock.
- Provider interface with an explicit knowledge policy (exact /
  conservative / estimated).
- SEC EDGAR provider: submissions (with paginated history) and company
  facts; acceptance times read as US/Eastern (the conservative choice
  given the API's misleading 'Z'), fallback to 22:00 ET on the filed
  date, mandatory User-Agent, host allow-list, rate limiting, retries,
  on-disk cache.
- Bitemporal quarterly fundamentals from as-reported XBRL: discrete
  quarters derived from cumulative spans (Q4 = FY - 9M or FY - quarters,
  year-to-date cash-flow differencing), restatements emitted as new
  observations when filed.
- Loaders from the store into the temporal graph (companies,
  filing events, filed edges, fundamentals).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Stage 3 of the revival (see docs/ROADMAP.md).

- moonrs::backtest: decisions after bar t execute at the open of t+1;
  sizing/pricing uses only quantities known before that open. Models
  commission, half-spread, square-root impact, participation cap,
  borrow, cash/margin financing, splits, dividends, halts (frozen,
  valued at last close) and delistings (forced exit with haircut);
  enforces long-only, gross and per-name limits; ruin is terminal.
  Unit tests plus property tests (frictionless equity matches an
  independent reference; costs never increase equity).
- Python bindings: Market (shared, immutable) and Simulator with step()
  and a GIL-free batched run().
- MarketPanel from dense arrays or the Parquet store: listing spans,
  halt-aware close carry-forward, lagged ADV and volatility via prefix
  sums, ex-date mapping of corporate actions, per-bar decision times.
- Multi-horizon forward total log returns on execution prices, with
  realization indices for purging.
- Walk-forward folds (expanding or rolling) with label purge and embargo.
- Metrics: log-growth, CAGR, volatility, CVaR, max drawdown and time
  under water, Calmar, Sharpe/Sortino, probabilistic and deflated Sharpe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Stage 4. Every strategy implements one Strategy protocol and is scored by
one harness: each fold is fitted on a panel truncated before its test
window, all test windows form one continuous simulated path, and
check_causal recomputes targets on truncated panels to prove no future bar
was used. compare() reports deflated Sharpe across all trials.

- Simulator: NaN target weights hold current shares (no trade), so
  discrete-trade strategies let weights drift; property test extended.
- MarketPanel: high/low, truncate, causal log_returns and total-return index.
- Rule baselines: cash, buy-and-hold, equal weight, inverse volatility,
  cross-sectional momentum, trend following (vectorized, causal).
- PGPerceptron: descriptors vectorized and verified against the original
  formulas (to 1e-13), literal trade-manager port, same policy network,
  REINFORCE with batched log-prob recomputation under recorded dropout
  masks, the server's retrain/deploy rule. "legacy" keeps the original's
  defects (position input always cash, rewards credited to the next
  action, no-op best-episode revert, live manager at leverage 0);
  "repaired" fixes them; selection is in-sample or validation-based.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
@SnowCheetos SnowCheetos self-assigned this Nov 14, 2026
Drop Python 3.10 support: requires-python >=3.14 with abi3-py314, modern
dependency floors (numpy 2.3, pyarrow 22, torch 2.9), ruff/mypy targeting
3.14, PEP 695 type aliases, and no `from __future__ import annotations`
(deferred annotations are the default). Rust stays on edition 2024 with
rust-version 1.97. CI runs a single 3.14 Python job.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
- YahooProvider (ESTIMATED knowledge policy): hourly/daily bars converted
  back to as-traded prices from Yahoo's split-adjusted series, bar ends at
  the regular session close, in-progress bars dropped, dividends per
  as-traded share, ex-date actions.
- walk_forward_targets + simulate: targets do not depend on costs, so one
  fit can be scored under several cost assumptions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
…ndent

CI sorted imports differently from a local editable install because ruff
guessed whether automoonbot was first party.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
…ularity

range=max silently returns weekly, monthly or quarterly bars for long
histories. Request it as period1/period2 instead and reject any response
whose dataGranularity differs from the requested interval.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
One accession can be filed by several entities (a parent and its
subsidiary), which the accession-only key rejected as a conflict.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
…policy

- models/features: causal per-security price features, cross-sectionally
  standardized per row (median/MAD), never with future statistics.
- models/universe: company -> industry -> sector graph in the
  point-in-time store; the model reads each day's structure from the
  snapshot known at that day's decision time.
- models/transformer: PatchTST-style temporal encoder per company, GPS-style
  graph layers (typed message passing along known edges plus fused global
  attention with absent tokens masked), chained MTP horizon heads with
  Student-t outputs, and a policy head (count-invariant exposure, softmax
  allocation, per-name cap).
- models/strategy: trained directly on realized cost-adjusted portfolio
  log-growth minus a CVaR penalty plus the auxiliary NLL; prices are
  exogenous, so the path is differentiable and no critic is needed. Random
  sub-universes per batch, early stopping on a purged validation tail,
  warm starts across folds, a no-trade band and an optional drawdown
  overlay. Inference encodes each day alone with a fixed token layout, so
  the causality audit holds bit for bit.
- experiments/stage5_sp500_daily.py: yearly walk-forward on S&P 500 daily
  bars against rule baselines under three cost assumptions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Stage 4: across three seeds no PGPerceptron variant beats an
exposure-matched passive SPY position; seed spread exceeds the variant
differences.

Stage 5: on current S&P 500 constituents the graph transformer beats every
baseline and factor control out of sample (alpha about 6-8% a year, t about
3), but the universe is survivorship-biased and the model tilts to
high-volatility names, so the result needs a point-in-time universe before
it means anything.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
- MarketPanel.member / investable / with_membership: a point-in-time
  universe; prices of non-members stay available as feature history, but
  rules and models only see and hold investable securities.
- data.membership: dated constituent snapshots -> [T, S] membership on
  each bar's trading date; require_history drops membership runs whose
  price series starts long after the run (symbols reused by later
  companies or ETFs); coverage reports the share of member-days with
  prices.
- Features standardize against the universe; the graph transformer masks
  non-members as tokens and never allocates to them.
- Stage 5 experiment: --membership/--sic/--instruments for a point-in-time
  S&P 500 classified uniformly by SEC SIC codes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
On historical S&P 500 membership (former members' prices, SIC
classification) the graph transformer makes +10.5% a year against +10.7%
for equal weight; its factor alpha is -1.0% (t -0.5). The survivor-only
run's 6-8% alpha came from the universe. Write-up in
docs/results/stage5-pit.md; the survivor-only page now points to it.

The universe description now records coverage before the history check
and the symbols the check removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Simulator (moonrs::backtest, now a module):
- Instruments per column: equity, index (reference level), option
  (American/European, physical or cash settlement, deliverable), future.
- Option premium, expiry exercise/assignment, rational early exercise,
  OCC-style split adjustments of strike and deliverable.
- Futures daily variation margin and close or next-open final settlement.
- Per-contract commissions, option half-spread, lots, optional absolute
  per-bar half-spread, unit (contract count) targets.
- Margin models: none (default, unchanged behavior), Reg T, and TIMS-style
  portfolio margin with Black-Scholes/Black-76 repricing at implied vol;
  initial-margin cutbacks and maintenance liquidations by bisection.
- Unit tests plus property tests (futures equity equals summed variation
  margin, exercise at intrinsic conserves equity, margin homogeneity).

Python:
- Bindings for instruments, margin and unit targets; MarketPanel
  with_instruments, with_half_spread, with_contracts, and
  from_store(align="session") for 16:15 option bars beside 16:00 stock
  bars. from_store now rejects two bars of one security in one row.
- Massive provider: point-in-time chain selection (a contract enters on
  the first close near its strike), unadjusted daily bars, the
  option_contracts dataset. The API key is sent only as an Authorization
  header and never reaches URLs, cache keys, rows or reprs.
- docs/derivatives.md describes the design and its limitations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
…ment

- Weights of options are now their notional (deliverable x underlying
  price), as for futures, so writing calls on a stock weight of 1 is a
  call weight of -1 and both legs are sized from the stock's open; the
  gross limit counts the same notional. Underlyings without a price make
  the option unsizable by weight (held) rather than producing NaN units.
- OptionWrite baseline: covered calls and cash-secured put writes on the
  nearest monthly contract, held to expiration, chosen only from
  contracts with a bar at the decision (causality-audited in tests).
- experiments/options_spy.py: ingest SPY bars (Yahoo) and point-in-time
  monthly chains (Massive), then buy-and-hold vs covered calls and put
  writes under portfolio margin and two cost assumptions, with the share
  of stale option marks reported. Smoke-tested on the fake API chain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
- backtest.synthetic: monthly chains listed at the previous expiration's
  close, priced with generalized Black-Scholes at a VIX-based ATM vol with
  a standardized-moneyness skew, floored at intrinsic and the tick; opens
  use the open's spot and index level with the last close's rate. Tested
  for listing rules, expiry at intrinsic, put-call parity, and that no
  price changes when later inputs change.
- _moonrs.option_value exposes the simulator's own pricing, vectorized.
- Market rate series (Market(rate=...), MarketPanel.with_rate): cash and
  margin accrue at the rate known at each close plus cash_spread /
  margin_spread, and portfolio margin reprices with it.
- Yahoo provider accepts index symbols (^VIX, ^IRX) and URL-quotes them.
- experiments/options_synthetic.py and docs/results/options-synthetic.md:
  SPY covered calls and put writes 1996-2026 vs buy-and-hold and T-bills.
  The ATM/VIX ratio (0.86) is fitted to the Cboe PutWrite index on
  1996-2010; on 2011-2026 the synthetic put write runs 1.7%/yr above it
  (correlation 0.95). Writers beat SPY on risk-adjusted terms in
  1996-2010 but not in 2011-2026.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACHC7e3BMB6p8xWQsgTWyo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants