agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/integrations/nexus_adapter.py

@@ -0,0 +1,108 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Nexus Integration Stub — Trust Scoring for Ring Assignment.
+
+Provides the interface for integrating an external trust/reputation
+engine with the Hypervisor. Supply your own scorer implementation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Protocol
+
+
+class NexusTrustScorer(Protocol):
+    """Protocol for a trust scoring backend."""
+
+    def calculate_trust_score(
+        self,
+        verification_level: str,
+        history: Any,
+        capabilities: dict | None = None,
+        privacy: dict | None = None,
+    ) -> Any: ...
+
+    def slash_reputation(
+        self,
+        agent_did: str,
+        reason: str,
+        severity: str,
+        evidence_hash: str | None = None,
+        trace_id: str | None = None,
+        broadcast: bool = True,
+    ) -> Any: ...
+
+    def record_task_outcome(
+        self,
+        agent_did: str,
+        outcome: str,
+    ) -> Any: ...
+
+
+@dataclass
+class NexusScoreResult:
+    """Result of a trust score lookup."""
+
+    agent_did: str
+    raw_nexus_score: int
+    normalized_sigma: float
+    tier: str
+    resolved_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+class NexusAdapter:
+    """Stub adapter for trust scoring integration.
+
+    Provides a default sigma of 0.50 when no scorer is configured.
+    """
+
+    def __init__(
+        self,
+        scorer: NexusTrustScorer | None = None,
+        cache_ttl_seconds: int = 300,
+    ) -> None:
+        self._scorer = scorer
+        self._cache: dict[str, NexusScoreResult] = {}
+        self._cache_ttl = cache_ttl_seconds
+
+    def resolve_sigma(
+        self,
+        agent_did: str,
+        verification_level: str = "standard",
+        history: Any | None = None,
+        capabilities: dict | None = None,
+    ) -> float:
+        """Resolve an agent's sigma. Returns 0.50 default when no scorer is configured."""
+        if self._scorer is None:
+            return 0.50
+        score = self._scorer.calculate_trust_score(
+            verification_level=verification_level,
+            history=history,
+            capabilities=capabilities,
+        )
+        raw_score = getattr(score, "total_score", 500)
+        return raw_score / 1000.0
+
+    def report_slash(
+        self,
+        agent_did: str,
+        reason: str,
+        severity: str = "medium",
+        evidence_hash: str | None = None,
+    ) -> None:
+        """Report a penalty event to the trust backend."""
+        if self._scorer:
+            self._scorer.slash_reputation(
+                agent_did=agent_did,
+                reason=reason,
+                severity=severity,
+                evidence_hash=evidence_hash,
+            )
+
+    def report_task_outcome(self, agent_did: str, outcome: str) -> None:
+        """Report a task outcome for reputation tracking."""
+        if self._scorer:
+            self._scorer.record_task_outcome(agent_did, outcome)

hypervisor/integrations/verification_adapter.py

@@ -0,0 +1,122 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Verification Integration Stub — Behavioral Verification adapter.
+
+Provides the interface for integrating a behavioral verification
+system with the Hypervisor. Supply your own verifier implementation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any, Protocol
+
+
+class VerificationBackend(Protocol):
+    """Protocol for a behavioral verification backend."""
+
+    def verify_embeddings(
+        self,
+        embedding_a: Any,
+        embedding_b: Any,
+        metric: str = "cosine",
+        weights: Any = None,
+        threshold_profile: str | None = None,
+        explain: bool = False,
+    ) -> Any: ...
+
+
+class DriftSeverity(str, Enum):
+    NONE = "none"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@dataclass
+class DriftCheckResult:
+    """Result of a behavioral verification check."""
+
+    agent_did: str
+    session_id: str
+    drift_score: float
+    severity: DriftSeverity
+    passed: bool
+    explanation: str | None = None
+    action_id: str | None = None
+    checked_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    @property
+    def should_slash(self) -> bool:
+        return self.severity in (DriftSeverity.HIGH, DriftSeverity.CRITICAL)
+
+    @property
+    def should_demote(self) -> bool:
+        return self.severity == DriftSeverity.MEDIUM
+
+
+@dataclass
+class DriftThresholds:
+    low: float = 0.15
+    medium: float = 0.30
+    high: float = 0.50
+    critical: float = 0.75
+
+
+class VerificationAdapter:
+    """Stub adapter for behavioral verification integration."""
+
+    def __init__(
+        self,
+        verifier: VerificationBackend | None = None,
+        thresholds: DriftThresholds | None = None,
+        on_drift_detected: Callable[[DriftCheckResult], None] | None = None,
+    ) -> None:
+        self._verifier = verifier
+        self.thresholds = thresholds or DriftThresholds()
+        self._on_drift_detected = on_drift_detected
+        self._check_history: list[DriftCheckResult] = []
+
+    def check_behavioral_drift(
+        self,
+        agent_did: str,
+        session_id: str,
+        claimed_embedding: Any,
+        observed_embedding: Any,
+        action_id: str | None = None,
+        metric: str = "cosine",
+        threshold_profile: str | None = None,
+    ) -> DriftCheckResult:
+        """Check for behavioral drift. Returns a pass-through result when no verifier is configured."""
+        result = DriftCheckResult(
+            agent_did=agent_did,
+            session_id=session_id,
+            drift_score=0.0,
+            severity=DriftSeverity.NONE,
+            passed=True,
+            action_id=action_id,
+        )
+        self._check_history.append(result)
+        return result
+
+    def get_agent_drift_history(self, agent_did: str, session_id: str | None = None) -> list[DriftCheckResult]:
+        return [r for r in self._check_history if r.agent_did == agent_did and (session_id is None or r.session_id == session_id)]
+
+    def get_drift_rate(self, agent_did: str, session_id: str | None = None) -> float:
+        history = self.get_agent_drift_history(agent_did, session_id)
+        if not history:
+            return 0.0
+        return sum(1 for r in history if not r.passed) / len(history)
+
+    @property
+    def total_checks(self) -> int:
+        return len(self._check_history)
+
+    @property
+    def total_violations(self) -> int:
+        return sum(1 for r in self._check_history if not r.passed)

hypervisor/liability/__init__.py

@@ -0,0 +1,142 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Liability Matrix — simple event log for sponsor→sponsored agent relationships.
+
+Public Preview: graph operations are retained for API compatibility
+but sponsorship/penalty/quarantine are stubs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class LiabilityEdge:
+    """An edge in the liability graph."""
+
+    voucher_did: str
+    vouchee_did: str
+    bonded_amount: float
+    vouch_id: str
+
+
+class LiabilityMatrix:
+    """
+    Directed graph tracking sponsor→sponsored agent bonds within a session.
+
+    Provides query APIs for exposure analysis and cascade detection.
+    """
+
+    def __init__(self, session_id: str) -> None:
+        self.session_id = session_id
+        self._edges: list[LiabilityEdge] = []
+
+    def add_edge(
+        self,
+        voucher_did: str,
+        vouchee_did: str,
+        bonded_amount: float,
+        vouch_id: str,
+    ) -> LiabilityEdge:
+        """Record a sponsorship relationship."""
+        edge = LiabilityEdge(
+            voucher_did=voucher_did,
+            vouchee_did=vouchee_did,
+            bonded_amount=bonded_amount,
+            vouch_id=vouch_id,
+        )
+        self._edges.append(edge)
+        return edge
+
+    def remove_edge(self, vouch_id: str) -> None:
+        """Remove a sponsorship relationship by sponsor ID."""
+        self._edges = [e for e in self._edges if e.vouch_id != vouch_id]
+
+    def who_vouches_for(self, agent_did: str) -> list[LiabilityEdge]:
+        """Get all sponsors for a given agent."""
+        return [e for e in self._edges if e.vouchee_did == agent_did]
+
+    def who_is_vouched_by(self, agent_did: str) -> list[LiabilityEdge]:
+        """Get all sponsored agents of a given sponsor."""
+        return [e for e in self._edges if e.voucher_did == agent_did]
+
+    def total_exposure(self, voucher_did: str) -> float:
+        """Total σ bonded by a sponsor across all sponsored agents."""
+        return sum(e.bonded_amount for e in self._edges if e.voucher_did == voucher_did)
+
+    def cascade_path(self, agent_did: str, max_depth: int = 2) -> list[list[str]]:
+        """
+        Find cascade paths from an agent through the liability graph.
+
+        Returns all paths where penalty agent_did would cascade to others.
+        """
+        paths: list[list[str]] = []
+        self._dfs_cascade(agent_did, [agent_did], paths, max_depth)
+        return paths
+
+    def has_cycle(self) -> bool:
+        """Check if the liability graph contains any cycles."""
+        all_nodes = set()
+        for e in self._edges:
+            all_nodes.add(e.voucher_did)
+            all_nodes.add(e.vouchee_did)
+
+        visited: set[str] = set()
+        in_stack: set[str] = set()
+
+        for node in all_nodes:
+            if node not in visited:
+                if self._dfs_cycle(node, visited, in_stack):
+                    return True
+        return False
+
+    def clear(self) -> None:
+        """Release all bonds (session termination)."""
+        self._edges.clear()
+
+    @property
+    def edges(self) -> list[LiabilityEdge]:
+        return list(self._edges)
+
+    def _dfs_cascade(
+        self,
+        current: str,
+        path: list[str],
+        paths: list[list[str]],
+        max_depth: int,
+    ) -> None:
+        if len(path) > max_depth + 1:
+            return
+        vouchees = self.who_is_vouched_by(current)
+        if not vouchees and len(path) > 1:
+            paths.append(list(path))
+            return
+        for edge in vouchees:
+            if edge.vouchee_did not in path:
+                path.append(edge.vouchee_did)
+                self._dfs_cascade(edge.vouchee_did, path, paths, max_depth)
+                path.pop()
+        if not vouchees:
+            return
+        if len(path) > 1:
+            paths.append(list(path))
+
+    def _dfs_cycle(
+        self, node: str, visited: set[str], in_stack: set[str]
+    ) -> bool:
+        visited.add(node)
+        in_stack.add(node)
+        for edge in self._edges:
+            if edge.voucher_did == node:
+                neighbor = edge.vouchee_did
+                if neighbor in in_stack:
+                    return True
+                if neighbor not in visited:
+                    if self._dfs_cycle(neighbor, visited, in_stack):
+                        return True
+        in_stack.discard(node)
+        return False

hypervisor/liability/attribution.py

@@ -0,0 +1,86 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Fault Logging — stub implementation.
+
+Public Preview: assigns full liability to the direct-cause agent.
+No causal chain analysis.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+
+@dataclass
+class FaultAttribution:
+    """Fault attribution for an agent."""
+
+    agent_did: str
+    liability_score: float
+    causal_contribution: float
+    is_direct_cause: bool = False
+    reason: str = ""
+
+
+@dataclass
+class AttributionResult:
+    """Attribution result for a saga failure."""
+
+    attribution_id: str = field(default_factory=lambda: f"attr:{uuid.uuid4().hex[:8]}")
+    saga_id: str = ""
+    session_id: str = ""
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    attributions: list[FaultAttribution] = field(default_factory=list)
+    causal_chain_length: int = 0
+    root_cause_agent: str | None = None
+
+    @property
+    def agents_involved(self) -> list[str]:
+        return [a.agent_did for a in self.attributions]
+
+    def get_liability(self, agent_did: str) -> float:
+        for a in self.attributions:
+            if a.agent_did == agent_did:
+                return a.liability_score
+        return 0.0
+
+
+class CausalAttributor:
+    """Simple fault attribution — assigns liability to the direct cause agent."""
+
+    def __init__(self) -> None:
+        self._history: list[AttributionResult] = []
+
+    def attribute(
+        self,
+        saga_id: str,
+        session_id: str,
+        agent_actions: dict[str, list[dict]],
+        failure_step_id: str,
+        failure_agent_did: str,
+        risk_weights: dict[str, float] | None = None,
+    ) -> AttributionResult:
+        """Assign full liability to the direct-cause agent."""
+        attributions = []
+        for agent_did in agent_actions:
+            attributions.append(FaultAttribution(
+                agent_did=agent_did,
+                liability_score=1.0 if agent_did == failure_agent_did else 0.0,
+                causal_contribution=1.0 if agent_did == failure_agent_did else 0.0,
+                is_direct_cause=(agent_did == failure_agent_did),
+                reason="Direct cause" if agent_did == failure_agent_did else "",
+            ))
+        result = AttributionResult(
+            saga_id=saga_id, session_id=session_id,
+            attributions=attributions, root_cause_agent=failure_agent_did,
+        )
+        self._history.append(result)
+        return result
+
+    @property
+    def attribution_history(self) -> list[AttributionResult]:
+        return list(self._history)

hypervisor/liability/ledger.py

@@ -0,0 +1,121 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Liability Ledger — simple append-only fault log.
+
+Public Preview: records fault events as (agent, type, timestamp, details).
+No risk scoring, no admission decisions.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+
+
+class LedgerEntryType(str, Enum):
+    """Types of liability ledger entries."""
+
+    VOUCH_GIVEN = "vouch_given"
+    VOUCH_RECEIVED = "vouch_received"
+    VOUCH_RELEASED = "vouch_released"
+    SLASH_RECEIVED = "slash_received"
+    SLASH_CASCADED = "slash_cascaded"
+    QUARANTINE_ENTERED = "quarantine_entered"
+    QUARANTINE_RELEASED = "quarantine_released"
+    FAULT_ATTRIBUTED = "fault_attributed"
+    CLEAN_SESSION = "clean_session"
+
+
+@dataclass
+class LedgerEntry:
+    """A single entry in the liability ledger."""
+
+    entry_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    agent_did: str = ""
+    entry_type: LedgerEntryType = LedgerEntryType.CLEAN_SESSION
+    session_id: str = ""
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    severity: float = 0.0
+    details: str = ""
+    related_agent: str | None = None
+
+
+@dataclass
+class AgentRiskProfile:
+    """Risk profile for an agent (Public Preview: always admits)."""
+
+    agent_did: str
+    total_entries: int = 0
+    slash_count: int = 0
+    quarantine_count: int = 0
+    clean_session_count: int = 0
+    fault_score_avg: float = 0.0
+    risk_score: float = 0.0
+    recommendation: str = "admit"
+
+
+class LiabilityLedger:
+    """
+    Simple append-only fault log.
+
+    Public Preview: records events for audit trail only.
+    No risk scoring or admission logic.
+    """
+
+    PROBATION_THRESHOLD = 0.3
+    DENY_THRESHOLD = 0.6
+
+    def __init__(self) -> None:
+        self._entries: list[LedgerEntry] = []
+        self._by_agent: dict[str, list[LedgerEntry]] = {}
+
+    def record(
+        self,
+        agent_did: str,
+        entry_type: LedgerEntryType,
+        session_id: str = "",
+        severity: float = 0.0,
+        details: str = "",
+        related_agent: str | None = None,
+    ) -> LedgerEntry:
+        """Record a liability event."""
+        entry = LedgerEntry(
+            agent_did=agent_did,
+            entry_type=entry_type,
+            session_id=session_id,
+            severity=severity,
+            details=details,
+            related_agent=related_agent,
+        )
+        self._entries.append(entry)
+        self._by_agent.setdefault(agent_did, []).append(entry)
+        return entry
+
+    def get_agent_history(self, agent_did: str) -> list[LedgerEntry]:
+        """Get all ledger entries for an agent."""
+        return list(self._by_agent.get(agent_did, []))
+
+    def compute_risk_profile(self, agent_did: str) -> AgentRiskProfile:
+        """Return a basic risk profile (Public Preview: always admits)."""
+        entries = self.get_agent_history(agent_did)
+        return AgentRiskProfile(
+            agent_did=agent_did,
+            total_entries=len(entries),
+            recommendation="admit",
+        )
+
+    def should_admit(self, agent_did: str) -> tuple[bool, str]:
+        """Always admits in Public Preview."""
+        return True, "admit"
+
+    @property
+    def total_entries(self) -> int:
+        return len(self._entries)
+
+    @property
+    def tracked_agents(self) -> list[str]:
+        return list(self._by_agent.keys())

hypervisor/liability/quarantine.py

@@ -0,0 +1,119 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Quarantine Manager — stub implementation.
+
+Public Preview: quarantine is not enforced. Calls return safe defaults.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+
+
+class QuarantineReason(str, Enum):
+    """Why an agent was quarantined."""
+
+    BEHAVIORAL_DRIFT = "behavioral_drift"
+    LIABILITY_VIOLATION = "liability_violation"
+    RING_BREACH = "ring_breach"
+    RATE_LIMIT_EXCEEDED = "rate_limit_exceeded"
+    MANUAL = "manual"
+    CASCADE_SLASH = "cascade_slash"
+
+
+@dataclass
+class QuarantineRecord:
+    """Record of an agent in quarantine."""
+
+    quarantine_id: str = field(default_factory=lambda: f"quar:{uuid.uuid4().hex[:8]}")
+    agent_did: str = ""
+    session_id: str = ""
+    reason: QuarantineReason = QuarantineReason.MANUAL
+    details: str = ""
+    entered_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    expires_at: datetime | None = None
+    released_at: datetime | None = None
+    is_active: bool = True
+    forensic_data: dict = field(default_factory=dict)
+
+    @property
+    def is_expired(self) -> bool:
+        if self.expires_at is None:
+            return False
+        return datetime.now(UTC) > self.expires_at
+
+    @property
+    def duration_seconds(self) -> float:
+        end = self.released_at or datetime.now(UTC)
+        return (end - self.entered_at).total_seconds()
+
+
+class QuarantineManager:
+    """
+    Quarantine stub (Public Preview: no quarantine enforcement).
+    """
+
+    DEFAULT_QUARANTINE_SECONDS = 300
+
+    def __init__(self) -> None:
+        self._quarantines: dict[str, QuarantineRecord] = {}
+
+    def quarantine(
+        self,
+        agent_did: str,
+        session_id: str,
+        reason: QuarantineReason,
+        details: str = "",
+        duration_seconds: int | None = None,
+        forensic_data: dict | None = None,
+    ) -> QuarantineRecord:
+        """Log a quarantine request (Public Preview: no enforcement)."""
+        record = QuarantineRecord(
+            agent_did=agent_did,
+            session_id=session_id,
+            reason=reason,
+            details=details,
+            is_active=False,
+        )
+        self._quarantines[record.quarantine_id] = record
+        return record
+
+    def release(self, agent_did: str, session_id: str) -> QuarantineRecord | None:
+        """No-op in Public Preview."""
+        return None
+
+    def is_quarantined(self, agent_did: str, session_id: str) -> bool:
+        """Always False in Public Preview."""
+        return False
+
+    def get_active_quarantine(
+        self, agent_did: str, session_id: str
+    ) -> QuarantineRecord | None:
+        return None
+
+    def tick(self) -> list[QuarantineRecord]:
+        return []
+
+    def get_history(
+        self, agent_did: str | None = None, session_id: str | None = None
+    ) -> list[QuarantineRecord]:
+        """Get quarantine history, optionally filtered."""
+        records = list(self._quarantines.values())
+        if agent_did:
+            records = [r for r in records if r.agent_did == agent_did]
+        if session_id:
+            records = [r for r in records if r.session_id == session_id]
+        return records
+
+    @property
+    def active_quarantines(self) -> list[QuarantineRecord]:
+        return []
+
+    @property
+    def quarantine_count(self) -> int:
+        return 0