Metadata-Version: 2.4
Name: rivlet
Version: 0.2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Summary: Explicit, composable workflows with a Python API and a Rust execution core
Keywords: dag,workflow,task-graph,concurrency,rust
Author: ririv
License-Expression: MIT
Requires-Python: >=3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/ririv/rivlet/blob/main/docs/index.md
Project-URL: Homepage, https://github.com/ririv/rivlet
Project-URL: Issues, https://github.com/ririv/rivlet/issues
Project-URL: Repository, https://github.com/ririv/rivlet

# Rivlet

English | [简体中文](https://github.com/ririv/rivlet/blob/main/README.zh-CN.md)

Rivlet is an explicit, composable DAG declaration and execution library
with a Python API and a Rust execution core.

It provides steps, subgraphs, conditional dependencies, thread-based and async
execution, result access, execution state, and graph rendering. Logging, terminal
integration, and request-level control belong to the host application and are
connected through explicit interfaces.

## When to use it

- Compose build or automation tasks with explicit dependencies.
- Run independent data-processing or validation tasks concurrently, then join them.
- Reuse subgraphs inside a larger workflow while keeping execution observable.

This is an in-process task graph library, not a distributed workflow service.
Your application owns the actions and integration; the library handles dependency
ordering and execution state.

## Architecture

On `main`, Rust implements declaration compilation, execution-graph validation,
and the scheduling state machine. Python retains graph declarations, arbitrary
callables, result objects, and host integration. Complete Rust-native subgraphs
can join the same execution graph and concurrency budget.

See [Rust architecture](https://github.com/ririv/rivlet/blob/main/docs/rust-architecture.md) for implementation boundaries.

## Local development

Install the published package with `pip install rivlet`. The Python import name
is also `rivlet`; there is no `rivetoo_graph` compatibility package.
See [release policy](https://github.com/ririv/rivlet/blob/main/docs/releasing.md) for wheel coverage and publishing.

You need Python 3.13 or later, a Rust toolchain, and maturin. With a virtual
environment activated, install the native extension into that environment:

```bash
maturin develop
```

The native extension is required. There is no pure-Python execution fallback.

## Quick example

```python
from rivlet import GraphExecution, Step, ThreadGraphRunOptions

prepare = Step(lambda: print("prepare"), label="prepare")
validate = Step(lambda: print("validate"), label="validate")
test = Step(lambda: print("test"), label="test")
finish = Step(lambda: print("finish"), label="finish")

checks = (validate | test).graph(label="checks")
graph = (prepare >> checks >> finish).graph(label="example")
GraphExecution(graph=graph).run(ThreadGraphRunOptions(workers=2))
```

After `prepare`, the `checks` subgraph can run `validate` and `test` concurrently.
`finish` waits for both to succeed; their print order is not guaranteed.

`>>` declares ordering; `|` composes independent branches. Run options determine
actual concurrency. An ordinary action failure blocks dependent work while
unrelated branches continue; the run ultimately reports the failures.

See the [documentation](https://github.com/ririv/rivlet/blob/main/docs/index.md) for the model, composition API, and execution rules.

## License

This project is licensed under the [MIT License](https://github.com/ririv/rivlet/blob/main/LICENSE).

