Metadata-Version: 2.4
Name: kaggle-ckpt
Version: 0.1.0
Summary: Production checkpoint management for Kaggle and ephemeral training environments
Author-email: "Md.Nahin Alam" <nahin.alam@northsouth.edu>
License: MIT
Project-URL: Homepage, https://github.com/alamnahin/kaggle-ckpt
Project-URL: Repository, https://github.com/alamnahin/kaggle-ckpt
Project-URL: Issues, https://github.com/alamnahin/kaggle-ckpt/issues
Keywords: kaggle,checkpoint,pytorch,machine-learning,training
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=1.10.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# kaggle-ckpt

Production checkpoint management for Kaggle and other ephemeral training environments.

Kaggle notebooks wipe `/kaggle/temp` between sessions and cap `/kaggle/working` at
roughly 20 GB. `kaggle-ckpt` handles the lifecycle for you: fast atomic saves during
training, configurable retention so you don't blow the disk quota, and a single call
at the end to promote your best model (plus metrics, logs, and config) into persistent
storage.

## Features

- Automatic `/kaggle/temp` (fast, ephemeral) → `/kaggle/working` (persistent) promotion
- Atomic saves via PID-scoped temp files, so a crash mid-write never corrupts a checkpoint
- Configurable retention: keep the best, the last, and/or the last N periodic checkpoints
- Exponential Moving Average (EMA) of model weights, with serialization built in
- Robust state-dict loading that auto-handles `DataParallel`'s `module.` prefix
- Kaggle / Colab / local environment auto-detection with local fallback paths
- Framework-agnostic: works with raw PyTorch, Lightning, Hugging Face, etc.

## Install

```bash
pip install kaggle-ckpt
```

## Quickstart

```python
from kaggle_ckpt import CheckpointManager, CheckpointConfig

cfg = CheckpointConfig("my_experiment", monitor="val_macro_f1", mode="max")
ckpt = CheckpointManager(cfg)

for epoch in range(1, num_epochs + 1):
    train_metrics = train_one_epoch(...)
    val_metrics = validate(...)

    state = {
        "epoch": epoch,
        "model": model.state_dict(),
        "optimizer": optimizer.state_dict(),
    }
    ckpt.save_epoch(epoch, state, metrics=val_metrics)

# At the end of training, promote everything to /kaggle/working
ckpt.copy_final_artifacts(
    metrics=test_metrics,
    train_log=ckpt.metrics.get_history(),
    class_names=class_names,
    config_dict=config,
)
```

## Loading a checkpoint later

```python
from kaggle_ckpt import CheckpointManager, CheckpointConfig

ckpt = CheckpointManager(CheckpointConfig("my_experiment"))
checkpoint = ckpt.load_best()
ckpt.load_model_weights(model, checkpoint=checkpoint, use_ema=True)
```

## EMA

```python
from kaggle_ckpt import EMA

ema = EMA(model, decay=0.9998)

for step in training_loop:
    optimizer.step()
    ema.update()

ema.apply_shadow()
validate(model)
ema.restore()
```

## License

MIT
