ml_switcheroo.core.ghost
========================

.. py:module:: ml_switcheroo.core.ghost

.. autoapi-nested-parse::

   Ghost Core: Introspection Abstraction Layer.

   This module provides the data structures and inspection logic required to
   decouple framework analysis from the live environment. It enables the system
   to operate in "Ghost Mode" (WASM/CI) by working against cached snapshots
   instead of requiring heavy libraries (Torch/TensorFlow) to be installed.

   Updates:
   - Robust C-Extension handling (try/except around `inspect.signature`).
   - Validates parameter kinds to support `*args` (VarPositional).



Classes
-------

.. autoapisummary::

   ml_switcheroo.core.ghost.GhostParam
   ml_switcheroo.core.ghost.GhostRef
   ml_switcheroo.core.ghost.GhostInspector


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

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

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


   Serializable representation of a function parameter.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: kind
      :type:  str


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



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



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

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


   Serializable snapshot of a Framework API component.

   Used by the Consensus Engine to align concepts (e.g. 'HuberLoss' vs 'Huber')
   without needing the framework installed at runtime.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: api_path
      :type:  str


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



   .. py:attribute:: params
      :type:  List[GhostParam]
      :value: None



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



   .. py:attribute:: has_varargs
      :type:  bool
      :value: False



   .. py:method:: has_arg(arg_name: str) -> bool

      Checks if a specific argument exists in the signature.



.. py:class:: GhostInspector

   Facade for API Inspection.

   Responsibility: Convert Live Objects -> JSON-serializable GhostDefs.
   Crucial for populating snapshots used by WASM/JS environments.


   .. py:method:: inspect(obj: Union[Any, Callable], api_path: str) -> GhostRef
      :staticmethod:


      Creates a GhostRef from a live Python object.
      Gracefully handles C-Extensions and builtins that resist introspection.

      :param obj: The live class or function to inspect.
      :param api_path: The canonical string path (e.g. 'torch.nn.ReLU').

      :returns: A populated GhostRef object.



   .. py:method:: hydrate(data: dict) -> GhostRef
      :staticmethod:


      Creates a GhostRef from a dictionary (JSON snapshot).