Metadata-Version: 2.4
Name: novastack-workflows
Version: 2.0.1
Summary: A workflow engine to run AI applications with event-driven, stepwise control.
Project-URL: Repository, https://github.com/novastack-project/novastack/tree/main/novastack-workflows
Author-email: Leonardo Furnielis <leonardofurnielis@outlook.com>
License: Apache-2.0
License-File: LICENSE
Keywords: AI,LLM,QA,RAG,data,retrieval,semantic-search,workflows
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: httpx<1.0.0,>=0.28.1; extra == 'dev'
Requires-Dist: novastack-utils<3.0.0,>=1.0.0; extra == 'dev'
Requires-Dist: pyright<1.2.0,>=1.1.409; 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'
Provides-Extra: prebuilt
Requires-Dist: novastack-core<2.0.0,>=1.1.8; extra == 'prebuilt'
Provides-Extra: server
Requires-Dist: fastapi<1.0.0,>=0.136.3; extra == 'server'
Requires-Dist: uvicorn[standard]<1.0.0,>=0.48.0; extra == 'server'
Description-Content-Type: text/markdown

<div align="center">
  <img alt="Novastack workflows Logo" src=".github/images/logo-light.png" width="50%">
</div>

<div align="center">
  <h3>A powerful and flexible event-driven workflow engine for Python, designed to build complex asynchronous workflows with ease.</h3>
</div>

<div align="center">
  <img src="https://img.shields.io/pypi/v/novastack-workflows" alt="PyPI - Version">
  <img src="https://github.com/novastack-project/novastack-workflows/actions/workflows/test.yml/badge.svg" alt="Testing">
  <img
    src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"
    alt="Ruff">
  <img src="https://img.shields.io/pepy/dt/novastack-workflows" alt="Pepy Total Downloads">
  <img src="https://img.shields.io/pypi/l/novastack-workflows" alt="PyPI - License">
</div>

## 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
from novastack_workflows.events import Event, StartEvent, StopEvent


class MessageEvent(Event):
    message: str

class MyWorkflow(Workflow):

    @step(depends_on=StartEvent)
    async def start(self, ctx: Context, ev: StartEvent) -> MessageEvent:
        
        input_msg = ev.get("message", "")
        return MessageEvent(message=f"Processed: {input_msg}")

    @step(depends_on=MessageEvent)
    async def process(self, ctx: Context, ev: MessageEvent) -> StopEvent:
        return StopEvent(result=ev.message)


async def main():
    workflow = MyWorkflow()
    result = await workflow.run(input_msg="Hello, World!")

    print(result)
```

## Core Concepts

### 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.

### Steps

Steps are asynchronous methods decorated with `@step(depends_on=EventType)` that define what happens when a specific event is received.

- Steps receive a `Context` and an `Event`.
- Steps can return new events to trigger subsequent steps.

### 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`

### Context

The `Context` object provides access to workflow state and allows steps to share data throughout the workflow execution.

```python
# Read-only access
current_value = ctx.state.count

# Edit state
async with ctx.store.edit_state() as state:
    state.count = current_counter + 1

# Send events
ctx.send_event(MyEvent(...))
```
## Features

| Feature                | Novastack Workflows     |
| ---------------------- | ----------------------- |
| Event-driven execution | ✅                       |
| Fan-out (parallelism)  | ✅                       |
| Async execution        | ✅                       |
| Shared state           | ✅                       |
| Event joins            | ✅                       |
| Internal buffer.       | ✅                       |
| Declarative API        | ✅                       |

## License

Apache License 2.0
