pygeai-orchestration 0.1.0b2__py3-none-any.whl

pygeai_orchestration/core/common/context.py

@@ -0,0 +1,140 @@
+"""
+Execution context management for orchestration patterns.
+
+This module provides context storage for pattern execution, enabling
+sharing of data, configuration, and state across components.
+"""
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+class Context(BaseModel):
+    """
+    Execution context for pattern and agent operations.
+
+    This Pydantic model provides a simple key-value store for sharing
+    data, configuration, and temporary state during execution.
+
+    :param data: Dict[str, Any] - Context data storage.
+    :param created_at: datetime - Timestamp when context was created.
+    :param updated_at: datetime - Timestamp of last update.
+    """
+
+    data: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    def set(self, key: str, value: Any) -> None:
+        """
+        Set a context value and update timestamp.
+
+        :param key: str - Context key.
+        :param value: Any - Value to store.
+        """
+        self.data[key] = value
+        self.updated_at = datetime.utcnow()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a context value with optional default.
+
+        :param key: str - Context key.
+        :param default: Any - Default value if key not found.
+        :return: Any - Stored value or default.
+        """
+        return self.data.get(key, default)
+
+    def has(self, key: str) -> bool:
+        """
+        Check if a key exists in context.
+
+        :param key: str - Context key.
+        :return: bool - True if key exists, False otherwise.
+        """
+        return key in self.data
+
+    def remove(self, key: str) -> None:
+        """
+        Remove a key from context and update timestamp.
+
+        :param key: str - Context key to remove.
+        """
+        if key in self.data:
+            del self.data[key]
+            self.updated_at = datetime.utcnow()
+
+    def update(self, data: Dict[str, Any]) -> None:
+        """
+        Merge data into context and update timestamp.
+
+        :param data: Dict[str, Any] - Data to merge into context.
+        """
+        self.data.update(data)
+        self.updated_at = datetime.utcnow()
+
+    def clear(self) -> None:
+        """Clear all context data and update timestamp."""
+        self.data.clear()
+        self.updated_at = datetime.utcnow()
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+
+class ContextManager:
+    """
+    Manager for multiple execution contexts.
+
+    Provides centralized management of multiple context instances,
+    enabling isolated execution environments for different patterns or agents.
+    """
+
+    def __init__(self):
+        """Initialize the context manager with empty context registry."""
+        self._contexts: Dict[str, Context] = {}
+
+    def create_context(
+        self, context_id: str, initial_data: Optional[Dict[str, Any]] = None
+    ) -> Context:
+        """
+        Create and register a new context.
+
+        :param context_id: str - Unique identifier for the context.
+        :param initial_data: Optional[Dict[str, Any]] - Initial data for the context.
+        :return: Context - The newly created context instance.
+        """
+        context = Context(data=initial_data or {})
+        self._contexts[context_id] = context
+        return context
+
+    def get_context(self, context_id: str) -> Optional[Context]:
+        """
+        Retrieve a context by ID.
+
+        :param context_id: str - Context identifier.
+        :return: Optional[Context] - The context if found, None otherwise.
+        """
+        return self._contexts.get(context_id)
+
+    def delete_context(self, context_id: str) -> None:
+        """
+        Delete a context by ID.
+
+        :param context_id: str - Context identifier to delete.
+        """
+        if context_id in self._contexts:
+            del self._contexts[context_id]
+
+    def list_contexts(self) -> list:
+        """
+        List all registered context IDs.
+
+        :return: list - List of context identifiers.
+        """
+        return list(self._contexts.keys())
+
+    def clear_all(self) -> None:
+        """Clear all registered contexts."""
+        self._contexts.clear()

pygeai_orchestration/core/common/memory.py

@@ -0,0 +1,176 @@
+"""
+Memory management for orchestration patterns.
+
+This module provides short-term and long-term memory capabilities for agents
+and patterns, including key-value storage, access tracking, and eviction policies.
+"""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+class MemoryEntry(BaseModel):
+    """
+    Single memory entry with metadata and access tracking.
+
+    This Pydantic model represents an individual piece of stored information
+    with timestamp, access count, and custom metadata.
+
+    :param key: str - Unique identifier for this entry.
+    :param value: Any - The stored value.
+    :param timestamp: datetime - When this entry was created.
+    :param access_count: int - Number of times this entry has been accessed.
+    :param metadata: Dict[str, Any] - Custom metadata for this entry.
+    """
+
+    key: str = Field(..., description="Memory entry key")
+    value: Any = Field(..., description="Memory entry value")
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    access_count: int = Field(0, ge=0)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+
+class Memory(BaseModel):
+    """
+    Memory storage with size limits and eviction.
+
+    This Pydantic model provides a bounded key-value store with automatic
+    eviction of oldest entries when capacity is reached.
+
+    :param entries: Dict[str, MemoryEntry] - Stored memory entries.
+    :param max_size: Optional[int] - Maximum number of entries. None means unlimited.
+    """
+
+    entries: Dict[str, MemoryEntry] = Field(default_factory=dict)
+    max_size: Optional[int] = Field(None, ge=1, description="Maximum number of entries")
+
+    def store(self, key: str, value: Any, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Store a value in memory, evicting oldest if at capacity.
+
+        :param key: str - Entry key.
+        :param value: Any - Value to store.
+        :param metadata: Optional[Dict[str, Any]] - Custom metadata for this entry.
+        """
+        if self.max_size and len(self.entries) >= self.max_size and key not in self.entries:
+            oldest_key = min(self.entries.keys(), key=lambda k: self.entries[k].timestamp)
+            del self.entries[oldest_key]
+
+        self.entries[key] = MemoryEntry(key=key, value=value, metadata=metadata or {})
+
+    def retrieve(self, key: str) -> Optional[Any]:
+        """
+        Retrieve a value and increment access count.
+
+        :param key: str - Entry key.
+        :return: Optional[Any] - Stored value if found, None otherwise.
+        """
+        entry = self.entries.get(key)
+        if entry:
+            entry.access_count += 1
+            return entry.value
+        return None
+
+    def has(self, key: str) -> bool:
+        """
+        Check if a key exists in memory.
+
+        :param key: str - Entry key.
+        :return: bool - True if key exists, False otherwise.
+        """
+        return key in self.entries
+
+    def remove(self, key: str) -> None:
+        """
+        Remove an entry from memory.
+
+        :param key: str - Entry key to remove.
+        """
+        if key in self.entries:
+            del self.entries[key]
+
+    def clear(self) -> None:
+        """Clear all entries from memory."""
+        self.entries.clear()
+
+    def size(self) -> int:
+        """
+        Get the current number of entries.
+
+        :return: int - Number of stored entries.
+        """
+        return len(self.entries)
+
+    def get_recent(self, limit: int = 10) -> List[MemoryEntry]:
+        """
+        Get the most recently created entries.
+
+        :param limit: int - Maximum number of entries to return.
+        :return: List[MemoryEntry] - Recent entries sorted by timestamp (newest first).
+        """
+        sorted_entries = sorted(self.entries.values(), key=lambda e: e.timestamp, reverse=True)
+        return sorted_entries[:limit]
+
+
+class MemoryStore:
+    """
+    Manager for multiple memory instances.
+
+    Provides centralized management of multiple memory instances,
+    enabling separate memory spaces for different agents or contexts.
+    """
+
+    def __init__(self, max_size: Optional[int] = None):
+        """
+        Initialize the memory store.
+
+        :param max_size: Optional[int] - Default max size for created memories.
+        """
+        self._memories: Dict[str, Memory] = {}
+        self._max_size = max_size
+
+    def create_memory(self, memory_id: str, max_size: Optional[int] = None) -> Memory:
+        """
+        Create and register a new memory instance.
+
+        :param memory_id: str - Unique identifier for the memory.
+        :param max_size: Optional[int] - Max size for this memory (overrides default).
+        :return: Memory - The newly created memory instance.
+        """
+        memory = Memory(max_size=max_size or self._max_size)
+        self._memories[memory_id] = memory
+        return memory
+
+    def get_memory(self, memory_id: str) -> Optional[Memory]:
+        """
+        Retrieve a memory instance by ID.
+
+        :param memory_id: str - Memory identifier.
+        :return: Optional[Memory] - The memory if found, None otherwise.
+        """
+        return self._memories.get(memory_id)
+
+    def delete_memory(self, memory_id: str) -> None:
+        """
+        Delete a memory instance.
+
+        :param memory_id: str - Memory identifier to delete.
+        """
+        if memory_id in self._memories:
+            del self._memories[memory_id]
+
+    def list_memories(self) -> list:
+        """
+        List all registered memory IDs.
+
+        :return: list - List of memory identifiers.
+        """
+        return list(self._memories.keys())
+
+    def clear_all(self) -> None:
+        """Clear all memory instances."""
+        self._memories.clear()

pygeai_orchestration/core/common/message.py

@@ -0,0 +1,50 @@
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+from datetime import datetime
+from enum import Enum
+
+
+class MessageRole(str, Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+class Message(BaseModel):
+    role: MessageRole = Field(..., description="Message role")
+    content: str = Field(..., description="Message content")
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    tool_calls: Optional[List[Dict[str, Any]]] = None
+    tool_results: Optional[List[Dict[str, Any]]] = None
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+
+class Conversation(BaseModel):
+    id: str = Field(..., description="Conversation ID")
+    messages: List[Message] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    def add_message(self, message: Message) -> None:
+        self.messages.append(message)
+        self.updated_at = datetime.utcnow()
+
+    def get_messages(self, role: Optional[MessageRole] = None) -> List[Message]:
+        if role is None:
+            return self.messages.copy()
+        return [msg for msg in self.messages if msg.role == role]
+
+    def clear(self) -> None:
+        self.messages.clear()
+        self.updated_at = datetime.utcnow()
+
+    def to_dict_list(self) -> List[Dict[str, Any]]:
+        return [{"role": msg.role.value, "content": msg.content} for msg in self.messages]
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}

pygeai_orchestration/core/common/state.py

@@ -0,0 +1,181 @@
+"""
+State management for orchestration patterns.
+
+This module provides state tracking and checkpoint functionality for
+pattern execution, enabling pause/resume and state recovery.
+"""
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+from datetime import datetime
+from enum import Enum
+
+
+class StateStatus(str, Enum):
+    """
+    Enumeration of execution state statuses.
+
+    Tracks the lifecycle of pattern execution:
+    - INITIALIZED: State created, not yet started
+    - RUNNING: Actively executing
+    - PAUSED: Execution temporarily suspended
+    - COMPLETED: Successfully finished
+    - FAILED: Execution failed with error
+    """
+
+    INITIALIZED = "initialized"
+    RUNNING = "running"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class State(BaseModel):
+    """
+    State model for tracking pattern execution state.
+
+    This Pydantic model maintains execution status, data, checkpoints,
+    and timestamps for pattern lifecycle management.
+
+    :param status: StateStatus - Current execution status.
+    :param data: Dict[str, Any] - Arbitrary state data storage.
+    :param checkpoint: Optional[Dict[str, Any]] - Saved checkpoint for recovery.
+    :param created_at: datetime - Timestamp when state was created.
+    :param updated_at: datetime - Timestamp of last update.
+    """
+
+    status: StateStatus = Field(StateStatus.INITIALIZED, description="Current state status")
+    data: Dict[str, Any] = Field(default_factory=dict)
+    checkpoint: Optional[Dict[str, Any]] = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    def update_status(self, status: StateStatus) -> None:
+        """
+        Update the execution status and timestamp.
+
+        :param status: StateStatus - New status to set.
+        """
+        self.status = status
+        self.updated_at = datetime.utcnow()
+
+    def set(self, key: str, value: Any) -> None:
+        """
+        Set a data value and update timestamp.
+
+        :param key: str - Data key.
+        :param value: Any - Value to store.
+        """
+        self.data[key] = value
+        self.updated_at = datetime.utcnow()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get a data value with optional default.
+
+        :param key: str - Data key.
+        :param default: Any - Default value if key not found.
+        :return: Any - Stored value or default.
+        """
+        return self.data.get(key, default)
+
+    def create_checkpoint(self) -> None:
+        """
+        Create a checkpoint snapshot of current state.
+
+        Captures status, data, and timestamp for later restoration.
+        """
+        self.checkpoint = {
+            "status": self.status.value,
+            "data": self.data.copy(),
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+
+    def restore_checkpoint(self) -> bool:
+        """
+        Restore state from the most recent checkpoint.
+
+        :return: bool - True if restored successfully, False if no checkpoint exists.
+        """
+        if self.checkpoint is None:
+            return False
+        self.status = StateStatus(self.checkpoint["status"])
+        self.data = self.checkpoint["data"].copy()
+        self.updated_at = datetime.utcnow()
+        return True
+
+    class Config:
+        json_encoders = {datetime: lambda v: v.isoformat()}
+
+
+class StateManager:
+    """
+    Manager for multiple pattern execution states.
+
+    Provides centralized management of multiple state instances,
+    enabling orchestration of concurrent pattern executions.
+    """
+
+    def __init__(self):
+        """Initialize the state manager with empty state registry."""
+        self._states: Dict[str, State] = {}
+
+    def create_state(self, state_id: str, initial_data: Optional[Dict[str, Any]] = None) -> State:
+        """
+        Create and register a new state.
+
+        :param state_id: str - Unique identifier for the state.
+        :param initial_data: Optional[Dict[str, Any]] - Initial data for the state.
+        :return: State - The newly created state instance.
+        """
+        state = State(data=initial_data or {})
+        self._states[state_id] = state
+        return state
+
+    def get_state(self, state_id: str) -> Optional[State]:
+        """
+        Retrieve a state by ID.
+
+        :param state_id: str - State identifier.
+        :return: Optional[State] - The state if found, None otherwise.
+        """
+        return self._states.get(state_id)
+
+    def update_state(
+        self, state_id: str, status: StateStatus, data: Optional[Dict[str, Any]] = None
+    ) -> bool:
+        """
+        Update an existing state's status and data.
+
+        :param state_id: str - State identifier.
+        :param status: StateStatus - New status to set.
+        :param data: Optional[Dict[str, Any]] - Data to merge into state.
+        :return: bool - True if updated, False if state not found.
+        """
+        state = self._states.get(state_id)
+        if state is None:
+            return False
+        state.update_status(status)
+        if data:
+            state.data.update(data)
+        return True
+
+    def delete_state(self, state_id: str) -> None:
+        """
+        Delete a state by ID.
+
+        :param state_id: str - State identifier to delete.
+        """
+        if state_id in self._states:
+            del self._states[state_id]
+
+    def list_states(self) -> list:
+        """
+        List all registered state IDs.
+
+        :return: list - List of state identifiers.
+        """
+        return list(self._states.keys())
+
+    def clear_all(self) -> None:
+        self._states.clear()