CorePlexMLClient
================

The :class:`~coreplexml.CorePlexMLClient` is the entry point for all SDK
operations. It initializes the HTTP transport and exposes every API resource
as a typed attribute.

Constructor
-----------

.. code-block:: python

   CorePlexMLClient(base_url="http://localhost:8888", api_key=None, timeout=30)

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 15 15 50

   * - Parameter
     - Type
     - Default
     - Description
   * - ``base_url``
     - ``str``
     - ``"http://localhost:8888"``
     - CorePlexML server URL. Include the scheme (``https://``).
   * - ``api_key``
     - ``str | None``
     - ``None``
     - API key for Bearer authentication. Generate one from the web UI.
   * - ``timeout``
     - ``int``
     - ``30``
     - HTTP request timeout in seconds.

Resource Attributes
-------------------

Every resource is initialized once during client construction and is accessible
as a read-only attribute.

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - Attribute
     - Type
     - Description
   * - ``projects``
     - :class:`~coreplexml.projects.ProjectsResource`
     - Create, list, update, delete projects and manage members.
   * - ``datasets``
     - :class:`~coreplexml.datasets.DatasetsResource`
     - Upload, list, download datasets and inspect columns.
   * - ``experiments``
     - :class:`~coreplexml.experiments.ExperimentsResource`
     - Create AutoML experiments and poll for completion.
   * - ``models``
     - :class:`~coreplexml.models.ModelsResource`
     - List trained models, get details, and make predictions.
   * - ``deployments``
     - :class:`~coreplexml.deployments.DeploymentsResource`
     - Deploy models, make predictions, promote/rollback.
   * - ``reports``
     - :class:`~coreplexml.reports.ReportsResource`
     - Generate and download PDF reports.
   * - ``privacy``
     - :class:`~coreplexml.privacy.PrivacyResource`
     - PII detection and data transformation.
   * - ``synthgen``
     - :class:`~coreplexml.synthgen.SynthGenResource`
     - Train generative models and produce synthetic data.
   * - ``studio``
     - :class:`~coreplexml.studio.StudioResource`
     - What-If Analysis -- scenario-based model exploration.

Connection Configuration
------------------------

The SDK uses the ``requests`` library internally. The base URL is normalized
(trailing slashes are stripped), and the API key is sent as a
``Authorization: Bearer <key>`` header on every request.

.. code-block:: python

   # HTTPS with a long timeout for large uploads
   client = CorePlexMLClient(
       base_url="https://ml.example.com",
       api_key="cp_ab12cd34.your-secret-key",
       timeout=120,
   )

   # Local development (no auth)
   local_client = CorePlexMLClient()

Authentication
--------------

API keys are created in the CorePlexML web UI under *Settings > API Keys*.
Each key has a prefix and a secret separated by a dot (e.g.,
``cp_ab12cd34.your-secret-key``). Keys are scoped to a user account and inherit that
user's project permissions.

If no ``api_key`` is provided, requests are sent without an ``Authorization``
header. This may work for unauthenticated local development endpoints but will
fail against production servers.

.. code-block:: python

   from coreplexml import CorePlexMLClient, AuthenticationError

   client = CorePlexMLClient(
       base_url="https://ml.example.com",
       api_key="cp_ab12cd34.your-secret-key",
   )

   try:
       client.projects.list()
   except AuthenticationError:
       print("API key is invalid or expired. Generate a new one in Settings.")

Autodoc Reference
-----------------

.. autoclass:: coreplexml.CorePlexMLClient
   :members:
   :undoc-members:
   :show-inheritance: