Python SDK
==========

The CorePlexML Python SDK provides a type-safe wrapper around the CorePlexML
REST API. It gives Python developers a clean, resource-oriented interface for
managing the full ML lifecycle -- from data upload and model training to
production deployment and monitoring.

Installation
------------

Install from PyPI:

.. code-block:: bash

   pip install coreplexml

Or install from a local distribution (e.g., downloaded from your CorePlexML server):

.. code-block:: bash

   pip install /path/to/coreplexml-0.1.0.tar.gz

Requirements:

- Python >= 3.9
- ``requests`` >= 2.28

Quick Initialization
--------------------

.. code-block:: python

   from coreplexml import CorePlexMLClient

   client = CorePlexMLClient(
       base_url="https://your-domain.com",
       api_key="prefix.your-secret-key",
   )

   # All resources are accessible as attributes
   projects = client.projects.list()

Key Concepts
------------

Resources
^^^^^^^^^

The SDK is organized around **resources** that mirror the CorePlexML REST API.
Each resource is an attribute on the client and exposes methods matching the
available API operations:

- ``client.projects`` -- :class:`~coreplexml.projects.ProjectsResource`
- ``client.datasets`` -- :class:`~coreplexml.datasets.DatasetsResource`
- ``client.experiments`` -- :class:`~coreplexml.experiments.ExperimentsResource`
- ``client.models`` -- :class:`~coreplexml.models.ModelsResource`
- ``client.deployments`` -- :class:`~coreplexml.deployments.DeploymentsResource`
- ``client.reports`` -- :class:`~coreplexml.reports.ReportsResource`
- ``client.privacy`` -- :class:`~coreplexml.privacy.PrivacyResource`
- ``client.synthgen`` -- :class:`~coreplexml.synthgen.SynthGenResource`
- ``client.studio`` -- :class:`~coreplexml.studio.StudioResource`

All methods return plain Python dictionaries parsed from the server's JSON
responses.

Job Polling
^^^^^^^^^^^

Long-running operations (AutoML training, report generation) are handled as
background jobs. The SDK provides built-in polling methods that block until the
job completes or a configurable timeout is reached:

.. code-block:: python

   exp = client.experiments.create(...)
   result = client.experiments.wait(exp["id"], interval=5.0, timeout=3600.0)

Error Handling
^^^^^^^^^^^^^^

All API errors are raised as typed exceptions. Every exception includes
``message``, ``status_code``, and ``detail`` attributes:

.. code-block:: python

   from coreplexml import CorePlexMLError, NotFoundError

   try:
       client.projects.get("nonexistent-id")
   except NotFoundError as e:
       print(f"Status {e.status_code}: {e.detail}")

See :doc:`exceptions` for the full exception hierarchy.

Authentication
^^^^^^^^^^^^^^

The SDK uses **Bearer token** authentication via API keys. Generate an API key
from the CorePlexML web UI under *Settings > API Keys*. Pass it to the client
constructor:

.. code-block:: python

   client = CorePlexMLClient(
       base_url="https://your-domain.com",
       api_key="prefix.your-secret-key",
   )

Version Compatibility
---------------------

.. list-table::
   :header-rows: 1

   * - SDK Version
     - Server Version
     - Python Version
   * - 0.1.x
     - >= 0.1.0
     - >= 3.9

Contents
--------

.. toctree::
   :maxdepth: 2

   quickstart
   client
   resources
   exceptions
   advanced
   examples