README.md

xcl-lens
========

RCCL/NCCL log parser and analyzer.

## Installation

### From PyPI

#### Using pipx (recommended for CLI use)

```bash
pipx install xcl-lens
```

#### Using uv

```bash
uv tool install xcl-lens
```

#### Using pip

```bash
pip install xcl-lens
```

### From Source

#### Using pipx

```bash
pipx install .
```

#### Using uv

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

# Or using uv's native install
uv tool install .
```

#### Using pip

```bash
pip install -e .
```

## Usage

### As a Wrapper

```bash
mpirun -np 4 xcl-lens \
    ./build/all_reduce_perf -b 4 -e 2G -f 2 -w 3 -n 3 -g 1
```

### Process an Existing File

```bash
xcl-lens cat rccl-log.txt
```

### Verbose Mode

By default, only the report is printed. Use `-v` or `--verbose` to also print raw log lines:

```bash
xcl-lens -v ./build/all_reduce_perf -b 4 -e 2G -f 2 -w 3 -n 3 -g 1
```

## Development

```bash
make setup    # Set up development environment
make format   # Auto-fix and format code (ruff)
make lint     # Check code style and errors (ruff)
make test     # Run all unit tests (pytest)
make build    # Build wheel and sdist into dist/
make clean    # Remove build caches and the virtual environment
```