loom-core 0.1.0__py3-none-any.whl

src/core/context.py

@@ -0,0 +1,256 @@
+import datetime
+from datetime import timedelta
+from typing import Any, Awaitable, Callable, Generic, List
+
+from ..common.errors import NonDeterministicWorkflowError, StopReplay
+from ..database.db import Database
+from ..schemas.activity import ActivityMetadata
+from ..schemas.events import Event
+from ..schemas.workflow import InputT, StateT
+from .logger import WorkflowLogger
+from .state import StateProxy
+
+
+class WorkflowContext(Generic[InputT, StateT]):
+    """Execution context for workflow steps with replay capabilities.
+
+    The WorkflowContext provides a controlled execution environment for workflow
+    steps, managing event history replay, state reconstruction, and activity
+    scheduling. It enforces deterministic execution by controlling access to
+    external resources and side effects.
+
+    Type Parameters:
+        InputT: Immutable input type for the workflow
+        StateT: Mutable state type that gets reconstructed during replay
+
+    Attributes:
+        id: Unique workflow identifier
+        input: Immutable workflow input data
+        history: Chronological list of workflow events
+        state: Current mutable workflow state
+        cursor: Current position in event history during replay
+    """
+
+    id: str
+    input: InputT
+    history: List[Event]
+    state: StateProxy[InputT, StateT]
+    cursor: int = 0
+    logger: WorkflowLogger
+
+    def __init__(
+        self, id: str, input: InputT, history: List[Event], state: StateT
+    ) -> None:
+        """Initialize workflow context with replay state.
+
+        Args:
+            id: Unique workflow identifier
+            input: Immutable workflow input data
+            history: List of events for replay
+            state: Current workflow state
+        """
+        self.id = id
+        self.input = input
+        self.history = history
+        self.state = StateProxy(self, state)
+        self.logger = WorkflowLogger(self)
+
+    # === Private Replay Management Methods ===
+
+    def _peek(self) -> Event | None:
+        """Look at the next event in history without consuming it.
+
+        Returns:
+            Next event in history or None if at end
+        """
+        if self.cursor >= len(self.history):
+            return None
+        return self.history[self.cursor]
+
+    def _consume(self) -> Event:
+        """Consume and return the next event in history.
+
+        Returns:
+            Next event in history
+
+        Raises:
+            RuntimeError: If no event is available to consume
+        """
+        event = self._peek()
+        if event is None:
+            raise RuntimeError("No event available to consume")
+        self.cursor += 1
+        return event
+
+    def _match_event(self, expected_type: str) -> Event | None:
+        """
+        Safe helper to check if the NEXT event matches what we expect.
+        Returns the event if it matches (does NOT consume).
+        Returns None if the next event is something else (or end of history).
+        """
+        event = self._peek()
+        if event and event["type"] == expected_type:
+            return event
+        return None
+
+    @property
+    def is_replaying(self) -> bool:
+        """Check if the workflow is currently replaying events.
+
+        Returns:
+            True if there are remaining events to replay, False otherwise
+        """
+        return self.cursor < len(self.history)
+
+    def _extract_activity_metadata[FuncReturn](
+        self, fn: Callable[..., Awaitable[FuncReturn]], args: tuple[Any, ...]
+    ) -> ActivityMetadata:
+        """Extract metadata from an activity function for scheduling.
+
+        Retrieves activity configuration attributes that were set by the
+        @activity decorator, including retry settings and timeout values.
+
+        Args:
+            fn: Activity function to extract metadata from
+            args: Arguments that will be passed to the activity
+
+        Returns:
+            ActivityMetadata dictionary with function metadata
+        """
+        return {
+            "name": getattr(fn, "_activity_name", fn.__name__),
+            "description": getattr(fn, "_activity_description", ""),
+            "retry_count": getattr(fn, "_activity_retry_count", 0),
+            "timeout_seconds": getattr(fn, "_activity_timeout_seconds", 0),
+            "func": fn.__name__,
+            "module": fn.__module__,
+            "args": list(args),
+        }
+
+    # === Public Activity Execution Methods ===
+
+    async def activity[FuncReturn](
+        self,
+        fn: Callable[..., Awaitable[FuncReturn]],
+        *args,
+    ) -> FuncReturn:
+        metadata = self._extract_activity_metadata(fn, args)
+
+        scheduled_event = self._match_event("ACTIVITY_SCHEDULED")
+
+        if scheduled_event:
+            if scheduled_event["payload"]["name"] != metadata["name"]:
+                raise NonDeterministicWorkflowError(
+                    f"Replay mismatch: Expected activity {metadata['name']}, "
+                    f"found {scheduled_event['payload']['name']} in history."
+                )
+
+            self._consume()
+
+            completed_event = self._match_event("ACTIVITY_COMPLETED")
+
+            if completed_event:
+                self._consume()
+                return completed_event["payload"]["result"]  # type: ignore
+
+            raise StopReplay
+
+        unexpected_event = self._peek()
+        if unexpected_event:
+            raise NonDeterministicWorkflowError(
+                f"Replay mismatch: Code wants to schedule activity {metadata['name']}, "
+                f"but history contains {unexpected_event['type']}."
+            )
+
+        async with Database[InputT, StateT]() as db:
+            await db.create_activity(
+                workflow_id=self.id,
+                metadata=metadata,
+            )
+
+        raise StopReplay
+
+    async def sleep(
+        self, delta: timedelta | None = None, until: datetime.datetime | None = None
+    ) -> None:
+        if delta is None and until is None:
+            raise ValueError("Either 'delta' or 'until' must be provided")
+
+        fire_at: datetime.datetime = (
+            datetime.datetime.now(datetime.timezone.utc) + delta if delta else until  # type: ignore
+        )
+
+        scheduled_event = self._match_event("TIMER_SCHEDULED")
+
+        if scheduled_event:
+            self._consume()
+
+            fired_event = self._match_event("TIMER_FIRED")
+            if fired_event:
+                self._consume()
+                return  # Timer is done
+
+            raise StopReplay
+
+        unexpected_event = self._peek()
+        if unexpected_event:
+            raise NonDeterministicWorkflowError(
+                f"Replay mismatch: Code wants to sleep, "
+                f"but history contains {unexpected_event['type']}."
+            )
+
+        async with Database[InputT, StateT]() as db:
+            await db.create_timer(self.id, fire_at)
+
+        raise StopReplay
+
+    async def wait_until_signal(self, signal_name: str) -> Any:
+        """Pauses the workflow until a specific signal is received.
+
+        If the signal is already in history (replay), it returns the data immediately.
+        If not, it raises StopReplay to suspend execution until the signal arrives.
+        """
+        # 1. Check if the signal is next in history
+        event = self._match_event("SIGNAL_RECEIVED")
+
+        if event:
+            # STRICT CHECK: Ensure this is the signal we are waiting for.
+            # If the history has "Signal B" but we are waiting for "Signal A",
+            # it means the code logic has changed or the flow is non-deterministic.
+            if event["payload"]["name"] != signal_name:
+                raise NonDeterministicWorkflowError(
+                    f"Replay mismatch: Expected signal '{signal_name}', "
+                    f"but history contains signal '{event['payload']['name']}'."
+                )
+
+            self._consume()
+            return event["payload"]["data"]
+
+        unexpected_event = self._peek()
+        if unexpected_event:
+            raise NonDeterministicWorkflowError(
+                f"Replay mismatch: Workflow expecting signal '{signal_name}', "
+                f"but history contains {unexpected_event['type']}."
+            )
+
+        self.logger.info(f"Waiting for signal: {signal_name}")
+        raise StopReplay
+
+    def last_emitted_event_type(self) -> str | None:
+        """Get the type of the last emitted event in the history."""
+        return self.history[-1]["type"]
+
+    async def _append_event(self, type: str, payload: dict[str, Any]) -> None:
+        """Append a new event to the workflow's event history in the database.
+
+        Args:
+            type: Type of the event to append
+            payload: Payload data for the event
+        """
+        async with Database[InputT, StateT]() as db:
+            await db.create_event(
+                workflow_id=self.id,
+                type=type,
+                payload=payload,
+            )
+        self.history.append({"type": type, "payload": payload})

src/core/engine.py

@@ -0,0 +1,106 @@
+from datetime import datetime, timedelta, timezone
+from typing import Generic
+
+from ..common.activity import load_activity
+from ..common.errors import StopReplay
+from ..common.workflow import workflow_registry
+from ..database.db import Database
+from ..schemas.activity import ActivityMetadata
+from ..schemas.tasks import Task
+from ..schemas.workflow import InputT, StateT
+from .context import WorkflowContext
+
+
+class Engine(Generic[InputT, StateT]):
+    """Core workflow execution engine with replay capabilities.
+
+    The Engine is responsible for workflow replay and step execution. It
+    reconstructs workflow state from event history and executes steps in
+    a deterministic manner, stopping when side effects are encountered.
+    """
+
+    @staticmethod
+    async def replay_activity(task: Task):
+        try:
+            workflow_id = task["workflow_id"]
+            activity_name = task["target"]
+            async with Database[InputT, StateT]() as db:
+                event = await db.get_activity_event(
+                    workflow_id, activity_name, task["attempts"]
+                )
+
+            if not event:
+                raise ValueError(
+                    f"No event found for activity {activity_name} in workflow {workflow_id} on attempt {task['attempts']}"
+                )
+
+            metadata = ActivityMetadata(**event["payload"])  # type: ignore
+            fn = load_activity(metadata["module"], metadata["func"])
+            args = metadata["args"]
+            response = await fn(*args)
+
+            async with Database[InputT, StateT]() as db:
+                await db.create_event(
+                    workflow_id,
+                    "ACTIVITY_COMPLETED",
+                    payload={
+                        "name": activity_name,
+                        "result": response,
+                    },
+                )
+
+                await db.task_completed(task["id"])
+                await db.recreate_workflow_task(workflow_id)
+
+        except Exception as e:
+            async with Database[InputT, StateT]() as db:
+                if task["attempts"] >= task["max_attempts"]:
+                    await db.task_failed(task["id"], str(e))
+                    await db.create_event(
+                        workflow_id=task["workflow_id"],
+                        type="ACTIVITY_FAILED",
+                        payload={
+                            "name": task["target"],
+                            "error": str(e),
+                        },
+                    )
+                else:
+
+                    delay = min(60, 2 ** task["attempts"])
+                    next_run = datetime.now(timezone.utc) + timedelta(seconds=delay)
+                    await db.schedule_retry(task["id"], next_run, str(e))
+
+    @staticmethod
+    async def replay_until_block(workflow_id: str) -> None:
+        # Load workflow event history
+        async with Database[InputT, StateT]() as db:
+            workflow_def = await db.get_workflow_info(workflow_id)
+            history = await db.get_workflow_events(workflow_id=workflow_def["id"])
+
+        ctx: WorkflowContext = WorkflowContext(
+            workflow_def["id"], workflow_def["input"], history, {}
+        )
+
+        first_event = ctx._peek()
+        if first_event and first_event["type"] == "WORKFLOW_STARTED":
+            ctx._consume()
+
+        workflow_cls = workflow_registry(workflow_def["module"], workflow_def["name"])
+        workflow = workflow_cls()
+        steps = workflow._discover_workflow_steps()
+
+        try:
+            for step in steps:
+                step_fn = getattr(workflow, step["fn"])
+                await step_fn(ctx)
+
+        except StopReplay:
+            last = ctx.last_emitted_event_type()
+            if last in ("STATE_SET", "STATE_UPDATE"):
+                async with Database[InputT, StateT]() as db:
+                    await db.rotate_workflow_driver(workflow_id)
+            return
+
+        async with Database[InputT, StateT]() as db:
+            await db.create_event(workflow_id, "WORKFLOW_COMPLETED", {})
+            await db.complete_running_step(workflow_id)

src/core/handle.py

@@ -0,0 +1,166 @@
+from datetime import datetime
+from typing import Any, Dict, Generic, Iterable, List
+
+from ..common.errors import (
+    WorkerCancelledError,
+    WorkflowExecutionError,
+    WorkflowStillRunningError,
+)
+from ..database.db import Database
+from ..schemas.events import (
+    ActivityFailurePayload,
+    Event,
+    ExtractedError,
+    WorkflowFailurePayload,
+)
+from ..schemas.workflow import InputT, StateT, WorkflowInfo
+
+
+class WorkflowHandle(Generic[InputT, StateT]):
+    """
+    Handle for managing workflows.
+    """
+
+    id: str
+
+    def __init__(self, id: str) -> None:
+        self.id = id
+
+    async def info(self) -> WorkflowInfo:
+        async with Database[InputT, StateT]() as db:
+            row = await db.get_workflow_info(self.id)
+
+        return WorkflowInfo(
+            id=row["id"],
+            name=row["name"],
+            status=row["status"],
+            module=row["module"],
+            created_at=datetime.fromisoformat(row["created_at"]),
+            updated_at=datetime.fromisoformat(row["updated_at"]),
+        )
+
+    async def status(self) -> str:
+        """Get workflow status efficiently without fetching all info."""
+        async with Database[InputT, StateT]() as db:
+            return await db.get_workflow_status(self.id)
+
+    async def result(self) -> StateT:
+        # Check status first to avoid unnecessary work
+        async with Database[InputT, StateT]() as db:
+            status = await db.get_workflow_status(self.id)
+
+        if status == "RUNNING":
+            raise WorkflowStillRunningError(
+                "Workflow is still running; result is not available."
+            )
+
+        async with Database[InputT, StateT]() as db:
+            events = await db.get_workflow_events(self.id)
+
+        state = self._replay_state(events)
+
+        if status == "FAILED":
+            error = self._extract_error(events)
+            raise WorkflowExecutionError(error)
+        if status == "CANCELED":
+            raise WorkerCancelledError("Workflow was canceled; no result is available.")
+
+        return state
+
+    async def signal(self, name: str, payload: Dict[str, Any]) -> None:
+        # Validate signal name and payload.
+        if not name:
+            raise ValueError("Signal name must be a non-empty string.")
+        if not isinstance(payload, dict):
+            raise ValueError("Signal payload must be a dictionary.")
+
+        async with Database[InputT, StateT]() as db:
+            await db.create_signal_event(self.id, name, payload)
+
+    def _replay_state(self, events: List[Event]) -> StateT:
+        """Replay workflow state from events with optimized processing."""
+        # Initialize as dict since we don't know the concrete StateT type at runtime
+        state_dict = {}
+
+        for event in events:
+            event_type = event["type"]
+
+            if event_type == "STATE_SET":
+                try:
+                    payload = event["payload"]
+                    state_dict[payload["key"]] = payload["value"]
+                except (KeyError, TypeError):
+                    continue
+
+            elif event_type == "STATE_UPDATE":
+                try:
+                    payload = event["payload"]
+                    state_dict.update(payload)
+                except TypeError:
+                    continue
+
+        return state_dict  # type: ignore
+
+    def _extract_error(self, events: Iterable[Event]) -> ExtractedError:
+        """
+        Extract the most relevant failure from workflow events.
+
+        Rules:
+        - Prefer WORKFLOW_FAILED over ACTIVITY_FAILED
+        - Use the last failure event
+        - Never raise from this method
+        """
+
+        last_workflow_failure: WorkflowFailurePayload | None = None
+        last_activity_failure: ActivityFailurePayload | None = None
+
+        for event in events:
+            etype = event["type"]
+            payload = event.get("payload", {})
+
+            if etype == "WORKFLOW_FAILED":
+                last_workflow_failure = payload  # type: ignore
+
+            elif etype == "ACTIVITY_FAILED":
+                last_activity_failure = payload  # type: ignore
+
+        if last_workflow_failure:
+            return {
+                "source": "WORKFLOW",
+                "message": last_workflow_failure.get("error", "Workflow failed"),
+                "step": last_workflow_failure.get("step"),
+                "details": dict(last_workflow_failure),
+            }
+
+        if last_activity_failure:
+            return {
+                "source": "ACTIVITY",
+                "message": last_activity_failure.get("error", "Activity failed"),
+                "activity": last_activity_failure.get("activity"),
+                "details": dict(last_activity_failure),
+            }
+
+        # Defensive fallback
+        return {
+            "source": "WORKFLOW",
+            "message": "Workflow failed for unknown reasons",
+            "details": {},
+        }
+
+    @classmethod
+    def with_id(cls, id: str) -> "WorkflowHandle[InputT, StateT]":
+        """
+        Create a new WorkflowHandle with the specified ID.
+
+        Args:
+            id: The workflow ID to associate with the handle.
+
+        Returns:
+            A new WorkflowHandle instance with the given ID.
+
+        Example:
+            ```python
+            handle = WorkflowHandle.with_id("workflow-1234")
+            ```
+        """
+        return cls(id)

src/core/logger.py

@@ -0,0 +1,60 @@
+import asyncio
+import logging
+from typing import Any
+
+from ..database.db import Database
+
+# Configure logging with rich formatting if available
+try:
+    from rich.logging import RichHandler
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(message)s",
+        handlers=[RichHandler(rich_tracebacks=True, show_time=True, show_path=False)],
+    )
+except ImportError:
+    # Fallback to standard logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+
+class WorkflowLogger:
+    def __init__(self, ctx: Any):
+        self._ctx = ctx
+        self._std_logger = logging.getLogger("workflow")
+        self._std_logger.setLevel(logging.DEBUG)
+
+    def info(self, msg: str):
+        self._log("INFO", msg)
+
+    def error(self, msg: str):
+        self._log("ERROR", msg)
+
+    def warning(self, msg: str):
+        self._log("WARNING", msg)
+
+    def debug(self, msg: str):
+        self._log("DEBUG", msg)
+
+    def _log(self, level: str, msg: str):
+        if self._ctx.is_replaying:
+            return
+
+        self._std_logger.info(f"{msg}")
+        asyncio.create_task(self._write_log_to_db(level, msg))
+
+    async def _write_log_to_db(self, level: str, msg: str):
+        # This is a "best effort" write. If it fails, workflow proceeds.
+        try:
+            async with Database[Any, Any]() as db:
+                await db.create_log(
+                    workflow_id=self._ctx.id,
+                    level=level,
+                    message=msg,
+                )
+        except Exception:
+            # Never crash the workflow because logging failed
+            pass

src/core/runner.py

@@ -0,0 +1,53 @@
+import datetime
+import traceback
+
+from ..common.errors import StopReplay
+from ..database.db import Database
+from .engine import Engine
+
+
+async def run_once() -> bool:
+    """Execute a single task from the queue.
+
+    Returns:
+        bool: True if a task was executed, False if no tasks available
+    """
+    db: Database = Database()
+    async with db:
+        task = await db.claim_task()
+        if not task:
+            return False
+
+        workflow_id = task["workflow_id"]
+        is_completed = await db.workflow_is_completed(workflow_id)
+        if is_completed:
+            await db.task_completed(task["id"])
+            return True
+
+        try:
+            if task["kind"] == "STEP":
+                await Engine.replay_until_block(workflow_id)
+            elif task["kind"] == "ACTIVITY":
+                await Engine.replay_activity(task)
+            elif task["kind"] == "TIMER":
+                now = datetime.datetime.now(datetime.timezone.utc)
+                run_at = datetime.datetime.fromisoformat(task["run_at"])
+                if now < run_at:
+                    await db.release_task(task["id"])
+                    return True
+
+                await db.create_event(
+                    workflow_id=workflow_id,
+                    type="TIMER_FIRED",
+                    payload={},
+                )
+
+                await db.rotate_workflow_driver(task["workflow_id"])
+            await db.task_completed(task["id"])
+            return True
+        except StopReplay:
+            return True
+        except Exception as e:
+            traceback.print_exc()
+            await db.task_failed(task["id"], str(e))
+            return True