a48988ccb3
* chore: sync tinygrad Runs great in sim. now we need to rebuild some models * oops forgot to unblock this after testing * helpers * oh yeah * latest tg * this wont do anything empriically * reduce complexity * okay lint * Update tinygrad_runner.py * Update modeld.py * Update build-all-tinygrad-models.yaml * tinygrad bump * Update modeld.py * Update tinygrad_runner.py * bump * Update SConscript * Update SConscript * com * Update fetcher.py * Update helpers.py * Update model_runner.py * Update model_runner.py --------- Co-authored-by: Jason Wen <haibin.wen3@gmail.com>
Model Selector Version Compatibility
This document explains the version compatibility mechanism used by the Model Selector system, and the rationale behind certain version constraints and JSON file management strategies.
Overview
The Model Selector is responsible for selecting and validating model bundles based on their metadata and version constraints. Each model bundle is distributed via a JSON file and includes a minimumSelectorVersion field indicating the minimum selector version required to load it.
To ensure robust compatibility and prevent mismatches between model expectations and selector capabilities, the selector enforces two version boundaries:
REQUIRED_MIN_SELECTOR_VERSION: the oldest selector version we support.CURRENT_SELECTOR_VERSION: the current version of the selector logic.
Version Compatibility Check
A model bundle is considered compatible if:
REQUIRED_MIN_SELECTOR_VERSION <= bundle["minimumSelectorVersion"] <= CURRENT_SELECTOR_VERSION
This ensures:
- Old bundles are rejected if they rely on deprecated selector behavior.
- Future bundles are ignored if they expect logic that the current selector doesn't yet implement.
Handling Breaking Changes
When a deep change in selector behavior requires all models to be recompiled (e.g., due to a major architectural update), we:
- Create a new JSON file (e.g., from
models_v4.jsontomodels_v5.json). - Assign updated
minimumSelectorVersionvalues in the new bundles.
This allows older selector versions to continue using the previous JSON file, while newer versions point to the new one, preventing cross-contamination.
Why REQUIRED_MIN_SELECTOR_VERSION Still Matters
Despite using new JSON files to isolate breaking changes, REQUIRED_MIN_SELECTOR_VERSION plays a critical role:
1. Cached Bundle Validation
Model bundles are cached locally (e.g., in-memory or on disk). A user might have previously loaded a now-invalid bundle from an older JSON file.
REQUIRED_MIN_SELECTOR_VERSION prevents the selector from reloading or trusting that stale cached bundle, even if the original JSON is gone.
2. Explicit Deprecation Boundary
By raising REQUIRED_MIN_SELECTOR_VERSION, we declare older bundles officially unsupported, even if they technically still exist in a legacy JSON file.
3. Avoiding Race Conditions
Some clients may have intermittent access to updated JSONs. The runtime check ensures version compatibility is enforced independently of external file state.
Summary
| Component | Purpose |
|---|---|
minimumSelectorVersion |
Declares the minimum selector version required to load a model bundle |
REQUIRED_MIN_SELECTOR_VERSION |
Prevents loading bundles that are too old (e.g., from stale cache) |
CURRENT_SELECTOR_VERSION |
Prevents loading bundles that are too new or forward-incompatible |
| JSON file renaming | Isolates bundles by selector generation to handle full recompiles |
This layered strategy ensures safe evolution of the model selection system while maintaining backward compatibility and runtime protection against stale or incompatible bundles.