Assured Prediction: Examples

Each example is a verified run of a guided tour script from the shipped python/examples/ bundle (see PROGRESSION.md for the full 01→06 sequence). Run the guided tour first: it narrates the scenario, explains each metric, and shows when to trust the result. Use the production one-liner when wiring the same API call into your pipeline.

Beta release. Products in this catalog other than the SolvSRK family and SolvScout / SolvTune are beta — suitable for trials and evaluation; APIs and packaging may change before GA. Do not deploy beta builds in production programs without a signed agreement with Resonix. Activate a trial license before running examples — see Install and Licensing.

Journeys

Example 1: Journey 01 — First contact

Version, license, simplest gate_logits(). Every support ticket starts with the package version. The C engine is machine-locked (Ed25519).

Walkthrough:

1. What you are doing — Assured Prediction is a post-hoc selective prediction filter. Any classifier that emits softmax (or logits) can say "I don't know" on uncertain samples and keep only the confident slice. No retraining.

2. Version — Every support ticket starts with the package version.

   • version: 0.1.0
   • native: 0.1.0

3. License — The C engine is machine-locked (Ed25519).

   • license_valid: True

4. Simplest call: gate_logits() — A peaked 4-class logit vector has low Shannon entropy, so the filter accepts the argmax prediction at a moderate epsilon.

   • accepted: True
   • predicted_class: 0
   • entropy: 0.40528
   • max_prob: 0.906178

Guided tour output (from a verified run):

Version, license, simplest gate_logits()

-- Act 1 - What you are doing --
  -> Assured Prediction is a post-hoc selective prediction filter. Any classifier that emits softmax (or logits) can say "I don't know" on uncertain samples and keep only the confident slice. No retraining.

-- Act 2 - Version --
  -> Every support ticket starts with the package version.
  version: 0.1.0
  native: 0.1.0

-- Act 3 - License --
  -> The C engine is machine-locked (Ed25519).
  license_valid: True

-- Act 4 - Simplest call: gate_logits() --
  -> A peaked 4-class logit vector has low Shannon entropy, so the filter accepts the argmax prediction at a moderate epsilon.
  accepted: True
  predicted_class: 0
  entropy: 0.40528
  max_prob: 0.906178

-- Run complete --
  version: 0.1.0
  accepted: True
  next_journey: 02_core_path.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/01_first_contact.py
 
# Production one-liner — same API call you ship:
python -c "import assured_prediction as ap; print(ap.__version__, ap.license_valid())"

Example 2: Journey 02 — Core path (calibrate + filter)

Calibrate epsilon to a coverage target, then filter. AssuredFilter.from_coverage builds the epsilon once. Same epsilon filters the batch; accepted rows are keepers.

Walkthrough:

1. The dial — Coverage is the fraction of samples you keep. Request 50% and Assured Prediction sets epsilon to the entropy percentile that retains the most confident half.

2. Calibrate — AssuredFilter.from_coverage builds the epsilon once.

   • epsilon: 1.039879
   • target_coverage: 0.5

3. Apply — Same epsilon filters the batch; accepted rows are keepers.

   • n_samples: 8
   • n_accepted: 4
   • coverage: 0.5
   • predictions: [0, 0, 0, 0, 0, 0, 0, 0]
   • accepted: [True, True, True, True, False, False, False, False]

Guided tour output (from a verified run):

Calibrate epsilon to a coverage target, then filter

-- Act 1 - The dial --
  -> Coverage is the fraction of samples you keep. Request 50% and Assured Prediction sets epsilon to the entropy percentile that retains the most confident half.

-- Act 2 - Calibrate --
  -> AssuredFilter.from_coverage builds the epsilon once.
  epsilon: 1.039879
  target_coverage: 0.5

-- Act 3 - Apply --
  -> Same epsilon filters the batch; accepted rows are keepers.
  n_samples: 8
  n_accepted: 4
  coverage: 0.5
  predictions: [0, 0, 0, 0, 0, 0, 0, 0]
  accepted: [True, True, True, True, False, False, False, False]

-- Run complete --
  epsilon: 1.039879
  coverage: 0.5
  next_journey: 03_configuration.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/02_core_path.py
 
# Production one-liner — same API call you ship:
python -c "from assured_prediction import AssuredFilter; ..."

Example 3: Journey 03 — Configuration (coverage dial)

Coverage targets move epsilon and keep-rate together. As target coverage rises, epsilon should rise (more permissive) and more samples should be accepted.

Walkthrough:

1. Sweep the dial — Tighter coverage (keep fewer samples) lowers epsilon and raises accuracy on the retained set. Looser coverage does the opposite.

   • target: 0.25
   • epsilon: 0.500858
   • realized_coverage: 0.25
   • n_accepted: 2
   • target: 0.5
   • epsilon: 0.641938
   • realized_coverage: 0.5
   • n_accepted: 4
   • target: 0.75
   • epsilon: 0.676793
   • realized_coverage: 0.75
   • n_accepted: 6

2. Monotonicity check — As target coverage rises, epsilon should rise (more permissive) and more samples should be accepted.

   • epsilons: [0.5009, 0.6419, 0.6768]
   • accepted_counts: [2, 4, 6]

Guided tour output (from a verified run):

Coverage targets move epsilon and keep-rate together

-- Act 1 - Sweep the dial --
  -> Tighter coverage (keep fewer samples) lowers epsilon and raises accuracy on the retained set. Looser coverage does the opposite.
  target: 0.25
  epsilon: 0.500858
  realized_coverage: 0.25
  n_accepted: 2
  target: 0.5
  epsilon: 0.641938
  realized_coverage: 0.5
  n_accepted: 4
  target: 0.75
  epsilon: 0.676793
  realized_coverage: 0.75
  n_accepted: 6

-- Act 2 - Monotonicity check --
  -> As target coverage rises, epsilon should rise (more permissive) and more samples should be accepted.
  epsilons: [0.5009, 0.6419, 0.6768]
  accepted_counts: [2, 4, 6]

-- Run complete --
  targets: [0.25, 0.5, 0.75]
  next_journey: 04_diagnostics.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/03_configuration.py
 
# Production one-liner — same API call you ship:
python -c "from assured_prediction import calibrate_epsilon, gate_batch_probs; ..."

Example 4: Journey 04 — Diagnostics (entropy audit)

Entropy, max_prob, and accepted-set composition. Inspect every sample the filter sees. Operators review only abstained chips; auto-clear the accepted ones.

Walkthrough:

1. Shannon entropy — H(p) = -Σ p_i log(p_i + 1e-10). Peaked softmax → low H → accept. Flat softmax → high H → abstain.

   • peaked_entropy: 0.26183
   • flat_entropy: 1.386294

2. Batch audit — Inspect every sample the filter sees.

   • i: 0
   • accepted: True
   • cls: 0
   • entropy: 0.1773
   • max_prob: 0.9647
   • i: 1
   • accepted: False
   • cls: 1
   • entropy: 1.0978
   • max_prob: 0.3501
   • i: 2
   • accepted: True
   • cls: 0
   • entropy: 0.5604
   • max_prob: 0.8316
   • i: 3
   • accepted: False
   • cls: 2
   • entropy: 1.0978
   • max_prob: 0.3501
   • i: 4
   • accepted: True
   • cls: 0
   • entropy: 0.3102
   • max_prob: 0.9273
   • i: 5
   • accepted: False
   • cls: 1
   • entropy: 1.0984
   • max_prob: 0.3423

3. Accepted set — Operators review only abstained chips; auto-clear the accepted ones.

   • epsilon: 0.829096
   • coverage: 0.5
   • kept_classes: [0, 0, 0]

Guided tour output (from a verified run):

Entropy, max_prob, and accepted-set composition

-- Act 1 - Shannon entropy --
  -> H(p) = -Σ p_i log(p_i + 1e-10). Peaked softmax → low H → accept. Flat softmax → high H → abstain.
  peaked_entropy: 0.26183
  flat_entropy: 1.386294

-- Act 2 - Batch audit --
  -> Inspect every sample the filter sees.
  i: 0
  accepted: True
  cls: 0
  entropy: 0.1773
  max_prob: 0.9647
  i: 1
  accepted: False
  cls: 1
  entropy: 1.0978
  max_prob: 0.3501
  i: 2
  accepted: True
  cls: 0
  entropy: 0.5604
  max_prob: 0.8316
  i: 3
  accepted: False
  cls: 2
  entropy: 1.0978
  max_prob: 0.3501
  i: 4
  accepted: True
  cls: 0
  entropy: 0.3102
  max_prob: 0.9273
  i: 5
  accepted: False
  cls: 1
  entropy: 1.0984
  max_prob: 0.3423

-- Act 3 - Accepted set --
  -> Operators review only abstained chips; auto-clear the accepted ones.
  epsilon: 0.829096
  coverage: 0.5
  kept_classes: [0, 0, 0]

-- Run complete --
  coverage: 0.5
  next_journey: 05_atr_scenario.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/04_diagnostics.py
 
# Production one-liner — same API call you ship:
python -c "from assured_prediction import entropy, softmax; ..."

Example 5: Journey 05 — Defense ATR scenario

A J2 cell gets thousands of SAR chips per day. Assured Prediction at 50% coverage auto-classifies the confident half and sends the rest to human review — same architecture validated on AFRL MSTAR (RADAR_S1). Use the batch itself as the entropy reference. Accepted chips auto-clear; abstained chips go to review.

Walkthrough:

1. Mission context — A J2 cell gets thousands of SAR chips per day. Assured Prediction at 50% coverage auto-classifies the confident half and sends the rest to human review — same architecture validated on AFRL MSTAR (RADAR_S1).

2. Calibrate on the window — Use the batch itself as the entropy reference.

   • epsilon: 0.751754
   • target_coverage: 0.5
   • n_chips: 8

3. Filter — Accepted chips auto-clear; abstained chips go to review.

   • auto_clear: ['orbit-A/chip-01->BMP2', 'orbit-A/chip-03->BMP2', 'orbit-B/chip-05->BTR70', 'orbit-B/chip-07->T72']
   • review_queue: ['orbit-A/chip-02 (H=1.098)', 'orbit-A/chip-04 (H=1.098)', 'orbit-B/chip-06 (H=1.097)', 'orbit-B/chip-08 (H=1.099)']
   • coverage: 0.5

4. Ensemble option — For production reliability, average softmax across N≥5 seeds before gating. Here two disagreeing models raise ensemble entropy.

   • ensemble_accepted: False
   • ensemble_entropy: 0.7697

Guided tour output (from a verified run):

Auto-clear confident SAR chips; route uncertain ones to analysts

-- Act 1 - Mission context --
  -> A J2 cell gets thousands of SAR chips per day. Assured Prediction at 50% coverage auto-classifies the confident half and sends the rest to human review — same architecture validated on AFRL MSTAR (RADAR_S1).

-- Act 2 - Calibrate on the window --
  -> Use the batch itself as the entropy reference.
  epsilon: 0.751754
  target_coverage: 0.5
  n_chips: 8

-- Act 3 - Filter --
  -> Accepted chips auto-clear; abstained chips go to review.
  auto_clear: ['orbit-A/chip-01->BMP2', 'orbit-A/chip-03->BMP2', 'orbit-B/chip-05->BTR70', 'orbit-B/chip-07->T72']
  review_queue: ['orbit-A/chip-02 (H=1.098)', 'orbit-A/chip-04 (H=1.098)', 'orbit-B/chip-06 (H=1.097)', 'orbit-B/chip-08 (H=1.099)']
  coverage: 0.5

-- Act 4 - Ensemble option --
  -> For production reliability, average softmax across N≥5 seeds before gating. Here two disagreeing models raise ensemble entropy.
  ensemble_accepted: False
  ensemble_entropy: 0.7697

-- Run complete --
  coverage: 0.5
  n_review: 4
  next_journey: 06_limits.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/05_atr_scenario.py
 
# Production one-liner — same API call you ship:
python -c "from assured_prediction import AssuredFilter; ..."

Example 6: Journey 06 — Limits

Honest scope: what Assured Prediction is NOT. When every sample is already high-confidence, a very low coverage target can still accept samples — or look empty if epsilon collapses. Tune the floor to your base-model accuracy. Coverage must be in (0, 1].

Walkthrough:

1. Post-hoc filter only — Assured Prediction does not retrain the model, does not improve weak models below ~20% baseline, and does not replace model quality. It trades coverage for accuracy on the retained slice.

2. Aggressive coverage on peaked models — When every sample is already high-confidence, a very low coverage target can still accept samples — or look empty if epsilon collapses. Tune the floor to your base-model accuracy.

   • epsilon: 0.111902
   • coverage: 0.0
   • n_accepted: 0

3. Bad arguments raise — Coverage must be in (0, 1].

   • error: calibrate_epsilon: value out of range
   • value_error_raised: True

4. Sibling products — Need bit-identical decision receipts? Use DeterministicML. Need tracking consistency? SolvFilter. Need dynamics integration? SolvSRK. Assured Prediction is the selective gate in front of any softmax head.

Guided tour output (from a verified run):

Honest scope: what Assured Prediction is NOT

-- Act 1 - Post-hoc filter only --
  -> Assured Prediction does not retrain the model, does not improve weak models below ~20% baseline, and does not replace model quality. It trades coverage for accuracy on the retained slice.

-- Act 2 - Aggressive coverage on peaked models --
  -> When every sample is already high-confidence, a very low coverage target can still accept samples — or look empty if epsilon collapses. Tune the floor to your base-model accuracy.
  epsilon: 0.111902
  coverage: 0.0
  n_accepted: 0

-- Act 3 - Bad arguments raise --
  -> Coverage must be in (0, 1].
  error: calibrate_epsilon: value out of range
  value_error_raised: True

-- Act 4 - Sibling products --
  -> Need bit-identical decision receipts? Use DeterministicML. Need tracking consistency? SolvFilter. Need dynamics integration? SolvSRK. Assured Prediction is the selective gate in front of any softmax head.

-- Run complete --
  value_error_raised: True

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/06_limits.py
 
# Production one-liner — same API call you ship:
python -c "from assured_prediction import calibrate_epsilon; calibrate_epsilon([[0.5,0.5]], 0.0)"

Example bundle

Every journey is a domain scenario with narrated acts — run the guided tour first to see what each number means, then copy the production one-liner into your pipeline.

Guided journeys

Run from the python/ directory after install and license activation. Set ASSURED_PREDICTION_QUIET=1 only when you want silent CLI runs (no narration).