readme: update description (#36)

* readme: update description
* examples
* update
* link

Author: Borda

README.md

@@ -1,39 +1,102 @@
-# Lightning Models
+# Effortless Model Management for Your Development ⚡
 
-This package provides utilities for saving and loading machine learning models using PyTorch Lightning. It aims to simplify the process of managing model checkpoints, making it easier to save, load, and share models.
+__Effortless management for your ML models.__
 
-## Features
+<div align="center">
 
-- **Save Models**: Easily save your trained models to cloud storage.
-- **Load Models**: Load pre-trained models for inference or further training.
-- **Checkpoint Management**: Manage multiple checkpoints with ease.
-- **Cloud Integration**: Support for saving and loading models from cloud storage services.
+🚀 [Quick start](#quick-start)
+📦 [Examples](#saving-and-loading-models)
+📚 [Documentation](https://lightning.ai/docs/overview/model-registry)
+💬 [Get help on Discord](https://discord.com/invite/XncpTy7DSt)
+📋 License: Apache 2.0
 
-[![CI testing](https://github.com/Lightning-AI/models/actions/workflows/ci-testing.yml/badge.svg?event=push)](https://github.com/Lightning-AI/models/actions/workflows/ci-testing.yml)
-[![General checks](https://github.com/Lightning-AI/models/actions/workflows/ci-checks.yml/badge.svg?event=push)](https://github.com/Lightning-AI/models/actions/workflows/ci-checks.yml)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Lightning-AI/models/main.svg?badge_token=mqheL1-cTn-280Vx4cJUdg)](https://results.pre-commit.ci/latest/github/Lightning-AI/models/main?badge_token=mqheL1-cTn-280Vx4cJUdg)
+</div>
 
-## Installation
+**Lightning Models** is a streamlined toolkit for effortlessly saving, loading, and managing your model checkpoints. Designed to simplify the entire model lifecycle—from training and inference to sharing, deployment, and cloud integration—Lightning Models supports any framework that produces model checkpoints, including but not limited to PyTorch Lightning.
 
-To install the package, you can use `pip`:
+<pre>
+✅ Seamless Model Saving & Loading
+✅ Robust Checkpoint Management
+✅ Cloud Integration Out of the Box
+✅ Versatile Across Frameworks
+</pre>
+
+# Quick start
+
+Install Lightning Models via pip (more installation options below):
 
 ```bash
 pip install -U litmodels
 ```
 
-Or installing from source:
+Or install directly from source:
 
 ```bash
 pip install https://github.com/Lightning-AI/models/archive/refs/heads/main.zip
 ```
 
-## Usage
+## Saving and Loading Models
+
+Lightning Models offers a simple API to manage your model checkpoints.
+Train your model using your preferred framework (our fist examples show `scikit-learn`) and then save your best checkpoint with a single function call.
+
+### Train scikit-learn model and save it
+
+```python
+import joblib
+from sklearn import datasets, model_selection, svm
+from litmodels import upload_model
+
+# Unique model identifier: <organization>/<teamspace>/<model-name>
+MY_MODEL_NAME = "your_org/your_team/sklearn-svm-model"
+
+# Load example dataset
+iris = datasets.load_iris()
+X, y = iris.data, iris.target
+
+# Split dataset into training and test sets
+X_train, X_test, y_train, y_test = model_selection.train_test_split(
+    X, y, test_size=0.2, random_state=42
+)
+
+# Train a simple SVC model
+model = svm.SVC()
+model.fit(X_train, y_train)
+
+# Upload the saved model using litmodels
+upload_model(model=model, name=MY_MODEL_NAME)
+```
+
+### Download and Load the Model for inference
+
+```python
+import os
+import joblib
+from litmodels import download_model
+
+# Unique model identifier: <organization>/<teamspace>/<model-name>
+MY_MODEL_NAME = "your_org/your_team/sklearn-svm-model"
+
+# Download the model file from cloud storage
+model_path = download_model(name=MY_MODEL_NAME, download_dir="my_models")
+
+# Load the model for inference using joblib
+model = joblib.load(os.path.join("my_models", model_path[0]))
+
+# Example: run inference with the loaded model
+sample_input = [[5.1, 3.5, 1.4, 0.2]]
+prediction = model.predict(sample_input)
+print(f"Prediction: {prediction}")
+```
+
+## Saving and Loading Models with Pytorch Lightning
 
-Here's a simple example of how to save and load a model using `litmodels`. First, you need to train a model using PyTorch Lightning. Then, you can save the model using the `upload_model` function.
+Next examples demonstrate seamless PyTorch Lightning integration with Lightning Models.
+
+### Train a simple Lightning model and save it
 
 ```python
 from lightning import Trainer
-from lightning.pytorch.callbacks import ModelCheckpoint
 from litmodels import upload_model
 from litmodels.demos import BoringModel
 
@@ -59,7 +122,7 @@ checkpoint_path = getattr(trainer.checkpoint_callback, "best_model_path")
 upload_model(model=checkpoint_path, name=MY_MODEL_NAME)
 ```
 
-To load the model, use the `download_model` function.
+### Download and Load the Model for fine-tuning
 
 ```python
 from lightning import Trainer
@@ -87,8 +150,11 @@ trainer = Trainer(max_epochs=4)
 trainer.fit(LitModel(), ckpt_path=checkpoint_path)
 ```
 
-You can also enhance your training with a simple Checkpointing callback which would always save the best model to the cloud storage and continue training.
-This can would be handy especially with long trainings or using interruptible machines so you would always resume/recover from the best model.
+<details>
+    <summary>Advanced Checkpointing Workflow</summary>
+
+Enhance your training process with an automatic checkpointing callback that uploads the best model at the end of each epoch.
+While the example uses PyTorch Lightning callbacks, similar workflows can be implemented in any training loop that produces checkpoints.
 
 ```python
 import os
@@ -132,69 +198,4 @@ trainer.fit(
 )
 ```
 
-## Logging Models
-
-You can also use model store together with [LitLogger](https://github.com/gridai/lit-logger) to log your model to the cloud storage.
-
-```python
-import os
-import lightning as L
-from psutil import cpu_count
-from torch import optim, nn
-from torch.utils.data import DataLoader
-from torchvision.datasets import MNIST
-from torchvision.transforms import ToTensor
-from litlogger import LightningLogger
-
-
-class LitAutoEncoder(L.LightningModule):
-
-    def __init__(self, lr=1e-3, inp_size=28):
-        super().__init__()
-
-        self.encoder = nn.Sequential(
-            nn.Linear(inp_size * inp_size, 64), nn.ReLU(), nn.Linear(64, 3)
-        )
-        self.decoder = nn.Sequential(
-            nn.Linear(3, 64), nn.ReLU(), nn.Linear(64, inp_size * inp_size)
-        )
-        self.lr = lr
-        self.save_hyperparameters()
-
-    def training_step(self, batch, batch_idx):
-        x, y = batch
-        x = x.view(x.size(0), -1)
-        z = self.encoder(x)
-        x_hat = self.decoder(z)
-        loss = nn.functional.mse_loss(x_hat, x)
-        # log metrics
-        self.log("train_loss", loss)
-        return loss
-
-    def configure_optimizers(self):
-        optimizer = optim.Adam(self.parameters(), lr=self.lr)
-        return optimizer
-
-
-if __name__ == "__main__":
-    # init the autoencoder
-    autoencoder = LitAutoEncoder(lr=1e-3, inp_size=28)
-
-    # setup data
-    train_loader = DataLoader(
-        dataset=MNIST(os.getcwd(), download=True, transform=ToTensor()),
-        batch_size=32,
-        shuffle=True,
-        num_workers=cpu_count(),
-        persistent_workers=True,
-    )
-
-    # configure the logger
-    lit_logger = LightningLogger(log_model=True)
-
-    # pass logger to the Trainer
-    trainer = L.Trainer(max_epochs=5, logger=lit_logger)
-
-    # train the model
-    trainer.fit(model=autoencoder, train_dataloaders=train_loader)
-```
+</details>

examples/train-resume.py examples/resume-lightning-training.pyexamples/train-resume.py renamed to examples/resume-lightning-training.py

@@ -1,3 +1,7 @@
+"""
+This example demonstrates how to resume training of a model using the `download_model` function.
+"""
+
 import torch.utils.data as data
 import torchvision as tv
 from lightning import Trainer

examples/train-simple.py examples/train-model-and-simple-save.pyexamples/train-simple.py renamed to examples/train-model-and-simple-save.py

@@ -1,3 +1,7 @@
+"""
+This example demonstrates how to train a model and upload it to the cloud using the `upload_model` function.
+"""
+
 import torch.utils.data as data
 import torchvision as tv
 from lightning import Trainer

examples/train-callback.py …s/train-model-with-lightning-callback.pyexamples/train-callback.py renamed to examples/train-model-with-lightning-callback.py examples/train-callback.py renamed to examples/train-model-with-lightning-callback.py

@@ -1,3 +1,7 @@
+"""
+Train a model with a Lightning callback that uploads the best model to the cloud after each epoch.
+"""
+
 import torch.utils.data as data
 import torchvision as tv
 from lightning import Callback, Trainer

examples/train-model-with-lightning-logger.py

@@ -0,0 +1,64 @@
+"""
+# Enhanced Logging with LightningLogger
+
+Integrate with [LitLogger](https://github.com/gridai/lit-logger) to automatically log your model checkpoints
+ and training metrics to cloud storage.
+Though the example utilizes PyTorch Lightning, this integration concept works across various model training frameworks.
+
+"""
+
+import os
+
+from lightning import LightningModule, Trainer
+from litlogger import LightningLogger
+from psutil import cpu_count
+from torch import nn, optim
+from torch.utils.data import DataLoader
+from torchvision.datasets import MNIST
+from torchvision.transforms import ToTensor
+
+
+class LitAutoEncoder(LightningModule):
+    def __init__(self, lr=1e-3, inp_size=28):
+        super().__init__()
+
+        self.encoder = nn.Sequential(nn.Linear(inp_size * inp_size, 64), nn.ReLU(), nn.Linear(64, 3))
+        self.decoder = nn.Sequential(nn.Linear(3, 64), nn.ReLU(), nn.Linear(64, inp_size * inp_size))
+        self.lr = lr
+        self.save_hyperparameters()
+
+    def training_step(self, batch, batch_idx):
+        x, y = batch
+        x = x.view(x.size(0), -1)
+        z = self.encoder(x)
+        x_hat = self.decoder(z)
+        loss = nn.functional.mse_loss(x_hat, x)
+        # log metrics
+        self.log("train_loss", loss)
+        return loss
+
+    def configure_optimizers(self):
+        return optim.Adam(self.parameters(), lr=self.lr)
+
+
+if __name__ == "__main__":
+    # init the autoencoder
+    autoencoder = LitAutoEncoder(lr=1e-3, inp_size=28)
+
+    # setup data
+    train_loader = DataLoader(
+        dataset=MNIST(os.getcwd(), download=True, transform=ToTensor()),
+        batch_size=32,
+        shuffle=True,
+        num_workers=cpu_count(),
+        persistent_workers=True,
+    )
+
+    # configure the logger
+    lit_logger = LightningLogger(log_model=True)
+
+    # pass logger to the Trainer
+    trainer = Trainer(max_epochs=5, logger=lit_logger)
+
+    # train the model
+    trainer.fit(model=autoencoder, train_dataloaders=train_loader)

src/litmodels/__about__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.9rc"
+__version__ = "0.1.0"
 __author__ = "Lightning-AI et al."
 __author_email__ = "[email protected]"
 __license__ = "Apache-2.0"