Pareto Frontier

ct game-metrics graph pareto computes a (safety, usefulness) scatter from a YAML config and marks the Pareto frontier. Each YAML entry independently picks its own safety + usefulness calculations from registered implementations, so a single Pareto plot can mix and match reference points (e.g. trusted-only, untrusted-only) with sweep curves (e.g. defer-to-trusted across many deferral rates).

Quick Start

uv run ct game-metrics graph pareto --yml-config experiments/my_pareto.yaml \
                              --output-dir results/my_pareto

Outputs land in --output-dir (auto-timestamped under figures/pareto/ if omitted) and contain:

results/my_pareto/
  data.json            # ParetoResult dump (points, frontier, metadata)
  pareto.png           # scatter + frontier polyline (raster)
  pareto.pdf           # same plot, vector
  <yml-config name>    # copy of the input YAML for provenance, kept under its original filename

YAML Schema

title: "My experiment — Pareto frontier"
entries:
  - label: "Trusted Only"
    honest: <run_id_or_path>
    attack: <run_id_or_path>           # ignored by trusted-agent-safety
    safety_calc:
      name: trusted-agent-safety
    usefulness_calc:
      name: main-task-success           # default; can be omitted
    style:
      marker: s
      color: "#87CEEB"

  - label: "Untrusted Only"
    honest: <run_id_or_path>
    attack: <run_id_or_path>
    safety_calc:
      name: tm-safety
      args: { mode: action_only, audit_budget: 0.0 }
    style:
      marker: D
      color: "#1f77b4"

  - label: "DTT defer @ 50% FPR"
    honest: <run_id_or_path>
    attack: <run_id_or_path>
    safety_calc:
      name: defer-to-trusted
      args: { audit_budget: 1.0, defer_fpr: 50.0 }
      bootstrap_ci: { n_bootstrap: 1000, confidence_level: 0.95 }  # optional
    usefulness_calc:
      name: defer-to-trusted
      args: { trusted: <trusted_run_id>, defer_fpr: 50.0 }
    style:
      marker: o
      color: "#1f77b4"

Required fields per entry: label, honest, attack, safety_calc.name. Optional: usefulness_calc (defaults to main-task-success), safety_calc.bootstrap_ci, and style (marker, color, size).

Sources can be run IDs, run URLs, local trajectory directories, or eval log file paths — anything convert_to_trajs accepts.

Calculation Registries

Every entry picks one impl from each of the safety and usefulness registries. Each impl returns a single (value, metadata, optional CI) triple — sweeps come from listing many entries with different parameters, not from sweep functions.

Safety calculations

Usefulness calculations

To enumerate registered impls + their args from the CLI:

uv run python -c "
from control_tower.metrics.safety_calculations.registry import safety_calculations
from control_tower.metrics.usefulness_calculations.registry import usefulness_calculations
print('safety:', sorted(safety_calculations))
print('usefulness:', sorted(usefulness_calculations))
"

tm-safety modes

tm-safety consolidates the previously separate optimized- and action-only audit-rule impls under a single, configurable entry point.

In all budget-driven modes (optimized, 50_50, stepwise_percentile, action_only, trajectory_only), audit_budget=0 short-circuits to a never-firing rule on both legs — the canonical "no audit budget = baseline safety" Pareto reference point. The same short-circuit is shared with the metrics CLI's per-budget fitter (fit_rule_for_target_fpr) so the two commands stay in lockstep.

Bootstrap CIs are opt-in at the selection layer via safety_calc.bootstrap_ci: { n_bootstrap: 1000, confidence_level: 0.95 }. Pareto computes the safety point once, then re-runs the selected safety calculation across bootstrap resamples of the attack trajectories.

Usefulness error bars come for free: the default main-task-success usefulness calc attaches a Jeffreys 95% binomial CI (metrics/confidence_intervals.py) — usefulness is a genuine binomial proportion, so no resampling is needed. Safety stays on bootstrap: it is not a binomial proportion of n_attack (fractional catches, mixed denominator), so binomial intervals do not apply.

Pareto Frontier Marking

Every point is non-dominated by default. After all entries run, each point's on_frontier flag is set: a point (s, u) is dominated iff some other point has s' >= s and u' >= u with at least one strict inequality. Frontier points are connected with a dashed polyline in pareto.png; off-frontier points are rendered translucent.

Programmatic API

The CLI is a thin wrapper around the standalone library function — call it directly from notebooks or downstream scripts:

import yaml
from control_tower.metrics.pareto import (
    ParetoConfig, compute_pareto,
)

with open("experiments/my_pareto.yaml") as f:
    config = ParetoConfig.model_validate(yaml.safe_load(f))

result = compute_pareto(config)
for p in result.points:
    print(p.label, p.safety, p.usefulness, "★" if p.on_frontier else "")
print("frontier (sorted by safety):", [p.label for p in result.frontier])

ParetoResult has a points: list[ParetoPoint] plus a frontier property that returns just the on-frontier points sorted by safety.

To render or persist without going through the CLI:

from pathlib import Path
from control_tower.metrics.printing.pareto import (
    handle_pareto,
)

handle_pareto(result, output_dir=Path("results/my_pareto"))

Adding a New Safety or Usefulness Calculation

Both registries follow the standard Args | None decorator pattern (see Function Registry). Drop a new module in src/control_tower/metrics/safety_calculations/impls/ or .../usefulness_calculations/impls/, decorate with the appropriate registry, and the discovery loader will pick it up at first lookup:

from control_tower.utils.function_registry.base_model import BaseModelPython
from control_tower.metrics.safety_calculations.registry import (
    safety_calculations,
)
from control_tower.metrics.safety_calculations.types import (
    SafetyResult,
)
from control_tower.trajectories.trajectory import Trajectory


class MyCalcArgs(BaseModelPython):
    threshold: float = 5.0


@safety_calculations.register()
def my_calc(
    honest: "list[Trajectory]",
    attack: "list[Trajectory]",
    args: MyCalcArgs | None = None,
) -> "SafetyResult":
    if args is None:
        args = MyCalcArgs()
    safety = _compute_safety(honest, attack, args.threshold)
    return SafetyResult(safety=safety, metadata={"threshold": args.threshold})

The registry name is derived from the function name (my_calc → my-calc). Reference it by that string in YAML's safety_calc.name.

Options Reference