triage4 1.0.0__py3-none-any.whl

triage4/__init__.py

@@ -0,0 +1,70 @@
+"""
+Tiered Resource Allocation for IoT Alarm and Geographic-priority Emergency (TRIAGE/4).
+
+Four-band hierarchical scheduler that resolves priority inversion by
+separating semantic urgency (alarms) from geographic priority (zones).
+
+Main components:
+    - TRIAGE4Scheduler: Main scheduler with discrete-event simulation
+    - TRIAGE4Config: Configuration dataclass with band thresholds and token parameters
+    - DeviceFairQueue: Per-device round-robin queue for fairness
+    - BandClassifier: Message-to-band classification logic
+
+Band hierarchy:
+    0. ALARM: Emergency messages, strict priority
+    1. HIGH: High-priority zones, token-constrained
+    2. STANDARD: Standard zones, token-constrained
+    3. BACKGROUND: Low-priority zones, token-constrained
+
+Example:
+    >>> from triage4 import TRIAGE4Scheduler, TRIAGE4Config
+    >>> config = TRIAGE4Config(
+    ...     high_zone_max=1,
+    ...     standard_zone_max=3,
+    ...     high_token_budget=10,
+    ...     service_rate=20.0
+    ... )
+    >>> scheduler = TRIAGE4Scheduler(config)
+    >>> result = scheduler.schedule(
+    ...     arrival_times=[0.0, 0.1, 0.2],
+    ...     device_ids=["sensor_1", "sensor_2", "sensor_1"],
+    ...     zone_priorities=[0, 5, 2],
+    ...     is_alarm=[False, True, False]
+    ... )
+"""
+
+from .band_classifier import (
+    BAND_ALARM,
+    BAND_BACKGROUND,
+    BAND_HIGH,
+    BAND_STANDARD,
+    BandClassifier,
+)
+from .adaptive_token_bucket import AdaptiveTokenBucket
+from .alarm_rate_monitor import AlarmRateMonitor
+from .device_fair_queue import DeviceFairQueue
+from .triage4_config import TRIAGE4Config, create_triage4_custom, create_triage4_default
+from .triage4_scheduler import TRIAGE4Scheduler
+from .source_aware_queue import SourceAwareQueue
+
+__all__ = [
+    # Main scheduler
+    "TRIAGE4Scheduler",
+    # Configuration
+    "TRIAGE4Config",
+    "create_triage4_default",
+    "create_triage4_custom",
+    # Components
+    "BandClassifier",
+    "DeviceFairQueue",
+    "AdaptiveTokenBucket",
+    "AlarmRateMonitor",
+    "SourceAwareQueue",
+    # Band constants
+    "BAND_ALARM",
+    "BAND_HIGH",
+    "BAND_STANDARD",
+    "BAND_BACKGROUND",
+]
+
+__version__ = "1.0.0"

triage4/adaptive_token_bucket.py

@@ -0,0 +1,61 @@
+"""
+Adaptive token bucket that activates only when alarm protection is enabled.
+
+Wraps the standard TokenBucket and exposes activation/deactivation hooks with
+hysteresis controlled by the caller (e.g., AlarmRateMonitor).
+"""
+
+from .token_bucket import TIME_TOLERANCE, TokenBucket
+
+
+class AdaptiveTokenBucket:
+    """Token bucket that can be activated/deactivated at runtime."""
+
+    def __init__(self, budget: int, period: float, burst_capacity: int | None = None):
+        if budget <= 0:
+            raise ValueError("budget must be positive")
+        if period <= 0:
+            raise ValueError("period must be positive")
+        if burst_capacity is not None and burst_capacity < budget:
+            raise ValueError("burst_capacity must be >= budget")
+
+        self.bucket = TokenBucket(
+            budget=budget, period=period, burst_capacity=burst_capacity
+        )
+        self.active = False
+
+    def activate(self, current_time: float) -> None:
+        """Enable rate limiting and realign refill schedule."""
+        if not self.active:
+            self.active = True
+            # Align next refill to current_time to avoid retroactive refills.
+            self.bucket.next_refill = current_time + self.bucket.period
+            self.bucket.tokens = self.bucket.max_capacity
+
+    def deactivate(self) -> None:
+        """Disable rate limiting (bucket becomes pass-through)."""
+        self.active = False
+
+    def consume(self, current_time: float, amount: int = 1) -> bool:
+        """
+        Consume tokens if active. Returns True if the request is allowed.
+        When inactive, always returns True (no limiting).
+        """
+        if not self.active:
+            return True
+
+        self.bucket.refill(current_time)
+        return self.bucket.consume(amount)
+
+    def get_next_refill_time(self) -> float:
+        """Expose next refill time for event scheduling."""
+        if not self.active:
+            # If inactive, never schedule on bucket events
+            return float("inf")
+        return self.bucket.get_next_refill_time()
+
+    @property
+    def tokens(self) -> int:
+        """Current token count (0 when inactive implies unlimited)."""
+        return self.bucket.tokens if self.active else -1
+

triage4/alarm_rate_monitor.py

@@ -0,0 +1,96 @@
+"""
+Sliding-window alarm rate monitor for adaptive protection.
+
+Detects abnormal alarm rates using a simple windowed counter with hysteresis.
+"""
+
+from collections import deque
+from typing import Deque, Tuple
+
+from .token_bucket import TIME_TOLERANCE
+
+
+class AlarmRateMonitor:
+    """Track alarm arrivals and detect abnormal rates."""
+
+    def __init__(
+        self,
+        window_duration: float,
+        abnormal_threshold: float,
+        deactivation_threshold: float,
+        min_observations: int = 1,
+    ):
+        """
+        Args:
+            window_duration: Sliding window size in seconds
+            abnormal_threshold: Alarms/sec that triggers protection
+            deactivation_threshold: Alarms/sec below which protection deactivates
+            min_observations: Minimum alarms before detection can trigger
+        """
+        if window_duration <= 0:
+            raise ValueError("window_duration must be positive")
+        if abnormal_threshold <= 0:
+            raise ValueError("abnormal_threshold must be positive")
+        if deactivation_threshold < 0:
+            raise ValueError("deactivation_threshold must be non-negative")
+        if deactivation_threshold > abnormal_threshold:
+            raise ValueError(
+                "deactivation_threshold must be <= abnormal_threshold for hysteresis"
+            )
+        if min_observations <= 0:
+            raise ValueError("min_observations must be positive")
+
+        self.window_duration = float(window_duration)
+        self.abnormal_threshold = float(abnormal_threshold)
+        self.deactivation_threshold = float(deactivation_threshold)
+        self.min_observations = int(min_observations)
+
+        self._arrivals: Deque[Tuple[float, str]] = deque()
+
+    def record_arrival(self, timestamp: float, alarm_source: str) -> None:
+        """Add an alarm arrival to the window."""
+        self._arrivals.append((timestamp, alarm_source))
+        self._prune(timestamp)
+
+    def get_rate(self, now: float | None = None) -> float:
+        """Return alarms/sec over the current window."""
+        if now is None and self._arrivals:
+            now = self._arrivals[-1][0]
+        elif now is None:
+            return 0.0
+
+        self._prune(now)
+        if not self._arrivals:
+            return 0.0
+
+        window_span = max(self.window_duration, TIME_TOLERANCE)
+        return len(self._arrivals) / window_span
+
+    def is_abnormal(self, now: float | None = None) -> bool:
+        """True if rate exceeds abnormal threshold with enough observations."""
+        if now is None and self._arrivals:
+            now = self._arrivals[-1][0]
+        elif now is None:
+            return False
+
+        self._prune(now)
+        if len(self._arrivals) < self.min_observations:
+            return False
+        return self.get_rate(now) >= self.abnormal_threshold - TIME_TOLERANCE
+
+    def is_recovered(self, now: float | None = None) -> bool:
+        """True if rate has fallen below deactivation threshold."""
+        if now is None and self._arrivals:
+            now = self._arrivals[-1][0]
+        elif now is None:
+            return True
+
+        self._prune(now)
+        return self.get_rate(now) <= self.deactivation_threshold + TIME_TOLERANCE
+
+    def _prune(self, now: float) -> None:
+        """Drop arrivals outside the sliding window."""
+        cutoff = now - self.window_duration - TIME_TOLERANCE
+        while self._arrivals and self._arrivals[0][0] < cutoff:
+            self._arrivals.popleft()
+

triage4/band_classifier.py

@@ -0,0 +1,110 @@
+"""
+Band classification logic for TRIAGE/4.
+
+Maps messages to one of four bands based on semantic urgency (is_alarm)
+and geographic priority (zone_priority).
+"""
+
+# Band constants
+BAND_ALARM = 0  # Emergency messages, always served first
+BAND_HIGH = 1  # High-priority zone telemetry, token-constrained
+BAND_STANDARD = 2  # Standard zone telemetry, token-constrained
+BAND_BACKGROUND = 3  # Low-priority zone data, best-effort
+
+
+class BandClassifier:
+    """
+    Classifies messages into TRIAGE/4 bands.
+
+    Classification hierarchy:
+        1. Semantic urgency (is_alarm) overrides geographic priority
+        2. Geographic priority (zone_priority) determines band for non-alarms
+
+    Band assignment rules:
+        - is_alarm=True → ALARM (0) - regardless of zone priority
+        - zone_priority <= high_zone_max → HIGH (1)
+        - zone_priority <= standard_zone_max → STANDARD (2)
+        - zone_priority > standard_zone_max → BACKGROUND (3)
+
+    This separation resolves priority inversion where routine telemetry
+    from high-priority zones delays critical alarms from low-priority zones.
+    """
+
+    def __init__(self, high_zone_max: int, standard_zone_max: int):
+        """
+        Initialize band classifier with zone thresholds.
+
+        Args:
+            high_zone_max: Maximum zone priority for HIGH band (inclusive)
+            standard_zone_max: Maximum zone priority for STANDARD band (inclusive)
+
+        Example:
+            >>> classifier = BandClassifier(high_zone_max=1, standard_zone_max=3)
+            >>> classifier.classify(zone_priority=0, is_alarm=False)
+            1  # HIGH band
+            >>> classifier.classify(zone_priority=5, is_alarm=True)
+            0  # ALARM band (semantic override)
+        """
+        if high_zone_max < 0:
+            raise ValueError(f"high_zone_max must be non-negative, got {high_zone_max}")
+        if standard_zone_max < high_zone_max:
+            raise ValueError(
+                f"standard_zone_max ({standard_zone_max}) must be >= "
+                f"high_zone_max ({high_zone_max})"
+            )
+
+        self.high_zone_max = high_zone_max
+        self.standard_zone_max = standard_zone_max
+
+    def classify(self, zone_priority: int, is_alarm: bool) -> int:
+        """
+        Classify message into TRIAGE/4 band.
+
+        Args:
+            zone_priority: Geographic zone priority (0=highest priority zone)
+            is_alarm: Semantic urgency flag (True for emergency messages)
+
+        Returns:
+            Band number: 0=ALARM, 1=HIGH, 2=STANDARD, 3=BACKGROUND
+
+        Raises:
+            ValueError: If zone_priority is negative
+        """
+        if zone_priority < 0:
+            raise ValueError(f"zone_priority must be non-negative, got {zone_priority}")
+
+        # Semantic urgency overrides geographic priority
+        if is_alarm:
+            return BAND_ALARM
+
+        # Geographic priority determines band for non-alarms
+        if zone_priority <= self.high_zone_max:
+            return BAND_HIGH
+        elif zone_priority <= self.standard_zone_max:
+            return BAND_STANDARD
+        else:
+            return BAND_BACKGROUND
+
+    def get_band_name(self, band: int) -> str:
+        """
+        Get human-readable band name.
+
+        Args:
+            band: Band number (0-3)
+
+        Returns:
+            Band name string
+        """
+        names = {
+            BAND_ALARM: "ALARM",
+            BAND_HIGH: "HIGH",
+            BAND_STANDARD: "STANDARD",
+            BAND_BACKGROUND: "BACKGROUND",
+        }
+        return names.get(band, f"UNKNOWN({band})")
+
+    def __repr__(self) -> str:
+        return (
+            f"BandClassifier(high_zone_max={self.high_zone_max}, "
+            f"standard_zone_max={self.standard_zone_max})"
+        )

triage4/device_fair_queue.py

@@ -0,0 +1,184 @@
+"""
+Per-device fair queue with round-robin device selection.
+
+Prevents device monopolization by cycling through devices and serving
+one message per device per round, maintaining FIFO within each device.
+"""
+
+from collections import deque
+from typing import Dict, Optional
+
+
+class DeviceFairQueue:
+    """
+    Round-robin per-device queue within a band.
+
+    Ensures fairness by cycling through active devices and serving one message
+    from each device per round. Messages within each device are served FIFO.
+
+    Key properties:
+        - Fair device selection: Each device gets equal turns regardless of load
+        - FIFO within device: Messages from same device served in arrival order
+        - Monopolization prevention: High-rate device cannot starve low-rate device
+        - Dynamic device set: Devices added/removed as queues fill/empty
+
+    Example:
+        >>> queue = DeviceFairQueue()
+        >>> queue.enqueue(job_idx=0, device_id="A")
+        >>> queue.enqueue(job_idx=1, device_id="B")
+        >>> queue.enqueue(job_idx=2, device_id="A")
+        >>> queue.dequeue()  # Returns 0 from device A
+        0
+        >>> queue.dequeue()  # Returns 1 from device B (round-robin)
+        1
+        >>> queue.dequeue()  # Returns 2 from device A (back to A)
+        2
+    """
+
+    def __init__(self):
+        """Initialize empty per-device fair queue."""
+        self.device_queues: Dict[str, deque[int]] = {}
+        self.last_served_device: Optional[str] = None
+
+    def enqueue(self, job_idx: int, device_id: str) -> None:
+        """
+        Add message to device's queue.
+
+        Args:
+            job_idx: Index of job in arrival_times array
+            device_id: Device identifier (e.g., "sensor_42", "EDU_5")
+        """
+        if device_id not in self.device_queues:
+            self.device_queues[device_id] = deque()
+        self.device_queues[device_id].append(job_idx)
+
+    def dequeue(self) -> Optional[int]:
+        """
+        Remove and return next message using round-robin device selection.
+
+        Round-robin algorithm:
+            1. Get list of devices with messages
+            2. Find position of last_served_device (or start at 0)
+            3. Iterate circularly starting from next device
+            4. Return first message from first non-empty device
+            5. Update last_served_device pointer
+            6. Clean up empty device queues
+
+        Returns:
+            Job index of next message, or None if all queues empty
+
+        Example:
+            With devices ["A", "B", "C"] and last_served="A":
+            - Next check: B (if non-empty, serve from B)
+            - Then: C, then A, then B, ... (circular)
+        """
+        if not self.device_queues:
+            return None
+
+        # Get sorted device list for deterministic round-robin
+        devices = sorted(self.device_queues.keys())
+
+        # Find starting position (next device after last served)
+        # Maintain circular order even when devices are removed
+        start_idx = 0
+        if self.last_served_device is not None:
+            # Find first device that comes after last_served in sorted order
+            for i, dev in enumerate(devices):
+                if dev > self.last_served_device:
+                    start_idx = i
+                    break
+            # If no device comes after (last_served was alphabetically last),
+            # wrap around to start
+
+        # Search circularly for next non-empty device
+        for i in range(len(devices)):
+            idx = (start_idx + i) % len(devices)
+            device_id = devices[idx]
+
+            if self.device_queues[device_id]:
+                # Serve from this device
+                self.last_served_device = device_id
+                job_idx = self.device_queues[device_id].popleft()
+
+                # Clean up empty queues
+                if not self.device_queues[device_id]:
+                    del self.device_queues[device_id]
+
+                return job_idx
+
+        # All queues empty (shouldn't reach here if self.device_queues non-empty)
+        return None
+
+    def peek(self) -> Optional[int]:
+        """
+        View next message without removing it.
+
+        Uses same round-robin logic as dequeue() but doesn't modify state.
+
+        Returns:
+            Job index of next message, or None if all queues empty
+        """
+        if not self.device_queues:
+            return None
+
+        devices = sorted(self.device_queues.keys())
+        start_idx = 0
+        if self.last_served_device is not None:
+            # Find first device that comes after last_served in sorted order
+            for i, dev in enumerate(devices):
+                if dev > self.last_served_device:
+                    start_idx = i
+                    break
+
+        for i in range(len(devices)):
+            idx = (start_idx + i) % len(devices)
+            device_id = devices[idx]
+
+            if self.device_queues[device_id]:
+                return self.device_queues[device_id][0]
+
+        return None
+
+    def is_empty(self) -> bool:
+        """
+        Check if all device queues are empty.
+
+        Returns:
+            True if no messages queued, False otherwise
+        """
+        return len(self.device_queues) == 0
+
+    def queue_length(self) -> int:
+        """
+        Get total number of messages across all devices.
+
+        Returns:
+            Total queued messages
+        """
+        return sum(len(q) for q in self.device_queues.values())
+
+    def device_count(self) -> int:
+        """
+        Get number of active devices (devices with queued messages).
+
+        Returns:
+            Number of devices with non-empty queues
+        """
+        return len(self.device_queues)
+
+    def get_device_queue_lengths(self) -> Dict[str, int]:
+        """
+        Get per-device queue lengths.
+
+        Returns:
+            Dictionary mapping device_id to queue length
+        """
+        return {device_id: len(queue) for device_id, queue in self.device_queues.items()}
+
+    def __repr__(self) -> str:
+        total = self.queue_length()
+        devices = self.device_count()
+        return (
+            f"DeviceFairQueue(total_messages={total}, "
+            f"active_devices={devices}, last_served={self.last_served_device})"
+        )