.. Flokkit Flow documentation master file

Welcome to Flokkit Flow
=======================

**Flokkit Flow** is a type-safe, async-first flow-based programming (FBP) framework for Python with zero dependencies.

.. image:: https://img.shields.io/badge/python-3.8+-blue.svg
   :target: https://www.python.org/downloads/
   :alt: Python Version

.. image:: https://img.shields.io/badge/type_checker-basedpyright-blue.svg
   :target: https://github.com/DetachHead/basedpyright
   :alt: Type Checker

.. image:: https://img.shields.io/badge/dependencies-zero-green.svg
   :alt: Zero Dependencies

Key Features
------------

- 🔒 **Type-safe** - Full type safety across the entire flow graph
- ⚡ **Async-first** - Built on asyncio with automatic sync function adaptation  
- 🚦 **Backpressure** - Bounded queues with configurable strategies
- 🔄 **DAG Safety** - Automatic cycle detection prevents deadlocks
- 📦 **Zero Dependencies** - Pure Python, no external packages required
- 🔌 **Lifecycle Hooks** - Proper resource management with init/cleanup
- 💾 **Caching** - Built-in memoization for expensive operations
- 🏭 **Flexible Patterns** - Support for both pipeline and server patterns
- 🎯 **Middleware System** - Extensible processing pipeline with logging, metrics, throttling, and retry support

Quick Example
-------------

.. code-block:: python

   from flow import flow
   import asyncio

   async def main():
       # Build a simple pipeline
       builder = flow("My Pipeline")
       
       def generate_numbers():
           return 42
       
       def double(x):
           return x * 2
       
       def print_result(x):
           print(f"Result: {x}")
       
       # Connect the nodes
       (builder
           .source(generate_numbers, int)
           .transform(double, int)
           .to(print_result))
       
       # Run the pipeline
       await builder.execute(duration=1.0)

   asyncio.run(main())

Table of Contents
-----------------

.. toctree::
   :maxdepth: 2
   :caption: Getting Started

   installation
   quickstart
   concepts

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   guide/basic-usage
   guide/async-programming
   guide/backpressure
   guide/lifecycle
   guide/patterns
   guide/shell-commands
   middleware

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api/core
   api/builder
   api/graph
   api/middleware
   api/nodes
   api/shell

.. toctree::
   :maxdepth: 2
   :caption: Examples

   examples/index
   examples/basic
   examples/advanced
   examples/patterns

.. toctree::
   :maxdepth: 1
   :caption: Development

   contributing
   changelog
   license

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`