agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/constraint_graph.py

@@ -0,0 +1,234 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Constraint Graph — DAG-based resource access control.
+
+The constraint graph is the **only** path through which agents may access
+resources (tools, APIs, data).  Every resource access request is resolved
+by traversing a directed acyclic graph of constraint edges that encode
+allow/deny rules with optional conditions.
+
+Architecture:
+    Agent ──▶ ConstraintGraph.resolve() ──▶ allow / deny
+                     │
+                     ├─ match agent_pattern against agent_id
+                     ├─ match resource name
+                     └─ evaluate conditions (time, role, etc.)
+
+Integration:
+    ``ConstraintGraphEnforcer`` implements the same ``intercept()`` protocol
+    as ``PolicyInterceptor`` so it can be composed via ``CompositeInterceptor``.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+class Permission(Enum):
+    """Permission type for a constraint edge."""
+    ALLOW = "allow"
+    DENY = "deny"
+
+
+class ResourceType(Enum):
+    """Classification of a governed resource."""
+    TOOL = "tool"
+    API = "api"
+    DATA = "data"
+
+
+@dataclass(frozen=True)
+class ResourceNode:
+    """A resource (tool, API, data) in the constraint graph.
+
+    Attributes:
+        name: Unique resource identifier (e.g. ``"database_query"``).
+        resource_type: Classification of the resource.
+        metadata: Arbitrary key/value metadata for condition evaluation.
+    """
+    name: str
+    resource_type: ResourceType = ResourceType.TOOL
+    metadata: dict[str, Any] = field(default_factory=dict, hash=False)
+
+    def __hash__(self) -> int:
+        return hash((self.name, self.resource_type))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ResourceNode):
+            return NotImplemented
+        return self.name == other.name and self.resource_type == other.resource_type
+
+
+@dataclass
+class ConstraintEdge:
+    """A constraint linking an agent pattern to a resource permission.
+
+    Attributes:
+        agent_pattern: Glob pattern matched against agent IDs.
+        resource: The resource this constraint governs.
+        permission: Whether to allow or deny access.
+        conditions: Optional key/value conditions that must all be satisfied
+            for this edge to apply (e.g. ``{"role": "admin"}``).
+        priority: Higher-priority edges take precedence during resolution.
+    """
+    agent_pattern: str
+    resource: str
+    permission: Permission
+    conditions: dict[str, Any] = field(default_factory=dict)
+    priority: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Constraint Graph
+# ---------------------------------------------------------------------------
+
+class ConstraintGraph:
+    """DAG of resource constraints.
+
+    Edges are evaluated in priority order (highest first).  The first matching
+    edge determines the outcome.  If no edge matches, access is **denied** by
+    default (deny-by-default posture).
+    """
+
+    def __init__(self) -> None:
+        self._nodes: dict[str, ResourceNode] = {}
+        self._edges: list[ConstraintEdge] = []
+
+    # -- mutators -----------------------------------------------------------
+
+    def add_resource(self, node: ResourceNode) -> None:
+        """Register a resource node."""
+        self._nodes[node.name] = node
+
+    def add_constraint(self, edge: ConstraintEdge) -> None:
+        """Add a constraint edge and re-sort by descending priority."""
+        self._edges.append(edge)
+        self._edges.sort(key=lambda e: e.priority, reverse=True)
+
+    # -- query --------------------------------------------------------------
+
+    @property
+    def resources(self) -> dict[str, ResourceNode]:
+        """Read-only view of registered resources."""
+        return dict(self._nodes)
+
+    @property
+    def edges(self) -> list[ConstraintEdge]:
+        """Read-only copy of constraint edges (sorted by priority)."""
+        return list(self._edges)
+
+    # -- resolution ---------------------------------------------------------
+
+    def resolve(
+        self,
+        agent_id: str,
+        resource: str,
+        context: dict[str, Any] | None = None,
+    ) -> bool:
+        """Check whether *agent_id* may access *resource*.
+
+        Args:
+            agent_id: The requesting agent's identifier.
+            resource: Name of the target resource.
+            context: Runtime context used for condition evaluation.
+
+        Returns:
+            ``True`` if access is allowed, ``False`` otherwise.
+        """
+        context = context or {}
+
+        for edge in self._edges:
+            if not fnmatch.fnmatch(agent_id, edge.agent_pattern):
+                continue
+            if not fnmatch.fnmatch(resource, edge.resource):
+                continue
+            if not self._conditions_met(edge.conditions, context):
+                continue
+
+            allowed = edge.permission == Permission.ALLOW
+            logger.debug(
+                "constraint resolved: agent=%s resource=%s -> %s (priority=%d)",
+                agent_id,
+                resource,
+                edge.permission.value,
+                edge.priority,
+            )
+            return allowed
+
+        # Deny by default
+        logger.debug(
+            "constraint resolved: agent=%s resource=%s -> deny (no matching edge)",
+            agent_id,
+            resource,
+        )
+        return False
+
+    # -- internals ----------------------------------------------------------
+
+    @staticmethod
+    def _conditions_met(
+        conditions: dict[str, Any],
+        context: dict[str, Any],
+    ) -> bool:
+        """Return ``True`` if every condition key/value is present in *context*."""
+        return all(context.get(k) == v for k, v in conditions.items())
+
+
+# ---------------------------------------------------------------------------
+# Enforcer (PolicyInterceptor-compatible)
+# ---------------------------------------------------------------------------
+
+class ConstraintGraphEnforcer:
+    """Intercepts tool calls and enforces the constraint graph.
+
+    Implements the same ``intercept(request) -> result`` protocol used by
+    ``PolicyInterceptor`` and ``CompositeInterceptor`` so it can be plugged
+    into the existing governance pipeline.
+    """
+
+    def __init__(
+        self,
+        graph: ConstraintGraph,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        self.graph = graph
+        self.context = context or {}
+
+    def intercept(self, request: Any) -> Any:
+        """Enforce constraint graph for a ``ToolCallRequest``.
+
+        Imports are deferred to avoid circular dependency with
+        ``integrations.base``.
+        """
+        from agent_os.integrations.base import ToolCallResult
+
+        agent_id = getattr(request, "agent_id", "") or ""
+        tool_name = getattr(request, "tool_name", "") or ""
+
+        if not agent_id:
+            return ToolCallResult(
+                allowed=False,
+                reason="Constraint graph requires agent_id on the request",
+            )
+
+        allowed = self.graph.resolve(agent_id, tool_name, self.context)
+        if not allowed:
+            return ToolCallResult(
+                allowed=False,
+                reason=(
+                    f"Constraint graph denied agent '{agent_id}' "
+                    f"access to resource '{tool_name}'"
+                ),
+            )
+
+        return ToolCallResult(allowed=True)

agent_os/content_governance.py

@@ -0,0 +1,140 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Content and knowledge quality governance for AI agents.
+
+Runtime governance answers 'is the agent behavior safe?'
+Content governance answers 'is the agent output accurate, well-structured,
+and meeting quality standards?'
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ContentDimension(str, Enum):
+    """Dimensions for content quality evaluation."""
+    ACCURACY = "accuracy"
+    COMPLETENESS = "completeness"
+    FRESHNESS = "freshness"
+    STRUCTURE = "structure"
+    RELEVANCE = "relevance"
+    CONSISTENCY = "consistency"
+
+
+class QualityGate(str, Enum):
+    """Content quality gate decisions."""
+    PASS = "pass"
+    WARN = "warn"
+    FAIL = "fail"
+
+
+@dataclass
+class ContentQualityRule:
+    """A rule for evaluating content quality."""
+    name: str
+    dimension: ContentDimension
+    threshold: float  # 0.0 to 1.0
+    gate: QualityGate = QualityGate.WARN
+    description: str = ""
+
+
+@dataclass
+class ContentEvaluation:
+    """Result of evaluating content against quality rules."""
+    dimension: ContentDimension
+    score: float
+    gate_result: QualityGate
+    rule_name: str
+    details: str = ""
+
+
+@dataclass
+class ContentQualityReport:
+    """Aggregated quality report for agent output."""
+    agent_id: str
+    content_id: str
+    evaluations: list[ContentEvaluation] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return all(e.gate_result != QualityGate.FAIL for e in self.evaluations)
+
+    @property
+    def overall_score(self) -> float:
+        if not self.evaluations:
+            return 0.0
+        return sum(e.score for e in self.evaluations) / len(self.evaluations)
+
+    @property
+    def warnings(self) -> list[ContentEvaluation]:
+        return [e for e in self.evaluations if e.gate_result == QualityGate.WARN]
+
+    @property
+    def failures(self) -> list[ContentEvaluation]:
+        return [e for e in self.evaluations if e.gate_result == QualityGate.FAIL]
+
+
+class ContentQualityEvaluator:
+    """Evaluates agent output against content quality rules.
+
+    Usage:
+        evaluator = ContentQualityEvaluator()
+        evaluator.add_rule(ContentQualityRule(
+            name="min-accuracy",
+            dimension=ContentDimension.ACCURACY,
+            threshold=0.8,
+            gate=QualityGate.FAIL,
+        ))
+
+        report = evaluator.evaluate(
+            agent_id="agent-1",
+            content_id="response-123",
+            scores={ContentDimension.ACCURACY: 0.75},
+        )
+        assert not report.passed  # Below 0.8 threshold
+    """
+
+    def __init__(self) -> None:
+        self._rules: list[ContentQualityRule] = []
+
+    def add_rule(self, rule: ContentQualityRule) -> None:
+        self._rules.append(rule)
+
+    def load_rules(self, rules: list[dict[str, Any]]) -> None:
+        """Load rules from a list of dicts (e.g., from YAML config)."""
+        for r in rules:
+            self._rules.append(ContentQualityRule(
+                name=r["name"],
+                dimension=ContentDimension(r["dimension"]),
+                threshold=float(r["threshold"]),
+                gate=QualityGate(r.get("gate", "warn")),
+                description=r.get("description", ""),
+            ))
+
+    def evaluate(
+        self,
+        agent_id: str,
+        content_id: str,
+        scores: dict[ContentDimension, float],
+    ) -> ContentQualityReport:
+        """Evaluate content scores against configured rules."""
+        evaluations = []
+        for rule in self._rules:
+            score = scores.get(rule.dimension, 0.0)
+            if score >= rule.threshold:
+                gate_result = QualityGate.PASS
+            else:
+                gate_result = rule.gate
+            evaluations.append(ContentEvaluation(
+                dimension=rule.dimension,
+                score=score,
+                gate_result=gate_result,
+                rule_name=rule.name,
+                details=f"Score {score:.2f} vs threshold {rule.threshold:.2f}",
+            ))
+        return ContentQualityReport(
+            agent_id=agent_id,
+            content_id=content_id,
+            evaluations=evaluations,
+        )

agent_os/context_budget.py

@@ -0,0 +1,305 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Context Budget Scheduler — token budget as a kernel primitive.
+
+Makes the "Scale by Subtraction" philosophy (90 % lookup, 10 % reasoning)
+concrete and enforced.  The kernel owns the budget; agents cannot exceed it.
+
+Closes #207.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any, Callable
+
+# ---------------------------------------------------------------------------
+# Signals
+# ---------------------------------------------------------------------------
+
+class AgentSignal(Enum):
+    """Kernel signals for context budget enforcement."""
+
+    SIGSTOP = auto()    # Budget exceeded — halt the agent
+    SIGWARN = auto()    # Budget nearing limit
+    SIGRESUME = auto()  # Budget replenished
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ContextWindow:
+    """An allocated context window for an agent task."""
+
+    agent_id: str
+    task: str
+    lookup_budget: int       # tokens for retrieval / facts
+    reasoning_budget: int    # tokens for LLM reasoning
+    total: int               # lookup + reasoning
+    created_at: float = field(default_factory=time.time)
+
+    @property
+    def lookup_ratio(self) -> float:
+        return self.lookup_budget / self.total if self.total else 0.0
+
+    @property
+    def reasoning_ratio(self) -> float:
+        return self.reasoning_budget / self.total if self.total else 0.0
+
+
+class ContextPriority(Enum):
+    """Task priority levels for context allocation."""
+
+    CRITICAL = 3   # Gets full allocation even if pool is tight
+    HIGH = 2
+    NORMAL = 1
+    LOW = 0        # Smallest possible allocation
+
+
+@dataclass
+class UsageRecord:
+    """Tracks actual token usage by an agent."""
+
+    agent_id: str
+    window: ContextWindow
+    lookup_used: int = 0
+    reasoning_used: int = 0
+    started_at: float = field(default_factory=time.time)
+    stopped: bool = False
+    stop_reason: str | None = None
+
+    @property
+    def total_used(self) -> int:
+        return self.lookup_used + self.reasoning_used
+
+    @property
+    def remaining(self) -> int:
+        return max(0, self.window.total - self.total_used)
+
+    @property
+    def utilization(self) -> float:
+        return self.total_used / self.window.total if self.window.total else 0.0
+
+
+# ---------------------------------------------------------------------------
+# Budget Exceeded Error
+# ---------------------------------------------------------------------------
+
+class BudgetExceeded(Exception):
+    """Raised when an agent exceeds its context budget."""
+
+    def __init__(self, agent_id: str, budget: int, used: int) -> None:
+        self.agent_id = agent_id
+        self.budget = budget
+        self.used = used
+        super().__init__(
+            f"Agent {agent_id} exceeded context budget: {used}/{budget} tokens"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Context Budget Scheduler
+# ---------------------------------------------------------------------------
+
+# Default minimum context sizes per priority (tokens)
+_MIN_CONTEXT: dict[ContextPriority, int] = {
+    ContextPriority.CRITICAL: 4000,
+    ContextPriority.HIGH: 2000,
+    ContextPriority.NORMAL: 1000,
+    ContextPriority.LOW: 500,
+}
+
+
+class ContextScheduler:
+    """
+    Kernel primitive that governs how context budget is allocated.
+
+    Like CPU scheduling but for token budgets.  Enforces the 90/10
+    (lookup/reasoning) split and emits SIGSTOP when an agent goes
+    over budget.
+
+    Parameters
+    ----------
+    total_budget : int
+        Global token pool (shared across all active agents).
+    lookup_ratio : float
+        Fraction of each allocation devoted to lookup (default 0.90).
+    warn_threshold : float
+        Fraction of budget at which SIGWARN fires (default 0.85).
+    """
+
+    def __init__(
+        self,
+        total_budget: int = 8000,
+        lookup_ratio: float = 0.90,
+        warn_threshold: float = 0.85,
+    ) -> None:
+        if not 0.0 < lookup_ratio < 1.0:
+            raise ValueError("lookup_ratio must be between 0 and 1 exclusive")
+        if total_budget < 1:
+            raise ValueError("total_budget must be positive")
+
+        self.total_budget = total_budget
+        self.lookup_ratio = lookup_ratio
+        self.warn_threshold = warn_threshold
+
+        self._active: dict[str, UsageRecord] = {}
+        self._history: list[UsageRecord] = []
+        self._signal_handlers: dict[AgentSignal, list[Callable]] = {
+            s: [] for s in AgentSignal
+        }
+
+    # -- Allocation -----------------------------------------------------------
+
+    def allocate(
+        self,
+        agent_id: str,
+        task: str,
+        priority: ContextPriority = ContextPriority.NORMAL,
+        max_tokens: int | None = None,
+    ) -> ContextWindow:
+        """
+        Allocate a context window for *agent_id*.
+
+        The scheduler decides the actual size based on remaining pool
+        capacity and the task priority.
+        """
+        available = self._available_tokens()
+        minimum = _MIN_CONTEXT[priority]
+
+        if max_tokens is not None:
+            desired = min(max_tokens, available)
+        else:
+            # Scale by priority
+            desired = min(
+                int(self.total_budget * (0.25 + 0.25 * priority.value)),
+                available,
+            )
+
+        # Ensure at least the minimum (or whatever is left),
+        # but never exceed an explicit max_tokens cap.
+        if max_tokens is not None:
+            allocated = min(desired, max_tokens)
+        else:
+            allocated = max(minimum, desired) if available >= minimum else available
+
+        lookup = int(allocated * self.lookup_ratio)
+        reasoning = allocated - lookup
+
+        window = ContextWindow(
+            agent_id=agent_id,
+            task=task,
+            lookup_budget=lookup,
+            reasoning_budget=reasoning,
+            total=allocated,
+        )
+
+        self._active[agent_id] = UsageRecord(agent_id=agent_id, window=window)
+        return window
+
+    # -- Usage tracking -------------------------------------------------------
+
+    def record_usage(
+        self,
+        agent_id: str,
+        lookup_tokens: int = 0,
+        reasoning_tokens: int = 0,
+    ) -> UsageRecord:
+        """
+        Record token usage for an active allocation.
+
+        Emits SIGWARN or SIGSTOP as thresholds are crossed.
+        """
+        rec = self._active.get(agent_id)
+        if rec is None:
+            raise KeyError(f"No active allocation for agent {agent_id}")
+        if rec.stopped:
+            raise BudgetExceeded(agent_id, rec.window.total, rec.total_used)
+
+        rec.lookup_used += lookup_tokens
+        rec.reasoning_used += reasoning_tokens
+
+        # Check thresholds
+        utilization = rec.utilization
+        if utilization >= 1.0:
+            rec.stopped = True
+            rec.stop_reason = "budget_exceeded"
+            self._emit(AgentSignal.SIGSTOP, agent_id)
+            raise BudgetExceeded(agent_id, rec.window.total, rec.total_used)
+        elif utilization >= self.warn_threshold:
+            self._emit(AgentSignal.SIGWARN, agent_id)
+
+        return rec
+
+    def release(self, agent_id: str) -> UsageRecord | None:
+        """Release an allocation and move it to history."""
+        rec = self._active.pop(agent_id, None)
+        if rec is not None:
+            self._history.append(rec)
+        return rec
+
+    # -- Queries --------------------------------------------------------------
+
+    def get_usage(self, agent_id: str) -> UsageRecord | None:
+        return self._active.get(agent_id)
+
+    @property
+    def active_agents(self) -> list[str]:
+        return list(self._active.keys())
+
+    @property
+    def active_count(self) -> int:
+        return len(self._active)
+
+    def _available_tokens(self) -> int:
+        used = sum(r.window.total for r in self._active.values())
+        return max(0, self.total_budget - used)
+
+    @property
+    def available_tokens(self) -> int:
+        return self._available_tokens()
+
+    @property
+    def utilization(self) -> float:
+        """Global pool utilization (0.0 – 1.0)."""
+        allocated = sum(r.window.total for r in self._active.values())
+        return allocated / self.total_budget if self.total_budget else 0.0
+
+    def get_health_report(self) -> dict[str, Any]:
+        """Return a summary of scheduler state."""
+        return {
+            "total_budget": self.total_budget,
+            "available": self._available_tokens(),
+            "utilization": round(self.utilization, 3),
+            "active_agents": self.active_count,
+            "lookup_ratio": self.lookup_ratio,
+            "agents": {
+                aid: {
+                    "task": r.window.task,
+                    "allocated": r.window.total,
+                    "used": r.total_used,
+                    "remaining": r.remaining,
+                    "stopped": r.stopped,
+                }
+                for aid, r in self._active.items()
+            },
+            "history_count": len(self._history),
+        }
+
+    # -- Signal system --------------------------------------------------------
+
+    def on_signal(self, signal: AgentSignal, handler: Callable) -> None:
+        """Register a handler for *signal*."""
+        self._signal_handlers[signal].append(handler)
+
+    def _emit(self, signal: AgentSignal, agent_id: str) -> None:
+        for handler in self._signal_handlers[signal]:
+            try:
+                handler(agent_id, signal)
+            except Exception:
+                pass