ml_switcheroo.core.tracer¶

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¶

`TraceEventType`	Enumeration of supported trace event types.
`TraceEvent`	A single unit of execution history.
`TraceLogger`	Records transpilation events for visualization.

Functions¶

`get_tracer`(→ TraceLogger)	Returns the global singleton TraceLogger instance.
`reset_tracer`(→ None)	Resets the global tracer state. Useful between runs or tests.

Module Contents¶

class ml_switcheroo.core.tracer.TraceEventType¶

Bases: str, enum.Enum

Enumeration of supported trace event types.

PHASE_START = 'phase_start'¶

PHASE_END = 'phase_end'¶

MATCH_SEMANTICS = 'match_semantics'¶

AST_MUTATION = 'ast_mutation'¶

ANALYSIS_WARNING = 'analysis_warning'¶

IMPORT_ACTION = 'import_action'¶

INSPECTION = 'inspection'¶

class ml_switcheroo.core.tracer.TraceEvent¶

A single unit of execution history.

id: str¶

type: TraceEventType¶

timestamp: float¶

description: str¶

parent_id: str | None = None¶

metadata: Dict[str, Any]¶

class ml_switcheroo.core.tracer.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).

start_phase(name: str, description: str = '') → str¶

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

Parameters:

name (str) – The name of the phase.
description (str) – Additional detail.

Returns:

The generated Phase ID.

Return type:

str

end_phase() → None¶: Ends the current active phase. Pops the phase ID from the stack and logs an end event.

log_match(source_api: str, target_api: str, abstract_op: str) → None¶

Logs a Semantic Match event.

Parameters:

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

log_mutation(node_type: str, before: str, after: str) → None¶

Logs an AST transformation with code diffs.

Parameters:

node_type – Description of node being changed (e.g. “Call”).
before – Source code snapshot before mutation.
after – Source code snapshot after mutation.

log_warning(message: str) → None¶

Logs an analysis warning.

Parameters:: message – The warning text.

log_inspection(node_str: str, outcome: str, detail: str = '') → None¶

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

Parameters:

node_str – The code element being inspected.
outcome – The result (e.g., “Skipped”, “Ignored”).
detail – Reason for the outcome.

export() → List[Dict[str, Any]]¶

Exports the event log as a list of dictionaries.

Returns:: JSON-serializable event stream.
Return type:: List[Dict[str, Any]]

ml_switcheroo.core.tracer.get_tracer() → TraceLogger¶: Returns the global singleton TraceLogger instance.

ml_switcheroo.core.tracer.reset_tracer() → None¶: Resets the global tracer state. Useful between runs or tests.