loom-core 0.1.0__py3-none-any.whl

src/decorators/activity.py

@@ -0,0 +1,126 @@
+from ..schemas.workflow import Func
+
+
+def activity(
+    name: str | None = None,
+    description: str | None = None,
+    retry_count: int = 0,
+    timeout_seconds: int = 60,
+):
+    """
+    Decorator to define an activity function with execution policies.
+
+    Activities are the only place where side effects should occur in Loom workflows.
+    They represent external operations like API calls, database queries, file operations,
+    or any non-deterministic work. Activities can be retried on failure and have
+    configurable timeouts.
+
+    Args:
+        name: Custom name for the activity. If None, uses the function name.
+            Should be descriptive and unique for debugging purposes.
+        description: Human-readable description of what this activity does.
+            Used for documentation, logging, and monitoring.
+        retry_count: Number of times to retry the activity on failure.
+            Must be >= 0. Set to 0 to disable retries.
+        timeout_seconds: Maximum time in seconds to wait for activity completion.
+            Must be > 0. Activities exceeding this timeout will be cancelled.
+
+    Returns:
+        The decorated function with activity metadata attached.
+
+    Example:
+        ```python
+        @loom.activity(
+            name="send_notification_email",
+            description="Send email notification to user",
+            retry_count=3,
+            timeout_seconds=30
+        )
+        async def send_email(user_email: str, subject: str, body: str) -> bool:
+            # This activity can fail and be retried up to 3 times
+            async with httpx.AsyncClient() as client:
+                response = await client.post("/api/email/send", json={
+                    "to": user_email,
+                    "subject": subject,
+                    "body": body
+                })
+                response.raise_for_status()
+                return True
+
+        # Usage in workflow step:
+        @loom.step
+        async def notify_user(self, ctx: WorkflowContext[MyState]):
+            success = await ctx.activity(
+                send_email,
+                ctx.input.user_email,
+                "Welcome!",
+                "Thanks for joining!"
+            )
+            ctx.state.email_sent = success
+        ```
+
+    Note:
+        - Activities should be idempotent when possible (safe to retry)
+        - Activities are the execution boundary - no side effects in workflow steps
+        - Activity results are persisted and replayed during workflow recovery
+        - Long-running activities should implement proper cancellation handling
+
+    Raises:
+        ValueError: If retry_count is negative or timeout_seconds is not positive.
+    """
+    # Validate parameters
+    if not isinstance(retry_count, int) or retry_count < 0:
+        raise ValueError(
+            f"Activity retry_count must be a non-negative integer, got {retry_count}"
+        )
+
+    if not isinstance(timeout_seconds, int) or timeout_seconds <= 0:
+        raise ValueError(
+            f"Activity timeout_seconds must be a positive integer, got {timeout_seconds}"
+        )
+
+    if name is not None and not isinstance(name, str):
+        raise ValueError(
+            f"Activity name must be a string or None, got {type(name).__name__}"
+        )
+
+    if description is not None and not isinstance(description, str):
+        raise ValueError(
+            f"Activity description must be a string or None, got {type(description).__name__}"
+        )
+
+    # Reasonable limits to prevent configuration errors
+    if retry_count > 100:
+        raise ValueError(
+            f"Activity retry_count seems excessive: {retry_count}. Maximum recommended is 100."
+        )
+
+    if timeout_seconds > 3600:  # 1 hour
+        raise ValueError(
+            f"Activity timeout_seconds seems excessive: {timeout_seconds}s. "
+            f"Consider if this operation should really take more than 1 hour."
+        )
+
+    def decorator(func: Func) -> Func:
+        """
+        Apply activity metadata to the target function.
+
+        Args:
+            func: The function to decorate as an activity
+
+        Returns:
+            The function with activity metadata attached
+        """
+        # Attach activity metadata
+        setattr(func, "_activity_name", name or getattr(func, "__name__"))
+        setattr(func, "_activity_description", description or "")
+        setattr(func, "_activity_retry_count", retry_count)
+        setattr(func, "_activity_timeout_seconds", timeout_seconds)
+
+        # Add helpful debugging info
+        original_name = getattr(func, "__name__", "unknown")
+        setattr(func, "_activity_original_name", original_name)
+
+        return func
+
+    return decorator

src/decorators/workflow.py

@@ -0,0 +1,46 @@
+from ..schemas.workflow import ClsT, Func
+
+
+def workflow(
+    name: str | None = None,
+    description: str | None = None,
+    version: str = "1.0.0",
+):
+    """
+    Decorator to define a workflow class.
+
+    Args:
+        name (str | None): The name of the workflow. Defaults to the class name if None.
+        description (str | None): A brief description of the workflow. Defaults to an empty string if None.
+        version (str): The version of the workflow. Defaults to "1.0.0".
+    """
+
+    def decorator(cls: ClsT) -> ClsT:
+        setattr(cls, "_workflow_name", name or getattr(cls, "__name__"))
+        setattr(cls, "_workflow_classname", getattr(cls, "__name__"))
+        setattr(cls, "_workflow_module", getattr(cls, "__module__"))
+        setattr(cls, "_workflow_description", description or "")
+        setattr(cls, "_workflow_version", version)
+        return cls
+
+    return decorator
+
+
+def step(
+    name: str | None = None,
+    description: str | None = None,
+):
+    """
+    Decorator to define a step method within a workflow.
+
+    Args:
+        name (str | None): The name of the step. Defaults to the method name if None.
+        description (str | None): A brief description of the step. Defaults to an empty string if None.
+    """
+
+    def decorator(func: Func) -> Func:
+        setattr(func, "_step_name", name or getattr(func, "__name__"))
+        setattr(func, "_step_description", description or "")
+        return func
+
+    return decorator

src/lib/progress.py

@@ -0,0 +1,109 @@
+"""Progress tracking and status display for workflows."""
+
+from datetime import datetime
+from typing import Optional
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskID,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+
+
+class WorkflowProgress:
+    """Display workflow execution progress with rich formatting."""
+
+    def __init__(self, workflow_name: str, total_steps: int):
+        """Initialize progress tracker.
+
+        Args:
+            workflow_name: Name of the workflow being executed
+            total_steps: Total number of steps in the workflow
+        """
+        self.workflow_name = workflow_name
+        self.total_steps = total_steps
+        self.current_step = 0
+        self.started_at = datetime.now()
+        self.console = Console()
+        self.progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            TimeElapsedColumn(),
+            console=self.console,
+        )
+        self.task_id: Optional[TaskID] = None
+
+    def start(self):
+        """Start the progress display."""
+        self.task_id = self.progress.add_task(
+            f"[cyan]Executing {self.workflow_name}", total=self.total_steps
+        )
+        self.progress.start()
+
+    def update(self, step_name: str):
+        """Update progress to next step.
+
+        Args:
+            step_name: Name of the step that just completed
+        """
+        self.current_step += 1
+
+        if self.task_id is not None:
+            self.progress.update(
+                self.task_id,
+                completed=self.current_step,
+                description=f"[cyan]Step: {step_name}",
+            )
+
+    def complete(self):
+        """Mark the workflow as complete."""
+        self.progress.stop()
+        elapsed = datetime.now() - self.started_at
+        self.console.print(
+            f"[green]Workflow '{self.workflow_name}' completed in {elapsed}[/green]"
+        )
+
+    def error(self, message: str):
+        """Display an error message.
+
+        Args:
+            message: Error message to display
+        """
+        self.progress.stop()
+        self.console.print(f"[red]Error: {message}[/red]")
+
+
+def create_status_table(workflows: list) -> Table:
+    """Create a formatted status table for workflows.
+
+    Args:
+        workflows: List of workflow dictionaries
+
+    Returns:
+        Rich Table object
+    """
+    table = Table(title="Workflow Status", show_header=True)
+    table.add_column("Name", style="cyan", width=30)
+    table.add_column("Status", justify="center", width=15)
+    table.add_column("Created", style="green", width=20)
+
+    for wf in workflows:
+        status_style = {
+            "RUNNING": "[yellow]RUNNING[/yellow]",
+            "COMPLETED": "[green]COMPLETED[/green]",
+            "FAILED": "[red]FAILED[/red]",
+            "CANCELED": "[dim]CANCELED[/dim]",
+        }.get(wf.get("status", "Unknown"), wf.get("status", "Unknown"))
+
+        table.add_row(
+            wf.get("name", "Unknown"), status_style, wf.get("created_at", "Unknown")
+        )
+
+    return table

src/lib/utils.py

@@ -0,0 +1,25 @@
+import os
+from typing import List
+
+from ..common.config import MIGRATION_DOWNGRADES, MIGRATION_UPGRADES
+from ..schemas.database import Migration
+
+
+def get_migrations(direction: str) -> List[Migration]:
+    migrations = []
+    migration_path = MIGRATION_UPGRADES if direction == "up" else MIGRATION_DOWNGRADES
+    files = sorted(os.listdir(migration_path))
+    for file in files:
+        if file.endswith(".sql"):
+            with open(os.path.join(migration_path, file), "r", encoding="utf-8") as f:
+                sql = f.read()
+            migrations.append(Migration(name=file, sql=sql))
+    return migrations
+
+
+def get_upgrade_migrations() -> List[Migration]:
+    return get_migrations("up")
+
+
+def get_downgrade_migrations() -> List[Migration]:
+    return get_migrations("down")

src/migrations/down/001_setup_pragma.sql

@@ -0,0 +1,5 @@
+-- Revert to SQLite defaults (no explicit PRAGMA resets needed)
+-- SQLite will use defaults when connection is closed/reopened
+
+-- Note: These settings are connection-specific and will revert to defaults
+-- when the database connection is closed. No explicit downgrade needed.

src/migrations/down/002_create_workflows.sql

@@ -0,0 +1,3 @@
+-- Drop workflows table
+
+DROP TABLE IF EXISTS workflows;

src/migrations/down/003.create_events.sql

@@ -0,0 +1,3 @@
+-- Drop events table
+
+DROP TABLE IF EXISTS events;

src/migrations/down/004.create_tasks.sql

@@ -0,0 +1,3 @@
+-- Drop tasks table
+
+DROP TABLE IF EXISTS tasks;

src/migrations/down/005.create_indexes.sql

@@ -0,0 +1,5 @@
+-- Drop indexes
+
+DROP INDEX IF EXISTS idx_events_workflow_id;
+DROP INDEX IF EXISTS idx_tasks_pending;
+DROP INDEX IF EXISTS idx_workflows_status;

src/migrations/down/006_auto_update_triggers.sql

@@ -0,0 +1,4 @@
+-- Drop triggers
+
+DROP TRIGGER IF EXISTS trg_workflows_updated;
+DROP TRIGGER IF EXISTS trg_tasks_updated;

src/migrations/down/007_create_logs.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS logs;

src/migrations/up/001_setup_pragma.sql

@@ -0,0 +1,11 @@
+-- Enable WAL for concurrent readers/writers
+PRAGMA journal_mode = WAL;
+
+-- Good durability/performance tradeoff for workflows
+PRAGMA synchronous = NORMAL;
+
+-- Wait for write locks instead of failing
+PRAGMA busy_timeout = 5000;
+
+-- Enforce foreign keys (off by default in SQLite)
+PRAGMA foreign_keys = ON;

src/migrations/up/002_create_workflows.sql

@@ -0,0 +1,15 @@
+-- Workflow instances (metadata + cached status)
+
+CREATE TABLE IF NOT EXISTS workflows (
+    id           TEXT PRIMARY KEY,
+    name         TEXT NOT NULL,
+    description  TEXT,
+    version      TEXT NOT NULL,
+    module       TEXT NOT NULL,
+    status       TEXT NOT NULL CHECK (
+        status IN ('RUNNING', 'COMPLETED', 'FAILED', 'CANCELLED')
+    ),
+    input        JSON NOT NULL,
+    created_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);

src/migrations/up/003_create_events.sql

@@ -0,0 +1,13 @@
+-- Append-only event log (SOURCE OF TRUTH)
+
+CREATE TABLE IF NOT EXISTS events (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    workflow_id  TEXT NOT NULL,
+    type         TEXT NOT NULL,
+    payload      JSON,
+    created_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (workflow_id)
+        REFERENCES workflows(id)
+        ON DELETE CASCADE
+);

src/migrations/up/004_create_tasks.sql

@@ -0,0 +1,23 @@
+-- Durable execution queue (steps, activities, timers)
+
+CREATE TABLE IF NOT EXISTS tasks (
+    id            TEXT PRIMARY KEY,
+    workflow_id   TEXT NOT NULL,
+    kind          TEXT NOT NULL CHECK (
+        kind IN ('STEP', 'ACTIVITY', 'TIMER')
+    ),
+    target        TEXT NOT NULL,
+    run_at        TIMESTAMP NOT NULL,
+    status        TEXT NOT NULL CHECK (
+        status IN ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')
+    ),
+    attempts      INTEGER NOT NULL DEFAULT 0,
+    max_attempts INTEGER NOT NULL DEFAULT 3,
+    last_error    TEXT,
+    created_at    TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at    TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (workflow_id)
+        REFERENCES workflows(id)
+        ON DELETE CASCADE
+);

src/migrations/up/005_create_indexes.sql

@@ -0,0 +1,11 @@
+-- Fast event replay
+CREATE INDEX IF NOT EXISTS idx_events_workflow_id
+    ON events(workflow_id);
+
+-- Worker polling (critical)
+CREATE INDEX IF NOT EXISTS idx_tasks_pending
+    ON tasks(status, run_at);
+
+-- Workflow listing / inspection
+CREATE INDEX IF NOT EXISTS idx_workflows_status
+    ON workflows(status);

src/migrations/up/006_auto_update_triggers.sql

@@ -0,0 +1,19 @@
+CREATE TRIGGER IF NOT EXISTS trg_workflows_updated
+AFTER UPDATE ON workflows
+FOR EACH ROW
+BEGIN
+    UPDATE workflows
+    SET updated_at = CURRENT_TIMESTAMP
+    WHERE id = OLD.id;
+END;
+
+-- Trigger to update 'updated_at' timestamp on tasks table updates --
+
+CREATE TRIGGER IF NOT EXISTS trg_tasks_updated
+AFTER UPDATE ON tasks
+FOR EACH ROW
+BEGIN
+    UPDATE tasks
+    SET updated_at = CURRENT_TIMESTAMP
+    WHERE id = OLD.id;
+END;

src/migrations/up/007_create_logs.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS logs (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    workflow_id  TEXT NOT NULL,
+    level        TEXT NOT NULL,
+    message      TEXT NOT NULL,
+    created_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (workflow_id)
+        REFERENCES workflows(id)
+        ON DELETE CASCADE
+);

src/schemas/activity.py

@@ -0,0 +1,13 @@
+from typing import Any, List, TypedDict, TypeVar
+
+FuncReturn = TypeVar("FuncReturn")
+
+
+class ActivityMetadata(TypedDict):
+    name: str
+    description: str
+    retry_count: int
+    args: List[Any]
+    timeout_seconds: int
+    func: str
+    module: str

src/schemas/database.py

@@ -0,0 +1,17 @@
+from typing import TypedDict
+
+from src.schemas.workflow import Step
+
+
+class Migration(TypedDict):
+    name: str
+    sql: str
+
+
+class WorkflowInput(TypedDict):
+    name: str
+    description: str
+    version: str
+    status: str
+    module: str
+    steps: list[Step]

src/schemas/events.py

@@ -0,0 +1,70 @@
+from typing import Any, Dict, Literal, Optional, TypedDict
+
+
+class Event(TypedDict):
+    """Represents a workflow event in the event store.
+
+    Events are immutable records of things that happened during workflow
+    execution, forming the single source of truth for workflow state.
+
+    Attributes:
+        type: Event type identifier (e.g., 'WORKFLOW_STARTED', 'ACTIVITY_COMPLETED')
+        payload: Event-specific data payload containing relevant information
+    """
+
+    type: str
+    payload: Dict[str, Any]
+
+
+class WorkflowFailurePayload(TypedDict, total=False):
+    """Payload structure for workflow failure events.
+
+    Used when a workflow encounters an unrecoverable error during execution.
+
+    Attributes:
+        error: Error message describing what went wrong
+        step: Name of the step where the failure occurred
+        reason: High-level reason for the failure
+        traceback: Full Python traceback for debugging
+    """
+
+    error: str
+    step: str
+    reason: str
+    traceback: str
+
+
+class ActivityFailurePayload(TypedDict, total=False):
+    """Payload structure for activity failure events.
+
+    Used when an activity fails and may be retried based on its configuration.
+
+    Attributes:
+        activity: Name of the failed activity
+        error: Error message from the activity execution
+        attempt: Current attempt number (for retry tracking)
+    """
+
+    activity: str
+    error: str
+    attempt: int
+
+
+class ExtractedError(TypedDict, total=False):
+    """Structured error information extracted from workflow or activity failures.
+
+    Provides a normalized view of errors for monitoring and debugging purposes.
+
+    Attributes:
+        source: Whether the error originated from workflow logic or an activity
+        message: Human-readable error message
+        step: Workflow step name (if error occurred in workflow logic)
+        activity: Activity name (if error occurred in an activity)
+        details: Additional context-specific error information
+    """
+
+    source: Literal["WORKFLOW", "ACTIVITY"]
+    message: str
+    step: Optional[str]
+    activity: Optional[str]
+    details: Dict[str, Any]

src/schemas/tasks.py

@@ -0,0 +1,58 @@
+from datetime import datetime
+from typing import Literal, TypedDict
+
+# Task kind types matching database CHECK constraint
+TaskKind = Literal["STEP", "ACTIVITY", "TIMER"]
+
+# Task status types matching database CHECK constraint
+TaskStatus = Literal["PENDING", "RUNNING", "COMPLETED", "FAILED"]
+
+
+class Task(TypedDict):
+    """
+    Task schema matching the database tasks table structure.
+
+    Tasks represent units of work in the workflow execution queue,
+    including workflow steps, activity executions, and timer events.
+    """
+
+    id: str
+    workflow_id: str
+    kind: TaskKind
+    target: str
+    run_at: str
+    status: TaskStatus
+    attempts: int
+    max_attempts: int
+    last_error: str | None
+    created_at: str
+    updated_at: str
+
+
+class TaskInput(TypedDict):
+    """
+    Input schema for creating new tasks.
+
+    Excludes auto-generated fields like timestamps and attempts.
+    """
+
+    id: str
+    workflow_id: str
+    kind: TaskKind
+    target: str
+    run_at: datetime
+    status: TaskStatus
+    max_attempts: int
+
+
+class TaskUpdate(TypedDict, total=False):
+    """
+    Schema for updating existing tasks.
+
+    All fields are optional to allow partial updates.
+    """
+
+    status: TaskStatus
+    attempts: int
+    last_error: str | None
+    updated_at: datetime

src/schemas/workflow.py

@@ -0,0 +1,33 @@
+from datetime import datetime
+from enum import Enum
+from typing import Awaitable, Callable, TypedDict, TypeVar
+
+StateT = TypeVar("StateT", bound=dict)
+
+Func = TypeVar("Func", bound=Callable[..., Awaitable[object]])
+
+InputT = TypeVar("InputT", bound=dict)
+
+ClsT = TypeVar("ClsT")
+
+
+class Step(TypedDict):
+    name: str
+    description: str
+    fn: str
+
+
+class WorkflowStatus(str, Enum):
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELED = "CANCELED"
+
+
+class WorkflowInfo(TypedDict):
+    id: str
+    name: str
+    status: WorkflowStatus
+    module: str
+    created_at: datetime
+    updated_at: datetime