nthlayer-workers 1.0.0__py3-none-any.whl

nthlayer_workers/respond/agents/investigation.py

@@ -0,0 +1,124 @@
+# src/nthlayer_respond/agents/investigation.py
+"""InvestigationAgent — hypothesis generation and root cause declaration."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from nthlayer_common.prompts import extract_confidence, load_prompt, render_user_prompt
+from nthlayer_workers.respond.agents.base import AgentBase
+from nthlayer_workers.respond.types import (
+    AgentRole,
+    Hypothesis,
+    IncidentContext,
+    InvestigationResult,
+)
+
+_PROMPT_PATH = Path(__file__).parent.parent.parent.parent / "prompts" / "investigation.yaml"
+
+
+class InvestigationAgent(AgentBase):
+    """Form hypotheses about root cause and rank by confidence.
+
+    Judgment SLO: 70% post-incident agreement on declared root causes.
+    Root cause is only declared when confidence exceeds root_cause_threshold.
+    """
+
+    role = AgentRole.INVESTIGATION
+    default_timeout = 60
+
+    # ------------------------------------------------------------------ #
+    # Judgment interface                                                   #
+    # ------------------------------------------------------------------ #
+
+    def build_prompt(self, context: IncidentContext) -> tuple[str, str]:
+        threshold = self._config.get("root_cause_threshold", 0.7)
+
+        spec = load_prompt(_PROMPT_PATH)
+        system = render_user_prompt(spec.system, root_cause_threshold=str(threshold))
+
+        parts: list[str] = []
+
+        # Triage context
+        if context.triage is not None:
+            t = context.triage
+            parts.append("Triage results:")
+            parts.append(f"  severity={t.severity}")
+            parts.append(f"  blast_radius={t.blast_radius}")
+            parts.append(f"  affected_slos={t.affected_slos}")
+
+        # nthlayer-correlate correlation verdicts
+        if context.trigger_verdict_ids:
+            parts.append("\nnthlayer-correlate correlation verdicts:")
+            for vid in context.trigger_verdict_ids:
+                try:
+                    v = self._verdict_store.get(vid)
+                    if v is not None:
+                        parts.append(
+                            f"  - ref={v.subject.ref!r}  "
+                            f"summary={v.subject.summary!r}  "
+                            f"confidence={v.judgment.confidence}  "
+                            f"reasoning={v.judgment.reasoning!r}"
+                        )
+                except Exception:  # noqa: BLE001
+                    pass
+
+        # Service context from OpenSRM spec + evaluation verdict
+        svc_ctx = self._build_service_context_prompt(context)
+        if svc_ctx:
+            parts.append(svc_ctx)
+
+        # Topology
+        # Prune topology to blast radius + 1 hop
+        relevant = context.triage.blast_radius if context.triage else []
+        pruned = self._prune_topology(context.topology, relevant) if relevant else context.topology
+        parts.append(f"\nTopology: {json.dumps(pruned)}")
+
+        user = render_user_prompt(spec.user_template, context="\n".join(parts))
+        return system, user
+
+    def parse_response(
+        self, response: str, context: IncidentContext
+    ) -> InvestigationResult:
+        data = self._parse_json(response)
+        threshold = self._config.get("root_cause_threshold", 0.7)
+
+        # Build hypotheses list — accept both "description" and "hypothesis" field names
+        hypotheses: list[Hypothesis] = []
+        for h in data.get("hypotheses") or []:
+            desc = h.get("description") or h.get("hypothesis") or h.get("summary", "")
+            raw_evidence = h.get("evidence") or []
+            if not raw_evidence and h.get("reasoning"):
+                raw_evidence = [h["reasoning"]]
+            hypotheses.append(
+                Hypothesis(
+                    description=desc,
+                    confidence=float(h.get("confidence", 0.0)),
+                    evidence=list(raw_evidence),
+                    change_candidate=h.get("change_candidate"),
+                )
+            )
+
+        root_cause: str | None = data.get("root_cause")
+        root_cause_confidence: float = float(data.get("root_cause_confidence") or data.get("confidence") or 0.0)
+        reasoning: str = data.get("reasoning", "") or data.get("analysis", "")
+
+        # Mechanical threshold check: clear root_cause if confidence is below threshold
+        if root_cause is not None and root_cause_confidence < threshold:
+            root_cause = None
+
+        confidence = extract_confidence(data)
+
+        return InvestigationResult(
+            hypotheses=hypotheses,
+            root_cause=root_cause,
+            root_cause_confidence=root_cause_confidence,
+            reasoning=reasoning,
+            confidence=confidence,
+        )
+
+    def _apply_result(
+        self, context: IncidentContext, result: InvestigationResult
+    ) -> IncidentContext:
+        context.investigation = result
+        return context

nthlayer_workers/respond/agents/remediation.py

@@ -0,0 +1,219 @@
+# src/nthlayer_respond/agents/remediation.py
+"""RemediationAgent — safe action execution with approval ratchet."""
+from __future__ import annotations
+
+import json
+import structlog
+from pathlib import Path
+
+from nthlayer_common.prompts import extract_confidence, load_prompt, render_user_prompt
+from nthlayer_workers.respond.agents.base import AgentBase
+from nthlayer_workers.respond.safe_actions.registry import SafeActionRegistry
+from nthlayer_workers.respond.types import (
+    AgentRole,
+    IncidentContext,
+    RemediationResult,
+)
+
+_PROMPT_PATH = Path(__file__).parent.parent.parent.parent / "prompts" / "remediation.yaml"
+
+logger = structlog.get_logger(__name__)
+
+
+def _format_safe_actions(policy: dict) -> str:
+    """Format safe action policy as context for the remediation prompt."""
+    lines = ["Available safe actions (you MUST choose from this list):"]
+    for name, spec in policy.items():
+        desc = spec.get("description", "").strip()
+        risk = spec.get("risk", "unknown")
+        approval = "requires approval" if spec.get("requires_approval") else "auto-approved"
+        applicable = spec.get("applicable_to", {})
+        modes = applicable.get("failure_modes", [])
+        lines.append(f"  - {name} ({risk} risk, {approval}): {desc}")
+        if modes:
+            lines.append(f"    Applicable to: {', '.join(modes)}")
+        not_applicable = spec.get("not_applicable_to")
+        if not_applicable:
+            reason = not_applicable.get("reason", "").strip()
+            lines.append(f"    NOT applicable to {not_applicable.get('service_types', [])}: {reason}")
+    return "\n".join(lines)
+
+
+class RemediationAgent(AgentBase):
+    """Suggest and execute pre-approved safe actions.
+
+    Judgment SLO: 80% fix success rate.
+
+    Safety properties:
+    - Only actions in the closed SafeActionRegistry may be proposed.
+    - Approval ratchet: registry.requires_approval=True can never be downgraded by
+      the model.  The model may always escalate (say True when registry says False).
+    - Novel actions (not in registry) are rejected: proposed_action set to None and
+      requires_human_approval forced to True.
+    """
+
+    role = AgentRole.REMEDIATION
+    default_timeout = 30
+
+    def __init__(
+        self,
+        *args,
+        safe_action_registry: SafeActionRegistry,
+        **kwargs,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._registry = safe_action_registry
+
+    # ------------------------------------------------------------------ #
+    # Judgment interface                                                   #
+    # ------------------------------------------------------------------ #
+
+    def build_prompt(self, context: IncidentContext) -> tuple[str, str]:
+        from nthlayer_workers.respond.safe_actions.actions import load_safe_action_policy
+
+        policy = load_safe_action_policy()
+        safe_actions_text = _format_safe_actions(policy)
+
+        spec = load_prompt(_PROMPT_PATH)
+        system = render_user_prompt(spec.system, safe_actions=safe_actions_text)
+
+        parts: list[str] = []
+
+        # Investigation context
+        if context.investigation is not None:
+            inv = context.investigation
+            parts.append("Investigation findings:")
+            if inv.root_cause is not None:
+                parts.append(f"  root_cause={inv.root_cause!r}")
+                parts.append(f"  root_cause_confidence={inv.root_cause_confidence}")
+            if inv.hypotheses:
+                parts.append("  hypotheses:")
+                for h in inv.hypotheses:
+                    parts.append(
+                        f"    - {h.description!r} (confidence={h.confidence}, "
+                        f"change_candidate={h.change_candidate!r})"
+                    )
+
+        # Triage context
+        if context.triage is not None:
+            t = context.triage
+            parts.append("Triage results:")
+            parts.append(f"  severity={t.severity}")
+            parts.append(f"  blast_radius={t.blast_radius}")
+            parts.append(f"  affected_slos={t.affected_slos}")
+
+        # Service context from OpenSRM spec + evaluation verdict
+        svc_ctx = self._build_service_context_prompt(context)
+        if svc_ctx:
+            parts.append(svc_ctx)
+
+        # Topology
+        # Prune topology to blast radius + 1 hop
+        relevant = context.triage.blast_radius if context.triage else []
+        pruned = self._prune_topology(context.topology, relevant) if relevant else context.topology
+        parts.append(f"\nTopology: {json.dumps(pruned)}")
+
+        user = render_user_prompt(spec.user_template, context="\n".join(parts))
+        return system, user
+
+    def parse_response(
+        self, response: str, context: IncidentContext
+    ) -> RemediationResult:
+        data = self._parse_json(response)
+
+        proposed_action: str | None = data.get("proposed_action") or data.get("recommended_action") or data.get("action")
+        target: str | None = data.get("target") or data.get("target_service")
+        risk_assessment: str = data.get("risk_assessment", "") or data.get("risk", "")
+        requires_human_approval: bool = bool(data.get("requires_human_approval", True))
+        autonomy_reduction: dict = data.get("autonomy_reduction") or {}
+        reasoning: str = data.get("reasoning", "") or data.get("rationale", "")
+
+        # Critical validation: reject hallucinated actions
+        if proposed_action is not None:
+            try:
+                registry_action = self._registry.get(proposed_action)
+            except KeyError:
+                logger.warning(
+                    "RemediationAgent: model proposed unknown action %r — rejecting "
+                    "(hallucinated action name). Forcing requires_human_approval=True.",
+                    proposed_action,
+                )
+                proposed_action = None
+                requires_human_approval = True
+                registry_action = None
+            else:
+                # Approval ratchet: registry can only escalate, never downgrade.
+                # If registry says approval required, model cannot override it to False.
+                if registry_action.requires_approval and not requires_human_approval:
+                    requires_human_approval = True
+        else:
+            registry_action = None
+
+        confidence = extract_confidence(data)
+
+        result = RemediationResult(
+            proposed_action=proposed_action,
+            target=target,
+            risk_assessment=risk_assessment,
+            requires_human_approval=requires_human_approval,
+            reasoning=reasoning,
+            confidence=confidence,
+        )
+
+        # Stash autonomy_reduction on the result for use in _post_execute
+        result.autonomy_reduction = autonomy_reduction
+
+        return result
+
+    def _apply_result(
+        self, context: IncidentContext, result: RemediationResult
+    ) -> IncidentContext:
+        context.remediation = result
+        return context
+
+    # ------------------------------------------------------------------ #
+    # Post-execute: safe action + autonomy reduction                      #
+    # ------------------------------------------------------------------ #
+
+    async def _post_execute(
+        self, context: IncidentContext, result: RemediationResult
+    ) -> IncidentContext:
+        """Execute safe action (if approved) then handle autonomy reduction.
+
+        Strict ordering:
+        1. Execute safe action (if not requires_human_approval and action is set)
+        2. Autonomy reduction (if recommended)
+        """
+        # Step 1: Execute safe action
+        if not result.requires_human_approval and result.proposed_action is not None:
+            try:
+                exec_result = await self._registry.execute(
+                    result.proposed_action, result.target, context
+                )
+                result.executed = True
+                result.execution_result = exec_result.get("detail")
+            except Exception as exc:  # noqa: BLE001
+                result.executed = False
+                result.execution_result = str(exc)
+
+        # Step 2: Autonomy reduction (if recommended by model)
+        autonomy_reduction: dict = result.autonomy_reduction or {}
+        if autonomy_reduction.get("recommended"):
+            target_agent: str = autonomy_reduction.get("target_agent", "")
+            arbiter_url: str = self._config.get("arbiter_url", "")
+            reason: str = autonomy_reduction.get("reason", "")
+
+            try:
+                gov_response = await self._request_autonomy_reduction(
+                    target_agent, arbiter_url, reason
+                )
+                result.autonomy_reduced = True
+                result.autonomy_target = target_agent
+                result.previous_autonomy_level = gov_response.get("previous_level")
+                result.new_autonomy_level = gov_response.get("new_level")
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "RemediationAgent: autonomy reduction request failed: %s", exc
+                )
+
+        return context

nthlayer_workers/respond/agents/triage.py

@@ -0,0 +1,132 @@
+# src/nthlayer_respond/agents/triage.py
+"""TriageAgent — first concrete agent in the Mayday pipeline."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from nthlayer_common.prompts import extract_confidence, load_prompt, render_user_prompt
+
+from nthlayer_workers.respond.agents.base import AgentBase
+from nthlayer_workers.respond.types import AgentRole, IncidentContext, TriageResult
+
+_PROMPT_PATH = Path(__file__).parent.parent.parent.parent / "prompts" / "triage.yaml"
+
+
+class TriageAgent(AgentBase):
+    """Assess severity, blast radius, affected SLOs, and team assignment.
+
+    Judgment SLO: severity reversal rate < 10%.
+    """
+
+    role = AgentRole.TRIAGE
+    default_timeout = 15
+
+    # ------------------------------------------------------------------ #
+    # Judgment interface                                                   #
+    # ------------------------------------------------------------------ #
+
+    def build_prompt(self, context: IncidentContext) -> tuple[str, str]:
+        spec = load_prompt(_PROMPT_PATH)
+
+        parts: list[str] = []
+
+        if context.trigger_source == "nthlayer-correlate":
+            parts.append(
+                "You have pre-correlated context from nthlayer-correlate. "
+                "The following correlation verdicts informed this incident:"
+            )
+            for vid in context.trigger_verdict_ids:
+                try:
+                    v = self._verdict_store.get(vid)
+                    if v is not None:
+                        parts.append(
+                            f"  - service={v.subject.service!r}  "
+                            f"summary={v.subject.summary!r}  "
+                            f"confidence={v.judgment.confidence}  "
+                            f"reasoning={v.judgment.reasoning!r}"
+                        )
+                except Exception:  # noqa: BLE001
+                    pass
+        else:
+            parts.append(
+                "No pre-correlation available. Raw alert only. "
+                "Assess based solely on the topology information below."
+            )
+
+        svc_ctx = self._build_service_context_prompt(context)
+        if svc_ctx:
+            parts.append(svc_ctx)
+
+        # Prune topology to trigger service + 1 hop (reduces prompt tokens)
+        trigger_svc = (context.metadata or {}).get("trigger_service", "")
+        pruned = self._prune_topology(context.topology, [trigger_svc]) if trigger_svc else context.topology
+        parts.append(f"\nTopology: {json.dumps(pruned)}")
+
+        user = render_user_prompt(spec.user_template, context="\n".join(parts))
+        return spec.system, user
+
+    def parse_response(self, response: str, context: IncidentContext) -> TriageResult:
+        data = self._parse_json(response)
+
+        raw_severity = data.get("severity", 2)
+        severity = max(0, min(4, int(raw_severity)))
+
+        raw_blast = data.get("blast_radius") or []
+        blast_radius: list[str] = raw_blast if isinstance(raw_blast, list) else [raw_blast] if raw_blast else []
+        affected_slos: list[str] = data.get("affected_slos") or []
+        assigned_team: str | None = data.get("assigned_team") or data.get("team_assignment")
+        reasoning: str = data.get("reasoning", "") or data.get("rationale", "")
+        confidence = extract_confidence(data)
+
+        return TriageResult(
+            severity=severity,
+            blast_radius=blast_radius,
+            affected_slos=affected_slos,
+            assigned_team=assigned_team,
+            reasoning=reasoning,
+            confidence=confidence,
+        )
+
+    def _apply_result(
+        self, context: IncidentContext, result: TriageResult
+    ) -> IncidentContext:
+        context.triage = result
+        return context
+
+    # ------------------------------------------------------------------ #
+    # Post-execute hook: autonomy reduction                               #
+    # ------------------------------------------------------------------ #
+
+    async def _post_execute(
+        self, context: IncidentContext, result: Any
+    ) -> IncidentContext:
+        """Trigger autonomy reduction when a model-update signal is present
+        and severity is low enough that the update may have distorted judgment.
+
+        Condition: any trigger verdict carries tag "agent_model_update"
+        AND result.severity <= 2.
+        """
+        if not (hasattr(result, "severity") and result.severity <= 2):
+            return context
+
+        for vid in context.trigger_verdict_ids:
+            try:
+                v = self._verdict_store.get(vid)
+                tags = (v.judgment.tags or []) if v is not None else []
+                if "agent_model_update" in tags:
+                    arbiter_url: str = self._config.get("arbiter_url", "")
+                    await self._request_autonomy_reduction(
+                        agent_name="triage",
+                        arbiter_url=arbiter_url,
+                        reason=(
+                            f"Trigger verdict {vid} flagged agent_model_update; "
+                            f"incident {context.id} severity={result.severity}"
+                        ),
+                    )
+                    break
+            except Exception:  # noqa: BLE001
+                pass
+
+        return context