Pareto Frontier

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

Quick Start

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

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), bootstrap_ci, and style (marker, color, size).

Sources can be run IDs, run URLs, or eval log file paths: anything run_like_to_samples accepts.

Calculation Registries

Every entry picks one impl from each registry. Each impl returns a single (value, metadata, optional CI) triple, so a sweep is a list of entries with different parameters.

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

In every mode except manual, audit_budget=0 yields a rule that never fires on either leg, giving the no-audit baseline point. The metrics CLI's per-budget fitter (fit_rule_for_target_fpr) behaves the same way.

Bootstrap CIs are opt-in per entry via 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 both honest and attack trajectories, refitting thresholds inside each draw. Safety needs the bootstrap because it is not a binomial proportion of n_attack (catches can be fractional and the denominator is mixed).

The default main-task-success usefulness calc attaches a Jeffreys 95% binomial CI (metrics/confidence_intervals.py), since usefulness is a binomial proportion.

Pareto Frontier Marking

After all entries run, each point's on_frontier flag records whether it is non-dominated. 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 wraps a library function you can call directly from notebooks or 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). Add a module under src/control_tower/metrics/safety_calculations/impls/ or .../usefulness_calculations/impls/ and decorate the function with the matching registry; the discovery loader picks 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 inspect_ai.log import EvalSample


class MyCalcArgs(BaseModelPython):
    threshold: float = 5.0


@safety_calculations.register()
def my_calc(
    honest: "list[EvalSample]",
    attack: "list[EvalSample]",
    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.

Run ct game-metrics graph pareto --help for every option.