The include_str!() Pattern — Embedding Python ML in a Rust Binary

A pattern discovered in Nightingale (Rust karaoke app). A practical architecture for handling Python ML stacks from Rust.

The Problem: Running Python ML from Rust

Nightingale needs UVR/Demucs (vocal separation) and WhisperX (speech recognition). Both are PyTorch-based and only work properly in Python.

Typical options and their problems:

Depend on system Python — version conflicts, package collisions, "works on my machine" syndrome.

Ship .py files separately — file loss, path issues, users accidentally deleting scripts.

PyO3 Rust↔Python bindings — fine for simple functions, but binding heavy ML stacks (PyTorch + WhisperX + audio-separator) is dependency hell.

Rewrite everything in Rust — impractical. ML ecosystem (PyTorch, Hugging Face, ONNX Runtime) is Python-centric.

Nightingale's Solution: include_str!() + Persistent Process

const STEMS_PY: &str = include_str!("../analyzer/stems.py");
const SERVER_PY: &str = include_str!("../analyzer/server.py");
// ... 10 Python files

Rust's include_str!() macro includes file contents as string constants at compile time. Not runtime file reading.

How It Works

Build time: cargo build embeds 10 .py files as strings → single binary output.

First launch (bootstrap): Create ~/.nightingale/vendor/ → extract .py strings to files → install Python 3.10 via uv → create venv → install PyTorch, WhisperX → write .ready marker.

Analysis: Rust spawns server.py as child process → Python loads WhisperX model → waits → Rust sends JSON via stdin → Python responds via stdout → server stays alive for next song.

5 Benefits

1. Single binary distribution — one file to ship.

2. Zero version mismatch — Rust and Python code from same commit.

3. Tamper-proof — users can't accidentally modify embedded scripts.

4. Persistent Python server — ML models stay loaded between songs. CUDA OOM? Kill and respawn without crashing the app.

5. Simple JSON communication — no FFI complexity, easy debugging.

When This Pattern Fits

• Python-dominant domains (ML inference)

• Low call frequency (per-song, not per-millisecond)

• Negligible IPC overhead

• Desktop apps where deployment simplicity matters

When It Doesn't Fit

• Thousands of calls per second → use PyO3 or ONNX Runtime Rust bindings

• Hundreds of Python files → binary bloat

• Bidirectional streaming → use gRPC or sockets

Core Insight

"Let Python do what Python does best (ML), but let Rust control deployment and orchestration." Instead of cramming both languages into one process via FFI, separate processes but bundle deployment. Low coupling, low deployment complexity.