Metadata-Version: 2.4
Name: novastack-workflows
Version: 1.1.0
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: 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

![PyPI - Version](https://img.shields.io/pypi/v/novastack-workflows)
[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
[![Testing](https://github.com/novastack-project/novastack-workflows/actions/workflows/test.yml/badge.svg)](https://github.com/novastack-project/novastack-workflows/actions/workflows/test.yml)
![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)
![Pepy Total Downloads](https://img.shields.io/pepy/dt/novastack-workflows)
![PyPI - License](https://img.shields.io/pypi/l/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
from novastack.workflows.events import Event, StartEvent, StopEvent


class MyEvent(Event):
    message: str

class SimpleWorkflow(Workflow):

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

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


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

    print(result)
```

## Features

| Feature | NovaStack Workflows |
|---------|---------------------|
| Single-event input | ✅ |
| Fan-out (parallelism) | ✅ |
| Async execution | ✅ |
| Event queue | ✅ |
| State (ctx.state) | ✅ |
| Single execution (join) | ✅ |
| Internal buffer | ✅ |
| Declarative | ✅ |


## 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 methods decorated with `@step(depends_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

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