sigularty 0.0.0__tar.gz

sigularty-0.0.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: sigularty
+Version: 0.0.0
+Summary: Production-grade PyTorch model compression: pruning, LRF, clustering, quantization, GPTQ.
+Author: sigularty
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: Other/Proprietary License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.0
+Requires-Dist: torchvision>=0.15
+Requires-Dist: torchmetrics>=0.11
+Requires-Dist: tqdm
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Provides-Extra: pruning
+Requires-Dist: torch-pruning>=1.3; extra == "pruning"
+Provides-Extra: full
+Requires-Dist: torch-pruning>=1.3; extra == "full"
+Requires-Dist: onnx; extra == "full"
+Requires-Dist: onnxruntime; extra == "full"
+
+# Using sigularty
+
+This is a quick reference for calling sigularty as a library: how to
+import it, the two ways to get a model in, and what every `compress()`
+argument does. For the theory behind each technique — why pruning runs
+before LRF, what CQI means, why quantization is always last — see
+[README.md](README.md).
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/<you>/sigularty.git
+cd sigularty
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+**Fastest path — a registry model + its paired dataset in one call:**
+
+```python
+from sigularty import load_from_registry, compress
+
+r = load_from_registry('resnet18', device='cuda')
+
+result = compress(
+    r.model,
+    r.train_loader,
+    num_classes=r.num_classes,
+    use_pruning=True,
+    use_lrf=True,
+)
+
+print(result)
+# CompressionResult(ratio=3.42x, accuracy_retention=96.1%, size=42.7->12.5 MB, speedup=1.8x, cqi=2.113)
+
+compressed_model = result.model
+```
+
+**Bring your own model:**
+
+```python
+from sigularty import compress
+
+result = compress(model, train_loader, num_classes=num_classes)
+compressed_model = result.model
+```
+
+`model` can be any `nn.Module`. `dataloader` (positional, second argument)
+is used for calibration, fine-tuning, and evaluation throughout the
+pipeline — it's never optional. The original model is never modified;
+`compress()` always works on a deep copy.
+
+---
+
+## Other entry points
+
+```python
+from sigularty import (
+    compress,               # run the full compression pipeline
+    analyze,                # inspect a model, get technique recommendations
+    load_from_registry,     # pull a registry model + its dataset together
+    load_model_and_data,    # older form of the above, returns a plain tuple
+    finetune,                # fine-tune a model before compressing it
+    find_best_lr,            # LR range test — run before finetune()/pretrain_*
+    plot_compression_report,
+    plot_pruning_report,
+    plot_epsilon_landscape,
+)
+```
+
+| Function | Signature | Returns |
+|---|---|---|
+| `analyze(model, dataloader=None, *, device=None)` | Inspects a model without modifying it. | `AnalysisResult` |
+| `load_from_registry(model_name, *, device=None, train_sample=None, test_sample=500, batch_size=32, model_path=None, force_retrain=False, pretrain_epochs=10, pretrain_lr=1e-4)` | See list of registry model names below. | `RegistryResult` |
+| `load_model_and_data(model_name, device=None, ...)` | Same idea as above, older interface. | `(model, train_loader, test_loader, meta)` |
+| `finetune(model, train_loader, *, test_loader=None, num_classes=10, epochs=10, lr=1e-3, max_batches=0, device=None, save_path=None)` | Fine-tunes in place and returns the same object. | `nn.Module` |
+| `find_best_lr(model, dataloader, *, device=None, num_classes=10, start_lr=1e-7, end_lr=10.0, num_steps=100)` | LR range test; run before `finetune()` or `pretrain_epochs > 0`. | `float` |
+
+Registry model names (pass as `model_name`): `resnet18`, `resnet50`,
+`resnext50_32x4d`, `wide_resnet50_2`, `vgg16`, `densenet121`,
+`convnext_tiny`, `regnet_y_400mf`, `shufflenet_v2_x1_0`, `squeezenet1_1`,
+`mobilenet_v3_large`, `efficientnet_b0`, `inception_v3`, `vit_b_16`,
+`swin_t`, `bert_base`, `distilbert`, `roberta_base`, `albert_base`,
+`distilgpt2`, `custom_cnn`.
+
+---
+
+## What `compress()` returns
+
+```python
+result.model                   # nn.Module — the compressed model, ready to use
+result.compression_ratio       # size_original / size_compressed, e.g. 3.8 = 3.8x smaller
+result.accuracy_retention      # (compressed_acc / original_acc) * 100
+result.size_original_mb
+result.size_compressed_mb
+result.original_accuracy
+result.compressed_accuracy
+result.original_latency_ms
+result.compressed_latency_ms
+result.latency_speedup         # original_lat / compressed_lat, >1.0 = faster
+result.cqi                     # Compression Quality Index — see README.md
+result.techniques_applied      # list[str], only techniques that actually ran/survived
+result.report_path             # path to the saved PNG report, or None
+result.pruning_report          # dict of per-layer pruning detail, or None
+```
+
+`analyze()` returns an `AnalysisResult`: `size_mb`, `num_parameters`,
+`architecture_type` (`'cnn'` / `'transformer'` / `'hybrid'` / `'unknown'`),
+`recommended_techniques`, `per_layer_signals` (a `LayerSignal` per eligible
+layer: `name`, `layer_type`, `lrf_epsilon`, `prunable`, `size_kb`), and
+`accuracy` if you passed a dataloader.
+
+`load_from_registry()` returns a `RegistryResult`: `model`, `train_loader`,
+`test_loader`, `num_classes`, `model_name`, `dataset_name`.
+
+---
+
+## `compress()` hyperparameters
+
+Every argument after `model` and `dataloader` is keyword-only. Grouped
+the same way the function itself groups them.
+
+### Device
+
+| Arg | Default | What it does |
+|---|---|---|
+| `device` | `None` | `'cuda'` or `'cpu'`. Auto-detected when not set. |
+
+### Model metadata
+
+| Arg | Default | What it does |
+|---|---|---|
+| `model_type` | `'unknown'` | Architecture class for pruning's safety clamp: `'classifier'`, `'embedding'`, `'generative'`, or `'unknown'`. |
+| `num_classes` | `10` | Output class count, used by every fine-tune step's accuracy metric. |
+
+### Pre-training
+
+Use these when the model hasn't been trained on your target dataset yet
+(e.g. fresh ImageNet weights with an untrained head).
+
+| Arg | Default | What it does |
+|---|---|---|
+| `pretrain_epochs` | `0` | Epochs to fine-tune before compressing. `0` skips this entirely. |
+| `pretrain_lr` | `1e-3` | Learning rate for that pre-training. |
+| `pretrain_test_loader` | `None` | Validation loader for pre-training. Falls back to `dataloader`. |
+
+### Hyperparameter search (optional, adds evaluations before the pipeline runs)
+
+| Arg | Default | What it does |
+|---|---|---|
+| `find_optimal_epsilon` | `False` | Auto-search for the best LRF epsilon instead of using `lrf_epsilon` as-is. |
+| `find_optimal_pruning` | `False` | Auto-search for the best pruning ratio instead of using `pruning_ratio` as-is. |
+| `epsilon_search_trials` | `15` | Evaluation budget for the epsilon search. |
+| `pruning_search_trials` | `16` | Evaluation budget for the pruning search. |
+| `pruning_search_ft_epochs` | `1` | Fine-tune epochs per trial during the pruning search (kept low for speed — the real run uses `pruning_fine_tune_epochs`). |
+| `pruning_search_ft_lr` | `1e-4` | Fine-tune learning rate per trial during the pruning search. |
+| `accuracy_drop_threshold` | `5.0` | Max acceptable accuracy drop in percentage points — used by both searches' final selection and the pipeline's per-technique revert gate. |
+
+### Technique enable flags
+
+| Arg | Default |
+|---|---|
+| `use_pruning` | `False` |
+| `use_lrf` | `True` |
+| `use_clustering` | `True` |
+| `use_quantization` | `True` |
+| `use_kd_finetune` | `True` |
+| `use_gptq` | `False` |
+
+### Pruning hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `pruning_ratio` | `0.3` | Target fraction of channels removed globally. |
+| `pruning_max_ratio` | `0.95` | Hard cap on how much any single layer/dependency-group can be pruned. |
+| `pruning_model_type` | `'classifier'` | Same role as `model_type`, specific to pruning's clamp. |
+| `pruning_fine_tune_epochs` | `3` | KD recovery epochs after pruning. |
+| `pruning_fine_tune_lr` | `1e-4` | Learning rate for that recovery fine-tune. |
+| `pruning_cal_batches` | `50` | Calibration batches for activation-statistics importance scoring. |
+| `pruning_iterative_steps` | `1` | Prune in one shot (`1`) or multiple incremental rounds (more stable, slower). |
+| `pruning_isomorphic` | `False` | Force identical pruning structure across coupled dependency groups. |
+| `pruning_round_to` | `None` | Round pruned channel counts to a multiple of this (e.g. `8`/`16` for Tensor Core alignment). |
+
+### Low-Rank Factorization (LRF) hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `lrf_epsilon` | `0.5` | Rank ratio kept. Lower = more compression, more accuracy risk. |
+| `lrf_adaptive` | `False` | Compute epsilon per layer from SVD energy decay instead of one global value. |
+| `lrf_energy_threshold` | `0.99` | Fraction of SVD energy retained per layer, when adaptive. |
+| `lrf_min_layer_size` | `64` | Skip layers with a dimension below this. |
+| `lrf_min_rank` | `2` | Skip a layer if its computed rank would fall below this. |
+| `lrf_skip_large_kernels` | `False` | Skip Conv2d layers with kernel > 1x1 — prevents latency regression on 3x3-heavy CNNs (ResNet/VGG-style). |
+
+### Weight clustering hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `num_clusters` | `16` | k for k-means weight clustering. |
+| `cluster_fine_tune_epochs` | `5` | Recovery fine-tune epochs after clustering. |
+| `cluster_fine_tune_lr` | `1e-5` | Learning rate for that recovery fine-tune. |
+
+### Knowledge distillation fine-tuning hyperparameters
+
+The final recovery step, run after quantization/GPTQ so it can recover
+accuracy lost from every prior step at once.
+
+| Arg | Default | What it does |
+|---|---|---|
+| `kd_epochs` | `3` | Fine-tune epochs. |
+| `kd_lr` | `1e-5` | Learning rate. |
+| `kd_temperature` | `4.0` | Softmax temperature for the teacher's soft labels. |
+| `kd_alpha` | `0.7` | Weight on hard-label loss; `1 - kd_alpha` goes to the distillation loss. |
+
+### Quantization hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `quant_mode` | `'fp16'` | `'fp16'`, `'dynamic'` (INT8, CPU-friendly), or `'static'` (auto-switched to `'dynamic'`). |
+| `quant_cal_batches` | `100` | Calibration batches — only used by `'static'`. |
+
+### GPTQ hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `gptq_bits` | `4` | `4` for INT4 (8x compression) or `8` for INT8 (4x). |
+| `gptq_cal_batches` | `16` | Batches used to estimate the Hessian from activations. |
+| `gptq_block_size` | `128` | Columns processed per Hessian update block. |
+
+### CQI scoring weights
+
+Each is an exponent applied to that factor's ratio in the Compression
+Quality Index — raise one to make the search/report weight that factor
+more heavily.
+
+| Arg | Default |
+|---|---|
+| `cqi_w_accuracy` | `1.0` |
+| `cqi_w_size` | `1.0` |
+| `cqi_w_latency` | `1.0` |
+| `cqi_w_kl` | `1.0` (only meaningful when pruning ran) |
+
+### Report
+
+| Arg | Default | What it does |
+|---|---|---|
+| `save_report` | `True` | Generate the PNG compression report. |
+| `report_path` | `'compression_report.png'` | Where to save it. |

sigularty-0.0.0/PublicReadme.md

@@ -0,0 +1,253 @@
+# Using sigularty
+
+This is a quick reference for calling sigularty as a library: how to
+import it, the two ways to get a model in, and what every `compress()`
+argument does. For the theory behind each technique — why pruning runs
+before LRF, what CQI means, why quantization is always last — see
+[README.md](README.md).
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/<you>/sigularty.git
+cd sigularty
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+**Fastest path — a registry model + its paired dataset in one call:**
+
+```python
+from sigularty import load_from_registry, compress
+
+r = load_from_registry('resnet18', device='cuda')
+
+result = compress(
+    r.model,
+    r.train_loader,
+    num_classes=r.num_classes,
+    use_pruning=True,
+    use_lrf=True,
+)
+
+print(result)
+# CompressionResult(ratio=3.42x, accuracy_retention=96.1%, size=42.7->12.5 MB, speedup=1.8x, cqi=2.113)
+
+compressed_model = result.model
+```
+
+**Bring your own model:**
+
+```python
+from sigularty import compress
+
+result = compress(model, train_loader, num_classes=num_classes)
+compressed_model = result.model
+```
+
+`model` can be any `nn.Module`. `dataloader` (positional, second argument)
+is used for calibration, fine-tuning, and evaluation throughout the
+pipeline — it's never optional. The original model is never modified;
+`compress()` always works on a deep copy.
+
+---
+
+## Other entry points
+
+```python
+from sigularty import (
+    compress,               # run the full compression pipeline
+    analyze,                # inspect a model, get technique recommendations
+    load_from_registry,     # pull a registry model + its dataset together
+    load_model_and_data,    # older form of the above, returns a plain tuple
+    finetune,                # fine-tune a model before compressing it
+    find_best_lr,            # LR range test — run before finetune()/pretrain_*
+    plot_compression_report,
+    plot_pruning_report,
+    plot_epsilon_landscape,
+)
+```
+
+| Function | Signature | Returns |
+|---|---|---|
+| `analyze(model, dataloader=None, *, device=None)` | Inspects a model without modifying it. | `AnalysisResult` |
+| `load_from_registry(model_name, *, device=None, train_sample=None, test_sample=500, batch_size=32, model_path=None, force_retrain=False, pretrain_epochs=10, pretrain_lr=1e-4)` | See list of registry model names below. | `RegistryResult` |
+| `load_model_and_data(model_name, device=None, ...)` | Same idea as above, older interface. | `(model, train_loader, test_loader, meta)` |
+| `finetune(model, train_loader, *, test_loader=None, num_classes=10, epochs=10, lr=1e-3, max_batches=0, device=None, save_path=None)` | Fine-tunes in place and returns the same object. | `nn.Module` |
+| `find_best_lr(model, dataloader, *, device=None, num_classes=10, start_lr=1e-7, end_lr=10.0, num_steps=100)` | LR range test; run before `finetune()` or `pretrain_epochs > 0`. | `float` |
+
+Registry model names (pass as `model_name`): `resnet18`, `resnet50`,
+`resnext50_32x4d`, `wide_resnet50_2`, `vgg16`, `densenet121`,
+`convnext_tiny`, `regnet_y_400mf`, `shufflenet_v2_x1_0`, `squeezenet1_1`,
+`mobilenet_v3_large`, `efficientnet_b0`, `inception_v3`, `vit_b_16`,
+`swin_t`, `bert_base`, `distilbert`, `roberta_base`, `albert_base`,
+`distilgpt2`, `custom_cnn`.
+
+---
+
+## What `compress()` returns
+
+```python
+result.model                   # nn.Module — the compressed model, ready to use
+result.compression_ratio       # size_original / size_compressed, e.g. 3.8 = 3.8x smaller
+result.accuracy_retention      # (compressed_acc / original_acc) * 100
+result.size_original_mb
+result.size_compressed_mb
+result.original_accuracy
+result.compressed_accuracy
+result.original_latency_ms
+result.compressed_latency_ms
+result.latency_speedup         # original_lat / compressed_lat, >1.0 = faster
+result.cqi                     # Compression Quality Index — see README.md
+result.techniques_applied      # list[str], only techniques that actually ran/survived
+result.report_path             # path to the saved PNG report, or None
+result.pruning_report          # dict of per-layer pruning detail, or None
+```
+
+`analyze()` returns an `AnalysisResult`: `size_mb`, `num_parameters`,
+`architecture_type` (`'cnn'` / `'transformer'` / `'hybrid'` / `'unknown'`),
+`recommended_techniques`, `per_layer_signals` (a `LayerSignal` per eligible
+layer: `name`, `layer_type`, `lrf_epsilon`, `prunable`, `size_kb`), and
+`accuracy` if you passed a dataloader.
+
+`load_from_registry()` returns a `RegistryResult`: `model`, `train_loader`,
+`test_loader`, `num_classes`, `model_name`, `dataset_name`.
+
+---
+
+## `compress()` hyperparameters
+
+Every argument after `model` and `dataloader` is keyword-only. Grouped
+the same way the function itself groups them.
+
+### Device
+
+| Arg | Default | What it does |
+|---|---|---|
+| `device` | `None` | `'cuda'` or `'cpu'`. Auto-detected when not set. |
+
+### Model metadata
+
+| Arg | Default | What it does |
+|---|---|---|
+| `model_type` | `'unknown'` | Architecture class for pruning's safety clamp: `'classifier'`, `'embedding'`, `'generative'`, or `'unknown'`. |
+| `num_classes` | `10` | Output class count, used by every fine-tune step's accuracy metric. |
+
+### Pre-training
+
+Use these when the model hasn't been trained on your target dataset yet
+(e.g. fresh ImageNet weights with an untrained head).
+
+| Arg | Default | What it does |
+|---|---|---|
+| `pretrain_epochs` | `0` | Epochs to fine-tune before compressing. `0` skips this entirely. |
+| `pretrain_lr` | `1e-3` | Learning rate for that pre-training. |
+| `pretrain_test_loader` | `None` | Validation loader for pre-training. Falls back to `dataloader`. |
+
+### Hyperparameter search (optional, adds evaluations before the pipeline runs)
+
+| Arg | Default | What it does |
+|---|---|---|
+| `find_optimal_epsilon` | `False` | Auto-search for the best LRF epsilon instead of using `lrf_epsilon` as-is. |
+| `find_optimal_pruning` | `False` | Auto-search for the best pruning ratio instead of using `pruning_ratio` as-is. |
+| `epsilon_search_trials` | `15` | Evaluation budget for the epsilon search. |
+| `pruning_search_trials` | `16` | Evaluation budget for the pruning search. |
+| `pruning_search_ft_epochs` | `1` | Fine-tune epochs per trial during the pruning search (kept low for speed — the real run uses `pruning_fine_tune_epochs`). |
+| `pruning_search_ft_lr` | `1e-4` | Fine-tune learning rate per trial during the pruning search. |
+| `accuracy_drop_threshold` | `5.0` | Max acceptable accuracy drop in percentage points — used by both searches' final selection and the pipeline's per-technique revert gate. |
+
+### Technique enable flags
+
+| Arg | Default |
+|---|---|
+| `use_pruning` | `False` |
+| `use_lrf` | `True` |
+| `use_clustering` | `True` |
+| `use_quantization` | `True` |
+| `use_kd_finetune` | `True` |
+| `use_gptq` | `False` |
+
+### Pruning hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `pruning_ratio` | `0.3` | Target fraction of channels removed globally. |
+| `pruning_max_ratio` | `0.95` | Hard cap on how much any single layer/dependency-group can be pruned. |
+| `pruning_model_type` | `'classifier'` | Same role as `model_type`, specific to pruning's clamp. |
+| `pruning_fine_tune_epochs` | `3` | KD recovery epochs after pruning. |
+| `pruning_fine_tune_lr` | `1e-4` | Learning rate for that recovery fine-tune. |
+| `pruning_cal_batches` | `50` | Calibration batches for activation-statistics importance scoring. |
+| `pruning_iterative_steps` | `1` | Prune in one shot (`1`) or multiple incremental rounds (more stable, slower). |
+| `pruning_isomorphic` | `False` | Force identical pruning structure across coupled dependency groups. |
+| `pruning_round_to` | `None` | Round pruned channel counts to a multiple of this (e.g. `8`/`16` for Tensor Core alignment). |
+
+### Low-Rank Factorization (LRF) hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `lrf_epsilon` | `0.5` | Rank ratio kept. Lower = more compression, more accuracy risk. |
+| `lrf_adaptive` | `False` | Compute epsilon per layer from SVD energy decay instead of one global value. |
+| `lrf_energy_threshold` | `0.99` | Fraction of SVD energy retained per layer, when adaptive. |
+| `lrf_min_layer_size` | `64` | Skip layers with a dimension below this. |
+| `lrf_min_rank` | `2` | Skip a layer if its computed rank would fall below this. |
+| `lrf_skip_large_kernels` | `False` | Skip Conv2d layers with kernel > 1x1 — prevents latency regression on 3x3-heavy CNNs (ResNet/VGG-style). |
+
+### Weight clustering hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `num_clusters` | `16` | k for k-means weight clustering. |
+| `cluster_fine_tune_epochs` | `5` | Recovery fine-tune epochs after clustering. |
+| `cluster_fine_tune_lr` | `1e-5` | Learning rate for that recovery fine-tune. |
+
+### Knowledge distillation fine-tuning hyperparameters
+
+The final recovery step, run after quantization/GPTQ so it can recover
+accuracy lost from every prior step at once.
+
+| Arg | Default | What it does |
+|---|---|---|
+| `kd_epochs` | `3` | Fine-tune epochs. |
+| `kd_lr` | `1e-5` | Learning rate. |
+| `kd_temperature` | `4.0` | Softmax temperature for the teacher's soft labels. |
+| `kd_alpha` | `0.7` | Weight on hard-label loss; `1 - kd_alpha` goes to the distillation loss. |
+
+### Quantization hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `quant_mode` | `'fp16'` | `'fp16'`, `'dynamic'` (INT8, CPU-friendly), or `'static'` (auto-switched to `'dynamic'`). |
+| `quant_cal_batches` | `100` | Calibration batches — only used by `'static'`. |
+
+### GPTQ hyperparameters
+
+| Arg | Default | What it does |
+|---|---|---|
+| `gptq_bits` | `4` | `4` for INT4 (8x compression) or `8` for INT8 (4x). |
+| `gptq_cal_batches` | `16` | Batches used to estimate the Hessian from activations. |
+| `gptq_block_size` | `128` | Columns processed per Hessian update block. |
+
+### CQI scoring weights
+
+Each is an exponent applied to that factor's ratio in the Compression
+Quality Index — raise one to make the search/report weight that factor
+more heavily.
+
+| Arg | Default |
+|---|---|
+| `cqi_w_accuracy` | `1.0` |
+| `cqi_w_size` | `1.0` |
+| `cqi_w_latency` | `1.0` |
+| `cqi_w_kl` | `1.0` (only meaningful when pruning ran) |
+
+### Report
+
+| Arg | Default | What it does |
+|---|---|---|
+| `save_report` | `True` | Generate the PNG compression report. |
+| `report_path` | `'compression_report.png'` | Where to save it. |