aury-agent 0.0.4__py3-none-any.whl

aury/agents/backends/state/sqlite.py

@@ -0,0 +1,262 @@
+"""SQLite-based state backend for local persistence.
+
+Provides persistent storage using SQLite database.
+Ideal for local development and single-user applications.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+
+class SQLiteStateBackend:
+    """SQLite-based state backend.
+    
+    Stores all framework state in a single SQLite database file.
+    Supports both key-value storage and message history.
+    
+    Tables:
+    - state: namespace/key/value for general storage
+    - messages: session_id/role/content for conversation history
+    
+    Example:
+        backend = SQLiteStateBackend("./data/agent.db")
+        
+        # Key-value storage
+        await backend.set("sessions", "sess_123", {"id": "sess_123"})
+        data = await backend.get("sessions", "sess_123")
+        
+        # Message history
+        await backend.add_message("sess_123", {"role": "user", "content": "Hello"})
+        messages = await backend.get_messages("sess_123")
+    """
+    
+    def __init__(self, db_path: str | Path = "./data/agent.db"):
+        """Initialize SQLite backend.
+        
+        Args:
+            db_path: Path to SQLite database file
+        """
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+    
+    def _init_db(self) -> None:
+        """Initialize database tables."""
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS state (
+                    namespace TEXT NOT NULL,
+                    key TEXT NOT NULL,
+                    value TEXT NOT NULL,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    PRIMARY KEY (namespace, key)
+                )
+            """)
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS messages (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT NOT NULL,
+                    namespace TEXT,
+                    role TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    invocation_id TEXT,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                )
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_messages_session 
+                ON messages(session_id, namespace)
+            """)
+            conn.commit()
+        finally:
+            conn.close()
+    
+    def _get_conn(self) -> sqlite3.Connection:
+        """Get database connection."""
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+    
+    # ========== Key-Value Storage ==========
+    
+    async def get(self, namespace: str, key: str) -> Any | None:
+        """Get value by key."""
+        conn = self._get_conn()
+        try:
+            cursor = conn.execute(
+                "SELECT value FROM state WHERE namespace = ? AND key = ?",
+                (namespace, key)
+            )
+            row = cursor.fetchone()
+            if row:
+                return json.loads(row["value"])
+            return None
+        finally:
+            conn.close()
+    
+    async def set(self, namespace: str, key: str, value: Any) -> None:
+        """Set value by key."""
+        conn = self._get_conn()
+        try:
+            value_json = json.dumps(value, default=str, ensure_ascii=False)
+            conn.execute("""
+                INSERT INTO state (namespace, key, value, updated_at)
+                VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+                ON CONFLICT(namespace, key) DO UPDATE SET
+                    value = excluded.value,
+                    updated_at = CURRENT_TIMESTAMP
+            """, (namespace, key, value_json))
+            conn.commit()
+        finally:
+            conn.close()
+    
+    async def delete(self, namespace: str, key: str) -> bool:
+        """Delete value by key."""
+        conn = self._get_conn()
+        try:
+            cursor = conn.execute(
+                "DELETE FROM state WHERE namespace = ? AND key = ?",
+                (namespace, key)
+            )
+            conn.commit()
+            return cursor.rowcount > 0
+        finally:
+            conn.close()
+    
+    async def list(self, namespace: str, prefix: str = "") -> list[str]:
+        """List keys with optional prefix filter."""
+        conn = self._get_conn()
+        try:
+            if prefix:
+                cursor = conn.execute(
+                    "SELECT key FROM state WHERE namespace = ? AND key LIKE ?",
+                    (namespace, f"{prefix}%")
+                )
+            else:
+                cursor = conn.execute(
+                    "SELECT key FROM state WHERE namespace = ?",
+                    (namespace,)
+                )
+            return [row["key"] for row in cursor.fetchall()]
+        finally:
+            conn.close()
+    
+    async def exists(self, namespace: str, key: str) -> bool:
+        """Check if key exists."""
+        conn = self._get_conn()
+        try:
+            cursor = conn.execute(
+                "SELECT 1 FROM state WHERE namespace = ? AND key = ?",
+                (namespace, key)
+            )
+            return cursor.fetchone() is not None
+        finally:
+            conn.close()
+    
+    # ========== Message Storage ==========
+    
+    async def add_message(
+        self,
+        session_id: str,
+        message: dict[str, Any],
+        namespace: str | None = None,
+    ) -> None:
+        """Add a message to session history.
+        
+        Args:
+            session_id: Session ID
+            message: Message dict with role, content, invocation_id
+            namespace: Optional namespace for isolation
+        """
+        conn = self._get_conn()
+        try:
+            content = message.get("content", "")
+            # Serialize list content (tool_use etc.)
+            if isinstance(content, list):
+                content = json.dumps(content, ensure_ascii=False)
+            
+            conn.execute("""
+                INSERT INTO messages (session_id, namespace, role, content, invocation_id)
+                VALUES (?, ?, ?, ?, ?)
+            """, (
+                session_id,
+                namespace,
+                message.get("role", "user"),
+                content,
+                message.get("invocation_id"),
+            ))
+            conn.commit()
+        finally:
+            conn.close()
+    
+    async def get_messages(
+        self,
+        session_id: str,
+        namespace: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get all messages for a session.
+        
+        Args:
+            session_id: Session ID
+            namespace: Optional namespace filter
+            
+        Returns:
+            List of message dicts in chronological order
+        """
+        conn = self._get_conn()
+        try:
+            if namespace is None:
+                cursor = conn.execute(
+                    "SELECT role, content, invocation_id FROM messages WHERE session_id = ? AND namespace IS NULL ORDER BY id",
+                    (session_id,)
+                )
+            else:
+                cursor = conn.execute(
+                    "SELECT role, content, invocation_id FROM messages WHERE session_id = ? AND namespace = ? ORDER BY id",
+                    (session_id, namespace)
+                )
+            
+            result = []
+            for row in cursor.fetchall():
+                content = row["content"]
+                # Try to parse JSON content (may be tool_use etc.)
+                if content and content.startswith("["):
+                    try:
+                        content = json.loads(content)
+                    except json.JSONDecodeError:
+                        pass
+                
+                result.append({
+                    "role": row["role"],
+                    "content": content,
+                    "invocation_id": row["invocation_id"],
+                })
+            
+            return result
+        finally:
+            conn.close()
+    
+    async def clear_messages(self, session_id: str) -> int:
+        """Clear all messages for a session.
+        
+        Returns:
+            Number of messages deleted
+        """
+        conn = self._get_conn()
+        try:
+            cursor = conn.execute(
+                "DELETE FROM messages WHERE session_id = ?",
+                (session_id,)
+            )
+            conn.commit()
+            return cursor.rowcount
+        finally:
+            conn.close()
+
+
+__all__ = ["SQLiteStateBackend"]

aury/agents/backends/state/types.py

@@ -0,0 +1,178 @@
+"""State backend types and protocols.
+
+StateBackend is a simplified key-value storage for generic state.
+For specific data types, use dedicated backends:
+- SessionBackend: Session management
+- InvocationBackend: Invocation management
+- MessageBackend: Message storage
+- MemoryBackend: Long-term memory
+- ArtifactBackend: File/artifact storage
+
+Architecture:
+- StateStore: Low-level storage protocol (implemented by API layer)
+- StateBackend: High-level interface (used by framework, wraps StateStore)
+"""
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class StateStore(Protocol):
+    """Low-level storage protocol for state persistence.
+    
+    This is the interface that API/application layer implements.
+    Provides raw key-value operations without namespace logic.
+    
+    Example implementations:
+    - SQLAlchemyStateStore: Uses State table
+    - RedisStateStore: Uses Redis
+    - MemoryStateStore: In-memory dict
+    """
+    
+    async def get(self, key: str) -> Any | None:
+        """Get value by key."""
+        ...
+    
+    async def set(self, key: str, value: Any) -> None:
+        """Set value by key."""
+        ...
+    
+    async def delete(self, key: str) -> bool:
+        """Delete value by key. Returns True if deleted."""
+        ...
+    
+    async def list(self, prefix: str = "") -> list[str]:
+        """List keys with optional prefix filter."""
+        ...
+    
+    async def exists(self, key: str) -> bool:
+        """Check if key exists."""
+        ...
+
+
+@runtime_checkable
+class StateBackend(Protocol):
+    """Protocol for generic key-value state storage.
+    
+    Provides simple key-value storage with namespace isolation.
+    Use for storing arbitrary state that doesn't fit other backends.
+    
+    Example namespaces:
+    - "plan" - Plan state
+    - "config" - Configuration
+    - "cache" - Temporary cache
+    - "workflow" - Workflow state
+    
+    Example usage:
+        # Store plan state
+        await backend.set("plan", "sess_123:plan", {"status": "active"})
+        
+        # Get plan state
+        plan = await backend.get("plan", "sess_123:plan")
+        
+        # List all plans
+        keys = await backend.list("plan")
+    """
+    
+    async def get(self, namespace: str, key: str) -> Any | None:
+        """Get value by key.
+        
+        Args:
+            namespace: Namespace for isolation
+            key: Storage key
+            
+        Returns:
+            Stored value or None if not found
+        """
+        ...
+    
+    async def set(self, namespace: str, key: str, value: Any) -> None:
+        """Set value by key.
+        
+        Args:
+            namespace: Namespace for isolation
+            key: Storage key
+            value: Value to store (must be JSON-serializable)
+        """
+        ...
+    
+    async def delete(self, namespace: str, key: str) -> bool:
+        """Delete value by key.
+        
+        Args:
+            namespace: Namespace
+            key: Storage key
+            
+        Returns:
+            True if deleted, False if not found
+        """
+        ...
+    
+    async def list(self, namespace: str, prefix: str = "") -> list[str]:
+        """List keys with optional prefix filter.
+        
+        Args:
+            namespace: Namespace
+            prefix: Optional key prefix filter
+            
+        Returns:
+            List of matching keys
+        """
+        ...
+    
+    async def exists(self, namespace: str, key: str) -> bool:
+        """Check if key exists.
+        
+        Args:
+            namespace: Namespace
+            key: Storage key
+            
+        Returns:
+            True if exists
+        """
+        ...
+
+
+class StoreBasedStateBackend:
+    """StateBackend implementation that wraps a StateStore.
+    
+    This allows API layer to implement only the simple StateStore interface,
+    while the framework provides namespace handling.
+    
+    Example:
+        # API layer implements StateStore
+        store = SQLAlchemyStateStore(session_factory, tenant_id)
+        
+        # Framework wraps it as StateBackend
+        backend = StoreBasedStateBackend(store)
+    """
+    
+    def __init__(self, store: StateStore):
+        self._store = store
+    
+    def _make_key(self, namespace: str, key: str) -> str:
+        """Combine namespace and key."""
+        return f"{namespace}:{key}"
+    
+    async def get(self, namespace: str, key: str) -> Any | None:
+        return await self._store.get(self._make_key(namespace, key))
+    
+    async def set(self, namespace: str, key: str, value: Any) -> None:
+        await self._store.set(self._make_key(namespace, key), value)
+    
+    async def delete(self, namespace: str, key: str) -> bool:
+        return await self._store.delete(self._make_key(namespace, key))
+    
+    async def list(self, namespace: str, prefix: str = "") -> list[str]:
+        full_prefix = self._make_key(namespace, prefix)
+        keys = await self._store.list(full_prefix)
+        # Strip namespace prefix from results
+        ns_prefix = f"{namespace}:"
+        return [k[len(ns_prefix):] for k in keys if k.startswith(ns_prefix)]
+    
+    async def exists(self, namespace: str, key: str) -> bool:
+        return await self._store.exists(self._make_key(namespace, key))
+
+
+__all__ = ["StateBackend", "StateStore", "StoreBasedStateBackend"]

aury/agents/backends/subagent/__init__.py

@@ -0,0 +1,165 @@
+"""SubAgent backend for sub-agent registry and retrieval.
+
+Supports different agent retrieval strategies:
+- ListSubAgentBackend: Static list of agents
+- Custom backends: DB, API, dynamic discovery
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol, TYPE_CHECKING, runtime_checkable
+
+if TYPE_CHECKING:
+    from ...core.base import BaseAgent
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for a sub-agent.
+    
+    行为配置:
+    - inherit_messages: 是否继承父 agent 的消息历史
+    - return_to_parent: 完成后是否返回结果给父 agent
+    - create_invocation: 是否创建新 invocation（用户可直接交互）
+    
+    状态配置:
+    - inherit_state: 继承哪些状态 ("all", "none", 或具体 key 列表)
+    - return_state_keys: 返回哪些状态给父 agent
+    - summary_mode: 返回摘要模式 ("full", "truncate", "none")
+    
+    手动切换配置:
+    - switchable: 是否出现在前端可切换列表
+    - display_name: 前端显示名称
+    
+    超时配置:
+    - timeout: 执行超时时间（秒），收到事件时会刷新
+    """
+    key: str
+    agent: Any  # BaseAgent instance or class
+    description: str = ""
+    
+    # 行为配置（替代原 mode）
+    inherit_messages: bool = False
+    return_to_parent: bool = True
+    create_invocation: bool = False
+    
+    # 状态配置
+    inherit_state: Literal["all", "none"] | list[str] = "none"
+    return_state_keys: list[str] = field(default_factory=list)
+    summary_mode: Literal["full", "truncate", "none"] = "full"
+    
+    # 手动切换配置
+    switchable: bool = False
+    display_name: str = ""
+    
+    # 超时配置（默认 5 分钟，收到事件时刷新）
+    timeout: float = 300.0
+    
+    # 消息记录配置（可选覆盖，默认由 return_to_parent 派生）
+    # - return_to_parent=True → 不记录（消息归并到父级结果）
+    # - return_to_parent=False → 记录到独立 namespace
+    _record_messages: bool | None = None  # None = 用默认派生逻辑
+    
+    # Permission config (optional override)
+    permission_config: Any | None = None
+    
+    @property
+    def record_messages(self) -> bool:
+        """是否记录消息 - 默认由 return_to_parent 派生.
+        
+        - return_to_parent=True → 不记录（结果归并到父级）
+        - return_to_parent=False → 记录（独立运行）
+        """
+        if self._record_messages is not None:
+            return self._record_messages
+        return not self.return_to_parent
+    
+    @property
+    def mode(self) -> Literal["embedded", "delegated"]:
+        """兼容属性：根据 create_invocation 返回 mode."""
+        return "delegated" if self.create_invocation else "embedded"
+    
+    def to_dict(self) -> dict:
+        return {
+            "key": self.key,
+            "agent_name": getattr(self.agent, "name", str(self.agent)),
+            "mode": self.mode,
+            "description": self.description or getattr(self.agent, "description", ""),
+            "inherit_messages": self.inherit_messages,
+            "return_to_parent": self.return_to_parent,
+            "create_invocation": self.create_invocation,
+            "switchable": self.switchable,
+            "display_name": self.display_name,
+        }
+
+
+@runtime_checkable
+class SubAgentBackend(Protocol):
+    """Protocol for sub-agent retrieval."""
+    
+    async def get(self, key: str) -> AgentConfig | None:
+        """Get agent config by key."""
+        ...
+    
+    async def list(self) -> list[AgentConfig]:
+        """List all available agents."""
+        ...
+
+
+class ListSubAgentBackend:
+    """Default implementation: Static list of agents."""
+    
+    def __init__(self, agents: list[AgentConfig] | None = None):
+        self._agents: dict[str, AgentConfig] = {}
+        if agents:
+            for config in agents:
+                self._agents[config.key] = config
+    
+    def register(self, config: AgentConfig) -> None:
+        """Register an agent config."""
+        self._agents[config.key] = config
+    
+    def register_agent(
+        self,
+        key: str,
+        agent: Any,
+        description: str = "",
+        *,
+        inherit_messages: bool = False,
+        return_to_parent: bool = True,
+        create_invocation: bool = False,
+        switchable: bool = False,
+        display_name: str = "",
+    ) -> None:
+        """Convenience method to register an agent."""
+        self._agents[key] = AgentConfig(
+            key=key,
+            agent=agent,
+            description=description or getattr(agent, "description", ""),
+            inherit_messages=inherit_messages,
+            return_to_parent=return_to_parent,
+            create_invocation=create_invocation,
+            switchable=switchable,
+            display_name=display_name,
+        )
+    
+    async def get(self, key: str) -> AgentConfig | None:
+        return self._agents.get(key)
+    
+    async def list(self) -> list[AgentConfig]:
+        return list(self._agents.values())
+    
+    def list_sync(self) -> list[AgentConfig]:
+        """Synchronous version of list() for use in property getters."""
+        return list(self._agents.values())
+    
+    def clear(self) -> None:
+        """Clear all agents."""
+        self._agents.clear()
+
+
+__all__ = [
+    "SubAgentBackend",
+    "AgentConfig", 
+    "ListSubAgentBackend",
+]

aury/agents/cli/__init__.py

@@ -0,0 +1,41 @@
+"""
+Aury Agent CLI - 命令行界面
+===========================
+
+提供命令行工具用于:
+- 交互式对话 (chat)
+- 运行 Workflow (workflow)
+- 管理会话 (session)
+- 配置管理 (config)
+
+扩展支持:
+- 注册自定义 Agent
+- 注册自定义 Tool
+- 从配置文件加载扩展
+- 从 entry points 加载扩展
+"""
+from aury.agents.cli.main import app, main
+from aury.agents.cli.extensions import (
+    ExtensionRegistry,
+    ExtensionInfo,
+    registry,
+    register_agent,
+    register_tool,
+    get_agent,
+    get_tool,
+    auto_discover,
+)
+
+__all__ = [
+    "app",
+    "main",
+    # Extensions
+    "ExtensionRegistry",
+    "ExtensionInfo",
+    "registry",
+    "register_agent",
+    "register_tool",
+    "get_agent",
+    "get_tool",
+    "auto_discover",
+]