continuous-intelligence-layer 0.1.0__py3-none-any.whl

rca_engine/incident_report.py

@@ -0,0 +1,162 @@
+"""
+incident_report.py
+------------------
+Generates a human-readable Markdown incident report from an RCAResult.
+
+Includes:
+- Execution metadata
+- Overall status
+- Primary root cause
+- Failure propagation chain (ASCII diagram)
+- Evidence table
+- Contributing factors
+- Recommendations
+- Confidence score
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from graph_builder.models import ExecutionGraph
+from .rca_engine import RCAResult
+
+
+class IncidentReportGenerator:
+    """Generates Markdown incident reports from RCA results."""
+
+    def __init__(self, output_dir: str = "./reports"):
+        self._output_dir = Path(output_dir)
+        self._output_dir.mkdir(parents=True, exist_ok=True)
+
+    def generate(self, rca: RCAResult, graph: ExecutionGraph) -> str:
+        """Generate a Markdown incident report and save it to disk."""
+        report = self._build_report(rca, graph)
+        filepath = self._save(rca.execution_id, report)
+        return filepath
+
+    def _build_report(self, rca: RCAResult, graph: ExecutionGraph) -> str:
+        summary = graph.summary()
+        now     = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+        status_badge = "🔴 FAILED" if rca.overall_status == "FAIL" else (
+                       "🟡 PARTIAL" if rca.overall_status == "PARTIAL" else "🟢 PASSED")
+
+        lines = [
+            f"# Incident Report — Execution `{rca.execution_id}`",
+            "",
+            f"**Generated:** {now}",
+            "",
+            "---",
+            "",
+            "## Overview",
+            "",
+            f"| Field | Value |",
+            f"|---|---|",
+            f"| Execution ID | `{rca.execution_id}` |",
+            f"| Status | {status_badge} |",
+            f"| Total Nodes | {summary['total_nodes']} |",
+            f"| Failed Nodes | {summary['failed_nodes']} |",
+            f"| Total Latency | {summary['total_latency_ms']} ms |",
+            f"| Total Tokens | {summary['total_tokens']} |",
+            f"| RCA Confidence | {rca.confidence * 100:.1f}% |",
+            "",
+            "---",
+            "",
+            "## 🔍 Primary Root Cause",
+            "",
+            f"> **{rca.root_cause}**",
+            "",
+            "---",
+            "",
+        ]
+
+        # Propagation chain
+        if rca.propagation_chain:
+            lines += [
+                "## 🔗 Failure Propagation Chain",
+                "",
+                "```",
+                self._ascii_chain(rca.propagation_chain),
+                "```",
+                "",
+                "---",
+                "",
+            ]
+
+        # Evidence table
+        lines += [
+            "## 🧾 Evidence",
+            "",
+            "| Node | Validator | Status | Reason |",
+            "|---|---|:---:|---|",
+        ]
+        for ev in rca.evidence:
+            status_str = "❌ FAIL" if ev.status == "FAIL" else "✅ PASS"
+            reason = ev.reason.replace("|", "\\|")[:120]
+            lines.append(f"| `{ev.node_name}` | {ev.validator} | {status_str} | {reason} |")
+
+        if not rca.evidence:
+            lines.append("| — | — | — | No failures detected |")
+
+        lines += ["", "---", ""]
+
+        # Contributing factors
+        if rca.contributing_factors:
+            lines += [
+                "## ⚠️ Contributing Factors",
+                "",
+            ]
+            for factor in rca.contributing_factors:
+                lines.append(f"- {factor}")
+            lines += ["", "---", ""]
+
+        # Recommendations
+        lines += [
+            "## ✅ Recommendations",
+            "",
+        ]
+        for i, rec in enumerate(rca.recommendations, 1):
+            lines.append(f"{i}. {rec}")
+        if not rca.recommendations:
+            lines.append("No specific recommendations generated.")
+
+        lines += [
+            "",
+            "---",
+            "",
+            "## 📊 Node Summary",
+            "",
+            "| Node | Type | Status | Latency (ms) | Tokens |",
+            "|---|---|:---:|---:|---:|",
+        ]
+        for node in graph.nodes:
+            n_status = "❌ ERROR" if node.error else "✅ OK"
+            tokens   = node.tokens.total or 0
+            lines.append(
+                f"| `{node.name[:35]}` | {node.node_type} | {n_status} "
+                f"| {node.latency_ms:.1f} | {tokens} |"
+            )
+
+        lines += [
+            "",
+            "---",
+            "",
+            f"*Report generated by AgentOPS Intelligent Layer — confidence: {rca.confidence*100:.1f}%*",
+        ]
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def _ascii_chain(chain: list[str]) -> str:
+        if not chain:
+            return "(empty)"
+        return "\n↓\n".join(chain)
+
+    def _save(self, execution_id: str, content: str) -> str:
+        ts   = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
+        name = f"incident_{execution_id}_{ts}.md"
+        path = self._output_dir / name
+        path.write_text(content, encoding="utf-8")
+        return str(path)

rca_engine/rca_engine.py

@@ -0,0 +1,202 @@
+"""
+rca_engine.py
+-------------
+RCA Engine — Phase 4 Intelligence Layer
+
+Input:
+  - ExecutionGraph (with validation_results attached to every node)
+
+Responsibilities:
+  1. Identify the primary root cause
+  2. Identify contributing factors
+  3. Explain failure propagation (which node failure caused downstream failures)
+  4. Suggest fixes
+  5. Produce confidence scores
+
+Output: RCAResult (structured JSON + evidence list)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from pydantic import BaseModel
+
+from graph_builder.models import ExecutionGraph, ExecutionNode
+from llm_router import LLMRouter
+
+
+def _parse_json(text: str) -> dict:
+    text = re.sub(r"```(?:json)?", "", text).replace("```", "").strip()
+    match = re.search(r"\{.*\}", text, re.DOTALL)
+    if match:
+        return json.loads(match.group())
+    raise ValueError(f"No JSON in LLM response: {text[:400]}")
+
+
+# ── Result model ───────────────────────────────────────────────────────────
+
+class EvidenceItem(BaseModel):
+    node_id:   str
+    node_name: str
+    validator: str
+    status:    str
+    reason:    str
+
+
+class RCAResult(BaseModel):
+    execution_id:        str
+    project_id:          str | None = None
+    overall_status:      str         # "PASS" | "FAIL" | "PARTIAL"
+    root_cause:          str
+    confidence:          float
+    propagation_chain:   list[str]   # node names in order of failure spread
+    contributing_factors: list[str]
+    evidence:            list[EvidenceItem]
+    recommendations:     list[str]
+    raw_llm_analysis:    str = ""
+
+
+# ── Engine ─────────────────────────────────────────────────────────────────
+
+_PROMPT_TEMPLATE = """
+You are an expert AI systems reliability engineer performing Root Cause Analysis (RCA)
+on a failed multi-agent AI system execution.
+
+## Execution Summary
+Execution ID: {execution_id}
+Total Nodes: {total_nodes}
+Failed Nodes: {failed_nodes}
+Total Latency: {total_latency_ms} ms
+Total Tokens: {total_tokens}
+
+## Execution Graph (node hierarchy)
+{graph_structure}
+
+## Validation Failures (Evidence)
+{validation_failures}
+
+## All Validation Results
+{all_validations}
+
+## Your Task
+Perform a thorough Root Cause Analysis.
+
+1. Identify the PRIMARY ROOT CAUSE — what single issue was most responsible for the failure?
+2. Identify CONTRIBUTING FACTORS — secondary issues that amplified the failure.
+3. Explain FAILURE PROPAGATION — how did the root cause cascade through the execution graph?
+4. Provide specific, actionable RECOMMENDATIONS to fix the issues.
+5. Assign a CONFIDENCE SCORE (0.0-1.0) to your analysis.
+
+Consider:
+- Which node failed FIRST chronologically?
+- Did that failure cause downstream nodes to fail?
+- Was the issue in the input, the decision, the execution, or the goal?
+- What could have prevented this?
+
+## Response Format
+Respond ONLY with a valid JSON object. No explanation outside the JSON. No markdown.
+
+{{
+  "overall_status": "PASS" or "FAIL" or "PARTIAL",
+  "root_cause": "<concise primary root cause in 1-2 sentences>",
+  "confidence": <float 0.0-1.0>,
+  "propagation_chain": ["<node_name_1>", "<node_name_2>", ...],
+  "contributing_factors": ["<factor 1>", "<factor 2>", ...],
+  "recommendations": ["<specific fix 1>", "<specific fix 2>", ...]
+}}
+"""
+
+
+class RCAEngine:
+    """Analyzes an ExecutionGraph's validation results and produces an RCA."""
+
+    def __init__(self, router: LLMRouter):
+        self._router = router
+
+    def analyze(self, graph: ExecutionGraph) -> RCAResult:
+        summary = graph.summary()
+
+        # ── Collect evidence ───────────────────────────────────────────────
+        all_evidence: list[EvidenceItem] = []
+        failures: list[EvidenceItem] = []
+        graph_structure_lines = []
+
+        for node in graph.nodes:
+            indent = "  " if node.parent_id else ""
+            graph_structure_lines.append(
+                f"{indent}• [{node.node_type}] {node.name} (id={node.node_id[:8]})"
+            )
+
+            for vr in node.validation_results:
+                if not isinstance(vr, dict):
+                    continue
+                item = EvidenceItem(
+                    node_id   = node.node_id,
+                    node_name = node.name,
+                    validator = vr.get("evaluator", "Unknown"),
+                    status    = vr.get("status", "UNKNOWN"),
+                    reason    = vr.get("reason", "")[:300],
+                )
+                all_evidence.append(item)
+                if vr.get("status") == "FAIL":
+                    failures.append(item)
+
+        # ── Format for LLM ─────────────────────────────────────────────────
+        graph_structure = "\n".join(graph_structure_lines)
+
+        validation_failures_str = (
+            "\n".join(
+                f"- [{f.validator}] Node '{f.node_name}': {f.reason}"
+                for f in failures
+            )
+            if failures else "No failures detected."
+        )
+
+        all_validations_str = json.dumps(
+            {node.node_id: node.validation_results for node in graph.nodes},
+            indent=2, default=str
+        )[:8000]  # cap to avoid huge prompts
+
+        prompt = _PROMPT_TEMPLATE.format(
+            execution_id        = graph.execution_id,
+            total_nodes         = summary["total_nodes"],
+            failed_nodes        = summary["failed_nodes"],
+            total_latency_ms    = summary["total_latency_ms"],
+            total_tokens        = summary["total_tokens"],
+            graph_structure     = graph_structure,
+            validation_failures = validation_failures_str,
+            all_validations     = all_validations_str,
+        )
+
+        # ── Call LLM ──────────────────────────────────────────────────────
+        raw_text = self._router.call(prompt)
+        try:
+            parsed = _parse_json(raw_text)
+        except Exception as exc:
+            parsed = {
+                "overall_status":      "FAIL" if failures else "PASS",
+                "root_cause":          f"RCA LLM parsing failed: {exc}",
+                "confidence":          0.3,
+                "propagation_chain":   [],
+                "contributing_factors": [],
+                "recommendations":     ["Review validation failures manually."],
+            }
+
+        # ── Determine overall status if not provided ───────────────────────
+        overall = parsed.get("overall_status", "FAIL" if failures else "PASS")
+
+        return RCAResult(
+            execution_id         = graph.execution_id,
+            project_id           = graph.project_id,
+            overall_status       = overall,
+            root_cause           = parsed.get("root_cause", "Unknown"),
+            confidence           = float(parsed.get("confidence", 0.5)),
+            propagation_chain    = parsed.get("propagation_chain", []),
+            contributing_factors = parsed.get("contributing_factors", []),
+            evidence             = failures,
+            recommendations      = parsed.get("recommendations", []),
+            raw_llm_analysis     = raw_text,
+        )