feat: Auto-clear SSD cache on model unload

[afanty2021]

Summary

Add automatic SSD cache clearing when models are unloaded, useful for benchmarking scenarios where cache persistence across model loads is not needed.

Problem

When running multiple models in sequence for benchmarking:

• Each model leaves SSD cache behind after unloading
• Subsequent models write new cache, causing "SSD write queue full" warnings
• Cache interference can affect benchmark results

2026-04-21 06:29:19,224 - omlx.cache.paged_ssd_cache - WARNING - SSD write queue full, dropping evicted block c127f0c289fba682

Solution

Add a clear_ssd_cache_on_unload configuration option that:

• Clears SSD cache before engine stop during model unload
• Is disabled by default (backward compatible)
• Can be enabled via CLI flag, environment variable, or config file

Changes

Configuration

• CLI flag: --paged-ssd-cache-clear-on-unload
• Environment variable: OMLX_PAGED_SSD_CACHE_CLEAR_ON_UNLOAD
• Config file: clear_on_unload in paged_ssd_cache section

Implementation

• Modified _unload_engine() in omlx/engine_pool.py
• Clears SSD cache before stopping the engine
• Safe attribute access with exception handling
• Comprehensive test coverage (3 new tests)

Usage

# Enable auto-clear (recommended for benchmarking)
omlx serve --model-dir ~/models --paged-ssd-cache-clear-on-unload

# Environment variable
export OMLX_PAGED_SSD_CACHE_CLEAR_ON_UNLOAD=true
omlx serve --model-dir ~/models

# Config file (~/.omlx/settings.json)
{
  "paged_ssd_cache": {
    "clear_on_unload": true
  }
}

Test plan

• Unit tests pass (3 new tests in test_engine_pool.py)
• Configuration parsing works correctly
• CLI argument parsing works correctly
• Manual testing with multiple model loads/unloads
• Documentation added (docs/CLEAR_SSD_CACHE_ON_UNLOAD.md)

Breaking changes

None. This feature is opt-in and disabled by default.

Checklist

• Code follows project style guidelines
• Tests added/updated
• Documentation updated
• No breaking changes

🤖 Generated with Claude Code