puffinflow 2.dev0__py3-none-any.whl

puffinflow/__init__.py

@@ -0,0 +1,132 @@
+"""
+PuffinFlow - Workflow Orchestration Framework.
+"""
+
+__version__ = "0.1.dev12+g0f61537.d20250701"
+__author__ = "Mohamed Ahmed"
+__email__ = "mohamed.ahmed.4894@gmail.com"
+
+# Core agent functionality
+from .core.agent import (
+    Agent,
+    AgentCheckpoint,
+    AgentResult,
+    AgentStatus,
+    Context,
+    Priority,
+    StateBuilder,
+    StateResult,
+    StateStatus,
+    build_state,
+    cpu_intensive,
+    critical_state,
+    gpu_accelerated,
+    io_intensive,
+    memory_intensive,
+    network_intensive,
+    state,
+)
+
+# Configuration
+from .core.config import Features, Settings, get_features, get_settings
+
+# Enhanced coordination
+from .core.coordination import (
+    AgentGroup,
+    AgentOrchestrator,
+    AgentPool,
+    Agents,
+    AgentTeam,
+    DynamicProcessingPool,
+    EventBus,
+    ParallelAgentGroup,
+    TeamResult,
+    WorkItem,
+    WorkQueue,
+    create_pipeline,
+    create_team,
+    run_agents_parallel,
+    run_agents_sequential,
+)
+
+# Reliability patterns
+from .core.reliability import (
+    Bulkhead,
+    BulkheadConfig,
+    CircuitBreaker,
+    CircuitBreakerConfig,
+    ResourceLeakDetector,
+)
+
+# Resource management
+from .core.resources import (
+    AllocationStrategy,
+    QuotaManager,
+    ResourcePool,
+    ResourceRequirements,
+    ResourceType,
+)
+
+__all__ = [
+    "Agent",
+    "AgentCheckpoint",
+    "AgentGroup",
+    "AgentOrchestrator",
+    "AgentPool",
+    "AgentResult",
+    "AgentStatus",
+    "AgentTeam",
+    "Agents",
+    "AllocationStrategy",
+    "Bulkhead",
+    "BulkheadConfig",
+    "CircuitBreaker",
+    "CircuitBreakerConfig",
+    "Context",
+    "DynamicProcessingPool",
+    "EventBus",
+    "Features",
+    "ParallelAgentGroup",
+    "Priority",
+    "QuotaManager",
+    "ResourceLeakDetector",
+    "ResourcePool",
+    "ResourceRequirements",
+    "ResourceType",
+    "Settings",
+    "StateBuilder",
+    "StateResult",
+    "StateStatus",
+    "TeamResult",
+    "WorkItem",
+    "WorkQueue",
+    "build_state",
+    "cpu_intensive",
+    "create_pipeline",
+    "create_team",
+    "critical_state",
+    "get_features",
+    "get_settings",
+    "gpu_accelerated",
+    "io_intensive",
+    "memory_intensive",
+    "network_intensive",
+    "run_agents_parallel",
+    "run_agents_sequential",
+    "state",
+]
+
+
+def get_version() -> str:
+    """Get PuffinFlow version."""
+    return __version__
+
+
+def get_info() -> dict[str, str]:
+    """Get PuffinFlow package information."""
+    return {
+        "version": __version__,
+        "author": __author__,
+        "email": __email__,
+        "description": "Workflow orchestration framework with advanced resource management and observability",
+    }

puffinflow/core/__init__.py

@@ -0,0 +1,110 @@
+"""Workflow Orchestrator Core Engine."""
+
+__version__ = "0.1.0"
+
+from .agent.base import Agent
+from .agent.context import Context
+from .agent.state import Priority, StateStatus
+from .resources.pool import ResourcePool
+from .resources.requirements import (
+    ResourceRequirements,
+    ResourceType,
+)
+
+# Import reliability components
+try:
+    from .reliability.bulkhead import Bulkhead, BulkheadConfig
+    from .reliability.circuit_breaker import (
+        CircuitBreaker,
+        CircuitBreakerConfig,
+    )
+    from .reliability.leak_detector import ResourceLeakDetector
+except ImportError:
+    # Create mock classes if reliability module is not available
+    from typing import Any
+
+    class MockCircuitBreaker:
+        def __init__(self, config: Any) -> None:
+            pass
+
+    class MockCircuitBreakerConfig:
+        def __init__(self, **kwargs: Any) -> None:
+            pass
+
+    class MockBulkhead:
+        def __init__(self, config: Any) -> None:
+            pass
+
+    class MockBulkheadConfig:
+        def __init__(self, **kwargs: Any) -> None:
+            pass
+
+    class MockResourceLeakDetector:
+        def __init__(self, **kwargs: Any) -> None:
+            pass
+
+    # Assign to actual names to avoid redefinition
+    CircuitBreaker = MockCircuitBreaker  # type: ignore[assignment,misc]
+    CircuitBreakerConfig = MockCircuitBreakerConfig  # type: ignore[assignment,misc]
+    Bulkhead = MockBulkhead  # type: ignore[assignment,misc]
+    BulkheadConfig = MockBulkheadConfig  # type: ignore[assignment,misc]
+    ResourceLeakDetector = MockResourceLeakDetector  # type: ignore[assignment,misc]
+
+
+# Import state decorator if available
+try:
+    from .agent.decorators.flexible import state
+except ImportError:
+    # Create a simple mock state decorator
+    from typing import Any, Callable
+
+    def state(**kwargs: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:  # type: ignore[misc]
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            # Create ResourceRequirements from kwargs
+            requirements = ResourceRequirements()
+            if "cpu" in kwargs:
+                requirements.cpu_units = kwargs["cpu"]
+            if "memory" in kwargs:
+                requirements.memory_mb = kwargs["memory"]
+            if "io" in kwargs:
+                requirements.io_weight = kwargs["io"]
+            if "network" in kwargs:
+                requirements.network_weight = kwargs["network"]
+            if "gpu" in kwargs:
+                requirements.gpu_units = kwargs["gpu"]
+
+            # Determine resource_types from non-zero values
+            resource_types = ResourceType.NONE
+            if requirements.cpu_units > 0:
+                resource_types |= ResourceType.CPU
+            if requirements.memory_mb > 0:
+                resource_types |= ResourceType.MEMORY
+            if requirements.io_weight > 0:
+                resource_types |= ResourceType.IO
+            if requirements.network_weight > 0:
+                resource_types |= ResourceType.NETWORK
+            if requirements.gpu_units > 0:
+                resource_types |= ResourceType.GPU
+
+            requirements.resource_types = resource_types
+            func._resource_requirements = requirements  # type: ignore
+            return func
+
+        return decorator
+
+
+__all__ = [
+    "Agent",
+    "Bulkhead",
+    "BulkheadConfig",
+    "CircuitBreaker",
+    "CircuitBreakerConfig",
+    "Context",
+    "Priority",
+    "ResourceLeakDetector",
+    "ResourcePool",
+    "ResourceRequirements",
+    "ResourceType",
+    "StateStatus",
+    "state",
+]

puffinflow/core/agent/__init__.py

@@ -0,0 +1,320 @@
+"""Agent module with enhanced coordination features."""
+
+from typing import Any, Callable
+
+from .base import Agent, AgentResult, ResourceTimeoutError
+from .checkpoint import AgentCheckpoint
+from .context import Context, StateType
+from .dependencies import DependencyConfig, DependencyLifecycle, DependencyType
+from .state import (
+    AgentStatus,
+    DeadLetter,
+    PrioritizedState,
+    Priority,
+    RetryPolicy,
+    StateMetadata,
+    StateResult,
+    StateStatus,
+)
+
+# Decorators
+try:
+    from .decorators.builder import (
+        StateBuilder,
+        build_state,
+        cpu_state,
+        exclusive_state,
+        external_service_state,
+        fault_tolerant_state,
+        gpu_state,
+        high_priority_state,
+        isolated_state,
+        memory_state,
+        production_state,
+        protected_state,
+    )
+    from .decorators.flexible import (
+        FlexibleStateDecorator,
+        StateProfile,
+        batch_state,
+        concurrent_state,
+        cpu_intensive,
+        create_custom_decorator,
+        critical_state,
+        external_service,
+        fault_tolerant,
+        get_profile,
+        gpu_accelerated,
+        high_availability,
+        io_intensive,
+        list_profiles,
+        memory_intensive,
+        minimal_state,
+        network_intensive,
+        quick_state,
+        state,
+    )
+
+    # synchronized_state,  # Temporarily disabled
+    from .decorators.inspection import (
+        compare_states,
+        get_state_config,
+        get_state_coordination,
+        get_state_rate_limit,
+        get_state_requirements,
+        get_state_summary,
+        is_puffinflow_state,
+        list_state_metadata,
+    )
+except ImportError:
+    # Decorators not available
+    pass
+
+# Scheduling components
+try:
+    from .scheduling import (
+        GlobalScheduler,
+        InputType,
+        InvalidInputTypeError,
+        InvalidScheduleError,
+        ScheduleBuilder,
+        ScheduledAgent,
+        ScheduledInput,
+        ScheduleParser,
+        SchedulingError,
+        parse_magic_prefix,
+        parse_schedule_string,
+    )
+
+    _SCHEDULING_AVAILABLE = True
+except ImportError:
+    # Scheduling not available
+    _SCHEDULING_AVAILABLE = False
+
+
+# Team decorators for convenience
+def create_team_decorator(
+    team_name: str, **defaults: Any
+) -> Callable[[Callable], Callable]:
+    """Create a decorator for team-specific agents."""
+    try:
+        from .decorators.flexible import create_custom_decorator
+
+        team_defaults = {
+            "tags": {"team": team_name},
+            "description": f"Agent for {team_name} team",
+            **defaults,
+        }
+        return create_custom_decorator(**team_defaults)
+    except ImportError:
+        return lambda func: func
+
+
+def create_environment_decorator(
+    env: str, **defaults: Any
+) -> Callable[[Callable], Callable]:
+    """Create a decorator for environment-specific agents."""
+    try:
+        from .decorators.flexible import create_custom_decorator
+
+        env_defaults = {
+            "tags": {"environment": env},
+            "description": f"Agent for {env} environment",
+            **defaults,
+        }
+        return create_custom_decorator(**env_defaults)
+    except ImportError:
+        return lambda func: func
+
+
+def create_service_decorator(
+    service_name: str, **defaults: Any
+) -> Callable[[Callable], Callable]:
+    """Create a decorator for service-specific agents."""
+    try:
+        from .decorators.flexible import create_custom_decorator
+
+        service_defaults = {
+            "tags": {"service": service_name},
+            "description": f"Agent for {service_name} service",
+            **defaults,
+        }
+        return create_custom_decorator(**service_defaults)
+    except ImportError:
+        return lambda func: func
+
+
+def create_reliable_team_decorator(
+    team_name: str, **defaults: Any
+) -> Callable[[Callable], Callable]:
+    """Create a decorator for reliable team agents."""
+    try:
+        from .decorators.flexible import create_custom_decorator
+
+        reliable_defaults = {
+            "tags": {"team": team_name, "reliability": "high"},
+            "circuit_breaker": True,
+            "bulkhead": True,
+            "retries": 5,
+            **defaults,
+        }
+        return create_custom_decorator(**reliable_defaults)
+    except ImportError:
+        return lambda func: func
+
+
+def create_external_team_decorator(
+    team_name: str, **defaults: Any
+) -> Callable[[Callable], Callable]:
+    """Create a decorator for external service team agents."""
+    try:
+        from .decorators.flexible import create_custom_decorator
+
+        external_defaults = {
+            "tags": {"team": team_name, "type": "external"},
+            "circuit_breaker": True,
+            "timeout": 30.0,
+            "retries": 3,
+            **defaults,
+        }
+        return create_custom_decorator(**external_defaults)
+    except ImportError:
+        return lambda func: func
+
+
+__all__ = [
+    # Core classes
+    "Agent",
+    "AgentCheckpoint",
+    "AgentResult",
+    "AgentStatus",
+    "Context",
+    "DeadLetter",
+    "DependencyConfig",
+    "DependencyLifecycle",
+    # Dependencies
+    "DependencyType",
+    "FlexibleStateDecorator",
+    # Scheduling (if available)
+    "GlobalScheduler",
+    "InputType",
+    "InvalidInputTypeError",
+    "InvalidScheduleError",
+    "PrioritizedState",
+    # State management
+    "Priority",
+    "ResourceTimeoutError",
+    "RetryPolicy",
+    "ScheduleBuilder",
+    "ScheduleParser",
+    "ScheduledAgent",
+    "ScheduledInput",
+    "SchedulingError",
+    # Decorators (if available)
+    "StateBuilder",
+    "StateMetadata",
+    "StateProfile",
+    "StateResult",
+    "StateStatus",
+    "StateType",
+    "batch_state",
+    "build_state",
+    "compare_states",
+    "concurrent_state",
+    "cpu_intensive",
+    "cpu_state",
+    "create_custom_decorator",
+    "create_environment_decorator",
+    "create_external_team_decorator",
+    "create_reliable_team_decorator",
+    "create_service_decorator",
+    # Team decorators
+    "create_team_decorator",
+    "critical_state",
+    "exclusive_state",
+    "external_service",
+    "external_service_state",
+    "fault_tolerant",
+    "fault_tolerant_state",
+    "get_profile",
+    "get_state_config",
+    "get_state_coordination",
+    "get_state_rate_limit",
+    "get_state_requirements",
+    "get_state_summary",
+    "gpu_accelerated",
+    "gpu_state",
+    "high_availability",
+    "high_priority_state",
+    "io_intensive",
+    # Inspection utilities
+    "is_puffinflow_state",
+    "isolated_state",
+    "list_profiles",
+    "list_state_metadata",
+    "memory_intensive",
+    "memory_state",
+    "minimal_state",
+    "network_intensive",
+    "parse_magic_prefix",
+    "parse_schedule_string",
+    "production_state",
+    "protected_state",
+    "quick_state",
+    # Flexible decorators
+    "state",
+]
+
+__doc__ = """
+Enhanced Agent Module for PuffinFlow
+
+This module provides the core Agent class with enhanced features for:
+- Direct variable access and manipulation
+- Rich context management with multiple content types
+- Team coordination and messaging
+- Event-driven communication
+- State management and checkpointing
+- Resource management and reliability patterns
+
+Key Classes:
+- Agent: Enhanced agent with direct variable access
+- Context: Rich context with outputs, metadata, metrics, caching
+- AgentResult: Comprehensive result container
+- AgentCheckpoint: State persistence and recovery
+
+Decorators (if available):
+- @state: Flexible state decorator with profiles
+- @cpu_intensive, @memory_intensive, etc.: Predefined profiles
+- @build_state(): Fluent builder pattern
+
+Team Features:
+- AgentTeam: Multi-agent coordination
+- Messaging between agents
+- Event bus for loose coupling
+- Shared variables and context
+
+Example:
+    from puffinflow import Agent, state
+
+    class DataProcessor(Agent):
+        @state(cpu=2.0, memory=512.0)
+        async def process_data(self, context):
+            # Direct variable access
+            batch_size = self.get_variable("batch_size", 1000)
+
+            # Process data
+            result = await self.process(batch_size)
+
+            # Set outputs and metrics
+            context.set_output("processed_count", len(result))
+            context.set_metric("processing_time", time.time())
+
+            return "completed"
+
+    # Create and run agent
+    processor = DataProcessor("processor")
+    processor.set_variable("batch_size", 2000)
+
+    result = await processor.run()
+    print(f"Processed: {result.get_output('processed_count')}")
+"""