ionworks-api 0.1.0__py3-none-any.whl

ionworks/__init__.py

@@ -0,0 +1,3 @@
+from .client import Ionworks, IonworksError
+
+__all__ = ["Ionworks", "IonworksError"]

ionworks/cell_instance.py

@@ -0,0 +1,201 @@
+from typing import Any
+
+from pydantic import ValidationError
+
+from .errors import IonworksError
+from .models import (
+    CellInstance,
+    CellInstanceDetail,
+    CellSpecificationInstances,
+    CellSpecificationInstancesWithSteps,
+)
+
+
+class CellInstanceClient:
+    def __init__(self, client: Any):
+        self.client = client
+
+    def get(self, cell_instance_id: str) -> CellInstance:
+        """
+        Get a specific cell instance by ID.
+        """
+        endpoint = f"/cell_instances/{cell_instance_id}"
+        try:
+            response_data = self.client.get(endpoint)
+            # Validate and parse the response
+            return CellInstance(**response_data)
+        except ValidationError as e:
+            raise ValueError(f"Invalid response format from {endpoint}: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+    def get_by_slug(self, cell_instance_slug: str) -> CellInstance:
+        """
+        Get a specific cell instance by slug.
+        """
+        endpoint = f"/cell_instances/slug/{cell_instance_slug}"
+        try:
+            response_data = self.client.get(endpoint)
+            return CellInstance(**response_data)
+        except ValidationError as e:
+            raise ValueError(f"Invalid response format from {endpoint}: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+    def list(self, cell_spec_id: str) -> list[CellInstance]:
+        """
+        List all cell instances for a cell specification by specification ID.
+        """
+        endpoint = f"/cell_specifications/{cell_spec_id}/cell_instances"
+        try:
+            response_data = self.client.get(endpoint)
+            if not isinstance(response_data, list):
+                raise ValueError(
+                    f"Unexpected response format from {endpoint}: expected a list, "
+                    f"got {type(response_data).__name__}"
+                )
+            # Validate each item in the list
+            return [CellInstance(**item) for item in response_data]
+        except ValidationError as e:
+            raise ValueError(f"Invalid item format in list from {endpoint}: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+    # def list_with_steps(
+    #     self, cell_instance_slug: str
+    # ) -> list[CellMeasurementDetailBase]:
+    #     """
+    #     List all cell measurements for a cell instance with steps.
+    #     """
+    #     endpoint = (
+    #         f"/cell_instances/{cell_instance_slug}/cell_measurements/with-steps"
+    #     )
+    #     response_data = self.client.get(endpoint)
+    #     return [CellMeasurementDetailBase(**item) for item in response_data]
+
+    def update(self, cell_instance_id: str, data: dict[str, Any]) -> CellInstance:
+        """
+        Update an existing cell instance.
+
+        Parameters
+        ----------
+        cell_instance_id : str
+            The ID of the cell instance to update.
+        data : dict
+            Dictionary containing the fields to update.
+
+        Returns
+        -------
+        CellInstance
+            The updated cell instance.
+        """
+        endpoint = f"/cell_instances/{cell_instance_id}"
+        response_data = self.client.put(endpoint, data)
+        return CellInstance(**response_data)
+
+    def delete(self, cell_instance_id: str) -> None:
+        """
+        Delete a cell instance by ID.
+        """
+        endpoint = f"/cell_instances/{cell_instance_id}"
+        self.client.delete(endpoint)
+
+    # Renamed and moved method from Data class
+    def detail(self, cell_instance_id: str) -> CellInstanceDetail:
+        """
+        Loads the full details for a cell instance from a single API endpoint,
+        including its spec, instance data, steps DataFrame, and time series DataFrame.
+        Uses the /detail endpoint.
+
+        Args:
+            organization: The organization slug.
+            cell_instance_id: The cell instance ID.
+
+        Returns:
+            A FullCellInstance object containing validated data.
+
+        Raises:
+            RuntimeError: If the API call fails.
+            ValueError: If the API response format is unexpected or parsing fails.
+            ValidationError: If the response data doesn't match expected models.
+        """
+        endpoint = f"/cell_instances/{cell_instance_id}/detail"
+        try:
+            response_data = self.client.get(endpoint)
+            return CellInstanceDetail(**response_data)
+
+        except ValidationError as e:
+            # Pydantic validation error during parsing
+            raise ValueError(f"Response validation failed for {endpoint}: {e}") from e
+        except ValueError as e:
+            # Re-raise our explicit format validation errors
+            raise e
+        except Exception as e:
+            # Catch client errors or any other unexpected issues
+            raise RuntimeError(
+                f"API call to {endpoint} failed or data processing error: {e}"
+            ) from e
+
+    def create(self, cell_spec_id: str, data: dict[str, Any]) -> CellInstance:
+        """
+        Create a new cell instance under a cell specification by
+        specification ID.
+        """
+        endpoint = f"/cell_specifications/{cell_spec_id}/cell_instances"
+        response_data = self.client.post(endpoint, data)
+        return CellInstance(**response_data)
+
+    def create_or_get(self, cell_spec_id: str, data: dict[str, Any]) -> CellInstance:
+        """
+        Create a new cell instance if it doesn't exist, otherwise get the
+        existing one.
+        """
+        try:
+            return self.create(cell_spec_id, data)
+        except IonworksError as e:
+            if e.status_code == 409 and e.data is not None:
+                existing_id = e.data.get("existing_cell_instance_id")
+                if existing_id:
+                    return self.get(existing_id)
+            raise e
+
+    def list_with_measurements(self, cell_spec_id: str) -> CellSpecificationInstances:
+        """
+        List all instances and measurements for a cell specification.
+        Returns normalized data: separate lists for specification, instances, and
+        measurements.
+        """
+        endpoint = (
+            f"/cell_specifications/{cell_spec_id}/cell_instances/with-measurements"
+        )
+        try:
+            response_data = self.client.get(endpoint)
+            return CellSpecificationInstances(**response_data)
+        except ValidationError as e:
+            raise ValueError(f"Response validation failed for {endpoint}: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+    def list_with_measurements_and_steps(
+        self, cell_spec_id: str
+    ) -> CellSpecificationInstancesWithSteps:
+        """
+        List all instances, measurements, and steps for a cell specification.
+        Returns normalized data: separate lists for specification, instances,
+        measurements, and steps.
+        """
+        endpoint = (
+            f"/cell_specifications/{cell_spec_id}/cell_instances"
+            "/with-measurements-and-steps"
+        )
+        try:
+            response_data = self.client.get(endpoint)
+            return CellSpecificationInstancesWithSteps(**response_data)
+        except ValidationError as e:
+            raise ValueError(f"Response validation failed for {endpoint}: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+
+class CellMeasurementClient:
+    pass

ionworks/cell_measurement.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+import io
+from typing import Any
+
+import pandas as pd
+import pyarrow as pa
+import pyarrow.parquet as pq
+from pydantic import ValidationError
+import requests
+
+from .errors import IonworksError
+from .models import (
+    CellInstanceMeasurementsWithSteps,
+    CellMeasurement,
+    CellMeasurementBundleResponse,
+    CellMeasurementDetail,
+    ConfirmUploadResponse,
+    InitiateUploadResponse,
+)
+from .validators import df_to_dict_validator
+
+
+class CellMeasurementClient:
+    def __init__(self, client: Any):
+        self.client = client
+
+    def list(self, cell_instance_id: str) -> list[CellMeasurement]:
+        """
+        List all cell measurements for a cell instance by instance ID.
+        """
+        endpoint = f"/cell_instances/{cell_instance_id}/cell_measurements"
+        response_data = self.client.get(endpoint)
+        return [CellMeasurement(**item) for item in response_data]
+
+    def get(self, measurement_id: str) -> CellMeasurement:
+        """
+        Get a specific cell measurement by its ID only.
+        """
+        endpoint = f"/cell_measurements/{measurement_id}"
+        response_data = self.client.get(endpoint)
+        return CellMeasurement(**response_data)
+
+    def detail(self, measurement_id: str) -> CellMeasurementDetail:
+        """
+        Get the full details for a cell measurement by measurement ID only.
+        """
+        endpoint = f"/cell_measurements/{measurement_id}/detail"
+        response_data = self.client.get(endpoint)
+        return CellMeasurementDetail(**response_data)
+
+    def update(self, measurement_id: str, data: dict[str, Any]) -> CellMeasurement:
+        """
+        Update an existing cell measurement.
+
+        Parameters
+        ----------
+        measurement_id : str
+            The ID of the cell measurement to update.
+        data : dict
+            Dictionary containing the fields to update.
+
+        Returns
+        -------
+        CellMeasurement
+            The updated cell measurement.
+        """
+        endpoint = f"/cell_measurements/{measurement_id}"
+        response_data = self.client.put(endpoint, data)
+        return CellMeasurement(**response_data)
+
+    def delete(self, measurement_id: str) -> None:
+        """
+        Delete a cell measurement by measurement ID only.
+        """
+        endpoint = f"/cell_measurements/{measurement_id}"
+        self.client.delete(endpoint)
+
+    def list_with_steps(
+        self, cell_instance_id: str
+    ) -> CellInstanceMeasurementsWithSteps:
+        """
+        List all measurements and steps for a specific cell instance.
+        Returns normalized data: separate lists for instance, measurements, and
+        steps.
+        """
+        endpoint = f"/cell_instances/{cell_instance_id}/cell_measurements/with-steps"
+        try:
+            response_data = self.client.get(endpoint)
+            return CellInstanceMeasurementsWithSteps(**response_data)
+        except ValidationError as e:
+            raise ValueError(f"Response validation failed for {endpoint}: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+    def get_by_slugs(
+        self, cell_instance_slug: str, measurement_slug: str
+    ) -> CellMeasurement:
+        """
+        Get a specific cell measurement by instance slug and measurement slug.
+
+        Returns metadata only (no steps or time series).
+        """
+        endpoint = (
+            f"/cell_instances/slug/{cell_instance_slug}"
+            f"/cell_measurements/slug/{measurement_slug}"
+        )
+        response_data = self.client.get(endpoint)
+        return CellMeasurement(**response_data)
+
+    def _dataframe_to_parquet(self, df: pd.DataFrame) -> bytes:
+        """
+        Convert a pandas DataFrame to parquet bytes.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            The DataFrame to convert.
+
+        Returns
+        -------
+        bytes
+            Parquet file content (uses built-in zstd compression).
+        """
+        table = pa.Table.from_pandas(df)
+        buffer = io.BytesIO()
+        pq.write_table(table, buffer, compression="zstd")
+        return buffer.getvalue()
+
+    def _initiate_upload(
+        self,
+        cell_instance_id: str,
+        name: str,
+        notes: str | None = None,
+    ) -> InitiateUploadResponse:
+        """
+        Initiate a signed URL upload for a new measurement.
+
+        Parameters
+        ----------
+        cell_instance_id : str
+            The ID of the cell instance.
+        name : str
+            Name for the new measurement.
+        notes : str, optional
+            Optional notes for the measurement.
+
+        Returns
+        -------
+        InitiateUploadResponse
+            Response containing measurement_id, signed_url, token, path.
+        """
+        endpoint = (
+            f"/cell_instances/{cell_instance_id}/cell_measurements/initiate-upload"
+        )
+        measurement_data: dict[str, Any] = {"name": name}
+        if notes:
+            measurement_data["notes"] = notes
+
+        payload = {"measurement": measurement_data}
+        response_data = self.client.post(endpoint, payload)
+        return InitiateUploadResponse(**response_data)
+
+    def _upload_to_signed_url(self, signed_url: str, parquet_bytes: bytes) -> None:
+        """
+        Upload parquet bytes to a signed URL.
+
+        Parameters
+        ----------
+        signed_url : str
+            The signed URL to upload to.
+        parquet_bytes : bytes
+            The parquet file content to upload.
+
+        Raises
+        ------
+        IonworksError
+            If the upload fails.
+        """
+        # Handle Docker-internal URLs when running locally
+        url = signed_url.replace("host.docker.internal", "localhost")
+
+        try:
+            response = requests.put(
+                url,
+                data=parquet_bytes,
+                headers={"Content-Type": "application/octet-stream"},
+            )
+            response.raise_for_status()
+        except requests.exceptions.RequestException as e:
+            raise IonworksError(f"Failed to upload to signed URL: {e}") from None
+
+    def _confirm_upload(
+        self,
+        measurement_id: str,
+        cell_instance_id: str,
+        measurement_data: dict[str, Any],
+        steps: dict[str, list[Any]] | None = None,
+    ) -> ConfirmUploadResponse:
+        """
+        Confirm a signed URL upload after successful file upload.
+
+        This creates the measurement record in the database. The measurement
+        data must be passed again (same as initiate) to ensure no orphaned
+        records are created if the file upload fails.
+
+        Parameters
+        ----------
+        measurement_id : str
+            The pre-generated ID for the measurement (from initiate).
+        cell_instance_id : str
+            The ID of the parent cell instance.
+        measurement_data : dict
+            Measurement metadata (name, notes, etc.) - same as passed to initiate.
+        steps : dict, optional
+            Pre-calculated steps data. If not provided, will be auto-calculated.
+
+        Returns
+        -------
+        ConfirmUploadResponse
+            Response containing instance, measurement, steps_created, and
+            file_path.
+        """
+        endpoint = f"/cell_measurements/{measurement_id}/confirm-upload"
+        payload: dict[str, Any] = {
+            "cell_instance_id": cell_instance_id,
+            "measurement": measurement_data,
+        }
+        if steps:
+            payload["steps"] = steps
+
+        response_data = self.client.post(endpoint, payload)
+        return ConfirmUploadResponse(**response_data)
+
+    def create(
+        self,
+        cell_instance_id: str,
+        measurement_detail: dict[str, Any],
+    ) -> CellMeasurementBundleResponse:
+        """
+        Create a new cell measurement with steps and time series data
+        for a cell instance.
+
+        Uses signed URL upload for better performance with large datasets.
+        Data is uploaded directly to storage as parquet, bypassing backend
+        JSON parsing. No database record is created until the upload is
+        confirmed, preventing orphaned records if upload fails.
+
+        Parameters
+        ----------
+        cell_instance_id : str
+            The ID of the cell instance to create the measurement for.
+        measurement_detail : dict
+            Dictionary containing 'measurement', 'steps', and 'time_series'.
+            - measurement: dict with 'name' (required) and 'notes' (optional)
+            - time_series: pandas DataFrame or dict with time series data
+            - steps: optional dict with pre-calculated steps data
+
+        Returns
+        -------
+        CellMeasurementBundleResponse
+            Response containing the created measurement, steps count, and
+            file path.
+        """
+        measurement_info = measurement_detail["measurement"]
+        name = measurement_info["name"]
+        notes = measurement_info.get("notes")
+
+        # Step 1: Initiate upload (validates metadata, returns signed URL, no DB record)
+        initiate_result = self._initiate_upload(cell_instance_id, name, notes)
+
+        # Step 2: Convert time_series to DataFrame if needed, then to parquet
+        time_series = measurement_detail["time_series"]
+        if isinstance(time_series, dict):
+            time_series = pd.DataFrame(time_series)
+        parquet_bytes = self._dataframe_to_parquet(time_series)
+
+        # Step 3: Upload to signed URL
+        self._upload_to_signed_url(initiate_result.signed_url, parquet_bytes)
+
+        # Step 4: Confirm upload (creates the measurement record)
+        steps = measurement_detail.get("steps")
+        if steps is not None:
+            # Convert DataFrame to dict if needed
+            steps = df_to_dict_validator(steps)
+        confirm_result = self._confirm_upload(
+            measurement_id=initiate_result.measurement_id,
+            cell_instance_id=cell_instance_id,
+            measurement_data=measurement_info,
+            steps=steps,
+        )
+
+        return CellMeasurementBundleResponse(
+            measurement=confirm_result.measurement,
+            steps_created=confirm_result.steps_created,
+            file_path=confirm_result.file_path,
+        )
+
+    def create_or_get(
+        self,
+        cell_instance_id: str,
+        measurement_detail: dict[str, Any],
+    ) -> CellMeasurementBundleResponse | CellMeasurement:
+        """
+        Create a new cell measurement if it doesn't exist, otherwise get the
+        existing one.
+
+        Parameters
+        ----------
+        cell_instance_id : str
+            The ID of the cell instance to create the measurement for.
+        measurement_detail : dict
+            Dictionary containing 'measurement', 'steps', and 'time_series'.
+
+        Returns
+        -------
+        CellMeasurementBundleResponse | CellMeasurement
+            Response containing the created measurement bundle, or the existing
+            measurement if it already exists.
+        """
+        try:
+            return self.create(cell_instance_id, measurement_detail)
+        except IonworksError as e:
+            # Check for duplicate key error (409 conflict or unique constraint)
+            if e.status_code == 409 or (
+                "duplicate key" in str(e).lower()
+                and "cell_measurements_name_cell_instance_id_key" in str(e)
+            ):
+                # Look up existing measurement by name
+                measurement_name = measurement_detail["measurement"]["name"]
+                measurements = self.list(cell_instance_id)
+                for m in measurements:
+                    if m.name == measurement_name:
+                        return m
+                raise ValueError(
+                    f"Measurement '{measurement_name}' reported as duplicate "
+                    "but could not be found"
+                )
+            raise

ionworks/cell_specification.py

@@ -0,0 +1,108 @@
+from typing import Any
+
+from pydantic import ValidationError
+
+from ionworks.errors import IonworksError
+
+from .models import CellSpecification
+
+
+class CellSpecificationClient:
+    def __init__(self, client: Any):
+        self.client = client
+
+    def get(self, cell_spec_id: str) -> CellSpecification:
+        """
+        Get a specific cell specification by ID.
+        """
+        endpoint = f"/cell_specifications/{cell_spec_id}"
+        try:
+            response_data = self.client.get(endpoint)
+            # Validate and parse the response
+            return CellSpecification(**response_data)
+        except ValidationError as e:
+            raise ValueError(f"Invalid response format from {endpoint}: {e}") from e
+        except Exception as e:  # Catch potential client errors
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+    def list(self) -> list[CellSpecification]:
+        """
+        List all cell specs.
+        """
+        endpoint = "/cell_specifications"
+        try:
+            response_data = self.client.get(endpoint)
+            if not isinstance(response_data, list):
+                raise ValueError(
+                    f"Unexpected response format from {endpoint}: expected a list, "
+                    f"got {type(response_data).__name__}"
+                )
+            # Validate each item in the list
+            return [CellSpecification(**item) for item in response_data]
+        except ValidationError as e:
+            raise ValueError(f"Invalid item format in list from {endpoint}: {e}") from e
+        except Exception as e:  # Catch potential client errors
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
+
+    def create(self, data: dict[str, Any]) -> CellSpecification:
+        """
+        Create a new cell spec.
+        """
+        endpoint = "/cell_specifications"
+        response_data = self.client.post(endpoint, data)
+        return CellSpecification(**response_data)
+
+    def create_or_get(self, data: dict[str, Any]) -> CellSpecification:
+        """
+        Create a new cell spec if it doesn't exist, otherwise get the
+        existing one.
+        """
+        try:
+            return self.create(data)
+        except IonworksError as e:
+            if e.status_code == 409 and e.data is not None:
+                existing_id = e.data.get("existing_cell_specification_id")
+                if existing_id:
+                    return self.get(existing_id)
+            raise e
+
+    def update(self, cell_spec_id: str, data: dict[str, Any]) -> CellSpecification:
+        """
+        Update an existing cell specification.
+
+        Parameters
+        ----------
+        cell_spec_id : str
+            The ID of the cell specification to update.
+        data : dict
+            Dictionary containing the fields to update. Supports nested
+            component/material data for upsert.
+
+        Returns
+        -------
+        CellSpecification
+            The updated cell specification.
+        """
+        endpoint = f"/cell_specifications/{cell_spec_id}"
+        response_data = self.client.put(endpoint, data)
+        return CellSpecification(**response_data)
+
+    def delete(self, cell_spec_id: str) -> None:
+        """
+        Delete a cell specification by ID.
+        """
+        endpoint = f"/cell_specifications/{cell_spec_id}"
+        self.client.delete(endpoint)
+
+    def get_by_slug(self, cell_spec_slug: str) -> CellSpecification:
+        """
+        Get a specific cell specification by slug.
+        """
+        endpoint = f"/cell_specifications/slug/{cell_spec_slug}"
+        try:
+            response_data = self.client.get(endpoint)
+            return CellSpecification(**response_data)
+        except ValidationError as e:
+            raise ValueError(f"Invalid response format from {endpoint}: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"API call to {endpoint} failed: {e}") from e