ml_switcheroo.core.hooks¶

Plugin Registry, Hook Context, and Dynamic Loader.

This module provides the infrastructure for extending ml-switcheroo via plugins. It enables developers to intercept and modify the Abstract Syntax Tree (AST) during the conversion process using a hook-based system.

Refactor:

Added auto_wire support to the register_hook decorator.
Plugins can now declare their own Semantic definitions, eliminating the need to edit standards_internal.py or JSON files for self-contained features.

Attributes¶

`SemanticsManagerType`
`T`
`ArgInjectorType`
`PreambleInjectorType`
`HookFunction`

Classes¶

`HookContext`	Context object passed to every plugin hook during transcoding.
`AutoWireSpec`	Schema for plugin self-registration metadata.

Functions¶

`register_hook`(→ Callable[[HookFunction], HookFunction])	Decorator to register a function as a plugin hook.
`get_hook`(→ Optional[HookFunction])	Retrieves a registered hook function by its trigger name.
`get_all_hook_metadata`(→ Dict[str, AutoWireSpec])	Returns the metadata for all registered hooks.
`clear_hooks`(→ None)	Resets the internal hook registry. Primarily for testing.
`load_plugins`(→ int)	Dynamically imports plugins.

Module Contents¶

ml_switcheroo.core.hooks.SemanticsManagerType¶

ml_switcheroo.core.hooks.T¶

ml_switcheroo.core.hooks.ArgInjectorType¶

ml_switcheroo.core.hooks.PreambleInjectorType¶

class ml_switcheroo.core.hooks.HookContext(semantics: SemanticsManagerType, config: ml_switcheroo.config.RuntimeConfig, arg_injector: ArgInjectorType | None = None, preamble_injector: PreambleInjectorType | None = None)¶

Context object passed to every plugin hook during transcoding.

Provides read-only access to global state and write access to specific injection points (signature args, function body preambles).

semantics¶

source_fw¶

target_fw¶

metadata: Dict[str, Any]¶

current_op_id: str | None = None¶

inject_signature_arg(name: str, annotation: str | None = None) → None¶: Requests injection of argument into the current function signature.

inject_preamble(code_str: str) → None¶: Requests injection of a statement at the beginning of the function body.

raw_config(key: str, default: Any = None) → Any¶: Retrieve a raw value from the unstructured plugin settings dict.

config(key: str, default: Any = None) → Any¶: Legacy alias for raw_config.

validate_settings(model: Type[T]) → T¶: Validates global config against a Plugin-specific Pydantic schema.

lookup_api(op_name: str) → str | None¶: Resolves target framework’s API string for a given standard operation.

lookup_signature(op_name: str) → List[str]¶: Retrieves standard argument list for a given operation.

class ml_switcheroo.core.hooks.AutoWireSpec(/, **data: Any)¶

Bases: pydantic.BaseModel

Schema for plugin self-registration metadata. Allows a plugin to define the Semantic Operation it satisfies.

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ops: Dict[str, Dict[str, Any]] = None¶

ml_switcheroo.core.hooks.HookFunction¶

ml_switcheroo.core.hooks.register_hook(trigger: str, auto_wire: Dict[str, Any] | None = None) → Callable[[HookFunction], HookFunction]¶

Decorator to register a function as a plugin hook.

Parameters:

trigger – The unique identifier. Can be an operation ID or a reserved system event like “transform_for_loop”.
auto_wire – Optional dictionary defining the Semantic Spec for this plugin. If provided, the SemanticsManager will automatically load these definitions, eliminating the need for JSON usage. Format matches semantics/*.json schema (e.g. {“ops”: {“MyOp”: …}}).

ml_switcheroo.core.hooks.get_hook(trigger: str) → HookFunction | None¶: Retrieves a registered hook function by its trigger name. Lazily loads plugins from the default directory if registry is empty.

ml_switcheroo.core.hooks.get_all_hook_metadata() → Dict[str, AutoWireSpec]¶: Returns the metadata for all registered hooks. Used by SemanticsManager to hydrate the Knowledge Base.

ml_switcheroo.core.hooks.clear_hooks() → None¶: Resets the internal hook registry. Primarily for testing.

ml_switcheroo.core.hooks.load_plugins(plugins_dir: pathlib.Path | None = None, extra_dirs: List[pathlib.Path] | None = None) → int¶

Dynamically imports plugins.

Parameters:

plugins_dir – Overrides default package directory. If provided, this directory is scanned for .py files. If NOT provided, the internal ml_switcheroo.plugins package is loaded.
extra_dirs – Additional directories to scan (e.g. user extensions).

Returns:

Number of modules loaded.

Return type:

int