aury-agent 0.0.4__py3-none-any.whl

aury/__init__.py

@@ -0,0 +1,2 @@
+"""Aury - Agent Framework."""
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

aury/agents/__init__.py

@@ -0,0 +1,55 @@
+"""Aury Agent Framework.
+
+A framework supporting both React Agent (autonomous loop) and Workflow (DAG orchestration).
+
+Package Structure:
+    aury.agents.backends      - Backend protocols and implementations
+    aury.agents.core          - Core infrastructure (types, bus, context)
+    aury.agents.llm           - LLM adapters
+    aury.agents.plugin        - Middleware system
+    aury.agents.memory        - Memory system
+    aury.agents.react         - ReactAgent
+    aury.agents.workflow      - Workflow orchestration
+    aury.agents.tool          - Tool system
+    aury.agents.skill         - Skill system (capability bundles)
+    aury.agents.sandbox       - Sandbox system (isolated execution)
+    aury.agents.cli           - CLI
+
+Quick Start:
+    from aury.agents import ReactAgent, AgentConfig
+    from aury.agents.core.types import Session, PromptInput
+    from aury.agents.backends import MemoryStateBackend
+    from aury.agents.core.event_bus import EventBus, Bus
+    from aury.agents.llm import MockLLMProvider
+    from aury.agents.tool import ToolSet
+"""
+
+__version__ = "0.1.0"
+
+# Only export the most commonly used classes at top level
+# For other classes, import from submodules directly
+from .core.base import BaseAgent, AgentConfig, ToolInjectionMode
+from .core.event_bus import EventBus, Events
+from .core.context import InvocationContext
+from .core.types import Session, PromptInput, generate_id
+from .react import ReactAgent
+from .workflow import WorkflowAgent
+from .context_providers import ContextProvider, AgentContext
+
+__all__ = [
+    "__version__",
+    "BaseAgent",
+    "AgentConfig",
+    "ToolInjectionMode",
+    "EventBus",
+    "Events",
+    "InvocationContext",
+    "Session",
+    "PromptInput",
+    "generate_id",
+    "ReactAgent",
+    "WorkflowAgent",
+    # Providers
+    "ContextProvider",
+    "AgentContext",
+]

aury/agents/a2a/__init__.py

@@ -0,0 +1,168 @@
+"""A2A (Agent-to-Agent) communication module.
+
+TODO: Implement A2A protocol support for inter-agent communication.
+
+This module will provide:
+- A2AClient: Client for calling remote A2A-compliant agents
+- A2AServer: Server to expose agent as A2A endpoint
+- AgentCard: Agent capability declaration
+- AgentSkill: Skill declaration for AgentCard
+
+Reference: Google A2A Protocol
+https://github.com/google-a2a/a2a-samples
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+
+# =============================================================================
+# TODO: Agent Card & Skill
+# =============================================================================
+
+@dataclass
+class AgentSkill:
+    """Skill declaration for AgentCard.
+    
+    TODO: Implement skill definition.
+    """
+    id: str
+    name: str
+    description: str
+    input_modes: list[str] = field(default_factory=lambda: ["text"])
+    output_modes: list[str] = field(default_factory=lambda: ["text"])
+    examples: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentCard:
+    """Agent capability declaration.
+    
+    TODO: Implement agent card for A2A discovery.
+    """
+    name: str
+    description: str
+    url: str = ""
+    version: str = "1.0.0"
+    capabilities: dict[str, Any] = field(default_factory=dict)
+    skills: list[AgentSkill] = field(default_factory=list)
+    default_input_modes: list[str] = field(default_factory=lambda: ["text"])
+    default_output_modes: list[str] = field(default_factory=lambda: ["text"])
+    authentication: dict[str, Any] = field(default_factory=dict)
+
+
+# =============================================================================
+# TODO: A2A Client
+# =============================================================================
+
+class A2AClient:
+    """Client for calling remote A2A-compliant agents.
+    
+    TODO: Implement A2A client.
+    
+    Usage:
+        # Discover agent
+        agent_card = await A2AClient.discover("http://example.com")
+        
+        # Send task
+        client = A2AClient(agent_card)
+        result = await client.send_task("Hello")
+        
+        # Stream task
+        async for event in client.stream_task("Generate report"):
+            print(event)
+    """
+    
+    def __init__(self, agent_card: AgentCard):
+        self.agent_card = agent_card
+        raise NotImplementedError("A2A client is not yet implemented")
+    
+    @classmethod
+    async def discover(cls, url: str) -> AgentCard:
+        """Discover agent capabilities from URL.
+        
+        TODO: Implement discovery via /.well-known/agent.json
+        """
+        raise NotImplementedError("A2A discovery is not yet implemented")
+    
+    @classmethod
+    def from_url(cls, url: str) -> "A2AClient":
+        """Create client from URL (discovers agent card first)."""
+        raise NotImplementedError("A2A client is not yet implemented")
+    
+    async def send_task(
+        self,
+        message: str,
+        accepted_output_modes: list[str] | None = None,
+    ) -> Any:
+        """Send task and wait for result.
+        
+        TODO: Implement synchronous task submission.
+        """
+        raise NotImplementedError("A2A send_task is not yet implemented")
+    
+    async def stream_task(
+        self,
+        message: str,
+        accepted_output_modes: list[str] | None = None,
+    ) -> AsyncIterator[Any]:
+        """Send task and stream results.
+        
+        TODO: Implement streaming task submission via SSE.
+        """
+        raise NotImplementedError("A2A stream_task is not yet implemented")
+        yield  # Make it a generator
+
+
+# =============================================================================
+# TODO: A2A Server
+# =============================================================================
+
+class A2AServer:
+    """Server to expose agent as A2A endpoint.
+    
+    TODO: Implement A2A server.
+    
+    Usage:
+        server = A2AServer(
+            agent=my_agent,
+            agent_card=agent_card,
+            host="0.0.0.0",
+            port=8080,
+        )
+        await server.start()
+    """
+    
+    def __init__(
+        self,
+        agent: Any,
+        agent_card: AgentCard,
+        host: str = "0.0.0.0",
+        port: int = 8080,
+    ):
+        self.agent = agent
+        self.agent_card = agent_card
+        self.host = host
+        self.port = port
+        raise NotImplementedError("A2A server is not yet implemented")
+    
+    async def start(self) -> None:
+        """Start the A2A server.
+        
+        TODO: Implement HTTP server with A2A protocol handlers.
+        """
+        raise NotImplementedError("A2A server is not yet implemented")
+    
+    async def stop(self) -> None:
+        """Stop the A2A server."""
+        raise NotImplementedError("A2A server is not yet implemented")
+
+
+__all__ = [
+    "AgentSkill",
+    "AgentCard",
+    "A2AClient",
+    "A2AServer",
+]

aury/agents/backends/__init__.py

@@ -0,0 +1,196 @@
+"""Backend protocols and implementations.
+
+Backends provide abstracted interfaces for various capabilities:
+
+Data Backends (storage):
+- SessionBackend: Session management
+- InvocationBackend: Invocation management
+- MessageBackend: Message storage (truncated/raw)
+- MemoryBackend: Long-term memory with search
+- ArtifactBackend: File/artifact storage
+- StateBackend: Generic key-value state
+
+Capability Backends:
+- SnapshotBackend: File state tracking and revert
+- ShellBackend: Shell command execution
+- FileBackend: File system operations
+- CodeBackend: Code execution
+- SubAgentBackend: Sub-agent registry and retrieval
+
+Backends Container:
+- Backends: Dataclass container for dependency injection
+"""
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+# Data backends - new architecture
+from .session import SessionBackend, InMemorySessionBackend
+from .invocation import InvocationBackend, InMemoryInvocationBackend
+from .message import MessageBackend, MessageType, InMemoryMessageBackend
+from .memory import MemoryBackend, InMemoryMemoryBackend
+from .artifact import ArtifactBackend, ArtifactSource, InMemoryArtifactBackend
+
+# State backend - simplified to key-value
+from .state import StateBackend, StateStore, StoreBasedStateBackend, SQLiteStateBackend, MemoryStateBackend, FileStateBackend, CompositeStateBackend
+
+# Capability backends - existing
+from .snapshot import SnapshotBackend, Patch, InMemorySnapshotBackend, GitSnapshotBackend, GitS3HybridBackend
+from .shell import ShellBackend, ShellResult, LocalShellBackend
+from .file import FileBackend, LocalFileBackend
+from .code import CodeBackend, CodeResult
+from .subagent import SubAgentBackend, AgentConfig, ListSubAgentBackend
+from .sandbox import SandboxShellBackend, SandboxCodeBackend
+
+
+@dataclass
+class Backends:
+    """Container for all backends.
+    
+    Provides a unified way to inject backends into agents and context.
+    
+    Data backends (for storage):
+    - session: Session management (required)
+    - invocation: Invocation management (required)
+    - message: Message storage (required)
+    - memory: Long-term memory (optional)
+    - artifact: Artifact storage (optional)
+    - state: Generic key-value state (optional)
+    
+    Capability backends (for actions):
+    - snapshot: File tracking and revert (optional)
+    - shell: Shell execution (optional)
+    - file: File operations (optional)
+    - code: Code execution (optional)
+    - subagent: Sub-agent registry (optional)
+    
+    Example:
+        # Create with defaults
+        backends = Backends.create_default()
+        
+        # Create with custom implementations
+        backends = Backends(
+            session=DatabaseSessionBackend(db),
+            invocation=DatabaseInvocationBackend(db),
+            message=DatabaseMessageBackend(db),
+            memory=VectorMemoryBackend(embedding_model),
+        )
+        
+        # Use in agent
+        agent = ReactAgent.create(llm=llm, backends=backends)
+    """
+    # Data backends - required
+    session: SessionBackend
+    invocation: InvocationBackend
+    message: MessageBackend
+    
+    # Data backends - optional
+    memory: MemoryBackend | None = None
+    artifact: ArtifactBackend | None = None
+    state: StateBackend | None = None
+    
+    # Capability backends - optional
+    snapshot: SnapshotBackend | None = None
+    shell: ShellBackend | None = None
+    file: FileBackend | None = None
+    code: CodeBackend | None = None
+    subagent: SubAgentBackend | None = None
+    
+    @classmethod
+    def create_default(cls) -> "Backends":
+        """Create Backends with default in-memory implementations.
+        
+        Suitable for testing and simple single-process use cases.
+        """
+        return cls(
+            session=InMemorySessionBackend(),
+            invocation=InMemoryInvocationBackend(),
+            message=InMemoryMessageBackend(),
+            memory=InMemoryMemoryBackend(),
+            artifact=InMemoryArtifactBackend(),
+            state=MemoryStateBackend(),
+        )
+    
+    @classmethod
+    def create_sqlite(cls, db_path: str = "./data/agent.db") -> "Backends":
+        """Create Backends with SQLite storage.
+        
+        Uses SQLite for state backend, in-memory for others.
+        For production, implement database backends.
+        
+        Args:
+            db_path: Path to SQLite database file
+        """
+        return cls(
+            session=InMemorySessionBackend(),
+            invocation=InMemoryInvocationBackend(),
+            message=InMemoryMessageBackend(),
+            memory=InMemoryMemoryBackend(),
+            artifact=InMemoryArtifactBackend(),
+            state=SQLiteStateBackend(db_path),
+        )
+
+
+__all__ = [
+    # Backends container
+    "Backends",
+    
+    # Session backend
+    "SessionBackend",
+    "InMemorySessionBackend",
+    
+    # Invocation backend
+    "InvocationBackend",
+    "InMemoryInvocationBackend",
+    
+    # Message backend
+    "MessageBackend",
+    "MessageType",
+    "InMemoryMessageBackend",
+    
+    # Memory backend
+    "MemoryBackend",
+    "InMemoryMemoryBackend",
+    
+    # Artifact backend
+    "ArtifactBackend",
+    "ArtifactSource",
+    "InMemoryArtifactBackend",
+    
+    # State backend (key-value)
+    "StateBackend",
+    "StateStore",
+    "StoreBasedStateBackend",
+    "SQLiteStateBackend",
+    "MemoryStateBackend",
+    "FileStateBackend",
+    "CompositeStateBackend",
+    
+    # Snapshot backend
+    "SnapshotBackend",
+    "Patch",
+    "InMemorySnapshotBackend",
+    "GitSnapshotBackend",
+    "GitS3HybridBackend",
+    
+    # Shell backend
+    "ShellBackend",
+    "ShellResult",
+    "LocalShellBackend",
+    
+    # File backend
+    "FileBackend",
+    "LocalFileBackend",
+    
+    # Code backend
+    "CodeBackend",
+    "CodeResult",
+    
+    # SubAgent backend
+    "SubAgentBackend",
+    "AgentConfig",
+    "ListSubAgentBackend",
+    
+    # Sandbox backends
+    "SandboxShellBackend",
+    "SandboxCodeBackend",
+]

aury/agents/backends/artifact/__init__.py

@@ -0,0 +1,9 @@
+"""Artifact backend."""
+from .types import ArtifactBackend, ArtifactSource
+from .memory import InMemoryArtifactBackend
+
+__all__ = [
+    "ArtifactBackend",
+    "ArtifactSource",
+    "InMemoryArtifactBackend",
+]

aury/agents/backends/artifact/memory.py

@@ -0,0 +1,130 @@
+"""In-memory artifact backend implementation."""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from .types import ArtifactSource
+
+
+class InMemoryArtifactBackend:
+    """In-memory implementation of ArtifactBackend.
+    
+    Stores artifact metadata in memory.
+    Suitable for testing and simple use cases.
+    """
+    
+    def __init__(self) -> None:
+        self._artifacts: dict[str, dict[str, Any]] = {}
+        self._session_artifacts: dict[str, list[str]] = {}
+    
+    def _make_key(self, session_id: str, namespace: str | None) -> str:
+        if namespace:
+            return f"{session_id}:{namespace}"
+        return session_id
+    
+    async def save(
+        self,
+        session_id: str,
+        name: str,
+        path: str,
+        source: ArtifactSource | str | None = None,
+        mime_type: str | None = None,
+        size: int | None = None,
+        invocation_id: str | None = None,
+        namespace: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Save an artifact reference."""
+        artifact_id = f"art_{uuid.uuid4().hex[:12]}"
+        key = self._make_key(session_id, namespace)
+        
+        artifact = {
+            "id": artifact_id,
+            "session_id": session_id,
+            "name": name,
+            "path": path,
+            "source": source,
+            "mime_type": mime_type,
+            "size": size,
+            "invocation_id": invocation_id,
+            "namespace": namespace,
+            "metadata": metadata or {},
+            "created_at": datetime.now().isoformat(),
+        }
+        
+        self._artifacts[artifact_id] = artifact
+        
+        if key not in self._session_artifacts:
+            self._session_artifacts[key] = []
+        self._session_artifacts[key].append(artifact_id)
+        
+        return artifact_id
+    
+    async def get(self, id: str) -> dict[str, Any] | None:
+        """Get artifact by ID."""
+        return self._artifacts.get(id)
+    
+    async def delete(self, id: str) -> bool:
+        """Delete an artifact reference."""
+        if id not in self._artifacts:
+            return False
+        
+        artifact = self._artifacts.pop(id)
+        session_id = artifact["session_id"]
+        namespace = artifact.get("namespace")
+        key = self._make_key(session_id, namespace)
+        
+        if key in self._session_artifacts:
+            self._session_artifacts[key] = [
+                aid for aid in self._session_artifacts[key] if aid != id
+            ]
+        
+        return True
+    
+    async def delete_by_invocation(
+        self,
+        session_id: str,
+        invocation_id: str,
+        namespace: str | None = None,
+    ) -> int:
+        """Delete artifacts by invocation."""
+        key = self._make_key(session_id, namespace)
+        artifact_ids = self._session_artifacts.get(key, [])
+        
+        to_delete = [
+            aid for aid in artifact_ids
+            if self._artifacts.get(aid, {}).get("invocation_id") == invocation_id
+        ]
+        
+        for aid in to_delete:
+            await self.delete(aid)
+        
+        return len(to_delete)
+    
+    async def list_by_session(
+        self,
+        session_id: str,
+        namespace: str | None = None,
+        source: ArtifactSource | str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """List artifacts for a session."""
+        key = self._make_key(session_id, namespace)
+        artifact_ids = self._session_artifacts.get(key, [])
+        
+        results = []
+        for aid in artifact_ids:
+            artifact = self._artifacts.get(aid)
+            if artifact:
+                # Filter by source if specified
+                if source and artifact.get("source") != source:
+                    continue
+                results.append(artifact)
+        
+        results.sort(key=lambda x: x.get("created_at", ""), reverse=True)
+        return results[:limit]
+
+
+__all__ = ["InMemoryArtifactBackend"]

aury/agents/backends/artifact/types.py

@@ -0,0 +1,133 @@
+"""Artifact backend types and protocols."""
+from __future__ import annotations
+
+from typing import Any, Literal, Protocol, runtime_checkable
+
+
+ArtifactSource = Literal["tool", "agent", "user", "system"]
+
+
+@runtime_checkable
+class ArtifactBackend(Protocol):
+    """Protocol for artifact storage.
+    
+    Artifacts are file references produced during agent execution,
+    such as generated images, documents, code files, etc.
+    
+    Note: This stores file metadata and path references, not binary data.
+    Actual file storage is handled by the file system or object storage.
+    
+    Example usage:
+        # Save artifact reference
+        artifact_id = await backend.save(
+            session_id="sess_123",
+            name="report.pdf",
+            path="/uploads/sess_123/report.pdf",
+            source="tool",
+            mime_type="application/pdf",
+            invocation_id="inv_456",
+        )
+        
+        # Get artifact metadata
+        artifact = await backend.get(artifact_id)
+        
+        # List artifacts
+        artifacts = await backend.list_by_session("sess_123")
+    """
+    
+    async def save(
+        self,
+        session_id: str,
+        name: str,
+        path: str,
+        source: ArtifactSource | str | None = None,
+        mime_type: str | None = None,
+        size: int | None = None,
+        invocation_id: str | None = None,
+        namespace: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Save an artifact reference.
+        
+        Args:
+            session_id: Session ID
+            name: Display name / filename
+            path: File path or URL (storage location)
+            source: Origin of artifact (tool, agent, user, system)
+            mime_type: MIME type (e.g., "image/png")
+            size: File size in bytes
+            invocation_id: Optional invocation ID for grouping
+            namespace: Optional namespace for isolation
+            metadata: Optional additional metadata
+            
+        Returns:
+            Generated artifact ID
+        """
+        ...
+    
+    async def get(self, id: str) -> dict[str, Any] | None:
+        """Get artifact by ID.
+        
+        Args:
+            id: Artifact ID
+            
+        Returns:
+            Artifact dict or None if not found:
+            {"id": str, "name": str, "path": str, "source": str, ...}
+        """
+        ...
+    
+    async def delete(self, id: str) -> bool:
+        """Delete an artifact reference.
+        
+        Note: This only deletes the metadata, not the actual file.
+        File cleanup should be handled separately.
+        
+        Args:
+            id: Artifact 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 artifacts by invocation (for revert).
+        
+        Args:
+            session_id: Session ID
+            invocation_id: Invocation ID to delete
+            namespace: Optional namespace filter
+            
+        Returns:
+            Number of artifacts deleted
+        """
+        ...
+    
+    async def list_by_session(
+        self,
+        session_id: str,
+        namespace: str | None = None,
+        source: ArtifactSource | str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """List artifacts for a session.
+        
+        Args:
+            session_id: Session ID
+            namespace: Optional namespace filter
+            source: Optional filter by source
+            limit: Max results
+            
+        Returns:
+            List of artifact dicts
+        """
+        ...
+
+
+__all__ = ["ArtifactBackend", "ArtifactSource"]