ml_switcheroo.core.engine
=========================

.. py:module:: ml_switcheroo.core.engine

.. autoapi-nested-parse::

   Orchestration Engine for AST Transformations.

   This module provides the `ASTEngine`, the primary driver for the transpilation process.
   It coordinates the various analysis and transformation passes required to convert code
   from a source framework to a target framework.

   The Engine pipeline consists of:

   1.  **Preprocessing**: Parsing source code into a LibCST tree.
   2.  **Safety Analysis**:

       *   **Purity**: Checking for side effects if targeting functional frameworks (JAX).
       *   **Lifecycle**: Verifying variable initialization.
       *   **Dependencies**: Scanning for unmapped 3rd-party imports.

   3.  **Semantic Pivoting**: Executing the `PivotRewriter` to map API calls and structure.
   4.  **Post-processing**:

       *   **Import Fixer**: Injecting necessary imports and removing unused source imports.
       *   **Structural Linting**: Verifying no artifacts from the source framework remain.

   The engine relies on `RuntimeConfig` to resolve 'Flavours' (e.g., distinguishing
   `flax_nnx` from generic `jax`) to load the correct structural traits.



Classes
-------

.. autoapisummary::

   ml_switcheroo.core.engine.ConversionResult
   ml_switcheroo.core.engine.ASTEngine


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

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

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


   Structured result of a single file conversion.


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



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



   .. py:attribute:: success
      :type:  bool
      :value: None



   .. py:attribute:: trace_events
      :type:  List[Dict[str, Any]]
      :value: None



   .. py:property:: has_errors
      :type: bool


      Returns True if any errors or warnings were recorded during conversion.

      :returns: True if errors list is non-empty.
      :rtype: bool


.. py:class:: ASTEngine(semantics: ml_switcheroo.semantics.manager.SemanticsManager = None, config: Optional[ml_switcheroo.config.RuntimeConfig] = None, source: str = 'torch', target: str = 'jax', strict_mode: bool = False, plugin_config: Optional[Dict[str, Any]] = None)

   The main compilation unit.

   This class encapsulates the state and logic required to transpile a single unit of code.
   It manages the lifecycle of the LibCST tree and the invocation of visitor passes.


   .. py:attribute:: semantics


   .. py:attribute:: source


   .. py:attribute:: target


   .. py:attribute:: strict_mode


   .. py:method:: parse(code: str) -> libcst.Module

      Parses source string into a LibCST Module.

      :param code: Python source code.
      :type code: str

      :returns: The parsed Abstract Syntax Tree.
      :rtype: cst.Module

      :raises libcst.ParserSyntaxError: If the input code is invalid Python.



   .. py:method:: to_source(tree: libcst.Module) -> str

      Converts CST back to source string.

      :param tree: The modified syntax tree.
      :type tree: cst.Module

      :returns: Generated Python code.
      :rtype: str



   .. py:method:: run(code: str) -> ConversionResult

      Executes the full transpilation pipeline.

      Passes performed:
      1.  Parse.
      2.  Purity Scan (if targeting JAX-like frameworks).
      3.  Lifecycle Analysis (Init/Forward mismatch).
      4.  Dependency Scan (Checking 3rd party libs).
      5.  Pivot Rewrite (The main transformation).
      6.  Import Fixer (Injecting new imports, pruning old ones).
      7.  Structural Linting (Verifying output cleanliness).

      :param code: The input source string.
      :type code: str

      :returns: Object containing transformed code and error logs.
      :rtype: ConversionResult