kalbio 0.2.0__py3-none-any.whl

kalbio/workspace.py

@@ -0,0 +1,315 @@
+"""Provides models and services for managing workspaces in the Kaleidoscope system.
+
+This module contains data models for workspaces, workspace users, workspace groups,
+and workspace events, along with a service class for interacting with workspace-related
+API endpoints.
+
+Classes:
+    WorkspaceAccessLevelEnum: Enumeration of possible access levels for workspace users.
+    Workspace: Model representing a workspace with its basic metadata.
+    WorkspaceUser: Model representing a user within a workspace, including access level.
+    WorkspaceGroup: Model representing a group of users within a workspace.
+    WorkspaceEvent: Model representing an event that occurred within a workspace.
+    WorkspaceService: Service class providing methods to interact with workspace API endpoints.
+
+Example:
+    ```python
+        # get an instance of the workspace
+        workspace = client.workspace.get_workspace()
+
+        # get all members in the workspace
+        members = client.workspace.get_members()
+
+        # get all events, with search criteria
+        events = client.workspace.get_events(event_types=["create", "update"])
+    ```
+"""
+
+from datetime import datetime
+import json
+import logging
+from enum import Enum
+from functools import lru_cache
+from typing import List, Optional, TypedDict, Unpack
+from kalbio._kaleidoscope_model import _KaleidoscopeBaseModel
+from kalbio.client import KaleidoscopeClient
+from pydantic import TypeAdapter
+
+_logger = logging.getLogger(__name__)
+
+
+class WorkspaceAccessLevelEnum(str, Enum):
+    """Enumeration of possible access levels for workspace users.
+
+    Attributes:
+        ADMIN: Administrator access with full privileges.
+        TEAM_MEMBER: Regular team member access.
+        GUEST: Guest access with limited privileges.
+        VIEWER: Read-only viewer access.
+        DEACTIVATED: Deactivated user status.
+    """
+
+    ADMIN = "admin"
+    TEAM_MEMBER = "team-member"
+    GUEST = "guest"
+    VIEWER = "viewer"
+    DEACTIVATED = "deactivated"
+
+
+class Workspace(_KaleidoscopeBaseModel):
+    """A model representing a workspace in the Kaleidoscope system.
+
+    This class extends _KaleidoscopeBaseModel and provides a structured representation
+    of a workspace with its associated metadata and utility methods for serialization
+    and string representation.
+
+    Attributes:
+        id (str): UUID of the workspace
+        workspace_name (str): The name identifier for the workspace.
+    """
+
+    workspace_name: str
+
+    def __str__(self):
+        return f"{self.workspace_name}"
+
+
+class WorkspaceUser(_KaleidoscopeBaseModel):
+    """Represents a user within a workspace with their access permissions and contact information.
+
+    This class models a workspace user, storing their identification, name preferences,
+    access level, and email address. It inherits from _KaleidoscopeBaseModel and provides
+    utility methods for serialization and string representation.
+
+    Attributes:
+        full_name (Optional[str]): The user's full legal or registered name.
+        preferred_name (Optional[str]): The name the user prefers to be called.
+        access_level (WorkspaceAccessLevelEnum): The user's permission level within the workspace.
+        email (str): The user's email address for communication and identification.
+    """
+
+    full_name: Optional[str]
+    preferred_name: Optional[str]
+    access_level: WorkspaceAccessLevelEnum
+    email: str
+
+    def __str__(self):
+        return f"{self.full_name}"
+
+
+class WorkspaceGroup(_KaleidoscopeBaseModel):
+    """Represents a workspace group in the Kaleidoscope system.
+
+    A WorkspaceGroup is a collection of users and programs that are organized together
+    under a common group name and associated email address.
+
+    Attributes:
+        group_name (str): The name of the workspace group.
+        user_ids (List[str]): A list of user IDs that belong to this workspace group.
+        program_ids (List[str]): A list of program IDs associated with this workspace group.
+        email (str): The email address associated with this workspace group.
+    """
+
+    group_name: str
+    user_ids: List[str]
+    program_ids: List[str]
+    email: str
+
+    def __str__(self):
+        return f"{self.group_name}"
+
+
+class WorkspaceEvent(_KaleidoscopeBaseModel):
+    """Represents a workspace event in the Kaleidoscope system.
+
+    This class models events that occur within a workspace, such as user actions,
+    resource modifications, or system-generated events. It inherits from
+    _KaleidoscopeBaseModel and provides methods for serialization and representation.
+
+    Attributes:
+        full_name (str): The full name of the user associated with the event.
+        preferred_name (Optional[str]): The preferred name of the user, if available.
+        is_bot (bool): Flag indicating whether the event was triggered by a bot.
+        event_attrs (dict): Additional attributes specific to the event type.
+        created_at (datetime): Timestamp when the event was created.
+        resource_id (Optional[str]): ID of the resource associated with the event, if applicable.
+        resource_type (Optional[str]): Type of the resource associated with the event, if applicable.
+        event_type (str): The type/category of the event.
+        event_type_version (int): Version number of the event type schema.
+        event_user_id (str): The unique identifier of the user who triggered the event.
+        parent_bulk_event_id (str): ID of the parent event if this is part of a bulk operation.
+        is_bulk (bool): Flag indicating whether this is a bulk event.
+    """
+
+    full_name: str
+    preferred_name: Optional[str]
+    is_bot: bool
+    event_attrs: dict
+    created_at: datetime
+    resource_id: Optional[str]
+    resource_type: Optional[str]
+    event_type: str
+    event_type_version: int
+    event_user_id: str
+    parent_bulk_event_id: str
+    is_bulk: bool
+
+    def __str__(self):
+        return f"{self.id}:{self.event_type}"
+
+
+class WorkspaceService:
+    """Service class for managing workspace-related operations in Kaleidoscope.
+
+    This service provides methods to retrieve workspace information, members, groups,
+    and events. It uses caching (via lru_cache) for frequently accessed data like
+    workspace details, members, and groups to improve performance.
+
+    Example:
+        ```python
+        # get an instance of the workspace
+        workspace = client.workspace.get_workspace()
+
+        # get all members in the workspace
+        members = client.workspace.get_members()
+
+        # get all events, with search criteria
+        events = client.workspace.get_events(event_types=["create", "update"])
+        ```
+
+    Note:
+        Cached methods (get_workspace, get_members, get_groups) will automatically
+        clear their cache on error to ensure stale data is not returned on subsequent calls.
+    """
+
+    def __init__(self, client: KaleidoscopeClient):
+        self._client = client
+
+    @lru_cache
+    def get_workspace(self) -> Workspace | None:
+        """Retrieves the authenticated workspace.
+
+        This method caches its values.
+
+        Returns:
+            (Workspace | None): The active workspace, or None if an error occurs.
+        """
+        try:
+            resp = self._client._get("/workspaces/active")
+            return Workspace.model_validate(resp)
+        except Exception as e:
+            _logger.error(f"Error fetching workspace: {e}")
+            self.get_workspace.cache_clear()
+            return None
+
+    @lru_cache
+    def get_members(self) -> List[WorkspaceUser]:
+        """Retrieves the members of the authenticated workspace.
+
+        This method caches its values.
+
+        Returns:
+            List[WorkspaceUser]: The users in the workspace.
+
+        Note:
+            If an exception occurs during the API request, it logs the error,
+            clears the cache, and returns an empty list.
+        """
+        try:
+            resp = self._client._get("/workspaces/members")
+            return TypeAdapter(List[WorkspaceUser]).validate_python(resp)
+        except Exception as e:
+            _logger.error(f"Error fetching members: {e}")
+            self.get_members.cache_clear()
+            return []
+
+    def get_members_by_ids(self, ids: List[str]) -> List[WorkspaceUser]:
+        """Retrieves a list of WorkspaceUser objects whose IDs match the provided list.
+
+        Args:
+            ids (List[str]): A list of member IDs to filter by.
+
+        Returns:
+            List[WorkspaceUser]: A list of WorkspaceUser instances with IDs found in ids.
+        """
+        return [member for member in self.get_members() if member.id in ids]
+
+    @lru_cache
+    def get_groups(self) -> List[WorkspaceGroup]:
+        """Retrieves the groups of the authenticated workspace.
+
+        This method caches its values.
+
+        Returns:
+            List[WorkspaceGroup]: The groups in the workspace.
+
+        Note:
+            If an exception occurs during the API request, it logs the error,
+            clears the cache, and returns an empty list.
+        """
+        try:
+            resp = self._client._get("/workspaces/groups")
+            return TypeAdapter(List[WorkspaceGroup]).validate_python(resp)
+        except Exception as e:
+            _logger.error(f"Error fetching groups: {e}")
+            self.get_groups.cache_clear()
+            return []
+
+    def get_groups_by_ids(self, ids: List[str]) -> List[WorkspaceGroup]:
+        """Retrieves a list of WorkspaceGroup objects whose IDs match the provided list.
+
+        Args:
+            ids (List[str]): A list of group IDs to filter by.
+
+        Returns:
+            List[WorkspaceGroup]: A list of WorkspaceGroup instances with IDs found in ids.
+        """
+        return [group for group in self.get_groups() if group.id in ids]
+
+    class EventsQuery(TypedDict):
+        """TypedDict for workspace events query parameters.
+
+        Attributes:
+            page (Optional[int]): The page number for pagination.
+            page_size (Optional[int]): The number of items per page.
+            event_types (List[str]): List of event types to filter by.
+            resource_type (str): The type of resource to filter by.
+            event_user_ids (list[str]): List of user IDs to filter events by.
+            after_date (datetime): Filter events occurring after this date.
+            before_date (datetime): Filter events occurring before this date.
+        """
+
+        page: Optional[int]
+        page_size: Optional[int]
+        event_types: List[str]
+        resource_type: str
+        event_user_ids: list[str]
+        after_date: datetime
+        before_date: datetime
+
+    def get_events(self, **params: Unpack[EventsQuery]) -> List[WorkspaceEvent]:
+        """Searches for events using the provided query parameters.
+
+        Args:
+            **params (Unpack[EventsQuery]): Keyword arguments representing search criteria. Non-string values will be JSON-encoded before being sent.
+
+        Returns:
+            list[WorkspaceEvent]: A list of events matching the search criteria.
+            Returns an empty list if the response is empty.
+
+        Note:
+            If an exception occurs during the API request, it logs the error and returns an empty list.
+        """
+        try:
+            client_params = {
+                key: (value if isinstance(value, str) else json.dumps(value))
+                for key, value in params.items()
+            }
+            resp = self._client._get("/workspaces/events", client_params)
+            if resp is None:
+                return []
+
+            return resp
+        except Exception as e:
+            _logger.error(f"Error fetching events: {e}")
+            return []

kalbio-0.2.0.dist-info/METADATA

@@ -0,0 +1,289 @@
+Metadata-Version: 2.1
+Name: kalbio
+Version: 0.2.0
+Summary: Python client for Kaleidoscope API
+License: MIT
+Author: Ahmed Elnaiem
+Author-email: ahmed@kaleidoscope.bio
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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
+Project-URL: Homepage, https://github.com/kaleidoscope-tech/kalbio
+Project-URL: Repository, https://github.com/kaleidoscope-tech/kalbio
+Description-Content-Type: text/markdown
+
+# Kalbio
+
+<!-- **Source Code**: [https://github.com/kaleidoscope-tech/kalbio](https://github.com/kaleidoscope-tech/kalbio)
+
+--- -->
+
+Kalbio is a Python Client library for building applications with the Kaleidoscope platform.
+
+## Key features
+
+- **Type-safe API Client**: Built with Pydantic models for full type safety and IDE autocomplete support
+- **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
+
+- [Python](https://docs.python.org/3/) 3.12+
+- [Pydantic](https://docs.pydantic.dev/) 2.9.2+
+- [Requests](https://requests.readthedocs.io/) 2.32.3+
+
+<!--
+TODO
+
+## Installation
+
+Clone the repository and install the client in editable mode:
+
+```bash
+git clone https://github.com/kaleidoscope-tech/kalbio.git
+cd kalbio
+pip install -e .
+```
+-->
+
+## Authentication
+
+Set your API credentials as environment variables before running examples:
+
+```bash
+export KALEIDOSCOPE_API_CLIENT_ID="your_client_id"
+export KALEIDOSCOPE_API_CLIENT_SECRET="your_client_secret"
+```
+
+## Example
+
+### Create it
+
+Create a file `main.py` with:
+
+```python
+from kalbio.client import KaleidoscopeClient
+from kalbio.activities import ActivityStatusEnum
+
+# Initialize the client using environment variables
+client = KaleidoscopeClient()
+
+# # Or with explicit arguements
+# client = KaleidoscopeClient(
+#     client_id="your_api_client_id",
+#     client_secret="your_api_client_secret"
+# )
+
+# Work with activities
+activities = client.activities.get_activities()
+for activity in activities:
+    print(f"Activity: {activity.title} - Status: {activity.status.value}")
+```
+
+### Run it
+
+Run the program with:
+
+```bash
+python main.py
+```
+
+Output:
+
+```text
+Activity: Experiment 1 - Status: to do
+Activity: Task 1 - Status: to do
+Activity: Drug Tests - Status: in progress
+```
+
+### Check it
+
+You now have a fully functional Kaleidoscope API client.
+
+## Features
+
+### Intuitive API Design
+
+Work with resources naturally:
+
+```python
+# Records
+record = client.records.get_record_by_id("record-uuid")
+
+if record:
+    record.add_value(
+        field_id="field-uuid",
+        content="Experiment result",
+        activity_id="activity-uuid"
+    )
+
+# Entity Types
+entity_types = client.entity_types.get_types()
+compound_type = client.entity_types.get_type_by_name("Compound")
+```
+
+### File Upload Support
+
+Upload files directly to records:
+
+```python
+# Upload a file to a record field
+with open("experiment_data.csv", "rb") as file:
+    record.update_field_file(
+        field_id="data-field-id",
+        file_name="experiment_data.csv",
+        file_data=file,
+        file_type="text/csv",
+        activity_id="activity-uuid"
+    )
+```
+
+### Comprehensive Resource Management
+
+Kalbio provides services for all Kaleidoscope resources:
+
+- **Programs**: Organize your work
+- **Activities**: Tasks, experiments, projects, etc.
+- **Records**: Structured data storage
+- **Entity Types**: Define your data schemas
+- **Entity Fields**: Manage field definitions
+- **Labels**: Tag and categorize
+- **Imports/Exports**: Bulk data operations
+- **Workspace**: User and group management
+
+## Interactive Documentation
+
+### Available Services
+
+Once you have a client instance, you have access to:
+
+| Service                | Description                                 |
+| ---------------------- | ------------------------------------------- |
+| `client.programs`      | Program management                          |
+| `client.activities`    | Activities (tasks, experiments, projects)   |
+| `client.records`       | Record CRUD operations                      |
+| `client.entity_types`  | Entity type definitions                     |
+| `client.entity_fields` | Field definitions (key fields, data fields) |
+| `client.labels`        | Label management                            |
+| `client.imports`       | Import operations and templates             |
+| `client.exports`       | Export operations                           |
+| `client.workspace`     | Workspace, users, and groups                |
+
+### Activity Management
+
+```python
+# Create an activity
+new_activity = client.activities.create_activity(
+    title="Synthesis Experiment",
+    activity_type="experiment",
+    program_ids=["program-uuid"],
+    assigned_user_ids=["user-uuid"]
+)
+
+if new_activity:
+    # Update activity status
+    new_activity.update(status=ActivityStatusEnum.IN_PROGRESS)
+
+    # Add records to activity
+    new_activity.add_records(["record-uuid-1", "record-uuid-2"])
+
+    # Get activity data
+    record_data = new_activity.get_record_data()
+```
+
+### Record Operations
+
+```python
+# Get record by ID
+record = client.records.get_record_by_id("record-uuid")
+
+if record:
+    # Add a value
+    record.add_value(
+        field_id="field-uuid",
+        content="High purity sample",
+        activity_id="activity-uuid"
+    )
+
+    # Get field value
+    value = record.get_value_content(field_id="field-uuid")
+
+    # Get values for specific activity
+    activity_values = record.get_activity_data(activity_id="activity-uuid")
+```
+
+## Full Example
+
+Here's a complete workflow example:
+
+```python
+# Initialize client
+client = KaleidoscopeClient(
+    KALEIDOSCOPE_API_CLIENT_ID,
+    KALEIDOSCOPE_API_CLIENT_SECRET,
+    "https://api.kaleidoscope.bio",
+)
+
+# 1. Get or create a program
+programs = client.programs.get_programs()
+program = programs[0] if programs else None
+
+if program:
+    print(f"Working with program: {program.title}")
+
+    # 2. Get entity types
+    entity_types = client.entity_types.get_types()
+    compound_type = next(
+        (et for et in entity_types if et.slice_name == "Compound"),
+        None
+    )
+
+    if compound_type:
+        # 3. Search for records
+        record_ids = client.records.search_records(
+            entity_slice_id=compound_type.id,
+            limit=10
+        )
+
+        print(f"Found {len(record_ids)} compound records")
+
+        # 4. Get detailed record information
+        if record_ids:
+            record = client.records.get_record_by_id(record_ids[0])
+            assert record
+            print(f"Record: {record.record_identifier}")
+
+            # 5. Create an activity
+            activity = client.activities.create_activity(
+                title="Quality Check",
+                activity_type="task",
+                program_ids=[program.id]
+            )
+            assert activity
+
+            # 6. Add data to record
+            record.add_value(
+                field_id="notes-field-id",
+                content="Quality check completed successfully",
+                activity_id=activity.id
+            )
+
+            # 7. Update activity status
+            activity.update(task_status=ActivityStatusEnum.COMPLETE)
+
+            print("Workflow completed successfully!")
+```
+
+## Support
+
+For support, email [support@kaleidoscope.bio](mailto:support@kaleidoscope.bio).
+

kalbio-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+kalbio/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+kalbio/_kaleidoscope_model.py,sha256=UnSpiubaEkoyOLjAmKzQGZdXOUMthuP0HiYU1Lo2sFM,4465
+kalbio/activities.py,sha256=zvemwfuiPgTjhpMhzsHon7UselKmuqw9tWpM766m5F4,40621
+kalbio/client.py,sha256=a2NP-FfIbIuRXQ-19KSxcbjyvCpfSXdkUiypgp2-jh8,16822
+kalbio/dashboards.py,sha256=0P8lNiTmyaQj0y8B7AKf1VWU0qHuTUGJ_4xDVtr9jXA,9334
+kalbio/entity_fields.py,sha256=HnvOSE9C_UB59ioY5mB5Sn_V3OwnfRuYZ_IJtEw2vUY,15184
+kalbio/entity_types.py,sha256=THXGbIV9dFU2DvIuDd7Q29onmEs9KdeqsB_tq6ZXmR4,6527
+kalbio/exports.py,sha256=xFdNzajrGUlPZx6tNhgqiUg1lVnrayVQW12d-SmKWA4,5236
+kalbio/helpers.py,sha256=TBPVls1GzfUygDAwCldI5sXYTgBC2pEUSEU0OtrQi3I,1955
+kalbio/imports.py,sha256=s7LIETRQtT6MXEmsbIT2FwFJdE3eh25ujbs4ZFbWYns,3523
+kalbio/labels.py,sha256=Vy7PiZ8vFXIBbrCmdHyz7ANooO0-giTvTLH7WwU_Mo8,2704
+kalbio/programs.py,sha256=SKVJbF08Pp4r7dXfy9NNQnJRnSh-kOpDVdib197EWUM,3017
+kalbio/property_fields.py,sha256=eCYzSnG-HQB6ECHFNpaGkpm3azHe-lDYVNJUpq5TOtc,2763
+kalbio/record_views.py,sha256=M3NEOhnN4JHA8ZO0I91L9pAVdVY0kmqSent3HehzFTI,7208
+kalbio/records.py,sha256=BXuFCA90ViSMp_TtnWJYfQnJgH9Hz-5u4iT0wF0B1UM,40480
+kalbio/workspace.py,sha256=YpeLtzo3o8um_CQLyTT8GnvkF6I195y43JhNN2GmM0M,11670
+kalbio-0.2.0.dist-info/METADATA,sha256=QkC4c9VlAZ5NkvtwY85tOAFs4hRkK32Q8RVmnAjsPug,7969
+kalbio-0.2.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+kalbio-0.2.0.dist-info/RECORD,,

kalbio-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any