kalbio 0.2.1__tar.gz → 0.2.2__tar.gz

{kalbio-0.2.1 → kalbio-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kalbio
-Version: 0.2.1
+Version: 0.2.2
 Summary: Python client for kaleidoscope.bio
 License: MIT
 Author: Ahmed Elnaiem
@@ -11,6 +11,9 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: iap
+Requires-Dist: cachetools (>=6.2.5,<7.0.0)
+Requires-Dist: google-auth (>=2.0.0,<3.0.0) ; extra == "iap"
 Requires-Dist: pydantic (>=2.9.2,<3.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Project-URL: Documentation, https://api.docs.kaleidoscope.bio
@@ -32,7 +35,6 @@ Kalbio is a Python Client library for building applications with the Kaleidoscop
 - **Intuitive Resource Management**: Clean, object-oriented interface for programs, activities, records, and more
 - **Advanced Search & Filtering**: Powerful query capabilities with type-safe filter operators
 - **File Upload Support**: Direct file upload to record fields with support for multiple file types
-- **Comprehensive Coverage**: Access all Kaleidoscope platform resources through a unified client
 - **Bulk Operations**: Import and export capabilities for efficient data management
 
 ## Requirements
@@ -147,13 +149,13 @@ with open("experiment_data.csv", "rb") as file:
     )
 ```
 
-### Comprehensive Resource Management
+### Resource Management
 
-Kalbio provides services for all Kaleidoscope resources:
+Kalbio provides services for the following Kaleidoscope resources:
 
 - **Programs**: Organize your work
 - **Activities**: Tasks, experiments, projects, etc.
-- **Records**: Structured data storage
+- **Records**: Structured entity records
 - **Entity Types**: Define your data schemas
 - **Entity Fields**: Manage field definitions
 - **Labels**: Tag and categorize
@@ -170,7 +172,7 @@ Once you have a client instance, you have access to:
 | ---------------------- | ------------------------------------------- |
 | `client.programs`      | Program management                          |
 | `client.activities`    | Activities (tasks, experiments, projects)   |
-| `client.records`       | Record CRUD operations                      |
+| `client.records`       | Entity record CRUD operations               |
 | `client.entity_types`  | Entity type definitions                     |
 | `client.entity_fields` | Field definitions (key fields, data fields) |
 | `client.labels`        | Label management                            |

{kalbio-0.2.1 → kalbio-0.2.2}/README.md

@@ -12,7 +12,6 @@ Kalbio is a Python Client library for building applications with the Kaleidoscop
 - **Intuitive Resource Management**: Clean, object-oriented interface for programs, activities, records, and more
 - **Advanced Search & Filtering**: Powerful query capabilities with type-safe filter operators
 - **File Upload Support**: Direct file upload to record fields with support for multiple file types
-- **Comprehensive Coverage**: Access all Kaleidoscope platform resources through a unified client
 - **Bulk Operations**: Import and export capabilities for efficient data management
 
 ## Requirements
@@ -127,13 +126,13 @@ with open("experiment_data.csv", "rb") as file:
     )
 ```
 
-### Comprehensive Resource Management
+### Resource Management
 
-Kalbio provides services for all Kaleidoscope resources:
+Kalbio provides services for the following Kaleidoscope resources:
 
 - **Programs**: Organize your work
 - **Activities**: Tasks, experiments, projects, etc.
-- **Records**: Structured data storage
+- **Records**: Structured entity records
 - **Entity Types**: Define your data schemas
 - **Entity Fields**: Manage field definitions
 - **Labels**: Tag and categorize
@@ -150,7 +149,7 @@ Once you have a client instance, you have access to:
 | ---------------------- | ------------------------------------------- |
 | `client.programs`      | Program management                          |
 | `client.activities`    | Activities (tasks, experiments, projects)   |
-| `client.records`       | Record CRUD operations                      |
+| `client.records`       | Entity record CRUD operations               |
 | `client.entity_types`  | Entity type definitions                     |
 | `client.entity_fields` | Field definitions (key fields, data fields) |
 | `client.labels`        | Label management                            |

kalbio-0.2.2/kalbio/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import version, PackageNotFoundError
+
+from kalbio.client import KaleidoscopeClient
+
+try:
+    __version__ = version("kalbio")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = ["KaleidoscopeClient"]

{kalbio-0.2.1 → kalbio-0.2.2}/kalbio/activities.py

@@ -1,6 +1,6 @@
 """Activities Module for Kaleidoscope API Client.
 
-This module provides comprehensive functionality for managing activities (tasks, experiments,
+This module provides functionality for managing activities (tasks, experiments,
 projects, stages, milestones, and design cycles) within the Kaleidoscope platform. It includes
 models for activities, activity definitions, and properties, as well as service classes for
 performing CRUD operations and managing activity workflows.
@@ -876,12 +876,11 @@ class ActivitiesService:
 
         try:
             payload = {
-                "program_ids": program_ids,
                 "title": title,
                 "activity_type": activity_type,
                 "definition_id": self._resolve_definition_id(activity_definition_id),
-                "record_ids": [],
-                "assigned_user_ids": assigned_user_ids,
+                "program_ids": program_ids if program_ids else [],
+                "assigned_user_ids": assigned_user_ids if assigned_user_ids else [],
                 "start_date": start_date.isoformat() if start_date else None,
                 "duration": duration,
             }

{kalbio-0.2.1 → kalbio-0.2.2}/kalbio/client.py

@@ -59,8 +59,8 @@ Any file retrieved by the `KaleidoscopeClient` must be of one the above types"""
 TIMEOUT_MAXIMUM = 10
 """Maximum timeout for API requests in seconds."""
 
-_api_key = os.getenv("KALEIDOSCOPE_API_CLIENT_ID")
-_api_secret = os.getenv("KALEIDOSCOPE_API_CLIENT_SECRET")
+_env_client_id = os.getenv("KALEIDOSCOPE_API_CLIENT_ID")
+_env_client_secret = os.getenv("KALEIDOSCOPE_API_CLIENT_SECRET")
 
 
 class _TokenResponse(BaseModel):
@@ -107,21 +107,34 @@ class KaleidoscopeClient:
         )
         # Use the client to interact with various services
         programs = client.activities.get_activities()
+
+        # For applications behind Google Cloud IAP:
+        client = KaleidoscopeClient(
+            client_id="your_api_client_id",
+            client_secret="your_api_client_secret",
+            iap_client_id="your_iap_client_id.apps.googleusercontent.com"
+        )
         ```
     """
 
     _client_id: str
     _client_secret: str
+    _iap_client_id: Optional[str]
 
-    _refresh_token: str
-    _access_token: str
-    _refresh_before: datetime
+    _refresh_token: str = None
+    _access_token: str = None
+    _auth_refresh_before: Optional[datetime] = None
+
+    _iap_token: Optional[str] = None
+    _iap_refresh_before: Optional[datetime] = None
 
     def __init__(
         self,
-        client_id: Optional[str] = _api_key,
-        client_secret: Optional[str] = _api_secret,
+        client_id: Optional[str] = _env_client_id,
+        client_secret: Optional[str] = _env_client_secret,
         url: str = PROD_API_URL,
+        iap_client_id: Optional[str] = None,
+        verify_ssl: bool = True,
     ):
         """Initialize the Kaleidoscope API client.
 
@@ -133,6 +146,9 @@ class KaleidoscopeClient:
             client_secret (str): The API client secret for authentication.
             url (Optional[str]): The base URL for the API. Defaults to the production
                 API URL if not provided.
+            iap_client_id (Optional[str]): The OAuth client ID for Google Cloud
+                Identity-Aware Proxy. If provided, the client will automatically
+                fetch and refresh IAP tokens. Requires the `google-auth` package.
 
         Example:
             ```python
@@ -141,6 +157,13 @@ class KaleidoscopeClient:
 
             # Or rely on environment variables KALEIDOSCOPE_API_CLIENT_ID/SECRET
             client = KaleidoscopeClient()
+
+            # For applications behind Google Cloud IAP
+            client = KaleidoscopeClient(
+                client_id="id",
+                client_secret="secret",
+                iap_client_id="your_iap_client_id.apps.googleusercontent.com"
+            )
             ```
         """
         if client_id is None:
@@ -183,9 +206,34 @@ class KaleidoscopeClient:
 
         self._client_id = client_id
         self._client_secret = client_secret
-        self._get_auth_token()
+        self._iap_client_id = iap_client_id
+        self._verify_ssl = verify_ssl
+
+    def _refresh_iap_token(self):
+        """Fetch or refresh the IAP ID token.
+
+        Uses google-auth to obtain an ID token for the configured IAP client ID.
+        Supports both service account credentials and user credentials from
+        `gcloud auth application-default login`.
+
+        Raises:
+            ImportError: If google-auth is not installed.
+            google.auth.exceptions.DefaultCredentialsError: If no valid credentials found.
+        """
+        try:
+            from google.auth.transport.requests import Request
+            from google.oauth2 import id_token
+        except ImportError:
+            raise ImportError(
+                "The 'google-auth' package is required for IAP authentication. "
+                "Install it with: pip install google-auth or re-install kalbio with the iap option: "
+                "pip install kalbio[iap]"
+            )
+        self._iap_token = id_token.fetch_id_token(Request(), self._iap_client_id)
+        # IAP tokens typically expire in 1 hour; refresh 10 minutes early
+        self._iap_refresh_before = datetime.now() + timedelta(minutes=50)
 
-    def _update_tokens(self, resp: _TokenResponse):
+    def _update_auth_tokens(self, resp: _TokenResponse):
         """Persist access and refresh tokens and compute the next refresh time.
 
         Args:
@@ -193,7 +241,7 @@ class KaleidoscopeClient:
         """
         self._access_token = resp.access_token
         self._refresh_token = resp.refresh_token
-        self._last_refreshed_at = datetime.now() + timedelta(
+        self._auth_refresh_before = datetime.now() + timedelta(
             seconds=resp.expires_in - (60 * 10)  # add a 10 minute buffer
         )
 
@@ -210,14 +258,16 @@ class KaleidoscopeClient:
                 "client_id": self._client_id,
                 "client_secret": self._client_secret,
             },
+            headers=self._get_iap_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if auth_resp.status_code >= 400:
             raise RuntimeError(
                 f"Could not connect to server with client_id {self._client_id}: {auth_resp.content}"
             )
 
-        self._update_tokens(_TokenResponse.model_validate(auth_resp.json()))
+        self._update_auth_tokens(_TokenResponse.model_validate(auth_resp.json()))
 
     def _refresh_auth_token(self):
         """Refresh the access token using the stored refresh token.
@@ -234,27 +284,53 @@ class KaleidoscopeClient:
                 "grant_type": "refresh_token",
                 "refresh_token": self._refresh_token,
             },
+            headers=self._get_iap_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if auth_resp.status_code >= 400:
             raise RuntimeError(f"Could not refresh access token: {auth_resp.content}")
 
-        self._update_tokens(_TokenResponse.model_validate(auth_resp.json()))
+        self._update_auth_tokens(_TokenResponse.model_validate(auth_resp.json()))
+
+    def _get_iap_headers(self) -> dict:
+        """Build IAP headers, refreshing tokens if needed.
+
+        Returns:
+            dict: HTTP header for IAP (Proxy-Authorization)
+        """
+        headers = {}
+        if self._iap_client_id:
+            if (
+                self._iap_refresh_before is None
+                or datetime.now() > self._iap_refresh_before
+            ):
+                self._refresh_iap_token()
+            headers["Authorization"] = f"Bearer {self._iap_token}"
+
+        return headers
 
     def _get_headers(self) -> dict:
         """Build authorization headers, refreshing tokens if needed.
 
         Returns:
-            dict: HTTP headers including `Authorization` and `Content-Type`.
+            dict: HTTP headers including `Authorization`, `Content-Type`,
+                and optionally `Proxy-Authorization` for IAP.
         """
-        if datetime.now() > self._last_refreshed_at:
+        if (
+            self._auth_refresh_before is None
+            or datetime.now() > self._auth_refresh_before
+        ):
             self._refresh_auth_token()
 
-        return {
+        headers = {
             "Content-Type": "application/json",
-            "Authorization": f"Bearer {self._access_token}",
+            "X-Kal-Authorization": f"Bearer {self._access_token}",
+            **self._get_iap_headers(),
         }
 
+        return headers
+
     def _post(self, url: str, payload: dict) -> Any:
         """Send a POST request to the specified URL with the given payload.
 
@@ -277,6 +353,7 @@ class KaleidoscopeClient:
             data=json.dumps(payload),
             headers=self._get_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"POST {url} received {resp.status_code}: ", resp.content)
@@ -317,6 +394,7 @@ class KaleidoscopeClient:
             data=form_data,
             headers=self._get_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"POST {url} received {resp.status_code}: ", resp.content)
@@ -346,6 +424,7 @@ class KaleidoscopeClient:
             data=json.dumps(payload),
             headers=self._get_headers(),
             timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"PUT {url} received {resp.status_code}: ", resp.content)
@@ -374,7 +453,12 @@ class KaleidoscopeClient:
         if params:
             url += "?" + urllib.parse.urlencode(params)
 
-        resp = requests.get(url, headers=self._get_headers(), timeout=TIMEOUT_MAXIMUM)
+        resp = requests.get(
+            url,
+            headers=self._get_headers(),
+            timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
+        )
         if resp.status_code >= 400:
             print(f"GET {url} received {resp.status_code}", resp.content)
             return None
@@ -412,7 +496,11 @@ class KaleidoscopeClient:
             url += "?" + urllib.parse.urlencode(params)
 
         resp = requests.get(
-            url, headers=self._get_headers(), stream=True, timeout=TIMEOUT_MAXIMUM
+            url,
+            headers=self._get_headers(),
+            stream=True,
+            timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"GET {url} received {resp.status_code}", resp.content)
@@ -452,7 +540,10 @@ class KaleidoscopeClient:
             url += "?" + urllib.parse.urlencode(params)
 
         resp = requests.delete(
-            url, headers=self._get_headers(), timeout=TIMEOUT_MAXIMUM
+            url,
+            headers=self._get_headers(),
+            timeout=TIMEOUT_MAXIMUM,
+            verify=self._verify_ssl,
         )
         if resp.status_code >= 400:
             print(f"DELETE {url} received {resp.status_code}", resp.content)

{kalbio-0.2.1 → kalbio-0.2.2}/kalbio/programs.py

@@ -1,10 +1,10 @@
-"""Programs module for interacting with Kaleidoscope programs/experiments.
+"""Programs module for interacting with Kaleidoscope programs.
 
 The service allows users to retrieve all available programs in a workspace
 and filter programs by specific IDs.
 
 Classes:
-    Program: Data model for a Kaleidoscope program/experiment.
+    Program: Data model for a Kaleidoscope program.
     ProgramsService: Service for managing program retrieval operations.
 
 Example:
@@ -64,12 +64,12 @@ class ProgramsService:
 
     @lru_cache
     def get_programs(self) -> List[Program]:
-        """Retrieve all programs (experiments) available in the workspace.
+        """Retrieve all programs available in the workspace.
 
         This method caches its values.
 
         Returns:
-            List[Program]: A list of Program objects representing the experiments in the workspace.
+            List[Program]: A list of Program objects in the workspace.
 
         Note:
             If an exception occurs during the API request, it logs the error,

{kalbio-0.2.1 → kalbio-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "kalbio"
-version = "0.2.1"
+version = "0.2.2"
 description = "Python client for kaleidoscope.bio"
 authors = ["Ahmed Elnaiem <ahmed@kaleidoscope.bio>"]
 readme = "README.md"
@@ -10,6 +10,11 @@ license = "MIT"
 python = "^3.10"
 pydantic = "^2.9.2"
 requests = "^2.32.3"
+cachetools = "^6.2.5"
+google-auth = { version = "^2.0.0", optional = true }
+
+[tool.poetry.extras]
+iap = ["google-auth"]
 
 [tool.poetry.urls]
 Homepage = "https://github.com/kaleidoscope-tech/kalbio"

kalbio-0.2.1/kalbio/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"