agent-os-kernel 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

agent_os/__init__.py

@@ -16,13 +16,21 @@ Quick Start:
     >>> ctx = kernel.create_agent_context("agent-001")
     >>> await ctx.write("/mem/working/task.txt", "Hello World")
 
+Stateless API (MCP June 2026):
+    >>> from agent_os import stateless_execute
+    >>> result = await stateless_execute(
+    ...     action="database_query",
+    ...     params={"query": "SELECT * FROM users"},
+    ...     agent_id="analyst-001",
+    ...     policies=["read_only"]
+    ... )
+
 Installation:
-    pip install agent-os[full]    # Everything
-    pip install agent-os[core]    # Primitives + Control Plane
-    pip install agent-os          # Minimal (just base)
+    pip install agent-os-kernel[full]  # Everything
+    pip install agent-os-kernel        # Core
 """
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 __author__ = "Imran Siddique"
 __license__ = "MIT"
 
@@ -193,6 +201,38 @@ try:
 except ImportError:
     _MUTE_AGENT_AVAILABLE = False
 
+# ============================================================================
+# Local Components (Always Available)
+# ============================================================================
+
+# Stateless Kernel (MCP June 2026)
+from agent_os.stateless import (
+    StatelessKernel,
+    ExecutionContext,
+    ExecutionRequest,
+    ExecutionResult,
+    MemoryBackend as StatelessMemoryBackend,
+    stateless_execute,
+)
+
+# AGENTS.md Compatibility
+from agent_os.agents_compat import (
+    AgentsParser,
+    AgentConfig as AgentsConfig,  # Renamed to avoid conflict
+    AgentSkill,
+    discover_agents,
+)
+
+# Base Agent Classes
+from agent_os.base_agent import (
+    BaseAgent,
+    ToolUsingAgent,
+    AgentConfig,
+    AuditEntry,
+    PolicyDecision,
+    TypedResult,
+)
+
 # ============================================================================
 # Availability Flags
 # ============================================================================
@@ -300,4 +340,26 @@ __all__ = [
     "MuteAgent",
     "ReasoningAgent",
     "ExecutionAgent",
+    
+    # Stateless API (MCP June 2026)
+    "StatelessKernel",
+    "ExecutionContext",
+    "ExecutionRequest",
+    "ExecutionResult",
+    "StatelessMemoryBackend",
+    "stateless_execute",
+    
+    # Base Agent Classes
+    "BaseAgent",
+    "ToolUsingAgent",
+    "AgentConfig",
+    "AuditEntry",
+    "PolicyDecision",
+    "TypedResult",
+    
+    # AGENTS.md Compatibility
+    "AgentsParser",
+    "AgentsConfig",
+    "AgentSkill",
+    "discover_agents",
 ]

agent_os/agents_compat.py

@@ -0,0 +1,286 @@
+"""
+AGENTS.md Compatibility for Agent OS.
+
+Parses OpenAI/Anthropic standard .agents/ directory structure
+and maps to Agent OS kernel policies.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import re
+import yaml
+
+
+@dataclass
+class AgentSkill:
+    """Parsed agent skill/capability."""
+    name: str
+    description: str
+    allowed: bool = True
+    requires_approval: bool = False
+    read_only: bool = False
+    constraints: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentConfig:
+    """Parsed agent configuration from AGENTS.md."""
+    name: str
+    description: str
+    skills: List[AgentSkill]
+    policies: List[str]
+    instructions: str
+    security_config: Dict[str, Any] = field(default_factory=dict)
+
+
+class AgentsParser:
+    """
+    Parse .agents/ directory structure.
+    
+    Supports:
+    - agents.md (OpenAI/Anthropic standard)
+    - security.md (Agent OS extension)
+    - YAML front matter
+    
+    Usage:
+        parser = AgentsParser()
+        config = parser.parse_directory("./my-project/.agents")
+        
+        # Convert to kernel policies
+        policies = parser.to_kernel_policies(config)
+    """
+    
+    def __init__(self):
+        self.skill_patterns = [
+            r"^[-*]\s+(.+)$",  # - skill or * skill
+            r"^(\d+)\.\s+(.+)$",  # 1. skill
+        ]
+    
+    def parse_directory(self, path: str) -> AgentConfig:
+        """Parse .agents/ directory."""
+        agents_dir = Path(path)
+        
+        if not agents_dir.exists():
+            raise FileNotFoundError(f"Agents directory not found: {path}")
+        
+        # Parse main agents.md
+        agents_md = agents_dir / "agents.md"
+        if not agents_md.exists():
+            agents_md = agents_dir / "AGENTS.md"
+        
+        config = self._parse_agents_md(agents_md) if agents_md.exists() else AgentConfig(
+            name="default",
+            description="",
+            skills=[],
+            policies=[],
+            instructions=""
+        )
+        
+        # Parse security.md (Agent OS extension)
+        security_md = agents_dir / "security.md"
+        if security_md.exists():
+            config.security_config = self._parse_security_md(security_md)
+        
+        return config
+    
+    def _parse_agents_md(self, path: Path) -> AgentConfig:
+        """Parse agents.md file."""
+        content = path.read_text(encoding="utf-8")
+        
+        # Extract YAML front matter if present
+        front_matter = {}
+        if content.startswith("---"):
+            end = content.find("---", 3)
+            if end != -1:
+                yaml_content = content[3:end]
+                front_matter = yaml.safe_load(yaml_content) or {}
+                content = content[end + 3:].strip()
+        
+        # Parse sections
+        name = front_matter.get("name", "agent")
+        description = ""
+        skills = []
+        instructions = content
+        
+        # Find "You can:" or "Capabilities:" section
+        can_match = re.search(r"(?:You can|Capabilities|Skills):\s*\n((?:[-*\d].*\n?)+)", content, re.IGNORECASE)
+        if can_match:
+            skills_text = can_match.group(1)
+            skills = self._parse_skills(skills_text)
+        
+        # Find description (first paragraph)
+        lines = content.split("\n")
+        for line in lines:
+            line = line.strip()
+            if line and not line.startswith(("#", "-", "*", "You can", "Capabilities")):
+                description = line
+                break
+        
+        return AgentConfig(
+            name=name,
+            description=description,
+            skills=skills,
+            policies=front_matter.get("policies", []),
+            instructions=instructions,
+            security_config=front_matter.get("security", {})
+        )
+    
+    def _parse_skills(self, text: str) -> List[AgentSkill]:
+        """Parse skills from bullet list."""
+        skills = []
+        
+        for line in text.strip().split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+            
+            # Extract skill text
+            skill_text = re.sub(r"^[-*\d.]+\s*", "", line)
+            
+            # Parse constraints from parentheses
+            constraints = {}
+            read_only = False
+            requires_approval = False
+            
+            # Check for (read-only), (requires approval), etc.
+            if "(read-only)" in skill_text.lower() or "(read only)" in skill_text.lower():
+                read_only = True
+                skill_text = re.sub(r"\s*\(read[- ]?only\)", "", skill_text, flags=re.IGNORECASE)
+            
+            if "(requires approval)" in skill_text.lower():
+                requires_approval = True
+                skill_text = re.sub(r"\s*\(requires approval\)", "", skill_text, flags=re.IGNORECASE)
+            
+            skills.append(AgentSkill(
+                name=self._skill_to_action(skill_text),
+                description=skill_text.strip(),
+                read_only=read_only,
+                requires_approval=requires_approval,
+                constraints=constraints
+            ))
+        
+        return skills
+    
+    def _skill_to_action(self, skill: str) -> str:
+        """Convert skill description to action name."""
+        skill_lower = skill.lower()
+        
+        # Map common patterns
+        mappings = {
+            "query database": "database_query",
+            "read database": "database_query",
+            "write to database": "database_write",
+            "send email": "send_email",
+            "write file": "file_write",
+            "read file": "file_read",
+            "call api": "api_call",
+            "execute code": "code_execution",
+            "search": "search",
+            "browse": "web_browse",
+        }
+        
+        for pattern, action in mappings.items():
+            if pattern in skill_lower:
+                return action
+        
+        # Default: snake_case the skill
+        return re.sub(r"[^a-z0-9]+", "_", skill_lower).strip("_")
+    
+    def _parse_security_md(self, path: Path) -> Dict[str, Any]:
+        """Parse security.md (Agent OS extension)."""
+        content = path.read_text(encoding="utf-8")
+        
+        # Try YAML front matter first
+        if content.startswith("---"):
+            end = content.find("---", 3)
+            if end != -1:
+                yaml_content = content[3:end]
+                return yaml.safe_load(yaml_content) or {}
+        
+        # Try full YAML
+        try:
+            return yaml.safe_load(content) or {}
+        except yaml.YAMLError:
+            pass
+        
+        return {}
+    
+    def to_kernel_policies(self, config: AgentConfig) -> Dict[str, Any]:
+        """
+        Convert AgentConfig to Agent OS kernel policies.
+        
+        Returns policy configuration for Control Plane.
+        """
+        policies = {
+            "name": config.name,
+            "version": "1.0",
+            "rules": []
+        }
+        
+        # Convert skills to rules
+        for skill in config.skills:
+            rule = {
+                "action": skill.name,
+                "effect": "allow" if skill.allowed else "deny",
+            }
+            
+            if skill.read_only:
+                rule["mode"] = "read_only"
+            
+            if skill.requires_approval:
+                rule["requires_approval"] = True
+            
+            if skill.constraints:
+                rule["constraints"] = skill.constraints
+            
+            policies["rules"].append(rule)
+        
+        # Add security config
+        if config.security_config:
+            sec = config.security_config
+            
+            if "signals" in sec:
+                policies["allowed_signals"] = sec["signals"]
+            
+            if "max_tokens" in sec:
+                policies["limits"] = {"max_tokens": sec["max_tokens"]}
+        
+        return policies
+
+
+def discover_agents(root_dir: str = ".") -> List[AgentConfig]:
+    """
+    Discover all agent configurations in a repository.
+    
+    Looks for:
+    - .agents/agents.md
+    - .agents/AGENTS.md
+    - agents.md (root)
+    - AGENTS.md (root)
+    
+    Returns list of parsed configurations.
+    """
+    parser = AgentsParser()
+    configs = []
+    root = Path(root_dir)
+    
+    # Check .agents/ directory
+    agents_dir = root / ".agents"
+    if agents_dir.exists():
+        try:
+            configs.append(parser.parse_directory(str(agents_dir)))
+        except Exception:
+            pass
+    
+    # Check root agents.md
+    for name in ["agents.md", "AGENTS.md"]:
+        agents_md = root / name
+        if agents_md.exists():
+            try:
+                config = parser._parse_agents_md(agents_md)
+                configs.append(config)
+            except Exception:
+                pass
+    
+    return configs

agent_os/base_agent.py

@@ -0,0 +1,308 @@
+"""
+Base Agent Module - Reusable base classes for Agent OS agents.
+
+Provides a consistent pattern for building agents that run under
+the Agent OS kernel with policy governance, audit logging, and
+tool integration.
+
+Example:
+    >>> from agent_os.base_agent import BaseAgent, AgentConfig
+    >>> 
+    >>> class MyAgent(BaseAgent):
+    ...     async def run(self, task: str) -> ExecutionResult:
+    ...         return await self._execute("process", {"task": task})
+    >>> 
+    >>> agent = MyAgent(AgentConfig(agent_id="my-agent", policies=["read_only"]))
+    >>> result = await agent.run("hello")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Generic
+from uuid import uuid4
+
+from agent_os.stateless import (
+    StatelessKernel,
+    ExecutionContext,
+    ExecutionResult,
+    MemoryBackend,
+    StateBackend,
+)
+
+
+class PolicyDecision(Enum):
+    """Result of policy evaluation."""
+    ALLOW = "allow"
+    DENY = "deny"
+    AUDIT = "audit"  # Allow but log for review
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for an agent instance.
+    
+    Attributes:
+        agent_id: Unique identifier for this agent instance
+        policies: List of policy names to apply (e.g., ["read_only", "no_pii"])
+        metadata: Additional metadata for the agent
+        state_backend: Optional custom state backend (defaults to in-memory)
+    """
+    agent_id: str
+    policies: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    state_backend: Optional[StateBackend] = None
+
+
+@dataclass
+class AuditEntry:
+    """An entry in the agent's audit log."""
+    timestamp: datetime
+    agent_id: str
+    request_id: str
+    action: str
+    params: Dict[str, Any]
+    decision: PolicyDecision
+    result_success: Optional[bool] = None
+    error: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "timestamp": self.timestamp.isoformat(),
+            "agent_id": self.agent_id,
+            "request_id": self.request_id,
+            "action": self.action,
+            "params_keys": list(self.params.keys()),  # Don't log full params
+            "decision": self.decision.value,
+            "result_success": self.result_success,
+            "error": self.error,
+        }
+
+
+class BaseAgent(ABC):
+    """Abstract base class for Agent OS agents.
+    
+    Provides:
+    - Kernel integration with policy enforcement
+    - Execution context management
+    - Audit logging
+    - Common helper methods
+    
+    Subclasses must implement the `run` method which defines
+    the agent's main task.
+    
+    Example:
+        >>> class GreeterAgent(BaseAgent):
+        ...     async def run(self, name: str) -> ExecutionResult:
+        ...         result = await self._execute(
+        ...             action="greet",
+        ...             params={"name": name, "output": f"Hello, {name}!"}
+        ...         )
+        ...         return result
+        >>> 
+        >>> agent = GreeterAgent(AgentConfig(agent_id="greeter"))
+        >>> result = await agent.run("World")
+        >>> print(result.data)  # "Hello, World!"
+    """
+    
+    def __init__(self, config: AgentConfig):
+        """Initialize the agent.
+        
+        Args:
+            config: Agent configuration including ID, policies, and backend
+        """
+        self._config = config
+        self._kernel = StatelessKernel(
+            backend=config.state_backend or MemoryBackend()
+        )
+        self._audit_log: List[AuditEntry] = []
+    
+    @property
+    def agent_id(self) -> str:
+        """Get the agent's unique identifier."""
+        return self._config.agent_id
+    
+    @property
+    def policies(self) -> List[str]:
+        """Get the agent's active policies."""
+        return self._config.policies.copy()
+    
+    def _new_context(self, **extra_metadata) -> ExecutionContext:
+        """Create a new execution context for a request.
+        
+        Args:
+            **extra_metadata: Additional metadata to include
+            
+        Returns:
+            Fresh ExecutionContext with agent's default settings
+        """
+        metadata = {**self._config.metadata, **extra_metadata}
+        return ExecutionContext(
+            agent_id=self._config.agent_id,
+            policies=self._config.policies.copy(),
+            metadata=metadata,
+        )
+    
+    async def _execute(
+        self,
+        action: str,
+        params: Dict[str, Any],
+        context: Optional[ExecutionContext] = None,
+    ) -> ExecutionResult:
+        """Execute an action through the kernel with policy checks.
+        
+        This is the primary method for agents to perform actions.
+        All actions are:
+        1. Checked against configured policies
+        2. Logged for audit
+        3. Executed through the kernel
+        
+        Args:
+            action: Name of the action to execute
+            params: Parameters for the action
+            context: Optional custom context (uses default if None)
+            
+        Returns:
+            ExecutionResult with success status, data, and any errors
+        """
+        ctx = context or self._new_context()
+        request_id = str(uuid4())[:16]
+        
+        # Create audit entry
+        audit = AuditEntry(
+            timestamp=datetime.now(timezone.utc),
+            agent_id=self._config.agent_id,
+            request_id=request_id,
+            action=action,
+            params=params,
+            decision=PolicyDecision.ALLOW,  # Will be updated
+        )
+        
+        # Execute through kernel
+        result = await self._kernel.execute(action, params, ctx)
+        
+        # Update audit entry with result
+        if result.signal == "SIGKILL":
+            audit.decision = PolicyDecision.DENY
+        audit.result_success = result.success
+        audit.error = result.error
+        
+        self._audit_log.append(audit)
+        
+        return result
+    
+    def get_audit_log(self) -> List[Dict[str, Any]]:
+        """Get the agent's audit log.
+        
+        Returns:
+            List of audit entries as dictionaries
+        """
+        return [entry.to_dict() for entry in self._audit_log]
+    
+    def clear_audit_log(self) -> None:
+        """Clear the agent's audit log."""
+        self._audit_log.clear()
+    
+    @abstractmethod
+    async def run(self, *args, **kwargs) -> ExecutionResult:
+        """Run the agent's main task.
+        
+        Subclasses must implement this method to define the agent's
+        primary functionality.
+        
+        Returns:
+            ExecutionResult with the outcome of the task
+        """
+        pass
+
+
+class ToolUsingAgent(BaseAgent):
+    """Base class for agents that use registered tools from ATR.
+    
+    Extends BaseAgent with tool discovery and execution capabilities.
+    Tools are executed through the kernel for policy enforcement.
+    
+    Example:
+        >>> class AnalysisAgent(ToolUsingAgent):
+        ...     async def run(self, data: str) -> ExecutionResult:
+        ...         # Use registered tools
+        ...         parsed = await self._use_tool("json_parser", {"text": data})
+        ...         return parsed
+    """
+    
+    def __init__(self, config: AgentConfig, tools: Optional[List[str]] = None):
+        """Initialize the tool-using agent.
+        
+        Args:
+            config: Agent configuration
+            tools: Optional list of tool names this agent is allowed to use
+        """
+        super().__init__(config)
+        self._allowed_tools = set(tools) if tools else None
+    
+    async def _use_tool(
+        self,
+        tool_name: str,
+        params: Dict[str, Any],
+    ) -> ExecutionResult:
+        """Use a registered tool through the kernel.
+        
+        Args:
+            tool_name: Name of the tool to use
+            params: Parameters to pass to the tool
+            
+        Returns:
+            ExecutionResult from tool execution
+        """
+        # Check tool allowlist if configured
+        if self._allowed_tools and tool_name not in self._allowed_tools:
+            return ExecutionResult(
+                success=False,
+                data=None,
+                error=f"Tool '{tool_name}' not in allowed tools list",
+            )
+        
+        # Execute through kernel
+        return await self._execute(
+            action=f"tool:{tool_name}",
+            params=params,
+        )
+    
+    def list_allowed_tools(self) -> Optional[List[str]]:
+        """Get list of allowed tools, or None if all tools allowed."""
+        return list(self._allowed_tools) if self._allowed_tools else None
+
+
+# Type variable for generic agent results
+T = TypeVar("T")
+
+
+@dataclass
+class TypedResult(Generic[T]):
+    """A typed wrapper for execution results.
+    
+    Useful when you want type hints on the result data.
+    """
+    success: bool
+    data: Optional[T] = None
+    error: Optional[str] = None
+    
+    @classmethod
+    def from_execution_result(
+        cls,
+        result: ExecutionResult,
+        transform: Optional[Callable[[Any], T]] = None,
+    ) -> "TypedResult[T]":
+        """Create from an ExecutionResult with optional transformation."""
+        data = None
+        if result.success and result.data is not None:
+            data = transform(result.data) if transform else result.data
+        return cls(
+            success=result.success,
+            data=data,
+            error=result.error,
+        )