Tracking and reports

Experiment tracking behind one protocol, and the HTML report.

ExperimentTracker

Bases: Protocol

The tracking contract shared by every backend.

run

run(experiment: str, run_name: str) -> ActiveRun

Open a new run under experiment and return a context-manager handle.

list_runs

list_runs(experiment: str) -> list[RunRecord]

Return all runs for experiment, newest first.

get_run

get_run(experiment: str, run_id: str) -> RunRecord | None

Return a single run by id, or None if absent.

ActiveRun

ActiveRun(tracker: _Persistable, record: RunRecord)

A live run handle. Accumulates state and asks the tracker to persist.

Obtained from ExperimentTracker.run and used as a context manager so the run is flushed (with a finished/failed status) on exit even when the body raises.

run_id property

run_id: str

log_params

log_params(params: dict[str, Any]) -> None

log_metrics

log_metrics(metrics: Any) -> None

log_gate

log_gate(gate: Any) -> None

log_reproducibility

log_reproducibility(record: Any) -> None

Store the run's ReproducibilityRecord (or its dict).

It sits next to the params and metrics, so pmlab reproduce <run_id> can re-execute the run from this file alone.

LocalJSONTracker

LocalJSONTracker(root: str | Path)

Zero-dependency tracker: one JSON file per run under <root>/<experiment>/.

root instance-attribute

root = Path(root)

run

run(experiment: str, run_name: str) -> ActiveRun

list_runs

list_runs(experiment: str) -> list[RunRecord]

get_run

get_run(experiment: str, run_id: str) -> RunRecord | None

RunRecord dataclass

RunRecord(
    run_id: str,
    experiment: str,
    run_name: str,
    params: dict[str, Any] = dict(),
    metrics: dict[str, Any] = dict(),
    gate: dict[str, Any] = dict(),
    reproducibility: dict[str, Any] = dict(),
    status: str = "running",
    started_at: str = "",
    ended_at: str | None = None,
    error: str | None = None,
)

An immutable record of one tracked run.

run_id instance-attribute

run_id: str

experiment instance-attribute

experiment: str

run_name instance-attribute

run_name: str

params class-attribute instance-attribute

params: dict[str, Any] = field(default_factory=dict)

metrics class-attribute instance-attribute

metrics: dict[str, Any] = field(default_factory=dict)

gate class-attribute instance-attribute

gate: dict[str, Any] = field(default_factory=dict)

reproducibility class-attribute instance-attribute

reproducibility: dict[str, Any] = field(
    default_factory=dict
)

status class-attribute instance-attribute

status: str = 'running'

started_at class-attribute instance-attribute

started_at: str = ''

ended_at class-attribute instance-attribute

ended_at: str | None = None

error class-attribute instance-attribute

error: str | None = None

to_dict

to_dict() -> dict[str, Any]

from_dict classmethod

from_dict(d: dict[str, Any]) -> RunRecord

generate_report

generate_report(
    trades: list[dict[str, Any]],
    output_path: Path | str = Path("pmlab_report.html"),
    title: str = "pmlab Paper Trading Report",
    brier_score: float | None = None,
) -> Path

Render paper trades as one self-contained HTML report and write it to disk.

Parameters:

Name	Type	Description	Default
trades	list[dict[str, Any]]	Trade records (dicts). A trade with a realized_pnl is settled; one without is open. The summary uses realized_pnl, flat_stake and edge_after_fee.	required
output_path	Path | str	Where to write the file.	Path('pmlab_report.html')
title	str	The report's heading.	'pmlab Paper Trading Report'
brier_score	float | None	A Brier score to show alongside the summary, if you have one.	None

Returns:

Type	Description
Path	The path written.

MLflowTracker

MLflowTracker(tracking_uri: str | None = None)

Experiment tracker backed by MLflow. Conforms to ExperimentTracker.

run

run(experiment: str, run_name: str) -> ActiveRun

list_runs

list_runs(experiment: str) -> list[RunRecord]

get_run

get_run(experiment: str, run_id: str) -> RunRecord | None