agent-runtime-core 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

agent_runtime_core/persistence/__init__.py

@@ -6,6 +6,8 @@ This module provides pluggable storage backends for:
 - Conversation history (full conversation state including tool calls)
 - Task state (task lists and progress)
 - Preferences (user and agent configuration)
+- Knowledge base (facts, summaries, embeddings) - optional
+- Audit/history (logs, errors, metrics) - optional
 
 Example usage:
     from agent_runtime_core.persistence import (
@@ -16,33 +18,51 @@ Example usage:
         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_core.persistence.base import (
+    # Core stores
     MemoryStore,
     ConversationStore,
     TaskStore,
     PreferencesStore,
+    # Optional stores
+    KnowledgeStore,
+    AuditStore,
+    # Enums
     Scope,
+    TaskState,
+    FactType,
+    AuditEventType,
+    ErrorSeverity,
+    # Conversation models
     Conversation,
     ConversationMessage,
     ToolCall,
     ToolResult,
+    # Task models
     TaskList,
     Task,
-    TaskState,
+    # Knowledge models
+    Fact,
+    Summary,
+    Embedding,
+    # Audit models
+    AuditEntry,
+    ErrorRecord,
+    PerformanceMetric,
 )
 
 from agent_runtime_core.persistence.file import (
@@ -60,20 +80,36 @@ from agent_runtime_core.persistence.manager import (
 )
 
 __all__ = [
-    # Abstract interfaces
+    # Abstract interfaces - core
     "MemoryStore",
     "ConversationStore",
     "TaskStore",
     "PreferencesStore",
+    # Abstract interfaces - optional
+    "KnowledgeStore",
+    "AuditStore",
+    # Enums
     "Scope",
-    # Data classes
+    "TaskState",
+    "FactType",
+    "AuditEventType",
+    "ErrorSeverity",
+    # Conversation models
     "Conversation",
     "ConversationMessage",
     "ToolCall",
     "ToolResult",
+    # Task models
     "TaskList",
     "Task",
-    "TaskState",
+    # Knowledge models
+    "Fact",
+    "Summary",
+    "Embedding",
+    # Audit models
+    "AuditEntry",
+    "ErrorRecord",
+    "PerformanceMetric",
     # File implementations
     "FileMemoryStore",
     "FileConversationStore",

agent_runtime_core/persistence/base.py

@@ -83,48 +83,56 @@ class ToolResult:
 @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
+    usage: dict = field(default_factory=dict)  # token counts: {prompt_tokens, completion_tokens, total_tokens}
     metadata: dict = field(default_factory=dict)
 
+    # Branching support
+    parent_message_id: Optional[UUID] = None  # For branched/edited messages
+    branch_id: Optional[UUID] = None  # Groups messages in same branch
+
 
 @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
 
+    # Branching support
+    parent_conversation_id: Optional[UUID] = None  # For forked conversations
+    active_branch_id: Optional[UUID] = None  # Currently active branch
+
 
 @dataclass
 class Task:
     """A task in a task list."""
-    
+
     id: UUID
     name: str
     description: str = ""
@@ -134,17 +142,31 @@ class Task:
     updated_at: datetime = field(default_factory=datetime.utcnow)
     metadata: dict = field(default_factory=dict)
 
+    # Dependencies and scheduling
+    dependencies: list[UUID] = field(default_factory=list)  # Task IDs this depends on
+    priority: int = 0  # Higher = more important
+    due_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+
+    # Checkpoint for resumable long-running operations
+    checkpoint_data: dict = field(default_factory=dict)
+    checkpoint_at: Optional[datetime] = None
+
+    # Execution tracking
+    attempts: int = 0
+    last_error: Optional[str] = None
+
 
 @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
@@ -330,3 +352,386 @@ class PreferencesStore(ABC):
         """Close any connections. Override if needed."""
         pass
 
+
+# =============================================================================
+# Knowledge Base Models and Store
+# =============================================================================
+
+
+class FactType(str, Enum):
+    """Type of fact stored in knowledge base."""
+
+    USER = "user"  # Facts about the user
+    PROJECT = "project"  # Facts about the project
+    PREFERENCE = "preference"  # Learned preferences
+    CONTEXT = "context"  # Contextual information
+    CUSTOM = "custom"  # Custom fact type
+
+
+@dataclass
+class Fact:
+    """A learned fact about user, project, or context."""
+
+    id: UUID
+    key: str  # Unique identifier for the fact
+    value: Any  # The fact content
+    fact_type: FactType = FactType.CUSTOM
+    confidence: float = 1.0  # 0.0 to 1.0
+    source: Optional[str] = None  # Where this fact came from
+
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    updated_at: datetime = field(default_factory=datetime.utcnow)
+    expires_at: Optional[datetime] = None  # Optional expiration
+
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class Summary:
+    """A summary of a conversation or set of interactions."""
+
+    id: UUID
+    content: str  # The summary text
+
+    # What this summarizes
+    conversation_id: Optional[UUID] = None
+    conversation_ids: list[UUID] = field(default_factory=list)  # For multi-conversation summaries
+
+    # Time range covered
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class Embedding:
+    """
+    A vector embedding for semantic search.
+
+    Note: This is optional and requires additional dependencies
+    for vector operations (e.g., numpy, faiss, pgvector).
+    """
+
+    id: UUID
+    vector: list[float]  # The embedding vector
+
+    # What this embedding represents
+    content: str  # Original text
+    content_type: str = "text"  # text, summary, fact, etc.
+    source_id: Optional[UUID] = None  # ID of source object
+
+    model: Optional[str] = None  # Embedding model used
+    dimensions: int = 0  # Vector dimensions
+
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    metadata: dict = field(default_factory=dict)
+
+
+class KnowledgeStore(ABC):
+    """
+    Abstract interface for knowledge base storage.
+
+    Knowledge stores handle facts, summaries, and optionally
+    embeddings for semantic search. This is optional - agents
+    can function without a knowledge store.
+    """
+
+    # Fact operations
+    @abstractmethod
+    async def save_fact(self, fact: Fact, scope: Scope = Scope.PROJECT) -> None:
+        """Save or update a fact."""
+        ...
+
+    @abstractmethod
+    async def get_fact(self, fact_id: UUID, scope: Scope = Scope.PROJECT) -> Optional[Fact]:
+        """Get a fact by ID."""
+        ...
+
+    @abstractmethod
+    async def get_fact_by_key(self, key: str, scope: Scope = Scope.PROJECT) -> Optional[Fact]:
+        """Get a fact by its key."""
+        ...
+
+    @abstractmethod
+    async def list_facts(
+        self,
+        scope: Scope = Scope.PROJECT,
+        fact_type: Optional[FactType] = None,
+        limit: int = 100,
+    ) -> list[Fact]:
+        """List facts, optionally filtered by type."""
+        ...
+
+    @abstractmethod
+    async def delete_fact(self, fact_id: UUID, scope: Scope = Scope.PROJECT) -> bool:
+        """Delete a fact. Returns True if it existed."""
+        ...
+
+    # Summary operations
+    @abstractmethod
+    async def save_summary(self, summary: Summary, scope: Scope = Scope.PROJECT) -> None:
+        """Save or update a summary."""
+        ...
+
+    @abstractmethod
+    async def get_summary(self, summary_id: UUID, scope: Scope = Scope.PROJECT) -> Optional[Summary]:
+        """Get a summary by ID."""
+        ...
+
+    @abstractmethod
+    async def get_summaries_for_conversation(
+        self,
+        conversation_id: UUID,
+        scope: Scope = Scope.PROJECT,
+    ) -> list[Summary]:
+        """Get all summaries for a conversation."""
+        ...
+
+    @abstractmethod
+    async def delete_summary(self, summary_id: UUID, scope: Scope = Scope.PROJECT) -> bool:
+        """Delete a summary. Returns True if it existed."""
+        ...
+
+    # Embedding operations (optional - can raise NotImplementedError)
+    async def save_embedding(self, embedding: Embedding, scope: Scope = Scope.PROJECT) -> None:
+        """Save an embedding. Optional - may raise NotImplementedError."""
+        raise NotImplementedError("Embeddings not supported by this store")
+
+    async def search_similar(
+        self,
+        query_vector: list[float],
+        limit: int = 10,
+        scope: Scope = Scope.PROJECT,
+        content_type: Optional[str] = None,
+    ) -> list[tuple[Embedding, float]]:
+        """
+        Search for similar embeddings. Returns (embedding, score) tuples.
+        Optional - may raise NotImplementedError.
+        """
+        raise NotImplementedError("Embeddings not supported by this store")
+
+    async def delete_embedding(self, embedding_id: UUID, scope: Scope = Scope.PROJECT) -> bool:
+        """Delete an embedding. Optional - may raise NotImplementedError."""
+        raise NotImplementedError("Embeddings not supported by this store")
+
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass
+
+
+# =============================================================================
+# Audit/History Models and Store
+# =============================================================================
+
+
+class AuditEventType(str, Enum):
+    """Type of audit event."""
+
+    # Conversation events
+    CONVERSATION_START = "conversation_start"
+    CONVERSATION_END = "conversation_end"
+    MESSAGE_SENT = "message_sent"
+    MESSAGE_RECEIVED = "message_received"
+
+    # Tool events
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    TOOL_ERROR = "tool_error"
+
+    # Agent events
+    AGENT_START = "agent_start"
+    AGENT_END = "agent_end"
+    AGENT_ERROR = "agent_error"
+
+    # System events
+    CHECKPOINT_SAVED = "checkpoint_saved"
+    CHECKPOINT_RESTORED = "checkpoint_restored"
+
+    CUSTOM = "custom"
+
+
+class ErrorSeverity(str, Enum):
+    """Severity level for errors."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass
+class AuditEntry:
+    """An audit log entry for tracking interactions."""
+
+    id: UUID
+    event_type: AuditEventType
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+    # Context
+    conversation_id: Optional[UUID] = None
+    run_id: Optional[UUID] = None
+    agent_key: Optional[str] = None
+
+    # Event details
+    action: str = ""  # Human-readable action description
+    details: dict = field(default_factory=dict)  # Event-specific data
+
+    # Actor information
+    actor_type: str = "agent"  # agent, user, system
+    actor_id: Optional[str] = None
+
+    # Request/response tracking
+    request_id: Optional[str] = None
+    parent_event_id: Optional[UUID] = None  # For nested events
+
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class ErrorRecord:
+    """A record of an error for debugging."""
+
+    id: UUID
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    severity: ErrorSeverity = ErrorSeverity.ERROR
+
+    # Error details
+    error_type: str = ""  # Exception class name
+    message: str = ""
+    stack_trace: Optional[str] = None
+
+    # Context
+    conversation_id: Optional[UUID] = None
+    run_id: Optional[UUID] = None
+    agent_key: Optional[str] = None
+
+    # What was happening when error occurred
+    context: dict = field(default_factory=dict)
+
+    # Resolution tracking
+    resolved: bool = False
+    resolved_at: Optional[datetime] = None
+    resolution_notes: Optional[str] = None
+
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class PerformanceMetric:
+    """A performance metric for monitoring."""
+
+    id: UUID
+    name: str  # Metric name (e.g., "llm_latency", "tool_execution_time")
+    value: float  # Metric value
+    unit: str = ""  # Unit of measurement (ms, tokens, etc.)
+
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+    # Context
+    conversation_id: Optional[UUID] = None
+    run_id: Optional[UUID] = None
+    agent_key: Optional[str] = None
+
+    # Additional dimensions for grouping/filtering
+    tags: dict = field(default_factory=dict)
+
+    metadata: dict = field(default_factory=dict)
+
+
+class AuditStore(ABC):
+    """
+    Abstract interface for audit and history storage.
+
+    Audit stores handle interaction logs, error history, and
+    performance metrics. This is optional - agents can function
+    without an audit store.
+    """
+
+    # Audit entry operations
+    @abstractmethod
+    async def log_event(self, entry: AuditEntry, scope: Scope = Scope.PROJECT) -> None:
+        """Log an audit event."""
+        ...
+
+    @abstractmethod
+    async def get_events(
+        self,
+        scope: Scope = Scope.PROJECT,
+        conversation_id: Optional[UUID] = None,
+        run_id: Optional[UUID] = None,
+        event_types: Optional[list[AuditEventType]] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> list[AuditEntry]:
+        """Get audit events with optional filters."""
+        ...
+
+    # Error operations
+    @abstractmethod
+    async def log_error(self, error: ErrorRecord, scope: Scope = Scope.PROJECT) -> None:
+        """Log an error."""
+        ...
+
+    @abstractmethod
+    async def get_errors(
+        self,
+        scope: Scope = Scope.PROJECT,
+        severity: Optional[ErrorSeverity] = None,
+        resolved: Optional[bool] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> list[ErrorRecord]:
+        """Get errors with optional filters."""
+        ...
+
+    @abstractmethod
+    async def resolve_error(
+        self,
+        error_id: UUID,
+        resolution_notes: Optional[str] = None,
+        scope: Scope = Scope.PROJECT,
+    ) -> bool:
+        """Mark an error as resolved. Returns True if error existed."""
+        ...
+
+    # Performance metric operations
+    @abstractmethod
+    async def record_metric(self, metric: PerformanceMetric, scope: Scope = Scope.PROJECT) -> None:
+        """Record a performance metric."""
+        ...
+
+    @abstractmethod
+    async def get_metrics(
+        self,
+        name: str,
+        scope: Scope = Scope.PROJECT,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        tags: Optional[dict] = None,
+        limit: int = 1000,
+    ) -> list[PerformanceMetric]:
+        """Get metrics by name with optional filters."""
+        ...
+
+    @abstractmethod
+    async def get_metric_summary(
+        self,
+        name: str,
+        scope: Scope = Scope.PROJECT,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+    ) -> dict:
+        """
+        Get summary statistics for a metric.
+        Returns: {count, min, max, avg, sum, p50, p95, p99}
+        """
+        ...
+
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass