feat: hotpath optimizations, parity knobs, docs rewrite, dep cleanup - #3
Merged
Merged
Conversation
- Fix zipline_strict profile: change short_cash_policy from credit_proceeds to credit (root cause of 45% trade deficit, not code bugs) - Add standalone LEAN profile with Mode.LEAN and "quantconnect" alias - Harden credit_proceeds policy to reserve 1x short notional - Add settlement_delay config knob (T+N settlement) wired through account, gatekeeper, broker, and fill_executor - Add benchmark suite for cross-framework parity comparisons - Update .gitignore for validation artifacts
Zipline allows cash to go negative and never rejects orders for insufficient funds. The new skip_cash_validation config knob bypasses gatekeeper validation entirely, faithfully emulating this behavior. Results on 250×20yr synthetic benchmark: - Zipline parity: 45% trade deficit → 0.00% (exact match) - Final value gap: $12 on $10.5M (0.0001%) - 9.2x faster than Zipline, 2.7x less memory Also fixes DateOffset overflow in benchmark suite for older pandas versions without pandas-market-calendars.
…eservation - Correct LEAN profile from next_bar/open to same_bar/close (matching LEAN's OnData fill semantics) — reduced gap by 92% - Add execution_price config knob with CLOSE/OPEN/MID/VWAP dispatch in fill_engine.py - Add buying_power_reservation knob (LEAN-style shadow cash pool that reserves buying power at order submission time) - Fix credit-model inflation in shadow check: shorts now consume buying power (abs(opened) * price) instead of crediting cash - Add T+2 settlement to lean_strict profile - Update lean_strict: buying_power_reservation=True, settlement_delay=2 LEAN parity: 663→589 trades (11% reduction), $13K→$7.2K value (45% reduction)
…power - Add SEQUENTIAL fill ordering: processes orders in submission order without exit/entry separation, with mark-to-market after each fill. When buying_power_reservation is enabled, entries bypass the gatekeeper since the shadow already validated them at submission time. - Add settlement_reduces_buying_power config flag (default True): controls whether unsettled cash is deducted from gatekeeper's available buying power. Set False for frameworks where settlement doesn't reduce fill-time buying power. - Wire settlement_reduces_buying_power through BacktestConfig → Broker → Gatekeeper with full serialization round-trip support. - Add tests: sequential interleaving, entry-before-exit rejection, settlement flag round-trip. Note: lean_strict profile remains exit_first (best parity at +589/+$7.2K). SEQUENTIAL mode is infrastructure for future use.
Rename CommissionModel/SlippageModel enums to CommissionType/SlippageType for clarity (they select a type, not a model instance). Rename config fields commission_model/slippage_model to commission_type/slippage_type throughout. Clean up engine.py by moving order processing logic to core modules. Remove unused account state module. Add immediate_fill config knob. Simplify config.py by removing deprecated mypy-era aliases. Update all tests to match renamed fields and removed modules. Fix result.py docstring (asset→symbol, commission→fees) and test fixtures.
Archive 35 one-off validation/debug scripts to validation/archived/. Remove LEAN workspace outputs and Nautilus catalog from git. Remove mypy config from pyproject.toml (using ty). Update all AGENT.md files with accurate line counts. Update README.md, LIMITATIONS.md, and validation/README.md. Add all 7 account presets to docs/user-guide/accounts.md.
Rewrite all broken docs (quickstart, index, installation) with correct API. Add 8 new guides: execution semantics, configuration, profiles, risk management, data feed, rebalancing, results, and architecture overview. Expand API reference with full mkdocstrings coverage. 15 files, ~2,700 lines. All examples verified against source.
Remove ml4t-style (phantom, not on PyPI), pyarrow (transitive via polars), tables, sortedcontainers, numba, pydantic, structlog, python-dateutil. None are imported in src/. Core deps: polars, pandas, numpy, PyYAML, pandas-market-calendars.
…tions-and-benchmarks # Conflicts: # src/ml4t/backtest/core/execution_engine.py # tests/test_config_wiring.py
There was a problem hiding this comment.
Pull request overview
Prepares an “alpha release” by consolidating performance-focused core changes, expanding cross-framework parity controls (including a new LEAN profile), and doing a broad documentation + dependency cleanup.
Changes:
- Reworks configuration and validation wiring across core engine/tests (e.g.,
BacktestConfig, commission/slippage enums, execution price), and adds settlement-delay accounting. - Optimizes hot paths (notably
DataFeed) and adds benchmark/contract coverage around performance + parity. - Large docs/navigation refresh (new guides + API ref restructuring) and repository cleanup (archiving scripts, removing workspace artifacts, pruning deps).
Reviewed changes
Copilot reviewed 81 out of 119 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| validation/zipline/scenario_01_long_only.py | Updates validation scenario to new BacktestConfig + enum-based commission/slippage configuration. |
| validation/vectorbt_oss/scenario_01_long_only.py | Same as above, plus explicit execution_price to match VectorBT semantics. |
| validation/nautilus/catalog/data/quote_tick/EURUSD.SIM/2020-01-01T17-00-10-447000000Z_2020-01-31T16-59-56-198000000Z.parquet | Adds Nautilus catalog parquet sample data. |
| validation/nautilus/catalog/data/currency_pair/EURUSD.SIM/1970-01-01T00-00-00-000000000Z_1970-01-01T00-00-00-000000000Z.parquet | Adds Nautilus catalog parquet sample data. |
| validation/lean/workspace/test_validation/research.ipynb | Removes LEAN workspace artifact. |
| validation/lean/workspace/test_validation/main.py | Removes LEAN workspace artifact. |
| validation/lean/workspace/test_validation/config.json | Removes LEAN workspace artifact. |
| validation/lean/workspace/test_validation/backtests/2026-01-01_11-48-59/config | Removes LEAN workspace artifact. |
| validation/lean/workspace/test_validation/backtests/2026-01-01_11-48-59/code/research.ipynb | Removes LEAN workspace artifact. |
| validation/lean/workspace/test_validation/backtests/2026-01-01_11-48-59/code/main.py | Removes LEAN workspace artifact. |
| validation/backtrader/scenario_01_long_only.py | Updates validation scenario to new config/enums. |
| validation/archived/vbt_pro_perf_comparison.py | Archives a performance comparison script. |
| validation/archived/trailing_trigger_debug.py | Archives parity/debug script. |
| validation/archived/trailing_stop_debug.py | Archives parity/debug script. |
| validation/archived/trailing_stop_compare.py | Archives parity/debug script. |
| validation/archived/trailing_reentry_debug.py | Archives parity/debug script. |
| validation/archived/single_asset_debug.py | Archives parity/debug script. |
| validation/archived/signal_only_compare.py | Archives parity/debug script. |
| validation/archived/scale_test.py | Archives parity/debug script. |
| validation/archived/reentry_debug.py | Archives parity/debug script. |
| validation/archived/large_scale_perf.py | Archives parity/debug script. |
| validation/archived/debug_reentry.py | Archives parity/debug script. |
| validation/archived/debug_pnl_mismatch.py | Archives parity/debug script. |
| validation/archived/debug_hwm_precise.py | Archives parity/debug script. |
| validation/archived/debug_exit_price_diff.py | Archives parity/debug script. |
| validation/archived/debug_asset000.py | Archives parity/debug script. |
| validation/archived/continuous_signal_debug.py | Archives parity/debug script. |
| validation/archived/calendar_scale_test.py | Archives parity/debug script. |
| validation/archived/basic_entry_debug.py | Archives parity/debug script. |
| validation/archived/README.md | Documents archived validation scripts and their purpose. |
| tests/test_strategy_templates.py | Updates tests to new Engine.from_config + BacktestConfig presets. |
| tests/test_result.py | Updates trade dataframe schema expectations and adds integration coverage for enrichment. |
| tests/test_extreme_conditions.py | Updates config validation tests to new config/types. |
| tests/test_core.py | Refactors tests to new config object usage + enum changes; removes deprecated paths. |
| tests/regression/test_golden_strategies.py | Updates regression tests from model objects to enum-based config wiring. |
| tests/contracts/test_public_api_surface.py | Updates public API surface contract (removes Mode, adds TakeProfit). |
| tests/contracts/test_profile_parity_basics.py | Expands profile list (adds lean) and adds LEAN/zipline strict contract tests. |
| tests/contracts/test_ledger_invariants.py | Ensures invariants tests run with explicit zero-cost config. |
| tests/contracts/test_execution_contracts.py | Adds execution_price to execution contracts and moves to config-based invocation. |
| tests/contracts/test_book_parity_behaviors.py | Updates parity-behavior contracts to new commission/slippage enums and removes FillTiming. |
| tests/benchmark/test_hotpath_benchmarks.py | Adds benchmark tests and a legacy reference feed for regression guarding. |
| tests/benchmark/test_cross_framework_selected.py | Adds opt-in cross-framework benchmark runner behind env var + import guards. |
| tests/accounting/test_settlement_delay.py | Adds unit + integration coverage for settlement delay (T+N). |
| tests/accounting/test_cash_account_policy.py | Adds coverage for credit_proceeds short-cash reservation behavior. |
| src/ml4t/backtest/strategies/init.py | Updates doc example to new config-based engine creation. |
| src/ml4t/backtest/strategies/AGENT.md | Updates AGENT module inventory after docs rewrite/reorg. |
| src/ml4t/backtest/risk/types.py | Micro-optimization: reuses a singleton HOLD action. |
| src/ml4t/backtest/risk/position/static.py | Cleans imports; aligns stop/take-profit helpers with shared types. |
| src/ml4t/backtest/risk/position/AGENT.md | Updates AGENT module inventory. |
| src/ml4t/backtest/risk/portfolio/AGENT.md | Updates AGENT module inventory. |
| src/ml4t/backtest/risk/AGENT.md | Updates AGENT module inventory. |
| src/ml4t/backtest/result.py | Updates trade dataframe docs to symbol + fees naming. |
| src/ml4t/backtest/models.py | Clarifies futures commission/slippage docstrings and usage notes. |
| src/ml4t/backtest/execution/fill_executor.py | Adds settlement-hold behavior + buying-power sync fixes and minor numeric tolerances. |
| src/ml4t/backtest/execution/AGENT.md | Updates AGENT module inventory. |
| src/ml4t/backtest/datafeed.py | Hotpath optimization: precomputed column indices + faster per-row extraction + internal cached views. |
| src/ml4t/backtest/core/shared.py | Adds shared constants/helpers (e.g., cash tolerance, exit-order detection). |
| src/ml4t/backtest/core/risk_engine.py | Uses position context directly and tightens initial-quantity handling. |
| src/ml4t/backtest/core/fill_engine.py | Adds execution-price dispatch and new spendable-cash based affordability logic. |
| src/ml4t/backtest/core/AGENT.md | Adds new core subpackage inventory doc. |
| src/ml4t/backtest/analytics/trades.py | Fixes trade filtering to use direction field. |
| src/ml4t/backtest/analytics/AGENT.md | Updates analytics AGENT inventory and bridge section. |
| src/ml4t/backtest/accounting/policy.py | Introduces spendable-cash concept + short-cash policies + central cash tolerance. |
| src/ml4t/backtest/accounting/gatekeeper.py | Makes order validation use spendable cash and optionally account for unsettled cash. |
| src/ml4t/backtest/accounting/account.py | Adds settlement-hold tracking and removes legacy fill-application logic. |
| src/ml4t/backtest/accounting/AGENT.md | Updates accounting AGENT inventory. |
| src/ml4t/backtest/init.py | Updates public API surface exports (removes Mode, adds TakeProfit). |
| src/ml4t/backtest/AGENT.md | Updates package inventory for new structure and line counts. |
| scripts/pr_merge_release.sh | Adds a GH CLI-based merge+tag automation script. |
| pyproject.toml | Removes unused deps, adds comparison/dev deps, swaps mypy config for ty config. |
| mkdocs.yml | Restructures nav to include new concepts/guides. |
| docs/user-guide/results.md | Adds a new Results & Analysis guide. |
| docs/user-guide/rebalancing.md | Adds a new Rebalancing guide. |
| docs/user-guide/profiles.md | Adds a new Profiles guide explaining presets and parity results. |
| docs/user-guide/orders.md | Rewrites order docs (market/limit/stop/brackets, ordering, lifecycle). |
| docs/user-guide/data-feed.md | Adds a new Data Feed guide and performance notes. |
| docs/user-guide/accounts.md | Updates account/cost configuration to new commission/slippage enums and profiles. |
| docs/index.md | Rewrites landing page: parity claims, examples, docs map. |
| docs/getting-started/installation.md | Updates installation requirements, repo URL, and optional deps section. |
| docs/concepts/how-it-works.md | Adds an architecture/execution-flow explanation. |
| docs/api/index.md | Expands API reference structure with more explicit members/sections. |
| README.md | Updates README for profiles/parity/performance claims and new capabilities. |
| LIMITATIONS.md | Updates settlement limitations section and validation status tables. |
| AGENT.md | Updates repo-level AGENT inventory and structure. |
| .gitignore | Expands ignores for validation artifacts/workspaces. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Final alpha release prep. This branch accumulates all work since v0.1.0a9:
Performance & Parity
FillOrdering.SEQUENTIAL,settlement_reduces_buying_power,execution_price,buying_power_reservation,skip_cash_validationDocumentation Rewrite
Dependency Cleanup
Repo Cleanup
Test plan
uv buildproduces wheel with correct 5 depsuv run pytestworks (ml4t-style blocker resolved)