arbiter-engine 0.1.0__py3-none-any.whl

arbiter_engine/history/readiness.py

@@ -0,0 +1,288 @@
+"""
+Axiom Readiness Tracking.
+
+Tracks which axioms are ready to be checked for each entity
+based on available observation history.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from ..interfaces import Entity, ObservationHistory
+from ..types import Axiom, AxiomReadiness, AXIOM_MINIMUMS  # noqa: F401
+
+logger = logging.getLogger(__name__)
+
+
+# Minimum observations required for each axiom.
+#
+# the canonical table moved to ``arbiter_engine/types.py``, beside the
+# enum it keys on. Two of its eight values had drifted from the copies in
+# ``ontology/reasoner.py``; one definition removes the class of bug.
+# Re-exported above so existing ``...readiness import AXIOM_MINIMUMS``
+# imports keep working.
+
+
+class AxiomReadinessTracker:
+    """
+    Track and report axiom readiness across all entities.
+
+    Axiom readiness depends on:
+    - Number of historical observations
+    - Time span of observations
+    - Quality of data (no gaps, consistent sampling)
+    """
+
+    def __init__(self, custom_minimums: Optional[Dict[Axiom, int]] = None,
+                 sample_interval_seconds: float = 1.0):
+        self.minimums = AXIOM_MINIMUMS.copy()
+        if custom_minimums:
+            self.minimums.update(custom_minimums)
+
+        # Adjust minimums based on observation sample interval.
+        # Slower-sampling domains need fewer observations (each carries more info).
+        if sample_interval_seconds > 1.0:
+            self.minimums = {
+                axiom: self._get_adjusted_minimum(base, sample_interval_seconds)
+                for axiom, base in self.minimums.items()
+            }
+
+    @staticmethod
+    def _get_adjusted_minimum(base: int, sample_interval: float) -> int:
+        """Adjust axiom minimum based on sample interval.
+
+        Fast sampling (<=1s): use base minimums (K8s standard).
+        Moderate (1-10s): halve minimums (each obs is more informative).
+        Slow (>10s): third of minimums (hardware, network domains).
+        """
+        if sample_interval <= 1.0:
+            return base
+        elif sample_interval <= 10.0:
+            return max(3, base // 2)
+        else:
+            return max(2, base // 3)
+
+    def get_entity_readiness(
+        self,
+        entity: Entity,
+        history: ObservationHistory,
+        properties: Optional[List[str]] = None
+    ) -> Dict[Axiom, AxiomReadiness]:
+        """
+        Get axiom readiness for a single entity.
+
+        Uses per-property observation timestamps to infer actual
+        sample interval instead of relying on the global default. Mixed-rate
+        entities (e.g., temperature at 1s, firmware version at 60s) get
+        per-property adjusted minimums.
+
+        Args:
+            entity: Entity to check
+            history: Observation history
+            properties: Properties to check (all if None)
+
+        Returns:
+            Dict mapping axiom to readiness status
+        """
+        readiness = {}
+
+        # Get observation counts for entity properties
+        max_counts: Dict[Axiom, int] = {axiom: 0 for axiom in Axiom}
+
+        # Properties to check
+        if properties is None:
+            properties = self._extract_property_names(entity)
+
+        # Estimate per-property sample interval from observation history.
+        # Use the interval to apply property-specific adjusted minimums for
+        # mixed-rate entities where different properties sample at different rates.
+        _prop_intervals: Dict[str, float] = {}
+        if hasattr(history, 'get_observation_timestamps'):
+            for prop in (properties or []):
+                try:
+                    timestamps = history.get_observation_timestamps(entity.id, prop, limit=10)
+                    if len(timestamps) >= 2:
+                        deltas = [
+                            (timestamps[i] - timestamps[i - 1]).total_seconds()
+                            for i in range(1, len(timestamps))
+                            if (timestamps[i] - timestamps[i - 1]).total_seconds() > 0
+                        ]
+                        if deltas:
+                            _prop_intervals[prop] = sum(deltas) / len(deltas)
+                except Exception:
+                    pass
+
+        for prop in properties:
+            count = history.get_observation_count(entity.id, prop)
+
+            # Assign count to relevant axioms based on property type
+            value = entity.get_property(prop)
+
+            if isinstance(value, (int, float)):
+                # Numeric: relevant for BOUNDEDNESS, HOMEOSTASIS, and — added
+                # after the KeyError fix exposed it — CONSERVATION and
+                # MONOTONICITY. Both are numeric-series axioms, but neither was
+                # ever assigned a count here, so both sat at 0 and reported
+                # never-ready for every entity. That silently and permanently
+                # downweighted every CONSERVATION/MONOTONICITY problem the
+                # LayeredDetector raised, via _adjust_confidence. Adding the
+                # minimums un-crashed the pass; it did not make the table true.
+                max_counts[Axiom.BOUNDEDNESS] = max(max_counts[Axiom.BOUNDEDNESS], count)
+                max_counts[Axiom.HOMEOSTASIS] = max(max_counts[Axiom.HOMEOSTASIS], count)
+                max_counts[Axiom.CONSERVATION] = max(max_counts[Axiom.CONSERVATION], count)
+                max_counts[Axiom.MONOTONICITY] = max(max_counts[Axiom.MONOTONICITY], count)
+            elif isinstance(value, str):
+                # State: relevant for STABILITY, CONSISTENCY
+                max_counts[Axiom.STABILITY] = max(max_counts[Axiom.STABILITY], count)
+                max_counts[Axiom.CONSISTENCY] = max(max_counts[Axiom.CONSISTENCY], count)
+
+            # All properties count for RESPONSIVENESS
+            max_counts[Axiom.RESPONSIVENESS] = max(max_counts[Axiom.RESPONSIVENESS], count)
+
+        # CONNECTIVITY doesn't need history
+        max_counts[Axiom.CONNECTIVITY] = 1
+
+        # Build readiness report
+        for axiom in Axiom:
+            # Degrade-with-surfacing rather than KeyError: a future axiom added
+            # to the enum without a minimums entry should narrow readiness for
+            # that one axiom, not crash the entire detection pass.
+            if axiom not in self.minimums:
+                logger.warning(
+                    "AxiomReadinessTracker: no minimum configured for %s — "
+                    "treating it as never-ready. Add it to AXIOM_MINIMUMS.",
+                    axiom,
+                )
+            required = self.minimums.get(axiom, 2 ** 31)
+            count = max_counts[axiom]
+            is_ready = count >= required
+            ratio = min(1.0, count / required) if required > 0 else 1.0
+
+            readiness[axiom] = AxiomReadiness(
+                axiom=axiom,
+                entity_id=entity.id,
+                entity_type=entity.type,
+                observations_count=count,
+                required_count=required,
+                is_ready=is_ready,
+                readiness_ratio=ratio,
+            )
+
+        return readiness
+
+    def _extract_property_names(self, entity: Entity) -> List[str]:
+        """Extract all property names from entity."""
+        properties = []
+
+        def extract(props: dict, prefix: str = ''):
+            for key, value in props.items():
+                path = f"{prefix}.{key}" if prefix else key
+                if isinstance(value, dict):
+                    extract(value, path)
+                else:
+                    properties.append(path)
+
+        extract(entity.properties)
+        return properties
+
+    def get_readiness_report(
+        self,
+        entities: List[Entity],
+        history: ObservationHistory
+    ) -> Dict:
+        """
+        Generate system-wide readiness report.
+
+        Returns:
+            Dict with overall readiness statistics
+        """
+        total_by_axiom = {axiom: {'ready': 0, 'not_ready': 0} for axiom in Axiom}
+        entity_reports = {}
+
+        for entity in entities:
+            readiness = self.get_entity_readiness(entity, history)
+            entity_reports[entity.id] = readiness
+
+            for axiom, status in readiness.items():
+                if status.is_ready:
+                    total_by_axiom[axiom]['ready'] += 1
+                else:
+                    total_by_axiom[axiom]['not_ready'] += 1
+
+        # Calculate percentages
+        summary = {}
+        for axiom in Axiom:
+            ready = total_by_axiom[axiom]['ready']
+            not_ready = total_by_axiom[axiom]['not_ready']
+            total = ready + not_ready
+
+            summary[axiom.value] = {
+                'ready_count': ready,
+                'not_ready_count': not_ready,
+                'ready_percentage': (ready / total * 100) if total > 0 else 0,
+                #.get() for the same reason as the per-entity loop: a 9th enum
+                # member added without a minimums entry should narrow the report,
+                # not KeyError the summary. The per-entity path was guarded and
+                # this one was missed — the guard is only as good as its coverage.
+                'minimum_required': self.minimums.get(axiom),
+            }
+
+        return {
+            'entity_count': len(entities),
+            'axiom_summary': summary,
+            'timestamp': datetime.utcnow().isoformat(),
+        }
+
+    def get_warmup_status(
+        self,
+        entities: List[Entity],
+        history: ObservationHistory
+    ) -> Dict[str, Dict[str, Any]]:
+        """Get observable warmup progress per entity per axiom.
+
+        Returns a dict keyed by entity_id with per-axiom warmup progress.
+        Operators can distinguish "healthy" from "still warming up".
+        """
+        status = {}
+        for entity in entities:
+            readiness = self.get_entity_readiness(entity, history)
+            entity_status = {}
+            for axiom, r in readiness.items():
+                entity_status[axiom.value] = {
+                    'is_ready': r.is_ready,
+                    'observations': r.observations_count,
+                    'required': r.required_count,
+                    'progress_pct': min(100, int(
+                        r.observations_count / r.required_count * 100
+                    )) if r.required_count > 0 else 100,
+                }
+            status[entity.id] = entity_status
+        return status
+
+    def adjust_detection_confidence(
+        self,
+        problem: 'Problem',
+        readiness: AxiomReadiness
+    ) -> 'Problem':
+        """
+        Adjust problem confidence based on axiom readiness.
+
+        Problems detected with insufficient history get lower confidence.
+        """
+        if readiness.is_ready:
+            return problem
+
+        # Scale confidence by readiness ratio
+        adjusted_confidence = problem.confidence * readiness.readiness_ratio
+
+        # Update evidence
+        problem.evidence['axiom_readiness'] = {
+            'observations': readiness.observations_count,
+            'required': readiness.required_count,
+            'ratio': readiness.readiness_ratio,
+        }
+        problem.confidence = adjusted_confidence
+        problem.metadata['confidence_adjusted'] = True
+
+        return problem