superbio 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
superbio/__init__.py ADDED
@@ -0,0 +1 @@
1
+ from .client import Client
superbio/auth.py ADDED
@@ -0,0 +1,33 @@
1
+ import requests
2
+
3
+
4
+ class AuthManager:
5
+ def __init__(self, base_url, email, password, token=None, user_id=None):
6
+ self.base_url = base_url
7
+ self.email = email
8
+ self.password = password
9
+ self.token = token
10
+ self.user_id = user_id
11
+ self.login()
12
+
13
+ def login(self):
14
+ try:
15
+ response = requests.post(
16
+ f"{self.base_url}/login", json={"email": self.email, "password": self.password}
17
+ )
18
+ response.raise_for_status()
19
+ response_json = response.json()
20
+
21
+ # Check for required fields in response
22
+ if not response_json.get("access_token") or not response_json.get("id"):
23
+ raise PermissionError(
24
+ "Invalid response from server. Missing required authentication fields.")
25
+
26
+ self.token = response_json["access_token"]
27
+ self.user_id = response_json["id"]
28
+
29
+ except requests.exceptions.HTTPError as e:
30
+ if hasattr(e, 'response') and e.response is not None and e.response.status_code == 401:
31
+ raise PermissionError(
32
+ "Authentication failed. Please check your credentials or refresh your token.") from e
33
+ raise # Re-raise other HTTP errors
superbio/client.py ADDED
@@ -0,0 +1,490 @@
1
+ import json
2
+ import os
3
+ from typing import Literal
4
+ import requests
5
+ from requests_toolbelt import MultipartEncoder, MultipartEncoderMonitor
6
+
7
+ from superbio.auth import AuthManager
8
+ from superbio.utils import data_validation, job_post_validation
9
+
10
+ """
11
+ Superbio API Client
12
+
13
+ This module provides a client for interacting with the Superbio API. It handles authentication,
14
+ job submission, file management, and result retrieval.
15
+
16
+ Example:
17
+ >>> from superbio import Client
18
+ >>> client = Client("your@email.com", "your_password")
19
+ >>> # [TODO: Add a simple example of submitting a job]
20
+ """
21
+
22
+ PROBLEM_WITH_JOB = "There was a problem finding your job, check the job_id is correct"
23
+ RUNNING_MODE = {"cpu": 1, "gpu": 2}
24
+
25
+
26
+ def create_callback(encoder):
27
+ def callback(monitor):
28
+ progress = (monitor.bytes_read / encoder.len) * 100
29
+ print(f"Upload Progress: {progress:.2f}%")
30
+
31
+ return callback
32
+
33
+
34
+ class Client:
35
+ """
36
+ Main client class for interacting with the Superbio API.
37
+
38
+ The client provides programmatic access to the Superbio platform, allowing users to:
39
+ - List and browse available apps
40
+ - Get app configurations and parameters
41
+ - Submit and manage computational jobs
42
+ - Track job status and retrieve results
43
+ - Monitor balances
44
+
45
+ Note:
46
+ You must first create an account at https://app.superbio.ai before using this client.
47
+ Your email and password from the platform will be used to authenticate API requests.
48
+
49
+ Attributes:
50
+ auth (AuthManager): Handles authentication with the API
51
+ BASE_URL (str): The base URL for the API
52
+ """
53
+
54
+ BASE_URL = "https://api.superbio.ai"
55
+ # BASE_URL = "http://127.0.0.1:8000"
56
+
57
+ # TODO:
58
+ # add files to datahub function and handle add to datahub in post job
59
+ # download results to remote storage function
60
+ # cache for app config
61
+ # helper function to return a job_config template
62
+ # get open data list
63
+
64
+ def __init__(self, email: str, password: str, token: str = None):
65
+ """
66
+ Initialize the Superbio client.
67
+
68
+ Args:
69
+ email (str): User's email address
70
+ password (str): User's password
71
+ token (str, optional): Existing authentication token
72
+ """
73
+ self.auth = AuthManager(self.BASE_URL, email, password, token)
74
+
75
+ def _request(self, method, endpoint, data=None, _json=None, params=None, files=None, headers=None, stream=False,
76
+ return_json=True):
77
+ url = f"{self.BASE_URL}/{endpoint}"
78
+ headers = headers or {}
79
+ headers.update({"Authorization": f"Bearer {self.auth.token}"})
80
+ response = requests.request(method, url, data=data, json=_json, params=params, files=files, headers=headers,
81
+ stream=stream)
82
+
83
+ response.raise_for_status()
84
+
85
+ if return_json:
86
+ return response.json()
87
+ else:
88
+ return response
89
+
90
+ def post_job(self, app_id: str, running_mode: Literal["gpu", "cpu"], config=None, local_files=None,
91
+ remote_file_source_data=None, datahub_file_data=None, validate=True):
92
+ """
93
+ Submit a new job to the Superbio platform.
94
+
95
+ Args:
96
+ app_id (str): ID of the application to run
97
+ running_mode (str): Either "gpu" or "cpu"
98
+ config (dict, optional): Job configuration parameters
99
+ local_files (dict, optional): Mapping of file keys to local file paths
100
+ remote_file_source_data (dict, optional): Remote file source configuration
101
+ Example for S3:
102
+ {
103
+ "file_key": [{
104
+ "protocol": "s3",
105
+ "credentials": {
106
+ "aws_access_key_id": "YOUR_ACCESS_KEY",
107
+ "aws_secret_access_key": "YOUR_SECRET_KEY"
108
+ },
109
+ "path": "bucket/path/to/file.csv"
110
+ }]
111
+ }
112
+ datahub_file_data (dict, optional): Mapping of file keys to lists of datahub file paths
113
+ Example:
114
+ {
115
+ "file_key": ["path/to/datahub/file.csv"]
116
+ }
117
+ validate (bool, optional): Whether to validate inputs before submission
118
+
119
+ Returns:
120
+ dict: Response from the API containing job details
121
+ Example:
122
+ {
123
+ "job_id": "job_123abc..."
124
+ }
125
+
126
+ Raises:
127
+ Exception: If validation fails or job submission fails
128
+ """
129
+ # TODO: credits validation
130
+ # TODO: handle open data
131
+ # TODO: make remote and datahub data easier
132
+ if config is None:
133
+ config = {}
134
+
135
+ if local_files is None:
136
+ local_files = {}
137
+
138
+ formatted_datahub_file_data = {}
139
+ if datahub_file_data is not None:
140
+ for file_key in datahub_file_data:
141
+ formatted_datahub_file_data[file_key] = []
142
+ for path in datahub_file_data[file_key]:
143
+ formatted_datahub_file_data[file_key].append({
144
+ "protocol": "s3",
145
+ "path": path
146
+ })
147
+
148
+ if validate:
149
+ app_config = self.get_app_parameters(app_id)
150
+ job_post_validation(app_config, config, local_files.keys() if local_files else [], remote_file_source_data, formatted_datahub_file_data,
151
+ running_mode)
152
+
153
+ running_id = RUNNING_MODE.get(running_mode)
154
+ config = json.dumps(config)
155
+ remote_file_source_data = json.dumps(remote_file_source_data)
156
+ formatted_datahub_file_data = json.dumps(formatted_datahub_file_data)
157
+ payload = {
158
+ "app_id": app_id,
159
+ "partial_job_submit": True,
160
+ "config": config,
161
+ "running_mode": running_id
162
+ }
163
+ response = self._request("POST", "api/jobs", data=payload)
164
+
165
+ partial_job_id = response["job_id"]
166
+
167
+ # TODO: add file duplicated handling after adding 'add to data hub'
168
+ headers = {
169
+ "X-File-Name-To-File-Key-Map": json.dumps({}),
170
+ "X-Add-To-Data-Hub-Paths": json.dumps({}),
171
+ "Authorization": f"Bearer {self.auth.token}",
172
+ "Content-Type": "multipart/form-data", # This will be replaced dynamically
173
+ }
174
+ fields = {
175
+ "partial_job_id": partial_job_id,
176
+ "remote_file_source_data": remote_file_source_data,
177
+ "datahub_file_data": formatted_datahub_file_data
178
+ }
179
+ open_files = {file_key: (os.path.basename(file_path), open(file_path, "rb"), "application/octet-stream") for file_key, file_path in
180
+ local_files.items()}
181
+ fields.update(open_files)
182
+ encoder = MultipartEncoder(fields)
183
+
184
+ monitor = MultipartEncoderMonitor(encoder, create_callback(encoder))
185
+ headers["Content-Type"] = monitor.content_type # Set correct content type
186
+
187
+ res = self._request("PATCH", f"api/jobs/{partial_job_id}", headers=headers, data=monitor, stream=True)
188
+
189
+ for file_obj in open_files.values():
190
+ file_obj[1].close()
191
+
192
+ return res
193
+
194
+ def get_jobs(self, page: int = 1, hits_per_page: int = 100, search_string: str = None, date_from: str = None,
195
+ date_to: str = None, status: Literal["running", "failed", "completed"] = None,
196
+ added_by_me: bool = True):
197
+ """
198
+ Retrieve a list of jobs.
199
+
200
+ Args:
201
+ page (int): Page number for pagination
202
+ hits_per_page (int): Number of results per page
203
+ search_string (str, optional): Filter jobs by search term
204
+ date_from (str, optional): Start date in format dd/mm/yyyy
205
+ date_to (str, optional): End date in format dd/mm/yyyy
206
+ status (str, optional): Filter by job status
207
+ added_by_me (bool): Only show jobs created by current user
208
+
209
+ Returns:
210
+ dict: List of jobs and metadata
211
+ Example:
212
+ {
213
+ "hits": [{
214
+ "id": "job_123abc...",
215
+ "title": "DGE-20221028-084933-cpu",
216
+ "status": "Completed",
217
+ "app_name": "Differential Gene Expression",
218
+ "created_at": "2022-10-28T08:49:33",
219
+ "updated_at": "2022-10-28T08:52:45",
220
+ "running_mode": "cpu",
221
+ "config": {...}
222
+ ...
223
+ }],
224
+ "hits_per_page": 100,
225
+ "total": 1234,
226
+ "page": 1
227
+ }
228
+ """
229
+ if status not in ["running", "failed", "completed", None]:
230
+ raise ValueError('Invalid status. Choose from: "running", "failed", "completed"')
231
+
232
+ if status:
233
+ status = status.capitalize()
234
+
235
+ data_validation([date_to, date_from])
236
+ params = {k: v for k, v in locals().items() if k != "self" and v is not None}
237
+ return self._request("GET", "api/jobs", params=params)
238
+
239
+ def _download_file(self, response, path_to_download_to):
240
+ with open(path_to_download_to, "wb") as file:
241
+ for chunk in response.iter_content(chunk_size=8192):
242
+ file.write(chunk)
243
+
244
+ def list_job_result_files(self, job_id: str):
245
+ """
246
+ Get list of result files for a completed job.
247
+
248
+ Args:
249
+ job_id (str): ID of the job
250
+
251
+ Returns:
252
+ dict: Structure containing file information
253
+ Example:
254
+ {
255
+ "download": [{"file": "results.zip", "title": "Output results"}],
256
+ "tables": [[{"file": "table.csv", "title": "Results table"}, ...], ...],
257
+ "pdbs": [[{"file": "protein.pdb", "title": "Results protein"}, ...], ...],
258
+ "images": [[{"file": "image.png", "title": "Results Images"}, ...], ...],
259
+ }
260
+
261
+ Raises:
262
+ Exception: If job not found, not completed or other error occurs
263
+ """
264
+ try:
265
+ return self._request("GET", f"api/jobs/{job_id}/result_files")
266
+ except Exception:
267
+ raise Exception(PROBLEM_WITH_JOB)
268
+
269
+ def download_job_result_file(self, job_id: str, result_file_path: str, path_to_download_to: str,
270
+ result_type: str = None):
271
+ """
272
+ Download a specific result file from a job.
273
+
274
+ Args:
275
+ job_id (str): ID of the job
276
+ result_file_path (str): Path to the file within job results
277
+ path_to_download_to (str): Local path to save file to
278
+ result_type (str, optional): This is for internal use only
279
+ Raises:
280
+ Exception: If download fails
281
+ """
282
+ url = f"api/jobs/{job_id}/result_files"
283
+ download_path = os.path.join(f"{path_to_download_to.strip('/')}/{result_file_path.lstrip('/')}")
284
+ download_dir = os.path.dirname(download_path)
285
+ if not os.path.exists(download_dir):
286
+ os.makedirs(download_dir)
287
+ params = {"result_type": result_type, "file_name": result_file_path, "download_file": True}
288
+ try:
289
+ response = self._request("GET", url, params=params, stream=True, return_json=False)
290
+ self._download_file(response, download_path)
291
+ except Exception:
292
+ raise Exception(
293
+ "There was a problem downloading this result file, check the job_id and result_file_path are correct and you have write permissions for path_to_download_to")
294
+
295
+ def download_all_job_results(self, job_id: str, path_to_download_to: str, download_compressed: bool = True):
296
+ """
297
+ Download all results for a job.
298
+
299
+ Args:
300
+ job_id (str): ID of the job
301
+ path_to_download_to (str): Local path to save files to
302
+ download_compressed (bool): Whether to download as compressed archive
303
+
304
+ Raises:
305
+ Exception: If job not found or download fails
306
+ """
307
+ result_files = self.list_job_result_files(job_id)
308
+ if download_compressed:
309
+ download_section = result_files.get("download")[0]
310
+ if download_section:
311
+ self.download_job_result_file(job_id, download_section['file'], path_to_download_to)
312
+ else:
313
+ # Exception for job id not valid
314
+ raise Exception(
315
+ f"No compressed version is available. Try with download_compressed = False or go to your jobs page on the Superbio.ai platform")
316
+ else:
317
+ if result_files.get("download"):
318
+ del result_files["download"]
319
+ for result_file_key in result_files:
320
+ for result_section in result_files[result_file_key]:
321
+ for result in result_section:
322
+ self.download_job_result_file(job_id, result['file'], path_to_download_to)
323
+
324
+ def delete_job(self, job_id: str):
325
+ """
326
+ Delete a job.
327
+
328
+ Args:
329
+ job_id (str): ID of the job to delete
330
+
331
+ Returns:
332
+ dict: Response indicating success/failure
333
+ Example:
334
+ {
335
+ "message": "Deleted job"
336
+
337
+ Raises:
338
+ Exception: If job not found or deletion fails
339
+ """
340
+ try:
341
+ return self._request("DELETE", f"api/jobs/{job_id}")
342
+ except Exception:
343
+ raise Exception(PROBLEM_WITH_JOB)
344
+
345
+ def get_balances(self):
346
+ """
347
+ Get current credit balances.
348
+
349
+ Returns:
350
+ dict: Credit balance information
351
+ Example:
352
+ {
353
+ "balances": {
354
+ "available_credits": 6000,
355
+ "credits": 6000,
356
+ "runs_left": 400,
357
+ "total_runs": 400,
358
+ "runtime_left": 72000.0,
359
+ "total_runtime": 72000,
360
+ "runs_reset_time": "Feb 28 2025, 23:08:05",
361
+ "runtime_reset_time": "Feb 28 2025, 23:08:05",
362
+ "tier": "free_organisation",
363
+ "is_last_billing_cycle": False,
364
+ "comments_left": 0
365
+ }
366
+ }
367
+ """
368
+ return self._request("GET", f"api/users/{self.auth.user_id}/balances")
369
+
370
+ def get_app_list(self, hits_per_page=None, page=None, search_string=None):
371
+ """
372
+ Get list of available applications.
373
+
374
+ Args:
375
+ hits_per_page (int, optional): Number of results per page
376
+ page (int, optional): Page number to return
377
+ search_string (str, optional): Search by string
378
+
379
+ Returns:
380
+ dict: List of applications and metadata
381
+ Example:
382
+ {
383
+ "hits": [{
384
+ "id": "job_123abc...",
385
+ "name": "App Name",
386
+ "description": "App description",
387
+ "author": "Author name",
388
+ "creation_time": "Jul 19 2023, 15:44:59",
389
+ "dev_version": 1,
390
+ "example_job_id": "64bf9448823bc93b64c10b95",
391
+ "featured": true,
392
+ "group": null,
393
+ "group_tags": {
394
+ "category": [{
395
+ "description": "Category description",
396
+ "group": "category",
397
+ "id": "category_id",
398
+ "name": "Category Name"
399
+ }],
400
+ "data_extension": [...],
401
+ "focus": [...],
402
+ "method": [...],
403
+ "organization": [...],
404
+ "subject": []
405
+ },
406
+ "has_liked": true,
407
+ "is_paid_app": false,
408
+ "last_update_time": null,
409
+ "like_count": 31,
410
+ "long_description": "...",
411
+ "mean_job_execution_time": {
412
+ "hardware": "gpu",
413
+ "mean_job_execution_time_str": "~2m"
414
+ },
415
+ "model_actions": null,
416
+ "run_count": 369,
417
+ "save_model": false,
418
+ "status": "released",
419
+ "uid": 270
420
+ }, ...],
421
+ "hits_per_page": 100,
422
+ "total": 1234,
423
+ "page": 1
424
+ }
425
+ """
426
+ params = {k: v for k, v in locals().items() if k != "self" and v is not None}
427
+ return self._request("GET", f"api/appstore_list", params=params)
428
+
429
+ def get_app_parameters(self, app_id: str):
430
+ """
431
+ Get configuration parameters for an application.
432
+
433
+ Args:
434
+ app_id (str): ID of the application
435
+
436
+ Returns:
437
+ dict: Application configuration
438
+ Example:
439
+ {
440
+ "parameter_settings": {
441
+ "parameters": [{
442
+ "field_name": "parameter_name",
443
+ "title": "Parameter Title",
444
+ "tooltip": "Parameter description",
445
+ "input_type": "dropdown|slider|checkbox|user_input",
446
+ "type": "str|integer|text",
447
+ "default_value": "default",
448
+ "options": [{"label": "Option 1", "value": "opt1"}, ...],
449
+ "min_value": 0,
450
+ "max_value": 100,
451
+ "increment": 1,
452
+ "hidden": false,
453
+ "disabled": false,
454
+ "optional": true
455
+ }, ...],
456
+ "disabled_fields": ["field1", "field2"],
457
+ "inputs_require_files": ["field3"]
458
+ },
459
+ "file_settings": [{
460
+ "name": "file_input_name",
461
+ "title": "File Input Title",
462
+ "allowed_extensions": ["h5ad"],
463
+ "upload_types": ["local", "remote"],
464
+ "supports_preview": true,
465
+ "disabled": false,
466
+ "data_structure_description": "File format description",
467
+ "demo_data_details": {
468
+ "description": "Demo data description",
469
+ "file_name": "demo.h5ad",
470
+ "file_path": "path/to/demo.h5ad",
471
+ "preview_file_name": "preview.h5ad",
472
+ "file_sources": [{
473
+ "title": "Source Title",
474
+ "url": "https://source.url"
475
+ }]
476
+ }
477
+ }],
478
+ "running_modes": ["cpu", "gpu"]
479
+ }
480
+
481
+ Raises:
482
+ Exception: If app not found
483
+ """
484
+ try:
485
+ response = self._request("GET", f"api/apps/{app_id}")
486
+ config = response["config"]
487
+ config["running_modes"] = response["running_modes"]
488
+ return config
489
+ except Exception:
490
+ raise Exception("There was a problem finding this app, check app_id is correct")
superbio/endpoints.py ADDED
File without changes
superbio/exceptions.py ADDED
File without changes
superbio/utils.py ADDED
@@ -0,0 +1,63 @@
1
+ from datetime import datetime
2
+ from typing import List
3
+
4
+
5
+ def data_validation(date_strs: List[str]):
6
+ try:
7
+ for date_str in date_strs:
8
+ if date_str:
9
+ datetime.strptime(date_str, "%d/%m/%Y")
10
+ return True
11
+ except ValueError:
12
+ raise ValueError("Invalid date format. Use dd/mm/yyyy.")
13
+
14
+
15
+ def get_missing_values(required_items, items):
16
+ return [key for key in required_items if key not in items]
17
+
18
+
19
+ def job_post_validation(app_config, job_config, local_files_keys, remote_file_source_data_keys, datahub_file_data_keys,
20
+ running_mode):
21
+ # TODO: add numeric input range validation
22
+ # TODO: add file extension validation
23
+ # TODO: remote file data format and datahub file validation format
24
+
25
+ job_files = []
26
+ if local_files_keys:
27
+ job_files.extend(local_files_keys)
28
+ if remote_file_source_data_keys:
29
+ job_files.extend(remote_file_source_data_keys)
30
+ if datahub_file_data_keys:
31
+ job_files.extend(datahub_file_data_keys)
32
+
33
+ app_config_running_modes = app_config["running_modes"]
34
+ print(f"app_config_running_modes {app_config_running_modes}")
35
+ app_config_running_mode_ids = {mode["mode_id"] for mode in app_config_running_modes}
36
+ if running_mode not in ["cpu", "gpu"]:
37
+ raise Exception("Invalid running mode, choose 'gpu' or 'cpu' depending on what running modes the app supports")
38
+ elif running_mode == "gpu" and 2 not in app_config_running_mode_ids:
39
+ raise Exception("")
40
+ elif running_mode == "cpu" and not app_config_running_mode_ids.intersection({1, 3, 4}):
41
+ raise Exception("")
42
+
43
+ required_params = []
44
+ for param_config in app_config["parameter_settings"]["parameters"]:
45
+ if param_config.get("optional"):
46
+ continue
47
+ required_params.append(param_config["field_name"])
48
+
49
+ file_settings = app_config["file_settings"]
50
+ required_files = [file["name"] for file in file_settings if
51
+ file.get("optional") is None or file.get("optional") is False]
52
+
53
+ missing_params = get_missing_values(required_params, job_config.keys())
54
+ missing_files = get_missing_values(required_files, job_files)
55
+
56
+ print("required_params", required_params)
57
+ print("job_config.keys()", job_config.keys())
58
+
59
+ if len(missing_params):
60
+ raise Exception(f"Missing the following parameter values: {missing_params}")
61
+
62
+ if len(missing_files):
63
+ raise Exception(f"Missing the following files: {missing_files}")
@@ -0,0 +1,179 @@
1
+ Metadata-Version: 2.1
2
+ Name: superbio
3
+ Version: 0.1.0
4
+ Summary: Python client for the Superbio API
5
+ Home-page: https://github.com/Superbio-ai/superbioAPI
6
+ Author: Superbio
7
+ Author-email: dmason@superbio.ai
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Science/Research
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.7
14
+ Classifier: Programming Language :: Python :: 3.8
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Requires-Python: >=3.7
18
+ Description-Content-Type: text/markdown
19
+ Requires-Dist: requests (>=2.25.0)
20
+ Requires-Dist: requests-toolbelt (>=0.9.1)
21
+ Provides-Extra: dev
22
+ Requires-Dist: pytest (>=7.0.0) ; extra == 'dev'
23
+ Requires-Dist: pytest-mock (>=3.10.0) ; extra == 'dev'
24
+ Requires-Dist: requests-mock (>=1.10.0) ; extra == 'dev'
25
+ Requires-Dist: coverage (>=7.0.0) ; extra == 'dev'
26
+
27
+ # Superbio Python Client
28
+
29
+ Official Python client for the [Superbio](https://app.superbio.ai) platform API. Access bioinformatics tools and AI models programmatically.
30
+
31
+ ## Installation
32
+ ```bash
33
+ pip install superbio
34
+ ```
35
+
36
+ ## Quick Start
37
+ ```python
38
+ from superbio import Client
39
+
40
+ # Initialize client
41
+ client = Client("your@email.com", "your_password")
42
+
43
+ # List available apps
44
+ apps = client.get_app_list()
45
+
46
+ # Get app parameters
47
+ app_params = client.get_app_parameters("app_id")
48
+
49
+ # Submit a job with local files
50
+ job = client.post_job(
51
+ app_id="app_id",
52
+ running_mode="cpu",
53
+ config={"param": "value"},
54
+ local_files={"file_key": "path/to/file"}
55
+ )
56
+ ```
57
+ ## Submit a job with S3 files
58
+ ```python
59
+ job = client.post_job(
60
+ app_id="app_id",
61
+ running_mode="cpu",
62
+ config={"param": "value"},
63
+ remote_file_source_data={
64
+ "file_key": [{
65
+ "protocol": "s3",
66
+ "credentials": {
67
+ "aws_access_key_id": "YOUR_ACCESS_KEY",
68
+ "aws_secret_access_key": "YOUR_SECRET_KEY"
69
+ },
70
+ "path": "bucket/path/to/file.csv"
71
+ }]
72
+ }
73
+ )
74
+ ```
75
+ Check job status
76
+ ```python
77
+ status = client.get_job_status("job_id")
78
+ ```
79
+ Download results
80
+ ```python
81
+ client.download_job_results("job_id", "output_directory")
82
+ ```
83
+ ## Features
84
+
85
+ - Browse and search available bioinformatics applications
86
+ - Get detailed app configurations and parameters
87
+ - Submit computational jobs with:
88
+ - Local files
89
+ - Remote files (S3)
90
+ - Files from Superbio DataHub
91
+ - Monitor job status and progress
92
+ - Download and manage results
93
+ - Track credit balances and usage
94
+
95
+ ## Authentication
96
+
97
+ You must first create an account at [app.superbio.ai](https://app.superbio.ai). Your email and password from the platform will be used to authenticate API requests.
98
+
99
+ <!-- ## Documentation
100
+
101
+ For complete API documentation and examples, visit [docs.superbio.ai](https://docs.superbio.ai). -->
102
+
103
+ ## Examples
104
+
105
+ ### Working with Apps
106
+
107
+ ```python
108
+ # Get list of all apps
109
+ apps = client.get_app_list()
110
+
111
+ # List apps with pagination and search
112
+ apps = client.get_app_list(
113
+ hits_per_page=10, # (optional) Number of results per page
114
+ page=1, # (optional) Page number
115
+ search_string="genomics" # (optional)Search by keyword
116
+ )
117
+
118
+ # Get app details and parameters
119
+ app_config = client.get_app_parameters("app_id")
120
+ ```
121
+
122
+ ### Job Management
123
+ ```python
124
+ # List jobs with filters
125
+ jobs = client.get_jobs(
126
+ hits_per_page=100, # (optional) Number of jobs per page
127
+ page=1, # (optional) Page number
128
+ status="running", # (optional) Filter by status: "running", "completed", "failed", etc.
129
+ date_from="01/01/2024", # (optional) Filter by start date (dd/mm/yyyy)
130
+ date_to="31/01/2024", # Filter by end date (dd/mm/yyyy)
131
+ search_string="analysis" # Search job titles
132
+ )
133
+
134
+ # Download specific result files
135
+ client.download_job_result_file(
136
+ job_id="job_id",
137
+ file_path="path/to/result.csv", # Path of file in job results
138
+ output_dir="output_dir", # Local directory to save file
139
+ )
140
+
141
+ # Download all results
142
+ client.download_all_job_results(
143
+ job_id="job_id",
144
+ output_dir="output_dir", # Local directory to save files
145
+ )
146
+
147
+ # Delete a job
148
+ client.delete_job("job_id")
149
+ ```
150
+
151
+ ### Credit Management
152
+ ```python
153
+ # Get credit balances and usage info
154
+ balances = client.get_balances()
155
+ # Returns:
156
+ # {
157
+ # "balances": {
158
+ # "available_credits": 6000,
159
+ # "credits": 6000,
160
+ # "runs_left": 400,
161
+ # "total_runs": 400,
162
+ # "runtime_left": 72000.0,
163
+ # "total_runtime": 72000,
164
+ # "runs_reset_time": "Feb 28 2025, 23:08:05",
165
+ # "runtime_reset_time": "Feb 28 2025, 23:08:05",
166
+ # "tier": "free_organisation"
167
+ # }
168
+ # }
169
+ ```
170
+
171
+ ## Support
172
+
173
+ For support, contact dmason@superbio.ai.
174
+ <!-- For support, contact dmason@superbio.ai or visit our [documentation](https://docs.superbio.ai). -->
175
+
176
+
177
+ <!-- ## License
178
+
179
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -->
@@ -0,0 +1,15 @@
1
+ superbio/__init__.py,sha256=8PUi-Vi1vK1TH9CYOwhuhRy0K8DdJqBvdXWVruz_9u0,28
2
+ superbio/auth.py,sha256=TFL3faPntwIQ3F8QQveeuXwJfwRV44fxRygCWMSeCsU,1340
3
+ superbio/client.py,sha256=zGcfVSqrMmO0t4Yog6gdSHoUqjVU5wkhbxQuq0Iuy2o,20165
4
+ superbio/endpoints.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
+ superbio/exceptions.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ superbio/utils.py,sha256=9cC3GGSI4K7j8tx9jNLsYsIVevb5HezRIoi766kLbJo,2559
7
+ tests/__init__.py,sha256=Gu9QnGHXYl7mCgSVxBZs9mn4W-CBBtBpWj1c2pRPIgY,42
8
+ tests/conftest.py,sha256=LoQxIIpMPk5jtqlTBlZCDxDluE0MKNEGBsZnD0ItlX0,1527
9
+ tests/test_auth.py,sha256=PkA8txzwJCzkRT2TlpuH8lFmcB6cn0kRmxEBPtqc-ks,4414
10
+ tests/test_client.py,sha256=lmFMvIVFGRxWBzdb8fVMpULHvzYojGdlV6VAVytGpoA,7096
11
+ tests/test_utils.py,sha256=OYObgacLHBzN4QInhIbWjLEIu9j3BWXic_3RvvJFJdk,3561
12
+ superbio-0.1.0.dist-info/METADATA,sha256=QrfXGxTG57OoyWKbAf20rSycQPHiCMebyFWRh0zRavY,5211
13
+ superbio-0.1.0.dist-info/WHEEL,sha256=2wepM1nk4DS4eFpYrW1TTqPcoGNfHhhO_i5m4cOimbo,92
14
+ superbio-0.1.0.dist-info/top_level.txt,sha256=cB5T8J4MFUiEndHpiMgO7ohnr4gS-h6CQWBVulEOMKE,15
15
+ superbio-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: bdist_wheel (0.38.4)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ superbio
2
+ tests
tests/__init__.py ADDED
@@ -0,0 +1 @@
1
+ # Empty init file to make tests a package
tests/conftest.py ADDED
@@ -0,0 +1,49 @@
1
+ import pytest
2
+ from unittest.mock import patch
3
+ from superbio.client import Client
4
+
5
+ @pytest.fixture(autouse=True)
6
+ def no_requests(monkeypatch):
7
+ """Prevent any real HTTP requests from being made during tests."""
8
+ with patch('requests.request'), patch('requests.post'):
9
+ yield
10
+
11
+ @pytest.fixture
12
+ def mock_credentials():
13
+ return {
14
+ 'email': 'test@example.com',
15
+ 'password': 'test_password',
16
+ 'token': 'test_token',
17
+ 'user_id': 'test_user_id'
18
+ }
19
+
20
+ @pytest.fixture
21
+ def mock_client(mock_credentials, no_requests):
22
+ with patch('superbio.client.AuthManager') as mock_auth:
23
+ mock_auth.return_value.token = mock_credentials['token']
24
+ mock_auth.return_value.user_id = mock_credentials['user_id']
25
+ client = Client(
26
+ email=mock_credentials['email'],
27
+ password=mock_credentials['password']
28
+ )
29
+ return client
30
+
31
+ @pytest.fixture
32
+ def sample_app_config():
33
+ return {
34
+ "parameter_settings": {
35
+ "parameters": [
36
+ {"field_name": "analysis", "optional": False},
37
+ {"field_name": "index_column", "optional": True}
38
+ ]
39
+ },
40
+ "file_settings": [
41
+ {"name": "control", "optional": False},
42
+ {"name": "experiment", "optional": False},
43
+ {"name": "optional_file", "optional": True}
44
+ ],
45
+ "running_modes": [
46
+ {"mode_id": 1}, # CPU
47
+ {"mode_id": 2} # GPU
48
+ ]
49
+ }
tests/test_auth.py ADDED
@@ -0,0 +1,123 @@
1
+ import pytest
2
+ import requests
3
+ from unittest.mock import patch, MagicMock
4
+ from superbio.auth import AuthManager
5
+
6
+
7
+ @pytest.fixture
8
+ def mock_auth_response():
9
+ mock_response = MagicMock()
10
+ mock_response.json.return_value = {
11
+ "access_token": "test_token",
12
+ "id": "test_user_id"
13
+ }
14
+ return mock_response
15
+
16
+
17
+ def test_auth_manager_initialization(mock_credentials):
18
+ with patch('requests.post') as mock_post:
19
+ mock_post.return_value.json.return_value = {
20
+ "access_token": mock_credentials['token'],
21
+ "id": mock_credentials['user_id']
22
+ }
23
+
24
+ auth = AuthManager(
25
+ "http://test.com",
26
+ mock_credentials['email'],
27
+ mock_credentials['password']
28
+ )
29
+
30
+ assert auth.token == mock_credentials['token']
31
+ assert auth.user_id == mock_credentials['user_id']
32
+
33
+
34
+ def test_auth_manager_failed_login():
35
+ """Test handling of failed authentication"""
36
+ with patch('requests.post') as mock_post:
37
+ # Create a mock response with 401 status code
38
+ mock_response = MagicMock()
39
+ mock_response.status_code = 401
40
+ mock_error = requests.exceptions.HTTPError(response=mock_response)
41
+ mock_post.side_effect = mock_error
42
+
43
+ with pytest.raises(PermissionError, match="Authentication failed"):
44
+ AuthManager(
45
+ "http://test.com",
46
+ "invalid@email.com",
47
+ "wrong_password"
48
+ )
49
+
50
+
51
+ def test_auth_manager_other_http_error():
52
+ """Test handling of non-auth HTTP errors"""
53
+ with patch('requests.post') as mock_post:
54
+ # Create a mock response with 500 status code
55
+ mock_response = MagicMock()
56
+ mock_response.status_code = 500
57
+ mock_error = requests.exceptions.HTTPError(response=mock_response)
58
+ mock_post.side_effect = mock_error
59
+
60
+ with pytest.raises(requests.exceptions.HTTPError):
61
+ AuthManager(
62
+ "http://test.com",
63
+ "test@example.com",
64
+ "password"
65
+ )
66
+
67
+
68
+ def test_auth_manager_with_token(mock_credentials):
69
+ """Test initialization with an existing token"""
70
+ with patch('requests.post') as mock_post:
71
+ # Setup mock response
72
+ mock_post.return_value.json.return_value = {
73
+ "access_token": mock_credentials['token'],
74
+ "id": mock_credentials['user_id']
75
+ }
76
+
77
+ auth = AuthManager(
78
+ "http://test.com",
79
+ mock_credentials['email'],
80
+ mock_credentials['password'],
81
+ token=mock_credentials['token'],
82
+ user_id=mock_credentials['user_id']
83
+ )
84
+
85
+ # Should still try to login to verify token
86
+ mock_post.assert_called_once()
87
+ assert auth.token == mock_credentials['token']
88
+
89
+
90
+ def test_auth_manager_invalid_response():
91
+ """Test handling of invalid response format"""
92
+ with patch('requests.post') as mock_post:
93
+ # Mock a successful response but with missing fields
94
+ mock_response = MagicMock()
95
+ mock_response.status_code = 200 # Successful response
96
+ mock_response.raise_for_status.return_value = None # Won't raise an error
97
+ mock_response.json.return_value = {} # Missing required fields
98
+ mock_post.return_value = mock_response
99
+
100
+ with pytest.raises(PermissionError, match="Invalid response from server"):
101
+ AuthManager(
102
+ "http://test.com",
103
+ "test@example.com",
104
+ "password"
105
+ )
106
+
107
+
108
+ def test_auth_manager_partial_response():
109
+ """Test handling of response with only some required fields"""
110
+ with patch('requests.post') as mock_post:
111
+ # Mock a response with only one of the required fields
112
+ mock_response = MagicMock()
113
+ mock_response.status_code = 200 # Successful response
114
+ mock_response.raise_for_status.return_value = None # Won't raise an error
115
+ mock_response.json.return_value = {"access_token": "token"} # Missing id
116
+ mock_post.return_value = mock_response
117
+
118
+ with pytest.raises(PermissionError, match="Invalid response from server"):
119
+ AuthManager(
120
+ "http://test.com",
121
+ "test@example.com",
122
+ "password"
123
+ )
tests/test_client.py ADDED
@@ -0,0 +1,227 @@
1
+ import pytest
2
+ from unittest.mock import patch, MagicMock
3
+ from superbio.client import Client, RUNNING_MODE
4
+
5
+
6
+ def test_client_initialization(mock_credentials):
7
+ """Test that Client properly initializes AuthManager"""
8
+ with patch('superbio.client.AuthManager') as mock_auth:
9
+ mock_auth.return_value.token = mock_credentials['token']
10
+ mock_auth.return_value.user_id = mock_credentials['user_id']
11
+
12
+ client = Client(
13
+ email=mock_credentials['email'],
14
+ password=mock_credentials['password']
15
+ )
16
+
17
+ # Verify AuthManager was created with correct parameters
18
+ mock_auth.assert_called_once_with(
19
+ Client.BASE_URL,
20
+ mock_credentials['email'],
21
+ mock_credentials['password'],
22
+ None
23
+ )
24
+
25
+ # Verify client has the mock auth instance
26
+ assert client.auth is mock_auth.return_value
27
+
28
+
29
+ def test_get_jobs(mock_client):
30
+ with patch.object(mock_client, '_request') as mock_request:
31
+ mock_request.return_value = {"hits": []}
32
+
33
+ response = mock_client.get_jobs(
34
+ page=1,
35
+ hits_per_page=100,
36
+ status="completed"
37
+ )
38
+
39
+ mock_request.assert_called_once()
40
+ assert "hits" in response
41
+
42
+
43
+ def test_get_jobs_invalid_status(mock_client):
44
+ with pytest.raises(ValueError, match="Invalid status"):
45
+ mock_client.get_jobs(status="invalid")
46
+
47
+
48
+ def test_get_app_parameters(mock_client):
49
+ app_id = "test_app_id"
50
+ mock_response = {
51
+ "config": {"test": "config"},
52
+ "running_modes": [{"mode_id": 1}]
53
+ }
54
+
55
+ with patch.object(mock_client, '_request') as mock_request:
56
+ mock_request.return_value = mock_response
57
+
58
+ response = mock_client.get_app_parameters(app_id)
59
+
60
+ mock_request.assert_called_once_with(
61
+ "GET",
62
+ f"api/apps/{app_id}"
63
+ )
64
+ assert "test" in response
65
+ assert "running_modes" in response
66
+
67
+
68
+ def test_post_job(mock_client, sample_app_config):
69
+ with patch.object(mock_client, '_request') as mock_request, \
70
+ patch.object(mock_client, 'get_app_parameters') as mock_get_params:
71
+ mock_get_params.return_value = sample_app_config
72
+ mock_request.return_value = {"job_id": "test_job_id"}
73
+
74
+ response = mock_client.post_job(
75
+ app_id="test_app_id",
76
+ running_mode="cpu",
77
+ config={"analysis": "test"},
78
+ local_files={"control": "test_files/deg_background_preprocessed.csv",
79
+ "experiment": "test_files/deg_experimental_preprocessed.csv"}
80
+ )
81
+
82
+ assert response["job_id"] == "test_job_id"
83
+
84
+
85
+ def test_download_job_result_file(mock_client, tmp_path):
86
+ with patch.object(mock_client, '_request') as mock_request:
87
+ mock_response = MagicMock()
88
+ mock_response.iter_content.return_value = [b"test content"]
89
+ mock_request.return_value = mock_response
90
+
91
+ download_path = tmp_path / "test_file.txt"
92
+
93
+ mock_client.download_job_result_file(
94
+ "test_job_id",
95
+ "test_file.txt",
96
+ str(tmp_path)
97
+ )
98
+
99
+ assert download_path.exists()
100
+
101
+
102
+ def test_download_job_result_file_error(mock_client, tmp_path):
103
+ with patch.object(mock_client, '_request') as mock_request:
104
+ mock_request.side_effect = Exception("Download Error")
105
+
106
+ with pytest.raises(Exception, match="There was a problem downloading this result file"):
107
+ mock_client.download_job_result_file(
108
+ "test_job_id",
109
+ "test_file.txt",
110
+ str(tmp_path)
111
+ )
112
+
113
+
114
+ def test_delete_job(mock_client):
115
+ with patch.object(mock_client, '_request') as mock_request:
116
+ mock_request.return_value = {"status": "success"}
117
+
118
+ response = mock_client.delete_job("test_job_id")
119
+
120
+ mock_request.assert_called_once_with(
121
+ "DELETE",
122
+ "api/jobs/test_job_id"
123
+ )
124
+ assert response["status"] == "success"
125
+
126
+
127
+ def test_get_balances(mock_client):
128
+ with patch.object(mock_client, '_request') as mock_request:
129
+ mock_request.return_value = {"credits": 100}
130
+
131
+ response = mock_client.get_balances()
132
+
133
+ mock_request.assert_called_once_with(
134
+ "GET",
135
+ f"api/users/{mock_client.auth.user_id}/balances"
136
+ )
137
+ assert "credits" in response
138
+
139
+
140
+ def test_get_app_list(mock_client):
141
+ with patch.object(mock_client, '_request') as mock_request:
142
+ mock_request.return_value = {"hits": []}
143
+
144
+ response = mock_client.get_app_list(
145
+ page=1,
146
+ hits_per_page=100,
147
+ search_string="test"
148
+ )
149
+
150
+ mock_request.assert_called_once()
151
+ assert "hits" in response
152
+
153
+
154
+ def test_download_all_job_results(mock_client, tmp_path):
155
+ mock_results = {
156
+ "download": [{"file": "results.zip", "title": "Results!"}],
157
+ "figures": [[{"file": "plot.png", "title": "Plot!"}]]
158
+ }
159
+
160
+ with patch.object(mock_client, 'list_job_result_files') as mock_list_files, \
161
+ patch.object(mock_client, 'download_job_result_file') as mock_download:
162
+ mock_list_files.return_value = mock_results
163
+
164
+ # Test compressed download
165
+ mock_client.download_all_job_results(
166
+ "test_job_id",
167
+ str(tmp_path),
168
+ download_compressed=True
169
+ )
170
+ mock_download.assert_called_once()
171
+
172
+ # Test uncompressed download
173
+ mock_client.download_all_job_results(
174
+ "test_job_id",
175
+ str(tmp_path),
176
+ download_compressed=False
177
+ )
178
+ assert mock_download.call_count > 1
179
+
180
+
181
+ def test_request_method(mock_client):
182
+ with patch('requests.request') as mock_request:
183
+ mock_request.return_value.json.return_value = {"test": "data"}
184
+
185
+ response = mock_client._request(
186
+ "GET",
187
+ "test/endpoint",
188
+ params={"test": "param"}
189
+ )
190
+
191
+ mock_request.assert_called_once_with(
192
+ "GET",
193
+ f"{mock_client.BASE_URL}/test/endpoint",
194
+ data=None,
195
+ json=None,
196
+ params={"test": "param"},
197
+ files=None,
198
+ headers={"Authorization": f"Bearer {mock_client.auth.token}"},
199
+ stream=False
200
+ )
201
+ assert response == {"test": "data"}
202
+
203
+
204
+ def test_list_job_result_files_error(mock_client):
205
+ with patch.object(mock_client, '_request') as mock_request:
206
+ mock_request.side_effect = Exception("API Error")
207
+
208
+ with pytest.raises(Exception, match="There was a problem finding your job"):
209
+ mock_client.list_job_result_files("invalid_job_id")
210
+
211
+
212
+ def test_create_callback(capsys):
213
+ from superbio.client import create_callback
214
+ from requests_toolbelt import MultipartEncoder
215
+
216
+ encoder = MultipartEncoder(fields={"test": "data"})
217
+ callback = create_callback(encoder)
218
+
219
+ class MockMonitor:
220
+ def __init__(self):
221
+ self.bytes_read = 50
222
+
223
+ monitor = MockMonitor()
224
+ callback(monitor)
225
+
226
+ captured = capsys.readouterr()
227
+ assert "Upload Progress: " in captured.out
tests/test_utils.py ADDED
@@ -0,0 +1,126 @@
1
+ import pytest
2
+ from datetime import datetime
3
+ from superbio.utils import data_validation, get_missing_values, job_post_validation
4
+
5
+ def test_data_validation_valid_dates():
6
+ valid_dates = ["01/01/2023", "31/12/2023"]
7
+ assert data_validation(valid_dates) is True
8
+
9
+ def test_data_validation_invalid_dates():
10
+ invalid_dates = ["2023/01/01", "13/13/2023"]
11
+ with pytest.raises(ValueError, match="Invalid date format"):
12
+ data_validation(invalid_dates)
13
+
14
+ def test_get_missing_values():
15
+ required = ["a", "b", "c"]
16
+ provided = ["a", "c"]
17
+ assert get_missing_values(required, provided) == ["b"]
18
+
19
+ def test_job_post_validation_valid(sample_app_config):
20
+ job_config = {
21
+ "analysis": "test",
22
+ "index_column": True
23
+ }
24
+ local_files = ["control", "experiment"]
25
+
26
+ # Should not raise any exceptions
27
+ job_post_validation(
28
+ sample_app_config,
29
+ job_config,
30
+ local_files,
31
+ None,
32
+ None,
33
+ "cpu"
34
+ )
35
+
36
+ def test_job_post_validation_missing_required(sample_app_config):
37
+ job_config = {
38
+ "index_column": True # Missing required 'analysis'
39
+ }
40
+ local_files = ["control", "experiment"]
41
+
42
+ with pytest.raises(Exception, match="Missing the following parameter values"):
43
+ job_post_validation(
44
+ sample_app_config,
45
+ job_config,
46
+ local_files,
47
+ None,
48
+ None,
49
+ "cpu"
50
+ )
51
+
52
+ def test_job_post_validation_invalid_mode(sample_app_config):
53
+ job_config = {
54
+ "analysis": "test",
55
+ "index_column": True
56
+ }
57
+ local_files = ["control", "experiment"]
58
+
59
+ with pytest.raises(Exception, match="Invalid running mode"):
60
+ job_post_validation(
61
+ sample_app_config,
62
+ job_config,
63
+ local_files,
64
+ None,
65
+ None,
66
+ "invalid_mode"
67
+ )
68
+
69
+ def test_job_post_validation_missing_files(sample_app_config):
70
+ job_config = {
71
+ "analysis": "test",
72
+ "index_column": True
73
+ }
74
+ local_files = ["control"] # Missing 'experiment' file
75
+
76
+ with pytest.raises(Exception, match="Missing the following files"):
77
+ job_post_validation(
78
+ sample_app_config,
79
+ job_config,
80
+ local_files,
81
+ None,
82
+ None,
83
+ "cpu"
84
+ )
85
+
86
+ def test_job_post_validation_unsupported_mode(sample_app_config):
87
+ # Modify sample config to only support CPU
88
+ sample_app_config["running_modes"] = [{"mode_id": 1}]
89
+
90
+ job_config = {
91
+ "analysis": "test",
92
+ "index_column": True
93
+ }
94
+ local_files = ["control", "experiment"]
95
+
96
+ with pytest.raises(Exception):
97
+ job_post_validation(
98
+ sample_app_config,
99
+ job_config,
100
+ local_files,
101
+ None,
102
+ None,
103
+ "gpu"
104
+ )
105
+
106
+ def test_job_post_validation_mixed_file_sources(sample_app_config):
107
+ job_config = {
108
+ "analysis": "test",
109
+ "index_column": True
110
+ }
111
+ local_files = ["control"]
112
+ remote_files = ["experiment"]
113
+
114
+ # Should not raise any exceptions when files come from different sources
115
+ job_post_validation(
116
+ sample_app_config,
117
+ job_config,
118
+ local_files,
119
+ remote_files,
120
+ None,
121
+ "cpu"
122
+ )
123
+
124
+ def test_data_validation_none_dates():
125
+ # Should handle None values without raising exception
126
+ assert data_validation([None, None]) is True