agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/providers.py

@@ -0,0 +1,182 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Provider Discovery System
+
+Enables plug-and-play upgrades from Public Preview to Advanced implementations.
+When an advanced provider package is installed (e.g., agent-governance-providers),
+factory functions automatically return the advanced implementation. Otherwise,
+they return the built-in Public Preview.
+
+Usage:
+    from agent_os.providers import get_verification_engine, get_self_correction_kernel
+
+    engine = get_verification_engine()   # Advanced if available, else CE
+    kernel = get_self_correction_kernel() # Advanced if available, else CE
+
+Advanced: pip install agent-governance-providers (from PyPI)
+Community: pip install agent-os-kernel (from PyPI) — works out of the box
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Entry point group names — internal packages register under these
+PROVIDER_GROUPS = {
+    "verification": "agent_os.providers.verification",
+    "self_correction": "agent_os.providers.self_correction",
+    "policy_engine": "agent_os.providers.policy_engine",
+    "context_service": "agent_os.providers.context_service",
+    "memory": "agent_os.providers.memory",
+    "trust_protocol": "agent_os.providers.trust_protocol",
+    "mute_agent": "agent_os.providers.mute_agent",
+}
+
+# Cache loaded providers to avoid repeated discovery
+_provider_cache: dict[str, Any] = {}
+
+
+def _discover_provider(group: str) -> type | None:
+    """Discover an advanced provider via entry_points.
+
+    Returns the provider class if found, None otherwise.
+    """
+    if group in _provider_cache:
+        return _provider_cache[group]
+
+    try:
+        eps = entry_points(group=group)
+        if eps:
+            # Use the first registered provider (highest priority)
+            ep = next(iter(eps))
+            provider_cls = ep.load()
+            _provider_cache[group] = provider_cls
+            logger.info(
+                "Advanced provider loaded: %s from %s", ep.name, ep.value
+            )
+            return provider_cls
+    except Exception:
+        logger.debug("Provider discovery failed for %s", group, exc_info=True)
+
+    _provider_cache[group] = None
+    return None
+
+
+def get_verification_engine(**kwargs: Any):
+    """Get the best available verification engine.
+
+    Advanced: Cross-model adversarial verification with strategy banning.
+    Community: Single-model self-check using difflib comparison.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["verification"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from cmvk.verification import VerificationEngine
+    return VerificationEngine(**kwargs)
+
+
+def get_self_correction_kernel(**kwargs: Any):
+    """Get the best available self-correction kernel.
+
+    Advanced: Dual-loop OODA with differential auditing and semantic purge.
+    Community: Simple retry with exponential backoff.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["self_correction"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from agent_kernel.kernel import SelfCorrectingAgentKernel
+    return SelfCorrectingAgentKernel(**kwargs)
+
+
+def get_policy_engine(**kwargs: Any):
+    """Get the best available policy engine.
+
+    Advanced: ABAC with attribute evaluation, constraint graphs, shadow mode.
+    Community: YAML-driven allow/deny rules with first-match semantics.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["policy_engine"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from agent_os.integrations.base import GovernancePolicy
+    return GovernancePolicy(**kwargs)
+
+
+def get_context_service(**kwargs: Any):
+    """Get the best available context service.
+
+    Advanced: Hot/Warm/Cold tiers with heuristic routing and pragmatic truth.
+    Community: Single-tier context with TTL-based expiry.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["context_service"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from caas.triad import ContextTriadManager
+    return ContextTriadManager(**kwargs)
+
+
+def get_memory_store(**kwargs: Any):
+    """Get the best available episodic memory store.
+
+    Advanced: Immutable append-only store with hash chaining (GARR).
+    Community: Mutable JSON file-based episode store.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["memory"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from emk.store import EpisodicMemoryStore
+    return EpisodicMemoryStore(**kwargs)
+
+
+def get_trust_protocol(**kwargs: Any):
+    """Get the best available trust protocol engine.
+
+    Advanced: Full IATP with sidecar attestation and capability handshake.
+    Community: Basic policy engine with nonce-based verification.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["trust_protocol"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from iatp.policy_engine import IATPPolicyEngine
+    return IATPPolicyEngine(**kwargs)
+
+
+def get_mute_agent(**kwargs: Any):
+    """Get the best available mute agent implementation.
+
+    Advanced: NULL response pattern with zero information leakage.
+    Community: Simple empty-string response on policy block.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["mute_agent"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from agent_os.mute_agent import MuteAgent
+    return MuteAgent(**kwargs)
+
+
+def list_providers() -> dict[str, str]:
+    """List all provider slots and their current implementations.
+
+    Returns a dict of {slot_name: "advanced" | "community"}.
+    """
+    result = {}
+    for name, group in PROVIDER_GROUPS.items():
+        provider = _discover_provider(group)
+        result[name] = "advanced" if provider is not None else "community"
+    return result
+
+
+def clear_cache() -> None:
+    """Clear the provider cache. Useful for testing."""
+    _provider_cache.clear()

agent_os/retry.py

@@ -0,0 +1,81 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Shared retry utilities for governance toolkit components."""
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import time
+from typing import Any, Callable, Sequence, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def retry(
+    max_attempts: int = 3,
+    backoff_base: float = 1.0,
+    exceptions: Sequence[type[BaseException]] = (Exception,),
+    on_retry: Callable[[int, BaseException], None] | None = None,
+) -> Callable:
+    """Decorator for retrying functions with exponential backoff.
+
+    Works with both sync and async functions.
+
+    Args:
+        max_attempts: Maximum number of attempts (including first try).
+        backoff_base: Base delay in seconds (doubled each retry).
+        exceptions: Tuple of exception types to catch and retry.
+        on_retry: Optional callback(attempt, exception) called before each retry.
+
+    Example:
+        @retry(max_attempts=3, exceptions=(ConnectionError, TimeoutError))
+        async def fetch_data(url: str) -> dict:
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                last_exc: BaseException | None = None
+                for attempt in range(1, max_attempts + 1):
+                    try:
+                        return await func(*args, **kwargs)
+                    except tuple(exceptions) as exc:
+                        last_exc = exc
+                        if attempt == max_attempts:
+                            raise
+                        delay = backoff_base * (2 ** (attempt - 1))
+                        if on_retry:
+                            on_retry(attempt, exc)
+                        logger.warning(
+                            "Retry %d/%d for %s after %s: %s",
+                            attempt, max_attempts, func.__name__, type(exc).__name__, exc,
+                        )
+                        await asyncio.sleep(delay)
+                raise last_exc  # unreachable but satisfies type checker
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                last_exc: BaseException | None = None
+                for attempt in range(1, max_attempts + 1):
+                    try:
+                        return func(*args, **kwargs)
+                    except tuple(exceptions) as exc:
+                        last_exc = exc
+                        if attempt == max_attempts:
+                            raise
+                        delay = backoff_base * (2 ** (attempt - 1))
+                        if on_retry:
+                            on_retry(attempt, exc)
+                        logger.warning(
+                            "Retry %d/%d for %s after %s: %s",
+                            attempt, max_attempts, func.__name__, type(exc).__name__, exc,
+                        )
+                        time.sleep(delay)
+                raise last_exc  # unreachable but satisfies type checker
+            return sync_wrapper
+    return decorator

agent_os/reversibility.py

@@ -0,0 +1,251 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Action reversibility assessment and compensation primitives.
+
+Pre-execution check: is this action reversible? If not, require
+additional approval or block entirely. Post-execution: provide
+compensation actions to undo effects.
+
+Addresses the criticism that AGT has no "rollback/reversibility
+guarantees." Now every action can be assessed for reversibility
+before execution, and compensation plans are generated for
+irreversible operations.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ReversibilityLevel(str, Enum):
+    """How reversible an action is."""
+    FULLY_REVERSIBLE = "fully_reversible"      # Can be undone completely (e.g., write a file)
+    PARTIALLY_REVERSIBLE = "partially_reversible"  # Can be partially undone (e.g., send email — recall possible)
+    IRREVERSIBLE = "irreversible"              # Cannot be undone (e.g., delete, deploy, send to external)
+    UNKNOWN = "unknown"                        # Reversibility cannot be determined
+
+
+class CompensatingAction(BaseModel):
+    """An action that can undo or mitigate a previous action."""
+    description: str
+    action: str
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    effectiveness: str = Field(
+        default="full",
+        description="full, partial, or mitigation-only",
+    )
+    time_window: str = Field(
+        default="",
+        description="Time window in which compensation is possible (e.g., '30 minutes')",
+    )
+
+
+class ReversibilityAssessment(BaseModel):
+    """Pre-execution assessment of an action's reversibility."""
+    action: str
+    level: ReversibilityLevel
+    reason: str
+    compensating_actions: list[CompensatingAction] = Field(default_factory=list)
+    requires_extra_approval: bool = False
+    assessed_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+# Default reversibility classifications
+_REVERSIBILITY_MAP: dict[str, dict[str, Any]] = {
+    # Fully reversible
+    "write_file": {
+        "level": ReversibilityLevel.FULLY_REVERSIBLE,
+        "reason": "File writes can be reverted by restoring previous version",
+        "compensating": [
+            CompensatingAction(
+                description="Restore previous file version",
+                action="restore_file_backup",
+                effectiveness="full",
+            )
+        ],
+    },
+    "create_file": {
+        "level": ReversibilityLevel.FULLY_REVERSIBLE,
+        "reason": "Created files can be deleted",
+        "compensating": [
+            CompensatingAction(
+                description="Delete the created file",
+                action="delete_file",
+                effectiveness="full",
+            )
+        ],
+    },
+    "database_write": {
+        "level": ReversibilityLevel.FULLY_REVERSIBLE,
+        "reason": "Database writes can be rolled back within transaction",
+        "compensating": [
+            CompensatingAction(
+                description="Rollback transaction",
+                action="rollback_transaction",
+                effectiveness="full",
+                time_window="within transaction scope",
+            )
+        ],
+    },
+    "create_pr": {
+        "level": ReversibilityLevel.FULLY_REVERSIBLE,
+        "reason": "Pull requests can be closed",
+        "compensating": [
+            CompensatingAction(
+                description="Close the pull request",
+                action="close_pr",
+                effectiveness="full",
+            )
+        ],
+    },
+
+    # Partially reversible
+    "send_email": {
+        "level": ReversibilityLevel.PARTIALLY_REVERSIBLE,
+        "reason": "Email recall may work within org, but external delivery cannot be undone",
+        "compensating": [
+            CompensatingAction(
+                description="Recall email (internal only)",
+                action="recall_email",
+                effectiveness="partial",
+                time_window="30 minutes",
+            ),
+            CompensatingAction(
+                description="Send correction/retraction",
+                action="send_correction",
+                effectiveness="mitigation-only",
+            ),
+        ],
+    },
+    "update_record": {
+        "level": ReversibilityLevel.PARTIALLY_REVERSIBLE,
+        "reason": "Previous value may be recoverable from audit log",
+        "compensating": [
+            CompensatingAction(
+                description="Restore from audit trail",
+                action="restore_from_audit",
+                effectiveness="partial",
+            )
+        ],
+    },
+
+    # Irreversible
+    "deploy": {
+        "level": ReversibilityLevel.IRREVERSIBLE,
+        "reason": "Production deployments affect live users immediately",
+        "compensating": [
+            CompensatingAction(
+                description="Rollback deployment",
+                action="rollback_deploy",
+                effectiveness="partial",
+                time_window="depends on deployment pipeline",
+            )
+        ],
+        "requires_extra_approval": True,
+    },
+    "delete_file": {
+        "level": ReversibilityLevel.IRREVERSIBLE,
+        "reason": "Deleted files may not be recoverable without backups",
+        "compensating": [
+            CompensatingAction(
+                description="Restore from backup if available",
+                action="restore_from_backup",
+                effectiveness="partial",
+            )
+        ],
+        "requires_extra_approval": True,
+    },
+    "delete_record": {
+        "level": ReversibilityLevel.IRREVERSIBLE,
+        "reason": "Deleted records may not be recoverable",
+        "compensating": [],
+        "requires_extra_approval": True,
+    },
+    "execute_trade": {
+        "level": ReversibilityLevel.IRREVERSIBLE,
+        "reason": "Executed trades are settled and cannot be undone",
+        "compensating": [
+            CompensatingAction(
+                description="Execute offsetting trade",
+                action="offsetting_trade",
+                effectiveness="mitigation-only",
+            )
+        ],
+        "requires_extra_approval": True,
+    },
+    "ssh_connect": {
+        "level": ReversibilityLevel.IRREVERSIBLE,
+        "reason": "Remote commands may have irreversible effects",
+        "compensating": [],
+        "requires_extra_approval": True,
+    },
+    "execute_code": {
+        "level": ReversibilityLevel.IRREVERSIBLE,
+        "reason": "Arbitrary code execution effects are unpredictable",
+        "compensating": [],
+        "requires_extra_approval": True,
+    },
+}
+
+
+class ReversibilityChecker:
+    """Assess action reversibility before execution.
+
+    Usage:
+        checker = ReversibilityChecker()
+        assessment = checker.assess("deploy")
+        if assessment.level == ReversibilityLevel.IRREVERSIBLE:
+            # require extra approval
+            ...
+    """
+
+    def __init__(
+        self,
+        custom_rules: dict[str, dict[str, Any]] | None = None,
+        block_irreversible: bool = False,
+    ) -> None:
+        self._rules = dict(_REVERSIBILITY_MAP)
+        if custom_rules:
+            self._rules.update(custom_rules)
+        self._block_irreversible = block_irreversible
+
+    def assess(self, action: str) -> ReversibilityAssessment:
+        """Assess the reversibility of an action before execution."""
+        rule = self._rules.get(action)
+
+        if not rule:
+            return ReversibilityAssessment(
+                action=action,
+                level=ReversibilityLevel.UNKNOWN,
+                reason=f"No reversibility data for action '{action}'",
+                requires_extra_approval=True,
+            )
+
+        return ReversibilityAssessment(
+            action=action,
+            level=rule["level"],
+            reason=rule["reason"],
+            compensating_actions=rule.get("compensating", []),
+            requires_extra_approval=rule.get("requires_extra_approval", False),
+        )
+
+    def is_safe(self, action: str) -> bool:
+        """Quick check: is this action safely reversible?"""
+        assessment = self.assess(action)
+        return assessment.level == ReversibilityLevel.FULLY_REVERSIBLE
+
+    def should_block(self, action: str) -> bool:
+        """Check if action should be blocked per policy."""
+        if not self._block_irreversible:
+            return False
+        assessment = self.assess(action)
+        return assessment.level == ReversibilityLevel.IRREVERSIBLE
+
+    def get_compensation_plan(self, action: str) -> list[CompensatingAction]:
+        """Get the compensation plan for an action."""
+        assessment = self.assess(action)
+        return assessment.compensating_actions