Enhance engine creation API, update README

[kprokofi]

Summary

This PR enhances the create_engine() entry point to support creating engines from recipe YAML files and bare model names (in addition to the existing model-instance and weight-path dispatch). It also consolidates recipe-discovery utilities under getitune.utils, unifies engine constructor APIs, fixes a cross-backend checkpoint corruption bug, and adds unit tests.

Key Changes
New capabilities in create_engine() (getitune.engine.utils.create):

• Recipe path resolution: Pass a .yaml recipe file directly — the backend field in the YAML dictates which engine (UltralyticsEngine, LightningEngine, or OVEngine) instantiates.
• Model name resolution: Pass a bare model name (e.g. "yolo26_n") — the recipe tree under src/getitune/recipe/ is searched. Ambiguous names (matching multiple tasks) raise a ValueError listing candidates; pass task= to disambiguate.
• Backend dispatch: Reads the backend field from the recipe YAML and routes to the appropriate engine's from_config().

Unified engine API:

• Engine.from_config() — new base-class hook with explicit work_dir, device, checkpoint, task parameters. Every backend (LightningEngine, UltralyticsEngine, OVEngine) implements it.
• UltralyticsEngine now has a from_config() that builds a Configurator, creates a DataModule and model, and instantiates the engine.
• LightningEngine from_config(): renamed data_root → data, refactored argument routing to avoid kwargs hacks.
• work_dir made Optional across constructors so None flows through and the default applies at the init level.
  Checkpoint bug fix (cross-backend corruption):
• LightningEngine.train() previously created best_checkpoint.pt as a symlink → checkpoints/epoch_NNN.ckpt. When UltralyticsEngine subsequently trained and called shutil.copyfile on best_checkpoint.pt, it followed the symlink and overwrote the Lightning .ckpt file with YOLO weights — then recorded the .ckpt path, causing YOLO(...) to treat the model as a string (crash on predict()).
• Fix: Lightning now copies instead of symlinking; Ultralytics now unlinks any pre-existing symlink before copying and stores the canonical path without resolving symlinks.
  Recipe-discovery consolidation:
• list_models, RECIPE_PATH, get_getitune_root_path moved from getitune.backend.lightning.cli.utils to getitune.utils.recipes — eliminates a circular import.
• getitune.backend.lightning.cli/ directory deleted — was only a re-export shim.
• All public API now uses from getitune.utils import list_models.
  Ultralytics model classes exported:
• UltralyticsDetectionModel and UltralyticsInstSegModel added to getitune.models.init with optional import guard.
  Tests:
• 12 new unit tests in tests/unit/engine/test_engine.py covering recipe path resolution, model name resolution, ambiguity errors, task disambiguation, backend dispatch, and error cases.
• Existing tests updated for the new create_engine behavior and API changes.

Additionally, this PR changes README for library

from getitune.engine import create_engine
# Pass a recipe .yaml directly — the backend field inside the YAML
# determines which engine instantiates.
engine = create_engine(
    model="src/getitune/recipe/detection/yolo26_n.yaml",
    data="path/to/coco_dataset",
)

Create an engine from a bare model name

from getitune.engine import create_engine
# The library resolves "yolox_s" to the matching recipe under
# src/getitune/recipe/detection/.
engine = create_engine(
    model="yolox_s",
    data="path/to/coco_dataset",
    work_dir="./my_experiment",
    device="auto",
)

How to test

Checklist

• The PR title and description are clear and descriptive
• I have manually tested the changes
• All changes are covered by automated tests
• All related issues are linked to this PR (if applicable)
• Documentation has been updated (if applicable)

[Copilot]

Pull request overview

This PR refactors and expands the getitune engine-creation entry point to support creating engines from model names and recipe YAMLs (in addition to model instances / weight paths), centralizes recipe-discovery utilities under getitune.utils, and updates user-facing documentation accordingly.

Changes:

• Added getitune.engine.utils.create_engine() with recipe/model-name resolution and backend dispatch via the recipe’s backend field; re-exported it from getitune.engine.
• Updated Lightning/Utralytics/OpenVINO engines to align with the enhanced creation API (from_config, data naming, optional work_dir handling).
• Updated tests and docs to import recipe utilities from getitune.utils and refreshed the library README with the new API guidance.

Reviewed changes

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

Show a summary per file

File	Description
library/tests/unit/backend/lightning/utils/test_imports.py	Updates imports to use getitune.utils.
library/tests/unit/backend/lightning/utils/test_api.py	Updates imports to use getitune.utils.
library/tests/unit/backend/lightning/test_engine.py	Updates API calls to use data= instead of data_root=.
library/tests/perf_v2/benchmark.py	Updates RECIPE_PATH import and data= argument naming.
library/tests/integration/conftest.py	Updates get_getitune_root_path import to getitune.utils.
library/tests/integration/api/test_xai.py	Updates Lightning engine creation to use data=.
library/tests/integration/api/test_engine.py	Updates Lightning engine creation to use data=.
library/src/getitune/utils/recipes.py	Refreshes header/docstrings; keeps recipe discovery utilities.
library/src/getitune/utils/init.py	Re-exports RECIPE_PATH, get_getitune_root_path, list_models.
library/src/getitune/tools/auto_configurator.py	Switches recipe utilities import to getitune.utils.
library/src/getitune/models/init.py	Makes Ultralytics model exports optional (ImportError-guarded).
library/src/getitune/engine/utils/create.py	New: implements enhanced create_engine (model-name + recipe support).
library/src/getitune/engine/utils/init.py	Exposes create_engine from the engine utils package.
library/src/getitune/engine/engine.py	Adds a base Engine.from_config() API hook (default: NotImplemented).
library/src/getitune/engine/init.py	Re-exports create_engine from getitune.engine.utils.
library/src/getitune/cli/cli.py	Updates CLI “find” path to import list_models from getitune.utils.
library/src/getitune/benchmark/manifest.py	Updates RECIPE_PATH import to getitune.utils.
library/src/getitune/benchmark/experiment.py	Updates Lightning engine creation to use data=.
library/src/getitune/backend/ultralytics/tools/configurator.py	Avoids runtime circular import; makes work_dir optional.
library/src/getitune/backend/ultralytics/engine.py	Adds from_config() for Ultralytics recipes; makes work_dir optional.
library/src/getitune/backend/openvino/engine.py	Adds from_config() that explicitly raises NotImplementedError.
library/src/getitune/backend/lightning/engine.py	Renames data_root → data and refactors from_config() argument routing.
library/src/getitune/backend/lightning/cli/init.py	Deleted (utility exports moved to getitune.utils).
library/README.md	Updates installation + API docs for enhanced engine creation.
library/docs/source/guide/tutorials/base/how_to_train/semantic_segmentation.rst	Updates list_models import to getitune.utils.
library/docs/source/guide/tutorials/base/how_to_train/instance_segmentation.rst	Updates list_models import to getitune.utils.
library/docs/source/guide/tutorials/base/how_to_train/detection.rst	Updates list_models import to getitune.utils.
library/docs/source/guide/tutorials/base/how_to_train/classification.rst	Updates list_models import to getitune.utils.
library/docs/source/guide/get_started/api_tutorial.rst	Updates list_models import to getitune.utils.

[github-actions]

📊 Test coverage report

Metric	Coverage
Lines	57.0%
Functions	53.9%
Branches	48.6%
Statements	56.6%

[github-actions]

🐳 Docker image sizes

Device	Size
xpu	10791.7 MB (10.54 GB)
cpu	4003.1 MB (3.91 GB)
cuda	10208.5 MB (9.97 GB)

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 75.00000% with 38 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
library/src/getitune/backend/ultralytics/engine.py	34.61%	17 Missing ⚠️
library/src/getitune/backend/lightning/engine.py	67.85%	9 Missing ⚠️
library/src/getitune/engine/utils/create.py	91.86%	7 Missing ⚠️
library/src/getitune/backend/openvino/engine.py	50.00%	2 Missing ⚠️
library/src/getitune/engine/engine.py	50.00%	2 Missing ⚠️
library/src/getitune/cli/cli.py	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

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