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 replay policy search API reference

Autotune Replay Policy Search

The replay policy-search API is the non-actuating bridge between deterministic candidate generation and future learner-backed autotune loops. It generates bounded candidates around a seed policy, delegates each candidate to a replay or simulation evaluator, and returns a reviewable proposal record.

The evaluator is deliberately supplied by the caller. Production integrations should connect it to replay buffers, dry-run simulation, or hardware-in-the-loop shadow evaluation before a proposal is considered for deployment.

from scpn_phase_orchestrator.autotune import (
    AdaptiveReplayPolicySearchConfig,
    KnobPolicyCandidate,
    OfflinePolicySearchConfig,
    PolicyProposalConfig,
    RewardObservation,
    SafetyConstraintConfig,
    search_replay_policy,
)

seed = KnobPolicyCandidate(
    K=0.2,
    alpha=0.0,
    zeta=0.05,
    Psi=0.1,
    channel_weights=(1.0, 0.8),
    cross_channel_gains=(0.3, 0.5),
)


def replay(candidate: KnobPolicyCandidate) -> RewardObservation:
    return RewardObservation(
        coherence=0.82,
        previous_coherence=0.74,
        lyapunov_exponent=-0.015,
        stl_robustness=0.08,
        safety_cost=0.01,
    )


result = search_replay_policy(
    seed,
    replay,
    search_config=OfflinePolicySearchConfig(
        K_step=0.05,
        channel_weight_step=0.1,
        cross_channel_gain_step=0.1,
        max_abs_knob=1.0,
    ),
    proposal_config=PolicyProposalConfig(
        min_coherence=0.75,
        safety_constraints=SafetyConstraintConfig(
            max_lyapunov_exponent=0.0,
            min_stl_robustness=0.0,
            max_safety_cost=0.05,
            require_lyapunov=True,
            require_stl=True,
            require_safety_cost=True,
        ),
    ),
)

audit_record = result.to_audit_record()

For bounded learner-style refinement without enabling live actuation, use the adaptive search wrapper. It repeatedly evaluates replay candidates around the best replay-scored candidate, decays the coordinate step sizes, and then applies the same final proposal gates across all replay observations:

from scpn_phase_orchestrator.autotune import search_adaptive_replay_policy

adaptive_result = search_adaptive_replay_policy(
    seed,
    replay,
    adaptive_config=AdaptiveReplayPolicySearchConfig(
        base_search_config=OfflinePolicySearchConfig(
            K_step=0.05,
            zeta_step=0.02,
            max_abs_knob=1.0,
        ),
        iterations=3,
        step_decay=0.5,
    ),
    proposal_config=PolicyProposalConfig(min_coherence=0.75),
)

adaptive_audit_record = adaptive_result.to_audit_record()

The result keeps the seed, generated candidates, and proposal together so audit logs can prove which replay-only candidates were evaluated before a policy was accepted or rejected.

When SafetyConstraintConfig is attached to PolicyProposalConfig, the search will reject candidates that lack required Lyapunov or STL evidence, exceed the configured Lyapunov exponent bound, violate the STL robustness floor, or exceed the safety-cost ceiling. These gates run after replay scoring and before a proposal is accepted, so the search cannot promote a high-reward candidate that fails the explicit safety evidence contract.

Practical overview

This page is the control bridge between experimentation and controlled deployment:

• Generate candidates (bounded).
• Score in replay/simulation (comparative).
• Enforce safety gates (governance).
• Emit one auditable proposal record (promotion boundary).

The design is intentionally conservative because it prevents “good-scoring but unsafe” candidates from silently entering a deployment lane. This pattern is the same pattern used across safety-critical control stacks where model uncertainty and environmental shift can produce false positives.

Review and audit interpretation

Replay search is only as useful as its provenance. Keep the evaluator deterministic for a given seed and profile, and record search configurations so repeated runs can compare:

• candidate envelopes,
• proposal thresholds,
• safety boundary settings.

That evidence makes it possible to justify in review why a specific search depth or step size was chosen, and why rejected candidates were blocked.

Why this module exists in the control chain

This module is the non-actuating candidate-evaluation stage for the autotune path. Its output is a proposal record with explicit admission decisions, not a control command.

In practice:

• it produces bounded candidate candidates from a seed profile,
• evaluates those candidates through an external replay/adaptation function,
• enforces safety and stability gates,
• returns a single auditable record for downstream review and promotion.

That structure is the reason this page stays review-first: replay and offline validation complete before any policy path that may write to a physical actuator.

policy_search

Replay-only policy search helpers for autotune candidates.

Classes

AdaptiveReplayPolicySearchConfig dataclass

AdaptiveReplayPolicySearchConfig(
    base_search_config: OfflinePolicySearchConfig = OfflinePolicySearchConfig(),
    iterations: int = 3,
    step_decay: float = 0.5,
    improvement_tolerance: float = 0.0,
    min_step: float = 0.0,
)

Bounded adaptive search settings for replay-only autotune.

Methods:

__post_init__

__post_init__() -> None

Validate adaptive search bounds and canonical integer fields.

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

def __post_init__(self) -> None:
    """Validate adaptive search bounds and canonical integer fields."""
    if not isinstance(self.base_search_config, OfflinePolicySearchConfig):
        raise TypeError("base_search_config must be OfflinePolicySearchConfig")
    object.__setattr__(
        self,
        "iterations",
        _require_positive_integer(self.iterations, "iterations"),
    )
    object.__setattr__(
        self,
        "step_decay",
        _require_bounded_real(
            self.step_decay,
            "step_decay",
            lower=0.0,
            upper=1.0,
            lower_inclusive=False,
        ),
    )
    object.__setattr__(
        self,
        "improvement_tolerance",
        _require_non_negative_real(
            self.improvement_tolerance,
            "improvement_tolerance",
        ),
    )
    object.__setattr__(
        self,
        "min_step",
        _require_non_negative_real(self.min_step, "min_step"),
    )

ReplayPolicySearchResult dataclass

ReplayPolicySearchResult(
    seed: KnobPolicyCandidate,
    candidates: tuple[KnobPolicyCandidate, ...],
    proposal: AutotunePolicyProposal,
)

Replay-only policy-search result suitable for audit review.

Methods:

__post_init__

__post_init__() -> None

Validate the seed, generated candidates, and review proposal.

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

def __post_init__(self) -> None:
    """Validate the seed, generated candidates, and review proposal."""
    _validate_candidate(self.seed, "seed")
    if not isinstance(self.candidates, tuple):
        raise TypeError("candidates must be a tuple of KnobPolicyCandidate")
    if not self.candidates:
        raise ValueError("candidates must not be empty")
    for index, candidate in enumerate(self.candidates):
        _validate_candidate(candidate, f"candidates[{index}]")
    if not isinstance(self.proposal, AutotunePolicyProposal):
        raise TypeError("proposal must be AutotunePolicyProposal")

to_audit_record

to_audit_record() -> dict[str, object]

Return a serialisable search record.

Returns

dict[str, object] A serialisable search record.

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

def to_audit_record(self) -> dict[str, object]:
    """Return a serialisable search record.

    Returns
    -------
    dict[str, object]
        A serialisable search record.
    """
    return {
        "seed": _candidate_to_record(self.seed),
        "candidates": [
            _candidate_to_record(candidate) for candidate in self.candidates
        ],
        "proposal": self.proposal.to_audit_record(),
    }

AdaptiveReplayPolicySearchResult dataclass

AdaptiveReplayPolicySearchResult(
    seed: KnobPolicyCandidate,
    rounds: tuple[ReplayPolicySearchResult, ...],
    proposal: AutotunePolicyProposal,
    config: AdaptiveReplayPolicySearchConfig,
)

Multi-round replay-only policy-search result for audit review.

Methods:

__post_init__

__post_init__() -> None

Validate the multi-round adaptive replay-search record.

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

def __post_init__(self) -> None:
    """Validate the multi-round adaptive replay-search record."""
    _validate_candidate(self.seed, "seed")
    if not isinstance(self.rounds, tuple):
        raise TypeError("rounds must be a tuple of ReplayPolicySearchResult")
    if not self.rounds:
        raise ValueError("rounds must not be empty")
    for index, round_result in enumerate(self.rounds):
        if not isinstance(round_result, ReplayPolicySearchResult):
            raise TypeError(f"rounds[{index}] must be ReplayPolicySearchResult")
    if not isinstance(self.proposal, AutotunePolicyProposal):
        raise TypeError("proposal must be AutotunePolicyProposal")
    if not isinstance(self.config, AdaptiveReplayPolicySearchConfig):
        raise TypeError("config must be AdaptiveReplayPolicySearchConfig")

to_audit_record

to_audit_record() -> dict[str, object]

Return a serialisable adaptive-search record.

Returns

dict[str, object] A serialisable adaptive-search record.

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

def to_audit_record(self) -> dict[str, object]:
    """Return a serialisable adaptive-search record.

    Returns
    -------
    dict[str, object]
        A serialisable adaptive-search record.
    """
    return {
        "seed": _candidate_to_record(self.seed),
        "rounds": [round_result.to_audit_record() for round_result in self.rounds],
        "proposal": self.proposal.to_audit_record(),
        "config": {
            "iterations": self.config.iterations,
            "step_decay": self.config.step_decay,
            "improvement_tolerance": self.config.improvement_tolerance,
            "min_step": self.config.min_step,
            "base_search_config": _search_config_to_record(
                self.config.base_search_config
            ),
        },
    }

Functions:

search_replay_policy

search_replay_policy(
    seed: KnobPolicyCandidate,
    evaluator: ReplayPolicyEvaluator,
    search_config: OfflinePolicySearchConfig | None = None,
    reward_config: RewardConfig | None = None,
    proposal_config: PolicyProposalConfig | None = None,
) -> ReplayPolicySearchResult

Generate, replay-evaluate, and propose an autotune policy.

The evaluator must be a replay or simulation adapter. This helper never applies control actions directly; it only turns candidate observations into the existing reviewable proposal record.

Parameters

seed : KnobPolicyCandidate Seed for the deterministic RNG. evaluator : ReplayPolicyEvaluator The objective evaluator. search_config : OfflinePolicySearchConfig | None The search configuration. reward_config : RewardConfig | None The reward configuration. proposal_config : PolicyProposalConfig | None The proposal configuration.

Returns

ReplayPolicySearchResult Generate, replay-evaluate, and propose an autotune policy.

Raises

TypeError If an argument has the wrong type. ValueError If the inputs are invalid or inconsistent.

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

def search_replay_policy(
    seed: KnobPolicyCandidate,
    evaluator: ReplayPolicyEvaluator,
    search_config: OfflinePolicySearchConfig | None = None,
    reward_config: RewardConfig | None = None,
    proposal_config: PolicyProposalConfig | None = None,
) -> ReplayPolicySearchResult:
    """Generate, replay-evaluate, and propose an autotune policy.

    The evaluator must be a replay or simulation adapter. This helper never
    applies control actions directly; it only turns candidate observations into
    the existing reviewable proposal record.

    Parameters
    ----------
    seed : KnobPolicyCandidate
        Seed for the deterministic RNG.
    evaluator : ReplayPolicyEvaluator
        The objective evaluator.
    search_config : OfflinePolicySearchConfig | None
        The search configuration.
    reward_config : RewardConfig | None
        The reward configuration.
    proposal_config : PolicyProposalConfig | None
        The proposal configuration.

    Returns
    -------
    ReplayPolicySearchResult
        Generate, replay-evaluate, and propose an autotune policy.

    Raises
    ------
    TypeError
        If an argument has the wrong type.
    ValueError
        If the inputs are invalid or inconsistent.
    """
    _validate_candidate(seed, "seed")
    if not callable(evaluator):
        raise TypeError("evaluator must be callable")
    active_search_config = cast(
        "OfflinePolicySearchConfig | None",
        _optional_config(
            search_config,
            OfflinePolicySearchConfig,
            "search_config",
        ),
    )
    active_reward_config = cast(
        "RewardConfig | None",
        _optional_config(
            reward_config,
            RewardConfig,
            "reward_config",
        ),
    )
    active_proposal_config = cast(
        "PolicyProposalConfig | None",
        _optional_config(
            proposal_config,
            PolicyProposalConfig,
            "proposal_config",
        ),
    )

    candidates = generate_offline_policy_candidates(seed, active_search_config)
    if not candidates:
        raise ValueError("replay policy search generated no candidates")

    replay_observations = tuple(
        (candidate, _evaluate_candidate(evaluator, candidate))
        for candidate in candidates
    )
    proposal = propose_replay_policy(
        replay_observations,
        reward_config=active_reward_config,
        proposal_config=active_proposal_config,
    )
    return ReplayPolicySearchResult(
        seed=seed,
        candidates=candidates,
        proposal=proposal,
    )

search_adaptive_replay_policy

search_adaptive_replay_policy(
    seed: KnobPolicyCandidate,
    evaluator: ReplayPolicyEvaluator,
    adaptive_config: AdaptiveReplayPolicySearchConfig
    | None = None,
    reward_config: RewardConfig | None = None,
    proposal_config: PolicyProposalConfig | None = None,
) -> AdaptiveReplayPolicySearchResult

Run bounded adaptive replay-only policy search.

Each round generates deterministic coordinate-search candidates around the current best replay candidate, then shrinks the coordinate step sizes. The final proposal is still built from replay observations and existing review gates; no candidate is applied directly.

Parameters

seed : KnobPolicyCandidate Seed for the deterministic RNG. evaluator : ReplayPolicyEvaluator The objective evaluator. adaptive_config : AdaptiveReplayPolicySearchConfig | None Adaptive-tuning configuration. reward_config : RewardConfig | None The reward configuration. proposal_config : PolicyProposalConfig | None The proposal configuration.

Returns

AdaptiveReplayPolicySearchResult Bounded adaptive replay-only policy search.

Raises

TypeError If an argument has the wrong type. ValueError If the inputs are invalid or inconsistent.

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

def search_adaptive_replay_policy(
    seed: KnobPolicyCandidate,
    evaluator: ReplayPolicyEvaluator,
    adaptive_config: AdaptiveReplayPolicySearchConfig | None = None,
    reward_config: RewardConfig | None = None,
    proposal_config: PolicyProposalConfig | None = None,
) -> AdaptiveReplayPolicySearchResult:
    """Run bounded adaptive replay-only policy search.

    Each round generates deterministic coordinate-search candidates around the
    current best replay candidate, then shrinks the coordinate step sizes. The
    final proposal is still built from replay observations and existing review
    gates; no candidate is applied directly.

    Parameters
    ----------
    seed : KnobPolicyCandidate
        Seed for the deterministic RNG.
    evaluator : ReplayPolicyEvaluator
        The objective evaluator.
    adaptive_config : AdaptiveReplayPolicySearchConfig | None
        Adaptive-tuning configuration.
    reward_config : RewardConfig | None
        The reward configuration.
    proposal_config : PolicyProposalConfig | None
        The proposal configuration.

    Returns
    -------
    AdaptiveReplayPolicySearchResult
        Bounded adaptive replay-only policy search.

    Raises
    ------
    TypeError
        If an argument has the wrong type.
    ValueError
        If the inputs are invalid or inconsistent.
    """
    _validate_candidate(seed, "seed")
    if not callable(evaluator):
        raise TypeError("evaluator must be callable")
    active_config = (
        AdaptiveReplayPolicySearchConfig()
        if adaptive_config is None
        else cast(
            "AdaptiveReplayPolicySearchConfig",
            _require_config_type(
                adaptive_config,
                AdaptiveReplayPolicySearchConfig,
                "adaptive_config",
            ),
        )
    )
    active_reward_config = cast(
        "RewardConfig | None",
        _optional_config(
            reward_config,
            RewardConfig,
            "reward_config",
        ),
    )
    active_proposal_config = (
        PolicyProposalConfig()
        if proposal_config is None
        else cast(
            "PolicyProposalConfig",
            _require_config_type(
                proposal_config,
                PolicyProposalConfig,
                "proposal_config",
            ),
        )
    )
    current_seed = seed
    search_config = active_config.base_search_config
    rounds: list[ReplayPolicySearchResult] = []
    replay_observations: list[tuple[KnobPolicyCandidate, RewardObservation]] = []
    best_reward = -np.inf

    for _ in range(active_config.iterations):
        candidates = generate_offline_policy_candidates(current_seed, search_config)
        if not candidates:
            raise ValueError("adaptive replay policy search generated no candidates")
        round_observations = tuple(
            (candidate, _evaluate_candidate(evaluator, candidate))
            for candidate in candidates
        )
        replay_observations.extend(round_observations)
        round_proposal = propose_replay_policy(
            round_observations,
            reward_config=active_reward_config,
            proposal_config=active_proposal_config,
        )
        rounds.append(
            ReplayPolicySearchResult(
                seed=current_seed,
                candidates=candidates,
                proposal=round_proposal,
            )
        )

        ranked = rank_replay_candidates(
            round_observations,
            active_reward_config,
            require_safe=active_proposal_config.require_safe,
            top_k=1,
        )
        candidate_best = ranked[0]
        if candidate_best.reward > best_reward + active_config.improvement_tolerance:
            best_reward = candidate_best.reward
            current_seed = candidate_best.candidate
        search_config = _decay_search_config(search_config, active_config)

    final_proposal = propose_replay_policy(
        tuple(replay_observations),
        reward_config=active_reward_config,
        proposal_config=active_proposal_config,
    )
    return AdaptiveReplayPolicySearchResult(
        seed=seed,
        rounds=tuple(rounds),
        proposal=final_proposal,
        config=active_config,
    )