triage4 1.0.0__tar.gz

triage4-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laboratory of Emerging Smart Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

triage4-1.0.0/MANIFEST.in

@@ -0,0 +1,20 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+
+# Only ship core package sources
+recursive-include src/triage4 *.py
+
+# Never ship research/benchmark/test trees in sdist
+prune tests
+prune benchmarks
+prune assessment
+prune results
+prune scripts
+prune docs
+prune tmp
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store

triage4-1.0.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: triage4
+Version: 1.0.0
+Summary: TRIAGE/4 core scheduling package for priority-aware IoT message serving
+Author: TRIAGE/4 Contributors
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Provides-Extra: research
+Requires-Dist: matplotlib>=3.7.0; extra == "research"
+Requires-Dist: scipy>=1.10.0; extra == "research"
+Requires-Dist: pandas>=2.0.0; extra == "research"
+Requires-Dist: tqdm>=4.67.1; extra == "research"
+Dynamic: license-file
+
+# triage4
+
+Core TRIAGE/4 scheduling package for priority-aware IoT message serving.
+
+## Package Scope
+
+- Distributable package code lives in `src/triage4`.
+- Research and benchmarking code lives in `assessment/` and is intentionally non-distribution.
+- Compatibility modules under `src/schedulers` and `src/vanilla` support repository workflows and are excluded from wheel packaging.
+
+## Installation
+
+Install core package for runtime use:
+
+```bash
+pip install -e .
+```
+
+Install research dependencies for local assessment/benchmark execution:
+
+```bash
+pip install -e ".[research]"
+```
+
+Install development + research dependencies:
+
+```bash
+pip install -e ".[dev,research]"
+```
+
+## Packaging Guarantees
+
+- Project distribution name: `triage4`
+- Published wheel content: `triage4/*` modules and package metadata only
+- `assessment/`, `tests/`, and benchmark artifacts are not shipped in distribution files

triage4-1.0.0/README.md

@@ -0,0 +1,35 @@
+# triage4
+
+Core TRIAGE/4 scheduling package for priority-aware IoT message serving.
+
+## Package Scope
+
+- Distributable package code lives in `src/triage4`.
+- Research and benchmarking code lives in `assessment/` and is intentionally non-distribution.
+- Compatibility modules under `src/schedulers` and `src/vanilla` support repository workflows and are excluded from wheel packaging.
+
+## Installation
+
+Install core package for runtime use:
+
+```bash
+pip install -e .
+```
+
+Install research dependencies for local assessment/benchmark execution:
+
+```bash
+pip install -e ".[research]"
+```
+
+Install development + research dependencies:
+
+```bash
+pip install -e ".[dev,research]"
+```
+
+## Packaging Guarantees
+
+- Project distribution name: `triage4`
+- Published wheel content: `triage4/*` modules and package metadata only
+- `assessment/`, `tests/`, and benchmark artifacts are not shipped in distribution files

triage4-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "triage4"
+version = "1.0.0"
+description = "TRIAGE/4 core scheduling package for priority-aware IoT message serving"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "TRIAGE/4 Contributors" }
+]
+license = "MIT"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "numpy>=1.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4.0",
+  "pytest-cov>=4.1.0",
+  "black>=23.0.0",
+  "mypy>=1.5.0",
+]
+research = [
+  "matplotlib>=3.7.0",
+  "scipy>=1.10.0",
+  "pandas>=2.0.0",
+  "tqdm>=4.67.1",
+]
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["triage4*"]
+exclude = ["tests*", "benchmarks*", "assessment*"]

triage4-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

triage4-1.0.0/setup.py

@@ -0,0 +1,8 @@
+"""Compatibility shim for legacy setuptools workflows.
+
+Packaging metadata is defined in pyproject.toml.
+"""
+
+from setuptools import setup
+
+setup()

triage4-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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})"
+        )