backtest_pine_grid
Optimize PineScript strategies by parameter sweeping across input and override grids, then rank results by key metrics to find the best configuration.
Instructions
Use when the user wants to optimize, sweep, tune, or compare PineScript parameter values (e.g. 'try fast length 8/12/19', 'find the best commission/qty settings') rather than test a single configuration — for one fixed configuration use backtest_pine. Run a parameter sweep: transpile the Pine source ONCE (locally, in-container), then re-run the same compiled strategy against the OHLCV CSV across the cartesian product of inputs × overrides grids. Returns a ranked list of {inputs, overrides, summary, elapsed_seconds} entries sorted by sort_by descending, plus the top entry under best. Cap: max_combinations (default 64). Set concurrency > 1 to run backtests in parallel — each docker container has its own startup overhead, so 2-4 is usually plenty.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | PineScript v6 source. | |
| ohlcv_csv_path | Yes | Path to OHLCV CSV (same format as backtest_pine). | |
| image | No | Docker image override. Defaults to ghcr.io/pineforge-4pass/pineforge-engine:latest. | |
| inputs | No | Grid of input.*() names → list of values to sweep. Example: {"Fast Length": [8, 12, 19], "Slow Length": [21, 26, 39]} | |
| overrides | No | Grid of strategy(...) header overrides → list of values, one axis per key. Example: {"default_qty_value": [1, 5], "commission_value": [0.04]}. Call list_engine_params for the full catalog with types and enum values. | |
| fixed_inputs | No | Inputs applied to every combo (overridden by per-combo `inputs` keys). | |
| fixed_overrides | No | Overrides applied to every combo (overridden by per-combo `overrides` keys). | |
| runtime | No | Engine runtime args applied to every combo in the sweep. Same shape as backtest_pine.runtime — input_tf / script_tf / bar_magnifier / magnifier_samples / magnifier_dist. Currently fixed across the grid (not swept); add to the grid axes through future versions if you need to vary them. | |
| max_combinations | No | Hard cap on combinations. Default 64. | |
| concurrency | No | Parallel backtests. Default 1. | |
| include_trades | No | Include the per-trade list in each result. Default false (saves tokens). | |
| sort_by | No | summary.* field to rank by, descending. Default net_pnl. | |
| report_path | No | Where to write the full sweep JSON IF it is too large to return inline. Oversized sweeps are offloaded here and the tool returns the best + top-ranked combinations + report_path; read the file for all combinations. Defaults to pineforge-grid-<timestamp>.json in the working dir. |