SPDX-License-Identifier: AGPL-3.0-or-later

Commercial license available

© Concepts 1996–2026 Miroslav Šotek. All rights reserved.

© Code 2020–2026 Miroslav Šotek. All rights reserved.

ORCID: 0009-0009-3560-0851

Contact: www.anulum.li | protoscience@anulum.li

SCPN Phase Orchestrator — Autotune supervisor-candidate bundle API reference

Autotune Supervisor-Candidate Bundle

A reviewer asked to trust a supervisor policy candidate has three questions, and the autotune track answers each on its own: is it better (the reward report and a comparison against the incumbent), why these knobs (per-knob attribution), and is it safe (the safety certificate). build_supervisor_candidate_bundle glues those answers into one sealed, review-only artefact so a candidate carries its whole case in a single record.

The bundle scores the candidate, attributes it against a baseline, certifies its safety, compares it against the incumbent it would replace, and stamps the result with its numeric provenance — which compute backend produced the numbers and the parity tolerance they were checked to — and its safety tier. The record is the studio.supervisor_candidate.v1 shape, content-addressed by a canonical-JSON SHA-256 seal, and carries the safety certificate's evidence modality. It proposes nothing and actuates nothing.

from scpn_phase_orchestrator.autotune import (
    KnobPolicyCandidate,
    NumericProvenance,
    RewardObservation,
    SafetyConstraintConfig,
    build_supervisor_candidate_bundle,
    evaluate_knob_policy,
)

def evaluate(policy: KnobPolicyCandidate):
    return evaluate_knob_policy(policy, RewardObservation(coherence=0.82))

bundle = build_supervisor_candidate_bundle(
    KnobPolicyCandidate(alpha=0.2, zeta=0.05),       # candidate
    KnobPolicyCandidate(alpha=0.0, zeta=0.0),        # baseline for attribution
    KnobPolicyCandidate(alpha=0.1, zeta=0.02),       # incumbent to compare against
    evaluate,
    observations=[RewardObservation(coherence=0.82, lyapunov_exponent=-0.02)],
    constraints=SafetyConstraintConfig(max_lyapunov_exponent=0.0),
    safety_tier="research",
    numeric_provenance=NumericProvenance("python", 1e-9),
)

record = bundle.to_audit_record()
assert record["schema"] == "studio.supervisor_candidate.v1"
assert record["digest"] == bundle.digest
# One flag a reviewer can gate on: is it safe AND an improvement?
print(bundle.safe_and_improved)

What the bundle is, and is not

The bundle is evidence, not an action. It does not promote a candidate, drive a supervisor, or touch hardware; it is the record a separate, human review consumes before a candidate is promoted. Keeping the assembly side-effect free is what lets the same bundle be produced in replay, in a notebook, or in CI without any of them implying a control decision.

The comparison against the incumbent is deliberately lightweight — a difference of two reward reports under the same evaluator — rather than a learned-policy comparison, so the bundle stays free of the optional differentiable-learning dependencies and reduces to plain arithmetic a reviewer can re-check by hand.

Numeric provenance and the studio contract

numeric_provenance and safety_tier are first-class fields, not afterthoughts: the same numbers can come from any of the polyglot compute backends, so the bundle records which backend produced them and the parity tolerance they were held to, and it carries the deployment safety tier the candidate targets. Together with the evidence modality from the safety certificate, these are the fields the cross-studio studio.*.v1 evidence contract depends on.

supervisor_candidate

Assemble the auditable supervisor-candidate evidence bundle.

A reviewer asked to trust a supervisor policy candidate has three questions, and the autotune track answers each separately: is it better (the reward report and a comparison against the incumbent), why these knobs (the per-knob attribution), and is it safe (the candidate safety certificate). This module glues those answers into one sealed, review-only artefact so the candidate carries its whole case in a single record.

:func:build_supervisor_candidate_bundle scores the candidate, attributes it against a baseline, certifies its safety, compares it against the incumbent it would replace, and stamps the result with its numeric provenance (which compute backend produced the numbers, and the parity tolerance they were checked to) and its safety tier. The bundle is content-addressed by a canonical-JSON SHA-256 seal and carries the safety certificate's evidence modality. It proposes nothing and actuates nothing — it is the evidence a separate, human review consumes before a candidate is promoted.

Classes

NumericProvenance dataclass

NumericProvenance(
    active_backend: str, parity_tolerance: float
)

Which compute backend produced a bundle's numbers, and to what tolerance.

Parameters

active_backend : str The name of the compute backend that produced the numbers, e.g. "python" or "rust". parity_tolerance : float The non-negative absolute tolerance the backend was parity-checked to against the Python reference.

Methods:

__post_init__

__post_init__() -> None

Validate the provenance fields.

Raises

ValueError If active_backend is empty or parity_tolerance is negative.

Source code in src/scpn_phase_orchestrator/autotune/supervisor_candidate.py

def __post_init__(self) -> None:
    """Validate the provenance fields.

    Raises
    ------
    ValueError
        If ``active_backend`` is empty or ``parity_tolerance`` is negative.
    """
    if not self.active_backend:
        raise ValueError("active_backend must be a non-empty name")
    if self.parity_tolerance < 0.0:
        raise ValueError("parity_tolerance must be non-negative")

to_audit_record

to_audit_record() -> dict[str, object]

Return a JSON-ready record of the provenance.

Returns

dict[str, object] A mapping with the active backend and the parity tolerance.

Source code in src/scpn_phase_orchestrator/autotune/supervisor_candidate.py

def to_audit_record(self) -> dict[str, object]:
    """Return a JSON-ready record of the provenance.

    Returns
    -------
    dict[str, object]
        A mapping with the active backend and the parity tolerance.
    """
    return {
        "active_backend": self.active_backend,
        "parity_tolerance": self.parity_tolerance,
    }

SupervisorCandidateComparison dataclass

SupervisorCandidateComparison(
    incumbent_reward: float,
    candidate_reward: float,
    reward_delta: float,
    component_deltas: Mapping[str, float],
    improved: bool,
)

How a candidate's reward compares against the incumbent it would replace.

Parameters

incumbent_reward : float The incumbent policy's total reward under the same evaluator. candidate_reward : float The candidate policy's total reward. reward_delta : float candidate_reward minus incumbent_reward. component_deltas : Mapping[str, float] Per-component reward differences (candidate minus incumbent). improved : bool True when reward_delta is strictly positive.

Methods:

to_audit_record

to_audit_record() -> dict[str, object]

Return a JSON-ready, deterministic record of the comparison.

Returns

dict[str, object] A mapping with the two rewards, the total and per-component deltas (sorted by component name), and the improvement flag.

Source code in src/scpn_phase_orchestrator/autotune/supervisor_candidate.py

def to_audit_record(self) -> dict[str, object]:
    """Return a JSON-ready, deterministic record of the comparison.

    Returns
    -------
    dict[str, object]
        A mapping with the two rewards, the total and per-component deltas
        (sorted by component name), and the improvement flag.
    """
    return {
        "incumbent_reward": self.incumbent_reward,
        "candidate_reward": self.candidate_reward,
        "reward_delta": self.reward_delta,
        "component_deltas": {
            name: self.component_deltas[name]
            for name in sorted(self.component_deltas)
        },
        "improved": self.improved,
    }

SupervisorCandidateBundle dataclass

SupervisorCandidateBundle(
    candidate: KnobPolicyCandidate,
    reward: AutotuneRewardReport,
    attribution: KnobAttributionReport,
    safety: CandidateSafetyCertificate,
    comparison: SupervisorCandidateComparison,
    safety_tier: str,
    numeric_provenance: NumericProvenance,
    evidence_kind: str,
    digest: str,
)

The complete, sealed evidence bundle for one supervisor candidate.

Parameters

candidate : KnobPolicyCandidate The candidate the bundle describes. reward : AutotuneRewardReport The candidate's reward report. attribution : KnobAttributionReport The per-knob attribution against the baseline. safety : CandidateSafetyCertificate The candidate's safety certificate. comparison : SupervisorCandidateComparison The comparison against the incumbent. safety_tier : str The declared safety tier of the deployment the candidate targets. numeric_provenance : NumericProvenance The compute provenance of the numbers in the bundle. evidence_kind : str The safety certificate's evidence modality, carried to the bundle level. digest : str Canonical-JSON SHA-256 content address of the bundle body.

Attributes

safe_and_improved property

safe_and_improved: bool

Return whether the candidate is both safe and an improvement.

Returns

bool True when the safety certificate is safe and the comparison shows an improvement over the incumbent.

Methods:

to_audit_record

to_audit_record() -> dict[str, object]

Return the JSON-ready studio.supervisor_candidate.v1 record.

Returns

dict[str, object] The schema-tagged bundle with the candidate, reward, attribution, safety, and comparison sub-records, the safety tier, the numeric provenance, the evidence kind, and the content-address digest.

Source code in src/scpn_phase_orchestrator/autotune/supervisor_candidate.py

def to_audit_record(self) -> dict[str, object]:
    """Return the JSON-ready ``studio.supervisor_candidate.v1`` record.

    Returns
    -------
    dict[str, object]
        The schema-tagged bundle with the candidate, reward, attribution,
        safety, and comparison sub-records, the safety tier, the numeric
        provenance, the evidence kind, and the content-address digest.
    """
    body = _bundle_body(
        candidate=self.candidate,
        reward=self.reward,
        attribution=self.attribution,
        safety=self.safety,
        comparison=self.comparison,
        safety_tier=self.safety_tier,
        numeric_provenance=self.numeric_provenance,
        evidence_kind=self.evidence_kind,
    )
    return {**body, "digest": self.digest}

Functions:

build_supervisor_candidate_bundle

build_supervisor_candidate_bundle(
    candidate: KnobPolicyCandidate,
    baseline: KnobPolicyCandidate,
    incumbent: KnobPolicyCandidate,
    evaluate: CandidateEvaluator,
    *,
    observations: Sequence[RewardObservation],
    constraints: SafetyConstraintConfig,
    safety_tier: str,
    numeric_provenance: NumericProvenance,
    barrier: NeuralBarrier | None = None,
    replay_states: Sequence[FloatArray]
    | FloatArray
    | None = None,
    forward_invariance: BarrierCertificate | None = None,
    attribution_config: KnobAttributionConfig | None = None,
) -> SupervisorCandidateBundle

Assemble the sealed, review-only supervisor-candidate evidence bundle.

The candidate is scored, attributed against baseline, certified for safety, and compared against incumbent under the same evaluator. The pieces are stamped with the numeric provenance and safety tier and sealed. The function proposes and actuates nothing.

Parameters

candidate : KnobPolicyCandidate The candidate being bundled. baseline : KnobPolicyCandidate The reference the attribution credits knobs against. incumbent : KnobPolicyCandidate The policy the candidate would replace, scored for the comparison. evaluate : CandidateEvaluator A side-effect-free scorer returning a reward report for any candidate. observations : Sequence[RewardObservation] The replay observations driving the safety certificate. constraints : SafetyConstraintConfig The Lyapunov/STL/safety-cost bounds for the safety certificate. safety_tier : str The declared safety tier of the target deployment. numeric_provenance : NumericProvenance The compute provenance of the bundle's numbers. barrier : NeuralBarrier | None An optional control-barrier function for the safety certificate. replay_states : object The states the candidate visited, required when barrier is supplied. forward_invariance : BarrierCertificate | None An optional forward-invariance certificate for the barrier. attribution_config : KnobAttributionConfig | None Optional exact-versus-sampled settings for the attribution.

Returns

SupervisorCandidateBundle The sealed evidence bundle.

Source code in src/scpn_phase_orchestrator/autotune/supervisor_candidate.py

def build_supervisor_candidate_bundle(
    candidate: KnobPolicyCandidate,
    baseline: KnobPolicyCandidate,
    incumbent: KnobPolicyCandidate,
    evaluate: CandidateEvaluator,
    *,
    observations: Sequence[RewardObservation],
    constraints: SafetyConstraintConfig,
    safety_tier: str,
    numeric_provenance: NumericProvenance,
    barrier: NeuralBarrier | None = None,
    replay_states: Sequence[FloatArray] | FloatArray | None = None,
    forward_invariance: BarrierCertificate | None = None,
    attribution_config: KnobAttributionConfig | None = None,
) -> SupervisorCandidateBundle:
    """Assemble the sealed, review-only supervisor-candidate evidence bundle.

    The candidate is scored, attributed against ``baseline``, certified for
    safety, and compared against ``incumbent`` under the same evaluator. The
    pieces are stamped with the numeric provenance and safety tier and sealed.
    The function proposes and actuates nothing.

    Parameters
    ----------
    candidate : KnobPolicyCandidate
        The candidate being bundled.
    baseline : KnobPolicyCandidate
        The reference the attribution credits knobs against.
    incumbent : KnobPolicyCandidate
        The policy the candidate would replace, scored for the comparison.
    evaluate : CandidateEvaluator
        A side-effect-free scorer returning a reward report for any candidate.
    observations : Sequence[RewardObservation]
        The replay observations driving the safety certificate.
    constraints : SafetyConstraintConfig
        The Lyapunov/STL/safety-cost bounds for the safety certificate.
    safety_tier : str
        The declared safety tier of the target deployment.
    numeric_provenance : NumericProvenance
        The compute provenance of the bundle's numbers.
    barrier : NeuralBarrier | None
        An optional control-barrier function for the safety certificate.
    replay_states : object
        The states the candidate visited, required when ``barrier`` is supplied.
    forward_invariance : BarrierCertificate | None
        An optional forward-invariance certificate for the barrier.
    attribution_config : KnobAttributionConfig | None
        Optional exact-versus-sampled settings for the attribution.

    Returns
    -------
    SupervisorCandidateBundle
        The sealed evidence bundle.
    """
    reward = evaluate(candidate)
    attribution = attribute_knob_policy(
        candidate, baseline, evaluate, config=attribution_config
    )
    safety = certify_candidate_safety(
        candidate,
        observations,
        constraints,
        barrier=barrier,
        replay_states=replay_states,
        forward_invariance=forward_invariance,
    )
    comparison = _compare(evaluate(incumbent), reward)
    body = _bundle_body(
        candidate=candidate,
        reward=reward,
        attribution=attribution,
        safety=safety,
        comparison=comparison,
        safety_tier=safety_tier,
        numeric_provenance=numeric_provenance,
        evidence_kind=safety.evidence_kind,
    )
    return SupervisorCandidateBundle(
        candidate=candidate,
        reward=reward,
        attribution=attribution,
        safety=safety,
        comparison=comparison,
        safety_tier=safety_tier,
        numeric_provenance=numeric_provenance,
        evidence_kind=safety.evidence_kind,
        digest=_seal(body),
    )