ml_switcheroo.cli.handlers

CLI handlers module.

Exposes individual command handler functions aggregated by domain.

Submodules

Functions

handle_scaffold(→ int)

Handles the 'scaffold' command.

handle_import_spec(→ int)

Handles the 'import-spec' command.

handle_sync_standards(→ int)

Handles 'sync-standards' command.

handle_snapshot(→ int)

Handles the 'snapshot' command.

handle_sync(→ int)

Handles the 'sync' command.

handle_wizard(→ int)

Handles the 'wizard' command for interactive mapping discovery.

handle_harvest(→ int)

Handles the 'harvest' command to learn mappings from manual tests.

handle_ci(→ int)

Handles 'ci' command.

handle_matrix(→ int)

Handles 'matrix' command.

handle_docs(→ int)

Handles 'gen-docs' command.

handle_gen_tests(→ int)

Handles 'gen-tests' command.

Package Contents

ml_switcheroo.cli.handlers.handle_scaffold(frameworks: list[str], out_dir: pathlib.Path) → int

Handles the ‘scaffold’ command.

  • Iterates through provided frameworks.

  • Uses FrameworkAdapter.discovery_heuristics regexes to fuzzy match framework APIs against known specs or structural conventions.

  • Populates semantic specs (Hub) and framework mappings (Spokes/Snapshots).

Parameters:

  • frameworks (list[str]) – List of framework package names to scaffold (e.g., [‘torch’, ‘jax’]).

  • out_dir (Path) – The root directory for generating the knowledge base. Defaults to the package source if None.

Returns:

Exit code.

Return type:

int

ml_switcheroo.cli.handlers.handle_import_spec(target: pathlib.Path) → int

Handles the ‘import-spec’ command.

Parses upstream standards documentation or stubs and merges the definitions into the local semantics Hub.

Parameters:

target (Path) – .md file, .html file, or directory to parse.

Returns:

Exit code.

Return type:

int

ml_switcheroo.cli.handlers.handle_sync_standards(categories: List[str], frameworks: List[str] | None, dry_run: bool) → int

Handles ‘sync-standards’ command.

Invokes the Consensus Engine to automatically discover new Abstract Operations by finding commonalities across multiple framework API surfaces. Writes the results to k_discovered.json (The Unofficial/Discovered Standard).

Parameters:

  • categories (List[str]) – List of category strings (layer, loss, etc.) to scan.

  • frameworks (Optional[List[str]]) – List of framework keys to scan. Defaults to installed/registered frameworks.

  • dry_run (bool) – If True, prints results without saving.

Returns:

Exit code.

Return type:

int

ml_switcheroo.cli.handlers.handle_snapshot(out_dir: pathlib.Path | None) → int

Handles the ‘snapshot’ command.

Scans installed frameworks and dumps their API signatures to JSON files. These snapshots allow the engine to operate in “Ghost Mode” (e.g., in WebAssembly) without requiring the heavy frameworks to be installed.

Parameters:

out_dir – Optional custom output directory. Defaults to package/snapshots.

Returns:

Exit code (0 for success, 1 for failure).

ml_switcheroo.cli.handlers.handle_sync(framework: str) → int

Handles the ‘sync’ command.

Links the Abstract Standards (Hub) to the concrete implementation in a specific framework. This process involves: 1. Reading the Specs from semantics/. 2. Introspecting the installed framework to find matching APIs. 3. Merging Static Definitions from the Adapter (for Ghost support). 4. Applying Adapter-specific manual wiring (plugins, templates). 5. Persisting Test Configuration templates. 6. Writing the results to the Snapshot Overlay (snapshots/{fw}_mappings.json).

Parameters:

framework – The framework key to sync (e.g. ‘torch’, ‘jax’).

Returns:

Exit code (0 for success, 1 for failure).

ml_switcheroo.cli.handlers.handle_wizard(package: str) → int

Handles the ‘wizard’ command for interactive mapping discovery.

Parameters:

package – The name of the python package to inspect (e.g., ‘torch’).

Returns:

Exit code (0 for success).

Return type:

int

ml_switcheroo.cli.handlers.handle_harvest(path: pathlib.Path, target: str, dry_run: bool) → int

Handles the ‘harvest’ command to learn mappings from manual tests.

Parameters:

  • path – File or directory containing python test files.

  • target – The framework target used in the tests (e.g., ‘jax’).

  • dry_run – If True, prints changes without writing to disk.

Returns:

Exit code (0 for success, 1 for path errors).

Return type:

int

ml_switcheroo.cli.handlers.handle_ci(update_readme: bool, readme_path: pathlib.Path, json_report: pathlib.Path | None, repair: bool = False) → int

Handles ‘ci’ command.

Parameters:

  • update_readme – If True, updates the compatibility matrix in the README.

  • readme_path – Path to the README file.

  • json_report – Optional path to dump results JSON.

  • repair – If True, attempts to automatically relax tolerances for failing tests via bisection.

Returns:

Exit code (0 on success, 1 on error).

Return type:

int

ml_switcheroo.cli.handlers.handle_matrix() → int

Handles ‘matrix’ command. Prints the compatibility table to stdout.

Returns:

0 on success.

Return type:

int

ml_switcheroo.cli.handlers.handle_docs(source: str, target: str, out_path: pathlib.Path) → int

Handles ‘gen-docs’ command. Generates a migration guide Markdown file.

Parameters:

  • source – Source framework key.

  • target – Target framework key.

  • out_path – Output file path.

Returns:

0 on success.

Return type:

int

ml_switcheroo.cli.handlers.handle_gen_tests(out: pathlib.Path) → int

Handles ‘gen-tests’ command. Generates physical test files for known APIs.

Parameters:

out – Output file path.

Returns:

0 on success.

Return type:

int