Metadata-Version: 2.4
Name: alpinekit
Version: 0.1.0
Summary: An ultralight optimisation tracking package
Author-email: hconnorh <dev@hibble.com>
License: MIT
License-File: LICENCE.md
Keywords: benchmarking,metrics,optimization,performance,tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: numpy>=1.20.0
Requires-Dist: polars>=1.0.0
Requires-Dist: psutil>=5.0.0
Requires-Dist: tqdm>=4.0.0
Provides-Extra: examples
Requires-Dist: ipykernel>=7.1.0; extra == 'examples'
Requires-Dist: multiprocess>=0.70.18; extra == 'examples'
Requires-Dist: nbformat>=5.10.4; extra == 'examples'
Requires-Dist: plotly>=6.5.0; extra == 'examples'
Description-Content-Type: text/markdown

# AlpineKit

An ultralight optimisation tracking package for Python. Track metrics, timing and memory usage with minimal overhead.

## Quick Start

```python
import time
from alpinekit import Metric, Track, history

# Define a metric to track
x_val = Metric("x")

# Track iterations with automatic timing and progress bars
x = 1
for i in Track(range(5)):
    time.sleep(0.1)
    x += x + i
    x_val.add(x)  # Add metric value

# View results as DataFrame
history.df

# View summary statistics
history.summary
```

## Installation

**From PyPI:**

```bash
# Core package
pip install alpinekit

# With examples (optional)
pip install alpinekit[examples]
```

**With uv:**

```bash
# Core package
uv pip install alpinekit

# With examples (optional)
uv pip install alpinekit[examples]
```

**From GitHub source:**

```bash
git clone https://github.com/hconnorh/alpinekit.git
cd alpinekit

# With pip
pip install -e ".[examples]"

# With uv
uv sync --extra examples
source .venv/bin/activate
```

**Requirements:** Python >= 3.13

## Key Features

### **Metric** - Track custom values
- `Metric(name)` - Create a metric tracker
- `.add(value)` - Record a value
- `.add_norm(array)` - Track array norm
- `.add_mem(*arrays)` - Track memory usage

### **Track** - Enhanced iteration tracking
- Automatic progress bars (tqdm)
- CPU time per iteration
- Wall-clock time per iteration
- Memory (RSS) tracking per iteration
- Thread-safe operation

### **History** - Access and analyze results
- `history.df` - Get all metrics as a Polars DataFrame
- `history.summary` - Get statistics (mean, std, min, max) for all metrics
- `history.merge_runs()` - Merge results from parallel runs with `run_id` column

Check out the `examples/` directory for basic usage guides and parallel batch processing examples.

## License

This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.
