[presentyourlove]

Description

This PR resolves item 8 in TODO.md: If model folder exists, load directly without checking anything (allows using models without internet connection).

Background & Motivation

Previously, Exo attempted to fetch the model's file list from HuggingFace even if the model was already fully downloaded locally. If internet was unavailable:

1. fetch_file_list_with_cache would fall back to _build_file_list_from_local_directory.
2. However, _scan_model_directory strictly required a *.safetensors.index.json file.
3. For standalone models, single .safetensors / .gguf weights, or copied/offline model folders lacking an explicit index JSON, _scan_model_directory returned None, triggering a fatal FileNotFoundError: No internet connection and no cached file list for <model_id>.

This prevented users from running models in air-gapped environments, private subnets, or using pre-downloaded model folders.

Key Changes

1. Model Folder Readiness Detection (is_local_model_folder_ready):

   • Added validation in src/exo/download/download_utils.py to check that a model directory is non-empty, contains recognized model artifacts (.safetensors, .bin, .pt, .gguf, .onnx, config.json, etc.), and contains no incomplete download fragments (.partial files).
   • Added has_partial_files helper to quickly detect in-progress or corrupted downloads.

2. Standalone & Copied Directory Scanning (_scan_model_directory):

   • Expanded _scan_model_directory into two complementary branches:
     • Branch A (Sharded Index Models): Retains existing logic for reading *.safetensors.index.json when present.
     • Branch B (Offline/Copied Model Directories - TODO Is windows supported ? #8): When no index file is present, scans the local files directly and populates FileListEntry objects with actual file sizes via filesystem stats. If any .partial file is encountered, scanning safely aborts (returning None) to prevent loading half-downloaded weights.

3. Offline File List Cache Persistence:

   • When offline fallback constructs a valid file list from a ready local directory, the result is automatically persisted to {model_id}--{revision}--file_list.json in the cache folder. Subsequent launches bypass filesystem re-scanning.

4. Unit Tests (src/exo/download/tests/test_offline_model_loading.py):

   • Added 5 comprehensive test cases covering:
     • test_has_partial_files: In-progress fragment detection.
     • test_is_local_model_folder_ready: Validation of complete vs. empty/non-model directories.
     • test_scan_model_directory_offline_copy_without_index: Correct file list assembly for index-less offline models.
     • test_scan_model_directory_with_partial_file_fails: Safety rejection when partial downloads exist.
     • test_fetch_file_list_with_cache_offline_fallback: End-to-end verification of offline loading without internet and cache generation.

Verification

• Unit Tests:

  .venv/Scripts/pytest.exe src/exo/download/tests/test_offline_model_loading.py -v
  # 5 passed in 1.46s

• Existing Download Suite Compatibility:

  .venv/Scripts/pytest.exe src/exo/download/tests/test_model_dirs.py src/exo/download/tests/test_offline_mode.py src/exo/download/tests/test_safetensors_index.py src/exo/download/tests/test_offline_model_loading.py -v
  # 36 passed in 1.67s

• Code Linting:

  .venv/Scripts/ruff.exe check src/exo/download/tests/test_offline_model_loading.py
  # All checks passed!

Related Issues

• Resolves: Item 8 in TODO.md (If model folder exists, load directly without checking anything (allows using models without internet connection))