# Installation

Flokkit Flow has zero runtime dependencies and supports Python 3.8+.

## From PyPI

```bash
pip install flokkit-flow
```

Or using [uv](https://github.com/astral-sh/uv) (recommended):

```bash
uv pip install flokkit-flow
```

## From Source

### Using Git

```bash
# Clone the repository
git clone https://gitlab.com/flokkit/flow.git
cd flow

# Install in editable mode
pip install -e .
```

### For Development

If you want to contribute or run tests:

```bash
# Clone the repository
git clone https://gitlab.com/flokkit/flow.git
cd flow

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev]"
```

Or using uv (recommended):

```bash
# Clone the repository
git clone https://gitlab.com/flokkit/flow.git
cd flow

# Create virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```

## Using just

The project includes a `justfile` for common development tasks:

```bash
# Install just (macOS)
brew install just

# Set up development environment
just bootstrap
just install-dev

# Run tests
just test

# Run type checking
just typecheck

# Run examples
just example      # List all examples
just example 1    # Run specific example
```

## Verify Installation

```python
import flow
from flow import flow

# Create a simple flow to test
builder = flow("Test Flow")
print("Flokkit Flow is installed successfully!")
```

## Optional Dependencies

While Flokkit Flow has zero runtime dependencies, you may want to install additional packages for development:

- **Testing**: `pytest`, `pytest-asyncio`
- **Type Checking**: `basedpyright`
- **Documentation**: `sphinx`, `sphinx-rtd-theme`

Install all development dependencies:

```bash
pip install -e ".[dev,docs]"
```

## System Requirements

- Python 3.8 or higher
- No additional system dependencies
- Works on Linux, macOS, and Windows

## Troubleshooting

### Import Error

If you get an import error, make sure:
1. You've activated your virtual environment
2. Flokkit Flow is installed (`pip list | grep flokkit-flow`)
3. You're not in the flokkit-flow source directory when importing

### Type Checking

For the best development experience, we recommend using a type checker:

```bash
# Install basedpyright
pip install basedpyright

# Run type checking
basedpyright
```

### Performance

Flokkit Flow is built on Python's asyncio and is designed for I/O-bound workloads. For CPU-intensive tasks, consider:
- Using the `is_blocking=True` parameter on transforms
- Implementing custom thread pool executors
- Breaking work into smaller chunks