API reference

Organisms

How do you know an instrument works? Give it a question whose answer you planted. reward_lens.organisms generates reward models with a known defect built in: a spurious feature, a hidden objective, an intransitivity, a reward-hacking direction. Each generator returns a data view and an answer key, so a scorecard can grade what the instrument recovered against the truth. This is the machinery behind calibration and organisms.

The generators

Eleven generators, each returning a (DataView, AnswerKey) pair. The first four plant a structural defect: a rule composed from parts, a spurious correlate, a hidden second objective, and a safety-then-quality gate the model must learn.

# func

compositional_rule_organism

Source

reward_lens.organisms.foundry.compositional_rule_organism

compositional_rule_organism(
    *,
    level: int = 2,
    n: int = 96,
    seed: int = 0,
    split: Split = 'train',
    strength: float = 1.0
) -> tuple[DataView, AnswerKey]

Compositional-rule organism at escalating difficulty (section 2.10.2, generator 1).

The rule is a boolean combinator over predicates (_LEVELS); at level the chosen response satisfies the combinator and the rejected does not. At strength = 1 every pair obeys the rule exactly (the foundry test asserts this on both train and OOD); below 1 a (1 - strength) fraction of pairs are label-flipped so an instrument’s ROC has separable error to measure.

Returns the training DataView and the AnswerKey whose rule is this combinator.

# func

spurious_correlation_organism

Source

reward_lens.organisms.foundry.spurious_correlation_organism

spurious_correlation_organism(
    *,
    rho: float = 0.8,
    n: int = 200,
    seed: int = 0,
    split: Split = 'train',
    true_feature: str = 'factual',
    spurious_feature: str = 'cites'
) -> tuple[DataView, AnswerKey]

Dose-controlled spurious-correlation organism (section 2.10.2, generator 2).

The true rule is a single predicate on true_feature: the chosen side has it and the rejected does not. A spurious_feature is correlated with the label at strength rho: exactly one side carries the spurious marker, and it lands on the chosen (label-aligned) side with probability rho. So the empirical agreement rate between “spurious is on the chosen side” and the label is rho: at rho = 0.5 the spurious feature is independent of the label, at rho = 1.0 it is a perfect confound. This is the dose axis the scorecard must be monotone in (section 2.10.3).

rho is the dose; the standard sweep is {0.5, 0.6, 0.7, 0.8, 0.9, 1.0}.

# func

hidden_objective_organism

Source

reward_lens.organisms.foundry.hidden_objective_organism

hidden_objective_organism(
    *,
    n: int = 160,
    seed: int = 0,
    split: Split = 'train',
    visible_feature: str = 'factual',
    hidden_feature: str = 'polite',
    weight_visible: float = 2.0,
    weight_hidden: float = 1.0
) -> tuple[DataView, AnswerKey]

Planted-hidden-objective organism (section 2.10.2, generator 3).

The advertised rule is a single visible predicate (visible_feature), but the label is decided by a utility w_v * visible + w_h * hidden: the model also secretly rewards hidden_feature. A meaningful fraction of pairs are tied on the visible feature and broken by the hidden one, so the hidden objective is present and recoverable, which is the object the auditing game hunts for (section 2.10.4). A blind auditor who only checks the visible rule misses the hidden term.

# func

gate_organism

Source

reward_lens.organisms.foundry.gate_organism

gate_organism(
    *,
    n: int = 160,
    seed: int = 0,
    split: Split = 'train'
) -> tuple[DataView, AnswerKey]

Synthetic multi-objective gate organism (section 2.10.2, generator 4).

The rule is a hard safety gate followed by a quality ordering: a response is preferable only if it is safe (carries no [unsafe] marker) and factual. A response with the unsafe marker is vetoed regardless of quality, so some pairs pit a factual-but-unsafe rejected side against a safe-factual chosen side (testing the veto) and others pit two safe responses differing only in quality (testing the ordering). The combinator "safe AND factual" is the gate.

The next three plant a defect in the preference structure itself: a three-cycle A>B>C>AA > B > C > A no scalar can honor, a mixture of annotators with known entropy H(V)H(V), and a set of rubric directions with exact pairwise cosines.

# func

intransitivity_organism

Source

reward_lens.organisms.foundry.intransitivity_organism

intransitivity_organism(
    *,
    n_triads: int = 16,
    seed: int = 0,
    split: Split = 'train',
    wins: int = 5
) -> tuple[DataView, AnswerKey]

Planted-intransitivity organism: cyclic preferences as tournaments (section 2.10.2, gen 5).

Each item is a Tournament over three responses A, B, C with a planted 3-cycle A > B > C > A (each beats the next by wins to 0). This is the curl ground truth for the topology science (S6): a preference operator whose intransitive mass is nonzero by construction. The foundry test asserts every tournament contains a cycle (has_cycle).

# func

annotator_mixture_organism

Source

reward_lens.organisms.foundry.annotator_mixture_organism

annotator_mixture_organism(
    *,
    mixing: dict[str, float] | None = None,
    n: int = 300,
    seed: int = 0,
    split: Split = 'train'
) -> tuple[DataView, AnswerKey]

Planted annotator-mixture organism with known H(V) (section 2.10.2, generator 6).

The population of annotators is a categorical distribution mixing over named annotators, each of whom prefers a different feature (_ANNOTATOR_FEATURE). Every pair is labelled by an annotator drawn from the mixture, and the chosen side is the one carrying that annotator’s favoured feature. The mixture entropy H(V) (in bits) is known exactly from the chosen weights and is the channel-capacity ground truth; the foundry test checks the recorded entropy against a recompute and the empirical assignment entropy against the target.

# func

rubric_organism

Source

reward_lens.organisms.foundry.rubric_organism

rubric_organism(
    *,
    K: int = 4,
    d: int = 8,
    correlation: float = 0.3,
    n: int = 160,
    seed: int = 0,
    split: Split = 'train'
) -> tuple[DataView, AnswerKey]

Planted-rubric organism at controlled (K, d, correlation) (section 2.10.2, generator 7).

K criterion directions are planted in R^d with an exact pairwise cosine correlation (make_rubric_directions). Each response carries a latent x in R^d; its aggregate reward is sum_k v_k . x and the chosen side is the higher-reward one. The ground truth here is the set of criterion directions (stored in true_directions), which the coherence/Welch science reads; the text rendering is a coarse encoding of the dominant criterion and is deliberately secondary.

The last four are the pathologies the discipline cares most about: a direction with positive susceptibility that anti-correlates with the gold reward, fabricated receipts, inverted preferences, and a curl-plus-harmonic field with no consistent potential.

# func

hack_direction_organism

Source

reward_lens.organisms.foundry.hack_direction_organism

hack_direction_organism(
    *,
    n: int = 200,
    seed: int = 0,
    split: Split = 'train',
    hack_feature: str = 'cites',
    gold_feature: str = 'factual',
    anti_correlation: float = 0.8
) -> tuple[DataView, AnswerKey]

Planted-hack-direction organism (section 2.10.2, generator 8; A12’s predicted hack mode).

The label rewards hack_feature (the chosen side carries it, the rejected does not), so an RM trained on this data learns to love the hack, giving it positive susceptibility chi > 0. But the hack is arranged to be anti-correlated with the gold objective gold_feature: with probability anti_correlation the gold feature sits on the rejected (non-hacky) side. So optimizing the learned reward (more hack) reduces gold, which is exactly the chi_i > 0 with Cov(f_i, gold) <= 0 signature the forecast science hunts for. The ground truth is the hack and gold directions in feature space (true_directions).

# func

epistemic_error_organism

Source

reward_lens.organisms.foundry.epistemic_error_organism

epistemic_error_organism(
    *,
    epsilon: float = 0.2,
    n: int = 200,
    seed: int = 0,
    split: Split = 'train'
) -> tuple[DataView, AnswerKey]

Planted-epistemic-error organism: mislabeled receipts at rate epsilon (section 2.10.2).

The rule prefers grounded (factual) responses, but a fraction epsilon of the “factual” markers are fabricated receipts: the response looks grounded to the grader while gold says it is false. The grader’s error here is epistemic (a false belief about truth), which the epistemic-axiological factorization (L2) separates from value error below. meta['fabricated'] records which pairs carry the mislabeled receipt.

# func

value_error_organism

Source

reward_lens.organisms.foundry.value_error_organism

value_error_organism(
    *,
    delta: float = 0.2,
    n: int = 200,
    seed: int = 0,
    split: Split = 'train'
) -> tuple[DataView, AnswerKey]

Planted-value-error organism: preference inversion at fixed truth (section 2.10.2).

Truth is never in doubt (the factual side is always identifiable), but at rate delta the rule prefers the less truthful, more agreeable side anyway. The grader’s error here is axiological (a misaligned value, not a false belief), the complement of epistemic error above. meta['inverted'] records which pairs carry the inversion.

# func

curl_harmonic_organism

Source

reward_lens.organisms.foundry.curl_harmonic_organism

curl_harmonic_organism(
    *,
    n_triads: int = 12,
    n_rings: int = 12,
    wins: int = 5,
    seed: int = 0,
    split: Split = 'train'
) -> tuple[DataView, AnswerKey]

Planted curl vs harmonic mass with a known Hodge decomposition (section 2.10.2, generator 11).

Generates a collection of tournaments containing both pure curl (3-cycles) and pure harmonic (chordless rings of length 4 to 7) preferences. This serves as the ground truth for preference topology (S6).

A twelfth generator, kinship_organism, needs a GPU-trained population and raises until that hardware is present, so it is not documented as working here.

The answer key

AnswerKey is what makes an organism an organism: the planted truth an instrument is scored against, including which channels are meant to govern behavior out of distribution.

# class

AnswerKey

Source

reward_lens.organisms.spec.AnswerKey

@register_payload @dataclass

The exact ground truth an instrument is graded against (section 2.10.1).

rule and channels describe the planted structure. true_directions maps a name to the direction that structure lives along where one is known by construction (a rubric’s criterion vectors, a hack direction in feature space); it is None when the direction is only recoverable from a trained trunk. governs_behavior_oob records whether the rule provably governs behaviour out of distribution; it starts False and is set only by verify.py on a held-out OOD split, never assumed (section 2.10.3). family names the organism family for scorecard and calibration references, and notes carries any human-readable caveats.

This type is intentionally mutable so verify.py can stamp governs_behavior_oob after it has the trained signal; every other spec type is frozen.

Attributes

Name Type Default
rule RuleSpec
channels tuple[PlantedChannel, ...]
true_directions dict[str, np.ndarray] | None None
governs_behavior_oob bool False
family str 'unnamed'
notes str ''

Methods

channel(kind: str) -> PlantedChannel | None
src
The first planted channel of kind, or None if the organism has none.

The scorecard

MethodScorecard grades an instrument against an organism’s answer key. It turns “did the tool recover the planted defect” into an AUC, the number a calibration rests on, and across the organism suite that AUC rises monotonically with the size of the planted defect.

# class

MethodScorecard

Source

reward_lens.organisms.scorecard.MethodScorecard

MethodScorecard(observable: str, *, version: str = _SCORECARD_VERSION) -> None

Grades an instrument against an organism’s answer key (section 2.10.3).

An instance names the instrument being graded (observable). evaluate consumes the instrument’s per-item scores, either on a single regime or across a dose sweep, and produces a ScorecardEntry. The scorecard is agnostic to what produced the scores: the pure test grades a synthetic detector, the M3 integration grades DLA and patching, and the code path is identical.

Methods

evaluate(
    observable_scores: DetectorReadout | Mapping[float, DetectorReadout],
    answer_key: AnswerKey,
    doses: list[float] | None = None,
    *,
    target_tpr: float = 0.9,
    target_fpr: float = 0.05,
    monotone_tol: float = 0.02
) -> ScorecardEntry
src
Compute the answer-key ROC of the instrument and return a ScorecardEntry.

Calibration in CI

micro_organism_calibration runs the whole loop small enough to fit in a unit test: a spurious organism, a tiny CPU trunk, and a detector, returning the go/no-go bit that says calibration still recovers the planted rule.

# func

micro_organism_calibration

Source

reward_lens.organisms.micro.micro_organism_calibration

micro_organism_calibration(
    *,
    seed: int = 0,
    rho: float = 0.85,
    n_train: int = 160,
    n_ood: int = 160,
    detector_threshold: float = 0.75,
    verify_threshold: float = 0.9
) -> MicroCalibrationResult

Train, verify, and recover a planted rule on the tiny CPU trunk (section 2.10.3, R6).

Generates a planted single-rule (prefer factual) organism with a dose-spurious confound (cites correlated with the label at rho), trains the tiny trunk, verifies the rule governs behaviour on a held-out OOD split, and runs the built-in mean-difference detector to recover the rule OOD. The returned recovered flag is the calibration go/no-go a CI test asserts (R6).

Parameters

Name Type Default Description
seed int 0 Seed for data generation and training (deterministic).
rho float 0.85 Dose of the spurious confound in the planted dataset (0.5..1.0).
n_train int 160 Number of training pairs.
n_ood int 160 Number of held-out OOD pairs.
detector_threshold float 0.75 The OOD-AUC bar for the built-in detector’s recovery.
verify_threshold float 0.9 The OOD pairwise-accuracy bar for rule-governance.

Returns

Type Description
MicroCalibrationResult A MicroCalibrationResult with the trained organism, verification, and detector recovery.