ADR-001: Rust Core + Python Plugins via PyO3¶

Status: Accepted
Date: 2026-05-18
Deciders: Mohsen Seyedkazemi Ardebili

Context¶

YazSes v0.4 is implemented in Python 3.11, but the v1.0 goals of single-binary distribution, idle RSS below 80 MB, and zero Python-version-conflict install errors are difficult to achieve with a Python core. The whisper.cpp and llama.cpp ecosystem — the architectural gold standard for on-device AI daemons — demonstrates that Rust (or C/C++) delivers these properties in production. At the same time, the plugin ecosystem (editor bridges, command grammars, LoRA adapter authors) benefits from Python's ergonomics and community familiarity.

Decision¶

The v1.0 core — orchestrator, IPC server, input handling, LLM and STT FFI, dispatcher, and personal memory — is implemented in Rust. Python plugins are supported via embedded PyO3, gated behind a python-plugins cargo feature. If no Python interpreter is present, the core operates Python-free; plugins simply do not load.

Crate layout: yazses-core (orchestrator), yazses-llm-llamacpp, yazses-llm-mlx, yazses-stt-whispercpp, yazses-stt-onnx, yazses-memory, and yazses-plugins-python. Distribution is handled by cargo-dist (see ADR-008).

Consequences¶

Positive: - Single static binary per platform; idle RSS targets 20–40 MB instead of 80–120 MB. - No Python-version-conflict errors for users who do not install plugins. - Memory-safe, type-safe core with deterministic concurrency via Tokio async runtime. - llama.cpp, whisper.cpp, and sqlite-vec all have maintained first-class Rust bindings.

Negative / trade-offs: - Migration from Python to Rust spans multiple subsystems and is estimated at 4–6 person-months of focused engineering. - Contributors familiar only with Python face a higher barrier to core contributions. - Some primitives (Outlines, sentence-transformers) lack mature Rust equivalents; they remain in the embedded Python plugin layer for v1.0. - The cross-compilation matrix (five targets) is non-trivial even with cargo-dist handling most of it.

Implementation¶

The Rust workspace lives at the repo root (Cargo.toml). Core orchestration is in yazses-core/src/. FFI adapters are in their respective crates under crates/. Python plugin loading is in yazses-plugins-python/src/ and is compiled only when the python-plugins feature is enabled. The v0.4 Python codebase serves as integration-test material during migration.