aury-agent 0.0.4__py3-none-any.whl

aury/agents/backends/memory/types.py

@@ -0,0 +1,136 @@
+"""Memory backend types and protocols."""
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class MemoryBackend(Protocol):
+    """Protocol for long-term memory storage.
+    
+    Handles persistent memory entries with semantic search capability.
+    Used for RAG, knowledge recall, and conversation summaries.
+    
+    Example usage:
+        # Add memory
+        memory_id = await backend.add(
+            session_id="sess_123",
+            content="User prefers dark mode and Python",
+            namespace="preferences",
+            metadata={"importance": 0.8},
+        )
+        
+        # Search memories
+        results = await backend.search(
+            session_id="sess_123",
+            query="what are user preferences",
+            limit=5,
+        )
+        
+        # Delete memories from invocation (for revert)
+        await backend.delete_by_invocation("sess_123", "inv_456")
+    """
+    
+    async def add(
+        self,
+        session_id: str,
+        content: str,
+        invocation_id: str | None = None,
+        namespace: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Add a memory entry.
+        
+        Args:
+            session_id: Session ID
+            content: Memory content text
+            invocation_id: Optional invocation ID for grouping/revert
+            namespace: Optional namespace for categorization
+            metadata: Optional metadata (importance, tags, etc.)
+            
+        Returns:
+            Generated memory entry ID
+        """
+        ...
+    
+    async def search(
+        self,
+        session_id: str,
+        query: str,
+        namespace: str | None = None,
+        limit: int = 10,
+    ) -> list[dict[str, Any]]:
+        """Search memories by semantic relevance.
+        
+        Args:
+            session_id: Session ID
+            query: Search query
+            namespace: Optional namespace filter
+            limit: Max results to return
+            
+        Returns:
+            List of memory dicts with scores, ordered by relevance:
+            [{"id": str, "content": str, "score": float, "metadata": dict}, ...]
+        """
+        ...
+    
+    async def get(self, id: str) -> dict[str, Any] | None:
+        """Get memory by ID.
+        
+        Args:
+            id: Memory entry ID
+            
+        Returns:
+            Memory dict or None if not found
+        """
+        ...
+    
+    async def delete(self, id: str) -> bool:
+        """Delete a memory entry.
+        
+        Args:
+            id: Memory entry ID
+            
+        Returns:
+            True if deleted, False if not found
+        """
+        ...
+    
+    async def delete_by_invocation(
+        self,
+        session_id: str,
+        invocation_id: str,
+        namespace: str | None = None,
+    ) -> int:
+        """Delete memories by invocation (for revert).
+        
+        Args:
+            session_id: Session ID
+            invocation_id: Invocation ID to delete
+            namespace: Optional namespace filter
+            
+        Returns:
+            Number of memories deleted
+        """
+        ...
+    
+    async def list(
+        self,
+        session_id: str,
+        namespace: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """List memories for a session (without search).
+        
+        Args:
+            session_id: Session ID
+            namespace: Optional namespace filter
+            limit: Max results to return
+            
+        Returns:
+            List of memory dicts, ordered by created_at desc
+        """
+        ...
+
+
+__all__ = ["MemoryBackend"]

aury/agents/backends/message/__init__.py

@@ -0,0 +1,9 @@
+"""Message backend."""
+from .types import MessageBackend, MessageType
+from .memory import InMemoryMessageBackend
+
+__all__ = [
+    "MessageBackend",
+    "MessageType",
+    "InMemoryMessageBackend",
+]

aury/agents/backends/message/memory.py

@@ -0,0 +1,122 @@
+"""In-memory message backend implementation."""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .types import MessageType
+
+
+class InMemoryMessageBackend:
+    """In-memory implementation of MessageBackend.
+    
+    Stores both truncated and raw messages in separate dicts.
+    Suitable for testing and simple single-process use cases.
+    """
+    
+    def __init__(self) -> None:
+        # Key format: "{session_id}" or "{session_id}:{namespace}"
+        # Value: list of message dicts
+        self._truncated: dict[str, list[dict[str, Any]]] = {}
+        self._raw: dict[str, list[dict[str, Any]]] = {}
+    
+    def _make_key(self, session_id: str, namespace: str | None) -> str:
+        if namespace:
+            return f"{session_id}:{namespace}"
+        return session_id
+    
+    def _get_store(self, type: MessageType) -> dict[str, list[dict[str, Any]]]:
+        return self._truncated if type == "truncated" else self._raw
+    
+    async def add(
+        self,
+        session_id: str,
+        message: dict[str, Any],
+        type: MessageType = "truncated",
+        agent_id: str | None = None,
+        namespace: str | None = None,
+        invocation_id: str | None = None,
+    ) -> None:
+        """Add a message."""
+        key = self._make_key(session_id, namespace)
+        store = self._get_store(type)
+        
+        if key not in store:
+            store[key] = []
+        
+        # Add metadata
+        msg = {
+            **message,
+            "agent_id": agent_id,
+            "invocation_id": invocation_id,
+            "created_at": datetime.now().isoformat(),
+        }
+        store[key].append(msg)
+    
+    async def get(
+        self,
+        session_id: str,
+        type: MessageType = "truncated",
+        agent_id: str | None = None,
+        namespace: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get messages."""
+        key = self._make_key(session_id, namespace)
+        store = self._get_store(type)
+        messages = store.get(key, [])
+        
+        # Filter by agent_id if specified
+        if agent_id:
+            messages = [m for m in messages if m.get("agent_id") == agent_id]
+        
+        # Apply limit (return last N messages)
+        if limit:
+            messages = messages[-limit:]
+        
+        return messages.copy()
+    
+    async def delete_by_invocation(
+        self,
+        session_id: str,
+        invocation_id: str,
+        type: MessageType | None = None,
+        namespace: str | None = None,
+    ) -> int:
+        """Delete messages by invocation."""
+        key = self._make_key(session_id, namespace)
+        deleted = 0
+        
+        types_to_delete = [type] if type else ["truncated", "raw"]
+        
+        for t in types_to_delete:
+            store = self._get_store(t)
+            if key in store:
+                original = store[key]
+                store[key] = [m for m in original if m.get("invocation_id") != invocation_id]
+                deleted += len(original) - len(store[key])
+        
+        return deleted
+    
+    async def clear(
+        self,
+        session_id: str,
+        type: MessageType | None = None,
+        namespace: str | None = None,
+    ) -> int:
+        """Clear all messages for a session."""
+        key = self._make_key(session_id, namespace)
+        deleted = 0
+        
+        types_to_clear = [type] if type else ["truncated", "raw"]
+        
+        for t in types_to_clear:
+            store = self._get_store(t)
+            if key in store:
+                deleted += len(store[key])
+                del store[key]
+        
+        return deleted
+
+
+__all__ = ["InMemoryMessageBackend"]

aury/agents/backends/message/types.py

@@ -0,0 +1,124 @@
+"""Message backend types and protocols."""
+from __future__ import annotations
+
+from typing import Any, Literal, Protocol, runtime_checkable
+
+
+MessageType = Literal["truncated", "raw"]
+
+
+@runtime_checkable
+class MessageBackend(Protocol):
+    """Protocol for message storage.
+    
+    Handles both truncated (context window) and raw (full history) messages
+    through a unified interface with type parameter.
+    
+    - truncated: Messages kept in context window, may be summarized/trimmed
+    - raw: Full original messages for audit/replay
+    
+    Example usage:
+        # Add truncated message (for LLM context)
+        await backend.add(
+            session_id="sess_123",
+            message={"role": "user", "content": "Hello"},
+            type="truncated",
+        )
+        
+        # Add raw message (for audit)
+        await backend.add(
+            session_id="sess_123",
+            message={"role": "user", "content": "Hello", "attachments": [...]},
+            type="raw",
+        )
+        
+        # Get messages for LLM
+        messages = await backend.get("sess_123", type="truncated", limit=50)
+        
+        # Get raw history
+        raw_messages = await backend.get("sess_123", type="raw")
+    """
+    
+    async def add(
+        self,
+        session_id: str,
+        message: dict[str, Any],
+        type: MessageType = "truncated",
+        agent_id: str | None = None,
+        namespace: str | None = None,
+        invocation_id: str | None = None,
+    ) -> None:
+        """Add a message.
+        
+        Args:
+            session_id: Session ID
+            message: Message dict (role, content, tool_call_id, etc.)
+            type: Message type - "truncated" or "raw"
+            agent_id: Optional agent ID
+            namespace: Optional namespace for sub-agent isolation
+            invocation_id: Optional invocation ID for grouping
+        """
+        ...
+    
+    async def get(
+        self,
+        session_id: str,
+        type: MessageType = "truncated",
+        agent_id: str | None = None,
+        namespace: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get messages.
+        
+        Args:
+            session_id: Session ID
+            type: Message type - "truncated" or "raw"
+            agent_id: Optional filter by agent
+            namespace: Optional namespace filter
+            limit: Max messages to return (None = all)
+            
+        Returns:
+            List of message dicts in chronological order
+        """
+        ...
+    
+    async def delete_by_invocation(
+        self,
+        session_id: str,
+        invocation_id: str,
+        type: MessageType | None = None,
+        namespace: str | None = None,
+    ) -> int:
+        """Delete messages by invocation (for revert).
+        
+        Args:
+            session_id: Session ID
+            invocation_id: Invocation ID to delete
+            type: Message type to delete, None = both types
+            namespace: Optional namespace filter
+            
+        Returns:
+            Number of messages deleted
+        """
+        ...
+    
+    async def clear(
+        self,
+        session_id: str,
+        type: MessageType | None = None,
+        namespace: str | None = None,
+    ) -> int:
+        """Clear all messages for a session.
+        
+        Args:
+            session_id: Session ID
+            type: Message type to clear, None = both types
+            namespace: Optional namespace filter
+            
+        Returns:
+            Number of messages deleted
+        """
+        ...
+
+
+__all__ = ["MessageBackend", "MessageType"]

aury/agents/backends/sandbox.py

@@ -0,0 +1,275 @@
+"""Sandbox-based backend implementations.
+
+Provides ShellBackend and CodeBackend implementations that execute
+commands and code in isolated sandbox environments.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, AsyncIterator
+
+from .shell import ShellBackend, ShellResult
+from .code import CodeBackend, CodeResult
+
+if TYPE_CHECKING:
+    from ..sandbox import Sandbox, SandboxProvider, SandboxConfig
+
+
+class SandboxShellBackend:
+    """Shell backend that executes commands in a sandbox.
+    
+    Commands are executed in an isolated container environment,
+    providing security isolation from the host system.
+    
+    Usage:
+        provider = LocalSandboxProvider()
+        backend = SandboxShellBackend(provider)
+        
+        result = await backend.execute("ls -la")
+    """
+    
+    def __init__(
+        self,
+        provider: "SandboxProvider",
+        config: "SandboxConfig | None" = None,
+        reuse_sandbox: bool = True,
+    ) -> None:
+        """Initialize sandbox shell backend.
+        
+        Args:
+            provider: Sandbox provider for creating sandboxes
+            config: Optional sandbox configuration
+            reuse_sandbox: If True, reuse sandbox across commands (default)
+        """
+        self.provider = provider
+        self.config = config
+        self.reuse_sandbox = reuse_sandbox
+        self._sandbox: "Sandbox | None" = None
+    
+    async def _get_sandbox(self) -> "Sandbox":
+        """Get or create sandbox instance."""
+        if self._sandbox is None or not self.reuse_sandbox:
+            self._sandbox = await self.provider.create(self.config)
+        return self._sandbox
+    
+    async def execute(
+        self,
+        command: str,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        timeout: int = 120,
+    ) -> ShellResult:
+        """Execute a shell command in the sandbox.
+        
+        Args:
+            command: Shell command to execute
+            cwd: Working directory (relative to sandbox workdir)
+            env: Environment variables
+            timeout: Timeout in seconds
+            
+        Returns:
+            ShellResult with stdout, stderr, exit_code
+        """
+        sandbox = await self._get_sandbox()
+        
+        result = await sandbox.execute(
+            command,
+            workdir=cwd,
+            env=env,
+            timeout=timeout,
+        )
+        
+        return ShellResult(
+            stdout=result.stdout,
+            stderr=result.stderr,
+            exit_code=result.exit_code,
+            command=command,
+            cwd=cwd or "",
+            duration_ms=result.duration_ms,
+        )
+    
+    async def execute_stream(
+        self,
+        command: str,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        timeout: int = 120,
+    ) -> AsyncIterator[str]:
+        """Execute command with streaming output.
+        
+        Note: Basic implementation - executes and yields result.
+        Full streaming requires sandbox API support.
+        """
+        result = await self.execute(command, cwd, env, timeout)
+        if result.stdout:
+            yield result.stdout
+        if result.stderr:
+            yield result.stderr
+    
+    async def cleanup(self) -> None:
+        """Cleanup sandbox resources."""
+        if self._sandbox:
+            await self._sandbox.destroy()
+            self._sandbox = None
+
+
+class SandboxCodeBackend:
+    """Code backend that executes code in a sandbox.
+    
+    Supports multiple programming languages by writing code
+    to files and executing with appropriate interpreters.
+    
+    Usage:
+        provider = LocalSandboxProvider()
+        backend = SandboxCodeBackend(provider)
+        
+        result = await backend.execute("print('hello')", language="python")
+    """
+    
+    # Language configurations
+    LANGUAGE_CONFIG = {
+        "python": {
+            "extension": ".py",
+            "command": "python3",
+        },
+        "python3": {
+            "extension": ".py", 
+            "command": "python3",
+        },
+        "javascript": {
+            "extension": ".js",
+            "command": "node",
+        },
+        "js": {
+            "extension": ".js",
+            "command": "node",
+        },
+        "typescript": {
+            "extension": ".ts",
+            "command": "npx ts-node",
+        },
+        "ts": {
+            "extension": ".ts",
+            "command": "npx ts-node",
+        },
+        "bash": {
+            "extension": ".sh",
+            "command": "bash",
+        },
+        "sh": {
+            "extension": ".sh",
+            "command": "sh",
+        },
+        "ruby": {
+            "extension": ".rb",
+            "command": "ruby",
+        },
+        "php": {
+            "extension": ".php",
+            "command": "php",
+        },
+        "go": {
+            "extension": ".go",
+            "command": "go run",
+        },
+        "rust": {
+            "extension": ".rs",
+            "command": "rustc -o /tmp/out && /tmp/out",  # Compile and run
+        },
+    }
+    
+    def __init__(
+        self,
+        provider: "SandboxProvider",
+        config: "SandboxConfig | None" = None,
+        reuse_sandbox: bool = True,
+    ) -> None:
+        """Initialize sandbox code backend.
+        
+        Args:
+            provider: Sandbox provider for creating sandboxes
+            config: Optional sandbox configuration
+            reuse_sandbox: If True, reuse sandbox across executions (default)
+        """
+        self.provider = provider
+        self.config = config
+        self.reuse_sandbox = reuse_sandbox
+        self._sandbox: "Sandbox | None" = None
+        self._exec_counter = 0
+    
+    @property
+    def supported_languages(self) -> list[str]:
+        """List of supported programming languages."""
+        return list(self.LANGUAGE_CONFIG.keys())
+    
+    async def _get_sandbox(self) -> "Sandbox":
+        """Get or create sandbox instance."""
+        if self._sandbox is None or not self.reuse_sandbox:
+            self._sandbox = await self.provider.create(self.config)
+        return self._sandbox
+    
+    async def execute(
+        self,
+        code: str,
+        language: str = "python",
+        timeout: int = 120,
+    ) -> CodeResult:
+        """Execute code in the sandbox.
+        
+        Args:
+            code: Source code to execute
+            language: Programming language
+            timeout: Timeout in seconds
+            
+        Returns:
+            CodeResult with output, error, exit_code
+        """
+        # Normalize language name
+        lang_lower = language.lower()
+        if lang_lower not in self.LANGUAGE_CONFIG:
+            return CodeResult(
+                output="",
+                error=f"Unsupported language: {language}. "
+                      f"Supported: {', '.join(self.supported_languages)}",
+                exit_code=1,
+                language=language,
+            )
+        
+        lang_config = self.LANGUAGE_CONFIG[lang_lower]
+        sandbox = await self._get_sandbox()
+        
+        # Generate unique filename
+        self._exec_counter += 1
+        filename = f"code_{self._exec_counter}{lang_config['extension']}"
+        filepath = f"/workspace/{filename}"
+        
+        # Write code to sandbox
+        await sandbox.write_file(filepath, code)
+        
+        # Build execution command
+        command = f"{lang_config['command']} {filepath}"
+        
+        # Execute
+        result = await sandbox.execute(
+            command,
+            timeout=timeout,
+        )
+        
+        return CodeResult(
+            output=result.stdout,
+            error=result.stderr,
+            exit_code=result.exit_code,
+            language=language,
+            duration_ms=result.duration_ms,
+        )
+    
+    async def cleanup(self) -> None:
+        """Cleanup sandbox resources."""
+        if self._sandbox:
+            await self._sandbox.destroy()
+            self._sandbox = None
+
+
+__all__ = [
+    "SandboxShellBackend",
+    "SandboxCodeBackend",
+]

aury/agents/backends/session/__init__.py

@@ -0,0 +1,8 @@
+"""Session backend."""
+from .types import SessionBackend
+from .memory import InMemorySessionBackend
+
+__all__ = [
+    "SessionBackend",
+    "InMemorySessionBackend",
+]