Metadata-Version: 2.5
Name: parakeet-workflows
Version: 0.1.0
Summary: High performance and flexible event-driven workflow engine.
Project-URL: Repository, https://github.com/parakeet-project/parakeet/tree/main/parakeet-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: parakeet-index-instrumentation<0.2.0,>=0.1.0
Requires-Dist: parakeet-index-utils<0.2.0,>=0.1.0
Requires-Dist: pydantic<3.0.0,>=2.13.4
Provides-Extra: dev
Requires-Dist: httpx<1,>=0.28.1; extra == 'dev'
Requires-Dist: pyright<1.2.0,>=1.1.411; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=1.4.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=9.1.1; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.15.20; extra == 'dev'
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.139.0; extra == 'server'
Requires-Dist: uvicorn[standard]<1,>=0.51.0; extra == 'server'
Description-Content-Type: text/markdown

<div align="center">
  <img alt="Parakeet Logo" src=".github/images/favicon.png" width="80px">
  <h2>🦜🔀 Parakeet Workflows</h2>
  <p><strong>High performance and flexible event-driven workflow engine, designed to build complex tasks.</strong></p>
</div>

<div align="center">
  <img src="https://github.com/parakeet-project/parakeet-workflows/actions/workflows/test.yml/badge.svg" alt="Testing">
  <img src="https://img.shields.io/pypi/v/parakeet-workflows?style=flat&colorA=black&colorB=black" alt="PyPI - Version">
  <a href="https://pepy.tech/projects/parakeet-workflows"><img src="https://static.pepy.tech/personalized-badge/parakeet-workflows?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLACK" alt="Downloads"></a>
  <img src="https://img.shields.io/pypi/l/parakeet-workflows?style=flat&colorA=black&colorB=black" alt="PyPI - License">
  <img
    src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"
    alt="Ruff">
</div>

## ✨ Highlight features

- **Event-driven execution** — Steps communicate through typed events.
- **Fan-out / Fan-in** — Emit multiple events in parallel and join results back, with full async support.
- **Shared state** — Pass data across steps via a built-in `Context` object without global variables.
- **Internal buffer** — Events are queued internally, so steps can produce and consume at their own pace.
- **Declarative API** — Define steps with a simple `@step` decorator.
- **Built-in observability** — Instrument workflows with OpenTelemetry-compatible tracing and custom metrics.

## 📦 Installation

```bash
pip install parakeet-workflows
```

With [uv](https://docs.astral.sh/uv/):

```bash
uv add parakeet-workflows
```

## 🚀 Quickstart

Here's a simple example to get you started with Parakeet Workflows:

```python
import asyncio
from parakeet_workflows import Workflow, Context, step
from parakeet_workflows.events import Event, StartEvent, StopEvent


class MessageEvent(Event):
    message: str

class MyWorkflow(Workflow):

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

    @step(when=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)

asyncio.run(main())
```

## 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(when=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(...))
```

## Server

Parakeet Workflows includes an optional HTTP server built on FastAPI that exposes your workflows as REST endpoints.

```python
import asyncio
from parakeet_workflows.server import WorkflowServer

server = WorkflowServer()
server.add_workflow("my-workflow", MyWorkflow())

asyncio.run(server.serve(host="0.0.0.0", port=8080))
```

| Endpoint | Description |
| :--- | :--- |
| `GET /workflows` | List all registered workflows |
| `POST /workflows/{id}/run` | Execute a workflow |

## License

[Apache License 2.0](LICENSE)
