devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/__init__.py

@@ -0,0 +1,158 @@
+from .gcc import (
+    GCCRepository,
+    GCCIssue,
+    GCC_DIR_NAME,
+    EVENT_LOG_NAME,
+    MAIN_MD_NAME,
+    LOG_MD_NAME,
+    SENSITIVITIES_DIR_NAME,
+    PST_REPORTS_DIR_NAME,
+)
+from .sensitivity import SensitivityEvent, SensitivityStore, DISCLOSURE_LEVELS
+from .theta import AggPhi, RulesBasedAggPhi, ThetaStore, make_theta_store
+from .aggphi_textual import (
+    ConfidenceWeightedAggPhi,
+    TextualModeAggPhi,
+    near_duplicate_pairs,
+    merge_i3_records,
+)
+from .capability import (
+    OmegaCapability,
+    CapabilityStore,
+    CapabilityValidationResult,
+    PSTRunner,
+    PSTReport,
+    L_MAX_DEFAULT,
+    PST_SCORE_THRESHOLD,
+    PST_STATUS_PASSED,
+    PST_STATUS_FAILED,
+    PST_STATUS_NOT_RUN,
+    # S9: A1 round cap
+    check_round_cap,
+    RoundCapResult,
+    T_MAX_MULTIPLIER,
+    CONVERGENCE_TIMEOUT_ROUNDS,
+)
+from .invariants import (
+    InvariantFailure,
+    InvariantContext,
+    InvariantEngine,
+    ConceptStore,
+    check_i1_commit_backed,
+    make_i3_semantic_handshake,
+)
+from .variance import (
+    f_max,
+    VARIANCE_ALERT_EVENT,
+    VarianceReport,
+    VarianceStore,
+    VarianceMonitorResult,
+    variance_calibrate,
+    run_variance_monitor,
+    variance_deterministic_mode_forced,
+    reputation_with_variance_penalty,
+)
+from .rep import REPEnvelope, REPLedger, create_envelope
+from .sis import (
+    SISTCCorpusEntry,
+    SISTCReport,
+    load_sis_tc_corpus,
+    run_sis_tc_eval,
+    QuarantineDecision,
+    quarantine_decision_tree,
+    QuarantineEventStore,
+)
+from .prompt_artifact import PromptArtifactStore
+from .deltaf import DeltaFReport, DeltaFStore, run_deltaf_estimation
+from .rdp import RDPState, RDPAccountant, PRIVACY_BUDGET_EXHAUSTED_EVENT
+from .disclosure import DisclosurePolicy, apply_disclosure_policy, receiver_mandate_private_count
+from .reasoning import ReasoningEntry, ReasoningStore
+
+__all__ = [
+    # GCC core
+    "GCCRepository",
+    "GCCIssue",
+    "GCC_DIR_NAME",
+    "EVENT_LOG_NAME",
+    "MAIN_MD_NAME",
+    "LOG_MD_NAME",
+    "SENSITIVITIES_DIR_NAME",
+    "PST_REPORTS_DIR_NAME",
+    # Sensitivity (S3)
+    "SensitivityEvent",
+    "SensitivityStore",
+    "DISCLOSURE_LEVELS",
+    # Theta / Aggφ (S3 / S8)
+    "AggPhi",
+    "RulesBasedAggPhi",
+    "ThetaStore",
+    "make_theta_store",
+    "ConfidenceWeightedAggPhi",
+    "TextualModeAggPhi",
+    "near_duplicate_pairs",
+    "merge_i3_records",
+    # Capability / PST (S3)
+    "OmegaCapability",
+    "CapabilityStore",
+    "CapabilityValidationResult",
+    "PSTRunner",
+    "PSTReport",
+    "L_MAX_DEFAULT",
+    "PST_SCORE_THRESHOLD",
+    "PST_STATUS_PASSED",
+    "PST_STATUS_FAILED",
+    "PST_STATUS_NOT_RUN",
+    # S9: A1 round cap
+    "check_round_cap",
+    "RoundCapResult",
+    "T_MAX_MULTIPLIER",
+    "CONVERGENCE_TIMEOUT_ROUNDS",
+    # Invariants (S4)
+    "InvariantFailure",
+    "InvariantContext",
+    "InvariantEngine",
+    "ConceptStore",
+    "check_i1_commit_backed",
+    "make_i3_semantic_handshake",
+    # Variance (S4)
+    "f_max",
+    "VARIANCE_ALERT_EVENT",
+    "VarianceReport",
+    "VarianceStore",
+    "VarianceMonitorResult",
+    "variance_calibrate",
+    "run_variance_monitor",
+    "variance_deterministic_mode_forced",
+    "reputation_with_variance_penalty",
+    # REP (S5)
+    "REPEnvelope",
+    "REPLedger",
+    "create_envelope",
+    # SIS (S5)
+    "SISTCCorpusEntry",
+    "SISTCReport",
+    "load_sis_tc_corpus",
+    "run_sis_tc_eval",
+    "QuarantineDecision",
+    "quarantine_decision_tree",
+    "QuarantineEventStore",
+    # Prompt artifact (S5)
+    "PromptArtifactStore",
+    # Deltaf (S5)
+    "DeltaFReport",
+    "DeltaFStore",
+    "run_deltaf_estimation",
+    # RDP (S5)
+    "RDPState",
+    "RDPAccountant",
+    "PRIVACY_BUDGET_EXHAUSTED_EVENT",
+    # Disclosure (S5)
+    "DisclosurePolicy",
+    "apply_disclosure_policy",
+    "receiver_mandate_private_count",
+    # Reasoning (S19)
+    "ReasoningEntry",
+    "ReasoningStore",
+]
+
+

devtorch_core/aggphi_textual.py

@@ -0,0 +1,275 @@
+"""
+Sprint 8 — Textual Mode Aggφ (LLM-assisted + confidence-weighted aggregation).
+
+Provides:
+- :class:`ConfidenceWeightedAggPhi` — deterministic aggregation: recency weighting
+  multiplied by a confidence signal weight (low-confidence events contribute less).
+- :class:`TextualModeAggPhi` — uses confidence-weighted aggregation; optionally
+  refines the per-concept delta via Anthropic when ``DEVTORCH_AGGPHI_LLM=1`` and
+  credentials are available; otherwise identical to the weighted path.
+- :func:`near_duplicate_pairs` — detects near-duplicate concept names for I3
+  handshake (does not merge keys automatically).
+
+Environment
+---------
+DEVTORCH_AGGPHI       — ``rules`` (default) | ``textual`` — select aggregator in
+                        :func:`devtorch_core.theta.make_theta_store`.
+DEVTORCH_AGGPHI_LLM   — ``1``/``true`` to enable optional LLM refinement inside
+                        :class:`TextualModeAggPhi` (falls back on any error).
+DEVTORCH_DISABLE      — if set, LLM refinement is skipped.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from difflib import SequenceMatcher
+from typing import Dict, List, Optional
+
+from .theta import AggPhi
+
+logger = logging.getLogger("devtorch.aggphi_textual")
+
+_LEVEL_RANK: Dict[str, int] = {"PUBLIC": 0, "PROTECTED": 1, "PRIVATE": 2}
+_RANK_LEVEL: Dict[int, str] = {0: "PUBLIC", 1: "PROTECTED", 2: "PRIVATE"}
+
+# ---------------------------------------------------------------------------
+# Near-duplicate detection (I3 handshake candidates)
+# ---------------------------------------------------------------------------
+
+
+def near_duplicate_pairs(
+    concepts: List[str],
+    *,
+    threshold: float = 0.82,
+) -> List[dict]:
+    """
+    Return pairs of concept names whose normalised string similarity is >=
+    *threshold* (SequenceMatcher ratio on lowercased names).
+
+    Each item:
+        ``concept_a``, ``concept_b`` (lexicographic order), ``similarity``,
+        ``requires_i3_handshake``: True
+    """
+    unique = sorted({c for c in concepts if c and str(c).strip()})
+    out: List[dict] = []
+    seen: set[tuple[str, str]] = set()
+    for i, a in enumerate(unique):
+        for b in unique[i + 1 :]:
+            if a == b:
+                continue
+            ratio = SequenceMatcher(None, a.lower(), b.lower()).ratio()
+            if ratio < threshold:
+                continue
+            key = (a, b) if a < b else (b, a)
+            if key in seen:
+                continue
+            seen.add(key)
+            ca, cb = key
+            out.append(
+                {
+                    "concept_a": ca,
+                    "concept_b": cb,
+                    "similarity": round(ratio, 4),
+                    "requires_i3_handshake": True,
+                }
+            )
+    return out
+
+
+def merge_i3_records(existing: List[dict], incoming: List[dict]) -> List[dict]:
+    """Union by unordered pair (concept_a, concept_b); keep highest similarity."""
+    by_pair: dict[tuple[str, str], dict] = {}
+    for row in existing + incoming:
+        a = row.get("concept_a", "")
+        b = row.get("concept_b", "")
+        if not a or not b:
+            continue
+        key = tuple(sorted((a, b)))
+        prev = by_pair.get(key)
+        if prev is None or float(row.get("similarity", 0)) > float(
+            prev.get("similarity", 0)
+        ):
+            by_pair[key] = row
+    return sorted(by_pair.values(), key=lambda r: (-r.get("similarity", 0), r["concept_a"]))
+
+
+# ---------------------------------------------------------------------------
+# Confidence-weighted Aggφ (deterministic)
+# ---------------------------------------------------------------------------
+
+
+class ConfidenceWeightedAggPhi(AggPhi):
+    """
+    Like the rules-based aggregator (group by concept, recency 2×/1×), but each
+    event's contribution is also scaled by ``max(ε, confidence)**exponent`` so
+    inferred/low-confidence signals move Θ less than explicit high-confidence ones.
+    """
+
+    def __init__(self, confidence_exponent: float = 1.5, epsilon: float = 0.05) -> None:
+        self.confidence_exponent = confidence_exponent
+        self.epsilon = epsilon
+
+    def aggregate(self, events: List[dict]) -> Dict[str, dict]:
+        grouped: Dict[str, List[dict]] = {}
+        for ev in events:
+            concept = ev.get("target_concept", "unknown")
+            grouped.setdefault(concept, []).append(ev)
+
+        result: Dict[str, dict] = {}
+        for concept, group in grouped.items():
+            sorted_group = sorted(
+                group,
+                key=lambda e: e.get("created_at", ""),
+                reverse=True,
+            )
+            total_w = 0.0
+            weighted_conf_sum = 0.0
+            max_rank = 0
+
+            for i, ev in enumerate(sorted_group):
+                recency_w = 2.0 if i == 0 else 1.0
+                conf = float(ev.get("confidence", 0.5))
+                sig = max(self.epsilon, conf) ** self.confidence_exponent
+                w = recency_w * sig
+                weighted_conf_sum += conf * w
+                total_w += w
+
+                rank = _LEVEL_RANK.get(ev.get("disclosure_level", "PUBLIC"), 0)
+                if rank > max_rank:
+                    max_rank = rank
+
+            mean_conf = weighted_conf_sum / total_w if total_w else 0.0
+            result[concept] = {
+                "mean_confidence": round(mean_conf, 6),
+                "disclosure_level": _RANK_LEVEL[max_rank],
+                "event_count": len(group),
+            }
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Optional LLM refinement (structured JSON)
+# ---------------------------------------------------------------------------
+
+_LLM_JSON_RE = re.compile(r"\{[\s\S]*\}")
+
+
+def _try_llm_synthesize_delta(events: List[dict]) -> Optional[Dict[str, dict]]:
+    """
+    Ask the model to emit a JSON object mapping concept -> {mean_confidence,
+    disclosure_level, event_count}. Returns None if unavailable or invalid.
+    """
+    if os.environ.get("DEVTORCH_DISABLE", "").strip().lower() in ("1", "true", "yes"):
+        return None
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        return None
+    try:
+        import anthropic  # noqa: PLC0415
+    except ImportError:
+        return None
+
+    payload = json.dumps(events, indent=2, sort_keys=True)[:12000]
+    prompt = (
+        "You are a governance engine aggregating sensitivity events into a "
+        "coordination vector Θ. Given the JSON list of events below, output "
+        "**only** a single JSON object (no markdown) whose keys are "
+        "target_concept strings and values are objects with:\n"
+        '  "mean_confidence": float in [0,1],\n'
+        '  "disclosure_level": one of PUBLIC, PROTECTED, PRIVATE,\n'
+        '  "event_count": positive integer (count of events merged into that concept).\n'
+        "Aggregate semantically: same meaning under different wording should map "
+        "to one concept key when obvious; otherwise keep distinct keys.\n\n"
+        f"EVENTS:\n{payload}"
+    )
+
+    try:
+        client = anthropic.Anthropic()
+        resp = client.messages.create(
+            model=os.environ.get("DEVTORCH_AGGPHI_MODEL", "claude-3-5-haiku-20241022"),
+            max_tokens=4096,
+            temperature=0.0,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        raw = resp.content[0].text
+    except Exception as exc:
+        logger.warning("devtorch Aggφ LLM call failed — %s", exc)
+        return None
+
+    m = _LLM_JSON_RE.search(raw)
+    if not m:
+        logger.warning("devtorch Aggφ LLM: no JSON object in response")
+        return None
+    try:
+        obj = json.loads(m.group(0))
+    except json.JSONDecodeError as exc:
+        logger.warning("devtorch Aggφ LLM: JSON parse error — %s", exc)
+        return None
+
+    if not isinstance(obj, dict):
+        return None
+
+    out: Dict[str, dict] = {}
+    for concept, entry in obj.items():
+        if not isinstance(concept, str) or not isinstance(entry, dict):
+            continue
+        try:
+            mc = float(entry.get("mean_confidence", 0.0))
+            dl = str(entry.get("disclosure_level", "PUBLIC")).upper()
+            ec = int(entry.get("event_count", 1))
+        except (TypeError, ValueError):
+            continue
+        if dl not in _LEVEL_RANK:
+            dl = "PUBLIC"
+        mc = max(0.0, min(1.0, mc))
+        ec = max(1, ec)
+        out[concept] = {
+            "mean_confidence": round(mc, 6),
+            "disclosure_level": dl,
+            "event_count": ec,
+        }
+
+    return out if out else None
+
+
+# ---------------------------------------------------------------------------
+# Textual Mode Aggφ (S8 facade)
+# ---------------------------------------------------------------------------
+
+
+class TextualModeAggPhi(AggPhi):
+    """
+    Sprint 8 default: confidence-weighted aggregation, optional LLM refinement,
+    and I3 near-duplicate tracking (via :class:`ThetaStore` when this class is used
+    as the aggregator).
+    """
+
+    records_i3_merge_candidates = True
+    similarity_threshold = 0.82
+
+    def __init__(
+        self,
+        *,
+        inner: Optional[ConfidenceWeightedAggPhi] = None,
+        use_llm: Optional[bool] = None,
+    ) -> None:
+        self._inner = inner if inner is not None else ConfidenceWeightedAggPhi()
+        self._use_llm = use_llm
+
+    def aggregate(self, events: List[dict]) -> Dict[str, dict]:
+        use_llm = self._use_llm
+        if use_llm is None:
+            use_llm = os.environ.get("DEVTORCH_AGGPHI_LLM", "").strip().lower() in (
+                "1",
+                "true",
+                "yes",
+            )
+
+        if use_llm:
+            llm_delta = _try_llm_synthesize_delta(events)
+            if llm_delta is not None:
+                return llm_delta
+
+        return self._inner.aggregate(events)

devtorch_core/alerts/__init__.py

@@ -0,0 +1,23 @@
+from .base import AlertEnvelope, AlertSeverity, DeliveryResult
+from .config import AlertConfig, load_config
+from .dispatcher import dispatch_alert, dispatch_from_event
+from .slack import SlackChannel
+from .teams import MicrosoftTeamsChannel
+from .jira import JiraChannel
+from .linear import LinearChannel
+from .pagerduty import PagerDutyChannel
+
+__all__ = [
+    "AlertEnvelope",
+    "AlertSeverity",
+    "DeliveryResult",
+    "AlertConfig",
+    "dispatch_alert",
+    "dispatch_from_event",
+    "load_config",
+    "SlackChannel",
+    "MicrosoftTeamsChannel",
+    "JiraChannel",
+    "LinearChannel",
+    "PagerDutyChannel",
+]

devtorch_core/alerts/base.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class AlertSeverity(Enum):
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+@dataclass
+class AlertEnvelope:
+    event_type: str          # e.g. "VARIANCE_ALERT"
+    severity: AlertSeverity
+    title: str
+    body: str                # markdown-safe text
+    branch: str
+    commit_id: str
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class DeliveryResult:
+    channel: str             # "slack", "jira", "pagerduty"
+    success: bool
+    error: str = ""
+    response_code: int = 0
+
+
+class AlertChannel:
+    """Base class for alert channels."""
+    channel_name: str = "base"
+
+    def deliver(self, envelope: AlertEnvelope) -> DeliveryResult:
+        raise NotImplementedError
+
+
+def event_to_severity(event_type: str) -> AlertSeverity:
+    """Map GCC event types to alert severity."""
+    critical = {"PRIVACY_BUDGET_EXHAUSTED", "CAPABILITY_DEGRADED"}
+    warning = {"VARIANCE_ALERT", "CONSENSUS_LOCKED"}
+    if event_type in critical:
+        return AlertSeverity.CRITICAL
+    elif event_type in warning:
+        return AlertSeverity.WARNING
+    return AlertSeverity.INFO

devtorch_core/alerts/config.py

@@ -0,0 +1,60 @@
+import os
+from dataclasses import dataclass
+
+from .base import AlertSeverity
+
+
+@dataclass
+class AlertConfig:
+    slack_webhook_url: str = ""         # DEVTORCH_SLACK_WEBHOOK_URL
+    teams_webhook_url: str = ""         # DEVTORCH_TEAMS_WEBHOOK_URL
+    jira_url: str = ""                  # DEVTORCH_JIRA_URL
+    jira_project_key: str = ""          # DEVTORCH_JIRA_PROJECT_KEY
+    jira_api_token: str = ""            # DEVTORCH_JIRA_API_TOKEN
+    jira_email: str = ""                # DEVTORCH_JIRA_EMAIL
+    linear_api_token: str = ""          # DEVTORCH_LINEAR_API_TOKEN
+    linear_team_id: str = ""            # DEVTORCH_LINEAR_TEAM_ID
+    pagerduty_routing_key: str = ""     # DEVTORCH_PAGERDUTY_ROUTING_KEY
+    min_severity: AlertSeverity = AlertSeverity.WARNING  # DEVTORCH_ALERT_MIN_SEVERITY
+
+
+def load_config() -> AlertConfig:
+    """Load from environment variables. Never raises."""
+    try:
+        raw_severity = os.environ.get("DEVTORCH_ALERT_MIN_SEVERITY", "warning").lower()
+        severity_map = {
+            "info": AlertSeverity.INFO,
+            "warning": AlertSeverity.WARNING,
+            "critical": AlertSeverity.CRITICAL,
+        }
+        min_severity = severity_map.get(raw_severity, AlertSeverity.WARNING)
+
+        return AlertConfig(
+            slack_webhook_url=os.environ.get("DEVTORCH_SLACK_WEBHOOK_URL", ""),
+            teams_webhook_url=os.environ.get("DEVTORCH_TEAMS_WEBHOOK_URL", ""),
+            jira_url=os.environ.get("DEVTORCH_JIRA_URL", ""),
+            jira_project_key=os.environ.get("DEVTORCH_JIRA_PROJECT_KEY", ""),
+            jira_api_token=os.environ.get("DEVTORCH_JIRA_API_TOKEN", ""),
+            jira_email=os.environ.get("DEVTORCH_JIRA_EMAIL", ""),
+            linear_api_token=os.environ.get("DEVTORCH_LINEAR_API_TOKEN", ""),
+            linear_team_id=os.environ.get("DEVTORCH_LINEAR_TEAM_ID", ""),
+            pagerduty_routing_key=os.environ.get("DEVTORCH_PAGERDUTY_ROUTING_KEY", ""),
+            min_severity=min_severity,
+        )
+    except Exception:
+        return AlertConfig()
+
+
+def is_channel_configured(config: AlertConfig, channel: str) -> bool:
+    """Returns True if the channel has enough config to attempt delivery."""
+    if channel == "slack":
+        return bool(config.slack_webhook_url)
+    if channel == "teams":
+        return bool(config.teams_webhook_url)
+    if channel == "jira":
+        return bool(config.jira_url and config.jira_project_key and config.jira_api_token)
+    if channel == "linear":
+        return bool(config.linear_api_token and config.linear_team_id)
+    if channel == "pagerduty":
+        return bool(config.pagerduty_routing_key)
+    return False

devtorch_core/alerts/dispatcher.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from .base import AlertChannel, AlertEnvelope, AlertSeverity, DeliveryResult, event_to_severity
+from .config import AlertConfig, load_config
+from .jira import JiraChannel
+from .linear import LinearChannel
+from .pagerduty import PagerDutyChannel
+from .slack import SlackChannel
+from .teams import MicrosoftTeamsChannel
+
+# Severity ordering for threshold filtering
+_SEVERITY_ORDER = {
+    AlertSeverity.INFO: 0,
+    AlertSeverity.WARNING: 1,
+    AlertSeverity.CRITICAL: 2,
+}
+
+
+def build_channels(config: AlertConfig) -> list[AlertChannel]:
+    """Build the list of configured channels from config."""
+    channels: list[AlertChannel] = []
+    if config.slack_webhook_url:
+        channels.append(SlackChannel(config.slack_webhook_url))
+    if config.teams_webhook_url:
+        channels.append(MicrosoftTeamsChannel(config.teams_webhook_url))
+    if config.jira_url and config.jira_project_key and config.jira_api_token:
+        channels.append(
+            JiraChannel(
+                url=config.jira_url,
+                project_key=config.jira_project_key,
+                api_token=config.jira_api_token,
+                email=config.jira_email,
+            )
+        )
+    if config.linear_api_token and config.linear_team_id:
+        channels.append(LinearChannel(config.linear_api_token, config.linear_team_id))
+    if config.pagerduty_routing_key:
+        channels.append(PagerDutyChannel(config.pagerduty_routing_key))
+    return channels
+
+
+def dispatch_alert(
+    envelope: AlertEnvelope,
+    config: AlertConfig | None = None,
+) -> list[DeliveryResult]:
+    """
+    Route an alert envelope to all configured channels.
+    Filters by min_severity. Returns delivery results for all channels.
+    Never raises.
+    """
+    try:
+        if config is None:
+            config = load_config()
+
+        # Filter: skip if envelope severity is below the configured minimum
+        if _SEVERITY_ORDER.get(envelope.severity, 0) < _SEVERITY_ORDER.get(config.min_severity, 0):
+            return []
+
+        channels = build_channels(config)
+        results: list[DeliveryResult] = []
+        for channel in channels:
+            try:
+                result = channel.deliver(envelope)
+                results.append(result)
+            except Exception as exc:
+                results.append(
+                    DeliveryResult(
+                        channel=channel.channel_name,
+                        success=False,
+                        error=str(exc),
+                    )
+                )
+        return results
+    except Exception:
+        return []
+
+
+def dispatch_from_event(
+    event_type: str,
+    branch: str,
+    commit_id: str,
+    metadata: dict | None = None,
+    config: AlertConfig | None = None,
+) -> list[DeliveryResult]:
+    """
+    Convenience function: build an AlertEnvelope from a GCC event type
+    and dispatch to all channels. Returns [] if no channels configured.
+    """
+    try:
+        if config is None:
+            config = load_config()
+
+        severity = event_to_severity(event_type)
+        title = f"{event_type} on {branch}"
+        body = (
+            f"DevTorch governance event `{event_type}` was triggered on branch `{branch}` "
+            f"at commit `{commit_id}`."
+        )
+        envelope = AlertEnvelope(
+            event_type=event_type,
+            severity=severity,
+            title=title,
+            body=body,
+            branch=branch,
+            commit_id=commit_id,
+            metadata=metadata or {},
+        )
+        return dispatch_alert(envelope, config=config)
+    except Exception:
+        return []