nthlayer-workers 1.0.0__py3-none-any.whl

nthlayer_workers/observe/gate/policies.py

@@ -0,0 +1,226 @@
+"""Policy condition evaluator.
+
+Parses and evaluates condition strings against a context dictionary.
+Supports a simple DSL for time, SLO, and service-based conditions.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable
+
+from nthlayer_workers.observe.gate.conditions import (
+    is_business_hours,
+    is_freeze_period,
+    is_peak_traffic,
+    is_weekday,
+)
+
+
+@dataclass
+class PolicyContext:
+    """Context for policy evaluation with service and SLO data."""
+
+    budget_remaining: float = 100.0
+    budget_consumed: float = 0.0
+    burn_rate: float = 1.0
+    tier: str = "standard"
+    environment: str = "prod"
+    service: str = ""
+    team: str = ""
+    downstream_count: int = 0
+    high_criticality_downstream: int = 0
+    now: datetime | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for evaluation. Delegates to get_current_context."""
+        from nthlayer_workers.observe.gate.conditions import get_current_context
+
+        ctx = get_current_context(
+            budget_remaining=self.budget_remaining,
+            budget_consumed=self.budget_consumed,
+            burn_rate=self.burn_rate,
+            tier=self.tier,
+            environment=self.environment,
+            downstream_count=self.downstream_count,
+            high_criticality_downstream=self.high_criticality_downstream,
+            now=self.now,
+        )
+        ctx["service"] = self.service
+        ctx["team"] = self.team
+        return ctx
+
+
+@dataclass
+class EvaluationResult:
+    """Result of condition evaluation."""
+
+    condition: str
+    result: bool
+    matched_rule: str | None = None
+    context_snapshot: dict[str, Any] = field(default_factory=dict)
+
+
+class ConditionEvaluator:
+    """Evaluates policy conditions against a context.
+
+    Supports comparisons, boolean operators (AND/OR/NOT), parentheses,
+    and built-in functions (business_hours, freeze_period, etc.).
+    """
+
+    OPERATORS: dict[str, Any] = {
+        "==": lambda a, b: a == b,
+        "!=": lambda a, b: a != b,
+        ">=": lambda a, b: a >= b,
+        "<=": lambda a, b: a <= b,
+        ">": lambda a, b: a > b,
+        "<": lambda a, b: a < b,
+    }
+
+    FUNCTIONS: dict[str, Callable[..., bool]] = {
+        "business_hours": is_business_hours,
+        "weekday": is_weekday,
+        "freeze_period": is_freeze_period,
+        "peak_traffic": is_peak_traffic,
+    }
+
+    def __init__(self, context: PolicyContext | dict[str, Any] | None = None):
+        self._policy_context: PolicyContext | None = None
+        if context is None:
+            self.context: dict[str, Any] = {}
+        elif isinstance(context, PolicyContext):
+            self.context = context.to_dict()
+            self._policy_context = context
+        else:
+            self.context = context
+
+    def evaluate(self, condition: str) -> bool:
+        """Evaluate a condition string. Empty condition = always true."""
+        if not condition or not condition.strip():
+            return True
+
+        condition = " ".join(condition.split())
+
+        try:
+            return self._evaluate_expression(condition)
+        except Exception:
+            return False  # fail safe
+
+    def _evaluate_expression(self, expr: str) -> bool:
+        """Evaluate a boolean expression with AND/OR/NOT."""
+        expr = expr.strip()
+
+        while "(" in expr:
+            match = re.search(r"(?<!\w)\(([^()]+)\)", expr)
+            if match:
+                inner = match.group(1)
+                result = self._evaluate_expression(inner)
+                expr = expr[: match.start()] + str(result) + expr[match.end() :]
+            else:
+                break
+
+        if expr.upper().startswith("NOT "):
+            return not self._evaluate_expression(expr[4:])
+
+        if " OR " in expr.upper():
+            parts = re.split(r"\s+OR\s+", expr, flags=re.IGNORECASE)
+            return any(self._evaluate_expression(p) for p in parts)
+
+        if " AND " in expr.upper():
+            parts = re.split(r"\s+AND\s+", expr, flags=re.IGNORECASE)
+            return all(self._evaluate_expression(p) for p in parts)
+
+        if expr.lower() == "true":
+            return True
+        if expr.lower() == "false":
+            return False
+
+        func_match = re.match(r"(\w+)\((.*)\)", expr)
+        if func_match:
+            return self._evaluate_function(func_match.group(1), func_match.group(2))
+
+        return self._evaluate_comparison(expr)
+
+    def _evaluate_comparison(self, expr: str) -> bool:
+        """Evaluate a comparison like 'hour >= 9'."""
+        for op, func in self.OPERATORS.items():
+            if op in expr:
+                parts = expr.split(op, 1)
+                if len(parts) == 2:
+                    left = self._resolve_value(parts[0].strip())
+                    right = self._resolve_value(parts[1].strip())
+                    return func(left, right)
+
+        value = self._resolve_value(expr)
+        return bool(value)
+
+    def _resolve_value(self, token: str) -> Any:
+        """Resolve a token to its value."""
+        token = token.strip()
+
+        if (token.startswith("'") and token.endswith("'")) or (
+            token.startswith('"') and token.endswith('"')
+        ):
+            return token[1:-1]
+
+        try:
+            if "." in token:
+                return float(token)
+            return int(token)
+        except ValueError:
+            pass
+
+        if token.lower() == "true":
+            return True
+        if token.lower() == "false":
+            return False
+
+        return self.context.get(token, False)
+
+    def _evaluate_function(self, name: str, args_str: str) -> bool:
+        """Evaluate a function call."""
+        name = name.lower()
+
+        if name not in self.FUNCTIONS:
+            return False
+
+        func = self.FUNCTIONS[name]
+
+        args = []
+        if args_str.strip():
+            raw_args = re.split(r",\s*(?=(?:[^']*'[^']*')*[^']*$)", args_str)
+            for arg in raw_args:
+                args.append(self._resolve_value(arg.strip()))
+
+        now = None
+        if self._policy_context:
+            now = self._policy_context.now
+
+        if name == "freeze_period" and len(args) >= 2:
+            return func(args[0], args[1], now=now)
+        elif name in ("business_hours", "weekday", "peak_traffic"):
+            return func(now=now)
+
+        return False
+
+    def evaluate_all(
+        self,
+        conditions: list[dict[str, Any]],
+    ) -> tuple[bool, dict[str, Any] | None]:
+        """Evaluate multiple conditions and return the most restrictive match."""
+        matched = None
+
+        for cond in conditions:
+            when_clause = cond.get("when", "")
+            if self.evaluate(when_clause):
+                if matched is None:
+                    matched = cond
+                else:
+                    curr_block = cond.get("blocking", 0)
+                    prev_block = matched.get("blocking", 0)
+                    if curr_block > prev_block:
+                        matched = cond
+
+        return (matched is not None, matched)

nthlayer_workers/observe/gate_adapter.py

@@ -0,0 +1,40 @@
+"""Read-only assessment store backed by core API.
+
+Used by the deploy gate CLI to read historical assessments from core.
+Synchronous wrapper — safe for CLI use only (no running event loop).
+Gate is CLI-only in v1.5; if gate moves to async (v2), use the
+CoreAPIClient directly instead of this adapter.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from nthlayer_common.api_client import CoreAPIClient
+
+from nthlayer_workers.observe.assessment import Assessment, from_dict
+from nthlayer_workers.observe.store import AssessmentFilter, AssessmentStore
+
+
+class CoreAPIAssessmentStore(AssessmentStore):
+    """Read-only assessment store backed by core API."""
+
+    def __init__(self, client: CoreAPIClient):
+        self._client = client
+
+    def put(self, assessment: Assessment) -> None:
+        raise NotImplementedError("CoreAPIAssessmentStore is read-only")
+
+    def get(self, assessment_id: str) -> Assessment | None:
+        # Not needed by gate; single-assessment lookup not exposed in v1.5.
+        raise NotImplementedError("Single assessment lookup not needed by gate")
+
+    def query(self, criteria: AssessmentFilter) -> list[Assessment]:
+        result = asyncio.run(self._client.get_assessments(
+            service=criteria.service,
+            kind=criteria.kind,
+            limit=criteria.limit if criteria.limit > 0 else 100,
+        ))
+        if not result.ok:
+            return []
+        return [from_dict(d) for d in result.data]

nthlayer_workers/observe/incident.py

@@ -0,0 +1,36 @@
+"""Incident envelope creation for the decision records system.
+
+Observe creates incident envelopes when a breach assessment triggers a respond cycle.
+The incident_id is assigned at trigger time and propagated to all downstream records.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from nthlayer_common.records.models import Incident
+from nthlayer_common.records.sqlite_store import SQLiteDecisionRecordStore
+
+__all__ = ["create_incident_from_breach"]
+
+
+def create_incident_from_breach(
+    store: SQLiteDecisionRecordStore,
+    trigger_hash: str,
+    stream: str,
+) -> Incident:
+    """Create an incident envelope from a breach assessment.
+
+    The incident is written to the store and returned. The caller should use
+    the ``incident.id`` to stamp downstream records (verdicts, evaluations).
+    """
+    incident_id = f"inc-{uuid.uuid4().hex[:12]}"
+    incident = Incident(
+        id=incident_id,
+        created_at=datetime.now(timezone.utc),
+        trigger_hash=trigger_hash,
+        stream=stream,
+    )
+    store.create_incident(incident)
+    return incident

nthlayer_workers/observe/portfolio/__init__.py

@@ -0,0 +1,17 @@
+"""Portfolio health aggregation."""
+
+from nthlayer_workers.observe.portfolio.aggregator import (
+    PortfolioSummary,
+    SLOHealth,
+    ServiceHealth,
+    build_portfolio,
+)
+from nthlayer_workers.observe.portfolio.scorer import score_service
+
+__all__ = [
+    "PortfolioSummary",
+    "SLOHealth",
+    "ServiceHealth",
+    "build_portfolio",
+    "score_service",
+]

nthlayer_workers/observe/portfolio/aggregator.py

@@ -0,0 +1,168 @@
+"""Portfolio aggregation from assessment store or in-memory SLO results."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+from nthlayer_workers.observe.slo.collector import SLOResult
+from nthlayer_workers.observe.store import AssessmentFilter, AssessmentStore
+
+# Status severity order for worst-status calculation
+_STATUS_SEVERITY = {
+    "EXHAUSTED": 4,
+    "CRITICAL": 3,
+    "WARNING": 2,
+    "ERROR": 1,
+    "NO_DATA": 0,
+    "HEALTHY": -1,
+    "UNKNOWN": -2,
+}
+
+
+@dataclass
+class SLOHealth:
+    """Health of a single SLO from assessment data."""
+
+    name: str
+    status: str
+    current_sli: float | None = None
+    objective: float | None = None
+    percent_consumed: float | None = None
+
+
+@dataclass
+class ServiceHealth:
+    """Aggregated health for a service across all its SLOs."""
+
+    service: str
+    slos: list[SLOHealth] = field(default_factory=list)
+    overall_status: str = "UNKNOWN"
+
+    def __post_init__(self) -> None:
+        if self.slos and self.overall_status == "UNKNOWN":
+            self.overall_status = _worst_status([s.status for s in self.slos])
+
+
+@dataclass
+class PortfolioSummary:
+    """Org-level portfolio health aggregated from assessments."""
+
+    services: list[ServiceHealth] = field(default_factory=list)
+    total_services: int = 0
+    healthy_count: int = 0
+    warning_count: int = 0
+    critical_count: int = 0
+    exhausted_count: int = 0
+
+
+def build_portfolio(store: AssessmentStore) -> PortfolioSummary:
+    """Build portfolio summary from recent slo_status assessments.
+
+    Reads the most recent slo_status assessment per service+SLO combination,
+    groups by service, and aggregates health status.
+    """
+    assessments = store.query(
+        AssessmentFilter(kind="slo_status", limit=0)
+    )
+
+    # Group by service, keeping only the latest assessment per service+slo_name
+    latest: dict[str, dict[str, dict]] = defaultdict(dict)
+    for a in assessments:
+        slo_name = a.data.get("slo_name", "unknown")
+        key = slo_name
+        # Assessments are ordered by timestamp desc, so first seen is latest
+        if key not in latest[a.service]:
+            latest[a.service][key] = a.data
+
+    services = []
+    for service_name in sorted(latest):
+        slos = []
+        for slo_name, data in sorted(latest[service_name].items()):
+            slos.append(
+                SLOHealth(
+                    name=slo_name,
+                    status=data.get("status", "UNKNOWN"),
+                    current_sli=data.get("current_sli"),
+                    objective=data.get("objective"),
+                    percent_consumed=data.get("percent_consumed"),
+                )
+            )
+        services.append(ServiceHealth(service=service_name, slos=slos))
+
+    return _summarise_services(services)
+
+
+def build_portfolio_from_results(
+    results_by_service: dict[str, list[SLOResult]],
+) -> PortfolioSummary:
+    """Build portfolio summary from current-cycle SLO results.
+
+    Used by ObserveCollectModule.process_cycle() — receives results
+    in-memory from the collector, no store round-trip. Parallel to
+    build_portfolio(store) which reads from an AssessmentStore.
+    """
+    services = []
+    for service_name in sorted(results_by_service):
+        slos = []
+        for r in results_by_service[service_name]:
+            slos.append(
+                SLOHealth(
+                    name=r.name,
+                    status=r.status,
+                    current_sli=r.current_sli,
+                    objective=r.objective,
+                    percent_consumed=r.percent_consumed,
+                )
+            )
+        services.append(ServiceHealth(service=service_name, slos=slos))
+
+    return _summarise_services(services)
+
+
+def _summarise_services(services: list[ServiceHealth]) -> PortfolioSummary:
+    """Build PortfolioSummary from a list of ServiceHealth objects.
+
+    Shared by build_portfolio (store path) and build_portfolio_from_results
+    (in-memory path). Must stay in sync — single implementation.
+    """
+    status_counts: dict[str, int] = defaultdict(int)
+    for svc in services:
+        bucket = _status_bucket(svc.overall_status)
+        status_counts[bucket] += 1
+
+    return PortfolioSummary(
+        services=services,
+        total_services=len(services),
+        healthy_count=status_counts["healthy"],
+        warning_count=status_counts["warning"],
+        critical_count=status_counts["critical"],
+        exhausted_count=status_counts["exhausted"],
+    )
+
+
+def _worst_status(statuses: list[str]) -> str:
+    """Return the worst status from a list."""
+    if not statuses:
+        return "UNKNOWN"
+    return max(statuses, key=lambda s: _STATUS_SEVERITY.get(s, -2))
+
+
+def _status_bucket(status: str) -> str:
+    """Map a status to a summary bucket.
+
+    UNKNOWN/NO_DATA/ERROR map to "unknown" which is NOT tracked in
+    PortfolioSummary (no unknown_count field). These represent missing
+    information, not active failures — they are silently excluded from
+    the healthy/warning/critical/exhausted counts.
+    """
+    buckets = {
+        "HEALTHY": "healthy",
+        "WARNING": "warning",
+        "CRITICAL": "critical",
+        "EXHAUSTED": "exhausted",
+        "UNKNOWN": "unknown",
+        "NO_DATA": "unknown",
+        "ERROR": "unknown",
+    }
+    return buckets.get(status, "unknown")

nthlayer_workers/observe/portfolio/scorer.py

@@ -0,0 +1,13 @@
+"""Simple reliability scoring from portfolio data."""
+
+from __future__ import annotations
+
+from nthlayer_workers.observe.portfolio.aggregator import ServiceHealth
+
+
+def score_service(health: ServiceHealth) -> float:
+    """Score a service based on its SLO compliance (0-100)."""
+    if not health.slos:
+        return 0.0
+    healthy = sum(1 for s in health.slos if s.status == "HEALTHY")
+    return (healthy / len(health.slos)) * 100

nthlayer_workers/observe/slo/__init__.py

@@ -0,0 +1,19 @@
+"""SLO state collection and storage."""
+
+from nthlayer_workers.observe.slo.collector import (
+    BudgetSummary,
+    SLOMetricCollector,
+    SLOResult,
+    ServiceSLO,
+    results_to_assessments,
+)
+from nthlayer_workers.observe.slo.spec_loader import load_specs
+
+__all__ = [
+    "BudgetSummary",
+    "SLOMetricCollector",
+    "SLOResult",
+    "ServiceSLO",
+    "load_specs",
+    "results_to_assessments",
+]