alma-memory 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

alma/workflow/outcomes.py

@@ -0,0 +1,189 @@
+"""
+ALMA Workflow Outcomes.
+
+Provides the WorkflowOutcome dataclass for capturing learnings
+from completed workflow executions.
+
+Sprint 1 Task 1.5
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+
+class WorkflowResult(Enum):
+    """Result status of a workflow execution."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PARTIAL = "partial"  # Partially succeeded
+    CANCELLED = "cancelled"
+    TIMEOUT = "timeout"
+
+
+@dataclass
+class WorkflowOutcome:
+    """
+    Captures learnings from a completed workflow execution.
+
+    WorkflowOutcome records what was learned from running a workflow,
+    including the strategies used, what worked, what didn't, and any
+    extracted heuristics or anti-patterns.
+
+    Attributes:
+        id: Unique outcome identifier
+        tenant_id: Multi-tenant isolation identifier
+        workflow_id: The workflow definition that was executed
+        run_id: The specific run this outcome is from
+        agent: The agent that executed the workflow
+        project_id: Project scope identifier
+        result: Overall result status
+        summary: Human-readable summary of what happened
+        strategies_used: List of strategies/approaches attempted
+        successful_patterns: Patterns that worked well
+        failed_patterns: Patterns that didn't work
+        extracted_heuristics: IDs of heuristics created from this run
+        extracted_anti_patterns: IDs of anti-patterns created from this run
+        duration_seconds: How long the workflow took
+        node_count: Number of nodes executed
+        error_message: Error details if failed
+        embedding: Vector embedding for semantic search
+        metadata: Additional outcome metadata
+        created_at: When this outcome was recorded
+    """
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    tenant_id: Optional[str] = None
+    workflow_id: str = ""
+    run_id: str = ""
+    agent: str = ""
+    project_id: str = ""
+    result: WorkflowResult = WorkflowResult.SUCCESS
+    summary: str = ""
+    strategies_used: List[str] = field(default_factory=list)
+    successful_patterns: List[str] = field(default_factory=list)
+    failed_patterns: List[str] = field(default_factory=list)
+    extracted_heuristics: List[str] = field(default_factory=list)
+    extracted_anti_patterns: List[str] = field(default_factory=list)
+    duration_seconds: Optional[float] = None
+    node_count: Optional[int] = None
+    error_message: Optional[str] = None
+    embedding: Optional[List[float]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def validate(self, require_tenant: bool = False) -> None:
+        """
+        Validate the workflow outcome.
+
+        Args:
+            require_tenant: If True, tenant_id must be provided.
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        if require_tenant and not self.tenant_id:
+            raise ValueError("tenant_id is required for multi-tenant deployments")
+        if not self.workflow_id:
+            raise ValueError("workflow_id is required")
+        if not self.run_id:
+            raise ValueError("run_id is required")
+        if not self.agent:
+            raise ValueError("agent is required")
+        if not self.project_id:
+            raise ValueError("project_id is required")
+
+    @property
+    def is_success(self) -> bool:
+        """Check if the workflow succeeded."""
+        return self.result == WorkflowResult.SUCCESS
+
+    @property
+    def is_failure(self) -> bool:
+        """Check if the workflow failed."""
+        return self.result in (WorkflowResult.FAILURE, WorkflowResult.TIMEOUT)
+
+    def get_searchable_text(self) -> str:
+        """
+        Get text suitable for embedding generation.
+
+        Combines summary, strategies, and patterns into a single
+        searchable string.
+        """
+        parts = [self.summary]
+
+        if self.strategies_used:
+            parts.append("Strategies: " + ", ".join(self.strategies_used))
+
+        if self.successful_patterns:
+            parts.append("Successful: " + ", ".join(self.successful_patterns))
+
+        if self.failed_patterns:
+            parts.append("Failed: " + ", ".join(self.failed_patterns))
+
+        if self.error_message:
+            parts.append("Error: " + self.error_message)
+
+        return " | ".join(parts)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "tenant_id": self.tenant_id,
+            "workflow_id": self.workflow_id,
+            "run_id": self.run_id,
+            "agent": self.agent,
+            "project_id": self.project_id,
+            "result": self.result.value,
+            "summary": self.summary,
+            "strategies_used": self.strategies_used,
+            "successful_patterns": self.successful_patterns,
+            "failed_patterns": self.failed_patterns,
+            "extracted_heuristics": self.extracted_heuristics,
+            "extracted_anti_patterns": self.extracted_anti_patterns,
+            "duration_seconds": self.duration_seconds,
+            "node_count": self.node_count,
+            "error_message": self.error_message,
+            "embedding": self.embedding,
+            "metadata": self.metadata,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "WorkflowOutcome":
+        """Create from dictionary."""
+        created_at = data.get("created_at")
+        if isinstance(created_at, str):
+            created_at = datetime.fromisoformat(created_at)
+        elif created_at is None:
+            created_at = datetime.now(timezone.utc)
+
+        result = data.get("result", "success")
+        if isinstance(result, str):
+            result = WorkflowResult(result)
+
+        return cls(
+            id=data.get("id", str(uuid4())),
+            tenant_id=data.get("tenant_id"),
+            workflow_id=data.get("workflow_id", ""),
+            run_id=data.get("run_id", ""),
+            agent=data.get("agent", ""),
+            project_id=data.get("project_id", ""),
+            result=result,
+            summary=data.get("summary", ""),
+            strategies_used=data.get("strategies_used", []),
+            successful_patterns=data.get("successful_patterns", []),
+            failed_patterns=data.get("failed_patterns", []),
+            extracted_heuristics=data.get("extracted_heuristics", []),
+            extracted_anti_patterns=data.get("extracted_anti_patterns", []),
+            duration_seconds=data.get("duration_seconds"),
+            node_count=data.get("node_count"),
+            error_message=data.get("error_message"),
+            embedding=data.get("embedding"),
+            metadata=data.get("metadata", {}),
+            created_at=created_at,
+        )

alma/workflow/reducers.py

@@ -0,0 +1,393 @@
+"""
+ALMA State Reducers.
+
+Provides state reducers for merging parallel branch states in workflow
+orchestration. Each reducer defines how to combine values from multiple
+branches into a single value.
+
+Sprint 1 Tasks 1.8-1.10
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, TypeVar, Union
+
+if TYPE_CHECKING:
+    from alma.workflow.checkpoint import Checkpoint
+
+T = TypeVar("T")
+
+
+class StateReducer(ABC):
+    """
+    Abstract base class for state reducers.
+
+    A reducer defines how to combine multiple values (from parallel branches)
+    into a single value during state merge operations.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The name of this reducer."""
+        pass
+
+    @abstractmethod
+    def reduce(self, values: List[Any]) -> Any:
+        """
+        Reduce multiple values into a single value.
+
+        Args:
+            values: List of values from different branches.
+                   May contain None values.
+
+        Returns:
+            The reduced single value.
+        """
+        pass
+
+
+class AppendReducer(StateReducer):
+    """
+    Concatenates lists from all branches.
+
+    Use for: messages, logs, notes, events
+    """
+
+    @property
+    def name(self) -> str:
+        return "append"
+
+    def reduce(self, values: List[Any]) -> List[Any]:
+        """Concatenate all lists, preserving order."""
+        result: List[Any] = []
+        for value in values:
+            if value is None:
+                continue
+            if isinstance(value, list):
+                result.extend(value)
+            else:
+                result.append(value)
+        return result
+
+
+class MergeDictReducer(StateReducer):
+    """
+    Merges dictionaries, with later values overwriting earlier ones.
+
+    Use for: context, metadata, configuration
+    """
+
+    @property
+    def name(self) -> str:
+        return "merge_dict"
+
+    def reduce(self, values: List[Any]) -> Dict[str, Any]:
+        """Merge all dictionaries, later values win."""
+        result: Dict[str, Any] = {}
+        for value in values:
+            if value is None:
+                continue
+            if isinstance(value, dict):
+                result.update(value)
+        return result
+
+
+class LastValueReducer(StateReducer):
+    """
+    Takes the last non-None value.
+
+    Use for: single values where the most recent is preferred
+    """
+
+    @property
+    def name(self) -> str:
+        return "last_value"
+
+    def reduce(self, values: List[Any]) -> Any:
+        """Return the last non-None value."""
+        for value in reversed(values):
+            if value is not None:
+                return value
+        return None
+
+
+class FirstValueReducer(StateReducer):
+    """
+    Takes the first non-None value.
+
+    Use for: priority values, initial state
+    """
+
+    @property
+    def name(self) -> str:
+        return "first_value"
+
+    def reduce(self, values: List[Any]) -> Any:
+        """Return the first non-None value."""
+        for value in values:
+            if value is not None:
+                return value
+        return None
+
+
+class SumReducer(StateReducer):
+    """
+    Sums numeric values.
+
+    Use for: counters, scores, totals
+    """
+
+    @property
+    def name(self) -> str:
+        return "sum"
+
+    def reduce(self, values: List[Any]) -> Union[int, float]:
+        """Sum all numeric values."""
+        total: Union[int, float] = 0
+        for value in values:
+            if value is not None and isinstance(value, (int, float)):
+                total += value
+        return total
+
+
+class MaxReducer(StateReducer):
+    """
+    Takes the maximum value.
+
+    Use for: high scores, limits, thresholds
+    """
+
+    @property
+    def name(self) -> str:
+        return "max"
+
+    def reduce(self, values: List[Any]) -> Optional[Union[int, float]]:
+        """Return the maximum value."""
+        numeric_values = [
+            v for v in values if v is not None and isinstance(v, (int, float))
+        ]
+        return max(numeric_values) if numeric_values else None
+
+
+class MinReducer(StateReducer):
+    """
+    Takes the minimum value.
+
+    Use for: low scores, minimums
+    """
+
+    @property
+    def name(self) -> str:
+        return "min"
+
+    def reduce(self, values: List[Any]) -> Optional[Union[int, float]]:
+        """Return the minimum value."""
+        numeric_values = [
+            v for v in values if v is not None and isinstance(v, (int, float))
+        ]
+        return min(numeric_values) if numeric_values else None
+
+
+class UnionReducer(StateReducer):
+    """
+    Creates a set union of all values.
+
+    Use for: tags, categories, unique items
+    """
+
+    @property
+    def name(self) -> str:
+        return "union"
+
+    def reduce(self, values: List[Any]) -> List[Any]:
+        """Return union of all values as a list."""
+        seen: set = set()
+        result: List[Any] = []
+        for value in values:
+            if value is None:
+                continue
+            items = value if isinstance(value, (list, set)) else [value]
+            for item in items:
+                # Handle unhashable types
+                try:
+                    if item not in seen:
+                        seen.add(item)
+                        result.append(item)
+                except TypeError:
+                    # Unhashable type - just append
+                    result.append(item)
+        return result
+
+
+# Built-in reducer instances
+BUILTIN_REDUCERS: Dict[str, StateReducer] = {
+    "append": AppendReducer(),
+    "merge_dict": MergeDictReducer(),
+    "last_value": LastValueReducer(),
+    "first_value": FirstValueReducer(),
+    "sum": SumReducer(),
+    "max": MaxReducer(),
+    "min": MinReducer(),
+    "union": UnionReducer(),
+}
+
+
+def get_reducer(name: str) -> StateReducer:
+    """
+    Get a built-in reducer by name.
+
+    Args:
+        name: The reducer name.
+
+    Returns:
+        The reducer instance.
+
+    Raises:
+        ValueError: If reducer name is unknown.
+    """
+    if name not in BUILTIN_REDUCERS:
+        raise ValueError(
+            f"Unknown reducer: '{name}'. "
+            f"Available reducers: {list(BUILTIN_REDUCERS.keys())}"
+        )
+    return BUILTIN_REDUCERS[name]
+
+
+@dataclass
+class ReducerConfig:
+    """
+    Configuration for state merging.
+
+    Specifies which reducer to use for each field in the state.
+
+    Attributes:
+        field_reducers: Mapping of field names to reducer names.
+        default_reducer: Default reducer for fields not in field_reducers.
+        custom_reducers: Custom reducer instances by name.
+    """
+
+    field_reducers: Dict[str, str] = field(default_factory=dict)
+    default_reducer: str = "last_value"
+    custom_reducers: Dict[str, StateReducer] = field(default_factory=dict)
+
+    def get_reducer_for_field(self, field_name: str) -> StateReducer:
+        """
+        Get the reducer for a specific field.
+
+        Args:
+            field_name: The field name.
+
+        Returns:
+            The reducer to use for this field.
+        """
+        reducer_name = self.field_reducers.get(field_name, self.default_reducer)
+
+        # Check custom reducers first
+        if reducer_name in self.custom_reducers:
+            return self.custom_reducers[reducer_name]
+
+        # Fall back to built-in
+        return get_reducer(reducer_name)
+
+
+class StateMerger:
+    """
+    Merges states from multiple parallel branches.
+
+    Uses ReducerConfig to determine how each field should be merged.
+    """
+
+    def __init__(self, config: Optional[ReducerConfig] = None):
+        """
+        Initialize the state merger.
+
+        Args:
+            config: Reducer configuration. Uses defaults if not provided.
+        """
+        self.config = config or ReducerConfig()
+
+    def merge(self, states: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Merge multiple states into a single state.
+
+        Args:
+            states: List of state dictionaries from parallel branches.
+
+        Returns:
+            The merged state dictionary.
+        """
+        if not states:
+            return {}
+
+        if len(states) == 1:
+            return states[0].copy()
+
+        # Collect all field names
+        all_fields: set = set()
+        for state in states:
+            all_fields.update(state.keys())
+
+        # Merge each field
+        result: Dict[str, Any] = {}
+        for field_name in all_fields:
+            # Collect values for this field from all states
+            values = [state.get(field_name) for state in states]
+
+            # Get the appropriate reducer
+            reducer = self.config.get_reducer_for_field(field_name)
+
+            # Apply the reducer
+            result[field_name] = reducer.reduce(values)
+
+        return result
+
+    def merge_checkpoints(
+        self,
+        checkpoints: List["Checkpoint"],  # type: ignore
+    ) -> Dict[str, Any]:
+        """
+        Merge states from multiple checkpoints.
+
+        Convenience method for merging checkpoint states.
+
+        Args:
+            checkpoints: List of Checkpoint objects.
+
+        Returns:
+            The merged state dictionary.
+        """
+        states = [cp.state for cp in checkpoints]
+        return self.merge(states)
+
+
+# Convenience function for simple merges
+def merge_states(
+    states: List[Dict[str, Any]],
+    config: Optional[ReducerConfig] = None,
+) -> Dict[str, Any]:
+    """
+    Merge multiple states into a single state.
+
+    Convenience function that creates a StateMerger and merges.
+
+    Args:
+        states: List of state dictionaries.
+        config: Optional reducer configuration.
+
+    Returns:
+        The merged state dictionary.
+
+    Example:
+        >>> config = ReducerConfig(
+        ...     field_reducers={
+        ...         "messages": "append",
+        ...         "context": "merge_dict",
+        ...         "total_score": "sum",
+        ...     },
+        ...     default_reducer="last_value",
+        ... )
+        >>> result = merge_states([state1, state2, state3], config)
+    """
+    merger = StateMerger(config)
+    return merger.merge(states)