ml_switcheroo.discovery.inspector
=================================

.. py:module:: ml_switcheroo.discovery.inspector

.. autoapi-nested-parse::

   Inspection Engine for Python Packages.

   This module provides the :class:`ApiInspector`, a hybrid static-dynamic analysis tool
   designed to extract API signatures (functions, classes, and attributes) from Python packages.

   It employs a two-stage strategy:

   1.  **Static Analysis (Griffe)**: Attempts to parse the source code first. This is safer
       and preserves comments/docstrings better, but fails on compiled modules (C-Extensions).
   2.  **Runtime Introspection (Inspect)**: Falls back to importing the module and inspecting
       live objects. This is required for frameworks like PyTorch, TensorFlow, and MLX which
       rely heavily on compiled bindings.

   **Memory Safety**:
   Includes recursion safeguards (visited set tracking) to prevent infinite loops
   or memory explosion when traversing circular references in large libraries like PyTorch.



Classes
-------

.. autoapisummary::

   ml_switcheroo.discovery.inspector.ApiInspector


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

.. py:class:: ApiInspector

   A robust inspector for discovering API surfaces of installed libraries.

   .. attribute:: _package_cache

      Cache of statically parsed Griffe trees.

      :type: Dict[str, griffe.Object]


   .. py:method:: inspect(package_name: str) -> Dict[str, Any]

      Scans a package and returns a flat catalog of its public API.

      :param package_name: The importable name of the package.

      :returns: Dict mapping 'fully.qualified.name' -> {metadata_dict}.