nthlayer-workers 1.0.0__py3-none-any.whl

nthlayer_workers/correlate/snapshot/generator.py

@@ -0,0 +1,170 @@
+"""Snapshot generator with token budget, priority tiers, and caching."""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+
+from nthlayer_workers.correlate.snapshot.token import CharDivFourEstimator, TokenEstimator
+from nthlayer_workers.correlate.types import AgentState, CorrelationGroup
+
+
+@dataclass
+class SnapshotBudget:
+    max_tokens: int = 4000
+    reserved_instructions: int = 500
+    reserved_history: int = 500
+
+    @property
+    def available_for_groups(self) -> int:
+        return self.max_tokens - self.reserved_instructions - self.reserved_history
+
+
+class SnapshotGenerator:
+    def __init__(
+        self,
+        budget: SnapshotBudget | None = None,
+        token_estimator: TokenEstimator | None = None,
+        cache_ttl_seconds: int = 900,  # 15 min default
+    ):
+        self._budget = budget or SnapshotBudget()
+        self._estimator = token_estimator or CharDivFourEstimator()
+        self._cache_ttl = cache_ttl_seconds
+        self._cached_hash: str | None = None
+        self._cached_prompt: str | None = None
+        self._cache_time: float = 0.0
+
+    def generate(
+        self,
+        groups: list[CorrelationGroup],
+        state: AgentState = AgentState.WATCHING,
+        service_context: dict | None = None,
+        force_refresh: bool = False,
+    ) -> tuple[str, bool]:
+        """Generate model prompt from correlation groups.
+
+        Returns (model_prompt, cache_hit).
+        If cache_hit is True, model_prompt is the cached prompt.
+        """
+        # Compute content hash
+        content_hash = self._compute_hash(groups)
+
+        # Check cache (skip in INCIDENT mode)
+        if not force_refresh and state != AgentState.INCIDENT:
+            if self._is_cache_valid(content_hash, state):
+                return self._cached_prompt or "", True
+
+        # Sort groups by priority (P0 first)
+        sorted_groups = sorted(groups, key=lambda g: g.priority)
+
+        # Apply token budget
+        included_groups = self._apply_budget(sorted_groups)
+
+        # Assemble prompt
+        prompt = self._assemble_prompt(included_groups, service_context)
+
+        # Update cache
+        self._cached_hash = content_hash
+        self._cached_prompt = prompt
+        self._cache_time = time.monotonic()
+
+        return prompt, False
+
+    def _compute_hash(self, groups: list[CorrelationGroup]) -> str:
+        """SHA256 of stable group content (services, event counts, priority)."""
+        parts = sorted(
+            f"{','.join(sorted(g.services))}:{g.event_count}:{g.priority}"
+            for g in groups
+        )
+        return hashlib.sha256("|".join(parts).encode()).hexdigest()
+
+    def _is_cache_valid(self, content_hash: str, state: AgentState) -> bool:
+        """Check if cached snapshot is still valid."""
+        if self._cached_hash is None:
+            return False
+        if content_hash != self._cached_hash:
+            return False
+        # Check TTL
+        elapsed = time.monotonic() - self._cache_time
+        ttl = {
+            AgentState.WATCHING: 900,
+            AgentState.ALERT: 300,
+            AgentState.INCIDENT: 0,  # never cache
+            AgentState.DEGRADED: 600,
+        }.get(state, self._cache_ttl)
+        return elapsed < ttl
+
+    def _apply_budget(self, sorted_groups: list[CorrelationGroup]) -> list[CorrelationGroup]:
+        """Include groups until token budget exhausted. P0 always included."""
+        included = []
+        tokens_used = 0
+        budget = self._budget.available_for_groups
+
+        for group in sorted_groups:
+            group_text = self._serialize_group(group)
+            group_tokens = self._estimator.estimate(group_text)
+
+            if group.priority == 0:
+                # P0 always included, even over budget
+                included.append(group)
+                tokens_used += group_tokens
+            elif tokens_used + group_tokens <= budget:
+                included.append(group)
+                tokens_used += group_tokens
+            # else: drop (never truncate)
+
+        return included
+
+    def _serialize_group(self, group: CorrelationGroup) -> str:
+        """Serialize a group to text for token counting and prompt inclusion."""
+        lines = [
+            f"## Correlation Group: {group.summary}",
+            f"Priority: P{group.priority}",
+            f"Services: {', '.join(group.services)}",
+            f"Events: {group.event_count}",
+            f"First seen: {group.first_seen}",
+        ]
+
+        if group.change_candidates:
+            lines.append("Change candidates:")
+            for cc in group.change_candidates:
+                proximity_min = cc.temporal_proximity_seconds / 60
+                relation = "same service" if cc.same_service else "dependency"
+                lines.append(
+                    f"  - {cc.change.payload.get('change_type', 'unknown')} on "
+                    f"{cc.affected_service} ({proximity_min:.0f}m ago, {relation})"
+                )
+
+        if group.topology:
+            lines.append(f"Topology: {' -> '.join(group.topology.topology_path)}")
+
+        return "\n".join(lines)
+
+    def _assemble_prompt(
+        self,
+        groups: list[CorrelationGroup],
+        service_context: dict | None,
+    ) -> str:
+        """Assemble the full model prompt."""
+        parts = []
+
+        if not groups:
+            parts.append("No elevated correlation groups detected. System appears healthy.")
+            return "\n\n".join(parts)
+
+        parts.append(f"Analyzing {len(groups)} correlation group(s):\n")
+
+        for group in groups:
+            parts.append(self._serialize_group(group))
+
+        if service_context:
+            parts.append("\nService context:")
+            parts.append(json.dumps(service_context, indent=2))
+
+        return "\n\n".join(parts)
+
+    def invalidate_cache(self) -> None:
+        """Manually invalidate the cache (e.g., on state transition)."""
+        self._cached_hash = None
+        self._cached_prompt = None

nthlayer_workers/correlate/snapshot/model.py

@@ -0,0 +1,177 @@
+"""Model interface — the ZFC judgment boundary.
+
+Used by: the `serve` and `replay` CLI subcommands (continuous snapshot generation).
+See also: reasoning.py which serves the `correlate` subcommand (live triggered).
+"""
+from __future__ import annotations
+
+import json
+import structlog
+from pathlib import Path
+
+from nthlayer_common.prompts import load_prompt
+from nthlayer_workers.correlate.types import CorrelationGroup
+
+_PROMPT_PATH = Path(__file__).parent.parent.parent.parent / "prompts" / "snapshot.yaml"
+
+logger = structlog.get_logger()
+
+
+class ModelInterface:
+    def __init__(self, model: str | None = None, max_tokens: int = 4096):
+        self._model = model  # None → llm_call uses NTHLAYER_MODEL env var
+        self._max_tokens = max_tokens
+
+    async def interpret(
+        self,
+        prompt: str,
+        groups: list[CorrelationGroup],
+        verdict_store=None,
+    ) -> list:
+        """Call model, parse response into verdicts.
+
+        Returns list of Verdict objects (children + parent).
+        If model call fails, returns template-based verdicts with confidence 0.0.
+        """
+        from nthlayer_common.verdicts import create as verdict_create
+
+        try:
+            response = await self._call_model(prompt)
+            assessments = self._parse_response(response, groups)
+        except Exception as e:
+            logger.warning("model_call_failed", error=str(e))
+            return self._create_template_verdicts(groups)
+
+        # Create per-correlation verdicts
+        child_verdicts = []
+        for assessment in assessments:
+            v = verdict_create(
+                subject={
+                    "type": "correlation",
+                    "service": assessment.get("service"),
+                    "ref": assessment.get("group_id", ""),
+                    "summary": assessment.get("summary", ""),
+                },
+                judgment={
+                    "action": assessment.get("action", "flag"),
+                    "confidence": assessment.get("confidence", 0.5),
+                    "reasoning": assessment.get("reasoning", ""),
+                    "tags": assessment.get("tags", []),
+                },
+                producer={"system": "nthlayer-correlate", "model": self._model},
+            )
+            child_verdicts.append(v)
+            if verdict_store:
+                verdict_store.put(v)
+
+        # Create parent snapshot verdict
+        overall_action = "escalate" if any(
+            a.get("action") == "escalate" for a in assessments
+        ) else "flag"
+        overall_confidence = (
+            sum(a.get("confidence", 0.5) for a in assessments) / len(assessments)
+            if assessments else 0.0
+        )
+
+        # Collect state transition tags
+        tags = []
+        for a in assessments:
+            tags.extend(a.get("tags", []))
+
+        parent = verdict_create(
+            subject={
+                "type": "correlation",
+                "service": None,
+                "ref": "snapshot",
+                "summary": f"Snapshot: {len(groups)} group(s), {len(assessments)} assessed",
+            },
+            judgment={
+                "action": overall_action,
+                "confidence": overall_confidence,
+                "reasoning": f"Assessed {len(assessments)} correlation group(s)",
+                "tags": list(set(tags)),
+            },
+            producer={"system": "nthlayer-correlate", "model": self._model},
+        )
+        parent.lineage.children = [v.id for v in child_verdicts]
+        if verdict_store:
+            verdict_store.put(parent)
+
+        return child_verdicts + [parent]
+
+    async def _call_model(self, prompt: str) -> str:
+        """Call the LLM via the shared nthlayer-common wrapper."""
+        import asyncio
+        from nthlayer_common.llm import llm_call
+
+        result = await asyncio.to_thread(
+            llm_call,
+            system=self._build_system_prompt(),
+            user=prompt,
+            model=self._model,
+            max_tokens=self._max_tokens,
+        )
+        return result.text
+
+    def _build_system_prompt(self) -> str:
+        spec = load_prompt(_PROMPT_PATH)
+        return spec.system
+
+    def _parse_response(self, response_text: str, groups: list[CorrelationGroup]) -> list[dict]:
+        """Parse model JSON response."""
+        from nthlayer_common.parsing import clamp, strip_markdown_fences
+
+        text = strip_markdown_fences(response_text)
+        data = json.loads(text)
+        assessments = data.get("assessments", [])
+
+        # Validate actions and clamp confidence before verdict creation
+        valid_actions = {"flag", "escalate", "defer"}
+        for a in assessments:
+            if a.get("action") not in valid_actions:
+                a["action"] = "flag"
+            a["confidence"] = clamp(float(a.get("confidence", 0.5)))
+
+        return assessments
+
+    def _create_template_verdicts(self, groups: list[CorrelationGroup]) -> list:
+        """Degraded mode: template-based verdicts with confidence 0.0."""
+        from nthlayer_common.verdicts import create as verdict_create
+
+        child_verdicts = []
+        for group in groups:
+            v = verdict_create(
+                subject={
+                    "type": "correlation",
+                    "service": group.services[0] if group.services else None,
+                    "ref": group.id,
+                    "summary": group.summary,
+                },
+                judgment={
+                    "action": "flag",
+                    "confidence": 0.0,
+                    "reasoning": "template-based, model unavailable",
+                    "tags": ["degraded"],
+                },
+                producer={"system": "nthlayer-correlate"},
+            )
+            child_verdicts.append(v)
+
+        parent = verdict_create(
+            subject={
+                "type": "correlation",
+                "service": None,
+                "ref": "snapshot-degraded",
+                "summary": f"Degraded snapshot: {len(groups)} group(s), no model assessment",
+            },
+            judgment={
+                "action": "flag",
+                "confidence": 0.0,
+                "reasoning": "template-based, model unavailable",
+                "tags": ["degraded"],
+            },
+            producer={"system": "nthlayer-correlate"},
+        )
+        parent.lineage.children = [v.id for v in child_verdicts]
+
+        return child_verdicts + [parent]

nthlayer_workers/correlate/snapshot/token.py

@@ -0,0 +1,14 @@
+"""Token estimation. Protocol + simple char/4 estimator for Tier 1."""
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class TokenEstimator(Protocol):
+    def estimate(self, text: str) -> int: ...
+
+
+class CharDivFourEstimator:
+    """len(text) // 4 — good enough for Tier 1."""
+    def estimate(self, text: str) -> int:
+        return len(text) // 4

nthlayer_workers/correlate/state.py

@@ -0,0 +1,88 @@
+"""Agent state machine for SitRep."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from nthlayer_workers.correlate.types import AgentState, CorrelationGroup
+
+
+class StateMachine:
+    """Deterministic state machine. Transitions are transport, not judgment."""
+
+    def __init__(self):
+        self.state = AgentState.WATCHING
+        self._alert_start: datetime | None = None
+        self._calm_since: datetime | None = None
+
+    def update(
+        self,
+        groups: list[CorrelationGroup],
+        model_healthy: bool = True,
+    ) -> AgentState:
+        """Evaluate state transition based on correlation output."""
+        now = datetime.now(timezone.utc)
+
+        # Model failure → DEGRADED (from any state except INCIDENT)
+        if not model_healthy and self.state != AgentState.INCIDENT:
+            self.state = AgentState.DEGRADED
+            self._calm_since = None
+            return self.state
+
+        # DEGRADED + model recovery → WATCHING
+        if self.state == AgentState.DEGRADED and model_healthy:
+            self.state = AgentState.WATCHING
+            self._calm_since = now
+            return self.state
+
+        has_p0 = any(g.priority == 0 for g in groups)
+        p1_count = sum(1 for g in groups if g.priority == 1)
+        has_elevated = has_p0 or p1_count >= 2
+
+        if self.state == AgentState.WATCHING:
+            if has_elevated:
+                self.state = AgentState.ALERT
+                self._alert_start = now
+                self._calm_since = None
+        elif self.state == AgentState.ALERT:
+            if has_elevated:
+                self._calm_since = None
+            else:
+                if self._calm_since is None:
+                    self._calm_since = now
+                elif (now - self._calm_since).total_seconds() >= 600:  # 10 min
+                    self.state = AgentState.WATCHING
+                    self._alert_start = None
+                    self._calm_since = None
+
+        return self.state
+
+    def declare_incident(self) -> None:
+        """External incident declaration → INCIDENT."""
+        self.state = AgentState.INCIDENT
+        self._calm_since = None
+
+    def resolve_incident(self) -> None:
+        """Incident resolved → WATCHING."""
+        self.state = AgentState.WATCHING
+        self._alert_start = None
+        self._calm_since = datetime.now(timezone.utc)
+
+    def get_interval(self) -> int:
+        """Snapshot interval in seconds for current state."""
+        intervals = {
+            AgentState.WATCHING: 300,
+            AgentState.ALERT: 60,
+            AgentState.INCIDENT: 30,
+            AgentState.DEGRADED: 120,
+        }
+        return intervals[self.state]
+
+    def get_cache_ttl(self) -> int | None:
+        """Cache TTL in seconds. None = no caching (INCIDENT)."""
+        ttls = {
+            AgentState.WATCHING: 900,  # 15 min
+            AgentState.ALERT: 300,     # 5 min
+            AgentState.INCIDENT: None, # no caching
+            AgentState.DEGRADED: 600,  # 10 min
+        }
+        return ttls[self.state]

nthlayer_workers/correlate/store/__init__.py

@@ -0,0 +1,5 @@
+"""Event storage for SitRep."""
+from nthlayer_workers.correlate.store.protocol import EventStore
+from nthlayer_workers.correlate.store.sqlite import SQLiteEventStore
+
+__all__ = ["EventStore", "SQLiteEventStore"]

nthlayer_workers/correlate/store/protocol.py

@@ -0,0 +1,48 @@
+"""EventStore protocol — the storage contract for SitRep."""
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from nthlayer_workers.correlate.types import EventType, SitRepEvent
+
+
+class EventStore(Protocol):
+    """Protocol defining the storage interface for SitRep events."""
+
+    def insert(self, event: SitRepEvent) -> None: ...
+
+    def insert_batch(self, events: list[SitRepEvent]) -> None: ...
+
+    def get_by_time_window(
+        self,
+        start: str,
+        end: str,
+        *,
+        service: str | None = None,
+        event_type: EventType | None = None,
+        min_severity: float | None = None,
+    ) -> list[SitRepEvent]: ...
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int = 100,
+        time_window: tuple[str, str] | None = None,
+        service: str | None = None,
+    ) -> list[SitRepEvent]: ...
+
+    def get_by_topology(
+        self, service: str, hops: int = 1
+    ) -> list[SitRepEvent]: ...
+
+    def get_recent_changes(
+        self, service: str, window_minutes: int = 30,
+        reference_time: str | None = None,
+    ) -> list[SitRepEvent]: ...
+
+    def expire_old(self) -> int: ...
+
+    def get_state_hash(self, time_window: tuple[str, str]) -> str: ...
+
+    def get_stats(self) -> dict[str, Any]: ...