aiecs 1.5.1__py3-none-any.whl

aiecs/core/__init__.py

@@ -0,0 +1,46 @@
+"""
+Core module for the Python middleware application.
+
+This module provides the core interfaces and abstractions including:
+- Execution interfaces
+- Core abstractions
+"""
+
+# Core interfaces
+from .interface.execution_interface import (
+    ExecutionInterface,
+    IToolProvider,
+    IToolExecutor,
+    ICacheProvider,
+    IOperationExecutor,
+)
+
+from .interface.storage_interface import (
+    ISessionStorage,
+    IConversationStorage,
+    ICheckpointStorage,
+    ITaskContextStorage,
+    IStorageBackend,
+    ICheckpointerBackend,
+)
+
+__all__ = [
+    # Execution interfaces
+    "ExecutionInterface",
+    "IToolProvider",
+    "IToolExecutor",
+    "ICacheProvider",
+    "IOperationExecutor",
+    # Storage interfaces
+    "ISessionStorage",
+    "IConversationStorage",
+    "ICheckpointStorage",
+    "ITaskContextStorage",
+    "IStorageBackend",
+    "ICheckpointerBackend",
+]
+
+# Version information
+__version__ = "1.0.0"
+__author__ = "Python Middleware Team"
+__description__ = "Core interfaces and abstractions for the middleware architecture"

aiecs/core/interface/__init__.py

@@ -0,0 +1,34 @@
+"""Core interfaces module"""
+
+from .execution_interface import (
+    ExecutionInterface,
+    IToolProvider,
+    IToolExecutor,
+    ICacheProvider,
+    IOperationExecutor,
+)
+
+from .storage_interface import (
+    ISessionStorage,
+    IConversationStorage,
+    ICheckpointStorage,
+    ITaskContextStorage,
+    IStorageBackend,
+    ICheckpointerBackend,
+)
+
+__all__ = [
+    # Execution interfaces
+    "ExecutionInterface",
+    "IToolProvider",
+    "IToolExecutor",
+    "ICacheProvider",
+    "IOperationExecutor",
+    # Storage interfaces
+    "ISessionStorage",
+    "IConversationStorage",
+    "ICheckpointStorage",
+    "ITaskContextStorage",
+    "IStorageBackend",
+    "ICheckpointerBackend",
+]

aiecs/core/interface/execution_interface.py

@@ -0,0 +1,152 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Callable
+from aiecs.domain.execution.model import TaskStepResult
+
+
+class IToolProvider(ABC):
+    """Tool provider interface - Domain layer abstraction"""
+
+    @abstractmethod
+    def get_tool(self, tool_name: str) -> Any:
+        """Get tool instance"""
+
+    @abstractmethod
+    def has_tool(self, tool_name: str) -> bool:
+        """Check if tool exists"""
+
+
+class IToolExecutor(ABC):
+    """Tool executor interface - Domain layer abstraction"""
+
+    @abstractmethod
+    def execute(self, tool: Any, operation_name: str, **params) -> Any:
+        """Execute tool operation synchronously"""
+
+    @abstractmethod
+    async def execute_async(self, tool: Any, operation_name: str, **params) -> Any:
+        """Execute tool operation asynchronously"""
+
+
+class ICacheProvider(ABC):
+    """Cache provider interface - Domain layer abstraction"""
+
+    @abstractmethod
+    def generate_cache_key(
+        self,
+        operation_type: str,
+        user_id: str,
+        task_id: str,
+        args: tuple,
+        kwargs: Dict[str, Any],
+    ) -> str:
+        """Generate cache key"""
+
+    @abstractmethod
+    def get_from_cache(self, cache_key: str) -> Optional[Any]:
+        """Get data from cache"""
+
+    @abstractmethod
+    def add_to_cache(self, cache_key: str, value: Any) -> None:
+        """Add data to cache"""
+
+
+class IOperationExecutor(ABC):
+    """Operation executor interface - Domain layer abstraction"""
+
+    @abstractmethod
+    async def execute_operation(self, operation_spec: str, params: Dict[str, Any]) -> Any:
+        """Execute single operation"""
+
+    @abstractmethod
+    async def batch_execute_operations(self, operations: List[Dict[str, Any]]) -> List[Any]:
+        """Batch execute operations"""
+
+    @abstractmethod
+    async def execute_operations_sequence(
+        self,
+        operations: List[Dict[str, Any]],
+        user_id: str,
+        task_id: str,
+        stop_on_failure: bool = False,
+        save_callback: Optional[Callable] = None,
+    ) -> List[TaskStepResult]:
+        """Execute operations sequence sequentially"""
+
+    @abstractmethod
+    async def execute_parallel_operations(
+        self, operations: List[Dict[str, Any]]
+    ) -> List[TaskStepResult]:
+        """Execute operations in parallel"""
+
+
+class ExecutionInterface(ABC):
+    """
+    Unified execution interface that defines standard methods for service and tool execution.
+    Supports plugin-based execution engines, allowing future introduction of new executors without modifying upper-level code.
+    """
+
+    @abstractmethod
+    async def execute_operation(self, operation_spec: str, params: Dict[str, Any]) -> Any:
+        """
+        Execute a single operation (e.g., tool operation or service subtask).
+
+        Args:
+            operation_spec (str): Operation specification, format as 'tool_name.operation_name' or other identifier
+            params (Dict[str, Any]): Operation parameters
+
+        Returns:
+            Any: Operation result
+        """
+
+    @abstractmethod
+    async def execute_task(
+        self,
+        task_name: str,
+        input_data: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> Any:
+        """
+        Execute a single task (e.g., service task).
+
+        Args:
+            task_name (str): Task name
+            input_data (Dict[str, Any]): Input data
+            context (Dict[str, Any]): Context information
+
+        Returns:
+            Any: Task result
+        """
+
+    @abstractmethod
+    async def batch_execute_operations(self, operations: List[Dict[str, Any]]) -> List[Any]:
+        """
+        Batch execute multiple operations.
+
+        Args:
+            operations (List[Dict[str, Any]]): List of operations, each containing 'operation' and 'params'
+
+        Returns:
+            List[Any]: List of operation results
+        """
+
+    @abstractmethod
+    async def batch_execute_tasks(self, tasks: List[Dict[str, Any]]) -> List[Any]:
+        """
+        Batch execute multiple tasks.
+
+        Args:
+            tasks (List[Dict[str, Any]]): List of tasks, each containing 'task_name', 'input_data', 'context'
+
+        Returns:
+            List[Any]: List of task results
+        """
+
+    def register_executor(self, executor_type: str, executor_instance: Any) -> None:
+        """
+        Register new executor type, supporting plugin-based extension.
+
+        Args:
+            executor_type (str): Executor type identifier
+            executor_instance (Any): Executor instance
+        """
+        raise NotImplementedError("Executor registration is not implemented in this interface")

aiecs/core/interface/storage_interface.py

@@ -0,0 +1,171 @@
+"""
+Storage interfaces for the middleware architecture.
+
+This module defines the core storage abstractions following the same pattern
+as other core interfaces, enabling dependency inversion and clean architecture.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, List
+
+
+class ISessionStorage(ABC):
+    """Session storage interface - Domain layer abstraction"""
+
+    @abstractmethod
+    async def create_session(
+        self, session_id: str, user_id: str, metadata: Dict[str, Any] = None
+    ) -> Dict[str, Any]:
+        """Create a new session."""
+
+    @abstractmethod
+    async def get_session(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """Get session by ID."""
+
+    @abstractmethod
+    async def update_session(
+        self,
+        session_id: str,
+        updates: Dict[str, Any] = None,
+        increment_requests: bool = False,
+        add_processing_time: float = 0.0,
+        mark_error: bool = False,
+    ) -> bool:
+        """Update session with activity and metrics."""
+
+    @abstractmethod
+    async def end_session(self, session_id: str, status: str = "completed") -> bool:
+        """End a session and update metrics."""
+
+
+class IConversationStorage(ABC):
+    """Conversation storage interface - Domain layer abstraction"""
+
+    @abstractmethod
+    async def add_conversation_message(
+        self,
+        session_id: str,
+        role: str,
+        content: str,
+        metadata: Dict[str, Any] = None,
+    ) -> bool:
+        """Add message to conversation history."""
+
+    @abstractmethod
+    async def get_conversation_history(
+        self, session_id: str, limit: int = 50
+    ) -> List[Dict[str, Any]]:
+        """Get conversation history for a session."""
+
+
+class ICheckpointStorage(ABC):
+    """Checkpoint storage interface - Domain layer abstraction"""
+
+    @abstractmethod
+    async def store_checkpoint(
+        self,
+        thread_id: str,
+        checkpoint_id: str,
+        checkpoint_data: Dict[str, Any],
+        metadata: Dict[str, Any] = None,
+    ) -> bool:
+        """Store checkpoint data."""
+
+    @abstractmethod
+    async def get_checkpoint(
+        self, thread_id: str, checkpoint_id: str = None
+    ) -> Optional[Dict[str, Any]]:
+        """Get checkpoint data. If checkpoint_id is None, get the latest."""
+
+    @abstractmethod
+    async def list_checkpoints(self, thread_id: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """List checkpoints for a thread, ordered by creation time."""
+
+
+class ITaskContextStorage(ABC):
+    """Task context storage interface - Domain layer abstraction"""
+
+    @abstractmethod
+    async def get_task_context(self, session_id: str) -> Optional[Any]:
+        """Get TaskContext for a session."""
+
+    @abstractmethod
+    async def store_task_context(self, session_id: str, context: Any) -> bool:
+        """Store TaskContext for a session."""
+
+
+class IStorageBackend(
+    ISessionStorage,
+    IConversationStorage,
+    ICheckpointStorage,
+    ITaskContextStorage,
+):
+    """
+    Unified storage backend interface - Domain layer abstraction
+
+    This interface combines all storage capabilities and follows the same
+    pattern as other core interfaces in the middleware architecture.
+    """
+
+    @abstractmethod
+    async def initialize(self) -> bool:
+        """Initialize the storage backend."""
+
+    @abstractmethod
+    async def close(self):
+        """Close the storage backend."""
+
+    @abstractmethod
+    async def health_check(self) -> Dict[str, Any]:
+        """Perform health check."""
+
+    @abstractmethod
+    async def get_metrics(self) -> Dict[str, Any]:
+        """Get comprehensive metrics."""
+
+    @abstractmethod
+    async def cleanup_expired_sessions(self, max_idle_hours: int = 24) -> int:
+        """Clean up expired sessions and associated data."""
+
+
+class ICheckpointerBackend(ABC):
+    """
+    Checkpointer backend interface for LangGraph integration.
+
+    This interface defines the minimal contract needed by BaseServiceCheckpointer
+    to work with any storage backend, following dependency inversion principle.
+    """
+
+    @abstractmethod
+    async def put_checkpoint(
+        self,
+        thread_id: str,
+        checkpoint_id: str,
+        checkpoint_data: Dict[str, Any],
+        metadata: Dict[str, Any] = None,
+    ) -> bool:
+        """Store a checkpoint for LangGraph workflows."""
+
+    @abstractmethod
+    async def get_checkpoint(
+        self, thread_id: str, checkpoint_id: str = None
+    ) -> Optional[Dict[str, Any]]:
+        """Retrieve a checkpoint for LangGraph workflows."""
+
+    @abstractmethod
+    async def list_checkpoints(self, thread_id: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """List checkpoints for LangGraph workflows."""
+
+    @abstractmethod
+    async def put_writes(
+        self,
+        thread_id: str,
+        checkpoint_id: str,
+        task_id: str,
+        writes_data: List[tuple],
+    ) -> bool:
+        """Store intermediate writes for a checkpoint."""
+
+    @abstractmethod
+    async def get_writes(self, thread_id: str, checkpoint_id: str) -> List[tuple]:
+        """Get intermediate writes for a checkpoint."""

aiecs/domain/__init__.py

@@ -0,0 +1,289 @@
+"""Domain layer module
+
+Contains business logic and domain models.
+"""
+
+from .execution.model import TaskStepResult, TaskStatus, ErrorCode
+from .task.model import TaskContext, DSLStep
+from .task.dsl_processor import DSLProcessor
+from .context import (
+    ContextEngine,
+    SessionMetrics,
+    ConversationMessage,
+    ConversationParticipant,
+    ConversationSession,
+    AgentCommunicationMessage,
+    create_session_key,
+    validate_conversation_isolation_pattern,
+)
+from .community import (
+    # Core managers
+    CommunityManager,
+    CommunityIntegration,
+    DecisionEngine,
+    ResourceManager,
+    CollaborativeWorkflowEngine,
+    CommunityAnalytics,
+    MemberLifecycleHooks,
+    # Communication and context
+    CommunicationHub,
+    Message,
+    Event,
+    MessageType,
+    EventType,
+    SharedContextManager,
+    SharedContext,
+    ContextScope,
+    ContextConflictStrategy,
+    # Agent adapters
+    AgentAdapter,
+    StandardLLMAdapter,
+    CustomAgentAdapter,
+    AgentAdapterRegistry,
+    AgentCapability,
+    # Builder
+    CommunityBuilder,
+    builder,
+    # Enums
+    CommunityRole,
+    GovernanceType,
+    DecisionStatus,
+    ResourceType,
+    ConsensusAlgorithm,
+    ConflictResolutionStrategy,
+    # Models
+    CommunityMember,
+    CommunityResource,
+    CommunityDecision,
+    AgentCommunity,
+    CollaborationSession,
+    # Exceptions
+    CommunityException,
+    CommunityNotFoundError,
+    MemberNotFoundError,
+    ResourceNotFoundError,
+    DecisionNotFoundError,
+    AccessDeniedError,
+    MembershipError,
+    VotingError,
+    GovernanceError,
+    CollaborationError,
+    CommunityInitializationError,
+    CommunityValidationError,
+    QuorumNotMetError,
+    ConflictResolutionError,
+    CommunityCapacityError,
+    AgentAdapterError,
+    CommunicationError,
+    ContextError,
+)
+
+from .agent import (
+    # Exceptions
+    AgentException,
+    AgentNotFoundError,
+    AgentAlreadyRegisteredError,
+    InvalidStateTransitionError,
+    ConfigurationError,
+    TaskExecutionError,
+    ToolAccessDeniedError,
+    SerializationError,
+    AgentInitializationError,
+    # Enums
+    AgentState,
+    AgentType,
+    GoalStatus,
+    GoalPriority,
+    CapabilityLevel,
+    MemoryType,
+    # Models
+    RetryPolicy,
+    AgentConfiguration,
+    AgentGoal,
+    AgentCapabilityDeclaration,
+    AgentMetrics,
+    AgentInteraction,
+    AgentMemory,
+    # Base and Concrete Agents
+    BaseAIAgent,
+    LLMAgent,
+    ToolAgent,
+    HybridAgent,
+    # Lifecycle Management
+    AgentRegistry,
+    AgentLifecycleManager,
+    get_global_registry,
+    get_global_lifecycle_manager,
+    # Persistence
+    InMemoryPersistence,
+    FilePersistence,
+    get_global_persistence,
+    set_global_persistence,
+    # Observability
+    AgentController,
+    LoggingObserver,
+    MetricsObserver,
+    # Prompts
+    PromptTemplate,
+    ChatPromptTemplate,
+    MessageBuilder,
+    # Tools
+    ToolSchemaGenerator,
+    generate_tool_schema,
+    # Memory
+    ConversationMemory,
+    Session,
+    # Integration
+    ContextEngineAdapter,
+    EnhancedRetryPolicy,
+    RoleConfiguration,
+    ContextCompressor,
+    compress_messages,
+    # Migration
+    LegacyAgentWrapper,
+    convert_langchain_prompt,
+    convert_legacy_config,
+)
+
+__all__ = [
+    # Execution domain
+    "TaskStepResult",
+    "TaskStatus",
+    "ErrorCode",
+    # Task domain
+    "TaskContext",
+    "DSLStep",
+    "DSLProcessor",
+    # Context domain
+    "ContextEngine",
+    "SessionMetrics",
+    "ConversationMessage",
+    "ConversationParticipant",
+    "ConversationSession",
+    "AgentCommunicationMessage",
+    "create_session_key",
+    "validate_conversation_isolation_pattern",
+    # Community domain - Core managers
+    "CommunityManager",
+    "CommunityIntegration",
+    "DecisionEngine",
+    "ResourceManager",
+    "CollaborativeWorkflowEngine",
+    "CommunityAnalytics",
+    "MemberLifecycleHooks",
+    # Community domain - Communication and context
+    "CommunicationHub",
+    "Message",
+    "Event",
+    "MessageType",
+    "EventType",
+    "SharedContextManager",
+    "SharedContext",
+    "ContextScope",
+    "ContextConflictStrategy",
+    # Community domain - Agent adapters
+    "AgentAdapter",
+    "StandardLLMAdapter",
+    "CustomAgentAdapter",
+    "AgentAdapterRegistry",
+    "AgentCapability",
+    # Community domain - Builder
+    "CommunityBuilder",
+    "builder",
+    # Community domain - Enums
+    "CommunityRole",
+    "GovernanceType",
+    "DecisionStatus",
+    "ResourceType",
+    "ConsensusAlgorithm",
+    "ConflictResolutionStrategy",
+    # Community domain - Models
+    "CommunityMember",
+    "CommunityResource",
+    "CommunityDecision",
+    "AgentCommunity",
+    "CollaborationSession",
+    # Community domain - Exceptions
+    "CommunityException",
+    "CommunityNotFoundError",
+    "MemberNotFoundError",
+    "ResourceNotFoundError",
+    "DecisionNotFoundError",
+    "AccessDeniedError",
+    "MembershipError",
+    "VotingError",
+    "GovernanceError",
+    "CollaborationError",
+    "CommunityInitializationError",
+    "CommunityValidationError",
+    "QuorumNotMetError",
+    "ConflictResolutionError",
+    "CommunityCapacityError",
+    "AgentAdapterError",
+    "CommunicationError",
+    "ContextError",
+    # Agent domain - Exceptions
+    "AgentException",
+    "AgentNotFoundError",
+    "AgentAlreadyRegisteredError",
+    "InvalidStateTransitionError",
+    "ConfigurationError",
+    "TaskExecutionError",
+    "ToolAccessDeniedError",
+    "SerializationError",
+    "AgentInitializationError",
+    # Agent domain - Enums
+    "AgentState",
+    "AgentType",
+    "GoalStatus",
+    "GoalPriority",
+    "CapabilityLevel",
+    "MemoryType",
+    # Agent domain - Models
+    "RetryPolicy",
+    "AgentConfiguration",
+    "AgentGoal",
+    "AgentCapabilityDeclaration",
+    "AgentMetrics",
+    "AgentInteraction",
+    "AgentMemory",
+    # Agent domain - Base and Concrete Agents
+    "BaseAIAgent",
+    "LLMAgent",
+    "ToolAgent",
+    "HybridAgent",
+    # Agent domain - Lifecycle Management
+    "AgentRegistry",
+    "AgentLifecycleManager",
+    "get_global_registry",
+    "get_global_lifecycle_manager",
+    # Agent domain - Persistence
+    "InMemoryPersistence",
+    "FilePersistence",
+    "get_global_persistence",
+    "set_global_persistence",
+    # Agent domain - Observability
+    "AgentController",
+    "LoggingObserver",
+    "MetricsObserver",
+    # Agent domain - Prompts
+    "PromptTemplate",
+    "ChatPromptTemplate",
+    "MessageBuilder",
+    # Agent domain - Tools
+    "ToolSchemaGenerator",
+    "generate_tool_schema",
+    # Agent domain - Memory
+    "ConversationMemory",
+    "Session",
+    # Agent domain - Integration
+    "ContextEngineAdapter",
+    "EnhancedRetryPolicy",
+    "RoleConfiguration",
+    "ContextCompressor",
+    "compress_messages",
+    # Agent domain - Migration
+    "LegacyAgentWrapper",
+    "convert_langchain_prompt",
+    "convert_legacy_config",
+]