devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/observability/formatter.py

@@ -0,0 +1,119 @@
+"""
+Markdown and JSON rendering for ObservabilityReport.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from .report import ObservabilityReport, report_to_dict
+
+if TYPE_CHECKING:
+    pass
+
+
+def format_report_markdown(report: ObservabilityReport) -> str:
+    """
+    Render an ObservabilityReport as a Markdown string.
+
+    Sections:
+      # DevTorch Governance Report
+      ## Summary
+      ## Coordination Vector (Top 5 Θ)
+      ## Capability & Variance
+      ## Privacy Budget (RDP)
+    """
+    lines: list[str] = []
+
+    # ---------- Header ----------
+    lines.append("# DevTorch Governance Report")
+    lines.append(
+        f"Generated: {report.generated_at} | "
+        f"Branch: {report.branch} | "
+        f"State: {report.node_state.upper()}"
+    )
+    lines.append("")
+
+    # ---------- Summary table ----------
+    lines.append("## Summary")
+    lines.append("")
+    lines.append("| Metric | Value |")
+    lines.append("|--------|-------|")
+    lines.append(f"| Commits | {report.commit_count} |")
+    lines.append(f"| Sensitivity Events | {report.sensitivity_event_count} |")
+    lines.append(f"| High Disclosure | {report.high_disclosure_count} |")
+    lines.append(f"| Branches | {report.branch_count} |")
+    lines.append(f"| SIS Quarantines | {report.sis_quarantine_count} |")
+    lines.append(f"| GCC Version | {report.gcc_version} |")
+    lines.append("")
+
+    # ---------- Period ----------
+    if report.period is not None:
+        lines.append(f"**Period:** {report.period.period_label}")
+        if report.period.start:
+            lines.append(f"  From: {report.period.start}")
+        if report.period.end:
+            lines.append(f"  To: {report.period.end}")
+        lines.append("")
+
+    # ---------- Theta (Coordination Vector) ----------
+    lines.append("## Coordination Vector (Top 5 Θ)")
+    lines.append("")
+    if report.theta_top_concepts:
+        lines.append("| Concept | Confidence |")
+        lines.append("|---------|------------|")
+        for entry in report.theta_top_concepts:
+            concept = entry.get("concept", "")
+            conf = entry.get("mean_confidence", 0.0)
+            lines.append(f"| {concept} | {conf:.4f} |")
+    else:
+        lines.append("_No coordination vector data available._")
+    lines.append("")
+
+    # ---------- Capability & Variance ----------
+    lines.append("## Capability & Variance")
+    lines.append("")
+
+    cap = report.capability_state
+    textual_allowed = cap.get("textual_mode_allowed", False)
+    lipschitz = cap.get("lipschitz_bound")
+    lipschitz_str = f"{lipschitz:.4f}" if lipschitz is not None else "N/A"
+    lines.append(f"- **Textual Mode Allowed:** {'Yes' if textual_allowed else 'No'}")
+    lines.append(f"- **Lipschitz Bound (L̂):** {lipschitz_str}")
+    lines.append("")
+
+    var = report.variance_state
+    f_max_val = var.get("f_max")
+    f_max_str = str(f_max_val) if f_max_val is not None else "N/A"
+    det_mode = var.get("deterministic_mode", False)
+    alert_count = var.get("alert_count", 0)
+    lines.append(f"- **f_max:** {f_max_str}")
+    lines.append(f"- **Variance Alert Count:** {alert_count}")
+    lines.append(f"- **Deterministic Mode:** {'Yes' if det_mode else 'No'}")
+    lines.append("")
+
+    # ---------- Privacy Budget (RDP) ----------
+    lines.append("## Privacy Budget (RDP)")
+    lines.append("")
+    rdp = report.rdp_budget
+    eps_used = float(rdp.get("epsilon_used", 0.0))
+    eps_max = float(rdp.get("epsilon_max", 1.0))
+    read_only = bool(rdp.get("read_only", False))
+
+    if eps_max > 0:
+        pct = (eps_used / eps_max) * 100.0
+        pct_str = f"{pct:.1f}%"
+    else:
+        pct_str = "N/A"
+
+    lines.append(f"ε used: {eps_used:.4f} / {eps_max:.4f} ({pct_str})")
+    lines.append(f"- **Read-only mode:** {'Yes' if read_only else 'No'}")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def format_report_json(report: ObservabilityReport) -> str:
+    """Render an ObservabilityReport as a formatted JSON string."""
+    return json.dumps(report_to_dict(report), indent=2)

devtorch_core/observability/report.py

@@ -0,0 +1,264 @@
+"""
+Structured observability report builder.
+
+Reads all .GCC/ state and produces a machine-readable + human-readable
+governance snapshot. Never reads prompts, code content, or raw LLM responses.
+Only reads governance metadata: commits, sensitivities (counts), theta,
+capabilities, variance state, RDP budget, branch refs.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class ReportTimeRange:
+    """Optional time window for filtering report data."""
+    start: str  # ISO timestamp or ""
+    end: str    # ISO timestamp or ""
+    period_label: str  # e.g. "last 7 days"
+
+
+@dataclasses.dataclass
+class ObservabilityReport:
+    """Full governance snapshot built from .GCC/ metadata only."""
+    generated_at: str
+    gcc_version: str
+    node_state: str
+    branch: str
+    commit_count: int
+    sensitivity_event_count: int
+    high_disclosure_count: int
+    theta_top_concepts: List[Dict[str, Any]]  # [{concept: str, mean_confidence: float}]
+    capability_state: Dict[str, Any]          # {textual_mode_allowed: bool, lipschitz_bound: float | None}
+    variance_state: Dict[str, Any]            # {f_max: float | None, alert_count: int, deterministic_mode: bool}
+    rdp_budget: Dict[str, Any]               # {epsilon_used: float, epsilon_max: float, read_only: bool}
+    branch_count: int
+    sis_quarantine_count: int
+    period: Optional[ReportTimeRange] = None
+
+
+# ---------------------------------------------------------------------------
+# Report builder
+# ---------------------------------------------------------------------------
+
+def build_report(gcc_repo: Any, period: Optional[ReportTimeRange] = None) -> ObservabilityReport:
+    """
+    Build an ObservabilityReport from a GCCRepository instance.
+
+    Each section is guarded by try/except so a broken or missing sub-store
+    never prevents the rest of the report from being generated.
+
+    Never reads: prompt content, commit message bodies, code, sensitivity
+    signal text, or any raw LLM response content.
+    """
+    generated_at = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+
+    # --- gcc_version ---
+    try:
+        version_path = gcc_repo.gcc_dir / "VERSION"
+        gcc_version = version_path.read_text(encoding="utf-8").strip() if version_path.exists() else ""
+    except Exception:
+        gcc_version = ""
+
+    # --- node_state ---
+    try:
+        ns_path = gcc_repo.gcc_dir / "NODE_STATE"
+        if ns_path.exists():
+            ns_data = json.loads(ns_path.read_text(encoding="utf-8"))
+            node_state = str(ns_data.get("mode", "unknown"))
+        else:
+            node_state = "unknown"
+    except Exception:
+        node_state = "unknown"
+
+    # --- current branch ---
+    try:
+        head_path = gcc_repo.gcc_dir / "refs" / "HEAD"
+        branch = head_path.read_text(encoding="utf-8").strip() if head_path.exists() else "unknown"
+    except Exception:
+        branch = "unknown"
+
+    # --- commit_count ---
+    try:
+        commits_dir = gcc_repo.gcc_dir / "commits"
+        if commits_dir.exists():
+            commit_count = len(list(commits_dir.glob("*.json")))
+        else:
+            commit_count = 0
+    except Exception:
+        commit_count = 0
+
+    # --- sensitivity counts (metadata only — no signal text) ---
+    sensitivity_event_count = 0
+    high_disclosure_count = 0
+    try:
+        sens_path = gcc_repo.gcc_dir / "sensitivities" / "events.jsonl"
+        if sens_path.exists():
+            with sens_path.open("r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        ev = json.loads(line)
+                        sensitivity_event_count += 1
+                        if ev.get("disclosure_level") == "PRIVATE":
+                            high_disclosure_count += 1
+                    except (json.JSONDecodeError, KeyError):
+                        continue
+    except Exception:
+        pass
+
+    # --- theta top concepts (metadata only — no content) ---
+    theta_top_concepts: List[Dict[str, Any]] = []
+    try:
+        theta_path = gcc_repo.gcc_dir / "theta.json"
+        if theta_path.exists():
+            theta_data = json.loads(theta_path.read_text(encoding="utf-8"))
+            cv: dict = theta_data.get("coordination_vector", {})
+            # Sort by mean_confidence descending, take top 5
+            sorted_concepts = sorted(
+                cv.items(),
+                key=lambda kv: float(kv[1].get("mean_confidence", 0.0)),
+                reverse=True,
+            )
+            for concept, entry in sorted_concepts[:5]:
+                theta_top_concepts.append({
+                    "concept": str(concept),
+                    "mean_confidence": float(entry.get("mean_confidence", 0.0)),
+                })
+    except Exception:
+        pass
+
+    # --- capability_state (A1 gate metadata — no calibration data body) ---
+    capability_state: Dict[str, Any] = {"textual_mode_allowed": False, "lipschitz_bound": None}
+    try:
+        omega_path = gcc_repo.gcc_dir / "capabilities" / "omega.json"
+        if omega_path.exists():
+            omega_data = json.loads(omega_path.read_text(encoding="utf-8"))
+            schema = omega_data.get("schema", "")
+            if schema == "omega-v2.1":
+                capability_state = {
+                    "textual_mode_allowed": bool(omega_data.get("pst_status") == "passed"),
+                    "lipschitz_bound": omega_data.get("lipschitz_bound"),
+                }
+            # else: stub format — leave defaults
+    except Exception:
+        pass
+
+    # --- variance_state ---
+    variance_state: Dict[str, Any] = {"f_max": None, "alert_count": 0, "deterministic_mode": False}
+    try:
+        live_path = gcc_repo.gcc_dir / "variance" / "live_state.json"
+        if live_path.exists():
+            live_data = json.loads(live_path.read_text(encoding="utf-8"))
+            variance_state = {
+                "f_max": live_data.get("last_f_max"),
+                "alert_count": _count_events_of_type(gcc_repo.gcc_dir, "VARIANCE_ALERT"),
+                "deterministic_mode": bool(live_data.get("deterministic_mode_forced", False)),
+            }
+        else:
+            variance_state["alert_count"] = _count_events_of_type(gcc_repo.gcc_dir, "VARIANCE_ALERT")
+    except Exception:
+        pass
+
+    # --- rdp_budget ---
+    rdp_budget: Dict[str, Any] = {"epsilon_used": 0.0, "epsilon_max": 1.0, "read_only": False}
+    try:
+        rdp_path = gcc_repo.gcc_dir / "rdp" / "rdp_state.json"
+        if rdp_path.exists():
+            rdp_data = json.loads(rdp_path.read_text(encoding="utf-8"))
+            rdp_budget = {
+                "epsilon_used": float(rdp_data.get("epsilon_spent", 0.0)),
+                "epsilon_max": float(rdp_data.get("epsilon_budget", 1.0)),
+                "read_only": bool(rdp_data.get("read_only", False)),
+            }
+    except Exception:
+        pass
+
+    # --- branch_count ---
+    try:
+        branches_dir = gcc_repo.gcc_dir / "refs" / "branches"
+        if branches_dir.exists():
+            branch_count = len([f for f in branches_dir.iterdir() if f.is_file()])
+        else:
+            branch_count = 0
+    except Exception:
+        branch_count = 0
+
+    # --- sis_quarantine_count ---
+    sis_quarantine_count = 0
+    try:
+        q_path = gcc_repo.gcc_dir / "sis" / "quarantine_events.jsonl"
+        if q_path.exists():
+            with q_path.open("r", encoding="utf-8") as f:
+                for line in f:
+                    if line.strip():
+                        sis_quarantine_count += 1
+    except Exception:
+        pass
+
+    return ObservabilityReport(
+        generated_at=generated_at,
+        gcc_version=gcc_version,
+        node_state=node_state,
+        branch=branch,
+        commit_count=commit_count,
+        sensitivity_event_count=sensitivity_event_count,
+        high_disclosure_count=high_disclosure_count,
+        theta_top_concepts=theta_top_concepts,
+        capability_state=capability_state,
+        variance_state=variance_state,
+        rdp_budget=rdp_budget,
+        branch_count=branch_count,
+        sis_quarantine_count=sis_quarantine_count,
+        period=period,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Serialisation
+# ---------------------------------------------------------------------------
+
+def report_to_dict(report: ObservabilityReport) -> dict:
+    """Convert ObservabilityReport to a JSON-serializable dict."""
+    d = dataclasses.asdict(report)
+    # period is a nested dataclass — already handled by asdict; may be None
+    return d
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _count_events_of_type(gcc_dir: Path, event_type: str) -> int:
+    """Count events of a specific type in the event log. Metadata only."""
+    count = 0
+    try:
+        event_log = gcc_dir / "events.log.jsonl"
+        if not event_log.exists():
+            return 0
+        with event_log.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                    if obj.get("event_type") == event_type:
+                        count += 1
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+    return count

devtorch_core/observability/servicenow.py

@@ -0,0 +1,147 @@
+"""
+ServiceNow integration for DevTorch change management.
+
+Creates Change Request records in ServiceNow from observability reports.
+Only includes metadata: DHS score, audit summary, branch, counts, and a link
+placeholder. NEVER includes: prompts, code, reasoning tokens, commit message
+bodies, sensitivity signal text, or LLM response content.
+"""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import json
+import os
+import urllib.request
+import urllib.error
+from typing import Optional
+
+from .report import ObservabilityReport
+from .webhook import WebhookResult
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass
+class ServiceNowConfig:
+    """Configuration for ServiceNow Change Request creation."""
+    instance_url: str
+    username: str
+    password: str
+    timeout_seconds: int = 10
+    enabled: bool = True
+
+
+# ---------------------------------------------------------------------------
+# Config loader
+# ---------------------------------------------------------------------------
+
+def load_servicenow_config() -> Optional[ServiceNowConfig]:
+    """
+    Load ServiceNow configuration from environment variables.
+
+    Environment variables:
+      - DEVTORCH_SERVICENOW_INSTANCE (required)
+      - DEVTORCH_SERVICENOW_USERNAME (required)
+      - DEVTORCH_SERVICENOW_PASSWORD (required)
+
+    Returns None if required variables are missing.
+    Never raises.
+    """
+    try:
+        instance_url = os.environ.get("DEVTORCH_SERVICENOW_INSTANCE", "").strip()
+        username = os.environ.get("DEVTORCH_SERVICENOW_USERNAME", "").strip()
+        password = os.environ.get("DEVTORCH_SERVICENOW_PASSWORD", "").strip()
+        if not instance_url or not username or not password:
+            return None
+        return ServiceNowConfig(
+            instance_url=instance_url,
+            username=username,
+            password=password,
+        )
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Change record builder
+# ---------------------------------------------------------------------------
+
+def build_change_record(report: ObservabilityReport, developer_id: str) -> dict:
+    """
+    Build a ServiceNow Change Request record from an ObservabilityReport.
+
+    The record includes metadata only: DHS score, audit summary, branch, and
+    a link placeholder. No prompt, code, or reasoning content is included.
+    """
+    sensitivity_total = max(report.sensitivity_event_count, 1)
+    dhs_score = 1.0 - (report.high_disclosure_count / sensitivity_total)
+
+    # Generate a short, human-readable audit summary.
+    audit_summary = (
+        f"DevTorch governance report for branch {report.branch}. "
+        f"Commits: {report.commit_count}, sensitivity events: {report.sensitivity_event_count}, "
+        f"high disclosure: {report.high_disclosure_count}, quarantines: {report.sis_quarantine_count}. "
+        f"DHS score: {dhs_score:.4f}."
+    )
+
+    audit_url = f"https://audit.devtorch.example/{developer_id}/{report.branch}"
+
+    return {
+        "description": audit_summary,
+        "short_description": f"DevTorch governance review: {report.branch}",
+        "u_devtorch_dhs": round(dhs_score, 4),
+        "u_devtorch_audit_url": audit_url,
+        "requested_by": developer_id,
+        "category": "Software",
+        "priority": "3",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Sender
+# ---------------------------------------------------------------------------
+
+def create_servicenow_change(record: dict, config: ServiceNowConfig) -> WebhookResult:
+    """
+    POST a Change Request record to ServiceNow REST API.
+
+    Endpoint: /api/now/table/change_request
+    Auth: Basic auth with config.username / config.password
+
+    Uses urllib.request — no external dependencies.
+    Never raises — returns WebhookResult with success=False on any error.
+    """
+    if not config.enabled:
+        return WebhookResult(success=False, status_code=0, error="ServiceNow export is disabled")
+
+    try:
+        base_url = config.instance_url.rstrip("/")
+        url = f"{base_url}/api/now/table/change_request"
+
+        body_bytes = json.dumps(record).encode("utf-8")
+        credentials = base64.b64encode(f"{config.username}:{config.password}".encode("utf-8")).decode("utf-8")
+
+        req = urllib.request.Request(
+            url=url,
+            data=body_bytes,
+            method="POST",
+            headers={
+                "Authorization": f"Basic {credentials}",
+                "Content-Type": "application/json",
+            },
+        )
+
+        with urllib.request.urlopen(req, timeout=config.timeout_seconds) as resp:
+            status_code = resp.status
+            return WebhookResult(success=True, status_code=status_code, error="")
+
+    except urllib.error.HTTPError as exc:
+        return WebhookResult(success=False, status_code=exc.code, error=str(exc))
+    except urllib.error.URLError as exc:
+        return WebhookResult(success=False, status_code=0, error=str(exc))
+    except Exception as exc:
+        return WebhookResult(success=False, status_code=0, error=str(exc))