loom-core 0.1.0__py3-none-any.whl

src/cli/cli.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Loom CLI - Command-line interface for Loom workflow orchestration."""
+
+import asyncio
+import sys
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ..core.worker import start_worker
+from ..database.db import Database
+
+console = Console()
+
+
+def echo(message: str, **kwargs):
+    """Print with rich console."""
+    console.print(message)
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="loom")
+def cli():
+    """Loom - Durable Workflow Orchestration Engine.
+
+    Loom provides event-sourced, deterministic workflow execution with
+    automatic recovery and replay capabilities.
+    """
+    pass
+
+
+@cli.command()
+@click.option(
+    "--workers",
+    "-w",
+    default=4,
+    type=int,
+    help="Number of concurrent task workers",
+    show_default=True,
+)
+@click.option(
+    "--poll-interval",
+    "-p",
+    default=0.5,
+    type=float,
+    help="Polling interval in seconds",
+    show_default=True,
+)
+def worker(workers: int, poll_interval: float):
+    """Start a distributed workflow worker.
+
+    The worker continuously polls for available tasks and executes them
+    concurrently. Supports graceful shutdown via Ctrl+C or SIGTERM.
+
+    Examples:
+        loom worker                    # Start with defaults (4 workers)
+        loom worker -w 8               # Start with 8 concurrent workers
+        loom worker -w 2 -p 1.0        # 2 workers, 1 second poll interval
+    """
+    try:
+        console.print("[bold green]Starting Loom workflow worker...[/bold green]")
+        asyncio.run(start_worker(workers=workers, poll_interval=poll_interval))
+    except KeyboardInterrupt:
+        pass
+
+
+@cli.command()
+def init():
+    """Initialize the Loom database and migrations.
+
+    Creates the database file and applies all pending migrations.
+    Safe to run multiple times - will skip if already initialized.
+    """
+    echo("Initializing Loom database...")
+
+    async def _init():
+        async with Database[Any, Any]() as db:
+            await db._init_db()
+
+    try:
+        asyncio.run(_init())
+        echo("[green]Database initialized successfully[/green]")
+    except Exception as e:
+        echo(f"[red]Initialization failed: {e}[/red]")
+        sys.exit(1)
+
+
+@cli.command()
+@click.option(
+    "--limit",
+    "-l",
+    default=50,
+    type=int,
+    help="Maximum number of workflows to display",
+    show_default=True,
+)
+@click.option(
+    "--status",
+    "-s",
+    type=click.Choice(
+        ["RUNNING", "COMPLETED", "FAILED", "CANCELED"], case_sensitive=False
+    ),
+    help="Filter by workflow status",
+)
+def list(limit: int, status: str | None):
+    """List workflows with optional filtering.
+
+    Examples:
+        loom list                      # List recent workflows
+        loom list -l 100               # List up to 100 workflows
+        loom list -s RUNNING           # List only running workflows
+    """
+
+    async def _list():
+        async with Database[Any, Any]() as db:
+            if status:
+                sql = """
+                    SELECT id, name, status, created_at, updated_at
+                    FROM workflows
+                    WHERE status = ?
+                    ORDER BY created_at DESC
+                    LIMIT ?
+                """
+                workflows = await db.query(sql, (status.upper(), limit))
+            else:
+                sql = """
+                    SELECT id, name, status, created_at, updated_at
+                    FROM workflows
+                    ORDER BY created_at DESC
+                    LIMIT ?
+                """
+                workflows = await db.query(sql, (limit,))
+
+            if not workflows:
+                echo("No workflows found")
+                return
+
+            table = Table(
+                title="Workflows", show_header=True, header_style="bold magenta"
+            )
+            table.add_column("ID", style="dim", width=40)
+            table.add_column("Name", style="cyan", width=25)
+            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["status"], wf["status"])
+
+                table.add_row(wf["id"], wf["name"], status_style, wf["created_at"])
+
+            console.print(table)
+
+    try:
+        asyncio.run(_list())
+    except Exception as e:
+        echo(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("workflow_id")
+@click.option(
+    "--events/--no-events",
+    default=False,
+    help="Show event history",
+)
+def inspect(workflow_id: str, events: bool):
+    """Inspect detailed workflow information.
+
+    Shows workflow metadata, current state, and optionally event history.
+
+    Examples:
+        loom inspect <workflow-id>
+        loom inspect <workflow-id> --events
+    """
+
+    async def _inspect():
+        async with Database[Any, Any]() as db:
+            # Get workflow info
+            workflow = await db.get_workflow_info(workflow_id)
+
+            echo(f"\n[bold]Workflow: {workflow['name']}[/bold]\n")
+            echo(f"ID:          {workflow['id']}")
+            echo(f"Status:      {workflow['status']}")
+            echo(f"Module:      {workflow['module']}")
+            echo(f"Version:     {workflow['version']}")
+            echo(f"Created:     {workflow['created_at']}")
+            echo(f"Updated:     {workflow['updated_at']}")
+
+            if events:
+                event_list = await db.get_workflow_events(workflow_id)
+                echo(f"\n[bold]Events ({len(event_list)}):[/bold]\n")
+
+                for i, event in enumerate(event_list, 1):
+                    echo(f"{i:3d}. {event['type']}")
+                    if event["payload"]:
+                        echo(f"     Payload: {event['payload']}")
+
+    try:
+        asyncio.run(_inspect())
+    except Exception as e:
+        echo(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+
+@cli.command()
+def stats():
+    """Show database statistics and health metrics.
+
+    Displays counts of workflows, events, tasks, and logs.
+    """
+
+    async def _stats():
+        async with Database[Any, Any]() as db:
+            workflows = await db.query("SELECT COUNT(*) as count FROM workflows")
+            events = await db.query("SELECT COUNT(*) as count FROM events")
+            tasks = await db.query("SELECT COUNT(*) as count FROM tasks")
+            logs = await db.query("SELECT COUNT(*) as count FROM logs")
+
+            running = await db.query(
+                "SELECT COUNT(*) as count FROM workflows WHERE status = 'RUNNING'"
+            )
+
+            echo("\n[bold]Database Statistics:[/bold]\n")
+            echo(f"Total Workflows:    {list(workflows)[0]['count']}")
+            echo(f"Running Workflows:  {list(running)[0]['count']}")
+            echo(f"Total Events:       {list(events)[0]['count']}")
+            echo(f"Pending Tasks:      {list(tasks)[0]['count']}")
+            echo(f"Log Entries:        {list(logs)[0]['count']}")
+
+    try:
+        asyncio.run(_stats())
+    except Exception as e:
+        echo(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

src/common/activity.py

@@ -0,0 +1,30 @@
+import importlib
+from typing import Any, Awaitable, Callable, cast
+
+
+def load_activity(module: str, func: str) -> Callable[..., Awaitable[Any]]:
+
+    try:
+        activity_module = importlib.import_module(module)
+    except ModuleNotFoundError as e:
+        raise ModuleNotFoundError(
+            f"Cannot import activity module '{module}'. "
+            f"Ensure the module exists and is in the Python path."
+        ) from e
+
+    try:
+        activity_func = getattr(activity_module, func)
+    except AttributeError as e:
+        raise AttributeError(
+            f"Activity function '{func}' not found in module '{module}'. "
+            f"Available functions: {[name for name in dir(activity_module) if not name.startswith('_')]}"
+        ) from e
+
+    # Validate that it's actually a function
+    if not callable(activity_func):
+        raise TypeError(
+            f"'{func}' from module '{module}' is not callable. "
+            f"Got {type(activity_func).__name__}."
+        )
+
+    return cast(Callable[..., Awaitable[Any]], activity_func)

src/common/config.py

@@ -0,0 +1,9 @@
+import os
+
+MIGRATION_UPGRADES = os.path.join(os.path.dirname(__file__), "../", "migrations", "up")
+
+MIGRATION_DOWNGRADES = os.path.join(
+    os.path.dirname(__file__), "../", "migrations", "down"
+)
+DATA_ROOT = ".loom"
+DATABASE = os.path.join(DATA_ROOT, "loom.db")

src/common/errors.py

@@ -0,0 +1,64 @@
+class WorkflowNotFoundError(Exception):
+    """Exception raised when a workflow is not found in the database."""
+
+    pass
+
+
+class WorkflowStillRunningError(Exception):
+    """Exception raised when attempting to retrieve the result of a running workflow."""
+
+    pass
+
+
+class WorkflowExecutionError(Exception):
+    """Exception raised when a workflow has failed during execution."""
+
+    pass
+
+
+class WorkerCancelledError(Exception):
+    """Exception raised when a worker has been cancelled."""
+
+    pass
+
+
+class StopReplay(Exception):
+    """
+    Exception used to signal that workflow replay should stop.
+
+    This is typically raised internally during workflow execution replay
+    when the workflow reaches a point where it needs to wait for external input
+    or events, indicating that replay cannot proceed further at this time.
+
+    Example usage:
+
+        from loom import loom
+        from loom.schemas.workflow import Workflow, WorkflowContext, InputT, StateT
+
+        class MyInput(InputT):
+            pass
+
+        class MyState(StateT):
+            pass
+
+        result: str = ""
+
+        @loom.workflow
+        class MyWorkflow(Workflow[MyInput, MyState]):
+            @loom.step
+            async def process(self, ctx: WorkflowContext[MyState]):
+                # Workflow logic here
+                pass
+    """
+
+    pass
+
+
+class NonDeterministicWorkflowError(Exception):
+    """Exception raised when a workflow execution diverges from its recorded history.
+
+    This typically indicates that the workflow code has changed in a way that
+    affects its execution path, leading to inconsistencies during replay.
+    """
+
+    pass

src/common/workflow.py

@@ -0,0 +1,56 @@
+import importlib
+from typing import Any, Type
+
+from ..core.workflow import Workflow
+
+
+def workflow_registry(module: str, cls: str) -> Type[Workflow[Any, Any]]:
+    """
+    Retrieve a workflow class from the global registry.
+
+    Args:
+        module: The module name where the workflow is defined.
+        cls: The class name of the workflow.
+
+    Returns:
+        The workflow class with proper typing.
+
+    Example:
+        ```python
+        # Get a workflow class dynamically
+        WorkflowCls = workflow_registry("myapp.workflows", "UserOnboardingWorkflow")
+
+        # Compile and use it
+        compiled_workflow = WorkflowCls.compile()
+        handle = await compiled_workflow.start(input_data)
+        ```
+
+    Raises:
+        ModuleNotFoundError: If the module cannot be imported.
+        AttributeError: If the class doesn't exist in the module.
+        TypeError: If the retrieved class is not a Workflow subclass.
+    """
+    try:
+        workflow_module = importlib.import_module(module)
+    except ModuleNotFoundError as e:
+        raise ModuleNotFoundError(
+            f"Cannot import workflow module '{module}'. "
+            f"Ensure the module exists and is in the Python path."
+        ) from e
+
+    try:
+        workflow_cls: Type[Workflow[Any, Any]] = getattr(workflow_module, cls)
+    except AttributeError as e:
+        raise AttributeError(
+            f"Workflow class '{cls}' not found in module '{module}'. "
+            f"Available classes: {[name for name in dir(workflow_module) if not name.startswith('_')]}"
+        ) from e
+
+    # Validate that it's actually a Workflow subclass
+    if not (isinstance(workflow_cls, type) and issubclass(workflow_cls, Workflow)):
+        raise TypeError(
+            f"Class '{cls}' from module '{module}' is not a Workflow subclass. "
+            f"Got {type(workflow_cls).__name__}."
+        )
+
+    return workflow_cls

src/core/compiled.py

@@ -0,0 +1,41 @@
+from typing import Generic, List
+
+from ..core.handle import WorkflowHandle
+from ..database.db import Database
+from ..schemas.database import WorkflowInput
+from ..schemas.workflow import InputT, StateT, Step
+
+
+class CompiledWorkflow(Generic[InputT, StateT]):
+    name: str
+    description: str
+    version: str
+    module: str
+    steps: List[Step]
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        version: str,
+        module: str,
+        steps: List[Step],
+    ):
+        self.name = name
+        self.description = description
+        self.version = version
+        self.module = module
+        self.steps = steps
+
+    async def start(self, input: InputT):
+        workflow: WorkflowInput = {
+            "name": self.name,
+            "description": self.description,
+            "version": self.version,
+            "status": "RUNNING",
+            "module": self.module,
+            "steps": self.steps,
+        }
+        async with Database[InputT, StateT]() as db:
+            workflow_id = await db.create_workflow(workflow, input)
+        return WorkflowHandle[InputT, StateT](workflow_id)