ShrinkRay User Guide

#Who it's for

Who it's not for (v0.1)

• Anyone who wants a GUI — v0.1 is a terminal tool (a VS Code extension is on the roadmap).
• Anyone who wants to train models — ShrinkRay starts from an already-trained model.
• Anyone deploying to Linux-class edge boxes, phones, or GPUs — ShrinkRay targets microcontroller-class chips (KiB-to-MiB of flash/RAM).
• Models larger than ~100 MB — this is a TinyML tool, not an LLM tool.

#Feature list

#Installation

ShrinkRay needs Python 3.10, 3.11 or 3.12. CPU-only is perfectly fine — no GPU, no cloud. Pick your OS below. Every command ends with the same verification step.

Windows 10/11

1. Install Python from python.org (tick "Add python.exe to PATH") or from the Microsoft Store.
2. Open PowerShell and run:

   py -m pip install shrinkray-cliCopy

   If py isn't recognized, use python -m pip install shrinkray-cli instead.

3. Verify:

   shrinkray --help
   shrinkray chipsCopy

macOS

1. Install Python 3.10–3.12 (via Homebrew: brew install python@3.12, or from python.org).
2. In Terminal:

   python3 -m pip install shrinkray-cliCopy

3. Verify:

   shrinkray --help
   shrinkray chipsCopy

Linux (Debian/Ubuntu/Fedora/…)

1. Make sure Python 3.10–3.12 and pip are installed (sudo apt install python3 python3-pip on Debian/Ubuntu).
2. Install:

   python3 -m pip install shrinkray-cliCopy

   On distros with PEP 668 "externally managed environment", use pipx (below) or a virtual environment.

3. Verify:

   shrinkray --help
   shrinkray chipsCopy

Alternative install methods

#30-second quickstart

shrinkray chips                                # browse the 12-chip database
shrinkray inspect model.keras                  # params, size, ops, FLOPs
shrinkray convert model.keras --target esp32s3 --method int8 --data cal.npyCopy

Output looks like this:

wrote outputs/model_int8.tflite (2.7 KiB)
wrote outputs/model_int8.cc
wrote outputs/model_int8.h
accuracy max-abs-error 0.002717, top-1 agreement 100.0%
esp32s3: ✅ FITS — flash 2.7 KiB / 8192.0 KiB (0.0%), est. RAM 0.1 KiB / 512.0 KiB (0.0%)
wrote outputs/report.md
wrote outputs/report.htmlCopy

--data cal.npy is a small float32 array of representative samples — create it from your training data with one line of NumPy:

import numpy as np
np.save("cal.npy", x_train[:100].astype("float32"))Copy

With calibration data you get full-integer quantization and the accuracy-delta check. Without it, int8 falls back to dynamic-range quantization (still fine, slightly less optimal on-chip).

#Command reference

ShrinkRay has three commands. Run any of them with --help for the built-in summary.

1 · shrinkray inspect <model> — know your model

Shows format, file size, parameter count, estimated FLOPs and an operator/layer histogram — before you convert anything. No target chip needed.

shrinkray inspect gesture.keras

        Model: gesture.keras
┌──────────────────┬───────────┐
│ Property         │ Value     │
├──────────────────┼───────────┤
│ Format           │ keras     │
│ File size        │ 5.2 KiB   │
│ Parameters       │ 12,403    │
│ Estimated FLOPs  │ 24,614    │
└──────────────────┴───────────┘
       Operators / layers
┌───────────────┬───────┐
│ Op            │ Count │
├───────────────┼───────┤
│ Dense         │ 3     │
│ ReLU          │ 2     │
└───────────────┴───────┘Copy

2 · shrinkray chips — browse target hardware

shrinkray chips                     # print all 12 built-in chips
shrinkray chips --chips my.json     # built-ins + your custom chipsCopy

3 · shrinkray convert <model> — shrink it & prove it fits

The main event: converts the model, measures the artifact, estimates peak RAM, prints the fit verdict, and writes the reports.

Examples

# Keras model → int8 C array for an ESP32-S3, with accuracy check
shrinkray convert model.keras --target esp32s3 --method int8 --data cal.npy

# No calibration data → dynamic-range quantization
shrinkray convert model.keras --target stm32u575 --method int8

# Which chips can take this model at all? (ranked table, always exit 0)
shrinkray convert model.keras --all-chips --data cal.npy

# scikit-learn random forest → C99 header (works even on ATmega328P)
shrinkray convert forest.pkl --target nano33ble --method inline

# ONNX → ESP-DL (needs: pip install "shrinkray-cli[espdl]")
shrinkray convert yolo_nano.onnx --target esp32p4

# Custom board not in the database
shrinkray convert model.keras --target myboard --chips mychips.json --data cal.npyCopy

#The 3 pipelines

ShrinkRay picks the pipeline automatically from the file extension — you never choose it yourself. If no pipeline can handle your file, you get a clear error listing what's supported.

Pipeline A — tflite_c · Keras/TFLite → quantized TFLite + C array

The workhorse. Input: .keras, .h5 or .tflite. Output: a quantized .tflite plus a .cc/.h pair containing const unsigned char g_model[] — ready to drop into a LiteRT-M (TFLite Micro) or CMSIS-NN project.

Pipeline B — sklearn_c · scikit-learn → C99 header

Input: a pickled scikit-learn model (.pkl) — trees, forests, small MLPs. Method: inline. Output: a single portable C99 header (via emlearn) with no runtime dependency — small enough for an ATmega328P with 2 KB of RAM.

shrinkray convert forest.pkl --target atmega328p --method inlineCopy

Pipeline C — espdl · ONNX → ESP-DL (optional)

Input: .onnx. Output: Espressif's .espdl format for ESP32 / ESP32-S3 / ESP32-P4, quantized by ESP-PPQ. This pipeline is an optional extra:

pip install "shrinkray-cli[espdl]"Copy

Without the extra, converting an .onnx file prints the install hint and exits with code 2 — every other command keeps working. Nothing breaks, nothing half-installs.

#Chip database

Twelve chips ship built in. The Runtime column is the recommended inference stack for that chip — the reports include matching integration next-steps.

Add your own chip

Create a JSON file and pass it with --chips. Your entries override built-ins when names collide.

// mychips.json
{"chips": [
  {"name": "myboard", "flash_kb": 512, "sram_kb": 128,
   "clock_mhz": 100, "features": ["dsp"], "runtime": "cmsis-nn"}
]}Copy

shrinkray convert model.keras --target myboard --chips mychips.json --data cal.npyCopy

#Fit verdicts — how the decision is made

Two numbers drive every verdict:

• Flash = the actual artifact size, measured on disk. No estimation involved.
• Peak RAM = tensor-liveness analysis of the TFLite graph: ShrinkRay walks the operator graph, tracks which activation tensors are alive at each step, takes the largest concurrently-live sum, and applies a ×1.2 safety factor. It's a solid heuristic — but it is an estimate, not an on-device measurement.

#Reports

Every conversion writes two files into your output directory:

The report is the "proof" half of ShrinkRay: attach it to a PR to show the team exactly what the model costs on the target hardware.

#Config file — shrinkray.toml

Tired of repeating flags? Drop a shrinkray.toml in your project directory:

# shrinkray.toml
[defaults]
target = "esp32s3"
data   = "cal.npy"
out    = "build"Copy

Now a bare shrinkray convert model.keras uses those defaults. Precedence is strict and simple:

CLI flag  ▸  shrinkray.toml  ▸  built-in default

• Only three keys are supported: target, data, out (all strings). Unknown keys or wrong types produce a friendly error, not a crash.
• The file is read from the current working directory — one config per project folder.
• On Python 3.10 you need the tomli package (installed automatically as a dependency); 3.11+ has TOML built in.

#Exit codes & CI usage

Because "doesn't fit" is its own exit code, you can gate CI on model size:

# Fail the build if the model outgrows the chip
shrinkray convert model.keras --target stm32u575 --method int8 --data cal.npy || exit 1Copy

Every error also comes with a Fix: suggestion line telling you the likely remedy — ShrinkRay never just dumps a traceback for expected problems.

#Troubleshooting

#Honest limitations (v0.1)

• No GUI, no training — input is an already-trained model ≤ ~100 MB.
• Pipeline A (Keras → TFLite) requires TensorFlow; everything else — TFLite inspect, sklearn pipeline, chips, reports — works without it.
• RAM figures are estimates (liveness ×1.2), not device measurements. Fit verdicts don't yet subtract the inference runtime's own footprint.
• Quantizing an already-.tflite file is not supported — pass the original Keras model (or --method float).
• Pipeline C requires pip install "shrinkray-cli[espdl]"; without it you get install instructions and exit code 2 — everything else keeps working.
• No ONNX Runtime quantization, no RISC-V paths, no model zoo — planned for later versions.

#FAQ

Is it really free?

Yes — AGPL-3.0 open source. Free for personal and commercial internal use; no account, no telemetry, no network calls, no watermark, no paid tier hiding features. Source-sharing only applies if you distribute ShrinkRay itself or offer it as a service.

Does it need an internet connection?

Only to install. After that, everything runs 100% locally on your machine — your models never leave it.

Do I need a GPU?

No. Quantizing small models is seconds-to-minutes of CPU work. A modest laptop is plenty.

Can I use a PyTorch model?

In v0.1: export to ONNX and use Pipeline C (ESP32-family targets, requires the espdl extra). Broader PyTorch/ExecuTorch support is high on the roadmap.

Which method should I pick?

Start with --method int8 --data cal.npy. If accuracy drops too much, try int16. Use float only as a baseline. For scikit-learn there's just inline — it's already tiny.

How many calibration samples do I need?

50–500 representative samples from real training/validation data are usually enough. More variety matters more than more rows.

The verdict is TIGHT — should I ship it?

Measure on the real device first. TIGHT means the numbers fit on paper within the safety margins; runtime overhead and your firmware's own RAM aren't counted yet.

Where do I report bugs or request chips?

Open an issue on the GitHub repository — chip requests and pipeline requests are welcome and directly drive the roadmap.