ml_switcheroo.discovery.consensus¶

Consensus Engine: The Dynamic Standardization Brain.

This module provides the logic to identify common operations across disjoint frameworks. It aligns variable naming conventions (e.g., ‘dim’ vs ‘axis’) and clusters API endpoints (e.g., ‘torch.sin’ and ‘jax.numpy.sin’) into unified Abstract Standards suitable for the Semantic Knowledge Base.

Classes¶

`CandidateStandard`	A proposed Abstract Standard discovered via consensus.
`ConsensusEngine`	Algorithms for aligning divergent API naming conventions.

Module Contents¶

class ml_switcheroo.discovery.consensus.CandidateStandard(/, **data: Any)¶

Bases: pydantic.BaseModel

A proposed Abstract Standard discovered via consensus.

name: str = None¶

variants: Dict[str, ml_switcheroo.core.ghost.GhostRef] = None¶

score: float = None¶

std_args: List[str] = None¶

arg_mappings: Dict[str, Dict[str, str]] = None¶

add_variant(framework: str, ref: ml_switcheroo.core.ghost.GhostRef) → None¶

Registers a framework’s implementation of this concept. Updates the consensus score based on support count.

Parameters:

framework (str) – The framework identifier (e.g. ‘torch’).
ref (GhostRef) – The API reference object found in that framework.

class ml_switcheroo.discovery.consensus.ConsensusEngine¶

Algorithms for aligning divergent API naming conventions.

Capabilities:

Clustering: Groups APIs like HuberLoss, huber_loss, and Huber together.
Normalization: Strips common noise (prefixes/suffixes) to find the semantic root.
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).