agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/supervisor.py

@@ -0,0 +1,148 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Supervisor Hierarchy — Enforces layered supervision with a deterministic trust root.
+
+Level 0 (root) MUST be a deterministic (non-LLM) trust root.
+Middle levels (1–N) may be agent-based supervisors.
+Escalation always terminates at the trust root.
+
+Example:
+    >>> from agent_os.trust_root import TrustRoot
+    >>> from agent_os.supervisor import SupervisorHierarchy
+    >>> from agent_os.integrations.base import GovernancePolicy
+    >>>
+    >>> root = TrustRoot(policies=[GovernancePolicy()])
+    >>> hierarchy = SupervisorHierarchy(trust_root=root)
+    >>> hierarchy.register_supervisor("trust-root", level=0, is_agent=False)
+    >>> hierarchy.register_supervisor("safety-agent", level=1, is_agent=True)
+    >>> hierarchy.validate_hierarchy()
+    []
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agent_os.trust_root import TrustDecision, TrustRoot
+
+
+@dataclass
+class _Supervisor:
+    """Internal record for a registered supervisor."""
+
+    name: str
+    level: int
+    is_agent: bool = True
+
+
+class SupervisorHierarchy:
+    """Manages the layered supervisor chain with a deterministic trust root.
+
+    Args:
+        trust_root: The deterministic TrustRoot that serves as level-0 authority.
+    """
+
+    def __init__(self, trust_root: TrustRoot) -> None:
+        self.trust_root = trust_root
+        self._supervisors: list[_Supervisor] = []
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register_supervisor(
+        self,
+        name: str,
+        level: int,
+        is_agent: bool = True,
+    ) -> None:
+        """Register a supervisor at a given level.
+
+        Args:
+            name: Unique supervisor name.
+            level: Hierarchy level (0 = root, higher = closer to workers).
+            is_agent: Whether this supervisor is an LLM-based agent.
+        """
+        self._supervisors.append(_Supervisor(name=name, level=level, is_agent=is_agent))
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    def validate_hierarchy(self) -> list[str]:
+        """Check hierarchy rules and return a list of violations (empty = valid).
+
+        Rules:
+        - Level 0 MUST exist and MUST be deterministic (not an LLM agent).
+        - Middle levels (1–N) may be agent-based.
+        - Each level present must have at least one supervisor.
+        """
+        violations: list[str] = []
+
+        level_0 = [s for s in self._supervisors if s.level == 0]
+        if not level_0:
+            violations.append("Level 0 (root) has no registered supervisor")
+        else:
+            for s in level_0:
+                if s.is_agent:
+                    violations.append(
+                        f"Level 0 supervisor '{s.name}' must be deterministic, not an LLM agent"
+                    )
+
+        # Ensure no gaps in levels (every level between 0 and max has a supervisor)
+        if self._supervisors:
+            max_level = max(s.level for s in self._supervisors)
+            for lvl in range(1, max_level + 1):
+                if not any(s.level == lvl for s in self._supervisors):
+                    violations.append(f"Level {lvl} has no registered supervisor")
+
+        return violations
+
+    # ------------------------------------------------------------------
+    # Authority chain & escalation
+    # ------------------------------------------------------------------
+
+    def get_authority_chain(self, action: dict[str, Any]) -> list[str]:
+        """Return the ordered chain of supervisor names that would evaluate *action*.
+
+        The chain goes from the lowest (closest to workers) up to the trust root.
+        """
+        sorted_supervisors = sorted(self._supervisors, key=lambda s: s.level, reverse=True)
+        return [s.name for s in sorted_supervisors]
+
+    def escalate(
+        self,
+        action: dict[str, Any],
+        from_level: int,
+    ) -> TrustDecision:
+        """Escalate *action* up the hierarchy starting above *from_level*.
+
+        Each level is consulted in descending order.  If the action reaches
+        level 0 the trust root makes the **final, non-overridable** decision.
+
+        Args:
+            action: Dict with ``tool`` and ``arguments``.
+            from_level: The level that initiated escalation.
+
+        Returns:
+            TrustDecision from the trust root (always deterministic).
+        """
+        levels_above = sorted(
+            {s.level for s in self._supervisors if s.level < from_level},
+            reverse=True,
+        )
+
+        depth = 0
+        for _level in levels_above:
+            depth += 1
+            if depth > self.trust_root.max_escalation_depth:
+                return TrustDecision(
+                    allowed=False,
+                    reason="Max escalation depth exceeded",
+                    policy_name="escalation_limit",
+                )
+
+        # Final decision always comes from the deterministic trust root
+        return self.trust_root.validate_action(action)

agent_os/task_outcome.py

@@ -0,0 +1,148 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Task outcome recording for RewardEngine trust scoring.
+
+Provides severity-based scoring with diminishing returns and
+time-based recovery for agent trust management.
+
+Example::
+
+    recorder = TaskOutcomeRecorder()
+    recorder.record(agent_id="a1", outcome="success")
+    recorder.record(agent_id="a1", outcome="failure", severity=0.8)
+    score = recorder.get_score("a1")
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TaskOutcome:
+    """A recorded task outcome."""
+
+    agent_id: str
+    outcome: str  # "success" | "failure"
+    severity: float = 0.5
+    timestamp: float = field(default_factory=time.time)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentScoreState:
+    """Running score state for an agent."""
+
+    score: float = 0.7  # Start at neutral-positive
+    total_tasks: int = 0
+    successes: int = 0
+    failures: int = 0
+    last_updated: float = field(default_factory=time.time)
+
+
+class TaskOutcomeRecorder:
+    """Records task outcomes and computes trust scores.
+
+    Features:
+    - Success boost with diminishing returns
+    - Severity-based failure penalties
+    - Time-based recovery (scores drift toward neutral over time)
+    - Per-agent score tracking
+    """
+
+    def __init__(
+        self,
+        success_boost: float = 0.05,
+        failure_base_penalty: float = 0.1,
+        recovery_rate: float = 0.01,
+        recovery_interval_seconds: float = 3600.0,
+        min_score: float = 0.0,
+        max_score: float = 1.0,
+    ) -> None:
+        self.success_boost = success_boost
+        self.failure_base_penalty = failure_base_penalty
+        self.recovery_rate = recovery_rate
+        self.recovery_interval = recovery_interval_seconds
+        self.min_score = min_score
+        self.max_score = max_score
+        self._agents: dict[str, AgentScoreState] = {}
+        self._history: list[TaskOutcome] = []
+
+    def record(
+        self,
+        agent_id: str,
+        outcome: str,
+        severity: float = 0.5,
+        **metadata: Any,
+    ) -> float:
+        """Record a task outcome and return updated score.
+
+        Args:
+            agent_id: The agent identifier.
+            outcome: "success" or "failure".
+            severity: 0.0-1.0, how severe (for failures) or impactful (for successes).
+            **metadata: Additional context.
+
+        Returns:
+            Updated trust score for the agent.
+        """
+        state = self._agents.setdefault(agent_id, AgentScoreState())
+
+        # Apply time-based recovery first
+        self._apply_recovery(state)
+
+        state.total_tasks += 1
+        entry = TaskOutcome(
+            agent_id=agent_id,
+            outcome=outcome,
+            severity=severity,
+            metadata=metadata,
+        )
+        self._history.append(entry)
+
+        if outcome == "success":
+            state.successes += 1
+            # Diminishing returns: boost decreases as score approaches max
+            headroom = self.max_score - state.score
+            boost = self.success_boost * severity * (headroom / self.max_score)
+            state.score = min(self.max_score, state.score + boost)
+        elif outcome == "failure":
+            state.failures += 1
+            penalty = self.failure_base_penalty * severity
+            state.score = max(self.min_score, state.score - penalty)
+
+        state.last_updated = time.time()
+        return state.score
+
+    def get_score(self, agent_id: str) -> float:
+        """Get current trust score for an agent."""
+        state = self._agents.get(agent_id)
+        if state is None:
+            return 0.7  # Default for unknown agents
+        self._apply_recovery(state)
+        return round(state.score, 4)
+
+    def get_stats(self, agent_id: str) -> dict[str, Any]:
+        """Get detailed stats for an agent."""
+        state = self._agents.get(agent_id)
+        if state is None:
+            return {"agent_id": agent_id, "score": 0.7, "total_tasks": 0}
+        return {
+            "agent_id": agent_id,
+            "score": round(state.score, 4),
+            "total_tasks": state.total_tasks,
+            "successes": state.successes,
+            "failures": state.failures,
+            "success_rate": round(state.successes / max(1, state.total_tasks), 3),
+        }
+
+    def _apply_recovery(self, state: AgentScoreState) -> None:
+        """Apply time-based score recovery toward neutral (0.7)."""
+        elapsed = time.time() - state.last_updated
+        intervals = elapsed / self.recovery_interval
+        if intervals > 0 and state.score < 0.7:
+            recovery = self.recovery_rate * intervals
+            state.score = min(0.7, state.score + recovery)
+            state.last_updated = time.time()

agent_os/transparency.py

@@ -0,0 +1,181 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""EU AI Act Art. 13/50 transparency enforcement interceptor.
+
+Ensures AI disclosure is delivered to users before tool execution,
+supporting Art. 50(1) (AI interaction notice), Art. 50(3) (emotion
+recognition notice), and Art. 13 (interpretable output documentation).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class TransparencyLevel(str, Enum):
+    """Disclosure level per EU AI Act risk classification."""
+
+    NONE = "none"
+    BASIC = "basic"
+    ENHANCED = "enhanced"
+    FULL = "full"
+
+
+@dataclass
+class ToolCallRequest:
+    """Minimal shim — real class imported from integrations.base at runtime."""
+
+    tool_name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    call_id: str = ""
+    agent_id: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolCallResult:
+    """Minimal shim — real class imported from integrations.base at runtime."""
+
+    allowed: bool
+    reason: str | None = None
+    modified_arguments: dict[str, Any] | None = None
+    audit_entry: dict[str, Any] | None = None
+
+
+DISCLOSURE_TEXTS = {
+    TransparencyLevel.BASIC: (
+        "You are interacting with an AI system. Outputs are machine-generated "
+        "and may contain errors. (EU AI Act Art. 50(1))"
+    ),
+    TransparencyLevel.ENHANCED: (
+        "You are interacting with a high-risk AI system. Outputs are "
+        "machine-generated, subject to governance policy enforcement, and "
+        "logged for regulatory audit. Interpretability documentation is "
+        "available on request. (EU AI Act Art. 13, Art. 50(1))"
+    ),
+    TransparencyLevel.FULL: (
+        "You are interacting with a high-risk AI system under full "
+        "transparency obligations. All tool calls are policy-governed, "
+        "audited, and subject to human oversight. System accuracy "
+        "declarations and technical documentation are available. "
+        "(EU AI Act Art. 13, Art. 14, Art. 50)"
+    ),
+}
+
+EMOTION_RECOGNITION_NOTICE = (
+    "This system uses emotion recognition technology. You have the right "
+    "to be informed when such processing takes place. (EU AI Act Art. 50(3))"
+)
+
+
+class TransparencyInterceptor:
+    """EU AI Act Art. 13/50 transparency enforcement interceptor.
+
+    Blocks tool execution when required AI disclosure has not been
+    confirmed, and injects disclosure metadata into allowed results.
+
+    Args:
+        default_level: Transparency level applied when none is specified
+            in the request context.
+        require_disclosure_confirmation: If ``True``, tool calls are
+            blocked until ``confirm_disclosure`` is called for the session.
+        emotion_recognition_notice: If ``True``, requires emotion
+            recognition acknowledgement per Art. 50(3).
+    """
+
+    def __init__(
+        self,
+        default_level: TransparencyLevel = TransparencyLevel.BASIC,
+        require_disclosure_confirmation: bool = True,
+        emotion_recognition_notice: bool = False,
+    ) -> None:
+        self.default_level = default_level
+        self.require_disclosure_confirmation = require_disclosure_confirmation
+        self.emotion_recognition_notice = emotion_recognition_notice
+        self._confirmed_sessions: dict[str, float] = {}
+        self._emotion_acknowledged: dict[str, float] = {}
+
+    def intercept(self, request: ToolCallRequest) -> ToolCallResult:
+        """Check transparency requirements before allowing a tool call."""
+        session_id = request.metadata.get("session_id", request.agent_id or "default")
+        level = request.metadata.get("transparency_level", self.default_level)
+        if isinstance(level, str):
+            try:
+                level = TransparencyLevel(level)
+            except ValueError:
+                level = self.default_level
+
+        if level == TransparencyLevel.NONE:
+            return ToolCallResult(allowed=True)
+
+        # Check disclosure confirmation
+        if self.require_disclosure_confirmation:
+            if session_id not in self._confirmed_sessions:
+                logger.warning(
+                    "Blocked %s: AI disclosure not confirmed for session %s",
+                    request.tool_name,
+                    session_id,
+                )
+                return ToolCallResult(
+                    allowed=False,
+                    reason=(
+                        f"AI disclosure must be confirmed before tool execution. "
+                        f"Required level: {level.value}. "
+                        f"Call confirm_disclosure(session_id) first."
+                    ),
+                )
+
+        # Check emotion recognition acknowledgement
+        if self.emotion_recognition_notice:
+            if session_id not in self._emotion_acknowledged:
+                logger.warning(
+                    "Blocked %s: emotion recognition notice not acknowledged for %s",
+                    request.tool_name,
+                    session_id,
+                )
+                return ToolCallResult(
+                    allowed=False,
+                    reason=(
+                        "Emotion recognition notice must be acknowledged "
+                        "before tool execution. (Art. 50(3))"
+                    ),
+                )
+
+        # Inject disclosure metadata
+        disclosure = {
+            "_ai_disclosure": {
+                "level": level.value,
+                "text": self.get_disclosure_text(level),
+                "confirmed_at": self._confirmed_sessions.get(session_id),
+                "emotion_recognition": self.emotion_recognition_notice,
+            }
+        }
+
+        return ToolCallResult(
+            allowed=True,
+            audit_entry=disclosure,
+        )
+
+    def confirm_disclosure(self, session_id: str) -> None:
+        """Mark AI disclosure as confirmed for a session."""
+        self._confirmed_sessions[session_id] = time.time()
+        logger.info("AI disclosure confirmed for session %s", session_id)
+
+    def acknowledge_emotion_recognition(self, session_id: str) -> None:
+        """Mark emotion recognition notice as acknowledged for a session."""
+        self._emotion_acknowledged[session_id] = time.time()
+        logger.info("Emotion recognition notice acknowledged for session %s", session_id)
+
+    def get_disclosure_text(self, level: TransparencyLevel) -> str:
+        """Get standard disclosure text for the given transparency level."""
+        return DISCLOSURE_TEXTS.get(level, DISCLOSURE_TEXTS[TransparencyLevel.BASIC])
+
+    def is_disclosure_confirmed(self, session_id: str) -> bool:
+        """Check if disclosure has been confirmed for a session."""
+        return session_id in self._confirmed_sessions

agent_os/trust_root.py

@@ -0,0 +1,128 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Deterministic Trust Root — Final authority for the supervisor hierarchy.
+
+The trust root is a pure-code (non-LLM) policy checkpoint that sits at
+the top of the supervisor chain.  It evaluates actions using
+GovernancePolicy rules and cannot be overridden by any agent.
+
+Example:
+    >>> from agent_os.trust_root import TrustRoot, TrustDecision
+    >>> from agent_os.integrations.base import GovernancePolicy
+    >>>
+    >>> policy = GovernancePolicy(allowed_tools=["read_file"])
+    >>> root = TrustRoot(policies=[policy])
+    >>> decision = root.validate_action({"tool": "delete_file", "arguments": {}})
+    >>> decision.allowed  # False
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agent_os.integrations.base import GovernancePolicy
+
+
+@dataclass
+class TrustDecision:
+    """Result of a deterministic trust-root evaluation."""
+
+    allowed: bool
+    reason: str
+    policy_name: str
+    deterministic: bool = True
+
+
+class TrustRoot:
+    """Deterministic (non-LLM) policy authority at the top of the supervisor hierarchy.
+
+    The trust root is the FINAL authority — it cannot be overridden by any agent.
+    All evaluations use pure code logic; no model inference is involved.
+
+    Args:
+        policies: List of GovernancePolicy instances to enforce.
+        max_escalation_depth: Maximum supervisor levels before forced rejection.
+    """
+
+    def __init__(
+        self,
+        policies: list[GovernancePolicy],
+        max_escalation_depth: int = 3,
+    ) -> None:
+        if not policies:
+            raise ValueError("TrustRoot requires at least one policy")
+        self.policies = policies
+        self.max_escalation_depth = max_escalation_depth
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def validate_action(self, action: dict[str, Any]) -> TrustDecision:
+        """Deterministic policy check against all registered policies.
+
+        Args:
+            action: Dict with at least ``tool`` (str) and ``arguments`` (dict).
+
+        Returns:
+            TrustDecision indicating whether the action is allowed.
+        """
+        tool = action.get("tool", "")
+        arguments = action.get("arguments", {})
+        args_str = str(arguments)
+
+        for policy in self.policies:
+            # Check allowed tools
+            if policy.allowed_tools and tool not in policy.allowed_tools:
+                return TrustDecision(
+                    allowed=False,
+                    reason=(
+                        f"Tool '{tool}' not in allowed list: {policy.allowed_tools}"
+                    ),
+                    policy_name=policy.name,
+                )
+
+            # Check blocked patterns
+            matched = policy.matches_pattern(args_str)
+            if matched:
+                return TrustDecision(
+                    allowed=False,
+                    reason=f"Blocked pattern '{matched[0]}' detected in arguments",
+                    policy_name=policy.name,
+                )
+
+        return TrustDecision(
+            allowed=True,
+            reason="All policies passed",
+            policy_name="aggregate",
+        )
+
+    def validate_supervisor(self, supervisor_config: dict[str, Any]) -> bool:
+        """Verify a supervisor agent meets trust requirements.
+
+        A supervisor at any level must declare a ``name`` and ``level``.
+        Level-0 supervisors **must not** be agent-based (``is_agent`` must be False).
+
+        Args:
+            supervisor_config: Dict with ``name``, ``level``, and optionally ``is_agent``.
+
+        Returns:
+            True if the supervisor configuration is acceptable.
+        """
+        level = supervisor_config.get("level")
+        is_agent = supervisor_config.get("is_agent", True)
+
+        if level is None or not supervisor_config.get("name"):
+            return False
+
+        # Root level must be deterministic — not an LLM agent
+        if level == 0 and is_agent:
+            return False
+
+        return True
+
+    def is_deterministic(self) -> bool:
+        """Guarantee that this trust root uses only deterministic logic."""
+        return True