agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/execution_context_policy.py

@@ -0,0 +1,141 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Execution-context-aware policy enforcement.
+
+Policies behave differently depending on where they run:
+- inner_loop (IDE/CLI): advisory, blocks only critical violations
+- ci_cd (pipeline): enforces anti-patterns, warns on advisory
+- autonomous (agent runtime): strictest, blocks everything non-compliant
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ExecutionContext(str, Enum):
+    """Execution environment where policy is evaluated."""
+
+    INNER_LOOP = "inner_loop"    # IDE, CLI, local dev
+    CI_CD = "ci_cd"              # Pipeline, PR checks
+    AUTONOMOUS = "autonomous"    # Agent runtime, production
+
+
+class EnforcementLevel(str, Enum):
+    """How strictly a policy violation is handled."""
+
+    BLOCK = "block"
+    WARN = "warn"
+    AUDIT = "audit"        # log only, no user-visible output
+    SKIP = "skip"
+
+
+@dataclass
+class ContextualPolicyRule:
+    """A policy rule with per-context enforcement levels."""
+
+    name: str
+    category: str = ""
+    description: str = ""
+    default_level: EnforcementLevel = EnforcementLevel.WARN
+    context_overrides: dict[ExecutionContext, EnforcementLevel] = field(
+        default_factory=dict,
+    )
+
+    def effective_level(self, context: ExecutionContext) -> EnforcementLevel:
+        return self.context_overrides.get(context, self.default_level)
+
+
+@dataclass
+class PolicyViolation:
+    """A detected policy violation with context-aware severity."""
+
+    rule_name: str
+    message: str
+    level: EnforcementLevel
+    context: ExecutionContext
+    location: str = ""
+    suggestion: str = ""
+
+
+class ContextualPolicyEngine:
+    """Policy engine that adjusts enforcement based on execution context."""
+
+    def __init__(
+        self, context: ExecutionContext = ExecutionContext.CI_CD,
+    ) -> None:
+        self._context = context
+        self._rules: list[ContextualPolicyRule] = []
+        self._violations: list[PolicyViolation] = []
+
+    @property
+    def context(self) -> ExecutionContext:
+        return self._context
+
+    def add_rule(self, rule: ContextualPolicyRule) -> None:
+        self._rules.append(rule)
+
+    def load_rules(self, rules: list[dict[str, Any]]) -> None:
+        for r in rules:
+            overrides: dict[ExecutionContext, EnforcementLevel] = {}
+            for ctx_name, level_name in r.get("context_overrides", {}).items():
+                overrides[ExecutionContext(ctx_name)] = EnforcementLevel(level_name)
+            self._rules.append(
+                ContextualPolicyRule(
+                    name=r["name"],
+                    category=r.get("category", ""),
+                    description=r.get("description", ""),
+                    default_level=EnforcementLevel(
+                        r.get("default_level", "warn"),
+                    ),
+                    context_overrides=overrides,
+                ),
+            )
+
+    def evaluate(
+        self,
+        rule_name: str,
+        message: str,
+        location: str = "",
+        suggestion: str = "",
+    ) -> PolicyViolation | None:
+        rule = next((r for r in self._rules if r.name == rule_name), None)
+        if rule is None:
+            return None
+        level = rule.effective_level(self._context)
+        if level == EnforcementLevel.SKIP:
+            return None
+        violation = PolicyViolation(
+            rule_name=rule_name,
+            message=message,
+            level=level,
+            context=self._context,
+            location=location,
+            suggestion=suggestion,
+        )
+        self._violations.append(violation)
+        return violation
+
+    @property
+    def blocking_violations(self) -> list[PolicyViolation]:
+        return [v for v in self._violations if v.level == EnforcementLevel.BLOCK]
+
+    @property
+    def warnings(self) -> list[PolicyViolation]:
+        return [v for v in self._violations if v.level == EnforcementLevel.WARN]
+
+    @property
+    def has_blocking(self) -> bool:
+        return len(self.blocking_violations) > 0
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "context": self._context.value,
+            "total_violations": len(self._violations),
+            "blocking": len(self.blocking_violations),
+            "warnings": len(self.warnings),
+            "audit_only": len(
+                [v for v in self._violations if v.level == EnforcementLevel.AUDIT],
+            ),
+        }

agent_os/github_enterprise.py

@@ -0,0 +1,96 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""GitHub Enterprise managed policy and ruleset integration.
+
+Provides integration points for GitHub Enterprise features:
+- Repository rulesets for governance enforcement
+- Custom properties for repo governance tier tagging
+- Enterprise-level policy templates
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class GovernanceTier(str, Enum):
+    """Repository governance tier assigned via GitHub custom properties."""
+    UNCLASSIFIED = "unclassified"
+    BASIC = "basic"
+    STANDARD = "standard"
+    ELEVATED = "elevated"
+    CRITICAL = "critical"
+
+
+@dataclass
+class RulesetConfig:
+    """Configuration for a GitHub repository ruleset."""
+    name: str
+    enforcement: str = "active"  # active, evaluate, disabled
+    target: str = "branch"  # branch, tag, push
+    conditions: dict[str, Any] = field(default_factory=dict)
+    rules: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class EnterpriseGovernancePolicy:
+    """Enterprise-level governance policy template.
+
+    Defines rulesets and custom properties that should be applied
+    to repositories based on their governance tier.
+    """
+    name: str
+    description: str = ""
+    applicable_tiers: list[GovernanceTier] = field(default_factory=list)
+    rulesets: list[RulesetConfig] = field(default_factory=list)
+    required_custom_properties: dict[str, str] = field(default_factory=dict)
+
+
+class EnterpriseGovernanceManager:
+    """Manages GitHub Enterprise governance policies and rulesets.
+
+    Maps governance tiers to repository rulesets and enforces
+    enterprise-level policy templates across org repos.
+    """
+
+    def __init__(self) -> None:
+        self._policies: list[EnterpriseGovernancePolicy] = []
+        self._repo_tiers: dict[str, GovernanceTier] = {}
+
+    def add_policy(self, policy: EnterpriseGovernancePolicy) -> None:
+        self._policies.append(policy)
+
+    def set_repo_tier(self, repo: str, tier: GovernanceTier) -> None:
+        self._repo_tiers[repo] = tier
+
+    def get_repo_tier(self, repo: str) -> GovernanceTier:
+        return self._repo_tiers.get(repo, GovernanceTier.UNCLASSIFIED)
+
+    def get_applicable_policies(self, repo: str) -> list[EnterpriseGovernancePolicy]:
+        """Get all policies applicable to a repo based on its tier."""
+        tier = self.get_repo_tier(repo)
+        return [p for p in self._policies if tier in p.applicable_tiers]
+
+    def get_required_rulesets(self, repo: str) -> list[RulesetConfig]:
+        """Get all rulesets that should be applied to a repo."""
+        rulesets = []
+        for policy in self.get_applicable_policies(repo):
+            rulesets.extend(policy.rulesets)
+        return rulesets
+
+    def audit_repo_compliance(self, repo: str, active_rulesets: list[str]) -> dict[str, Any]:
+        """Audit a repo's compliance with its governance tier requirements."""
+        required = self.get_required_rulesets(repo)
+        required_names = {r.name for r in required}
+        active_set = set(active_rulesets)
+        missing = required_names - active_set
+        extra = active_set - required_names
+        return {
+            "repo": repo,
+            "tier": self.get_repo_tier(repo).value,
+            "compliant": len(missing) == 0,
+            "required_rulesets": sorted(required_names),
+            "active_rulesets": sorted(active_set),
+            "missing_rulesets": sorted(missing),
+            "extra_rulesets": sorted(extra),
+        }

agent_os/health.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Convenience re-export of health check components.
+
+Canonical implementation lives in ``agent_os.integrations.health``.
+"""
+
+from agent_os.integrations.health import (  # noqa: F401
+    ComponentHealth,
+    HealthChecker,
+    HealthReport,
+    HealthStatus,
+)
+
+__all__ = [
+    "ComponentHealth",
+    "HealthChecker",
+    "HealthReport",
+    "HealthStatus",
+]

agent_os/integrations/__init__.py

@@ -0,0 +1,279 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Agent OS Integrations
+
+Adapters to wrap existing agent frameworks with Agent OS governance.
+
+Supported Frameworks:
+- LangChain: Chains, Agents, Runnables
+- LlamaIndex: Query Engines, Chat Engines, Agents
+- CrewAI: Crews and Agents
+- AutoGen: Multi-agent conversations
+- OpenAI Assistants: Assistants API with tools
+- Anthropic Claude: Messages API with tool use
+- Google Gemini: GenerativeModel with function calling
+- Mistral AI: Chat API with tool calls
+- Semantic Kernel: Microsoft's AI orchestration framework
+- PydanticAI: Model-agnostic agents with tool governance
+
+Usage:
+    # LangChain
+    from agent_os.integrations import LangChainKernel
+    kernel = LangChainKernel()
+    governed_chain = kernel.wrap(my_chain)
+
+    # LlamaIndex
+    from agent_os.integrations import LlamaIndexKernel
+    kernel = LlamaIndexKernel()
+    governed_engine = kernel.wrap(my_query_engine)
+
+    # OpenAI Assistants
+    from agent_os.integrations import OpenAIKernel
+    kernel = OpenAIKernel()
+    governed = kernel.wrap(assistant, client)
+
+    # Semantic Kernel
+    from agent_os.integrations import SemanticKernelWrapper
+    governed = SemanticKernelWrapper().wrap(sk_kernel)
+"""
+
+from agent_os.exceptions import (
+    AdapterNotFoundError,
+    AdapterTimeoutError,
+    AgentOSError,
+    BudgetError,
+    BudgetExceededError,
+    BudgetWarningError,
+    ConfigurationError,
+    CredentialExpiredError,
+    IdentityError,
+    IdentityVerificationError,
+    IntegrationError,
+    InvalidPolicyError,
+    MissingConfigError,
+    PolicyDeniedError,
+    PolicyError,
+    PolicyTimeoutError,
+    PolicyViolationError,
+    RateLimitError,
+)
+from agent_os.integrations.a2a_adapter import A2AEvaluation, A2AGovernanceAdapter, A2APolicy
+from agent_os.integrations.anthropic_adapter import AnthropicKernel, GovernedAnthropicClient
+from agent_os.integrations.autogen_adapter import AutoGenKernel
+from agent_os.integrations.crewai_adapter import CrewAIKernel
+from agent_os.integrations.gemini_adapter import GeminiKernel, GovernedGeminiModel
+from agent_os.integrations.google_adk_adapter import GoogleADKKernel
+from agent_os.integrations.guardrails_adapter import GuardrailsKernel
+from agent_os.integrations.langchain_adapter import LangChainKernel
+try:
+    from agent_os.integrations.maf_adapter import (
+        AuditTrailMiddleware as MAFAuditTrailMiddleware,
+        CapabilityGuardMiddleware as MAFCapabilityGuardMiddleware,
+        GovernancePolicyMiddleware as MAFGovernancePolicyMiddleware,
+        RogueDetectionMiddleware as MAFRogueDetectionMiddleware,
+        create_governance_middleware as maf_create_governance_middleware,
+    )
+except ImportError:  # agent_framework is an optional dependency
+    pass
+from agent_os.integrations.llamafirewall import (
+    FirewallMode,
+    FirewallResult,
+    FirewallVerdict,
+    LlamaFirewallAdapter,
+)
+from agent_os.integrations.llamaindex_adapter import LlamaIndexKernel
+from agent_os.integrations.mistral_adapter import GovernedMistralClient, MistralKernel
+from agent_os.integrations.openai_adapter import GovernedAssistant, OpenAIKernel
+from agent_os.integrations.pydantic_ai_adapter import PydanticAIKernel
+from agent_os.integrations.semantic_kernel_adapter import (
+    GovernedSemanticKernel,
+    SemanticKernelWrapper,
+)
+
+from .base import (
+    AsyncGovernedWrapper,
+    BaseIntegration,
+    BoundedSemaphore,
+    CompositeInterceptor,
+    ContentHashInterceptor,
+    DriftResult,
+    GovernancePolicy,
+    PolicyInterceptor,
+    ToolCallInterceptor,
+    ToolCallRequest,
+    ToolCallResult,
+)
+from .config import AgentOSConfig, get_config, reset_config
+from .conversation_guardian import (
+    AlertAction,
+    AlertSeverity,
+    ConversationAlert,
+    ConversationGuardian,
+    ConversationGuardianConfig,
+    EscalationClassifier,
+    FeedbackLoopBreaker,
+    OffensiveIntentDetector,
+)
+from .dry_run import DryRunCollector, DryRunDecision, DryRunPolicy, DryRunResult
+from .escalation import (
+    ApprovalBackend,
+    DefaultTimeoutAction,
+    EscalationDecision,
+    EscalationHandler,
+    EscalationPolicy,
+    EscalationRequest,
+    EscalationResult,
+    InMemoryApprovalQueue,
+    QuorumConfig,
+    WebhookApprovalBackend,
+)
+from .compat import CompatReport, check_compatibility, doctor, warn_on_import
+from .health import ComponentHealth, HealthChecker, HealthReport, HealthStatus
+from .logging import GovernanceLogger, JSONFormatter, get_logger
+from .policy_compose import PolicyHierarchy, compose_policies, override_policy
+from .rate_limiter import RateLimiter, RateLimitStatus
+from .templates import PolicyTemplates
+from .token_budget import TokenBudgetStatus, TokenBudgetTracker
+from .tool_aliases import ToolAliasRegistry
+from .webhooks import DeliveryRecord, WebhookConfig, WebhookEvent, WebhookNotifier
+
+__all__ = [
+    # Base
+    "AsyncGovernedWrapper",
+    "BaseIntegration",
+    "DriftResult",
+    "GovernancePolicy",
+    # Tool Call Interceptor (vendor-neutral)
+    "ToolCallInterceptor",
+    "ToolCallRequest",
+    "ToolCallResult",
+    "PolicyInterceptor",
+    "CompositeInterceptor",
+    # Backpressure / Concurrency
+    "BoundedSemaphore",
+    # LangChain
+    "LangChainKernel",
+    # LlamaIndex
+    "LlamaIndexKernel",
+    # CrewAI
+    "CrewAIKernel",
+    # AutoGen
+    "AutoGenKernel",
+    # OpenAI Assistants
+    "OpenAIKernel",
+    "GovernedAssistant",
+    # Anthropic Claude
+    "AnthropicKernel",
+    "GovernedAnthropicClient",
+    # Google Gemini
+    "GeminiKernel",
+    "GovernedGeminiModel",
+    # Mistral AI
+    "MistralKernel",
+    "GovernedMistralClient",
+    # Semantic Kernel
+    "SemanticKernelWrapper",
+    "GovernedSemanticKernel",
+    # Guardrails
+    "GuardrailsKernel",
+    # Google ADK
+    "GoogleADKKernel",
+    # A2A (Agent-to-Agent)
+    "A2AGovernanceAdapter",
+    "A2APolicy",
+    "A2AEvaluation",
+    # A2A Conversation Guardian
+    "ConversationGuardian",
+    "ConversationGuardianConfig",
+    "ConversationAlert",
+    "AlertAction",
+    "AlertSeverity",
+    "EscalationClassifier",
+    "FeedbackLoopBreaker",
+    "OffensiveIntentDetector",
+    # PydanticAI
+    "PydanticAIKernel",
+    # Microsoft Agent Framework (MAF)
+    "MAFGovernancePolicyMiddleware",
+    "MAFCapabilityGuardMiddleware",
+    "MAFAuditTrailMiddleware",
+    "MAFRogueDetectionMiddleware",
+    "maf_create_governance_middleware",
+    # LlamaFirewall
+    "LlamaFirewallAdapter",
+    "FirewallMode",
+    "FirewallVerdict",
+    "FirewallResult",
+    # Token Budget Tracking
+    "TokenBudgetTracker",
+    "TokenBudgetStatus",
+    # Dry Run
+    "DryRunPolicy",
+    "DryRunResult",
+    "DryRunDecision",
+    "DryRunCollector",
+    # Escalation (Human-in-the-Loop)
+    "EscalationPolicy",
+    "EscalationHandler",
+    "EscalationRequest",
+    "EscalationResult",
+    "EscalationDecision",
+    "DefaultTimeoutAction",
+    "ApprovalBackend",
+    "InMemoryApprovalQueue",
+    "WebhookApprovalBackend",
+    # Version Compatibility
+    "doctor",
+    "check_compatibility",
+    "CompatReport",
+    "warn_on_import",
+    # Tool Aliases
+    "ToolAliasRegistry",
+    # Rate Limiting
+    "RateLimiter",
+    "RateLimitStatus",
+    # Policy Templates
+    "PolicyTemplates",
+    # Webhooks
+    "WebhookConfig",
+    "WebhookEvent",
+    "WebhookNotifier",
+    "DeliveryRecord",
+    # Policy Composition
+    "compose_policies",
+    "PolicyHierarchy",
+    "override_policy",
+    # Exceptions
+    "AgentOSError",
+    "PolicyError",
+    "PolicyViolationError",
+    "PolicyDeniedError",
+    "PolicyTimeoutError",
+    "BudgetError",
+    "BudgetExceededError",
+    "BudgetWarningError",
+    "IdentityError",
+    "IdentityVerificationError",
+    "CredentialExpiredError",
+    "IntegrationError",
+    "AdapterNotFoundError",
+    "AdapterTimeoutError",
+    "ConfigurationError",
+    "InvalidPolicyError",
+    "MissingConfigError",
+    "RateLimitError",
+    # Health Checks
+    "HealthChecker",
+    "HealthReport",
+    "HealthStatus",
+    "ComponentHealth",
+    # Structured Logging
+    "GovernanceLogger",
+    "JSONFormatter",
+    "get_logger",
+    # Environment Configuration
+    "AgentOSConfig",
+    "get_config",
+    "reset_config",
+]