ml_switcheroo.core.tracer
=========================

.. py:module:: ml_switcheroo.core.tracer

.. autoapi-nested-parse::

   Transpilation Trace Logger.

   This module provides the infrastructure to record the step-by-step execution
   of the transpiler. It captures:
   1. Lifecycle Phases (Parsing, Analysis, Rewriting).
   2. Semantics Matches (Found `torch.abs` -> Map to `Abs` op).
   3. AST Mutations (Node A transformed to Node B).

   The output is a structured list of Event Log dictionaries suitable for JSON serialization.



Classes
-------

.. autoapisummary::

   ml_switcheroo.core.tracer.TraceEventType
   ml_switcheroo.core.tracer.TraceEvent
   ml_switcheroo.core.tracer.TraceLogger


Functions
---------

.. autoapisummary::

   ml_switcheroo.core.tracer.get_tracer
   ml_switcheroo.core.tracer.reset_tracer


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

.. py:class:: TraceEventType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Enumeration of supported trace event types.


   .. py:attribute:: PHASE_START
      :value: 'phase_start'



   .. py:attribute:: PHASE_END
      :value: 'phase_end'



   .. py:attribute:: MATCH_SEMANTICS
      :value: 'match_semantics'



   .. py:attribute:: AST_MUTATION
      :value: 'ast_mutation'



   .. py:attribute:: ANALYSIS_WARNING
      :value: 'analysis_warning'



   .. py:attribute:: IMPORT_ACTION
      :value: 'import_action'



   .. py:attribute:: INSPECTION
      :value: 'inspection'



.. py:class:: TraceEvent

   A single unit of execution history.


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: type
      :type:  TraceEventType


   .. py:attribute:: timestamp
      :type:  float


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: parent_id
      :type:  Optional[str]
      :value: None



   .. py:attribute:: metadata
      :type:  Dict[str, Any]


.. py:class:: TraceLogger

   Records transpilation events for visualization.
   Designed to be injected into the Engine and Rewriter.

   This class maintains a stack of active phases to establish parent-child
   relationships between events (e.g. an AST mutation inside a specific Rewrite pass).


   .. py:method:: start_phase(name: str, description: str = '') -> str

      Starts a nested phase (e.g., 'Rewriting Function X').

      :param name: The name of the phase.
      :type name: str
      :param description: Additional detail.
      :type description: str

      :returns: The generated Phase ID.
      :rtype: str



   .. py:method:: end_phase() -> None

      Ends the current active phase.
      Pops the phase ID from the stack and logs an end event.



   .. py:method:: log_match(source_api: str, target_api: str, abstract_op: str) -> None

      Logs a Semantic Match event.

      :param source_api: The source function name (e.g. `torch.abs`).
      :param target_api: The target implementation (e.g. `jax.numpy.abs`).
      :param abstract_op: The abstract standard key (e.g. `Abs`).



   .. py:method:: log_mutation(node_type: str, before: str, after: str) -> None

      Logs an AST transformation with code diffs.

      :param node_type: Description of node being changed (e.g. "Call").
      :param before: Source code snapshot before mutation.
      :param after: Source code snapshot after mutation.



   .. py:method:: log_warning(message: str) -> None

      Logs an analysis warning.

      :param message: The warning text.



   .. py:method:: log_inspection(node_str: str, outcome: str, detail: str = '') -> None

      Logs a decision point where no change occurred (for debugging).

      :param node_str: The code element being inspected.
      :param outcome: The result (e.g., "Skipped", "Ignored").
      :param detail: Reason for the outcome.



   .. py:method:: export() -> List[Dict[str, Any]]

      Exports the event log as a list of dictionaries.

      :returns: JSON-serializable event stream.
      :rtype: List[Dict[str, Any]]



.. py:function:: get_tracer() -> TraceLogger

   Returns the global singleton TraceLogger instance.


.. py:function:: reset_tracer() -> None

   Resets the global tracer state. Useful between runs or tests.