ml_switcheroo.core.hooks
========================

.. py:module:: ml_switcheroo.core.hooks

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   ml_switcheroo.core.hooks.SemanticsManagerType
   ml_switcheroo.core.hooks.T
   ml_switcheroo.core.hooks.ArgInjectorType
   ml_switcheroo.core.hooks.PreambleInjectorType
   ml_switcheroo.core.hooks.HookFunction


Classes
-------

.. autoapisummary::

   ml_switcheroo.core.hooks.HookContext
   ml_switcheroo.core.hooks.AutoWireSpec


Functions
---------

.. autoapisummary::

   ml_switcheroo.core.hooks.register_hook
   ml_switcheroo.core.hooks.get_hook
   ml_switcheroo.core.hooks.get_all_hook_metadata
   ml_switcheroo.core.hooks.clear_hooks
   ml_switcheroo.core.hooks.load_plugins


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

.. py:data:: SemanticsManagerType

.. py:data:: T

.. py:data:: ArgInjectorType

.. py:data:: PreambleInjectorType

.. py:class:: HookContext(semantics: SemanticsManagerType, config: ml_switcheroo.config.RuntimeConfig, arg_injector: Optional[ArgInjectorType] = None, preamble_injector: Optional[PreambleInjectorType] = 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).


   .. py:attribute:: semantics


   .. py:attribute:: source_fw


   .. py:attribute:: target_fw


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


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



   .. py:method:: inject_signature_arg(name: str, annotation: Optional[str] = None) -> None

      Requests injection of argument into the current function signature.



   .. py:method:: inject_preamble(code_str: str) -> None

      Requests injection of a statement at the beginning of the function body.



   .. py:method:: raw_config(key: str, default: Any = None) -> Any

      Retrieve a raw value from the unstructured plugin settings dict.



   .. py:method:: config(key: str, default: Any = None) -> Any

      Legacy alias for raw_config.



   .. py:method:: validate_settings(model: Type[T]) -> T

      Validates global config against a Plugin-specific Pydantic schema.



   .. py:method:: lookup_api(op_name: str) -> Optional[str]

      Resolves target framework's API string for a given standard operation.



   .. py:method:: lookup_signature(op_name: str) -> List[str]

      Retrieves standard argument list for a given operation.



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

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


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


   .. py:attribute:: model_config

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


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



.. py:data:: HookFunction

.. py:function:: register_hook(trigger: str, auto_wire: Optional[Dict[str, Any]] = None) -> Callable[[HookFunction], HookFunction]

   Decorator to register a function as a plugin hook.

   :param trigger: The unique identifier. Can be an operation ID or a
                   reserved system event like "transform_for_loop".
   :param 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": ...}}`).


.. py:function:: get_hook(trigger: str) -> Optional[HookFunction]

   Retrieves a registered hook function by its trigger name.
   Lazily loads plugins from the default directory if registry is empty.


.. py:function:: get_all_hook_metadata() -> Dict[str, AutoWireSpec]

   Returns the metadata for all registered hooks.
   Used by SemanticsManager to hydrate the Knowledge Base.


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

   Resets the internal hook registry. Primarily for testing.


.. py:function:: load_plugins(plugins_dir: Optional[pathlib.Path] = None, extra_dirs: Optional[List[pathlib.Path]] = None) -> int

   Dynamically imports plugins.

   :param 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.
   :param extra_dirs: Additional directories to scan (e.g. user extensions).

   :returns: Number of modules loaded.
   :rtype: int