API reference

Artifacts and operate

Can a report say more than the evidence store can back? No, and that is the whole point of reward_lens.artifacts: cards, atlases, and safety cases are views over the store, not fresh computations, so a claim on a card exists only if a piece of evidence in the store supports it. reward_lens.operate is the command-line and MCP surface that drives all of it.

Cards and the atlas

build_card assembles a single model’s card by reading the store, never by recomputing a number. Atlas is the population-scale view: a standard summary, a leaderboard, and a sweep that plans on CPU and gates its own execution behind hardware.

# func

build_card

Source

reward_lens.artifacts.card.build_card

build_card(signal_fp: str, store: EvidenceStore | None = None) -> Card

Assemble a Card from every latest Evidence about a signal (section 2.15).

Queries the store for the most recent Evidence per observable about this signal fingerprint, reads each one’s value, uncertainty, trust, gauge, and calibration status, and returns a Card. Uncalibrated entries are not filtered out; they are carried and flagged, because a card that hid its gaps would be a marketing document.

# class

Atlas

Source

reward_lens.artifacts.atlas.Atlas

Atlas(entries: Iterable[AtlasEntry] = ()) -> None

The population registry and its leaderboard view (section 2.15, Atlas-v0).

Construct with Atlas.standard() for the ten-model population, or empty and register entries. The registry is keyed by fingerprint; a second registration of the same fingerprint replaces the entry (the sweep uses this to upgrade a card-claimed entry to a weights-verified one).

Properties

entries : list[AtlasEntry]

Methods

standard() -> Atlas

src

The standard ten-model population with declared, card-claimed lineage (section 2.15).

register(entry: AtlasEntry) -> None

src

by_fingerprint(fingerprint: str) -> AtlasEntry | None

src

by_name(name: str) -> AtlasEntry | None

src

leaderboard(
    store: EvidenceStore | None = None,
    observables: Iterable[str] | None = None
) -> Leaderboard

src

Assemble the population leaderboard as a view over the store (section 2.15).

For every registered model and every requested observable, query the store for the most recent Evidence about that (observable, model) pair and record its value, trust, calibration, and metered cost. If observables is not given, the columns are the distinct observable names the store holds for this population, so a bare call tabulates whatever has been measured. Nothing is computed: an absent pair is an absent cell, and an uncalibrated cell is flagged.

export_leaderboard(
    store: EvidenceStore | None = None,
    observables: Iterable[str] | None = None,
    out_dir: str | Path | None = None
) -> dict[str, Any]

src

Export the leaderboard to JSON and HTML (section 2.15).

Returns a dict with the rendered json and html strings and the Leaderboard itself. When out_dir is given, writes leaderboard.json and leaderboard.html under it and adds their paths to the returned dict. The strings are the single source; the files are a convenience for the site export, which is the intended publishing vehicle.

sweep(
    signals: Iterable[str],
    battery: Iterable[str],
    budget: Cost,
    store: EvidenceStore | None = None,
    execute: bool = False
) -> SweepPlan

src

Plan and price the population sweep; do not run it (R13, GPU-gated).

Builds the cartesian product of signals (model fingerprints) and battery (observable names) into a SweepPlan. Each cell’s estimated cost is read from the store when a prior Evidence for that pair carries metered GPU-seconds, so the estimate is itself a view over recorded cost rather than a guess. execute=True raises SweepGatedError: loading and scoring the real population is GPU work this layer refuses to fake. The returned plan reports whether it fits the budget so an operator can size the run before dispatching it on hardware.

The claims checker

check_text and check_files scan a manuscript for claim tags of the form [[claim value=… ev=… field=… tol=…]] and verify each one against the store, failing when the evidence is absent, the field is missing, or the stored value is further from the claimed one than the tolerance allows. On the command line this is what makes reward-lens claims exit non-zero on an unbacked number. See cards and claims.

# func

check_text

Source

reward_lens.artifacts.claims.check_text

check_text(
    text: str,
    store: EvidenceStore | None = None,
    default_tol: float = 1e-06
) -> ClaimReport

Check every tagged claim in text against the store, returning a ClaimReport.

A claim fails if its Evidence id is not in the store, if the named field cannot be extracted, or if the claimed value differs from the stored value by more than the tolerance. Bare ev:... references that do not resolve are collected separately so a dangling citation is also caught.

# func

check_files

Source

reward_lens.artifacts.claims.check_files

check_files(paths: list[str | Path], store: EvidenceStore | None = None) -> ClaimReport

Check a set of documents, aggregating into one report (the CI entry point).

The safety case

assemble_safety_case is the strictest artifact: it refuses to assemble unless every component it rests on is both calibrated and registered, raising SafetyCaseRefusal rather than producing a case the trust ladder cannot support.

# func

assemble_safety_case

Source

reward_lens.artifacts.safety_case.assemble_safety_case

assemble_safety_case(
    signal: str,
    *,
    k_nats_evidence: str,
    monitor_evidence: str,
    erasure_evidence: str,
    honesty_evidence: str,
    store: EvidenceStore | None = None,
    bias_set: list[str] | None = None
) -> SafetyCase

Assemble a safety case from four component Evidence ids, refusing unless all are ADJUDICATED.

Loads the K-nats budget (S3), the monitor (S13/S14), the erasure certificate (S6/S12), and the honesty certificate (S16) by id, requires each to carry calibration (gate 1) and registration (gate 3), and extracts the claim parameters from the Evidence values. bias_set names the set B the case claims erased; if omitted, it is read from the erasure Evidence’s bias_set field. Any missing id raises KeyError from the store; any un-calibrated or un-registered component raises SafetyCaseRefusal. Nothing is recomputed: K, the monitor grade, and the certificate are read straight from their Evidence.

The command line and MCP

reward_lens.operate exposes the reward-lens command. The CPU-pure verbs read and check the store: card, scoreboard, claims, atlas export, and study freeze. The verbs that need a model are gated: score, serve, audit, study run, and organism train print the exact dispatch they would make and exit with code 3 rather than fabricate a result. The same module carries a minimal, in-process MCP server, honest in its own docstring about being transport-less. The full walkthrough is on the command line.