ml_switcheroo.discovery.consensus
=================================

.. py:module:: ml_switcheroo.discovery.consensus

.. autoapi-nested-parse::

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

.. autoapisummary::

   ml_switcheroo.discovery.consensus.CandidateStandard
   ml_switcheroo.discovery.consensus.ConsensusEngine


Module Contents
---------------

.. py:class:: CandidateStandard(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   A proposed Abstract Standard discovered via consensus.


   .. py:attribute:: name
      :type:  str
      :value: None



   .. py:attribute:: variants
      :type:  Dict[str, ml_switcheroo.core.ghost.GhostRef]
      :value: None



   .. py:attribute:: score
      :type:  float
      :value: None



   .. py:attribute:: std_args
      :type:  List[str]
      :value: None



   .. py:attribute:: arg_mappings
      :type:  Dict[str, Dict[str, str]]
      :value: None



   .. py:method:: 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.

      :param framework: The framework identifier (e.g. 'torch').
      :type framework: str
      :param ref: The API reference object found in that framework.
      :type ref: GhostRef



.. py:class:: 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`).


   .. py:attribute:: IGNORED_SUFFIXES
      :value: ['loss', 'error', 'layer', 'block', '2d', '1d', '3d', 'v1', 'v2', 'object', 'op', 'func']



   .. py:attribute:: ARG_ALIASES


   .. py:method:: normalize_name(name: str) -> str
      :classmethod:


      Reduces an API Name to its semantic core for comparison.

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

      .. rubric:: Examples

      * 'HuberLoss' -> 'huber'
      * 'reduce_mean' -> 'mean'
      * 'conv2d' -> 'conv'

      :param name: The raw API name (e.g. 'CrossEntropyLoss').
      :type name: str

      :returns: The normalized key (e.g. 'crossentropy').
      :rtype: str



   .. py:method:: normalize_arg(arg_name: str) -> str
      :classmethod:


      Canonicalizes an argument name using the alias map.

      .. rubric:: Example

      'learning_rate' -> 'lr'

      :param arg_name: The raw argument name.
      :type arg_name: str

      :returns: The canonical standard name.
      :rtype: str



   .. py:method:: 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.

      :param framework_inputs: Dictionary mapping 'framework_name' -> List of discovered GhostRefs.

      :returns: A list of potential standards, sorted by descending score.
      :rtype: List[CandidateStandard]



   .. py:method:: 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.

      :param candidates: List of candidates from clustering.
      :type candidates: List[CandidateStandard]
      :param min_support: Minimum number of different frameworks that must implement the op.
      :type min_support: int

      :returns: Filtered list of robust candidates.
      :rtype: List[CandidateStandard]



   .. py:method:: 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').

      :param candidates: List of CandidateStandards to process (in-place modification).
      :type candidates: List[CandidateStandard]
      :param consensus_threshold: Fraction of variants that must share an arg (0.0 - 1.0).
      :type consensus_threshold: float