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.

Classes

SemanticsManager

Central database for semantic mappings and configuration.

FrameworkSyncer

Links abstract operations to concrete framework implementations.

SemanticPersister

Handles serialization of Discovered Standards to disk using Hub-and-Spoke architecture.

ConsensusEngine

Algorithms for aligning divergent API naming conventions.

BatchValidator

Orchestrates the validation of the entire knowledge base.

ReadmeEditor

Utility to programmatically update the README.md with verification results.

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.

available_frameworks(→ List[str])

Returns a list of all registered framework keys.

get_adapter(→ Optional[FrameworkAdapter])

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.

Module Contents

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

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

Parameters:

  • path – Input source.

  • source_frameworks – List of framework keys to scan for.

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, 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.

  • 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) – Code resource to import (‘internal’, .md file, or directory).

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.

Return type:

int

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.

Return type:

int

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) → int

Handles ‘ci’ command.

ml_switcheroo.cli.commands.handle_matrix() → int

Handles ‘matrix’ command.

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

Handles ‘gen-docs’ command.

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

Handles ‘gen-tests’ command.

class ml_switcheroo.cli.commands.SemanticsManager

Central database for semantic mappings and configuration.

data: Dict[str, Dict]
import_data: Dict[str, Dict]
framework_configs: Dict[str, Dict]
test_templates: Dict[str, Dict]
get_all_rng_methods() → Set[str]
resolve_variant(abstract_id: str, target_fw: str) → Dict[str, Any] | None
load_validation_report(report_path: pathlib.Path) → None
is_verified(abstract_id: str) → bool
get_definition_by_id(abstract_id: str) → Dict[str, Any] | None
get_definition(api_name: str) → Tuple[str, Dict] | None
get_known_apis() → Dict[str, Dict]
get_import_map(target_fw: str) → Dict[str, Tuple[str, str | None, str | None]]
get_framework_config(framework: str) → Dict[str, Any]
get_test_template(framework: str) → Dict[str, str] | None
get_framework_aliases() → Dict[str, Tuple[str, str]]
update_definition(abstract_id: str, new_data: Dict[str, Any]) → None
class ml_switcheroo.cli.commands.FrameworkSyncer

Links abstract operations to concrete framework implementations.

console

A configured Rich console for logging output.

console
sync(tier_data: Dict[str, Any], framework: str) → None

Updates the ‘variants’ dict in tier_data by hunting for ops in the target framework.

ml_switcheroo.cli.commands.available_frameworks() → List[str]

Returns a list of all registered framework keys.

ml_switcheroo.cli.commands.get_adapter(name: str) → FrameworkAdapter | None
class ml_switcheroo.cli.commands.SemanticPersister

Handles serialization of Discovered Standards to disk using Hub-and-Spoke architecture.

persist(candidates: List[ml_switcheroo.discovery.consensus.CandidateStandard], target_spec_file: pathlib.Path) → None

Splits and persists candidates into Specifications (Hub) and Snapshots (Spokes).

Parameters:

  • candidates – List of aligned CandidateStandard objects.

  • target_spec_file – Path to the JSON semantic spec file (Hub) to update/create. (e.g., semantics/k_framework_extras.json)

class ml_switcheroo.cli.commands.ConsensusEngine

Algorithms for aligning divergent API naming conventions.

Capabilities:

  1. Clustering: Groups APIs like HuberLoss, huber_loss, and Huber together.

  2. Normalization: Strips common noise (prefixes/suffixes) to find the semantic root.

  3. Signature Alignment: Builds a translation map for arguments (e.g., keepdims <-> keep_dims).

IGNORED_SUFFIXES = ['loss', 'error', 'layer', 'block', '2d', '1d', '3d', 'v1', 'v2', 'object', 'op', 'func']
ARG_ALIASES
classmethod normalize_name(name: str) → str

Reduces an API Name to its semantic core for comparison.

This removes casing, underscores, and common prefixes/suffixes.

Examples

  • ‘HuberLoss’ -> ‘huber’

  • ‘reduce_mean’ -> ‘mean’

  • ‘conv2d’ -> ‘conv’

Parameters:

name (str) – The raw API name (e.g. ‘CrossEntropyLoss’).

Returns:

The normalized key (e.g. ‘crossentropy’).

Return type:

str

classmethod normalize_arg(arg_name: str) → str

Canonicalizes an argument name using the alias map.

Example

‘learning_rate’ -> ‘lr’

Parameters:

arg_name (str) – The raw argument name.

Returns:

The canonical standard name.

Return type:

str

cluster(framework_inputs: Dict[str, List[ml_switcheroo.core.ghost.GhostRef]]) → List[CandidateStandard]

Groups API definitions from multiple frameworks into Candidates based on name similarity.

Parameters:

framework_inputs – Dictionary mapping ‘framework_name’ -> List of discovered GhostRefs.

Returns:

A list of potential standards, sorted by descending score.

Return type:

List[CandidateStandard]

filter_common(candidates: List[CandidateStandard], min_support: int = 2) → List[CandidateStandard]

Filters candidates to keep only those present in a minimum number of frameworks.

This ensures we only create standards for concepts that are truly shared across ecosystems, avoiding framework-specific noise.

Parameters:

  • candidates (List[CandidateStandard]) – List of candidates from clustering.

  • min_support (int) – Minimum number of different frameworks that must implement the op.

Returns:

Filtered list of robust candidates.

Return type:

List[CandidateStandard]

align_signatures(candidates: List[CandidateStandard], consensus_threshold: float = 0.5) → None

Analyses the arguments of all variants in a candidate to determine Standard Arguments.

It populates std_args on the candidate by voting: if an argument (normalized) appears in >50% of the implementations, it becomes part of the standard signature.

It also populates arg_mappings to translate between the Standard name and the specific framework name (e.g. Standard ‘dim’ -> Torch ‘dim’, Jax ‘axis’).

Parameters:

  • candidates (List[CandidateStandard]) – List of CandidateStandards to process (in-place modification).

  • consensus_threshold (float) – Fraction of variants that must share an arg (0.0 - 1.0).

class ml_switcheroo.cli.commands.BatchValidator(semantics: ml_switcheroo.semantics.manager.SemanticsManager)

Orchestrates the validation of the entire knowledge base.

semantics
runner
run_all(verbose: bool = False, manual_test_dir: pathlib.Path | None = None) → Dict[str, bool]

Runs verification for all known APIs.

Validation Hierarchy:

  1. Manual Test Priority: If a file contains def test_<op_name>():, we assume the developer has manually verified this operation. It is marked as Passing.

  2. Automated Fuzzing: If no manual test exists, we unpack the arguments, type hints, and constraints from the spec, generate random inputs, and check equivalence using EquivalenceRunner.

Parameters:

  • verbose – Show progress bar using Rich.

  • manual_test_dir – Directory containing manual tests to scan (default: None).

Returns:

Validation status (True=Pass, False=Fail).

Return type:

Dict[op_name, bool]

class ml_switcheroo.cli.commands.ReadmeEditor(semantics: ml_switcheroo.semantics.manager.SemanticsManager, readme_path: pathlib.Path)

Utility to programmatically update the README.md with verification results.

It regenerates the “Compatibility Matrix” table based on the current state of the Knowledge Base and the results of the latest CI run, then splices it into the README content using regex markers.

semantics

Source of Truth for API definitions.

Type:

SemanticsManager

readme_path

Path to the README file.

Type:

Path

semantics
readme_path
update_matrix(validation_results: Dict[str, bool]) → bool

Regenerates the Markdown table and injects it into the README.

It looks for the section starting with ## ✅ Compatibility Matrix and replaces the content up to the next ## Header or End of File.

Parameters:

validation_results – Dictionary mapping op_name -> boolean pass status.

Returns:

True if the update was successful, False otherwise.

Return type:

bool

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