Entry Point Plugin Discovery

[speediedan]

Add runtime discovery and import semantics for external StrategyAdapter plugins via Python entry points, a before_restore_model() adapter hook to transform checkpoints prior to restore, and comprehensive documentation & tests for discovery/error handling.

Highlights / What changed

• Implemented entry-point discovery for strategy adapters:
  • New _discover_strategy_adapters() in src/finetuning_scheduler/fts_supporters.py that scans finetuning_scheduler.strategy_adapters entry points and extends the runtime STRATEGY_ADAPTERS mapping.
  • Import semantics accept both module.Class and module:Class forms and prefer short-name aliases when registered.
• Added adapter lifecycle hook:
  • before_restore_model() hook on StrategyAdapter (in src/finetuning_scheduler/strategy_adapters/base.py) allowing adapters to transform/translate a checkpoint before restore.
  • Integrated invocation into FinetuningScheduler.restore flow: self.strategy_adapter.before_restore_model(loaded_ckpt) is called (best-effort, exceptions caught and logged) and the transformed checkpoint is passed to restore_model().
• Configuration/API updates:
  • Accept custom_strategy_adapters (plural) mapping on the FTS constructor and updated import helper _import_strategy_adapter to resolve aliases and fully-qualified names.
• Docs & tests:
  • New docs: docs/source/plugins/strategy_adapter_entry_points.rst explaining custom_strategy_adapters, formats, and examples.
  • Tests added/updated in tests/test_strategy_adapter_discovery.py to cover successful discovery and error branches (ep.load failure, fallback import failure, invalid formats).
  • Test helpers: tests/helpers/fake_adapter.py and tests/helpers/expected_warns.py updates. Tests use MagicMock for EntryPoint-style objects to accommodate Python 3.12 immutability and simulate ep.load() side effects.
• Misc: minor housekeeping across fts_supporters.py, fts.py, strategy adapters, and docs indices.
• Infrastructure updates (torch-nightly.txt → torch-pre.txt for flexible prerelease channel support)

Files touched (non-exhaustive)

• src/finetuning_scheduler/fts_supporters.py
• src/finetuning_scheduler/strategy_adapters/base.py
• src/finetuning_scheduler/fts.py
• tests/test_strategy_adapter_discovery.py
• tests/test_finetuning_scheduler_callback.py
• tests/helpers/fake_adapter.py
• docs/source/plugins/strategy_adapter_entry_points.rst

Motivation

• Allow third-party or user-installed strategy adapters to be discovered and registered via standard Python packaging entry points so users can provide adapters without modifying library source.
• Enable adapters to perform strategy-specific checkpoint transformations (e.g., key expansion, mapping for TransformerBridge) before the library restores a model.
• Improve robustness and documentation for adapter import semantics and error handling.

Migration / Backwards compatibility

• custom_strategy_adapters is now accepted in plural form and the import helper accepts both module.Class and module:Class. Existing single-entry configurations should continue to work but authors are encouraged to adopt the plural mapping form for clarity.
• before_restore_model() is an optional hook; existing adapters that don't implement it will be unaffected.

Testing

• New tests verify discovery behavior, supported import formats, and error/fallback branches for EntryPoint.load() and imports.
• Tests include a fake adapter helper and use MagicMock to simulate EntryPoint objects and ep.load() side effects for Python 3.12 compatibility.

Documentation

• Added docs/source/plugins/strategy_adapter_entry_points.rst describing the entry-point format, examples, and how to reference adapters via alias or fully-qualified name.
• Updated fts docstrings to reference the new docs and usage patterns.

[Copilot]

Pull request overview

This pull request implements entry point plugin discovery for strategy adapters, enabling third-party packages to extend FTS with custom adapters. Key changes include:

Summary: Adds runtime discovery and import semantics for external StrategyAdapter plugins via Python entry points, a before_restore_model() adapter hook for checkpoint transformation, configuration updates (plural custom_strategy_adapters), and comprehensive documentation and tests.

Key Changes:

• Plugin discovery system via Python entry points (finetuning_scheduler.strategy_adapters group)
• New before_restore_model() lifecycle hook for checkpoint transformation
• Refactored parameter naming (singular custom_strategy_adapter → plural custom_strategy_adapters)
• Comprehensive test coverage for discovery, import formats, and error handling
• New documentation explaining plugin registration and usage
• Infrastructure updates (torch-nightly.txt → torch-pre.txt for flexible prerelease channel support)

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/test_strategy_adapter_discovery.py	New comprehensive test suite for plugin discovery and resolution
tests/test_finetuning_scheduler_callback.py	Tests for deprecation warning and adapter exception handling
tests/helpers/fake_adapter.py	Simple test fixture adapter class
src/finetuning_scheduler/fts_supporters.py	Core discovery function and adapter resolution logic
src/finetuning_scheduler/fts.py	Integration of discovery call and before_restore_model hook
src/finetuning_scheduler/strategy_adapters/base.py	New adapter lifecycle methods and delegation points
src/finetuning_scheduler/strategy_adapters/init.py	Plugin usage documentation in module docstring
docs/source/plugins/strategy_adapter_entry_points.rst	Complete plugin development guide
scripts/build_fts_env.sh, scripts/gen_fts_coverage.sh	Torch prerelease channel refactoring
requirements/ci/torch-pre.txt	New unified prerelease configuration (test/nightly)
pyproject.toml	Informational minimum version metadata section

Comments suppressed due to low confidence (1)

src/finetuning_scheduler/fts_supporters.py:1237

• The docstring for this method mentions a parameter named qualname but the actual parameter is named strategy_key. The Args section should document strategy_key and adapter_map instead.

        """Resolve the custom strategy adapter specified in the ``custom_strategy_adapters`` configuration.

        Args:
            qualname (Dict): The user-provided custom strategy adapter fully qualified class name.

        Raises:
            MisconfigurationException: If the specified custom strategy adapter cannot be imported successfully.
            MisconfigurationException: If the specified `strategy_key` does not match the current strategy.

        Returns:
            StrategyAdapter: The custom strategy adapter class to be instantiated.