puffinflow 2.dev0__py3-none-any.whl

puffinflow/core/agent/decorators/inspection.py

@@ -0,0 +1,144 @@
+"""Utilities for inspecting decorated states."""
+
+from typing import Any, Callable, Optional
+
+from ...coordination.rate_limiter import RateLimitStrategy
+from ...resources.requirements import ResourceRequirements
+from ..state import Priority
+
+
+def is_puffinflow_state(func: Callable) -> bool:
+    """Check if a function is a PuffinFlow state."""
+    return getattr(func, "_puffinflow_state", False)
+
+
+def get_state_config(func: Callable) -> Optional[dict[str, Any]]:
+    """Get the configuration of a PuffinFlow state."""
+    return getattr(func, "_state_config", None)
+
+
+def get_state_requirements(func: Callable) -> Optional[ResourceRequirements]:
+    """Get the resource requirements of a PuffinFlow state."""
+    return getattr(func, "_resource_requirements", None)
+
+
+def get_state_rate_limit(func: Callable) -> Optional[dict[str, Any]]:
+    """Get the rate limiting configuration of a PuffinFlow state."""
+    if not hasattr(func, "_rate_limit"):
+        return None
+
+    strategy = getattr(func, "_rate_strategy", RateLimitStrategy.TOKEN_BUCKET)
+
+    return {
+        "rate": func._rate_limit,
+        "burst": getattr(func, "_burst_limit", None),
+        "strategy": strategy,
+    }
+
+
+def get_state_coordination(func: Callable) -> Optional[dict[str, Any]]:
+    """Get the coordination configuration of a PuffinFlow state."""
+    primitive = getattr(func, "_coordination_primitive", None)
+    if primitive is None:
+        return None
+
+    return {"type": primitive, "config": getattr(func, "_coordination_config", {})}
+
+
+def list_state_metadata(func: Callable) -> dict[str, Any]:
+    """Get all metadata for a PuffinFlow state."""
+    if not is_puffinflow_state(func):
+        return {}
+
+    # Get description, falling back to docstring if not set
+    description = getattr(func, "_state_description", "")
+    if not description and func.__doc__:
+        description = func.__doc__.strip()
+
+    # If still no description, use fallback
+    if not description:
+        description = f"State: {func.__name__}"
+
+    return {
+        "name": getattr(func, "_state_name", func.__name__),
+        "description": description,
+        "tags": getattr(func, "_state_tags", {}),
+        "priority": getattr(func, "_priority", Priority.NORMAL),
+        "requirements": get_state_requirements(func),
+        "rate_limit": get_state_rate_limit(func),
+        "coordination": get_state_coordination(func),
+        "dependencies": getattr(func, "_dependency_configs", {}),
+        "preemptible": getattr(func, "_preemptible", False),
+        "checkpoint_interval": getattr(func, "_checkpoint_interval", None),
+        "cleanup_on_failure": getattr(func, "_cleanup_on_failure", True),
+    }
+
+
+def compare_states(func1: Callable, func2: Callable) -> dict[str, Any]:
+    """Compare two state configurations."""
+    config1 = get_state_config(func1) or {}
+    config2 = get_state_config(func2) or {}
+
+    differences = {}
+    all_keys = set(config1.keys()) | set(config2.keys())
+
+    for key in all_keys:
+        val1 = config1.get(key)
+        val2 = config2.get(key)
+        if val1 != val2:
+            differences[key] = {"func1": val1, "func2": val2}
+
+    return differences
+
+
+def get_state_summary(func: Callable) -> str:
+    """Get a human-readable summary of state configuration."""
+    if not is_puffinflow_state(func):
+        return f"{func.__name__}: Not a PuffinFlow state"
+
+    config = get_state_config(func)
+    if config is None or not isinstance(config, dict):
+        return f"{func.__name__}: No configuration found"
+
+    summary_parts = [f"{func.__name__}:"]
+
+    # Resources
+    resources = []
+    cpu = config.get("cpu", 0)
+    if cpu is not None and cpu > 0:
+        resources.append(f"CPU={cpu}")
+    memory = config.get("memory", 0)
+    if memory is not None and memory > 0:
+        resources.append(f"Memory={memory}MB")
+    gpu = config.get("gpu", 0)
+    if gpu is not None and gpu > 0:
+        resources.append(f"GPU={gpu}")
+
+    if resources:
+        summary_parts.append(f"  Resources: {', '.join(resources)}")
+
+    # Priority
+    priority = config.get("priority")
+    if priority and priority != Priority.NORMAL:
+        summary_parts.append(f"  Priority: {priority.name}")
+
+    # Coordination
+    coord_info = []
+    if config.get("mutex"):
+        coord_info.append("Mutex")
+    if config.get("semaphore"):
+        coord_info.append(f"Semaphore({config['semaphore']})")
+    if config.get("barrier"):
+        coord_info.append(f"Barrier({config['barrier']})")
+    if config.get("rate_limit"):
+        coord_info.append(f"RateLimit({config['rate_limit']}/s)")
+
+    if coord_info:
+        summary_parts.append(f"  Coordination: {', '.join(coord_info)}")
+
+    # Dependencies
+    deps = config.get("depends_on")
+    if deps:
+        summary_parts.append(f"  Dependencies: {', '.join(deps)}")
+
+    return "\n".join(summary_parts)

puffinflow/core/agent/dependencies.py

@@ -0,0 +1,57 @@
+"""Dependency management types."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+if TYPE_CHECKING:
+    from .base import Agent
+
+
+class DependencyType(Enum):
+    """Types of dependencies between states."""
+
+    REQUIRED = "required"  # Must complete before state can run
+    OPTIONAL = "optional"  # Will wait if running, otherwise skips
+    PARALLEL = "parallel"  # Can run in parallel with dependency
+    SEQUENTIAL = "sequential"  # Must run after dependency completes
+    CONDITIONAL = "conditional"  # Depends on condition function
+    TIMEOUT = "timeout"  # Wait for max time then continue
+    XOR = "xor"  # Only one dependency needs to be satisfied
+    AND = "and"  # All dependencies must be satisfied
+    OR = "or"  # At least one dependency must be satisfied
+
+    def __str__(self) -> str:
+        return f"DependencyType.{self.name}"
+
+    def __repr__(self) -> str:
+        return f"DependencyType.{self.name}"
+
+
+class DependencyLifecycle(Enum):
+    """Lifecycle management for dependencies."""
+
+    ONCE = "once"  # Dependency only needs to be satisfied once
+    ALWAYS = "always"  # Dependency must be satisfied every time
+    SESSION = "session"  # Dependency valid for current run() execution
+    TEMPORARY = "temporary"  # Dependency expires after specified time
+    PERIODIC = "periodic"  # Must be re-satisfied after specified interval
+
+    def __str__(self) -> str:
+        return f"DependencyLifecycle.{self.name}"
+
+    def __repr__(self) -> str:
+        return f"DependencyLifecycle.{self.name}"
+
+
+@dataclass
+class DependencyConfig:
+    """Configuration for state dependencies."""
+
+    type: DependencyType
+    lifecycle: DependencyLifecycle = DependencyLifecycle.ALWAYS
+    condition: Optional[Callable[["Agent"], bool]] = None
+    expiry: Optional[float] = None
+    interval: Optional[float] = None
+    timeout: Optional[float] = None
+    retry_policy: Optional[dict[str, Any]] = None

puffinflow/core/agent/scheduling/__init__.py

@@ -0,0 +1,21 @@
+"""Agent scheduling module for PuffinFlow."""
+
+from .builder import ScheduleBuilder
+from .exceptions import InvalidInputTypeError, InvalidScheduleError, SchedulingError
+from .inputs import InputType, ScheduledInput, parse_magic_prefix
+from .parser import ScheduleParser, parse_schedule_string
+from .scheduler import GlobalScheduler, ScheduledAgent
+
+__all__ = [
+    "GlobalScheduler",
+    "InputType",
+    "InvalidInputTypeError",
+    "InvalidScheduleError",
+    "ScheduleBuilder",
+    "ScheduleParser",
+    "ScheduledAgent",
+    "ScheduledInput",
+    "SchedulingError",
+    "parse_magic_prefix",
+    "parse_schedule_string",
+]

puffinflow/core/agent/scheduling/builder.py

@@ -0,0 +1,160 @@
+"""Fluent API builder for agent scheduling."""
+
+from typing import TYPE_CHECKING, Any
+
+from .inputs import ScheduledInput, parse_inputs
+
+if TYPE_CHECKING:
+    from ..base import Agent
+    from .scheduler import ScheduledAgent
+
+
+class ScheduleBuilder:
+    """Fluent API builder for scheduling agents."""
+
+    def __init__(self, agent: "Agent", schedule_string: str):
+        self._agent = agent
+        self._schedule_string = schedule_string
+        self._inputs: dict[str, ScheduledInput] = {}
+
+    def with_inputs(self, **inputs: Any) -> "ScheduleBuilder":
+        """Add regular variable inputs.
+
+        Args:
+            **inputs: Input key-value pairs
+
+        Returns:
+            Self for chaining
+        """
+        parsed = parse_inputs(**inputs)
+        self._inputs.update(parsed)
+        return self
+
+    def with_secrets(self, **secrets: Any) -> "ScheduleBuilder":
+        """Add secret inputs.
+
+        Args:
+            **secrets: Secret key-value pairs
+
+        Returns:
+            Self for chaining
+        """
+        for key, value in secrets.items():
+            prefixed_value = f"secret:{value}"
+            parsed = parse_inputs(**{key: prefixed_value})
+            self._inputs.update(parsed)
+        return self
+
+    def with_constants(self, **constants: Any) -> "ScheduleBuilder":
+        """Add constant inputs.
+
+        Args:
+            **constants: Constant key-value pairs
+
+        Returns:
+            Self for chaining
+        """
+        for key, value in constants.items():
+            prefixed_value = f"const:{value}"
+            parsed = parse_inputs(**{key: prefixed_value})
+            self._inputs.update(parsed)
+        return self
+
+    def with_cache(self, ttl: int, **cached_inputs: Any) -> "ScheduleBuilder":
+        """Add cached inputs with TTL.
+
+        Args:
+            ttl: Time to live in seconds
+            **cached_inputs: Cached input key-value pairs
+
+        Returns:
+            Self for chaining
+        """
+        for key, value in cached_inputs.items():
+            # Convert value to string for cache prefix
+            if isinstance(value, (dict, list)):
+                import json
+
+                value_str = json.dumps(value)
+            else:
+                value_str = str(value)
+            prefixed_value = f"cache:{ttl}:{value_str}"
+            parsed = parse_inputs(**{key: prefixed_value})
+            self._inputs.update(parsed)
+        return self
+
+    def with_typed(self, **typed_inputs: Any) -> "ScheduleBuilder":
+        """Add typed inputs.
+
+        Args:
+            **typed_inputs: Typed input key-value pairs
+
+        Returns:
+            Self for chaining
+        """
+        for key, value in typed_inputs.items():
+            # Convert value to string for typed prefix
+            if isinstance(value, (dict, list)):
+                import json
+
+                value_str = json.dumps(value)
+            else:
+                value_str = str(value)
+            prefixed_value = f"typed:{value_str}"
+            parsed = parse_inputs(**{key: prefixed_value})
+            self._inputs.update(parsed)
+        return self
+
+    def with_outputs(self, **outputs: Any) -> "ScheduleBuilder":
+        """Add pre-set outputs.
+
+        Args:
+            **outputs: Output key-value pairs
+
+        Returns:
+            Self for chaining
+        """
+        for key, value in outputs.items():
+            prefixed_value = f"output:{value}"
+            parsed = parse_inputs(**{key: prefixed_value})
+            self._inputs.update(parsed)
+        return self
+
+    def run(self) -> "ScheduledAgent":
+        """Execute the scheduling with configured inputs.
+
+        Returns:
+            ScheduledAgent instance
+        """
+        # Convert ScheduledInput objects back to input format for schedule method
+        input_kwargs = {}
+        for key, scheduled_input in self._inputs.items():
+            if scheduled_input.input_type.value == "secret":
+                input_kwargs[key] = f"secret:{scheduled_input.value}"
+            elif scheduled_input.input_type.value == "const":
+                input_kwargs[key] = f"const:{scheduled_input.value}"
+            elif scheduled_input.input_type.value == "cache":
+                input_kwargs[
+                    key
+                ] = f"cache:{scheduled_input.ttl}:{scheduled_input.value}"
+            elif scheduled_input.input_type.value == "typed":
+                input_kwargs[key] = f"typed:{scheduled_input.value}"
+            elif scheduled_input.input_type.value == "output":
+                input_kwargs[key] = f"output:{scheduled_input.value}"
+            else:  # variable
+                input_kwargs[key] = scheduled_input.value
+
+        return self._agent.schedule(self._schedule_string, **input_kwargs)
+
+
+def create_schedule_builder(agent: "Agent", schedule_string: str) -> ScheduleBuilder:
+    """Create a schedule builder for fluent API.
+
+    Args:
+        agent: Agent to schedule
+        schedule_string: Schedule string
+
+    Returns:
+        ScheduleBuilder instance
+    """
+    return ScheduleBuilder(agent, schedule_string)

puffinflow/core/agent/scheduling/exceptions.py

@@ -0,0 +1,35 @@
+"""Scheduling exceptions."""
+
+from typing import Optional
+
+
+class SchedulingError(Exception):
+    """Base exception for scheduling errors."""
+
+    pass
+
+
+class InvalidScheduleError(SchedulingError):
+    """Raised when a schedule string is invalid."""
+
+    def __init__(self, schedule: str, message: Optional[str] = None):
+        self.schedule = schedule
+        if message is None:
+            message = (
+                f"Invalid schedule '{schedule}'. "
+                "Try: 'daily', 'hourly', 'every 5 minutes', or cron expression."
+            )
+        super().__init__(message)
+
+
+class InvalidInputTypeError(SchedulingError):
+    """Raised when an input type prefix is invalid."""
+
+    def __init__(self, prefix: str, message: Optional[str] = None):
+        self.prefix = prefix
+        if message is None:
+            message = (
+                f"Unknown input type '{prefix}'. "
+                "Supported: secret:, const:, cache:TTL:, typed:, output:"
+            )
+        super().__init__(message)

puffinflow/core/agent/scheduling/inputs.py

@@ -0,0 +1,137 @@
+"""Input types and magic prefix parsing for scheduled agents."""
+
+import json
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Optional
+
+from .exceptions import InvalidInputTypeError
+
+
+class InputType(Enum):
+    """Types of inputs for scheduled agents."""
+
+    VARIABLE = "variable"  # Regular variables (no prefix)
+    SECRET = "secret"  # secret:value
+    CONSTANT = "const"  # const:value
+    CACHED = "cache"  # cache:TTL:value
+    TYPED = "typed"  # typed:value
+    OUTPUT = "output"  # output:value
+
+
+@dataclass
+class ScheduledInput:
+    """Configuration for a scheduled input."""
+
+    key: str
+    value: Any
+    input_type: InputType
+    ttl: Optional[int] = None  # For cached inputs
+
+    def apply_to_context(self, context: Any) -> None:
+        """Apply this input to a context."""
+        if self.input_type == InputType.SECRET:
+            context.set_secret(self.key, self.value)
+        elif self.input_type == InputType.CONSTANT:
+            context.set_constant(self.key, self.value)
+        elif self.input_type == InputType.CACHED:
+            context.set_cached(self.key, self.value, self.ttl)
+        elif self.input_type == InputType.TYPED:
+            context.set_typed_variable(self.key, self.value)
+        elif self.input_type == InputType.OUTPUT:
+            context.set_output(self.key, self.value)
+        else:  # VARIABLE
+            context.set_variable(self.key, self.value)
+
+
+def parse_magic_prefix(key: str, value: Any) -> ScheduledInput:
+    """Parse magic prefix from input value and return ScheduledInput.
+
+    Args:
+        key: The input key name
+        value: The input value, potentially with magic prefix
+
+    Returns:
+        ScheduledInput with parsed type and value
+
+    Raises:
+        InvalidInputTypeError: If prefix is invalid
+    """
+    if not isinstance(value, str):
+        # Non-string values are treated as regular variables
+        return ScheduledInput(key, value, InputType.VARIABLE)
+
+    # Check for magic prefixes
+    if ":" not in value:
+        # No prefix, regular variable
+        return ScheduledInput(key, value, InputType.VARIABLE)
+
+    parts = value.split(":", 1)
+    prefix = parts[0].lower()
+
+    if prefix == "secret":
+        if len(parts) != 2 or not parts[1]:
+            raise InvalidInputTypeError(prefix, "Secret format: secret:value")
+        return ScheduledInput(key, parts[1], InputType.SECRET)
+
+    elif prefix == "const":
+        if len(parts) != 2 or not parts[1]:
+            raise InvalidInputTypeError(prefix, "Constant format: const:value")
+        return ScheduledInput(key, parts[1], InputType.CONSTANT)
+
+    elif prefix == "cache":
+        # Format: cache:TTL:value
+        cache_parts = value.split(":", 2)
+        if len(cache_parts) != 3:
+            raise InvalidInputTypeError(prefix, "Cache format: cache:TTL:value")
+
+        try:
+            ttl = int(cache_parts[1])
+        except ValueError as e:
+            raise InvalidInputTypeError(prefix, "Cache TTL must be an integer") from e
+
+        # Try to parse value as JSON, fall back to string
+        raw_value = cache_parts[2]
+        try:
+            parsed_value = json.loads(raw_value)
+        except json.JSONDecodeError:
+            parsed_value = raw_value
+
+        return ScheduledInput(key, parsed_value, InputType.CACHED, ttl=ttl)
+
+    elif prefix == "typed":
+        if len(parts) != 2 or not parts[1]:
+            raise InvalidInputTypeError(prefix, "Typed format: typed:value")
+
+        # Try to parse value as JSON for complex types
+        raw_value = parts[1]
+        try:
+            parsed_value = json.loads(raw_value)
+        except json.JSONDecodeError:
+            parsed_value = raw_value
+
+        return ScheduledInput(key, parsed_value, InputType.TYPED)
+
+    elif prefix == "output":
+        if len(parts) != 2 or not parts[1]:
+            raise InvalidInputTypeError(prefix, "Output format: output:value")
+        return ScheduledInput(key, parts[1], InputType.OUTPUT)
+
+    else:
+        # Unknown prefix, treat as regular variable
+        return ScheduledInput(key, value, InputType.VARIABLE)
+
+
+def parse_inputs(**inputs: Any) -> dict[str, ScheduledInput]:
+    """Parse all inputs with magic prefixes.
+
+    Args:
+        **inputs: Input key-value pairs
+
+    Returns:
+        Dictionary mapping keys to ScheduledInput objects
+    """
+    parsed_inputs = {}
+    for key, value in inputs.items():
+        parsed_inputs[key] = parse_magic_prefix(key, value)
+    return parsed_inputs