agent-runtime-core 0.1.4__py3-none-any.whl → 0.2.1__py3-none-any.whl

agent_runtime/__init__.py

@@ -34,7 +34,7 @@ Example usage:
             return RunResult(final_output={"message": "Hello!"})
 """
 
-__version__ = "0.1.4"
+__version__ = "0.2.1"
 
 # Core interfaces
 from agent_runtime.interfaces import (
@@ -87,6 +87,34 @@ from agent_runtime.testing import (
     run_agent_test,
 )
 
+# Persistence (memory, conversations, tasks, preferences)
+from agent_runtime.persistence import (
+    # Abstract interfaces
+    MemoryStore,
+    ConversationStore,
+    TaskStore,
+    PreferencesStore,
+    Scope,
+    # Data classes
+    Conversation,
+    ConversationMessage,
+    ToolCall,
+    ToolResult,
+    TaskList,
+    Task,
+    TaskState,
+    # File implementations
+    FileMemoryStore,
+    FileConversationStore,
+    FileTaskStore,
+    FilePreferencesStore,
+    # Manager
+    PersistenceManager,
+    PersistenceConfig,
+    get_persistence_manager,
+    configure_persistence,
+)
+
 __all__ = [
     # Version
     "__version__",
@@ -125,4 +153,28 @@ __all__ = [
     "LLMEvaluator",
     "create_test_context",
     "run_agent_test",
+    # Persistence - Abstract interfaces
+    "MemoryStore",
+    "ConversationStore",
+    "TaskStore",
+    "PreferencesStore",
+    "Scope",
+    # Persistence - Data classes
+    "Conversation",
+    "ConversationMessage",
+    "ToolCall",
+    "ToolResult",
+    "TaskList",
+    "Task",
+    "TaskState",
+    # Persistence - File implementations
+    "FileMemoryStore",
+    "FileConversationStore",
+    "FileTaskStore",
+    "FilePreferencesStore",
+    # Persistence - Manager
+    "PersistenceManager",
+    "PersistenceConfig",
+    "get_persistence_manager",
+    "configure_persistence",
 ]

agent_runtime/llm/anthropic.py

@@ -40,7 +40,7 @@ class AnthropicClient(LLMClient):
         if AsyncAnthropic is None:
             raise ImportError(
                 "anthropic package is required for AnthropicClient. "
-                "Install it with: pip install agent_runtime[anthropic]"
+                "Install it with: pip install agent-runtime-core[anthropic]"
             )
 
         from agent_runtime.config import get_config

agent_runtime/llm/litellm_client.py

@@ -38,7 +38,7 @@ class LiteLLMClient(LLMClient):
         if litellm is None:
             raise ImportError(
                 "litellm package is required for LiteLLMClient. "
-                "Install it with: pip install agent_runtime[litellm]"
+                "Install it with: pip install agent-runtime-core[litellm]"
             )
 
         from agent_runtime.config import get_config

agent_runtime/llm/openai.py

@@ -42,7 +42,7 @@ class OpenAIClient(LLMClient):
         if AsyncOpenAI is None:
             raise ImportError(
                 "openai package is required for OpenAIClient. "
-                "Install it with: pip install agent_runtime[openai]"
+                "Install it with: pip install agent-runtime-core[openai]"
             )
 
         from agent_runtime.config import get_config

agent_runtime/persistence/__init__.py

@@ -0,0 +1,88 @@
+"""
+Persistence module for agent state, memory, and conversation history.
+
+This module provides pluggable storage backends for:
+- Memory (global and project-scoped key-value storage)
+- Conversation history (full conversation state including tool calls)
+- Task state (task lists and progress)
+- Preferences (user and agent configuration)
+
+Example usage:
+    from agent_runtime.persistence import (
+        MemoryStore,
+        ConversationStore,
+        FileMemoryStore,
+        FileConversationStore,
+        PersistenceManager,
+        Scope,
+    )
+    
+    # Use the high-level manager
+    manager = PersistenceManager()
+    
+    # Store global memory
+    await manager.memory.set("user_name", "Alice", scope=Scope.GLOBAL)
+    
+    # Store project-specific memory
+    await manager.memory.set("project_type", "python", scope=Scope.PROJECT)
+    
+    # Save a conversation
+    await manager.conversations.save(conversation)
+"""
+
+from agent_runtime.persistence.base import (
+    MemoryStore,
+    ConversationStore,
+    TaskStore,
+    PreferencesStore,
+    Scope,
+    Conversation,
+    ConversationMessage,
+    ToolCall,
+    ToolResult,
+    TaskList,
+    Task,
+    TaskState,
+)
+
+from agent_runtime.persistence.file import (
+    FileMemoryStore,
+    FileConversationStore,
+    FileTaskStore,
+    FilePreferencesStore,
+)
+
+from agent_runtime.persistence.manager import (
+    PersistenceManager,
+    PersistenceConfig,
+    get_persistence_manager,
+    configure_persistence,
+)
+
+__all__ = [
+    # Abstract interfaces
+    "MemoryStore",
+    "ConversationStore",
+    "TaskStore",
+    "PreferencesStore",
+    "Scope",
+    # Data classes
+    "Conversation",
+    "ConversationMessage",
+    "ToolCall",
+    "ToolResult",
+    "TaskList",
+    "Task",
+    "TaskState",
+    # File implementations
+    "FileMemoryStore",
+    "FileConversationStore",
+    "FileTaskStore",
+    "FilePreferencesStore",
+    # Manager
+    "PersistenceManager",
+    "PersistenceConfig",
+    "get_persistence_manager",
+    "configure_persistence",
+]
+

agent_runtime/persistence/base.py

@@ -0,0 +1,332 @@
+"""
+Abstract base classes for persistence backends.
+
+These interfaces define the contract that all storage backends must implement.
+Projects depending on agent-runtime-core can provide their own implementations
+(e.g., database-backed, cloud storage, etc.).
+
+For Django/database implementations:
+- The `scope` parameter can be ignored if you use user/tenant context instead
+- Store implementations receive context through their constructor (e.g., user, org)
+- The abstract methods still accept scope for interface compatibility, but
+  implementations can choose to ignore it
+
+Example Django implementation:
+    class DjangoMemoryStore(MemoryStore):
+        def __init__(self, user):
+            self.user = user
+
+        async def get(self, key: str, scope: Scope = Scope.PROJECT) -> Optional[Any]:
+            # Ignore scope, use self.user instead
+            try:
+                entry = await Memory.objects.aget(user=self.user, key=key)
+                return entry.value
+            except Memory.DoesNotExist:
+                return None
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional, AsyncIterator
+from uuid import UUID
+
+
+class Scope(str, Enum):
+    """
+    Storage scope for memory and other persistent data.
+
+    For file-based storage:
+    - GLOBAL: User's home directory (~/.agent_runtime/)
+    - PROJECT: Current working directory (./.agent_runtime/)
+    - SESSION: In-memory only, not persisted
+
+    For database-backed storage, implementations may ignore this
+    and use user/tenant context from the store constructor instead.
+    """
+
+    GLOBAL = "global"
+    PROJECT = "project"
+    SESSION = "session"
+
+
+class TaskState(str, Enum):
+    """State of a task."""
+    
+    NOT_STARTED = "not_started"
+    IN_PROGRESS = "in_progress"
+    COMPLETE = "complete"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class ToolCall:
+    """A tool call made during a conversation."""
+    
+    id: str
+    name: str
+    arguments: dict
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass
+class ToolResult:
+    """Result of a tool call."""
+    
+    tool_call_id: str
+    result: Any
+    error: Optional[str] = None
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass
+class ConversationMessage:
+    """A message in a conversation with full state."""
+    
+    id: UUID
+    role: str  # system, user, assistant, tool
+    content: str | dict | list
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    
+    # For assistant messages with tool calls
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    
+    # For tool result messages
+    tool_call_id: Optional[str] = None
+    
+    # Metadata
+    model: Optional[str] = None
+    usage: dict = field(default_factory=dict)  # token counts
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class Conversation:
+    """A complete conversation with all state."""
+    
+    id: UUID
+    title: Optional[str] = None
+    messages: list[ConversationMessage] = field(default_factory=list)
+    
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    updated_at: datetime = field(default_factory=datetime.utcnow)
+    metadata: dict = field(default_factory=dict)
+    
+    # Associated agent
+    agent_key: Optional[str] = None
+    
+    # Summary for long conversations
+    summary: Optional[str] = None
+
+
+@dataclass
+class Task:
+    """A task in a task list."""
+    
+    id: UUID
+    name: str
+    description: str = ""
+    state: TaskState = TaskState.NOT_STARTED
+    parent_id: Optional[UUID] = None
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    updated_at: datetime = field(default_factory=datetime.utcnow)
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class TaskList:
+    """A list of tasks."""
+    
+    id: UUID
+    name: str
+    tasks: list[Task] = field(default_factory=list)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    updated_at: datetime = field(default_factory=datetime.utcnow)
+    
+    # Associated conversation/run
+    conversation_id: Optional[UUID] = None
+    run_id: Optional[UUID] = None
+
+
+class MemoryStore(ABC):
+    """
+    Abstract interface for key-value memory storage.
+    
+    Memory stores handle persistent key-value data that agents can
+    use to remember information across sessions.
+    """
+    
+    @abstractmethod
+    async def get(self, key: str, scope: Scope = Scope.PROJECT) -> Optional[Any]:
+        """Get a value by key."""
+        ...
+    
+    @abstractmethod
+    async def set(self, key: str, value: Any, scope: Scope = Scope.PROJECT) -> None:
+        """Set a value by key."""
+        ...
+    
+    @abstractmethod
+    async def delete(self, key: str, scope: Scope = Scope.PROJECT) -> bool:
+        """Delete a key. Returns True if key existed."""
+        ...
+    
+    @abstractmethod
+    async def list_keys(self, scope: Scope = Scope.PROJECT, prefix: Optional[str] = None) -> list[str]:
+        """List all keys, optionally filtered by prefix."""
+        ...
+    
+    @abstractmethod
+    async def clear(self, scope: Scope = Scope.PROJECT) -> None:
+        """Clear all keys in the given scope."""
+        ...
+    
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass
+
+
+class ConversationStore(ABC):
+    """
+    Abstract interface for conversation history storage.
+
+    Conversation stores handle full conversation state including
+    messages, tool calls, and metadata.
+    """
+
+    @abstractmethod
+    async def save(self, conversation: Conversation, scope: Scope = Scope.PROJECT) -> None:
+        """Save or update a conversation."""
+        ...
+
+    @abstractmethod
+    async def get(self, conversation_id: UUID, scope: Scope = Scope.PROJECT) -> Optional[Conversation]:
+        """Get a conversation by ID."""
+        ...
+
+    @abstractmethod
+    async def delete(self, conversation_id: UUID, scope: Scope = Scope.PROJECT) -> bool:
+        """Delete a conversation. Returns True if it existed."""
+        ...
+
+    @abstractmethod
+    async def list_conversations(
+        self,
+        scope: Scope = Scope.PROJECT,
+        limit: int = 100,
+        offset: int = 0,
+        agent_key: Optional[str] = None,
+    ) -> list[Conversation]:
+        """List conversations, optionally filtered by agent."""
+        ...
+
+    @abstractmethod
+    async def add_message(
+        self,
+        conversation_id: UUID,
+        message: ConversationMessage,
+        scope: Scope = Scope.PROJECT,
+    ) -> None:
+        """Add a message to an existing conversation."""
+        ...
+
+    @abstractmethod
+    async def get_messages(
+        self,
+        conversation_id: UUID,
+        scope: Scope = Scope.PROJECT,
+        limit: Optional[int] = None,
+        before: Optional[datetime] = None,
+    ) -> list[ConversationMessage]:
+        """Get messages from a conversation."""
+        ...
+
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass
+
+
+class TaskStore(ABC):
+    """
+    Abstract interface for task list storage.
+
+    Task stores handle task lists and their state for tracking
+    agent progress on complex work.
+    """
+
+    @abstractmethod
+    async def save(self, task_list: TaskList, scope: Scope = Scope.PROJECT) -> None:
+        """Save or update a task list."""
+        ...
+
+    @abstractmethod
+    async def get(self, task_list_id: UUID, scope: Scope = Scope.PROJECT) -> Optional[TaskList]:
+        """Get a task list by ID."""
+        ...
+
+    @abstractmethod
+    async def delete(self, task_list_id: UUID, scope: Scope = Scope.PROJECT) -> bool:
+        """Delete a task list. Returns True if it existed."""
+        ...
+
+    @abstractmethod
+    async def get_by_conversation(
+        self,
+        conversation_id: UUID,
+        scope: Scope = Scope.PROJECT,
+    ) -> Optional[TaskList]:
+        """Get the task list associated with a conversation."""
+        ...
+
+    @abstractmethod
+    async def update_task(
+        self,
+        task_list_id: UUID,
+        task_id: UUID,
+        state: Optional[TaskState] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        scope: Scope = Scope.PROJECT,
+    ) -> None:
+        """Update a specific task in a task list."""
+        ...
+
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass
+
+
+class PreferencesStore(ABC):
+    """
+    Abstract interface for preferences storage.
+
+    Preferences stores handle user and agent configuration
+    that persists across sessions.
+    """
+
+    @abstractmethod
+    async def get(self, key: str, scope: Scope = Scope.GLOBAL) -> Optional[Any]:
+        """Get a preference value."""
+        ...
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, scope: Scope = Scope.GLOBAL) -> None:
+        """Set a preference value."""
+        ...
+
+    @abstractmethod
+    async def delete(self, key: str, scope: Scope = Scope.GLOBAL) -> bool:
+        """Delete a preference. Returns True if it existed."""
+        ...
+
+    @abstractmethod
+    async def get_all(self, scope: Scope = Scope.GLOBAL) -> dict[str, Any]:
+        """Get all preferences in the given scope."""
+        ...
+
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass
+

agent_runtime/persistence/file.py

@@ -0,0 +1,507 @@
+"""
+File-based implementations of persistence stores.
+
+These implementations store data in hidden directories:
+- Global: ~/.agent_runtime/
+- Project: ./.agent_runtime/
+
+Data is stored as JSON files for easy inspection and debugging.
+"""
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+from uuid import UUID
+
+from agent_runtime.persistence.base import (
+    MemoryStore,
+    ConversationStore,
+    TaskStore,
+    PreferencesStore,
+    Scope,
+    Conversation,
+    ConversationMessage,
+    ToolCall,
+    ToolResult,
+    TaskList,
+    Task,
+    TaskState,
+)
+
+
+def _get_base_path(scope: Scope, project_dir: Optional[Path] = None) -> Path:
+    """Get the base path for a given scope."""
+    if scope == Scope.GLOBAL:
+        return Path.home() / ".agent_runtime"
+    elif scope == Scope.PROJECT:
+        base = project_dir or Path.cwd()
+        return base / ".agent_runtime"
+    else:
+        raise ValueError(f"Cannot get path for scope: {scope}")
+
+
+def _ensure_dir(path: Path) -> None:
+    """Ensure a directory exists."""
+    path.mkdir(parents=True, exist_ok=True)
+
+
+class _JSONEncoder(json.JSONEncoder):
+    """Custom JSON encoder for our data types."""
+
+    def default(self, obj):
+        if isinstance(obj, UUID):
+            return str(obj)
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        if isinstance(obj, TaskState):
+            return obj.value
+        if hasattr(obj, '__dataclass_fields__'):
+            return {k: getattr(obj, k) for k in obj.__dataclass_fields__}
+        return super().default(obj)
+
+
+def _json_dumps(obj: Any) -> str:
+    """Serialize object to JSON string."""
+    return json.dumps(obj, cls=_JSONEncoder, indent=2)
+
+
+def _parse_datetime(value: Any) -> datetime:
+    """Parse a datetime from string or return as-is."""
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        return datetime.fromisoformat(value)
+    return value
+
+
+def _parse_uuid(value: Any) -> UUID:
+    """Parse a UUID from string or return as-is."""
+    if isinstance(value, UUID):
+        return value
+    if isinstance(value, str):
+        return UUID(value)
+    return value
+
+
+class FileMemoryStore(MemoryStore):
+    """
+    File-based memory store.
+
+    Stores key-value pairs in JSON files:
+    - {base_path}/memory/{key}.json
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        self._project_dir = project_dir
+
+    def _get_memory_path(self, scope: Scope) -> Path:
+        return _get_base_path(scope, self._project_dir) / "memory"
+
+    def _get_key_path(self, key: str, scope: Scope) -> Path:
+        # Sanitize key for filesystem
+        safe_key = key.replace("/", "_").replace("\\", "_")
+        return self._get_memory_path(scope) / f"{safe_key}.json"
+
+    async def get(self, key: str, scope: Scope = Scope.PROJECT) -> Optional[Any]:
+        path = self._get_key_path(key, scope)
+        if not path.exists():
+            return None
+        try:
+            with open(path, "r") as f:
+                data = json.load(f)
+                return data.get("value")
+        except (json.JSONDecodeError, IOError):
+            return None
+
+    async def set(self, key: str, value: Any, scope: Scope = Scope.PROJECT) -> None:
+        path = self._get_key_path(key, scope)
+        _ensure_dir(path.parent)
+        with open(path, "w") as f:
+            f.write(_json_dumps({
+                "key": key,
+                "value": value,
+                "updated_at": datetime.utcnow(),
+            }))
+
+    async def delete(self, key: str, scope: Scope = Scope.PROJECT) -> bool:
+        path = self._get_key_path(key, scope)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    async def list_keys(self, scope: Scope = Scope.PROJECT, prefix: Optional[str] = None) -> list[str]:
+        memory_path = self._get_memory_path(scope)
+        if not memory_path.exists():
+            return []
+        keys = []
+        for file in memory_path.glob("*.json"):
+            key = file.stem
+            if prefix is None or key.startswith(prefix):
+                keys.append(key)
+        return sorted(keys)
+
+    async def clear(self, scope: Scope = Scope.PROJECT) -> None:
+        memory_path = self._get_memory_path(scope)
+        if memory_path.exists():
+            for file in memory_path.glob("*.json"):
+                file.unlink()
+
+
+class FileConversationStore(ConversationStore):
+    """
+    File-based conversation store.
+
+    Stores conversations in JSON files:
+    - {base_path}/conversations/{conversation_id}.json
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        self._project_dir = project_dir
+
+    def _get_conversations_path(self, scope: Scope) -> Path:
+        return _get_base_path(scope, self._project_dir) / "conversations"
+
+    def _get_conversation_path(self, conversation_id: UUID, scope: Scope) -> Path:
+        return self._get_conversations_path(scope) / f"{conversation_id}.json"
+
+    def _serialize_conversation(self, conversation: Conversation) -> dict:
+        """Serialize a conversation to a dict."""
+        return {
+            "id": str(conversation.id),
+            "title": conversation.title,
+            "messages": [self._serialize_message(m) for m in conversation.messages],
+            "created_at": conversation.created_at.isoformat(),
+            "updated_at": conversation.updated_at.isoformat(),
+            "metadata": conversation.metadata,
+            "agent_key": conversation.agent_key,
+            "summary": conversation.summary,
+        }
+
+    def _serialize_message(self, message: ConversationMessage) -> dict:
+        """Serialize a message to a dict."""
+        return {
+            "id": str(message.id),
+            "role": message.role,
+            "content": message.content,
+            "timestamp": message.timestamp.isoformat(),
+            "tool_calls": [
+                {
+                    "id": tc.id,
+                    "name": tc.name,
+                    "arguments": tc.arguments,
+                    "timestamp": tc.timestamp.isoformat(),
+                }
+                for tc in message.tool_calls
+            ],
+            "tool_call_id": message.tool_call_id,
+            "model": message.model,
+            "usage": message.usage,
+            "metadata": message.metadata,
+        }
+
+    def _deserialize_conversation(self, data: dict) -> Conversation:
+        """Deserialize a conversation from a dict."""
+        return Conversation(
+            id=_parse_uuid(data["id"]),
+            title=data.get("title"),
+            messages=[self._deserialize_message(m) for m in data.get("messages", [])],
+            created_at=_parse_datetime(data["created_at"]),
+            updated_at=_parse_datetime(data["updated_at"]),
+            metadata=data.get("metadata", {}),
+            agent_key=data.get("agent_key"),
+            summary=data.get("summary"),
+        )
+
+    def _deserialize_message(self, data: dict) -> ConversationMessage:
+        """Deserialize a message from a dict."""
+        return ConversationMessage(
+            id=_parse_uuid(data["id"]),
+            role=data["role"],
+            content=data["content"],
+            timestamp=_parse_datetime(data["timestamp"]),
+            tool_calls=[
+                ToolCall(
+                    id=tc["id"],
+                    name=tc["name"],
+                    arguments=tc["arguments"],
+                    timestamp=_parse_datetime(tc["timestamp"]),
+                )
+                for tc in data.get("tool_calls", [])
+            ],
+            tool_call_id=data.get("tool_call_id"),
+            model=data.get("model"),
+            usage=data.get("usage", {}),
+            metadata=data.get("metadata", {}),
+        )
+
+    async def save(self, conversation: Conversation, scope: Scope = Scope.PROJECT) -> None:
+        path = self._get_conversation_path(conversation.id, scope)
+        _ensure_dir(path.parent)
+        conversation.updated_at = datetime.utcnow()
+        with open(path, "w") as f:
+            f.write(_json_dumps(self._serialize_conversation(conversation)))
+
+    async def get(self, conversation_id: UUID, scope: Scope = Scope.PROJECT) -> Optional[Conversation]:
+        path = self._get_conversation_path(conversation_id, scope)
+        if not path.exists():
+            return None
+        try:
+            with open(path, "r") as f:
+                data = json.load(f)
+                return self._deserialize_conversation(data)
+        except (json.JSONDecodeError, IOError):
+            return None
+
+    async def delete(self, conversation_id: UUID, scope: Scope = Scope.PROJECT) -> bool:
+        path = self._get_conversation_path(conversation_id, scope)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    async def list_conversations(
+        self,
+        scope: Scope = Scope.PROJECT,
+        limit: int = 100,
+        offset: int = 0,
+        agent_key: Optional[str] = None,
+    ) -> list[Conversation]:
+        conversations_path = self._get_conversations_path(scope)
+        if not conversations_path.exists():
+            return []
+
+        conversations = []
+        for file in conversations_path.glob("*.json"):
+            try:
+                with open(file, "r") as f:
+                    data = json.load(f)
+                    conv = self._deserialize_conversation(data)
+                    if agent_key is None or conv.agent_key == agent_key:
+                        conversations.append(conv)
+            except (json.JSONDecodeError, IOError):
+                continue
+
+        # Sort by updated_at descending
+        conversations.sort(key=lambda c: c.updated_at, reverse=True)
+        return conversations[offset:offset + limit]
+
+    async def add_message(
+        self,
+        conversation_id: UUID,
+        message: ConversationMessage,
+        scope: Scope = Scope.PROJECT,
+    ) -> None:
+        conversation = await self.get(conversation_id, scope)
+        if conversation is None:
+            raise ValueError(f"Conversation not found: {conversation_id}")
+        conversation.messages.append(message)
+        await self.save(conversation, scope)
+
+    async def get_messages(
+        self,
+        conversation_id: UUID,
+        scope: Scope = Scope.PROJECT,
+        limit: Optional[int] = None,
+        before: Optional[datetime] = None,
+    ) -> list[ConversationMessage]:
+        conversation = await self.get(conversation_id, scope)
+        if conversation is None:
+            return []
+
+        messages = conversation.messages
+        if before:
+            messages = [m for m in messages if m.timestamp < before]
+        if limit:
+            messages = messages[-limit:]
+        return messages
+
+
+class FileTaskStore(TaskStore):
+    """
+    File-based task store.
+
+    Stores task lists in JSON files:
+    - {base_path}/tasks/{task_list_id}.json
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        self._project_dir = project_dir
+
+    def _get_tasks_path(self, scope: Scope) -> Path:
+        return _get_base_path(scope, self._project_dir) / "tasks"
+
+    def _get_task_list_path(self, task_list_id: UUID, scope: Scope) -> Path:
+        return self._get_tasks_path(scope) / f"{task_list_id}.json"
+
+    def _serialize_task_list(self, task_list: TaskList) -> dict:
+        return {
+            "id": str(task_list.id),
+            "name": task_list.name,
+            "tasks": [
+                {
+                    "id": str(t.id),
+                    "name": t.name,
+                    "description": t.description,
+                    "state": t.state.value,
+                    "parent_id": str(t.parent_id) if t.parent_id else None,
+                    "created_at": t.created_at.isoformat(),
+                    "updated_at": t.updated_at.isoformat(),
+                    "metadata": t.metadata,
+                }
+                for t in task_list.tasks
+            ],
+            "created_at": task_list.created_at.isoformat(),
+            "updated_at": task_list.updated_at.isoformat(),
+            "conversation_id": str(task_list.conversation_id) if task_list.conversation_id else None,
+            "run_id": str(task_list.run_id) if task_list.run_id else None,
+        }
+
+    def _deserialize_task_list(self, data: dict) -> TaskList:
+        return TaskList(
+            id=_parse_uuid(data["id"]),
+            name=data["name"],
+            tasks=[
+                Task(
+                    id=_parse_uuid(t["id"]),
+                    name=t["name"],
+                    description=t.get("description", ""),
+                    state=TaskState(t["state"]),
+                    parent_id=_parse_uuid(t["parent_id"]) if t.get("parent_id") else None,
+                    created_at=_parse_datetime(t["created_at"]),
+                    updated_at=_parse_datetime(t["updated_at"]),
+                    metadata=t.get("metadata", {}),
+                )
+                for t in data.get("tasks", [])
+            ],
+            created_at=_parse_datetime(data["created_at"]),
+            updated_at=_parse_datetime(data["updated_at"]),
+            conversation_id=_parse_uuid(data["conversation_id"]) if data.get("conversation_id") else None,
+            run_id=_parse_uuid(data["run_id"]) if data.get("run_id") else None,
+        )
+
+    async def save(self, task_list: TaskList, scope: Scope = Scope.PROJECT) -> None:
+        path = self._get_task_list_path(task_list.id, scope)
+        _ensure_dir(path.parent)
+        task_list.updated_at = datetime.utcnow()
+        with open(path, "w") as f:
+            f.write(_json_dumps(self._serialize_task_list(task_list)))
+
+    async def get(self, task_list_id: UUID, scope: Scope = Scope.PROJECT) -> Optional[TaskList]:
+        path = self._get_task_list_path(task_list_id, scope)
+        if not path.exists():
+            return None
+        try:
+            with open(path, "r") as f:
+                data = json.load(f)
+                return self._deserialize_task_list(data)
+        except (json.JSONDecodeError, IOError):
+            return None
+
+    async def delete(self, task_list_id: UUID, scope: Scope = Scope.PROJECT) -> bool:
+        path = self._get_task_list_path(task_list_id, scope)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    async def get_by_conversation(
+        self,
+        conversation_id: UUID,
+        scope: Scope = Scope.PROJECT,
+    ) -> Optional[TaskList]:
+        tasks_path = self._get_tasks_path(scope)
+        if not tasks_path.exists():
+            return None
+
+        for file in tasks_path.glob("*.json"):
+            try:
+                with open(file, "r") as f:
+                    data = json.load(f)
+                    if data.get("conversation_id") == str(conversation_id):
+                        return self._deserialize_task_list(data)
+            except (json.JSONDecodeError, IOError):
+                continue
+        return None
+
+    async def update_task(
+        self,
+        task_list_id: UUID,
+        task_id: UUID,
+        state: Optional[TaskState] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        scope: Scope = Scope.PROJECT,
+    ) -> None:
+        task_list = await self.get(task_list_id, scope)
+        if task_list is None:
+            raise ValueError(f"Task list not found: {task_list_id}")
+
+        for task in task_list.tasks:
+            if task.id == task_id:
+                if state is not None:
+                    task.state = state
+                if name is not None:
+                    task.name = name
+                if description is not None:
+                    task.description = description
+                task.updated_at = datetime.utcnow()
+                break
+        else:
+            raise ValueError(f"Task not found: {task_id}")
+
+        await self.save(task_list, scope)
+
+
+
+class FilePreferencesStore(PreferencesStore):
+    """
+    File-based preferences store.
+
+    Stores preferences in a single JSON file:
+    - {base_path}/preferences.json
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        self._project_dir = project_dir
+
+    def _get_preferences_path(self, scope: Scope) -> Path:
+        return _get_base_path(scope, self._project_dir) / "preferences.json"
+
+    async def _load_preferences(self, scope: Scope) -> dict:
+        path = self._get_preferences_path(scope)
+        if not path.exists():
+            return {}
+        try:
+            with open(path, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {}
+
+    async def _save_preferences(self, preferences: dict, scope: Scope) -> None:
+        path = self._get_preferences_path(scope)
+        _ensure_dir(path.parent)
+        with open(path, "w") as f:
+            f.write(_json_dumps(preferences))
+
+    async def get(self, key: str, scope: Scope = Scope.GLOBAL) -> Optional[Any]:
+        preferences = await self._load_preferences(scope)
+        return preferences.get(key)
+
+    async def set(self, key: str, value: Any, scope: Scope = Scope.GLOBAL) -> None:
+        preferences = await self._load_preferences(scope)
+        preferences[key] = value
+        await self._save_preferences(preferences, scope)
+
+    async def delete(self, key: str, scope: Scope = Scope.GLOBAL) -> bool:
+        preferences = await self._load_preferences(scope)
+        if key in preferences:
+            del preferences[key]
+            await self._save_preferences(preferences, scope)
+            return True
+        return False
+
+    async def get_all(self, scope: Scope = Scope.GLOBAL) -> dict[str, Any]:
+        return await self._load_preferences(scope)

agent_runtime/persistence/manager.py

@@ -0,0 +1,266 @@
+"""
+Persistence manager for coordinating storage backends.
+
+The PersistenceManager provides a unified interface for accessing
+all persistence stores with configurable backends.
+
+For Django integration, you can either:
+1. Pass pre-instantiated store instances
+2. Pass store classes with appropriate kwargs
+3. Use factory functions for request-scoped stores
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional, Type, Union
+
+from agent_runtime.persistence.base import (
+    MemoryStore,
+    ConversationStore,
+    TaskStore,
+    PreferencesStore,
+    Scope,
+)
+from agent_runtime.persistence.file import (
+    FileMemoryStore,
+    FileConversationStore,
+    FileTaskStore,
+    FilePreferencesStore,
+)
+
+
+# Type aliases for store factories
+MemoryStoreFactory = Callable[[], MemoryStore]
+ConversationStoreFactory = Callable[[], ConversationStore]
+TaskStoreFactory = Callable[[], TaskStore]
+PreferencesStoreFactory = Callable[[], PreferencesStore]
+
+
+@dataclass
+class PersistenceConfig:
+    """
+    Configuration for persistence backends.
+
+    Each store can be configured as:
+    - A class (will be instantiated with store_kwargs)
+    - A pre-instantiated store instance
+    - A factory function that returns a store instance
+
+    Example for Django:
+        from myapp.stores import DjangoMemoryStore, DjangoConversationStore
+
+        # Option 1: Pass classes with kwargs
+        config = PersistenceConfig(
+            memory_store_class=DjangoMemoryStore,
+            memory_store_kwargs={"user": request.user},
+        )
+
+        # Option 2: Pass pre-instantiated stores
+        config = PersistenceConfig(
+            memory_store=DjangoMemoryStore(user=request.user),
+            conversation_store=DjangoConversationStore(user=request.user),
+        )
+
+        # Option 3: Pass factory functions
+        config = PersistenceConfig(
+            memory_store_factory=lambda: DjangoMemoryStore(user=get_current_user()),
+        )
+    """
+
+    # Backend classes (can be swapped for custom implementations)
+    memory_store_class: Type[MemoryStore] = FileMemoryStore
+    conversation_store_class: Type[ConversationStore] = FileConversationStore
+    task_store_class: Type[TaskStore] = FileTaskStore
+    preferences_store_class: Type[PreferencesStore] = FilePreferencesStore
+
+    # Pre-instantiated store instances (takes precedence over classes)
+    memory_store: Optional[MemoryStore] = None
+    conversation_store: Optional[ConversationStore] = None
+    task_store: Optional[TaskStore] = None
+    preferences_store: Optional[PreferencesStore] = None
+
+    # Factory functions (takes precedence over classes, but not instances)
+    memory_store_factory: Optional[MemoryStoreFactory] = None
+    conversation_store_factory: Optional[ConversationStoreFactory] = None
+    task_store_factory: Optional[TaskStoreFactory] = None
+    preferences_store_factory: Optional[PreferencesStoreFactory] = None
+
+    # Kwargs passed to store class constructors (only used with classes)
+    memory_store_kwargs: dict = field(default_factory=dict)
+    conversation_store_kwargs: dict = field(default_factory=dict)
+    task_store_kwargs: dict = field(default_factory=dict)
+    preferences_store_kwargs: dict = field(default_factory=dict)
+
+    # Project directory (convenience for file-based stores)
+    # Only used if store_kwargs doesn't already have project_dir
+    project_dir: Optional[Path] = None
+
+
+class PersistenceManager:
+    """
+    Unified manager for all persistence stores.
+
+    Provides access to memory, conversations, tasks, and preferences
+    with pluggable backends.
+
+    Example:
+        # Use default file-based storage
+        manager = PersistenceManager()
+
+        # Store global memory
+        await manager.memory.set("user_name", "Alice", scope=Scope.GLOBAL)
+
+        # Store project-specific memory
+        await manager.memory.set("project_type", "python", scope=Scope.PROJECT)
+
+        # Save a conversation
+        await manager.conversations.save(conversation)
+
+        # Use custom backends (Django example)
+        config = PersistenceConfig(
+            memory_store=DjangoMemoryStore(user=request.user),
+            conversation_store=DjangoConversationStore(user=request.user),
+        )
+        manager = PersistenceManager(config)
+    """
+
+    def __init__(self, config: Optional[PersistenceConfig] = None):
+        self._config = config or PersistenceConfig()
+        self._memory: Optional[MemoryStore] = None
+        self._conversations: Optional[ConversationStore] = None
+        self._tasks: Optional[TaskStore] = None
+        self._preferences: Optional[PreferencesStore] = None
+
+    def _build_kwargs(self, store_kwargs: dict) -> dict:
+        """Build kwargs for store instantiation."""
+        kwargs = {}
+        # Only add project_dir if not already in store_kwargs
+        if self._config.project_dir and "project_dir" not in store_kwargs:
+            kwargs["project_dir"] = self._config.project_dir
+        kwargs.update(store_kwargs)
+        return kwargs
+
+    @property
+    def memory(self) -> MemoryStore:
+        """Get the memory store."""
+        if self._memory is None:
+            # Priority: instance > factory > class
+            if self._config.memory_store is not None:
+                self._memory = self._config.memory_store
+            elif self._config.memory_store_factory is not None:
+                self._memory = self._config.memory_store_factory()
+            else:
+                kwargs = self._build_kwargs(self._config.memory_store_kwargs)
+                self._memory = self._config.memory_store_class(**kwargs)
+        return self._memory
+
+    @property
+    def conversations(self) -> ConversationStore:
+        """Get the conversation store."""
+        if self._conversations is None:
+            if self._config.conversation_store is not None:
+                self._conversations = self._config.conversation_store
+            elif self._config.conversation_store_factory is not None:
+                self._conversations = self._config.conversation_store_factory()
+            else:
+                kwargs = self._build_kwargs(self._config.conversation_store_kwargs)
+                self._conversations = self._config.conversation_store_class(**kwargs)
+        return self._conversations
+
+    @property
+    def tasks(self) -> TaskStore:
+        """Get the task store."""
+        if self._tasks is None:
+            if self._config.task_store is not None:
+                self._tasks = self._config.task_store
+            elif self._config.task_store_factory is not None:
+                self._tasks = self._config.task_store_factory()
+            else:
+                kwargs = self._build_kwargs(self._config.task_store_kwargs)
+                self._tasks = self._config.task_store_class(**kwargs)
+        return self._tasks
+
+    @property
+    def preferences(self) -> PreferencesStore:
+        """Get the preferences store."""
+        if self._preferences is None:
+            if self._config.preferences_store is not None:
+                self._preferences = self._config.preferences_store
+            elif self._config.preferences_store_factory is not None:
+                self._preferences = self._config.preferences_store_factory()
+            else:
+                kwargs = self._build_kwargs(self._config.preferences_store_kwargs)
+                self._preferences = self._config.preferences_store_class(**kwargs)
+        return self._preferences
+
+    async def close(self) -> None:
+        """Close all stores."""
+        if self._memory:
+            await self._memory.close()
+        if self._conversations:
+            await self._conversations.close()
+        if self._tasks:
+            await self._tasks.close()
+        if self._preferences:
+            await self._preferences.close()
+
+
+# Global manager instance
+_manager: Optional[PersistenceManager] = None
+_config: Optional[PersistenceConfig] = None
+
+
+def configure_persistence(
+    memory_store_class: Optional[Type[MemoryStore]] = None,
+    conversation_store_class: Optional[Type[ConversationStore]] = None,
+    task_store_class: Optional[Type[TaskStore]] = None,
+    preferences_store_class: Optional[Type[PreferencesStore]] = None,
+    project_dir: Optional[Path] = None,
+    **kwargs,
+) -> PersistenceConfig:
+    """
+    Configure the global persistence manager.
+    
+    Args:
+        memory_store_class: Custom memory store implementation
+        conversation_store_class: Custom conversation store implementation
+        task_store_class: Custom task store implementation
+        preferences_store_class: Custom preferences store implementation
+        project_dir: Project directory for PROJECT scope
+        **kwargs: Additional store-specific configuration
+    
+    Returns:
+        The configured PersistenceConfig
+    """
+    global _config, _manager
+    
+    config = PersistenceConfig(project_dir=project_dir)
+    
+    if memory_store_class:
+        config.memory_store_class = memory_store_class
+    if conversation_store_class:
+        config.conversation_store_class = conversation_store_class
+    if task_store_class:
+        config.task_store_class = task_store_class
+    if preferences_store_class:
+        config.preferences_store_class = preferences_store_class
+    
+    _config = config
+    _manager = None  # Reset manager to use new config
+    
+    return config
+
+
+def get_persistence_manager() -> PersistenceManager:
+    """
+    Get the global persistence manager.
+    
+    Creates a new manager with default config if not configured.
+    """
+    global _manager
+    
+    if _manager is None:
+        _manager = PersistenceManager(_config)
+    
+    return _manager
+

agent_runtime/tracing/langfuse.py

@@ -37,7 +37,7 @@ class LangfuseTraceSink(TraceSink):
         if Langfuse is None:
             raise ImportError(
                 "langfuse package is required for LangfuseTraceSink. "
-                "Install with: pip install agent_runtime[langfuse]"
+                "Install with: pip install agent-runtime-core[langfuse]"
             )
 
         self._client = Langfuse(

{agent_runtime_core-0.1.4.dist-info → agent_runtime_core-0.2.1.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: agent-runtime-core
-Version: 0.1.4
+Version: 0.2.1
 Summary: Framework-agnostic Python library for executing AI agents with consistent patterns
-Project-URL: Homepage, https://github.com/colstrom/agent_runtime
-Project-URL: Repository, https://github.com/colstrom/agent_runtime
+Project-URL: Homepage, https://github.com/colstrom/agent_runtime_core
+Project-URL: Repository, https://github.com/colstrom/agent_runtime_core
 Author: Chris Olstrom
 License-Expression: MIT
 License-File: LICENSE

{agent_runtime_core-0.1.4.dist-info → agent_runtime_core-0.2.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-agent_runtime/__init__.py,sha256=zE6kt74R7dmm7Oe9o7B4CsSwoOm6D2H4LHX_EGj_pHA,2430
+agent_runtime/__init__.py,sha256=d-9hrmPS2JmaaDdZRfO5_B1HiJxLU_hMrXY-COXOxxs,3591
 agent_runtime/config.py,sha256=ZRjpILjsjeh_kl7873DtV2g_zaTrfdkb3NgdQ6ndb5Y,4981
 agent_runtime/interfaces.py,sha256=-VGZJHUkyF8kdO-BDkURyc-sLbObIHErIFw1Hzn3n14,10434
 agent_runtime/registry.py,sha256=sa0speDFxFCZlXoCge8cPNqWYUeWHyazs6tBer5Jg1w,1471
@@ -10,9 +10,13 @@ agent_runtime/events/memory.py,sha256=7qseR6RtdaP833FxEHwyPw5TC7l4brJHr8uEx0mLc1
 agent_runtime/events/redis.py,sha256=Z6WEvp_6jcIPi4ZgkGk5J61qxgGqllwk7jqJM4jcTXk,5869
 agent_runtime/events/sqlite.py,sha256=EiX1BMOqeS7BelmD8A6cvhz3fE4w7vJ2Wg4pFu1V2u0,5092
 agent_runtime/llm/__init__.py,sha256=JEk1Q2H6U9_Uid48YVm1wYR1W7po0vtjfjf2TTmQe_A,2431
-agent_runtime/llm/anthropic.py,sha256=R5KIcHAvHwoibkI0bXxg0RXlwd1qRGcdlGEEEoApVCM,7491
-agent_runtime/llm/litellm_client.py,sha256=M_-dAJVMRfWeNJlB0HXpFykbiIDRGwq1uMnamO3XUr8,5178
-agent_runtime/llm/openai.py,sha256=eL6_lhsUvwlE24TfDnzmlF285M0tExjb00rJV43oz28,6837
+agent_runtime/llm/anthropic.py,sha256=ho3psMYAARpXyzqejgA1dx6Nk8io0TwCKb0mp_wsGyM,7496
+agent_runtime/llm/litellm_client.py,sha256=Pic3N4CHVoqzdHUbKlizBcuPP0xCKoeY6U2ZjsZIgWg,5183
+agent_runtime/llm/openai.py,sha256=cRk4WBpiVknqsy_cgPAGdC8Zj250nasqo1dNQN0uxlw,6842
+agent_runtime/persistence/__init__.py,sha256=YynbxYtCtaSurQS9Ikenj9n_4xSEh0T9K0kOpg3IW04,2009
+agent_runtime/persistence/base.py,sha256=7p9HYWYY4pjmDvQgLh11Fie_XmMnkimkCG7tUQt0zUQ,9444
+agent_runtime/persistence/file.py,sha256=uMNSNfXvHPMJzl3QTrU-CPt1cLCH8J9rkaThbq7kLf0,17780
+agent_runtime/persistence/manager.py,sha256=PP-imx6ygIlUSID8rMwR9CTeD02HjZ3mdqczgZvF1es,9682
 agent_runtime/queue/__init__.py,sha256=78k29iEl8brp71LrOnmTHhQzPMHkzGre-Xqdl1NlNr0,1502
 agent_runtime/queue/base.py,sha256=QW1eWbwBX_tmVD8yJobFJtlxLd_RtUWHTuXGessuxy8,3959
 agent_runtime/queue/memory.py,sha256=n7kiE0Fw_BFUdzMyoO1QPO0ATzz8zBYaMQex7GdceZw,5411
@@ -24,9 +28,9 @@ agent_runtime/state/memory.py,sha256=xOnlqM3ArXDKAdPx3PxdS9IGgJDSM-EKp_S1Hsit180
 agent_runtime/state/redis.py,sha256=-lPi_2xKm7Bc4DVMJfSEAF7wJHctLV3ZMM9AYBeQKZU,3425
 agent_runtime/state/sqlite.py,sha256=NwuiTBXELb2tyOoH91MZqRJaCk9h8PskyY2VUc5EMr0,4868
 agent_runtime/tracing/__init__.py,sha256=m4WzfgJpnV5XCCoMpBYZdJU_JTkAdhEhl7M7tpf62RY,1246
-agent_runtime/tracing/langfuse.py,sha256=uThF0P6f1VJ1l1b7UuiFQ-oHZ-tCa9MbbHvTqkSuQ2A,3650
+agent_runtime/tracing/langfuse.py,sha256=Z-2eEUHlxCC82JtXOAaoi-1zI6tQwEOWdpJgfCXcZH0,3655
 agent_runtime/tracing/noop.py,sha256=MOm5eTrnf3d4WhiWrwVU5Kd3GmJ1903V0U7U3Qwho7U,746
-agent_runtime_core-0.1.4.dist-info/METADATA,sha256=uUCm7NRcZiHN7PLOMKhBZMEa-Sf-SJi87ON2HBDxIH4,12478
-agent_runtime_core-0.1.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-agent_runtime_core-0.1.4.dist-info/licenses/LICENSE,sha256=PcOO8aiOZ4H2MWYeKIis3o6xTCT1hNkDyCxHZhh1NeM,1070
-agent_runtime_core-0.1.4.dist-info/RECORD,,
+agent_runtime_core-0.2.1.dist-info/METADATA,sha256=_YZWAHr9zovJKJ0d0Xhk04lPfU9PeaN9gmUFFvaQM58,12488
+agent_runtime_core-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agent_runtime_core-0.2.1.dist-info/licenses/LICENSE,sha256=PcOO8aiOZ4H2MWYeKIis3o6xTCT1hNkDyCxHZhh1NeM,1070
+agent_runtime_core-0.2.1.dist-info/RECORD,,