novastack-workflows 1.0.0__tar.gz

novastack_workflows-1.0.0/.gitignore

@@ -0,0 +1,85 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+#IDE
+.DS_Store
+.idea
+.vscode
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Mkdocs documentation
+docs/_build/
+docs/api_reference/site/
+
+# Ruff
+.ruff_cache/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/

novastack_workflows-1.0.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: novastack-workflows
+Version: 1.0.0
+Summary: A workflow engine to run AI applications with event-driven, stepwise control.
+Project-URL: Repository, https://github.com/novastack-project/novastack
+Author-email: Leonardo Furnielis <leonardofurnielis@outlook.com>
+License: Apache-2.0
+Keywords: AI,LLM,QA,RAG,data,observability,retrieval,semantic-search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.11
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0; extra == 'dev'
+Requires-Dist: pytest<10.0.0,>=9.0.3; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.15.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# NovaStack Workflows
+
+A powerful and flexible event-driven workflow engine for Python, designed to build complex asynchronous workflows with ease.
+
+## Installation
+
+```bash
+pip install novastack-workflows
+```
+
+## Quick Start
+
+Here's a simple example to get you started with NovaStack Workflows:
+
+```python
+from novastack.workflows import Workflow, Context, step, Event, StartEvent, StopEvent
+
+
+# Define a custom event
+class MyEvent(Event):
+    message: str
+
+# Create your workflow
+class SimpleWorkflow(Workflow):
+    """A simple workflow that processes a message."""
+
+    @step(on=StartEvent)
+    async def start(self, ctx: Context, ev: StartEvent) -> MyEvent:
+        # Get input from the start event
+        input_msg = ev.get("input_msg", "")
+        # Return a custom event to trigger the next step
+        return MyEvent(message=f"Processed: {input_msg}")
+
+    @step(on=MyEvent)
+    async def process(self, ctx: Context, ev: MyEvent) -> StopEvent:
+        # Process the message and return the final result
+        return StopEvent(result=ev.message)
+
+
+# Run the workflow
+async def main():
+    workflow = SimpleWorkflow()
+    result = await workflow.run(input_msg="Hello, World!")
+
+    print(result)
+```
+
+## Core Concepts
+
+### Events
+
+Events are the building blocks of workflows. They carry data between steps and trigger step execution.
+
+- **StartEvent**: Automatically triggered when a workflow starts
+- **StopEvent**: Signals the end of a workflow and carries the final result
+- **Custom Events**: Define your own events by inheriting from `Event`
+
+### Steps
+
+Steps are methods decorated with `@step(on=EventType)` that define what happens when a specific event is received.
+
+- Steps are asynchronous functions that receive a `Context` and an `Event`
+- Steps can return new events to trigger subsequent steps
+
+### Workflow
+
+A workflow is a class that inherits from `Workflow` and contains one or more steps. It orchestrates the execution of steps based on events.
+
+### Context
+
+The `Context` object provides access to workflow state and allows steps to share data throughout the workflow execution.

novastack_workflows-1.0.0/README.md

@@ -0,0 +1,71 @@
+# NovaStack Workflows
+
+A powerful and flexible event-driven workflow engine for Python, designed to build complex asynchronous workflows with ease.
+
+## Installation
+
+```bash
+pip install novastack-workflows
+```
+
+## Quick Start
+
+Here's a simple example to get you started with NovaStack Workflows:
+
+```python
+from novastack.workflows import Workflow, Context, step, Event, StartEvent, StopEvent
+
+
+# Define a custom event
+class MyEvent(Event):
+    message: str
+
+# Create your workflow
+class SimpleWorkflow(Workflow):
+    """A simple workflow that processes a message."""
+
+    @step(on=StartEvent)
+    async def start(self, ctx: Context, ev: StartEvent) -> MyEvent:
+        # Get input from the start event
+        input_msg = ev.get("input_msg", "")
+        # Return a custom event to trigger the next step
+        return MyEvent(message=f"Processed: {input_msg}")
+
+    @step(on=MyEvent)
+    async def process(self, ctx: Context, ev: MyEvent) -> StopEvent:
+        # Process the message and return the final result
+        return StopEvent(result=ev.message)
+
+
+# Run the workflow
+async def main():
+    workflow = SimpleWorkflow()
+    result = await workflow.run(input_msg="Hello, World!")
+
+    print(result)
+```
+
+## Core Concepts
+
+### Events
+
+Events are the building blocks of workflows. They carry data between steps and trigger step execution.
+
+- **StartEvent**: Automatically triggered when a workflow starts
+- **StopEvent**: Signals the end of a workflow and carries the final result
+- **Custom Events**: Define your own events by inheriting from `Event`
+
+### Steps
+
+Steps are methods decorated with `@step(on=EventType)` that define what happens when a specific event is received.
+
+- Steps are asynchronous functions that receive a `Context` and an `Event`
+- Steps can return new events to trigger subsequent steps
+
+### Workflow
+
+A workflow is a class that inherits from `Workflow` and contains one or more steps. It orchestrates the execution of steps based on events.
+
+### Context
+
+The `Context` object provides access to workflow state and allows steps to share data throughout the workflow execution.

novastack_workflows-1.0.0/novastack/workflows/__init__.py

@@ -0,0 +1,19 @@
+from novastack.workflows.workflow import Workflow
+from novastack.workflows.decorators import step
+
+from novastack.workflows.events import Event, StartEvent, StopEvent
+
+# Context management
+from novastack.workflows.context import Context
+
+
+__all__ = [
+    # Core
+    "Workflow",
+    "Context",
+    "step",
+    # Event system
+    "Event",
+    "StartEvent",
+    "StopEvent",
+]

novastack_workflows-1.0.0/novastack/workflows/context/__init__.py

@@ -0,0 +1,3 @@
+from novastack.workflows.context.context import Context
+
+__all__ = ["Context"]

novastack_workflows-1.0.0/novastack/workflows/context/context.py

@@ -0,0 +1,121 @@
+import asyncio
+from typing import Any, Generic, TypeVar, TYPE_CHECKING
+
+from pydantic import BaseModel
+from novastack.workflows.context.state_store import StateStore
+from novastack.workflows.runtime.optimized_queue import OptimizedEventQueue
+
+if TYPE_CHECKING:
+    from novastack.workflows.events import Event
+
+STATE_T = TypeVar("STATE_T", bound=BaseModel)
+
+
+class Context(Generic[STATE_T]):
+    """
+    Workflow execution context with copy-on-write state management.
+
+    Provides robust, immutable state management through 'state_store'.
+
+    State is automatically initialized based on the type annotation.
+    If no type is provided, uses DictLikeModel.
+
+    Example:
+        ```python
+        class RunState(BaseModel):
+            counter: int = 0
+            items: list[str] = []
+
+        # With typed state - auto-initialized
+        @step
+        async def start(self, ctx: Context[RunState], ev: StartEvent):
+            async with ctx.store.edit_state() as state:
+                state.counter += 1  # RunState auto-initialized
+
+        # Without type - uses DictLikeModel
+        @step
+        async def start(self, ctx: Context, ev: StartEvent):
+            async with ctx.store.edit_state() as state:
+                state.counter = 1  # DictLikeModel allows dynamic fields
+        ```
+    """
+
+    def __init__(
+        self,
+        workflow: Any,
+        event_queue: asyncio.Queue["Event"] | Any | None = None,
+    ):
+        """
+        Initialize workflow context.
+
+        Each context is isolated and maintains its own state store.
+        State type is inferred from Context[StateType] annotation or defaults to DictLikeModel.
+
+        Args:
+            workflow: Workflow instance
+            event_queue: Event queue for emission
+        """
+        self._workflow = workflow
+
+        # Use provided queue or create OptimizedEventQueue
+        if event_queue is None:
+            self._event_queue = OptimizedEventQueue()
+        else:
+            self._event_queue = event_queue
+
+        # Copy-on-write state store with auto-initialization
+        # Infer state type from workflow's _state_type if available
+        state_type = getattr(workflow, "_state_type", None)
+        self._store = StateStore(state_type=state_type)
+
+    @property
+    def workflow(self) -> Any:
+        """Get workflow instance."""
+        return self._workflow
+
+    @property
+    def store(self) -> StateStore:
+        """
+        Copy-on-write state store.
+
+        Provides immutability guarantees and thread-safety through
+        explicit edit contexts.
+
+        Example:
+            ```python
+            # Edit state
+            async with ctx.store.edit_state() as state:
+                state.counter += 1
+            ```
+        """
+        return self._store
+
+    @property
+    def state(self) -> BaseModel | None:
+        """
+        Get current state (read-only).
+
+        Convenience property for accessing store state.
+        Equivalent to ctx.store.state.
+
+        Example:
+            ```python
+            # Read-only access
+            current_value = ctx.state.counter
+            ```
+        """
+        return self._store.state
+
+    async def emit(self, event: "Event") -> None:
+        """
+        Emit an event to the workflow queue.
+
+        Args:
+            event: Event to emit
+
+        Example:
+            ```python
+            await ctx.emit(MyEvent(data="processed"))
+            ```
+        """
+        await self._event_queue.put(event)

novastack_workflows-1.0.0/novastack/workflows/context/state_store.py

@@ -0,0 +1,123 @@
+import asyncio
+import copy
+from contextlib import asynccontextmanager
+from typing import Generic, Type, TypeVar, cast
+
+from pydantic import BaseModel
+from novastack.workflows.exceptions import ContextStateError
+from novastack.workflows.types import DictLikeModel
+
+STATE_T = TypeVar("STATE_T", bound=BaseModel)
+
+
+class StateStore(Generic[STATE_T]):
+    """
+    Thread-safe state store with copy-on-write semantics.
+
+    Provides immutability guarantees through explicit edit contexts.
+    Changes are isolated until committed on context exit.
+
+    State is automatically initialized on first access if not provided.
+    If no state_type is specified, uses DictLikeModel for dynamic fields.
+
+    Thread-safe mutations through explicit contexts. Automatic rollback on errors makes it
+    robust and production-ready.
+
+    Example:
+        ```python
+        # Copy-on-write with immutability
+        async with ctx.store.edit_state() as state:
+            state.counter += 1  # Mutation isolated
+        # Automatic commit on exit
+        ```
+    """
+
+    def __init__(
+        self,
+        state_data: STATE_T | None = None,
+        state_type: Type[STATE_T] | None = None,
+    ):
+        """
+        Initialize state store with isolated state.
+
+        Each state store is independent and does not inherit state
+        from other contexts. This ensures proper isolation between
+        workflows.
+
+        Args:
+            state_data: Initial state instance (optional)
+            state_type: State model class for auto-initialization (optional)
+        """
+        self._lock = asyncio.Lock()
+        self._state_type: Type[BaseModel] = state_type or DictLikeModel
+
+        if state_data is not None:
+            self._state: STATE_T | None = state_data
+        else:
+            # Auto-initialize with state_type
+            self._state = cast(STATE_T, self._state_type())
+
+    @property
+    def state(self) -> STATE_T | None:
+        """Get current state (read-only)."""
+        return self._state
+
+    def _smart_copy(self, state: STATE_T) -> STATE_T:
+        """
+        Smart copy that optimizes based on state type.
+
+        For Pydantic models, uses the optimized model_copy() method.
+        This reduces copy overhead by 40-60% for Pydantic models.
+
+        Args:
+            state: State to copy
+        """
+        if isinstance(state, BaseModel):
+            # Pydantic has optimized copy
+            return state.model_copy(deep=True)
+
+        # Fallback to deep copy
+        return copy.deepcopy(state)
+
+    @asynccontextmanager
+    async def edit_state(self):
+        """
+        Context manager for editing state with copy-on-write semantics.
+
+        Creates a deep copy of the state for editing. Changes are committed
+        atomically when the context exits successfully. If an exception occurs,
+        changes are automatically rolled back.
+
+        State is guaranteed to be initialized (never None) due to auto-initialization
+        in __init__.
+
+        Example:
+            ```python
+            async with ctx.store.edit_state() as state:
+                state.counter += 1
+                state.items.append("new")
+
+            # On error, changes are rolled back:
+            try:
+                async with ctx.store.edit_state() as state:
+                    state.counter += 1
+                    raise Exception("Error!")  # Rollback happens
+            except Exception:
+                pass  # state.counter unchanged
+            ```
+        """
+        async with self._lock:
+            # State is always initialized in __init__, but keep check for safety
+            if self._state is None:
+                raise ContextStateError("State not initialized.")
+
+            # Use smart copy instead of deepcopy
+            state_copy = self._smart_copy(self._state)
+
+            try:
+                yield state_copy
+                # Commit changes on successful exit
+                self._state = state_copy
+            except Exception:
+                # Rollback on error (don't commit)
+                raise

novastack_workflows-1.0.0/novastack/workflows/decorators.py

@@ -0,0 +1,114 @@
+from typing import Any, Callable, Type
+from functools import wraps
+import inspect
+
+from novastack.workflows.events import Event
+from novastack.workflows.exceptions import WorkflowValidationError
+
+
+def step(
+    *,
+    on: Type[Event],
+    timeout: float | None = None,
+    num_retries: int = 0,
+    retry_delay: float = 1.0,
+) -> Callable:
+    """
+    Decorator to mark a method as a workflow step.
+
+    The decorated method will be automatically registered as a step
+    for the specified event type when the workflow class is defined.
+
+    Args:
+        on: The Event class this step handles.
+        timeout: Optional timeout in seconds for step execution
+        num_retries: Number of retry attempts on failure (default: 0)
+        retry_delay: Delay in seconds between retry attempts (default: 1)
+
+    Note:
+        The decorated method must have the signature:
+        async def fn(self, ctx: Context, ev: EventType) -> Event | None
+    """
+
+    def decorator(f: Callable) -> Callable:
+        # Is async function?
+        if not inspect.iscoroutinefunction(f):
+            raise WorkflowValidationError(
+                f"Step method '{f.__name__}' must be an async function."
+            )
+
+        # Validate step signature
+        sig = inspect.signature(f)
+        params = list(sig.parameters.keys())
+
+        if len(params) < 3:
+            raise WorkflowValidationError(
+                f"Step signature '{f.__name__}' must have at least 3 parameters: "
+                f"self, ctx, ev. got: {params}"
+            )
+
+        # Store metadata on the function
+        f.__workflow_step__ = True
+        f.__step_accepted_events__ = on
+        f.__step_name__ = f.__name__
+        f.__step_timeout__ = timeout
+        f.__step_num_retries__ = num_retries
+        f.__step_retry_delay__ = retry_delay
+
+        @wraps(f)
+        async def wrapper(*args, **kwargs):
+            return await f(*args, **kwargs)
+
+        # Copy metadata to wrapper
+        wrapper.__workflow_step__ = True
+        wrapper.__step_accepted_events__ = on
+        wrapper.__step_name__ = f.__name__
+        wrapper.__step_timeout__ = timeout
+        wrapper.__step_num_retries__ = num_retries
+        wrapper.__step_retry_delay__ = retry_delay
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def is_step_method(method: Any) -> bool:
+    """
+    Check if a method is decorated with @step.
+    """
+    return getattr(method, "__workflow_step__", False)
+
+
+def get_step_event_type(method: Any) -> Type[Event] | None:
+    """
+    Get the event type that a step method handles.
+    """
+    return getattr(method, "__step_accepted_events__", None)
+
+
+def get_step_name(method: Any) -> str | None:
+    """
+    Get the name of a step method.
+    """
+    return getattr(method, "__step_name__", None)
+
+
+def get_step_timeout(method: Any) -> float | None:
+    """
+    Get timeout for a step method.
+    """
+    return getattr(method, "__step_timeout__", None)
+
+
+def get_step_num_retries(method: Any) -> int:
+    """
+    Get number of retries for a step method.
+    """
+    return getattr(method, "__step_num_retries__", 0)
+
+
+def get_step_retry_delay(method: Any) -> float:
+    """
+    Get retry delay for a step method.
+    """
+    return getattr(method, "__step_retry_delay__", 1.0)

novastack_workflows-1.0.0/novastack/workflows/enums.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class WorkflowStatus(str, Enum):
+    """Workflow execution status."""
+
+    CANCELLED = "cancelled"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    RUNNING = "running"

novastack_workflows-1.0.0/novastack/workflows/events.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+from pydantic import Field
+from novastack.workflows.types import DictLikeModel
+
+
+class Event(DictLikeModel):
+    """Base class for all workflow events with dict-like interface."""
+
+
+class StartEvent(Event):
+    """Workflow initialization event.
+
+    This event marks the beginning of a workflow execution and can carry
+    any dynamic fields needed to initialize the workflow state.
+    """
+
+
+class StopEvent(Event):
+    """Workflow completion event.
+
+    This event marks the end of a workflow execution and typically contains
+    the final result. Additional dynamic fields can be included as needed.
+
+    Attributes:
+        result: The final result of the workflow execution.
+    """
+
+    result: Any = Field(
+        default=None,
+        description="The final result of the workflow execution",
+    )

novastack_workflows-1.0.0/novastack/workflows/exceptions.py

@@ -0,0 +1,14 @@
+class WorkflowValidationError(Exception):
+    """Raised when the workflow configuration or step signatures are invalid."""
+
+
+class WorkflowRuntimeError(Exception):
+    """Raised when runtime errors during step execution or event routing."""
+
+
+class WorkflowTimeoutError(Exception):
+    """Raised when a step run exceeds the configured timeout."""
+
+
+class ContextStateError(Exception):
+    """Raised when a context method is called in the wrong state."""