Dynamic Threshold Tuning for Fleet Types

Static defect severity thresholds fail to account for operational variance across heterogeneous fleets, and that failure has a regulatory edge. A brake-lining wear reading that should freeze dispatch on a Class 8 long-haul tractor may sit inside acceptable service limits for a regional step-van running at a lower GVWR — but the moment a computed threshold downgrades a condition that meets FMCSA out-of-service criteria under 49 CFR § 396.11©(2), the carrier is one roadside inspection away from an operating-with-a-known-defect violation. Within the Defect Classification & Repair Order Routing architecture, dynamic threshold tuning is the calibration layer that shifts the carrier-discretion portion of the severity scale per fleet type while leaving the federally mandated floors immovable. This page specifies the schema, the calibration workflow, and the routing integration required to operationalize adaptive thresholding without letting statistics override the regulation.

The scoring itself is not computed here: the 0–100 severity value is produced upstream by the Severity Scoring Algorithms for DVIR Defects engine, and the branch that acts on the tuned floors is owned by Critical vs Non-Critical Routing Logic. This layer supplies the fleet-aware cut points those two consume, and it must supply them deterministically and with a version stamp so any past routing decision can be replayed exactly during a DOT audit.

The calibration job is a scheduled, deterministic batch process that reads historical inspection records and writes a versioned threshold registry. It does not touch live routing directly; it publishes a registry that the routing service pulls. Target Python 3.10+ (the code below uses the union X | Y type syntax and match statements) with:

• Pydantic 2.x — schema validation and immutable, versioned registry payloads.
• pandas 2.x + NumPy — rolling-window aggregation, empirical CDF, and EMA smoothing over the DVIR event store.
• hashlib / datetime (stdlib) — SHA-256 audit hashing and timezone-aware effective dates.
• Celery 5.x or Prefect 2.x — scheduling the quarterly and event-driven recalibration runs.
• A read replica of the DVIR event store — never calibrate against the write primary; calibration is read-heavy and must not contend with ingestion.

The calibration input must already conform to the canonical defect contract defined in the Standardized DVIR JSON Schema Design. Records that fail that contract are excluded from the distribution rather than coerced, because a malformed record silently inflating a percentile is exactly the kind of drift that corrupts a threshold.

Threshold tuning operates on two records: the historical defect observations it aggregates, and the threshold configuration it emits. Field names and the 0–100 severity scale are held identical to the scoring and routing pages so a single defect can be reconstructed across the whole pipeline. The emitted configuration is the contract the routing layer reads:

The severity bands the tuned floors feed into are the same across every page in this section: 0–34 minor, 35–69 major, 70–100 critical. Tuning is permitted to move the minor/major boundary within a fleet type; it is never permitted to move the critical floor below 70 for a defect tagged DOT_OOS_CRITERIA. Enforcing the configuration contract in Pydantic makes the schema the first calibration gate — a registry that does not validate is never promoted:

from datetime import datetime
from typing import Literal

from pydantic import BaseModel, Field


class DefectThresholdConfig(BaseModel):
    model_config = {"frozen": True}  # immutable once built — corrections create a new version

    fleet_type: Literal[
        "long_haul_tractor", "regional_step_van",
        "refrigerated_box", "last_mile_sprinter",
    ]
    defect_category: str
    base_severity_score: float = Field(ge=0.0, le=10.0)
    frequency_percentile: float = Field(
        ge=0.0, le=1.0, description="Rolling 90th-percentile trigger threshold"
    )
    adjustment_multiplier: float = Field(default=1.0, ge=0.5, le=2.0)
    compliance_guardrail: Literal["OOS", "conditional", "monitor_only"]
    effective_date: datetime
    version: int


class FleetThresholdRegistry(BaseModel):
    model_config = {"frozen": True}

    registry_id: str
    configurations: list[DefectThresholdConfig]
    last_calibration: datetime
    audit_hash: str  # SHA-256 over the canonical-JSON of configurations

Calibration is a deterministic pipeline: it ingests historical DVIR submissions, computes per-fleet defect distributions, derives a bounded multiplier, and then subordinates every derived value to the regulatory guardrail. Run it as an ordered sequence so a failed step halts promotion rather than shipping a half-tuned registry.

1. Aggregate and partition. Query the DVIR event store, filtering by fleet_type, defect_category, and inspection_ts. Exclude records flagged duplicate or manually overridden within the past 14 days to prevent calibration drift, and partition by asset class so a long-haul tractor’s brake distribution never contaminates a sprinter’s.
2. Compute the rolling distribution. Use a sliding 90-day window with min_periods=30 for statistical significance, and compute the empirical cumulative distribution function (ECDF) per defect category to locate the inflection point where minor wear becomes an actionable maintenance trigger.
3. Derive and smooth the multiplier. Compare the current rolling 90th percentile against the historical baseline, then apply exponential-moving-average smoothing with decay α=0.15 to dampen seasonal volatility (winter tire wear, summer cooling-system failures). Clamp the output to [0.5, 2.0] so no single quarter can produce a runaway threshold.
4. Enforce the guardrail — imperatively. Overlay the regulatory constraint last. If a computed threshold would downgrade a defect tagged DOT_OOS_CRITERIA below the critical floor of 70, reject that configuration, log the rejection with the offending values, and keep the prior version. This hard stop guarantees alignment with 49 CFR § 396.11©(2) and prevents an automated system from tuning its way around a statutory OOS condition.
5. Version, hash, and dry-run. Serialize the validated configuration set, compute a SHA-256 audit_hash over its canonical JSON, and stamp a monotonic version. Replay the candidate registry against the last 72 hours of live DVIR traffic in shadow mode and diff the routing outcomes before promoting it to active.

The multiplier derivation and the guardrail clamp are the two steps that must be pure functions of their inputs — no wall-clock reads, no randomness — so the same history always yields the same registry:

import numpy as np
import pandas as pd

CRITICAL_FLOOR = 70.0  # 0-100 scale; matches the routing layer's critical band


def calibrate_multiplier(history: pd.Series, baseline_p90: float) -> float:
    """Derive a bounded, EMA-smoothed adjustment multiplier for one
    (fleet_type, defect_category) pair. Deterministic in `history`."""
    if history.count() < 30:
        return 1.0  # insufficient signal — do not tune, hold neutral
    rolling_p90 = history.rolling(window=90, min_periods=30).quantile(0.90)
    smoothed = rolling_p90.ewm(alpha=0.15, adjust=False).mean().iloc[-1]
    raw = float(smoothed) / baseline_p90 if baseline_p90 else 1.0
    return float(np.clip(raw, 0.5, 2.0))


def enforce_guardrail(tuned_floor: float, guardrail: str) -> float:
    """Reject any tuned floor that would drop an OOS defect below the
    federal critical band. 49 CFR 396.11(c)(2)."""
    if guardrail == "OOS" and tuned_floor < CRITICAL_FLOOR:
        raise ValueError(
            f"tuned floor {tuned_floor} below OOS critical floor {CRITICAL_FLOOR}"
        )
    return tuned_floor

The registry’s whole purpose is to move where a defect lands on the severity scale — but only inside the band the regulation leaves to carrier judgment. The mapping the routing layer must honor is explicit:

• Score ≥ 70 (critical), or any DOT_OOS_CRITERIA defect: trigger an out-of-service hold. This floor is fixed. No adjustment_multiplier may lower it, and step 4 of the workflow rejects any registry that tries.
• Score 35–69 (major): route to the regulated 24-hour repair queue. Tuning may raise or lower a fleet’s entry into this band to reflect that a refrigerated box’s cooling-related defect matures faster than a sprinter’s, but the 24-hour pre-trip clearance obligation still attaches.
• Score 0–34 (minor): route to scheduled preventive maintenance. This is where most tuning takes effect, absorbing operational variance without regulatory consequence.

For geographically dispersed operations, state inspection mandates can impose stricter floors than the federal baseline — California’s BIT program or New York’s periodic inspection requirements, for example. Encode those as per-jurisdiction guardrail overrides, version them separately from the fleet-type multipliers, and audit them on their own track so a regulator can see exactly which rule moved a threshold. A jurisdiction override may only tighten a floor; it may never relax one below the federal minimum.

Automated ingestion routinely produces sensor noise, OCR misreads, and inconsistent driver terminology. A sudden spike in a previously rare defect code is far more likely a miscalibrated sensor or an OCR artifact than a genuine fleet-wide failure. Route such spikes to a quarantine queue for human review before they reach the calibrator — an unfiltered artifact inflates a percentile and drags a threshold with it. Cross-referencing candidate distributions against the normalization rules in Automated Field Mapping & Data Normalization keeps the input signal clean before it ever weights a multiplier.

Once a registry version is promoted, the tuned floors it carries flow into the dispatch and maintenance orchestration layer, and from there to the CMMS, telematics, and ELD platforms that execute the repair. Emit the promotion as an immutable event, not a mutable config write:

• Idempotent promotion. Key each promotion event on (registry_id, version) so a retried publish is a no-op. A consumer that already applied version N ignores a duplicate.
• Cryptographic chaining. Hash-link each registry version to its predecessor via audit_hash, so a deleted or reordered calibration is detectable — the same tamper-evidence property the routing layer applies to its decisions.
• Dual-write shadow comparison. During a calibration cycle, route live DVIR payloads through both the active and the candidate registry, and quantify the routing drift before promotion. If the candidate would have moved any DOT_OOS_CRITERIA defect off the OOS lane, block the promotion outright.
• Structured decision logging. Log fleet_type, defect_category, applied_multiplier, compliance_guardrail, and the resolving version as JSON for every ingested report, so the reason a specific defect routed the way it did is reconstructable months later.

The repair orders that the tuned routing ultimately generates are consumed downstream by Mechanic Assignment & Workload Balancing, which is why the multiplier must never silently change the volume of critical work a shop expects without a logged, versioned reason.

• Schema validation — reject any registry that fails the FleetThresholdConfig contract; never promote a partially validated configuration set.
• Deterministic execution — multiplier derivation and guardrail enforcement are pure functions of the input history and tags; no clocks or randomness inside the calibration path.
• Immovable federal floors — the critical floor of 70 for DOT_OOS_CRITERIA defects is enforced in code and rejects any tuned value below it.
• Bounded adjustment — clamp every adjustment_multiplier to [0.5, 2.0] so no single cycle can produce a runaway threshold.
• Versioned, hashed registries — stamp a monotonic version and a SHA-256 audit_hash on every promotion so a past routing call can be replayed exactly.
• Shadow before promote — dry-run every candidate registry against recent live traffic and block promotion on any OOS-lane regression.
• Quarantine noisy input — route anomalous defect spikes to human review so sensor noise and OCR artifacts never weight a percentile.

• Severity Scoring Algorithms for DVIR Defects — produces the 0–100 score whose bands this layer tunes.
• Critical vs Non-Critical Routing Logic — consumes the fleet-aware cut points emitted here.
• Mechanic Assignment & Workload Balancing — receives the repair orders the tuned routing generates.
• Standardized DVIR JSON Schema Design — the canonical contract every calibration input must satisfy.
• Automated Field Mapping & Data Normalization — cleans the input signal before it weights a threshold.

Back to Defect Classification & Repair Order Routing.