turboquant-ml 0.1.0__tar.gz

turboquant_ml-0.1.0/.claude/settings.local.json

@@ -0,0 +1,95 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find E:/turboquant -type f -not -path '*/\\\\.*')",
+      "Bash(python -c \"import ast, pathlib; [ast.parse\\(p.read_text\\(encoding='utf-8'\\)\\) for p in pathlib.Path\\('src'\\).rglob\\('*.py'\\)]; print\\('src OK'\\)\")",
+      "Bash(python -m py_compile src/turboquant/__init__.py)",
+      "Bash(python -c \"import ast, pathlib; [ast.parse\\(p.read_text\\(encoding='utf-8'\\)\\) for p in list\\(pathlib.Path\\('tests'\\).rglob\\('*.py'\\)\\) + list\\(pathlib.Path\\('examples'\\).rglob\\('*.py'\\)\\) + list\\(pathlib.Path\\('benchmarks'\\).rglob\\('*.py'\\)\\)]; print\\('tests+examples+benchmarks OK'\\)\")",
+      "Bash(git --version)",
+      "Bash(gh --version)",
+      "Bash(git config *)",
+      "Bash(rtk git *)",
+      "Bash(git init *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git remote *)",
+      "Bash(git ls-remote *)",
+      "Bash(git push *)",
+      "Bash(python -c \"import torch; print\\('torch', torch.__version__, 'cuda', torch.cuda.is_available\\(\\)\\)\")",
+      "Bash(python -m venv .venv)",
+      "Bash(.venv/Scripts/python.exe -m pip install --upgrade pip wheel)",
+      "Bash(.venv/Scripts/python.exe -m pip install --index-url https://download.pytorch.org/whl/cpu torch)",
+      "Bash(.venv/Scripts/python.exe -m pip install transformers numpy psutil typer rich pyyaml accelerate)",
+      "Bash(.venv/Scripts/python.exe -m pip install -e . --no-deps)",
+      "Bash(.venv/Scripts/python.exe -c ' *)",
+      "Bash(.venv/Scripts/python.exe -m pip install pytest)",
+      "Bash(.venv/Scripts/python.exe -m pytest -m \"not slow and not gpu\" -x --tb=short)",
+      "Bash(.venv/Scripts/python.exe -m pip install matplotlib)",
+      "Bash(.venv/Scripts/python.exe benchmarks/scripts/sweep_cpu.py --model-id HuggingFaceTB/SmolLM2-135M --methods fp32,fp16,bf16,int8-dynamic --warmup 2 --iters 8 --max-new-tokens 24 --out benchmarks/results/smollm2_135m.json --plot benchmarks/results/smollm2_135m.png)",
+      "Bash(HF_HUB_DISABLE_XET=1 .venv/Scripts/python.exe -c ' *)",
+      "Bash(.venv/Scripts/python.exe -m pip install \"huggingface_hub<1.0\")",
+      "Bash(.venv/Scripts/python.exe -m pip install \"transformers<5\")",
+      "Bash(CERT='E:\\\\turboquant\\\\.venv\\\\Lib\\\\site-packages\\\\certifi\\\\cacert.pem' SSL_CERT_FILE='E:\\\\turboquant\\\\.venv\\\\Lib\\\\site-packages\\\\certifi\\\\cacert.pem' REQUESTS_CA_BUNDLE='E:\\\\turboquant\\\\.venv\\\\Lib\\\\site-packages\\\\certifi\\\\cacert.pem' CURL_CA_BUNDLE='E:\\\\turboquant\\\\.venv\\\\Lib\\\\site-packages\\\\certifi\\\\cacert.pem' .venv/Scripts/python.exe -c ' *)",
+      "Bash(.venv/Scripts/python.exe -m pip install truststore)",
+      "Bash(.venv/Scripts/python.exe benchmarks/scripts/sweep_cpu.py --model-id gpt2 --methods fp32,fp16,bf16,int8-dynamic --warmup 2 --iters 8 --max-new-tokens 24 --out benchmarks/results/gpt2.json --plot benchmarks/results/gpt2.png)",
+      "Bash(PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe benchmarks/scripts/sweep_cpu.py --model-id gpt2 --methods fp32,fp16,bf16,int8-dynamic --warmup 2 --iters 8 --max-new-tokens 24 --out benchmarks/results/gpt2.json --plot benchmarks/results/gpt2.png)",
+      "Bash(env)",
+      "Bash(curl --version)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\\\\n\" https://Ademo93.github.io/turboquant/)",
+      "Bash(.venv/Scripts/python.exe -m pip install mkdocs-material pymdown-extensions)",
+      "Bash(.venv/Scripts/python.exe -m mkdocs build --strict)",
+      "Bash(curl -sS \"https://api.github.com/repos/Ademo93/turboquant/actions/workflows\")",
+      "Bash(curl -sS -o /dev/null -w \"HTTP %{http_code}  \\(final URL: %{url_effective}\\)\\\\n\" -L https://Ademo93.github.io/turboquant/)",
+      "Bash(curl -sS -o /dev/null -w \"HTTP %{http_code}\\\\n\" https://api.github.com/repos/Ademo93/turboquant/pages)",
+      "Bash(curl -sS \"https://api.github.com/repos/Ademo93/turboquant/actions/runs?per_page=5\")",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/repos/Ademo93/turboquant/actions/workflows\")",
+      "Bash(curl -sS --ssl-no-revoke -o /dev/null -w \"HTTP %{http_code}  \\(final URL: %{url_effective}\\)\\\\n\" -L https://Ademo93.github.io/turboquant/)",
+      "Bash(curl -sS --ssl-no-revoke -o /dev/null -w \"HTTP %{http_code}\\\\n\" https://api.github.com/repos/Ademo93/turboquant/pages)",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/repos/Ademo93/turboquant/actions/runs?per_page=5\")",
+      "Bash(curl -sS --ssl-no-revoke https://api.github.com/repos/Ademo93/turboquant/actions/runs/27765595606/jobs)",
+      "Bash(curl -sS --ssl-no-revoke https://api.github.com/repos/Ademo93/turboquant/actions/runs/27766724363/jobs)",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/repos/Ademo93/turboquant/actions/runs/27766724363/jobs\")",
+      "Bash(python -c ' *)",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/repos/Ademo93/turboquant/actions/runs/27765595606/jobs\")",
+      "Bash(.venv/Scripts/python.exe -m pip install ruff)",
+      "Bash(.venv/Scripts/python.exe -m ruff check src tests)",
+      "Bash(.venv/Scripts/python.exe -m ruff format --check src tests)",
+      "Bash(curl -sSL --ssl-no-revoke -o /tmp/test_log.zip \"https://api.github.com/repos/Ademo93/turboquant/actions/jobs/82155364717/logs\")",
+      "Bash(.venv/Scripts/python.exe -m ruff check --fix src tests)",
+      "Bash(.venv/Scripts/python.exe -m ruff format src tests)",
+      "Bash(.venv/Scripts/python.exe -m ruff check --output-format=concise src tests)",
+      "Bash(PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe -m pytest -m \"not slow and not gpu\" --tb=short)",
+      "Bash(.venv/Scripts/python.exe -m pip install onnx onnxruntime onnxslim)",
+      "Bash(PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe -m pytest tests/test_export.py -x --tb=long)",
+      "Bash(.venv/Scripts/python.exe -m pip install onnxscript)",
+      "Bash(PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe -m pytest tests/test_export.py::test_onnx_dynamic_int8 --tb=long)",
+      "Bash(PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe -m pytest tests/test_export.py::test_onnx_dynamic_int8 --tb=long --no-header)",
+      "Bash(git rm *)",
+      "Bash(gh auth *)",
+      "Bash(curl -sS --ssl-no-revoke -o /dev/null -w \"HTTP %{http_code}\\\\n\" -L https://Ademo93.github.io/turboquant/)",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/repos/Ademo93/turboquant/actions/runs?per_page=6\")",
+      "Bash(curl -sS --ssl-no-revoke https://api.github.com/users/Ademo93)",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/users/Ademo93/repos?per_page=100&sort=pushed&direction=desc\")",
+      "Bash(curl -sS --ssl-no-revoke -i https://api.github.com/users/Ademo93)",
+      "Bash(curl -sS --ssl-no-revoke -A \"Mozilla/5.0\" \"https://github.com/Ademo93?tab=repositories\")",
+      "Bash(curl -sS --ssl-no-revoke -A \"Mozilla/5.0\" \"https://github.com/Ademo93?page=2&tab=repositories\")",
+      "Bash(curl -sS --ssl-no-revoke -A \"Mozilla/5.0\" \"https://github.com/Ademo93?page=3&tab=repositories\")",
+      "Bash(curl -sS --ssl-no-revoke -A \"Mozilla/5.0\" -o /tmp/profile.html \"https://github.com/Ademo93?tab=repositories\")",
+      "Read(//tmp/**)",
+      "Bash(cp /tmp/profile.html E:/turboquant/.venv/profile.html)",
+      "Bash(E:/turboquant/.venv/Scripts/python.exe -c ' *)",
+      "Bash(git reset *)",
+      "Bash(mkdir -p E:/Ademo93-profile)",
+      "Bash(mv E:/turboquant/profile-readme-staging/README.md E:/Ademo93-profile/README.md)",
+      "Read(//e//**)",
+      "Bash(git tag -a v0.1.0 -m 'v0.1.0 — first release *)",
+      "Bash(.venv/Scripts/python.exe -m pip install build twine)",
+      "Bash(.venv/Scripts/python.exe -m build)",
+      "Bash(.venv/Scripts/python.exe -m twine check dist/*)",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/repos/Ademo93/turboquant/git/refs/tags\")",
+      "Bash(curl -sS --ssl-no-revoke -A \"Mozilla/5.0\" https://github.com/Ademo93/turboquant/releases)",
+      "Bash(curl -sS --ssl-no-revoke \"https://api.github.com/repos/Ademo93/turboquant/git/refs/tags/v0.1.0\")",
+      "Bash(curl *)"
+    ]
+  }
+}

turboquant_ml-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install dev tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+      - name: Ruff
+        run: ruff check src tests
+      - name: Ruff format check
+        run: ruff format --check src tests
+      - name: Mypy (non-blocking)
+        continue-on-error: true
+        run: mypy src/turboquant
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,onnx,viz]"
+      - name: Run tests
+        run: pytest -m "not slow and not gpu" --cov=turboquant --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

turboquant_ml-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install MkDocs Material
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material mkdocs-glightbox pymdown-extensions
+      - name: Build site
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

turboquant_ml-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Notebooks
+.ipynb_checkpoints/
+
+# Models, datasets, weights
+*.bin
+*.safetensors
+*.pt
+*.pth
+*.onnx
+*.engine
+*.gguf
+models_cache/
+hf_cache/
+.cache/
+
+# Benchmarks output (gitignored by default; reference results are allowlisted below)
+benchmarks/results/*.json
+benchmarks/results/*.csv
+benchmarks/results/*.png
+!benchmarks/results/.gitkeep
+!benchmarks/results/smollm2_135m.json
+!benchmarks/results/smollm2_135m.png
+!benchmarks/results/gpt2.json
+!benchmarks/results/gpt2.png
+
+# MkDocs build output
+site/
+
+# Logs
+*.log
+logs/
+
+# Env files
+.env
+.env.local

turboquant_ml-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=512]

turboquant_ml-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and adheres
+to [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-18 — first release
+
+### Added
+- Unified `quantize(model, method=...)` dispatcher with FP16/BF16, INT8 dynamic
+  & static, BitsAndBytes (INT8 / NF4 / FP4), GPTQ, AWQ backends.
+- Unified `prune(model, strategy=...)` dispatcher with magnitude, L1/L2
+  structured channel pruning, and 2:4 N:M sparsity.
+- ONNX export with optional `onnxslim` graph optimization and ORT dynamic INT8
+  weight quantization.
+- TensorRT engine builder with FP16 / INT8 calibration support.
+- Benchmark helpers: latency (CUDA events + p95/p99), peak GPU/CPU memory,
+  serialized model size, sliding-window perplexity, top-k accuracy.
+- Typer CLI with `quantize`, `prune`, `export`, `bench`, `methods` subcommands.
+- pytest suite covering quantization, pruning, benchmark and CLI smoke paths.
+- GitHub Actions CI (lint + tests on Python 3.10–3.12 + wheel build).

turboquant_ml-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TurboQuant Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

turboquant_ml-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: turboquant-ml
+Version: 0.1.0
+Summary: TurboQuant — model quantization and optimization toolkit for edge and resource-constrained deployment.
+Project-URL: Homepage, https://github.com/Ademo93/turboquant
+Project-URL: Repository, https://github.com/Ademo93/turboquant
+Project-URL: Issues, https://github.com/Ademo93/turboquant/issues
+Author: TurboQuant Contributors
+License: MIT
+License-File: LICENSE
+Keywords: awq,bitsandbytes,edge-ai,gptq,llm,model-optimization,onnx,pruning,quantization,tensorrt
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: accelerate>=0.30
+Requires-Dist: datasets>=2.18
+Requires-Dist: numpy>=1.24
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: torch>=2.2
+Requires-Dist: transformers>=4.40
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: auto-gptq>=0.7.1; extra == 'all'
+Requires-Dist: autoawq>=0.2.5; extra == 'all'
+Requires-Dist: bitsandbytes>=0.43; extra == 'all'
+Requires-Dist: evaluate>=0.4; extra == 'all'
+Requires-Dist: lm-eval>=0.4.3; extra == 'all'
+Requires-Dist: matplotlib>=3.8; extra == 'all'
+Requires-Dist: onnx>=1.16; extra == 'all'
+Requires-Dist: onnxruntime>=1.18; extra == 'all'
+Requires-Dist: onnxscript>=0.1; extra == 'all'
+Requires-Dist: onnxslim>=0.1; extra == 'all'
+Requires-Dist: optimum>=1.20; extra == 'all'
+Requires-Dist: pandas>=2.2; extra == 'all'
+Provides-Extra: awq
+Requires-Dist: autoawq>=0.2.5; extra == 'awq'
+Provides-Extra: bnb
+Requires-Dist: bitsandbytes>=0.43; extra == 'bnb'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: eval
+Requires-Dist: evaluate>=0.4; extra == 'eval'
+Requires-Dist: lm-eval>=0.4.3; extra == 'eval'
+Provides-Extra: gptq
+Requires-Dist: auto-gptq>=0.7.1; extra == 'gptq'
+Requires-Dist: optimum>=1.20; extra == 'gptq'
+Provides-Extra: onnx
+Requires-Dist: onnx>=1.16; extra == 'onnx'
+Requires-Dist: onnxruntime>=1.18; extra == 'onnx'
+Requires-Dist: onnxscript>=0.1; extra == 'onnx'
+Requires-Dist: onnxslim>=0.1; extra == 'onnx'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == 'viz'
+Requires-Dist: pandas>=2.2; extra == 'viz'
+Description-Content-Type: text/markdown
+
+<h1 align="center">TurboQuant</h1>
+
+<p align="center">
+  <strong>Model quantization & optimization toolkit for edge and resource-constrained deployment.</strong><br>
+  INT4 · INT8 · FP16 · GPTQ · AWQ · BitsandBytes · Structured pruning · ONNX & TensorRT export
+</p>
+
+<p align="center">
+  <a href="#"><img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue"></a>
+  <a href="#"><img alt="PyTorch" src="https://img.shields.io/badge/pytorch-2.2%2B-ee4c2c"></a>
+  <a href="#"><img alt="License" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <a href="https://github.com/Ademo93/turboquant/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Ademo93/turboquant/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://Ademo93.github.io/turboquant/"><img alt="Docs" src="https://img.shields.io/badge/docs-mkdocs--material-blue"></a>
+  <a href="#"><img alt="Status" src="https://img.shields.io/badge/status-beta-orange"></a>
+</p>
+
+---
+
+## Why TurboQuant?
+
+Modern open-source models are powerful but expensive to serve. Shipping a 7B-parameter LLM in FP16 demands ~14&nbsp;GB of VRAM; a vision transformer that fits comfortably on a workstation may blow up on a Jetson Orin or a phone. **TurboQuant gives you a single, consistent interface to compress, quantize, prune, export, and benchmark models** — so you can ship them on the hardware you actually have.
+
+It is built around three principles:
+
+1. **One API, many backends.** Wrap `bitsandbytes`, `auto-gptq`, `autoawq`, native PyTorch quantization, and ONNX/TensorRT export behind a uniform `quantize(model, method=...)` interface.
+2. **Reproducible benchmarks.** Latency, peak memory, model size, and task accuracy (perplexity, classification top-1, etc.) are first-class citizens — every example ships with a comparable benchmark.
+3. **No magic.** Each technique is implemented as a small, readable module so it doubles as a reference for how the methods work.
+
+## Features
+
+| Category | Techniques |
+|---|---|
+| **Weight quantization** | INT8 dynamic & static PTQ, FP16/BF16 casting, INT4 (bitsandbytes NF4 / FP4), GPTQ, AWQ |
+| **Pruning** | Magnitude (unstructured), L1 structured (channel/filter), N:M sparsity helpers |
+| **Export** | ONNX (with `onnxslim` graph optimization), TensorRT engine builder, ORT quantization |
+| **Calibration** | Per-tensor & per-channel, MinMax / Entropy / Percentile observers |
+| **Benchmark** | Latency (warmup + median + p95), peak GPU/CPU memory, throughput, model size, perplexity, top-k accuracy |
+| **CLI** | `turboquant quantize`, `turboquant prune`, `turboquant export`, `turboquant bench` |
+
+## Installation
+
+The PyPI package is named **`turboquant-ml`** (the unsuffixed `turboquant`
+name was taken by an unrelated project). The Python import and CLI are still
+just `turboquant` / `tq`:
+
+```bash
+# Core install
+pip install turboquant-ml
+
+# With ONNX export
+pip install "turboquant-ml[onnx]"
+
+# Full LLM compression stack (GPTQ + AWQ + bitsandbytes)
+pip install "turboquant-ml[gptq,awq,bnb,eval]"
+
+# Everything
+pip install "turboquant-ml[all]"
+```
+
+```python
+import turboquant                  # import name unchanged
+from turboquant import quantize    # same API
+```
+
+> **Note** — `bitsandbytes`, `auto-gptq`, `autoawq` and `tensorrt` are heavy native dependencies. They are deliberately optional; TurboQuant degrades gracefully when they are missing.
+
+## Quick start
+
+### Python API
+
+```python
+from turboquant import quantize, benchmark
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_id = "meta-llama/Llama-3.2-1B"
+tok = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype="auto")
+
+# One-line INT4 weight-only quantization via bitsandbytes
+qmodel = quantize(model, method="bnb-nf4")
+
+# Benchmark side-by-side
+report = benchmark.compare(
+    baseline=model,
+    candidate=qmodel,
+    tokenizer=tok,
+    prompts=["Explain quantization in one sentence."],
+    metrics=["latency", "memory", "size", "perplexity"],
+)
+print(report.as_table())
+```
+
+### CLI
+
+```bash
+# Quantize a HuggingFace model to INT4 with GPTQ + W4A16
+tq quantize meta-llama/Llama-3.2-1B \
+    --method gptq \
+    --bits 4 \
+    --group-size 128 \
+    --calib-dataset wikitext \
+    --out ./outputs/llama-3.2-1b-gptq
+
+# Structured prune a vision model and re-evaluate
+tq prune microsoft/resnet-50 \
+    --strategy l1-channel \
+    --sparsity 0.30 \
+    --eval imagenet-val \
+    --out ./outputs/resnet50-pruned
+
+# Export to ONNX with INT8 dynamic quantization
+tq export ./outputs/resnet50-pruned \
+    --format onnx \
+    --quant int8-dynamic \
+    --opset 17
+
+# Benchmark FP16 vs INT8 vs INT4 on a model
+tq bench meta-llama/Llama-3.2-1B --methods fp16,int8-dynamic,bnb-nf4 \
+    --report ./benchmarks/results/llama32-1b.json
+```
+
+## Supported methods at a glance
+
+| Method | Bits | Backend | Calibration | Typical use case |
+|---|---|---|---|---|
+| `fp16` / `bf16` | 16 | PyTorch | none | Fast, lossless-ish baseline |
+| `int8-dynamic` | 8 | PyTorch | none | CPU inference, transformers |
+| `int8-static` | 8 | PyTorch | required | CNNs, edge CPUs |
+| `bnb-int8` | 8 | bitsandbytes | none | LLM training & serving on GPU |
+| `bnb-nf4` / `bnb-fp4` | 4 | bitsandbytes | none | LLM inference, QLoRA |
+| `gptq` | 2–8 | auto-gptq | required | LLM weight-only, best accuracy/bit |
+| `awq` | 4 | autoawq | required | LLM weight-only, fast inference |
+
+## Reference benchmarks
+
+### SmolLM2-135M on CPU (real measured numbers)
+
+`python benchmarks/scripts/sweep_cpu.py --model-id HuggingFaceTB/SmolLM2-135M --methods fp32,fp16,bf16,int8-dynamic`
+
+| Method | Size (MB) | Forward latency (ms) | Generation throughput (tok/s) |
+|---|---:|---:|---:|
+| FP32 (baseline) | 513.2 | 31.3 | 32.6 |
+| FP16 | 256.7 | 57.2 | 47.5 |
+| BF16 | 256.7 | 55.4 | **48.9** |
+| INT8 dynamic | **236.6** | **30.7** | 30.0 |
+
+Read this carefully — the result is realistic, not flattering:
+
+- **FP16/BF16 cut size in half**, and *generation* throughput goes **up ~50%**
+  (smaller KV cache wins), but the per-step forward pass is **2× slower**
+  because consumer CPUs have no fast FP16 matmul kernel. On a Tensor-Core GPU
+  these numbers flip.
+- **INT8 dynamic is the smallest** (≈54 % off) and matches FP32 forward
+  latency, but generation throughput is similar to FP32 here — the small
+  hidden size of a 135 M model limits how much INT8 GEMM kernels can help.
+- The right baseline matters: comparing INT8 to a poorly-quantizable
+  reference (e.g. GPT-2, which uses `transformers.Conv1D` instead of
+  `nn.Linear`) makes INT8 look bad. Always check what your method actually
+  rewrites — `tq methods` plus `print(model)` will tell you.
+
+![SmolLM2 sweep](benchmarks/results/smollm2_135m.png)
+
+### Reproduce
+
+```bash
+pip install -e ".[viz]" truststore
+python benchmarks/scripts/sweep_cpu.py \
+    --model-id HuggingFaceTB/SmolLM2-135M \
+    --methods fp32,fp16,bf16,int8-dynamic \
+    --out benchmarks/results/smollm2_135m.json \
+    --plot benchmarks/results/smollm2_135m.png
+```
+
+GPU sweeps (Llama-class models with GPTQ / AWQ / NF4) will land here once a CUDA
+runner is added to CI — contributions welcome.
+
+## Architecture
+
+```
+turboquant/
+├── quantization/          # Algorithms: int8, fp16, gptq, awq, bnb, observers
+├── pruning/               # Magnitude + structured (L1, L2, taylor) + N:M
+├── export/                # ONNX, TensorRT, ORT quantization
+├── benchmark/             # Latency, memory, perplexity, classification, plot
+├── calibration/           # Datasets, dataloaders, observer fitting
+├── models/                # Convenience loaders + registry
+└── cli.py                 # Typer-based CLI
+```
+
+Each algorithm lives in a single, readable file with a `quantize_*` / `prune_*` function and a short docstring referencing the original paper.
+
+## Roadmap
+
+- [x] INT8 dynamic & static PTQ (PyTorch native)
+- [x] FP16/BF16 casting
+- [x] BitsAndBytes INT8 / NF4 / FP4 wrappers
+- [x] GPTQ & AWQ integration
+- [x] L1 structured & magnitude pruning
+- [x] ONNX export with `onnxslim`
+- [x] Latency / memory / perplexity benchmarks
+- [ ] TensorRT INT8 calibration cache
+- [ ] SmoothQuant W8A8
+- [ ] HQQ (Half-Quadratic Quantization)
+- [ ] Distillation-aware quantization
+- [ ] Mobile export (CoreML / TFLite)
+- [ ] Web dashboard for benchmark comparison
+
+## Citing & related work
+
+TurboQuant stands on the shoulders of giants. If you use it in research, please also cite the underlying algorithms:
+
+- **GPTQ** — Frantar et al., 2023 (arXiv:2210.17323)
+- **AWQ** — Lin et al., 2023 (arXiv:2306.00978)
+- **LLM.int8()** / **QLoRA** — Dettmers et al., 2022 / 2023 (arXiv:2208.07339, 2305.14314)
+- **SmoothQuant** — Xiao et al., 2022 (arXiv:2211.10438)
+
+## Contributing
+
+Contributions are very welcome — see [`CONTRIBUTING.md`](docs/CONTRIBUTING.md). Good first issues are tagged on the issue tracker.
+
+```bash
+git clone https://github.com/Ademo93/turboquant
+cd turboquant
+pip install -e ".[dev,all]"
+pre-commit install
+pytest
+```
+
+## License
+
+[MIT](LICENSE) — do whatever you like, just keep the copyright notice.