How chrislernunes/pluto works
1. Repository role
- Pluto is a Python research backtesting platform centered on rule-based trading strategies.
- Its architecture is organized around a single flow: market data in, strategy decisions out, executed trades recorded, then metrics and optimization consume the resulting tradebook.
2. Top-level execution pipeline
- The main orchestration lives in backtest/, which coordinates strategy setup, simulation/backtest runs, and positional-vs-non-positional variants.
- The backtest layer does not appear to contain strategy logic itself; it is the control plane that wires together data access, the engine, and strategy classes.
3. Core execution engine
- engine/ is the runtime boundary for trade execution and state management.
- engine/datainterface.py likely abstracts how historical or live-like data is delivered to strategies.
- engine/ems.py and engine/ems_db.py suggest two data/execution backends, with the README indicating a Redis-backed path versus a database-backed path depending on configuration.
- This is the layer where entries, exits, position updates, and tradebook creation are centralized.
4. Strategy boundary
- strategies/ contains the actual trading rules, separated into:
- strategies/others/ for established research/backtest strategies,
- strategies/live/ for strategies shaped for live-like integration,
- strategies/wip/ for experimental or in-progress ideas.
- Examples like tbs, ut, spikesell, pbsar, and btst indicate the repo is strategy-agnostic: each strategy plugs into the same engine interface but implements its own entry/exit logic and parameterization.
5. Backtest and simulation variants
- backtest/backtester.py, backtest/backtester_pos.py, backtest/sim.py, backtest/sim_new.py, backtest/sim_strat.py, and backtest/sim_strat_pos.py indicate multiple execution modes.
- The “pos” suffix strongly suggests a positional variant of the same simulation/backtesting flow.
- The notebook backtest/backtester.ipynb is likely used for exploratory research and manual analysis rather than production execution.
6. Configuration model
- backtest/configs/*.json stores parameter presets for different strategy families.
- These configs are the main way the same engine/strategy stack is reused across experiments without changing code, which supports reproducibility and systematic sweeps.
7. Metrics and tradebook analysis
- metrics/ is a downstream analytics layer that consumes executed trades rather than raw candles.
- metrics/metrics.py, metrics/analyze_tradebooks.py, and metrics/margin_calc.py compute performance and risk outputs such as PnL, drawdown, trade statistics, and margin-related measures.
- This reflects the repo’s “tradebook-first” design: execution produces a tradebook, and all evaluation is derived from that artifact.
8. Optimization and research automation
- optimization/ contains parameter search and robustness tooling.
- Files like *_optimizer.py, walkforward_optimizer.py, ut_walkforward.py, and generate_reports.py suggest grid search, walk-forward testing, and report generation.
- visualizer_generic.py and strategy-specific visualizers indicate the optimization layer also turns numeric results into comparative research outputs.
9. Shared utilities
- utils/definitions.py, utils/sessions.py, utils/logging_config.py, and utils/utility.py provide shared constants, session/time-window logic, logging setup, and helper functions.
- These utilities are important architectural glue because strategy correctness depends heavily on trading sessions, weekday filters, and consistent parameter naming/UID generation.
10. Testing and validation
- tests/ contains notebooks and Python test files focused on engine behavior and specific strategy validation.
- The presence of validate_tbs.py and strategy-specific tests suggests the repo emphasizes regression checks on execution semantics, not just unit tests for helpers.
11. Important data flow for a diagram
- The typical flow is: configuration and utilities define a run, a strategy class produces signals, the engine executes them against historical data, the backtester/simulator records tradebook output, metrics analyze the tradebook, and optimization loops repeat this across parameter sets.
- The key architectural boundary is between strategy logic and execution/measurement: strategies decide “what,” the engine handles “how,” and metrics/optimization handle “how well.”
12. Technology and runtime shape
- The project is Python-based and research-oriented, with optional acceleration hinted by the README’s Cython note.
- External state/storage is abstracted behind the engine layer, especially via the Redis vs database split, which matters for deployment diagrams because it changes the data source but not the strategy interface.
Main entry points: utils Shared utils · sim_strat.py Strategy sim · backtester.py Backtest run · datainterface.py Data interface
Components 21
Control plane
Backtest orchestration, simulation variants, and configuration presets.
- Backtest run · Coordinates strategy setup and backtest/simulation entry points.
backtest/backtester.py - Positional run · Positional variant of the backtest flow.
backtest/backtester_pos.py - Simulator · Core simulation path used by research runs.
backtest/sim.py - New sim · Alternative simulation implementation.
backtest/sim_new.py - Strategy sim · Simulation wrapper that drives strategy execution.
backtest/sim_strat.py - Pos sim · Positional simulation wrapper.
backtest/sim_strat_pos.py - Config presets · Strategy parameter presets used to reproduce runs.
backtest/configs
Execution runtime
Strategy interface and trade execution/state management.
- Data interface · Abstracts how historical data is delivered to the engine.
engine/datainterface.py - EMS Redis · Redis-backed execution/state path.
engine/ems.py - EMS DB · Database-backed execution/state path.
engine/ems_db.py
Research layer
Analytics and optimization built on executed tradebooks.
- Tradebook · Executed trades and position history consumed downstream.
- Metrics · Performance, risk, and margin calculations on tradebooks.
metrics/metrics.py - Tradebook analysis · Aggregates and analyzes tradebooks.
metrics/analyze_tradebooks.py - Margin calc · Margin-related evaluation for executed trades.
metrics/margin_calc.py - Optimizer · Coordinates parameter search and repeated experiments.
optimization/optimization_runner.py - Walk-forward · Walk-forward optimization and validation flow.
optimization/walkforward_optimizer.py - Reports · Generates comparative research outputs and summaries.
optimization/generate_reports.py
Strategies
Rule-based strategy implementations by maturity and deployment mode.
- Research strats · Established backtest strategies.
strategies/others - Live strats · Strategies adapted for live-like integration.
strategies/live - WIP strats · Experimental or in-progress strategies.
strategies/wip
Shared code
Cross-cutting helpers for sessions, logging, and definitions.
- Shared utils · Definitions, sessions, and logging utilities used across runs.
utils
Connections 25
- Config presets → Backtest run: parameterize · Presets configure a run.
- Config presets → Optimizer: sweep · Optimization iterates over preset spaces.
- Shared utils → Backtest run: support · Shared helpers shape execution and naming.
- Shared utils → Research strats: support · Strategies depend on common session and definition logic.
- Shared utils → Live strats: support · Live strategies reuse shared helpers.
- Shared utils → WIP strats: support · Experimental strategies reuse shared helpers.
- Backtest run → Simulator: run · Backtest orchestration enters simulation.
- Positional run → Pos sim: run · Positional backtests use the positional simulator.
- Backtest run → Strategy sim: run · Strategy-driven backtests use the strategy simulator.
- Simulator → Data interface: read · Simulation consumes market data through the interface.
- New sim → Data interface: read · Alternative simulation reads through the same boundary.
- Strategy sim → Research strats: invoke · Strategy simulation executes strategy logic.
- Strategy sim → Live strats: invoke · Strategy simulation can host live-shaped strategies.
- Strategy sim → WIP strats: invoke · Strategy simulation can host experimental strategies.
- Pos sim → Research strats: invoke · Positional strategy simulation executes strategy logic.
- Data interface → EMS Redis: backend · One execution/data path is Redis-backed.
- Data interface → EMS DB: backend · Another execution/data path is database-backed.
- EMS Redis → Tradebook: record · Executed actions are accumulated into a tradebook.
- EMS DB → Tradebook: record · Executed actions are accumulated into a tradebook.
- Tradebook → Metrics: analyze · Metrics are derived from executed trades.
- Tradebook → Tradebook analysis: analyze · Tradebook analysis consumes the same artifact.
- Tradebook → Margin calc: analyze · Margin calculations consume executed trade history.
- Tradebook → Optimizer: evaluate · Optimization compares parameter sets via tradebook results.
- Optimizer → Walk-forward: validate · Optimizer can invoke walk-forward validation.
- Optimizer → Reports: publish · Optimization produces reports and summaries.