pymllm.configs.global_config
============================

.. py:module:: pymllm.configs.global_config

.. autoapi-nested-parse::

   Global configuration singleton aggregating all sub-configs.



Classes
-------

.. autoapisummary::

   pymllm.configs.global_config.GlobalConfig


Functions
---------

.. autoapisummary::

   pymllm.configs.global_config.make_args
   pymllm.configs.global_config.read_args
   pymllm.configs.global_config.get_global_config


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

.. py:class:: GlobalConfig

   Singleton that holds every sub-config pymllm needs.

   Usage::

       from pymllm.configs import get_global_config

       cfg = get_global_config()
       cfg.model.model_path
       cfg.model.hidden_size
       cfg.quantization.method
       cfg.server.host

   .. note::

      Always use :meth:`get_instance` (or the module-level
      :func:`get_global_config` shortcut) to obtain the singleton.
      ``GlobalConfig()`` is safe to call multiple times — the second and
      subsequent calls return the existing instance without re-initialising
      fields.


   .. py:attribute:: server
      :type:  pymllm.configs.server_config.ServerConfig


   .. py:attribute:: model
      :type:  pymllm.configs.model_config.ModelConfig


   .. py:attribute:: quantization
      :type:  pymllm.configs.quantization_config.QuantizationConfig


   .. py:method:: get_instance()
      :classmethod:



   .. py:method:: reset()
      :classmethod:


      Destroy the singleton (useful in tests).



.. py:function:: make_args(parser = None)

   Create an ``argparse`` parser with two-level GlobalConfig CLI options.

   The generated options follow the naming pattern ``--<section>.<field>`` so
   each sub-config can be configured independently:

   - ``server`` options map to :class:`ServerConfig` fields.
   - ``model`` options map to :class:`ModelConfig` fields.
   - ``quantization`` options map to :class:`QuantizationConfig` fields.

   .. rubric:: Examples

   - ``--server.host 0.0.0.0``
   - ``--server.port 8080``
   - ``--server.sleep_on_idle`` (implicit true)
   - ``--server.sleep_on_idle false`` (explicit false)
   - ``--quantization.method awq``

   Design notes
   ------------
   - Options are generated from dataclass metadata, which keeps the CLI surface
     synchronized with config definitions and avoids manual drift.
   - Parser defaults are suppressed (``argparse.SUPPRESS``), so ``read_args``
     can reliably detect whether a value was explicitly provided by the user.
   - Only CLI-friendly scalar fields are exposed; runtime-only fields are
     skipped automatically.


.. py:function:: read_args(argv = None, parser = None)

   Parse CLI args and apply overrides to the singleton ``GlobalConfig``.

   :param argv: Optional argument vector. If ``None``, ``argparse`` reads from
                ``sys.argv`` (standard CLI behavior).
   :param parser: Optional parser to use. When omitted, this function builds one through
                  :func:`make_args`.

   :returns: * *GlobalConfig* -- The singleton config instance after CLI overrides have been applied.
             * *Behavior*
             * *--------*
             * 1. Parse all generated ``--section.field`` options.
             * *2. Apply only explicitly provided options (no accidental overwrite by parser* -- defaults).
             * 3. Rebuild ``ServerConfig`` when server fields change so validation in -- ``ServerConfig.__post_init__`` and ``_validate`` remains enforced.
             * 4. Keep ``server.model_path`` and ``model.model_path`` aligned when only one -- side is explicitly overridden (the same precedence used by runtime config
               loading conventions).


.. py:function:: get_global_config()

   Return the global config singleton.