coreplexml 0.1.1__py3-none-any.whl

coreplexml/__init__.py

@@ -0,0 +1,21 @@
+"""CorePlexML Python SDK.
+
+A Python client for the CorePlexML AutoML & MLOps platform.
+Provides typed access to projects, datasets, experiments, models,
+deployments, reports, privacy suite, synthetic data generation,
+and what-if analysis.
+
+Quick start::
+
+    from coreplexml import CorePlexMLClient
+
+    client = CorePlexMLClient("https://your-domain.com", api_key="your-key")
+    projects = client.projects.list()
+
+Version: 0.1.1
+"""
+from coreplexml.client import CorePlexMLClient
+from coreplexml.exceptions import CorePlexMLError, AuthenticationError, NotFoundError, ValidationError
+
+__version__ = "0.1.1"
+__all__ = ["CorePlexMLClient", "CorePlexMLError", "AuthenticationError", "NotFoundError", "ValidationError", "__version__"]

coreplexml/_http.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+"""HTTP transport layer for the CorePlexML Python SDK.
+
+Provides low-level HTTP methods with automatic error handling,
+authentication, retry logic, and job polling support.
+"""
+
+import time
+import logging
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from coreplexml.exceptions import CorePlexMLError, AuthenticationError, NotFoundError, ValidationError
+
+logger = logging.getLogger(__name__)
+
+_SDK_VERSION = "0.1.1"
+
+
+class HTTPClient:
+    """Low-level HTTP client with error handling, retries, and job polling."""
+
+    def __init__(self, base_url: str, api_key: str | None = None, timeout: int = 30):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers["User-Agent"] = f"coreplexml-python/{_SDK_VERSION}"
+        self.session.headers["Content-Type"] = "application/json"
+        if api_key:
+            self.session.headers["Authorization"] = f"Bearer {api_key}"
+
+        # Retry transient failures with exponential backoff
+        retry = Retry(
+            total=3,
+            backoff_factor=0.5,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["GET", "PUT", "DELETE", "HEAD", "OPTIONS"],
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+
+    def close(self) -> None:
+        """Close the underlying HTTP session and release connections."""
+        self.session.close()
+
+    def __repr__(self) -> str:
+        return f"HTTPClient(base_url={self.base_url!r})"
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    def _request(self, method: str, path: str, **kwargs) -> requests.Response:
+        """Execute HTTP request with connection error wrapping."""
+        kwargs.setdefault("timeout", self.timeout)
+        try:
+            return self.session.request(method, self._url(path), **kwargs)
+        except requests.exceptions.Timeout as e:
+            raise CorePlexMLError(f"Request timed out: {e}") from e
+        except requests.exceptions.ConnectionError as e:
+            raise CorePlexMLError(f"Connection failed: {e}") from e
+        except requests.exceptions.RequestException as e:
+            raise CorePlexMLError(f"Request failed: {e}") from e
+
+    def _handle_response(self, resp: requests.Response) -> dict:
+        """Process HTTP response and raise typed exceptions on errors."""
+        if resp.status_code == 204:
+            return {}
+        try:
+            data = resp.json()
+        except Exception:
+            text = resp.text[:500] if resp.text else "No response body"
+            data = {"detail": text}
+
+        if resp.status_code >= 400:
+            detail = data.get("detail", str(data)) if isinstance(data, dict) else str(data)
+            msg = f"HTTP {resp.status_code}: {detail}"
+            if resp.status_code in (401, 403):
+                raise AuthenticationError(msg, resp.status_code, detail)
+            elif resp.status_code == 404:
+                raise NotFoundError(msg, resp.status_code, detail)
+            elif resp.status_code == 422:
+                raise ValidationError(msg, resp.status_code, detail)
+            else:
+                raise CorePlexMLError(msg, resp.status_code, detail)
+        return data
+
+    def get(self, path: str, params: dict | None = None) -> dict:
+        """Send GET request."""
+        resp = self._request("GET", path, params=params)
+        return self._handle_response(resp)
+
+    def post(self, path: str, json: dict | None = None, files: dict | None = None) -> dict:
+        """Send POST request."""
+        if files:
+            saved_ct = self.session.headers.pop("Content-Type", None)
+            try:
+                resp = self._request("POST", path, data=json, files=files)
+            finally:
+                if saved_ct:
+                    self.session.headers["Content-Type"] = saved_ct
+        else:
+            resp = self._request("POST", path, json=json)
+        return self._handle_response(resp)
+
+    def put(self, path: str, json: dict | None = None) -> dict:
+        """Send PUT request."""
+        resp = self._request("PUT", path, json=json)
+        return self._handle_response(resp)
+
+    def patch(self, path: str, json: dict | None = None) -> dict:
+        """Send PATCH request."""
+        resp = self._request("PATCH", path, json=json)
+        return self._handle_response(resp)
+
+    def delete(self, path: str) -> dict:
+        """Send DELETE request."""
+        resp = self._request("DELETE", path)
+        return self._handle_response(resp)
+
+    def download(self, path: str, output_path: str, params: dict | None = None) -> str:
+        """Download a file from the API.
+
+        Returns:
+            The output_path where the file was saved.
+        """
+        resp = self._request("GET", path, params=params, stream=True)
+        if resp.status_code >= 400:
+            self._handle_response(resp)  # raises typed exception
+        with open(output_path, "wb") as f:
+            for chunk in resp.iter_content(chunk_size=8192):
+                f.write(chunk)
+        return output_path
+
+    def poll_job(self, job_id: str, interval: float = 3.0, timeout: float = 600.0) -> dict:
+        """Poll a job until completion or timeout."""
+        start = time.time()
+        while time.time() - start < timeout:
+            data = self.get(f"/api/jobs/{job_id}")
+            job = data.get("job", data) if isinstance(data, dict) else {}
+            status = job.get("status", "") if isinstance(job, dict) else ""
+            if status in ("succeeded", "completed", "failed", "error"):
+                return job if isinstance(job, dict) else data
+            time.sleep(interval)
+        raise CorePlexMLError(f"Job {job_id} timed out after {timeout}s")
+
+    def upload(self, path: str, file_path: str, fields: dict | None = None) -> dict:
+        """Upload a file via multipart form."""
+        import os
+        filename = os.path.basename(file_path)
+        with open(file_path, "rb") as f:
+            files = {"file": (filename, f)}
+            return self.post(path, json=fields, files=files)

coreplexml/client.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+"""Main CorePlexML client."""
+
+from coreplexml._http import HTTPClient
+from coreplexml.projects import ProjectsResource
+from coreplexml.datasets import DatasetsResource
+from coreplexml.experiments import ExperimentsResource
+from coreplexml.models import ModelsResource
+from coreplexml.deployments import DeploymentsResource
+from coreplexml.reports import ReportsResource
+from coreplexml.privacy import PrivacyResource
+from coreplexml.synthgen import SynthGenResource
+from coreplexml.studio import StudioResource
+
+
+class CorePlexMLClient:
+    """Top-level client for the CorePlexML Python SDK.
+
+    Provides access to all API resources through typed sub-clients.
+
+    Args:
+        base_url: CorePlexML server URL (default ``http://localhost:8888``).
+        api_key: Bearer token for API authentication.
+        timeout: Request timeout in seconds (default 30).
+
+    Example::
+
+        from coreplexml import CorePlexMLClient
+
+        client = CorePlexMLClient("https://your-domain.com", api_key="your-key")
+        projects = client.projects.list()
+
+    Attributes:
+        projects: Manage projects.
+        datasets: Upload, list, and manage datasets.
+        experiments: Create and monitor AutoML experiments.
+        models: Get model info and make predictions.
+        deployments: Deploy models and manage production endpoints.
+        reports: Generate and download reports.
+        privacy: Privacy Suite -- PII detection and data transformation.
+        synthgen: Synthetic data generation with CTGAN/CopulaGAN/TVAE/Gaussian Copula.
+        studio: What-If Analysis -- scenario comparison.
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8888", api_key: str | None = None, timeout: int = 30):
+        """Initialize the CorePlexML client.
+
+        Args:
+            base_url: Server URL (default ``http://localhost:8888``).
+            api_key: API key for Bearer authentication.
+            timeout: Request timeout in seconds.
+        """
+        self._http = HTTPClient(base_url, api_key=api_key, timeout=timeout)
+        self.projects = ProjectsResource(self._http)
+        self.datasets = DatasetsResource(self._http)
+        self.experiments = ExperimentsResource(self._http)
+        self.models = ModelsResource(self._http)
+        self.deployments = DeploymentsResource(self._http)
+        self.reports = ReportsResource(self._http)
+        self.privacy = PrivacyResource(self._http)
+        self.synthgen = SynthGenResource(self._http)
+        self.studio = StudioResource(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP session and release connections."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"CorePlexMLClient(base_url={self._http.base_url!r})"

coreplexml/datasets.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+"""Datasets resource for the CorePlexML SDK."""
+from coreplexml._http import HTTPClient
+
+
+class DatasetsResource:
+    """Manage datasets and dataset versions.
+
+    Datasets are the foundation for training experiments. Upload CSV files
+    and CorePlexML will version, profile, and analyze them automatically.
+    """
+
+    def __init__(self, http: HTTPClient):
+        self._http = http
+
+    @staticmethod
+    def _normalize_dataset_upload(payload: dict) -> dict:
+        """Normalize upload response keys for docs/examples compatibility."""
+        if not isinstance(payload, dict):
+            return {}
+        out = dict(payload)
+        if "id" not in out and out.get("dataset_id"):
+            out["id"] = out["dataset_id"]
+        if "version_id" not in out and out.get("dataset_version_id"):
+            out["version_id"] = out["dataset_version_id"]
+        return out
+
+    def list(self, project_id: str | None = None, limit: int = 50, offset: int = 0) -> dict:
+        """List datasets, optionally filtered by project.
+
+        Args:
+            project_id: Filter by project UUID (optional).
+            limit: Maximum results (default 50).
+            offset: Pagination offset.
+
+        Returns:
+            Dictionary with ``items`` list and ``total`` count.
+        """
+        params: dict = {"limit": limit, "offset": offset}
+        if project_id:
+            params["project_id"] = project_id
+        return self._http.get("/api/datasets", params=params)
+
+    def upload(self, project_id: str, file_path: str, name: str, description: str = "") -> dict:
+        """Upload a CSV file as a new dataset.
+
+        Args:
+            project_id: UUID of the owning project.
+            file_path: Local path to the CSV file.
+            name: Display name for the dataset.
+            description: Optional description.
+
+        Returns:
+            Created dataset dictionary with ``id``, ``name``, etc.
+        """
+        data = self._http.upload(
+            "/api/datasets/upload",
+            file_path,
+            fields={"project_id": project_id, "name": name, "description": description},
+        )
+        return self._normalize_dataset_upload(data)
+
+    def get(self, dataset_id: str) -> dict:
+        """Get dataset details by ID.
+
+        Args:
+            dataset_id: UUID of the dataset.
+
+        Returns:
+            Dataset dictionary.
+        """
+        return self._http.get(f"/api/datasets/{dataset_id}")
+
+    def versions(self, dataset_id: str) -> dict:
+        """List all versions of a dataset.
+
+        Args:
+            dataset_id: UUID of the dataset.
+
+        Returns:
+            Dictionary with paginated ``items`` list plus ``total``, ``limit``, and ``offset``.
+        """
+        return self._http.get(f"/api/datasets/{dataset_id}/versions")
+
+    def quality(self, dataset_id: str) -> dict:
+        """Get data quality report for a dataset.
+
+        Args:
+            dataset_id: UUID of the dataset.
+
+        Returns:
+            Quality metrics dictionary.
+        """
+        return self._http.get(f"/api/datasets/{dataset_id}/quality")
+
+    def columns(self, dataset_id: str) -> dict:
+        """Get column metadata for a dataset.
+
+        Args:
+            dataset_id: UUID of the dataset.
+
+        Returns:
+            Dictionary with ``columns`` list.
+        """
+        return self._http.get(f"/api/datasets/{dataset_id}/columns")
+
+    def analyze(self, dataset_id: str) -> dict:
+        """Run statistical analysis on a dataset.
+
+        Args:
+            dataset_id: UUID of the dataset.
+
+        Returns:
+            Analysis results dictionary.
+        """
+        return self._http.get(f"/api/datasets/{dataset_id}/analyze")
+
+    def delete(self, dataset_id: str) -> dict:
+        """Delete a dataset.
+
+        Args:
+            dataset_id: UUID of the dataset.
+
+        Returns:
+            Empty dictionary on success.
+        """
+        return self._http.delete(f"/api/datasets/{dataset_id}")
+
+    def download(self, dataset_id: str, output_path: str, format: str = "csv") -> str:
+        """Download dataset to a local file.
+
+        Args:
+            dataset_id: UUID of the dataset.
+            output_path: Local path to save the file.
+            format: Output format -- ``csv`` or ``parquet`` (default ``csv``).
+
+        Returns:
+            The output_path on success.
+        """
+        return self._http.download(
+            f"/api/datasets/{dataset_id}/download",
+            output_path,
+            params={"format": format},
+        )

coreplexml/deployments.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+"""Deployments resource for the CorePlexML SDK."""
+from typing import Union
+from coreplexml._http import HTTPClient
+
+
+class DeploymentsResource:
+    """Deploy models to production endpoints.
+
+    Deployments create REST API endpoints for real-time predictions,
+    with support for staging/production stages and canary rollouts.
+    """
+
+    def __init__(self, http: HTTPClient):
+        self._http = http
+
+    @staticmethod
+    def _normalize_deployment(payload: dict) -> dict:
+        """Normalize API payloads to a direct deployment object."""
+        if not isinstance(payload, dict):
+            return {}
+        dep = payload.get("deployment")
+        if isinstance(dep, dict):
+            out = dict(dep)
+            # Preserve model payload when present for callers that need it.
+            if isinstance(payload.get("model"), dict):
+                out["_model"] = payload["model"]
+            return out
+        return payload
+
+    def list(self, project_id: str, limit: int = 50, offset: int = 0) -> dict:
+        """List deployments for a project.
+
+        Args:
+            project_id: UUID of the project.
+            limit: Maximum results (default 50).
+            offset: Pagination offset.
+
+        Returns:
+            Dictionary with ``items`` list and ``total`` count.
+        """
+        return self._http.get(f"/api/mlops/projects/{project_id}/deployments", params={"limit": limit, "offset": offset})
+
+    def create(self, project_id: str, model_id: str, name: str, stage: str = "staging", config: dict | None = None) -> dict:
+        """Create a new deployment.
+
+        Args:
+            project_id: UUID of the project.
+            model_id: UUID of the model to deploy.
+            name: Deployment name.
+            stage: Deployment stage -- ``staging`` or ``production`` (default ``staging``).
+            config: Optional deployment configuration.
+
+        Returns:
+            Created deployment dictionary.
+        """
+        body: dict = {"model_id": model_id, "name": name, "stage": stage}
+        if config:
+            body["config"] = config
+        data = self._http.post(f"/api/mlops/projects/{project_id}/deployments", json=body)
+        return self._normalize_deployment(data)
+
+    def get(self, deployment_id: str) -> dict:
+        """Get deployment details.
+
+        Args:
+            deployment_id: UUID of the deployment.
+
+        Returns:
+            Deployment dictionary.
+        """
+        data = self._http.get(f"/api/mlops/deployments/{deployment_id}")
+        return self._normalize_deployment(data)
+
+    def predict(self, deployment_id: str, inputs: Union[dict, list], options: dict | None = None) -> dict:
+        """Make predictions via a deployed model endpoint.
+
+        Args:
+            deployment_id: UUID of the deployment.
+            inputs: Feature values -- a dict or list of dicts.
+            options: Optional prediction options.
+
+        Returns:
+            Prediction results dictionary.
+        """
+        body = {"inputs": inputs, "options": options or {}}
+        data = self._http.post(f"/api/mlops/deployments/{deployment_id}/predict", json=body)
+        # Convenience aliases for single-row predictions used in quickstart docs.
+        if isinstance(inputs, dict) and isinstance(data, dict):
+            preds = data.get("predictions")
+            if isinstance(preds, list) and preds:
+                first = preds[0] if isinstance(preds[0], dict) else {}
+                if "prediction" in first and "prediction" not in data:
+                    data["prediction"] = first.get("prediction")
+                if "probability" in first and "probability" not in data:
+                    data["probability"] = first.get("probability")
+                if "probabilities" in first and "probabilities" not in data:
+                    data["probabilities"] = first.get("probabilities")
+        return data
+
+    def promote(self, deployment_id: str) -> dict:
+        """Promote a staging deployment to production.
+
+        Args:
+            deployment_id: UUID of the deployment.
+
+        Returns:
+            Updated deployment dictionary.
+        """
+        # Backend requires explicit target stage.
+        data = self._http.post(
+            f"/api/mlops/deployments/{deployment_id}/promote",
+            json={"to_stage": "production"},
+        )
+        return self._normalize_deployment(data)
+
+    def rollback(
+        self,
+        deployment_id: str,
+        to_deployment_id: str | None = None,
+        to_model_id: str | None = None,
+    ) -> dict:
+        """Rollback a deployment to the previous version.
+
+        Args:
+            deployment_id: UUID of the deployment.
+            to_deployment_id: Optional target deployment UUID.
+            to_model_id: Optional target model UUID.
+
+        Returns:
+            Updated deployment dictionary.
+        """
+        body: dict = {}
+        if to_deployment_id:
+            body["to_deployment_id"] = to_deployment_id
+        if to_model_id:
+            body["to_model_id"] = to_model_id
+        data = self._http.post(f"/api/mlops/deployments/{deployment_id}/rollback", json=body)
+        return self._normalize_deployment(data)
+
+    def deactivate(self, deployment_id: str) -> dict:
+        """Deactivate a deployment.
+
+        Args:
+            deployment_id: UUID of the deployment.
+
+        Returns:
+            Updated deployment dictionary.
+        """
+        data = self._http.post(f"/api/mlops/deployments/{deployment_id}/deactivate")
+        return self._normalize_deployment(data)
+
+    def drift(self, deployment_id: str) -> dict:
+        """Get drift detection results for a deployment.
+
+        Args:
+            deployment_id: UUID of the deployment.
+
+        Returns:
+            Drift metrics dictionary.
+        """
+        return self._http.get(f"/api/mlops/deployments/{deployment_id}/drift")

coreplexml/exceptions.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+"""Exception classes for the CorePlexML Python SDK.
+
+All SDK exceptions inherit from :class:`CorePlexMLError`.
+"""
+
+
+class CorePlexMLError(Exception):
+    """Base exception for all CorePlexML SDK errors.
+
+    Attributes:
+        message: Human-readable error message.
+        status_code: HTTP status code (if applicable).
+        detail: Detailed error information from the server.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None, detail: str | None = None):
+        """Initialize error.
+
+        Args:
+            message: Error description.
+            status_code: HTTP status code.
+            detail: Server error detail.
+        """
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(message)
+
+
+class AuthenticationError(CorePlexMLError):
+    """Raised when authentication fails (HTTP 401 or 403).
+
+    This indicates an invalid, expired, or missing API key.
+    """
+
+    pass
+
+
+class NotFoundError(CorePlexMLError):
+    """Raised when a resource is not found (HTTP 404).
+
+    The requested resource (project, dataset, model, etc.) does not exist
+    or is not accessible to the current user.
+    """
+
+    pass
+
+
+class ValidationError(CorePlexMLError):
+    """Raised when input validation fails (HTTP 422).
+
+    The request body or parameters did not pass server-side validation.
+    """
+
+    pass