msaas-workflow-engine 0.1.0__tar.gz

msaas_workflow_engine-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.*.template
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_workflow_engine-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: msaas-workflow-engine
+Version: 0.1.0
+Summary: Workflow and state machine engine for SaaS applications
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'

msaas_workflow_engine-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "msaas-workflow-engine"
+version = "0.1.0"
+description = "Workflow and state machine engine for SaaS applications"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+"msaas-api-core",
+"msaas-errors","pydantic>=2.0"
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+    "fastapi>=0.115.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/workflow_engine"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_workflow_engine-0.1.0/src/workflow_engine/__init__.py

@@ -0,0 +1,46 @@
+"""Willian Workflow Engine -- State machine engine for SaaS applications."""
+
+from workflow_engine.config import (
+    WorkflowConfig,
+    get_store,
+    get_workflow,
+    init_workflow,
+    reset,
+)
+from workflow_engine.engine import TransitionError, WorkflowEngine
+from workflow_engine.hooks import HookRegistry, HookType
+from workflow_engine.models import (
+    Condition,
+    HistoryEntry,
+    InstanceStatus,
+    State,
+    StateType,
+    Transition,
+    WorkflowDefinition,
+    WorkflowInstance,
+)
+from workflow_engine.router import create_workflow_router
+from workflow_engine.store import InMemoryWorkflowStore, WorkflowStore
+
+__all__ = [
+    "Condition",
+    "HistoryEntry",
+    "HookRegistry",
+    "HookType",
+    "InMemoryWorkflowStore",
+    "InstanceStatus",
+    "State",
+    "StateType",
+    "Transition",
+    "TransitionError",
+    "WorkflowConfig",
+    "WorkflowDefinition",
+    "WorkflowEngine",
+    "WorkflowInstance",
+    "WorkflowStore",
+    "create_workflow_router",
+    "get_store",
+    "get_workflow",
+    "init_workflow",
+    "reset",
+]

msaas_workflow_engine-0.1.0/src/workflow_engine/config.py

@@ -0,0 +1,98 @@
+"""Module configuration and singleton access."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from workflow_engine.hooks import HookRegistry
+from workflow_engine.store import InMemoryWorkflowStore, WorkflowStore
+
+
+_config: WorkflowConfig | None = None
+_engine: object | None = None  # Lazy ref to avoid circular import
+_store: WorkflowStore | None = None
+
+
+class WorkflowConfig(BaseModel):
+    """Configuration for the workflow engine module.
+
+    Args:
+        max_history_entries: Maximum history entries kept per instance (0 = unlimited).
+        enable_hooks: Whether lifecycle hooks are executed.
+        default_store_type: Store backend to use when none is provided.
+    """
+
+    max_history_entries: int = 0
+    enable_hooks: bool = True
+    default_store_type: str = "memory"
+
+
+def init_workflow(
+    config: WorkflowConfig | None = None,
+    *,
+    store: WorkflowStore | None = None,
+) -> WorkflowConfig:
+    """Initialize the workflow module.
+
+    Args:
+        config: Module configuration. Uses defaults if None.
+        store: Optional custom store. Falls back to InMemoryWorkflowStore.
+
+    Returns:
+        The active WorkflowConfig.
+    """
+    global _config, _engine, _store
+    _config = config or WorkflowConfig()
+    _store = store or InMemoryWorkflowStore()
+    _engine = None  # Reset cached engine
+    return _config
+
+
+def get_config() -> WorkflowConfig:
+    """Return the current module configuration.
+
+    Raises:
+        RuntimeError: If init_workflow() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError("Workflow module not initialized. Call init_workflow() first.")
+    return _config
+
+
+def get_store() -> WorkflowStore:
+    """Return the configured workflow store.
+
+    Raises:
+        RuntimeError: If init_workflow() has not been called.
+    """
+    if _store is None:
+        raise RuntimeError("Workflow module not initialized. Call init_workflow() first.")
+    return _store
+
+
+def get_workflow():
+    """Return or create the singleton WorkflowEngine.
+
+    Returns:
+        The active WorkflowEngine instance.
+
+    Raises:
+        RuntimeError: If init_workflow() has not been called.
+    """
+    global _engine
+    if _config is None:
+        raise RuntimeError("Workflow module not initialized. Call init_workflow() first.")
+    if _engine is None:
+        from workflow_engine.engine import WorkflowEngine
+
+        hooks = HookRegistry() if _config.enable_hooks else None
+        _engine = WorkflowEngine(_store, hooks=hooks)
+    return _engine
+
+
+def reset() -> None:
+    """Reset module state (useful for testing)."""
+    global _config, _engine, _store
+    _config = None
+    _engine = None
+    _store = None

msaas_workflow_engine-0.1.0/src/workflow_engine/engine.py

@@ -0,0 +1,254 @@
+"""Core workflow engine: orchestrates definitions, transitions, and hooks."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from workflow_engine.hooks import HookRegistry, HookType
+from workflow_engine.models import (
+    Condition,
+    HistoryEntry,
+    InstanceStatus,
+    StateType,
+    WorkflowDefinition,
+    WorkflowInstance,
+)
+from workflow_engine.store import WorkflowStore
+
+
+class TransitionError(Exception):
+    """Raised when a transition is invalid or cannot be executed."""
+
+
+class WorkflowEngine:
+    """State machine engine that manages workflow lifecycles.
+
+    Args:
+        store: Persistence backend for definitions and instances.
+        hooks: Hook registry for lifecycle callbacks.
+    """
+
+    def __init__(self, store: WorkflowStore, hooks: HookRegistry | None = None) -> None:
+        self._store = store
+        self._hooks = hooks or HookRegistry()
+
+    @property
+    def hooks(self) -> HookRegistry:
+        """Access the hook registry for registering callbacks."""
+        return self._hooks
+
+    # -- Definition management --
+
+    async def register_definition(self, definition: WorkflowDefinition) -> WorkflowDefinition:
+        """Validate and persist a workflow definition.
+
+        Raises:
+            ValueError: If the definition is structurally invalid.
+        """
+        self._validate_definition(definition)
+        await self._store.save_definition(definition)
+        return definition
+
+    async def get_definition(self, name: str) -> WorkflowDefinition | None:
+        """Retrieve a definition by name."""
+        return await self._store.get_definition(name)
+
+    # -- Instance management --
+
+    async def create_instance(
+        self,
+        definition_name: str,
+        context: dict[str, Any] | None = None,
+        *,
+        instance_id: str | None = None,
+    ) -> WorkflowInstance:
+        """Create a new workflow instance from a registered definition.
+
+        Args:
+            definition_name: Name of the workflow definition to instantiate.
+            context: Initial context data.
+            instance_id: Optional custom ID (auto-generated if omitted).
+
+        Raises:
+            ValueError: If the definition is not registered.
+        """
+        definition = await self._store.get_definition(definition_name)
+        if definition is None:
+            raise ValueError(f"Workflow definition '{definition_name}' not found")
+
+        kwargs: dict[str, Any] = {
+            "definition_name": definition_name,
+            "current_state": definition.initial_state,
+            "context": context or {},
+        }
+        if instance_id is not None:
+            kwargs["id"] = instance_id
+
+        instance = WorkflowInstance(**kwargs)
+
+        # Execute on_enter hooks for the initial state
+        state_obj = self._find_state(definition, definition.initial_state)
+        if state_obj and state_obj.on_enter:
+            await self._hooks.execute_many(HookType.ON_ENTER, state_obj.on_enter, instance)
+
+        await self._store.save_instance(instance)
+        return instance
+
+    async def get_instance(self, instance_id: str) -> WorkflowInstance | None:
+        """Retrieve an instance by ID."""
+        return await self._store.get_instance(instance_id)
+
+    async def list_instances(
+        self,
+        *,
+        definition_name: str | None = None,
+        status: InstanceStatus | None = None,
+        current_state: str | None = None,
+    ) -> list[WorkflowInstance]:
+        """List instances with optional filters."""
+        return await self._store.list_instances(
+            definition_name=definition_name,
+            status=status,
+            current_state=current_state,
+        )
+
+    # -- Transition execution --
+
+    async def trigger(
+        self,
+        instance_id: str,
+        trigger: str,
+        *,
+        actor_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        context_update: dict[str, Any] | None = None,
+    ) -> WorkflowInstance:
+        """Fire a trigger on an instance, causing a state transition.
+
+        Args:
+            instance_id: Target instance.
+            trigger: Event name to fire.
+            actor_id: Who/what initiated the trigger.
+            metadata: Extra data to record in the history entry.
+            context_update: Key-value pairs to merge into the instance context.
+
+        Raises:
+            ValueError: If instance or definition is not found.
+            TransitionError: If no valid transition exists for the trigger.
+        """
+        instance = await self._store.get_instance(instance_id)
+        if instance is None:
+            raise ValueError(f"Instance '{instance_id}' not found")
+
+        if instance.status != InstanceStatus.ACTIVE:
+            raise TransitionError(
+                f"Instance '{instance_id}' is {instance.status.value}, not active"
+            )
+
+        definition = await self._store.get_definition(instance.definition_name)
+        if definition is None:
+            raise ValueError(f"Definition '{instance.definition_name}' not found for instance")
+
+        # Apply context update before evaluating conditions
+        if context_update:
+            instance.context.update(context_update)
+
+        # Find matching transition
+        transition = self._find_transition(definition, instance, trigger)
+
+        # Execute on_exit hooks for the current state
+        from_state = self._find_state(definition, instance.current_state)
+        if from_state and from_state.on_exit:
+            await self._hooks.execute_many(HookType.ON_EXIT, from_state.on_exit, instance)
+
+        # Execute transition action hooks
+        if transition.actions:
+            await self._hooks.execute_many(HookType.ON_TRANSITION, transition.actions, instance)
+
+        # Record history
+        entry = HistoryEntry(
+            from_state=instance.current_state,
+            to_state=transition.to_state,
+            trigger=trigger,
+            actor_id=actor_id,
+            metadata=metadata or {},
+        )
+        instance.history.append(entry)
+
+        # Move to new state
+        instance.current_state = transition.to_state
+        instance.updated_at = datetime.now(timezone.utc)
+
+        # Execute on_enter hooks for the new state
+        to_state = self._find_state(definition, transition.to_state)
+        if to_state and to_state.on_enter:
+            await self._hooks.execute_many(HookType.ON_ENTER, to_state.on_enter, instance)
+
+        # Auto-complete if we reached an end state
+        if to_state and to_state.type == StateType.END:
+            instance.status = InstanceStatus.COMPLETED
+
+        await self._store.save_instance(instance)
+        return instance
+
+    # -- Validation helpers --
+
+    @staticmethod
+    def _validate_definition(definition: WorkflowDefinition) -> None:
+        """Validate structural integrity of a workflow definition."""
+        state_names = {s.name for s in definition.states}
+
+        if definition.initial_state not in state_names:
+            raise ValueError(f"Initial state '{definition.initial_state}' not in states")
+
+        start_states = [s for s in definition.states if s.type == StateType.START]
+        if len(start_states) > 1:
+            raise ValueError("Workflow must have at most one start state")
+
+        if start_states and start_states[0].name != definition.initial_state:
+            raise ValueError("Start state must match initial_state")
+
+        for t in definition.transitions:
+            if t.from_state not in state_names:
+                raise ValueError(f"Transition from unknown state '{t.from_state}'")
+            if t.to_state not in state_names:
+                raise ValueError(f"Transition to unknown state '{t.to_state}'")
+
+    @staticmethod
+    def _find_state(definition: WorkflowDefinition, name: str):
+        """Find a state by name within a definition."""
+        for s in definition.states:
+            if s.name == name:
+                return s
+        return None
+
+    def _find_transition(
+        self,
+        definition: WorkflowDefinition,
+        instance: WorkflowInstance,
+        trigger: str,
+    ):
+        """Find a valid transition for the trigger from the current state.
+
+        Raises:
+            TransitionError: If no matching transition is found.
+        """
+        candidates = [
+            t
+            for t in definition.transitions
+            if t.from_state == instance.current_state and t.trigger == trigger
+        ]
+
+        for t in candidates:
+            if self._evaluate_conditions(t.conditions, instance.context):
+                return t
+
+        raise TransitionError(
+            f"No valid transition for trigger '{trigger}' from state '{instance.current_state}'"
+        )
+
+    @staticmethod
+    def _evaluate_conditions(conditions: list[Condition], context: dict[str, Any]) -> bool:
+        """Check all conditions against the instance context."""
+        return all(context.get(c.field) == c.value for c in conditions)

msaas_workflow_engine-0.1.0/src/workflow_engine/hooks.py

@@ -0,0 +1,141 @@
+"""Hook registry for workflow lifecycle callbacks."""
+
+from __future__ import annotations
+
+import enum
+import inspect
+import logging
+from collections import defaultdict
+from typing import Any, Callable
+
+from workflow_engine.models import WorkflowInstance
+
+logger = logging.getLogger(__name__)
+
+HookCallback = Callable[..., Any]
+
+
+class HookType(str, enum.Enum):
+    """Categories of lifecycle hooks."""
+
+    ON_ENTER = "on_enter"
+    ON_EXIT = "on_exit"
+    ON_TRANSITION = "on_transition"
+
+
+class HookRegistry:
+    """Registry for sync and async callbacks on workflow lifecycle events.
+
+    Hooks are keyed by ``(hook_type, name)`` where *name* is the hook label
+    defined in the workflow definition (e.g. ``"send_notification"``).
+
+    Error isolation: if a hook raises, the error is logged and the
+    remaining hooks plus the transition continue uninterrupted.
+    """
+
+    def __init__(self) -> None:
+        self._hooks: dict[tuple[HookType, str], list[HookCallback]] = defaultdict(list)
+
+    def register(
+        self,
+        hook_type: HookType,
+        name: str,
+        callback: HookCallback,
+    ) -> None:
+        """Register a callback for a specific hook type and name.
+
+        Args:
+            hook_type: When the hook fires (enter, exit, transition).
+            name: Hook name matching the definition's on_enter/on_exit/actions.
+            callback: Sync or async callable receiving the workflow instance.
+        """
+        self._hooks[(hook_type, name)].append(callback)
+
+    def on_enter(self, name: str) -> Callable[[HookCallback], HookCallback]:
+        """Decorator to register an on_enter hook."""
+
+        def decorator(fn: HookCallback) -> HookCallback:
+            self.register(HookType.ON_ENTER, name, fn)
+            return fn
+
+        return decorator
+
+    def on_exit(self, name: str) -> Callable[[HookCallback], HookCallback]:
+        """Decorator to register an on_exit hook."""
+
+        def decorator(fn: HookCallback) -> HookCallback:
+            self.register(HookType.ON_EXIT, name, fn)
+            return fn
+
+        return decorator
+
+    def on_transition(self, name: str) -> Callable[[HookCallback], HookCallback]:
+        """Decorator to register an on_transition hook."""
+
+        def decorator(fn: HookCallback) -> HookCallback:
+            self.register(HookType.ON_TRANSITION, name, fn)
+            return fn
+
+        return decorator
+
+    async def execute(
+        self,
+        hook_type: HookType,
+        name: str,
+        instance: WorkflowInstance,
+    ) -> list[Exception]:
+        """Execute all callbacks for the given hook type and name.
+
+        Args:
+            hook_type: The lifecycle event.
+            name: The hook name.
+            instance: Current workflow instance (passed to callbacks).
+
+        Returns:
+            List of exceptions raised by callbacks (empty on full success).
+        """
+        callbacks = self._hooks.get((hook_type, name), [])
+        errors: list[Exception] = []
+
+        for cb in callbacks:
+            try:
+                result = cb(instance)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:
+                logger.error(
+                    "Hook %s:%s failed: %s",
+                    hook_type.value,
+                    name,
+                    exc,
+                    exc_info=True,
+                )
+                errors.append(exc)
+
+        return errors
+
+    async def execute_many(
+        self,
+        hook_type: HookType,
+        names: list[str],
+        instance: WorkflowInstance,
+    ) -> list[Exception]:
+        """Execute hooks for multiple names sequentially.
+
+        Args:
+            hook_type: The lifecycle event.
+            names: List of hook names to execute in order.
+            instance: Current workflow instance.
+
+        Returns:
+            Aggregated list of exceptions from all hooks.
+        """
+        all_errors: list[Exception] = []
+        for name in names:
+            errors = await self.execute(hook_type, name, instance)
+            all_errors.extend(errors)
+        return all_errors
+
+    def clear(self) -> None:
+        """Remove all registered hooks."""
+        self._hooks.clear()