ml_switcheroo.cli.handlers.discovery
====================================

.. py:module:: ml_switcheroo.cli.handlers.discovery

.. autoapi-nested-parse::

   Discovery & Standards Command Handlers.

   This module implements the logic for populating the Semantic Knowledge Base via
   Automated Discovery and Specification Imports.

   It handles:
   1.  **Ingestion**: Importing external standards (ONNX, Array API) and Internal Golden Sets (Hub).
   2.  **Scaffolding**: Generating skeleton mappings.
   3.  **Discovery**: Identifying Neural Layers via Consensus and linking them to the Semantic Hub.



Functions
---------

.. autoapisummary::

   ml_switcheroo.cli.handlers.discovery.handle_scaffold
   ml_switcheroo.cli.handlers.discovery.handle_import_spec
   ml_switcheroo.cli.handlers.discovery.handle_sync_standards


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

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

   :param frameworks: List of framework package names to scaffold (e.g., ['torch', 'jax']).
   :type frameworks: list[str]
   :param out_dir: The root directory for generating the knowledge base.
                   Defaults to the package source if None.
   :type out_dir: Path

   :returns: Exit code.
   :rtype: int


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

   :param target: Code resource to import ('internal', .md file, or directory).
   :type target: Path

   :returns: Exit code.
   :rtype: int


.. py:function:: handle_sync_standards(categories: List[str], frameworks: Optional[List[str]], 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).

   :param categories: List of category strings (layer, loss, etc.) to scan.
   :type categories: List[str]
   :param frameworks: List of framework keys to scan.
                      Defaults to installed/registered frameworks.
   :type frameworks: Optional[List[str]]
   :param dry_run: If True, prints results without saving.
   :type dry_run: bool

   :returns: Exit code.
   :rtype: int