ml_switcheroo.discovery.harvester
=================================

.. py:module:: ml_switcheroo.discovery.harvester

.. autoapi-nested-parse::

   Semantic Harvester for extracting knowledge from manual tests.

   This module provides the ``SemanticHarvester``, which inspects Python test files
   written by developers (Human Override Workflow). It analyzes successful test
   calls to reverse-engineer valid argument mappings for the Knowledge Base.

   Logic:
       1. Parse a test file's AST.
       2. Scan for imports to resolve aliases (e.g. ``import jax.numpy as jnp``).
       3. Identify test functions (e.g., ``test_matmul``).
       4. Find calls to the target framework (e.g., ``jax.numpy.matmul``).
       5. Correlate input arguments to target parameters using:
          - **Naming Convention**: `np_x` matches standard arg `x`.
          - **Explicit Keywords**: `kwargs` match standard arg names directly.
          - **Value-Based Inference**: Matches literals (e.g. `1`, `True`) to
            type hints defined in the Semantics (e.g., `axis: int`).
       6. Construct and return valid mapping dictionaries.



Classes
-------

.. autoapisummary::

   ml_switcheroo.discovery.harvester.ImportScanner
   ml_switcheroo.discovery.harvester.SemanticHarvester
   ml_switcheroo.discovery.harvester.TargetCallVisitor


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

.. py:class:: ImportScanner(root_fw: str)

   Bases: :py:obj:`ast.NodeVisitor`


   Scans AST for imports relevant to the target framework to build an alias map.


   .. py:attribute:: root_fw


   .. py:attribute:: aliases


   .. py:method:: visit_Import(node: ast.Import) -> Any


   .. py:method:: visit_ImportFrom(node: ast.ImportFrom) -> Any


.. py:class:: SemanticHarvester(semantics: ml_switcheroo.semantics.manager.SemanticsManager, target_fw: str = 'jax')

   Analyzes Python source code to extract valid API signatures from usage.


   .. py:attribute:: semantics


   .. py:attribute:: target_fw
      :value: 'jax'



   .. py:method:: harvest_file(file_path: pathlib.Path, dry_run: bool = False) -> int

      Scans a file, extracts mappings, and updates the semantics JSONs.

      :param file_path: Path to the python test file.
      :param dry_run: If True, does not write changes to disk.

      :returns: Number of definitions updated.
      :rtype: int



.. py:class:: TargetCallVisitor(target_api: str, aliases: Dict[str, str], std_args_info: List[Any])

   Bases: :py:obj:`ast.NodeVisitor`


   Helper AST walker to find specific API calls and extract arguments.

   Implements **Value-Based Inference**:
   - Matches naming conventions (``np_x``).
   - Matches literal types (e.g. ``1`` is ``int``) to Semantic Types (``axis: int``).


   .. py:attribute:: target_api


   .. py:attribute:: aliases


   .. py:attribute:: std_args_info
      :value: []



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



   .. py:method:: visit_Call(node: ast.Call) -> Any

      Inspects calls. Check if they match target_api and extract args.