ml_switcheroo.cli.commands

CLI Command Handlers Facade.

This module primarily re-exports handlers from ml_switcheroo.cli.handlers to maintain backward compatibility with existing tests and imports. Must remain synced with handler modules.

Functions

handle_audit(→ int)

Scans a directory/file to determine coverage against the Knowledge Base.

handle_convert(→ int)

Handles the 'convert' command execution.

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.

resolve_semantics_dir(→ pathlib.Path)

Locates the directory containing semantic JSON definitions.

resolve_snapshots_dir(→ pathlib.Path)

Locates the directory containing framework snapshots and mapping overlays.

handle_gen_weight_script(→ int)

Handler for generating weight migration script.

Module Contents

ml_switcheroo.cli.commands.handle_audit(path: pathlib.Path, source_frameworks: List[str], json_mode: bool = False) → int

Scans a directory/file to determine coverage against the Knowledge Base.

Parameters:

  • path – Input source file or directory.

  • source_frameworks – List of framework keys to scan for.

  • json_mode – If True, output JSON to stdout and suppress Rich logs.

Returns:

Exit code (0 if audit reveals full coverage, 1 if missing ops).

Note: In audit mode, missing ops might be considered a ‘failure’.

Return type:

int

ml_switcheroo.cli.commands.handle_convert(input_path: pathlib.Path, output_path: pathlib.Path | None, source: str | None, target: str | None, verify: bool, strict: bool | None, intermediate: str | None, plugin_settings: Dict[str, Any], json_trace_path: pathlib.Path | None = None) → int

Handles the ‘convert’ command execution.

Orchestrates the loading of configuration, initialization of the semantic knowledge base, and the execution of the transpilation engine on files or directories.

Parameters:

  • input_path – Path to the source file or directory to convert.

  • output_path – Path where generated code should be saved.

  • source – Override for source framework (e.g. ‘torch’).

  • target – Override for target framework (e.g. ‘jax’).

  • verify – If True, generates and runs a verification harness test immediately.

  • strict – If True, enforces strict strict_mode on the Engine.

  • intermediate – If provided, forces a roundtrip via this IR (e.g. ‘mlir’).

  • plugin_settings – Dictionary of specific plugin configuration flags.

  • json_trace_path – Optional path to dump execution trace JSON.

Returns:

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

Return type:

int

ml_switcheroo.cli.commands.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.commands.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.commands.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.commands.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.commands.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.commands.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.commands.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.commands.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.commands.handle_matrix() → int

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

Returns:

0 on success.

Return type:

int

ml_switcheroo.cli.commands.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.commands.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

ml_switcheroo.cli.commands.resolve_semantics_dir() → pathlib.Path

Locates the directory containing semantic JSON definitions.

Prioritizes the local file system (relative to this file) to ensure tests and editable installs find the source of truth correctly. Falls back to package resources for installed distributions.

Returns:

The absolute path to the ‘semantics’ directory.

Return type:

Path

ml_switcheroo.cli.commands.resolve_snapshots_dir() → pathlib.Path

Locates the directory containing framework snapshots and mapping overlays. Defaults to the sibling ‘snapshots’ directory relative to ‘semantics’.

Returns:

The absolute path to the ‘snapshots’ directory.

Return type:

Path

ml_switcheroo.cli.commands.handle_gen_weight_script(source_file: pathlib.Path, out_script: pathlib.Path, source_fw: str | None = None, target_fw: str | None = None) → int

Handler for generating weight migration script.

Delegates to the WeightScriptGenerator class.

Parameters:

  • source_file – Path to the model source code.

  • out_script – Path to write the output script.

  • source_fw – Source framework key (optional).

  • target_fw – Target framework key (optional).

Returns:

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

Return type:

int