Symusic Dependency Taste

Symusic Dependency Taste and Selection Framework

Use this skill when adding, replacing, or auditing dependencies.

High-Level Dependency Philosophy

1. Prefer focused libraries with clear performance or ergonomics wins.

   • Symusic favors small, purpose-built components (parser, serializer, binding layer) over heavy frameworks.

2. Keep the dependency surface narrow and intentional.

   • Every added dependency increases wheel complexity, ABI risk, cross-platform CI cost, and maintenance burden.

3. Keep core competency in-repo; outsource commodity building blocks.

   • MIDI-domain semantics and transformation logic should stay first-party.
   • Generic concerns (formatting, UTF-8 helpers, serialization primitives) can be external.

4. Choose libraries that align with cross-platform wheels and modern toolchains.

   • Compatibility with C++20, Python 3.9+ wheels, and reproducible CI builds is non-negotiable.

Existing Stack Taste Analysis

C++/Core Dependencies

• minimidi: chosen for fast and lightweight MIDI parsing; tightly aligned with symusic's core mission.
• prestosynth: dedicated synthesis backend for SoundFont rendering, consistent with a focused audio-rendering layer.
• pyvec: optimized container bridge that complements shared-pointer semantics and Python interop patterns.
• nanobind: modern, efficient C++/Python binding layer; matches performance-first and typed API goals.
• fmt: pragmatic formatting utility that improves clarity and maintainability over manual string assembly.
• zpp_bits (header-only include): lightweight serialization building block for pickle support.
• utfcpp + small utility headers (unordered_dense, macros): low-level helpers kept lean and local where practical.

Taste signal: this is a deliberately modular high-performance stack with minimal overlap between libraries.

Python Runtime Dependencies

• numpy: foundational numerical ecosystem choice; necessary for array-oriented conversions and interoperability.
• pySmartDL: targeted utility for managed downloads in soundfont workflows.
• platformdirs: minimal, standard choice for per-platform cache/config path correctness.

Taste signal: runtime Python dependencies are intentionally few, stable, and functionally justified.

Test/Dev Dependencies

• pytest, pytest-cov, pytest-xdist: standard, scalable Python testing stack.
• mypy, ruff configuration in pyproject.toml: static and style guardrails with pragmatic exceptions.
• pretty_midi (optional test extra): used as ecosystem interop/reference check rather than core runtime requirement.

Taste signal: strong quality automation, but optional extras remain clearly separated from runtime essentials.

Dependency Decision Rubric (Use Before Adding Anything New)

A candidate dependency should pass all gates:

1. Problem clarity: Is there a repeated, non-trivial problem not already solved in-repo?
2. Scope fit: Does the library solve exactly that problem without pulling broad framework baggage?
3. Performance profile: Any predictable hot-path cost, memory overhead, or startup regression?
4. Build/distribution impact: Does it complicate wheels, ABI compatibility, or CI matrix reliability?
5. Maintenance health: Active releases, clear license, issue responsiveness, and transparent governance?
6. Fallback plan: Can we pin, patch, or replace it safely if upstream breaks?

If any gate fails, prefer a smaller alternative or an internal implementation.