Backtesting

Runtime options and reports

BacktestOptions dataclass

BacktestOptions(
    input_timeframe: str = "",
    script_timeframe: str = "",
    bar_magnifier: bool = False,
    magnifier_samples: int = 4,
    magnifier_distribution: MagnifierDistribution = ENDPOINTS,
    trace_enabled: bool = False,
    chart_timezone: str | None = None,
    trade_start_time_ms: int | None = None,
)

Runtime options passed to run_backtest_full.

MagnifierDistribution

Bases: IntEnum

PineForge bar-magnifier path sampling distributions.

BacktestReport dataclass

BacktestReport(
    summary: Mapping[str, JsonValue],
    metrics: Mapping[str, Mapping[str, JsonValue]],
    trades: tuple[Mapping[str, JsonValue], ...],
    security_diagnostics: tuple[
        Mapping[str, JsonValue], ...
    ],
    trace: tuple[Mapping[str, JsonValue], ...],
    equity_curve: tuple[Mapping[str, JsonValue], ...],
)

A detached, JSON-safe copy of pf_report_t.

to_dict

to_dict() -> dict[str, JsonValue]

Return a mutable JSON-shaped representation.

PineForgeBacktestRunner

PineForgeBacktestRunner(library: CDLL)

Thin owner-safe wrapper around one compiled PineForge strategy library.

load classmethod

load(
    strategy_library: str | Path,
) -> PineForgeBacktestRunner

Load a compiled strategy shared library from disk.

run

run(
    bars: Sequence[Bar],
    *,
    instrument: Instrument,
    options: BacktestOptions | None = None,
    strategy_params: Mapping[str, JsonValue] | None = None,
) -> BacktestReport

Run confirmed normalized bars and return a detached report.

EngineBacktestError

Bases: RuntimeError

A PineForge historical backtest could not be completed.

Published release container

DockerBacktestRuntime dataclass

DockerBacktestRuntime(
    image: str = DEFAULT_RELEASE_IMAGE,
    pull_policy: PullPolicy = "missing",
    timeout_seconds: float = 300.0,
)

Pull and execute an immutable pineforge-release image.

ensure_image

ensure_image() -> str

Apply the configured pull policy and return the immutable image ref.

run

run(
    pine_source: str,
    bars: Sequence[Bar],
    *,
    instrument: Instrument,
    source: str,
    options: BacktestOptions,
    strategy_params: Mapping[str, JsonValue] | None = None,
    strategy_overrides: Mapping[str, JsonValue]
    | None = None,
) -> dict[str, object]

Run PineScript and normalized OHLCV in pineforge-release.

DockerPrerequisiteError

Bases: RuntimeError

Docker or the configured release image is unavailable.

DockerExecutionError

Bases: RuntimeError

The isolated release-container backtest failed.

DEFAULT_RELEASE_IMAGE module-attribute

DEFAULT_RELEASE_IMAGE = "ghcr.io/pineforge-4pass/pineforge-release:0.1.12@sha256:312b9d908390b828484617472c749d5815feb75507da87eae2f6902cfe3d47b1"

ReleaseContractError

Bases: ValueError

A request or release-image response violates the integration contract.

Remote FastAPI client

FastApiBacktestClient dataclass

FastApiBacktestClient(
    base_url: str,
    timeout_seconds: float = 330.0,
    api_key: str | None = None,
    max_response_bytes: int = 128 * 1024 * 1024,
)

Submit normalized bars to a bounded remote PineForge runtime.

BacktestServerError

Bases: RuntimeError

The configured FastAPI server rejected or failed a backtest.