Trajectory Preflight¶

Trajectory preflight estimates whether a prompt is likely to trigger a runtime halt before the main generation starts. TrajectorySimulator produces seeded candidate trajectories and PredictivePreHaltSteering turns the aggregate verdict into a calibrated allow, warn, or halt guard decision.

Predictive Steering¶

PredictivePreHaltSteering uses three evidence gates:

halt when the empirical halt probability crosses the calibrated risk threshold
escalate when the upper confidence bound crosses the calibrated threshold
escalate when there are too few simulations for the configured minimum

The steering payload is tenant-safe. It stores halt probability, confidence interval bounds, backend recommendation, and trajectory IDs for failed draws; it does not serialise prompt text or sampled token text.

from director_ai.core.guard_control import RiskEnvelope
from director_ai.core.trajectory import PredictivePreHaltSteering

steering = PredictivePreHaltSteering(min_simulations=8)
decision = steering.evaluate(
    verdict,
    risk_envelope=RiskEnvelope(
        action_category="inference_steering",
        reversibility="reversible",
        domain="regulated",
        calibrated_threshold=0.5,
        no_go_threshold=0.9,
    ),
    policy_id="policy.prehalt.regulated",
)

if decision.action == "escalate":
    route_to = decision.recommended_backend

Use InferenceServerHook.steer() when the decision must affect pre-sampling logits directly. The hook maps escalate to a finite negative bias for the candidate token and maps halt to the same block action used by the coherence threshold hook.

Full API¶

director_ai.core.trajectory.simulator.TrajectorySimulator ¶

TrajectorySimulator(*, actor: Actor, scorer: VerdictProducer, n_simulations: int = 8, halt_rate_halt: float = 0.5, halt_rate_warn: float = 0.25, base_seed: int = 17, ci_level: float = 0.95)

Pre-execution Monte-Carlo halt check.

Parameters:

Name	Type	Description	Default
`actor`	`Actor`	A :class:`Actor` that samples token sequences.	required
`scorer`	`VerdictProducer`	A :class:`VerdictProducer` that returns `(approved, score)`.	required
`n_simulations`	`int`	Number of independent draws per :meth:`preflight` call. Defaults to 8 — enough for a useful halt-rate estimate without turning preflight into the slow path.	`8`
`halt_rate_halt`	`float`	Halt-rate threshold above which :meth:`preflight` returns `action="halt"`.	`0.5`
`halt_rate_warn`	`float`	Halt-rate threshold for `action="warn"`. Between this and `halt_rate_halt` the caller is expected to escalate (e.g. route to a stronger model).	`0.25`
`base_seed`	`int`	Seed offset; per-trajectory seeds are `base_seed + i`.	`17`
`ci_level`	`float`	Credible-interval level for the `ci_low` / `ci_high` fields; 0.95 is the default.	`0.95`

preflight ¶

preflight(prompt: str, *, tenant_id: str = '', on_trajectory: Callable[[TrajectoryResult], None] | None = None) -> PreflightVerdict

Run the Monte-Carlo loop and return an aggregate verdict.

on_trajectory is an optional per-draw callback — handy for live observability sinks that want to stream intermediate results without waiting for the aggregate.

director_ai.core.trajectory.simulator.PreflightVerdict `dataclass` ¶

PreflightVerdict(n_simulations: int, halt_rate: float, mean_coherence: float, std_coherence: float, ci_low: float, ci_high: float, recommended: Action, reason: str, trajectories: tuple[TrajectoryResult, ...] = tuple(), safety_event: SafetyEvent | None = None)

Aggregate of N simulated trajectories.

director_ai.core.trajectory.steering.PredictivePreHaltSteering ¶

PredictivePreHaltSteering(*, min_simulations: int = 8, uncertainty_margin: float = 0.0)

Escalate or halt requests using calibrated trajectory risk evidence.

evaluate ¶

evaluate(verdict: PreflightVerdict, *, risk_envelope: RiskEnvelope, policy_id: str) -> PreHaltSteeringDecision

Return a pre-halt steering decision from a trajectory verdict.

director_ai.core.trajectory.steering.PreHaltSteeringDecision `dataclass` ¶

PreHaltSteeringDecision(action: SteeringAction, reason: str, halt_probability: float, ci_low: float, ci_high: float, recommended_backend: str, evidence_refs: Sequence[str], guard_decision: GuardDecision)

Tenant-safe pre-halt steering decision derived from trajectory evidence.

to_dict ¶

to_dict() -> dict[str, Any]

Serialise without trajectory token text or prompt payloads.

to_safety_event ¶

to_safety_event(*, hook_id: str, hook_scope: str = 'trajectory', request_id: str = '', tenant_id: str = '', latency_ms: float | None = None) -> SafetyEvent

Convert the steering decision to the shared safety-event schema.