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

alma/workflow/artifacts.py

@@ -0,0 +1,170 @@
+"""
+ALMA Workflow Artifacts.
+
+Provides artifact reference dataclass for linking external artifacts
+(files, screenshots, logs, etc.) to memories.
+
+Sprint 1 Task 1.4
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+
+class ArtifactType(Enum):
+    """Types of artifacts that can be linked to memories."""
+
+    # Files and documents
+    FILE = "file"
+    DOCUMENT = "document"
+    IMAGE = "image"
+    VIDEO = "video"
+
+    # Development artifacts
+    SCREENSHOT = "screenshot"
+    LOG = "log"
+    TRACE = "trace"
+    DIFF = "diff"
+
+    # Test artifacts
+    TEST_RESULT = "test_result"
+    COVERAGE_REPORT = "coverage_report"
+
+    # Analysis artifacts
+    REPORT = "report"
+    METRICS = "metrics"
+
+    # Generic
+    OTHER = "other"
+
+
+@dataclass
+class ArtifactRef:
+    """
+    Reference to an external artifact linked to a memory.
+
+    Artifacts are stored externally (e.g., Cloudflare R2, S3, local filesystem)
+    and referenced by URL/path. This allows memories to reference large files
+    without bloating the memory database.
+
+    Attributes:
+        id: Unique artifact reference identifier
+        memory_id: The memory this artifact is linked to
+        artifact_type: Type of artifact (screenshot, log, etc.)
+        storage_url: URL or path to the artifact in storage
+        filename: Original filename
+        mime_type: MIME type of the artifact
+        size_bytes: Size of the artifact in bytes
+        checksum: SHA256 checksum for integrity verification
+        metadata: Additional artifact metadata
+        created_at: When this reference was created
+    """
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    memory_id: str = ""
+    artifact_type: ArtifactType = ArtifactType.OTHER
+    storage_url: str = ""
+    filename: Optional[str] = None
+    mime_type: Optional[str] = None
+    size_bytes: Optional[int] = None
+    checksum: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def validate(self) -> None:
+        """
+        Validate the artifact reference.
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        if not self.memory_id:
+            raise ValueError("memory_id is required")
+        if not self.storage_url:
+            raise ValueError("storage_url is required")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "memory_id": self.memory_id,
+            "artifact_type": self.artifact_type.value,
+            "storage_url": self.storage_url,
+            "filename": self.filename,
+            "mime_type": self.mime_type,
+            "size_bytes": self.size_bytes,
+            "checksum": self.checksum,
+            "metadata": self.metadata,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ArtifactRef":
+        """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)
+
+        artifact_type = data.get("artifact_type", "other")
+        if isinstance(artifact_type, str):
+            artifact_type = ArtifactType(artifact_type)
+
+        return cls(
+            id=data.get("id", str(uuid4())),
+            memory_id=data.get("memory_id", ""),
+            artifact_type=artifact_type,
+            storage_url=data.get("storage_url", ""),
+            filename=data.get("filename"),
+            mime_type=data.get("mime_type"),
+            size_bytes=data.get("size_bytes"),
+            checksum=data.get("checksum"),
+            metadata=data.get("metadata", {}),
+            created_at=created_at,
+        )
+
+
+def link_artifact(
+    memory_id: str,
+    artifact_type: ArtifactType,
+    storage_url: str,
+    filename: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    size_bytes: Optional[int] = None,
+    checksum: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> ArtifactRef:
+    """
+    Create an artifact reference linked to a memory.
+
+    This is a convenience function for creating ArtifactRef instances.
+
+    Args:
+        memory_id: The memory to link the artifact to.
+        artifact_type: Type of artifact.
+        storage_url: URL or path to the artifact.
+        filename: Original filename.
+        mime_type: MIME type.
+        size_bytes: Size in bytes.
+        checksum: SHA256 checksum.
+        metadata: Additional metadata.
+
+    Returns:
+        A validated ArtifactRef instance.
+    """
+    ref = ArtifactRef(
+        memory_id=memory_id,
+        artifact_type=artifact_type,
+        storage_url=storage_url,
+        filename=filename,
+        mime_type=mime_type,
+        size_bytes=size_bytes,
+        checksum=checksum,
+        metadata=metadata or {},
+    )
+    ref.validate()
+    return ref

alma/workflow/checkpoint.py

@@ -0,0 +1,311 @@
+"""
+ALMA Workflow Checkpoints.
+
+Provides checkpoint dataclass and CheckpointManager for crash recovery
+and state persistence in workflow orchestration.
+
+Sprint 1 Task 1.3, Sprint 3 Tasks 3.1-3.4
+"""
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+# Default maximum state size (1MB)
+DEFAULT_MAX_STATE_SIZE = 1024 * 1024
+
+
+@dataclass
+class Checkpoint:
+    """
+    Represents a workflow execution checkpoint.
+
+    Checkpoints enable crash recovery by persisting state at key points
+    during workflow execution. They support parallel execution through
+    branch tracking and parent references.
+
+    Attributes:
+        id: Unique checkpoint identifier
+        run_id: The workflow run this checkpoint belongs to
+        node_id: The node that created this checkpoint
+        state: The serializable state data
+        sequence_number: Ordering within the run (monotonically increasing)
+        branch_id: Identifier for parallel branch (None for main branch)
+        parent_checkpoint_id: Previous checkpoint in the chain
+        state_hash: SHA256 hash for change detection
+        metadata: Additional checkpoint metadata
+        created_at: When this checkpoint was created
+    """
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    run_id: str = ""
+    node_id: str = ""
+    state: Dict[str, Any] = field(default_factory=dict)
+    sequence_number: int = 0
+    branch_id: Optional[str] = None
+    parent_checkpoint_id: Optional[str] = None
+    state_hash: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def __post_init__(self):
+        """Compute state hash if not provided."""
+        if not self.state_hash and self.state:
+            self.state_hash = self._compute_hash(self.state)
+
+    @staticmethod
+    def _compute_hash(state: Dict[str, Any]) -> str:
+        """Compute SHA256 hash of state for change detection."""
+        # Sort keys for consistent hashing
+        state_json = json.dumps(state, sort_keys=True, default=str)
+        return hashlib.sha256(state_json.encode()).hexdigest()
+
+    def has_changed(self, other_state: Dict[str, Any]) -> bool:
+        """Check if state has changed compared to another state."""
+        other_hash = self._compute_hash(other_state)
+        return self.state_hash != other_hash
+
+    def get_state_size(self) -> int:
+        """Get the size of the state in bytes."""
+        return len(json.dumps(self.state, default=str).encode())
+
+    def validate(self, max_state_size: int = DEFAULT_MAX_STATE_SIZE) -> None:
+        """
+        Validate the checkpoint.
+
+        Args:
+            max_state_size: Maximum allowed state size in bytes.
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        if not self.run_id:
+            raise ValueError("run_id is required")
+        if not self.node_id:
+            raise ValueError("node_id is required")
+        if self.sequence_number < 0:
+            raise ValueError("sequence_number must be non-negative")
+
+        state_size = self.get_state_size()
+        if state_size > max_state_size:
+            raise ValueError(
+                f"State size ({state_size} bytes) exceeds maximum "
+                f"({max_state_size} bytes). Consider storing large data "
+                "in artifact storage and linking via ArtifactRef."
+            )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "run_id": self.run_id,
+            "node_id": self.node_id,
+            "state": self.state,
+            "sequence_number": self.sequence_number,
+            "branch_id": self.branch_id,
+            "parent_checkpoint_id": self.parent_checkpoint_id,
+            "state_hash": self.state_hash,
+            "metadata": self.metadata,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Checkpoint":
+        """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)
+
+        return cls(
+            id=data.get("id", str(uuid4())),
+            run_id=data.get("run_id", ""),
+            node_id=data.get("node_id", ""),
+            state=data.get("state", {}),
+            sequence_number=data.get("sequence_number", 0),
+            branch_id=data.get("branch_id"),
+            parent_checkpoint_id=data.get("parent_checkpoint_id"),
+            state_hash=data.get("state_hash", ""),
+            metadata=data.get("metadata", {}),
+            created_at=created_at,
+        )
+
+
+class CheckpointManager:
+    """
+    Manages checkpoint operations for workflow execution.
+
+    Provides methods for creating, retrieving, and cleaning up checkpoints.
+    Supports concurrent access patterns and branch management.
+
+    Sprint 3 Tasks 3.1-3.4
+    """
+
+    def __init__(
+        self,
+        storage: Any,  # StorageBackend
+        max_state_size: int = DEFAULT_MAX_STATE_SIZE,
+    ):
+        """
+        Initialize the checkpoint manager.
+
+        Args:
+            storage: Storage backend for persisting checkpoints.
+            max_state_size: Maximum allowed state size in bytes.
+        """
+        self._storage = storage
+        self._max_state_size = max_state_size
+        self._sequence_cache: Dict[str, int] = {}  # run_id -> last sequence
+
+    def create_checkpoint(
+        self,
+        run_id: str,
+        node_id: str,
+        state: Dict[str, Any],
+        branch_id: Optional[str] = None,
+        parent_checkpoint_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        skip_if_unchanged: bool = True,
+    ) -> Optional[Checkpoint]:
+        """
+        Create a new checkpoint.
+
+        Args:
+            run_id: The workflow run identifier.
+            node_id: The node creating this checkpoint.
+            state: The state to persist.
+            branch_id: Optional branch identifier for parallel execution.
+            parent_checkpoint_id: Previous checkpoint in the chain.
+            metadata: Additional checkpoint metadata.
+            skip_if_unchanged: If True, skip creating checkpoint if state
+                              hasn't changed from the last checkpoint.
+
+        Returns:
+            The created Checkpoint, or None if skipped due to no changes.
+
+        Raises:
+            ValueError: If state exceeds max_state_size.
+        """
+        # Get next sequence number
+        sequence_number = self._get_next_sequence(run_id)
+
+        # Create checkpoint
+        checkpoint = Checkpoint(
+            run_id=run_id,
+            node_id=node_id,
+            state=state,
+            sequence_number=sequence_number,
+            branch_id=branch_id,
+            parent_checkpoint_id=parent_checkpoint_id,
+            metadata=metadata or {},
+        )
+
+        # Validate
+        checkpoint.validate(self._max_state_size)
+
+        # Check if state has changed (optional optimization)
+        if skip_if_unchanged and parent_checkpoint_id:
+            parent = self.get_checkpoint(parent_checkpoint_id)
+            if parent and not parent.has_changed(state):
+                return None
+
+        # Persist
+        self._storage.save_checkpoint(checkpoint)
+
+        # Update sequence cache
+        self._sequence_cache[run_id] = sequence_number
+
+        return checkpoint
+
+    def get_checkpoint(self, checkpoint_id: str) -> Optional[Checkpoint]:
+        """Get a checkpoint by ID."""
+        return self._storage.get_checkpoint(checkpoint_id)
+
+    def get_latest_checkpoint(
+        self,
+        run_id: str,
+        branch_id: Optional[str] = None,
+    ) -> Optional[Checkpoint]:
+        """
+        Get the most recent checkpoint for a run.
+
+        Args:
+            run_id: The workflow run identifier.
+            branch_id: Optional branch to filter by.
+
+        Returns:
+            The latest checkpoint, or None if no checkpoints exist.
+        """
+        return self._storage.get_latest_checkpoint(run_id, branch_id)
+
+    def get_resume_point(self, run_id: str) -> Optional[Checkpoint]:
+        """
+        Get the checkpoint to resume from after a crash.
+
+        This is an alias for get_latest_checkpoint for clarity.
+
+        Args:
+            run_id: The workflow run identifier.
+
+        Returns:
+            The checkpoint to resume from, or None if no checkpoints.
+        """
+        return self.get_latest_checkpoint(run_id)
+
+    def get_branch_checkpoints(
+        self,
+        run_id: str,
+        branch_ids: List[str],
+    ) -> Dict[str, Checkpoint]:
+        """
+        Get the latest checkpoint for each branch.
+
+        Used for parallel merge operations.
+
+        Args:
+            run_id: The workflow run identifier.
+            branch_ids: List of branch identifiers.
+
+        Returns:
+            Dictionary mapping branch_id to its latest checkpoint.
+        """
+        result = {}
+        for branch_id in branch_ids:
+            checkpoint = self.get_latest_checkpoint(run_id, branch_id)
+            if checkpoint:
+                result[branch_id] = checkpoint
+        return result
+
+    def cleanup_checkpoints(
+        self,
+        run_id: str,
+        keep_latest: int = 1,
+    ) -> int:
+        """
+        Clean up old checkpoints for a completed run.
+
+        Args:
+            run_id: The workflow run identifier.
+            keep_latest: Number of latest checkpoints to keep.
+
+        Returns:
+            Number of checkpoints deleted.
+        """
+        return self._storage.cleanup_checkpoints(run_id, keep_latest)
+
+    def _get_next_sequence(self, run_id: str) -> int:
+        """Get the next sequence number for a run."""
+        if run_id in self._sequence_cache:
+            return self._sequence_cache[run_id] + 1
+
+        # Query storage for latest sequence
+        latest = self.get_latest_checkpoint(run_id)
+        if latest:
+            self._sequence_cache[run_id] = latest.sequence_number
+            return latest.sequence_number + 1
+
+        return 0

alma/workflow/context.py

@@ -0,0 +1,228 @@
+"""
+ALMA Workflow Context.
+
+Defines the WorkflowContext dataclass and RetrievalScope enum for
+scoped memory retrieval in workflow orchestration systems.
+
+Sprint 1 Tasks 1.1, 1.2
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class RetrievalScope(Enum):
+    """
+    Defines the scope for memory retrieval operations.
+
+    The hierarchy from most specific to most general:
+    NODE -> RUN -> WORKFLOW -> AGENT -> TENANT -> GLOBAL
+
+    Note: Named RetrievalScope (not MemoryScope) to avoid collision
+    with the existing MemoryScope dataclass in alma/types.py which
+    defines what an agent is *allowed* to learn, not *where* to search.
+    """
+
+    # Most specific - only memories from this specific node execution
+    NODE = "node"
+
+    # Memories from this specific workflow run
+    RUN = "run"
+
+    # Memories from all runs of this workflow definition
+    WORKFLOW = "workflow"
+
+    # Memories from all workflows for this agent (default)
+    AGENT = "agent"
+
+    # Memories from all agents within this tenant
+    TENANT = "tenant"
+
+    # All memories across all tenants (admin only)
+    GLOBAL = "global"
+
+    @classmethod
+    def from_string(cls, value: str) -> "RetrievalScope":
+        """Convert string to RetrievalScope enum."""
+        try:
+            return cls(value.lower())
+        except ValueError as err:
+            raise ValueError(
+                f"Invalid RetrievalScope: '{value}'. "
+                f"Valid options: {[s.value for s in cls]}"
+            ) from err
+
+    def is_broader_than(self, other: "RetrievalScope") -> bool:
+        """Check if this scope is broader than another scope."""
+        hierarchy = [
+            RetrievalScope.NODE,
+            RetrievalScope.RUN,
+            RetrievalScope.WORKFLOW,
+            RetrievalScope.AGENT,
+            RetrievalScope.TENANT,
+            RetrievalScope.GLOBAL,
+        ]
+        return hierarchy.index(self) > hierarchy.index(other)
+
+
+@dataclass
+class WorkflowContext:
+    """
+    Context for workflow-scoped memory operations.
+
+    Provides hierarchical scoping for AGtestari and similar workflow
+    orchestration systems. All fields are optional except when
+    require_tenant=True is passed to validate().
+
+    Attributes:
+        tenant_id: Multi-tenant isolation identifier
+        workflow_id: Workflow definition identifier
+        run_id: Specific workflow execution identifier
+        node_id: Current node within the workflow
+        branch_id: Parallel branch identifier (for fan-out patterns)
+        metadata: Additional context data
+        created_at: When this context was created
+    """
+
+    tenant_id: Optional[str] = None
+    workflow_id: Optional[str] = None
+    run_id: Optional[str] = None
+    node_id: Optional[str] = None
+    branch_id: Optional[str] = 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 context.
+
+        Args:
+            require_tenant: If True, tenant_id must be provided.
+                           Use for multi-tenant deployments.
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        if require_tenant and not self.tenant_id:
+            raise ValueError(
+                "tenant_id is required for multi-tenant deployments. "
+                "Set require_tenant=False for single-tenant mode."
+            )
+
+        # If node_id is provided, run_id should also be provided
+        if self.node_id and not self.run_id:
+            raise ValueError("node_id requires run_id to be set")
+
+        # If run_id is provided, workflow_id should also be provided
+        if self.run_id and not self.workflow_id:
+            raise ValueError("run_id requires workflow_id to be set")
+
+        # If branch_id is provided, run_id should also be provided
+        if self.branch_id and not self.run_id:
+            raise ValueError("branch_id requires run_id to be set")
+
+    def get_scope_filter(self, scope: RetrievalScope) -> Dict[str, Any]:
+        """
+        Build a filter dict for the given retrieval scope.
+
+        Returns a dictionary that can be used to filter memories
+        based on the workflow context and requested scope.
+
+        Args:
+            scope: The retrieval scope to filter by.
+
+        Returns:
+            Dictionary with filter criteria.
+        """
+        filters: Dict[str, Any] = {}
+
+        if scope == RetrievalScope.GLOBAL:
+            # No filters - return everything
+            pass
+        elif scope == RetrievalScope.TENANT:
+            if self.tenant_id:
+                filters["tenant_id"] = self.tenant_id
+        elif scope == RetrievalScope.AGENT:
+            if self.tenant_id:
+                filters["tenant_id"] = self.tenant_id
+            # Agent filtering is done separately via the agent parameter
+        elif scope == RetrievalScope.WORKFLOW:
+            if self.tenant_id:
+                filters["tenant_id"] = self.tenant_id
+            if self.workflow_id:
+                filters["workflow_id"] = self.workflow_id
+        elif scope == RetrievalScope.RUN:
+            if self.tenant_id:
+                filters["tenant_id"] = self.tenant_id
+            if self.workflow_id:
+                filters["workflow_id"] = self.workflow_id
+            if self.run_id:
+                filters["run_id"] = self.run_id
+        elif scope == RetrievalScope.NODE:
+            if self.tenant_id:
+                filters["tenant_id"] = self.tenant_id
+            if self.workflow_id:
+                filters["workflow_id"] = self.workflow_id
+            if self.run_id:
+                filters["run_id"] = self.run_id
+            if self.node_id:
+                filters["node_id"] = self.node_id
+
+        return filters
+
+    def with_node(self, node_id: str) -> "WorkflowContext":
+        """Create a new context with a different node_id."""
+        return WorkflowContext(
+            tenant_id=self.tenant_id,
+            workflow_id=self.workflow_id,
+            run_id=self.run_id,
+            node_id=node_id,
+            branch_id=self.branch_id,
+            metadata=self.metadata.copy(),
+            created_at=self.created_at,
+        )
+
+    def with_branch(self, branch_id: str) -> "WorkflowContext":
+        """Create a new context for a parallel branch."""
+        return WorkflowContext(
+            tenant_id=self.tenant_id,
+            workflow_id=self.workflow_id,
+            run_id=self.run_id,
+            node_id=self.node_id,
+            branch_id=branch_id,
+            metadata=self.metadata.copy(),
+            created_at=self.created_at,
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "tenant_id": self.tenant_id,
+            "workflow_id": self.workflow_id,
+            "run_id": self.run_id,
+            "node_id": self.node_id,
+            "branch_id": self.branch_id,
+            "metadata": self.metadata,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "WorkflowContext":
+        """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)
+
+        return cls(
+            tenant_id=data.get("tenant_id"),
+            workflow_id=data.get("workflow_id"),
+            run_id=data.get("run_id"),
+            node_id=data.get("node_id"),
+            branch_id=data.get("branch_id"),
+            metadata=data.get("metadata", {}),
+            created_at=created_at,
+        )