promptbio 0.1.0__tar.gz
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.
- promptbio-0.1.0/LICENSE +202 -0
- promptbio-0.1.0/NOTICE +4 -0
- promptbio-0.1.0/PKG-INFO +98 -0
- promptbio-0.1.0/README.md +78 -0
- promptbio-0.1.0/pyproject.toml +28 -0
- promptbio-0.1.0/src/promptbio/__init__.py +14 -0
- promptbio-0.1.0/src/promptbio/_api.py +352 -0
- promptbio-0.1.0/src/promptbio/client.py +410 -0
promptbio-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
promptbio-0.1.0/NOTICE
ADDED
promptbio-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: promptbio
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Run PromptBio analyses from Python notebooks, jobs and scripts
|
|
5
|
+
Author: PromptBio
|
|
6
|
+
Requires-Python: >=3.9
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
License-Expression: Apache-2.0
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
License-File: NOTICE
|
|
11
|
+
Requires-Dist: requests>=2.28
|
|
12
|
+
Requires-Dist: pandas>=1.5 ; extra == "pandas"
|
|
13
|
+
Requires-Dist: pytest>=7 ; extra == "test"
|
|
14
|
+
Requires-Dist: pandas>=1.5 ; extra == "test"
|
|
15
|
+
Project-URL: Documentation, https://platform.promptbio.ai/developers/
|
|
16
|
+
Project-URL: Homepage, https://promptbio.ai
|
|
17
|
+
Provides-Extra: pandas
|
|
18
|
+
Provides-Extra: test
|
|
19
|
+
|
|
20
|
+
# promptbio
|
|
21
|
+
|
|
22
|
+
Run [PromptBio](https://promptbio.ai) analyses from Python: Databricks notebooks and jobs, Jupyter,
|
|
23
|
+
or any scheduler. Upload a matrix, submit an analysis, wait for it, and read its result tables as
|
|
24
|
+
pandas DataFrames.
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install "promptbio[pandas]"
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
from promptbio import Client
|
|
32
|
+
|
|
33
|
+
pb = Client() # reads PROMPTBIO_API_KEY, and PROMPTBIO_SERVER (default https://platform.promptbio.ai)
|
|
34
|
+
|
|
35
|
+
counts = pb.upload_matrix(counts_df, project="<project uuid>", feature_type="Gene Expression", name="counts")
|
|
36
|
+
design = pb.upload_matrix(samples_df, project="<project uuid>", feature_type="Clinical", name="samples")
|
|
37
|
+
|
|
38
|
+
run = pb.submit_differential_analysis(
|
|
39
|
+
name="tumor_vs_normal", project="<project uuid>",
|
|
40
|
+
feature_matrix=counts, design_matrix=design,
|
|
41
|
+
label_column="condition", case="tumor", control="normal",
|
|
42
|
+
)
|
|
43
|
+
pb.wait(run) # raises RunFailed if the run ends in error
|
|
44
|
+
for t in pb.result_tables(run): # what the run produced, with typed columns
|
|
45
|
+
print(t["name"], t.get("rows"))
|
|
46
|
+
da = pb.read_table(run, "da_results") # every file of the table, typed, under stable column names
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`PROMPTBIO_SERVER` may name a PromptBio web address (`https://` is added when it has no scheme);
|
|
50
|
+
the client finds the API under it as the `promptbio` CLI does.
|
|
51
|
+
|
|
52
|
+
## API key
|
|
53
|
+
|
|
54
|
+
Create one in PromptBio under **Connections › API Keys**, with **Access** set to *Read and submit*,
|
|
55
|
+
which covers everything above; a key limited to some projects works on those projects only. Keep it in a secret
|
|
56
|
+
store, for example a Databricks secret scope:
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
import os
|
|
60
|
+
os.environ["PROMPTBIO_API_KEY"] = dbutils.secrets.get("promptbio", "api_key")
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Every endpoint
|
|
64
|
+
|
|
65
|
+
`pb.api` has one method per operation of PromptBio's public API, generated from its OpenAPI file
|
|
66
|
+
(`https://platform.promptbio.ai/developers/openapi.json`) and named after the operation, for
|
|
67
|
+
example `pb.api.list_runs(...)` or `pb.api.estimate_analysis(body=...)`. Each returns the reply's
|
|
68
|
+
`data` and raises `PromptBioError` when the reply's `code` is not 0; an operation that answers CSV,
|
|
69
|
+
such as `pb.api.read_run_result_table(run, "da_results")`, returns its bytes.
|
|
70
|
+
|
|
71
|
+
A GET is retried on HTTP 429 and 5xx and on a dropped connection, waiting what `Retry-After` asks or
|
|
72
|
+
1, 2, 4 and 8 seconds; a submission or upload only on 429, since one that timed out or got a 5xx may
|
|
73
|
+
have gone through. `Client(retries=0)` turns this off.
|
|
74
|
+
|
|
75
|
+
`read_table` waits up to 10 minutes for its reply, as long as PromptBio's web proxy waits, since the
|
|
76
|
+
server prepares the whole table before sending it. A read that times out is not retried (the server
|
|
77
|
+
would prepare the table again); download a table that slow as result files. A client calling the
|
|
78
|
+
API directly can wait longer with `Client(table_timeout=...)`. When the server is busy preparing
|
|
79
|
+
other tables it answers 429, which the client waits out and retries.
|
|
80
|
+
|
|
81
|
+
## Network
|
|
82
|
+
|
|
83
|
+
A workspace that restricts outbound traffic (Databricks serverless egress control, a firewall) must
|
|
84
|
+
allow `platform.promptbio.ai`. Reading a result table goes through it too; only downloading a raw
|
|
85
|
+
result file (`pb.api.download_run_result`) reaches the storage host its link points to.
|
|
86
|
+
|
|
87
|
+
## Releasing
|
|
88
|
+
|
|
89
|
+
A tag `python-client-v<version>` matching `__version__` in `src/promptbio/__init__.py` publishes the
|
|
90
|
+
package to PyPI from the `Python client` workflow, through PyPI trusted publishing: no upload token is
|
|
91
|
+
stored anywhere. Only organization admins can push these tags (the `python-client-release-tags`
|
|
92
|
+
ruleset), and only these tags may deploy to the workflow's `pypi` environment. The PyPI project is owned
|
|
93
|
+
by named PromptBio staff accounts, one person each, as PyPI's terms require.
|
|
94
|
+
|
|
95
|
+
## License
|
|
96
|
+
|
|
97
|
+
Apache License 2.0; see `LICENSE`. Copyright 2026 PromptBio Inc.
|
|
98
|
+
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# promptbio
|
|
2
|
+
|
|
3
|
+
Run [PromptBio](https://promptbio.ai) analyses from Python: Databricks notebooks and jobs, Jupyter,
|
|
4
|
+
or any scheduler. Upload a matrix, submit an analysis, wait for it, and read its result tables as
|
|
5
|
+
pandas DataFrames.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install "promptbio[pandas]"
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```python
|
|
12
|
+
from promptbio import Client
|
|
13
|
+
|
|
14
|
+
pb = Client() # reads PROMPTBIO_API_KEY, and PROMPTBIO_SERVER (default https://platform.promptbio.ai)
|
|
15
|
+
|
|
16
|
+
counts = pb.upload_matrix(counts_df, project="<project uuid>", feature_type="Gene Expression", name="counts")
|
|
17
|
+
design = pb.upload_matrix(samples_df, project="<project uuid>", feature_type="Clinical", name="samples")
|
|
18
|
+
|
|
19
|
+
run = pb.submit_differential_analysis(
|
|
20
|
+
name="tumor_vs_normal", project="<project uuid>",
|
|
21
|
+
feature_matrix=counts, design_matrix=design,
|
|
22
|
+
label_column="condition", case="tumor", control="normal",
|
|
23
|
+
)
|
|
24
|
+
pb.wait(run) # raises RunFailed if the run ends in error
|
|
25
|
+
for t in pb.result_tables(run): # what the run produced, with typed columns
|
|
26
|
+
print(t["name"], t.get("rows"))
|
|
27
|
+
da = pb.read_table(run, "da_results") # every file of the table, typed, under stable column names
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`PROMPTBIO_SERVER` may name a PromptBio web address (`https://` is added when it has no scheme);
|
|
31
|
+
the client finds the API under it as the `promptbio` CLI does.
|
|
32
|
+
|
|
33
|
+
## API key
|
|
34
|
+
|
|
35
|
+
Create one in PromptBio under **Connections › API Keys**, with **Access** set to *Read and submit*,
|
|
36
|
+
which covers everything above; a key limited to some projects works on those projects only. Keep it in a secret
|
|
37
|
+
store, for example a Databricks secret scope:
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
import os
|
|
41
|
+
os.environ["PROMPTBIO_API_KEY"] = dbutils.secrets.get("promptbio", "api_key")
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Every endpoint
|
|
45
|
+
|
|
46
|
+
`pb.api` has one method per operation of PromptBio's public API, generated from its OpenAPI file
|
|
47
|
+
(`https://platform.promptbio.ai/developers/openapi.json`) and named after the operation, for
|
|
48
|
+
example `pb.api.list_runs(...)` or `pb.api.estimate_analysis(body=...)`. Each returns the reply's
|
|
49
|
+
`data` and raises `PromptBioError` when the reply's `code` is not 0; an operation that answers CSV,
|
|
50
|
+
such as `pb.api.read_run_result_table(run, "da_results")`, returns its bytes.
|
|
51
|
+
|
|
52
|
+
A GET is retried on HTTP 429 and 5xx and on a dropped connection, waiting what `Retry-After` asks or
|
|
53
|
+
1, 2, 4 and 8 seconds; a submission or upload only on 429, since one that timed out or got a 5xx may
|
|
54
|
+
have gone through. `Client(retries=0)` turns this off.
|
|
55
|
+
|
|
56
|
+
`read_table` waits up to 10 minutes for its reply, as long as PromptBio's web proxy waits, since the
|
|
57
|
+
server prepares the whole table before sending it. A read that times out is not retried (the server
|
|
58
|
+
would prepare the table again); download a table that slow as result files. A client calling the
|
|
59
|
+
API directly can wait longer with `Client(table_timeout=...)`. When the server is busy preparing
|
|
60
|
+
other tables it answers 429, which the client waits out and retries.
|
|
61
|
+
|
|
62
|
+
## Network
|
|
63
|
+
|
|
64
|
+
A workspace that restricts outbound traffic (Databricks serverless egress control, a firewall) must
|
|
65
|
+
allow `platform.promptbio.ai`. Reading a result table goes through it too; only downloading a raw
|
|
66
|
+
result file (`pb.api.download_run_result`) reaches the storage host its link points to.
|
|
67
|
+
|
|
68
|
+
## Releasing
|
|
69
|
+
|
|
70
|
+
A tag `python-client-v<version>` matching `__version__` in `src/promptbio/__init__.py` publishes the
|
|
71
|
+
package to PyPI from the `Python client` workflow, through PyPI trusted publishing: no upload token is
|
|
72
|
+
stored anywhere. Only organization admins can push these tags (the `python-client-release-tags`
|
|
73
|
+
ruleset), and only these tags may deploy to the workflow's `pypi` environment. The PyPI project is owned
|
|
74
|
+
by named PromptBio staff accounts, one person each, as PyPI's terms require.
|
|
75
|
+
|
|
76
|
+
## License
|
|
77
|
+
|
|
78
|
+
Apache License 2.0; see `LICENSE`. Copyright 2026 PromptBio Inc.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
# flit_core builds the package from src/promptbio alone: the source archive
|
|
3
|
+
# holds the package, this file, the README and the licence, nothing else
|
|
4
|
+
# from the repository.
|
|
5
|
+
requires = ["flit_core>=3.12,<4"]
|
|
6
|
+
build-backend = "flit_core.buildapi"
|
|
7
|
+
|
|
8
|
+
[project]
|
|
9
|
+
name = "promptbio"
|
|
10
|
+
dynamic = ["version"]
|
|
11
|
+
description = "Run PromptBio analyses from Python notebooks, jobs and scripts"
|
|
12
|
+
readme = "README.md"
|
|
13
|
+
license = "Apache-2.0"
|
|
14
|
+
license-files = ["LICENSE", "NOTICE"]
|
|
15
|
+
requires-python = ">=3.9"
|
|
16
|
+
authors = [{ name = "PromptBio" }]
|
|
17
|
+
dependencies = ["requests>=2.28"]
|
|
18
|
+
|
|
19
|
+
[project.optional-dependencies]
|
|
20
|
+
pandas = ["pandas>=1.5"]
|
|
21
|
+
test = ["pytest>=7", "pandas>=1.5"]
|
|
22
|
+
|
|
23
|
+
[project.urls]
|
|
24
|
+
Homepage = "https://promptbio.ai"
|
|
25
|
+
Documentation = "https://platform.promptbio.ai/developers/"
|
|
26
|
+
|
|
27
|
+
[tool.pytest.ini_options]
|
|
28
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""PromptBio's Python client: run PromptBio analyses from scripts and notebooks
|
|
2
|
+
(Databricks, Jupyter, schedulers) with an API key.
|
|
3
|
+
|
|
4
|
+
from promptbio import Client
|
|
5
|
+
pb = Client() # PROMPTBIO_API_KEY, PROMPTBIO_SERVER
|
|
6
|
+
run = pb.submit_differential_analysis(...)
|
|
7
|
+
pb.wait(run)
|
|
8
|
+
df = pb.read_table(run, "da_results")
|
|
9
|
+
"""
|
|
10
|
+
__version__ = "0.1.0"
|
|
11
|
+
|
|
12
|
+
from .client import Client, PromptBioError, RunFailed, api_base # noqa: E402
|
|
13
|
+
|
|
14
|
+
__all__ = ["Client", "PromptBioError", "RunFailed", "api_base", "__version__"]
|
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
"""Low-level PromptBio API calls, one per operation.
|
|
2
|
+
|
|
3
|
+
Generated by scripts/generate.py from frontend/public/developers/openapi.json
|
|
4
|
+
(API 1.0.0). Do not edit by hand.
|
|
5
|
+
"""
|
|
6
|
+
from typing import Any, Dict, Optional
|
|
7
|
+
|
|
8
|
+
# operationId: (method, path, path parameters, query parameters, body kind, response kind)
|
|
9
|
+
OPERATIONS = {
|
|
10
|
+
'listUsage': ('GET', '/api/v1/billing/user/history', (), ('from', 'to', 'category', 'q', 'tz', 'page', 'size'), None, 'json'),
|
|
11
|
+
'exportUsage': ('GET', '/api/v1/billing/user/history/export', (), ('from', 'to', 'category', 'q', 'tz'), None, 'csv'),
|
|
12
|
+
'connectAlibaba': ('POST', '/api/v1/connectors/alibaba/connect', (), (), 'json', 'json'),
|
|
13
|
+
'connectAzure': ('POST', '/api/v1/connectors/azure/connect', (), (), 'json', 'json'),
|
|
14
|
+
'connectBackblaze': ('POST', '/api/v1/connectors/backblaze/connect', (), (), 'json', 'json'),
|
|
15
|
+
'connectBenchling': ('POST', '/api/v1/connectors/benchling/connect', (), (), 'json', 'json'),
|
|
16
|
+
'browseConnection': ('POST', '/api/v1/connectors/browse', (), (), 'json', 'json'),
|
|
17
|
+
'connectByteDance': ('POST', '/api/v1/connectors/bytedance/connect', (), (), 'json', 'json'),
|
|
18
|
+
'connectDatabricksShared': ('POST', '/api/v1/connectors/databricks/connect_shared', (), (), None, 'json'),
|
|
19
|
+
'importDatabricksTable': ('POST', '/api/v1/connectors/databricks/tables/import', (), (), 'json', 'json'),
|
|
20
|
+
'getDatabricksTableImport': ('GET', '/api/v1/connectors/databricks/tables/imports/:uuid', ('uuid',), (), None, 'json'),
|
|
21
|
+
'refreshDatabricksTableImport': ('POST', '/api/v1/connectors/databricks/tables/imports/:uuid/refresh', ('uuid',), (), 'json', 'json'),
|
|
22
|
+
'previewDatabricksTable': ('POST', '/api/v1/connectors/databricks/tables/preview', (), (), 'json', 'json'),
|
|
23
|
+
'getDatabricksWorkspace': ('GET', '/api/v1/connectors/databricks/workspace', (), (), None, 'json'),
|
|
24
|
+
'saveDatabricksWorkspace': ('PUT', '/api/v1/connectors/databricks/workspace', (), (), 'json', 'json'),
|
|
25
|
+
'deleteDatabricksWorkspace': ('DELETE', '/api/v1/connectors/databricks/workspace', (), (), None, 'json'),
|
|
26
|
+
'checkDatabricksWorkspace': ('POST', '/api/v1/connectors/databricks/workspace/check', (), (), None, 'json'),
|
|
27
|
+
'disconnect': ('POST', '/api/v1/connectors/disconnect', (), (), 'json', 'json'),
|
|
28
|
+
'connectGCS': ('POST', '/api/v1/connectors/gcs/connect', (), (), 'json', 'json'),
|
|
29
|
+
'connectIQVIA': ('POST', '/api/v1/connectors/iqvia/connect', (), (), 'json', 'json'),
|
|
30
|
+
'listConnectors': ('GET', '/api/v1/connectors/list', (), (), None, 'json'),
|
|
31
|
+
'connectOracle': ('POST', '/api/v1/connectors/oracle/connect', (), (), 'json', 'json'),
|
|
32
|
+
'registerFiles': ('POST', '/api/v1/connectors/register', (), (), 'json', 'json'),
|
|
33
|
+
'connectS3': ('POST', '/api/v1/connectors/s3/connect', (), (), 'json', 'json'),
|
|
34
|
+
'connectTencent': ('POST', '/api/v1/connectors/tencent/connect', (), (), 'json', 'json'),
|
|
35
|
+
'connectTenx': ('POST', '/api/v1/connectors/tenx/connect', (), (), 'json', 'json'),
|
|
36
|
+
'connectVeeva': ('POST', '/api/v1/connectors/veeva/connect', (), (), 'json', 'json'),
|
|
37
|
+
'connectYandex': ('POST', '/api/v1/connectors/yandex/connect', (), (), 'json', 'json'),
|
|
38
|
+
'getMatrix': ('GET', '/api/v1/feature_store/feature_matrix/detail', (), ('feature_matrix_uuid', 'no_preview'), None, 'json'),
|
|
39
|
+
'listMatrices': ('GET', '/api/v1/feature_store/feature_matrix/list', (), ('project_uuid', 'feature_type', 'feature_matrix_name', 'page', 'size'), None, 'json'),
|
|
40
|
+
'registerRunMatrix': ('POST', '/api/v1/feature_store/feature_matrix/query_store', (), (), 'json', 'json'),
|
|
41
|
+
'registerMatrix': ('POST', '/api/v1/feature_store/feature_matrix/upload', (), (), 'multipart', 'json'),
|
|
42
|
+
'listFeatureTypes': ('GET', '/api/v1/feature_store/feature_type/list', (), (), None, 'json'),
|
|
43
|
+
'instrumentHeartbeat': ('POST', '/api/v1/instruments/heartbeat', (), (), 'json', 'json'),
|
|
44
|
+
'submitSampleSheet': ('POST', '/api/v1/samples/submit_file_v3', (), (), 'multipart', 'json'),
|
|
45
|
+
'sampleSheetTemplate': ('GET', '/api/v1/samples/template_v3', (), (), None, 'csv'),
|
|
46
|
+
'getRun': ('GET', '/api/v1/tasks/:uuid/detail', ('uuid',), (), None, 'json'),
|
|
47
|
+
'getRunLog': ('GET', '/api/v1/tasks/:uuid/log', ('uuid',), (), None, 'json'),
|
|
48
|
+
'getRunResultExport': ('GET', '/api/v1/tasks/:uuid/results/export', ('uuid',), (), None, 'json'),
|
|
49
|
+
'startRunResultExport': ('POST', '/api/v1/tasks/:uuid/results/export', ('uuid',), (), None, 'json'),
|
|
50
|
+
'listRunResults': ('GET', '/api/v1/tasks/:uuid/results/files', ('uuid',), ('path',), None, 'json'),
|
|
51
|
+
'downloadRunResult': ('GET', '/api/v1/tasks/:uuid/results/files/download', ('uuid',), ('path',), None, 'json'),
|
|
52
|
+
'listRunResultTables': ('GET', '/api/v1/tasks/:uuid/results/tables', ('uuid',), (), None, 'json'),
|
|
53
|
+
'readRunResultTable': ('GET', '/api/v1/tasks/:uuid/results/tables/:name/rows', ('uuid', 'name'), (), None, 'csv'),
|
|
54
|
+
'stopRun': ('POST', '/api/v1/tasks/:uuid/terminate', ('uuid',), (), None, 'json'),
|
|
55
|
+
'estimateAnalysis': ('POST', '/api/v1/tasks/analyses/cost_predict', (), (), 'json', 'json'),
|
|
56
|
+
'submitAnalysis': ('POST', '/api/v1/tasks/analyses/submit', (), (), 'json', 'json'),
|
|
57
|
+
'estimateByop': ('POST', '/api/v1/tasks/byop/cost_predict', (), (), 'json', 'json'),
|
|
58
|
+
'submitByop': ('POST', '/api/v1/tasks/byop/submit', (), (), 'json', 'json'),
|
|
59
|
+
'uploadRunInput': ('POST', '/api/v1/tasks/file/upload', (), (), 'multipart', 'json'),
|
|
60
|
+
'estimateMLGenie': ('POST', '/api/v1/tasks/ml_genie/cost_predict', (), (), 'json', 'json'),
|
|
61
|
+
'mlgenieLabel': ('POST', '/api/v1/tasks/ml_genie/label/submit', (), (), 'json', 'json'),
|
|
62
|
+
'mlgenieMatrices': ('POST', '/api/v1/tasks/ml_genie/matrix/submit', (), (), 'json', 'json'),
|
|
63
|
+
'submitMLGenie': ('POST', '/api/v1/tasks/ml_genie/submit', (), (), 'json', 'json'),
|
|
64
|
+
'estimateNfCore': ('POST', '/api/v1/tasks/nfcore/cost_predict', (), (), 'json', 'json'),
|
|
65
|
+
'submitNfCore': ('POST', '/api/v1/tasks/nfcore/submit', (), (), 'json', 'json'),
|
|
66
|
+
'getPipelineConfig': ('GET', '/api/v1/tasks/pipeline/config', (), ('pipeline_id',), None, 'json'),
|
|
67
|
+
'estimatePipeline': ('POST', '/api/v1/tasks/pipeline/cost_predict', (), (), 'json', 'json'),
|
|
68
|
+
'listPipelines': ('GET', '/api/v1/tasks/pipeline/release', (), ('pipeline_type',), None, 'json'),
|
|
69
|
+
'submitPipeline': ('POST', '/api/v1/tasks/pipeline/submit', (), (), 'json', 'json'),
|
|
70
|
+
'listRuns': ('GET', '/api/v1/tasks/runs', (), ('project_uuid', 'task_type', 'status', 'name', 'created_after', 'page', 'limit'), None, 'json'),
|
|
71
|
+
'finishUpload': ('POST', '/api/v1/upload/all_complete', (), (), 'json', 'json'),
|
|
72
|
+
'cancelUpload': ('POST', '/api/v1/upload/cancel', (), (), 'json', 'json'),
|
|
73
|
+
'completePart': ('POST', '/api/v1/upload/chunk_complete', (), (), 'json', 'json'),
|
|
74
|
+
'startUpload': ('GET', '/api/v1/upload/generate_upload_id', (), ('filename', 'file_hash', 'total_chunks'), None, 'json'),
|
|
75
|
+
'listFiles': ('GET', '/api/v1/upload/paginate_uploaded_files', (), ('name', 'page', 'size', 'sort_field', 'sort_order'), None, 'json'),
|
|
76
|
+
'signPart': ('POST', '/api/v1/upload/signed_url', (), (), 'json', 'json'),
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class API:
|
|
81
|
+
"""Every operation of the public API. Each returns the reply's ``data``."""
|
|
82
|
+
|
|
83
|
+
def __init__(self, transport: Any):
|
|
84
|
+
self._t = transport
|
|
85
|
+
|
|
86
|
+
def list_usage(self, *, from_: Any = None, to: Any = None, category: Any = None, q: Any = None, tz: Any = None, page: Any = None, size: Any = None) -> Any:
|
|
87
|
+
"""The credit ledger. ``GET /api/v1/billing/user/history``"""
|
|
88
|
+
return self._t.call('listUsage', path={}, query={'from': from_, 'to': to, 'category': category, 'q': q, 'tz': tz, 'page': page, 'size': size})
|
|
89
|
+
|
|
90
|
+
def export_usage(self, *, from_: Any = None, to: Any = None, category: Any = None, q: Any = None, tz: Any = None) -> Any:
|
|
91
|
+
"""Export the credit ledger as CSV. Returns the CSV's bytes. ``GET /api/v1/billing/user/history/export``"""
|
|
92
|
+
return self._t.call('exportUsage', path={}, query={'from': from_, 'to': to, 'category': category, 'q': q, 'tz': tz})
|
|
93
|
+
|
|
94
|
+
def connect_alibaba(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
95
|
+
"""Connect an Alibaba Cloud OSS bucket. ``POST /api/v1/connectors/alibaba/connect``"""
|
|
96
|
+
return self._t.call('connectAlibaba', path={}, query={}, body=body)
|
|
97
|
+
|
|
98
|
+
def connect_azure(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
99
|
+
"""Connect an Azure Blob Storage container. ``POST /api/v1/connectors/azure/connect``"""
|
|
100
|
+
return self._t.call('connectAzure', path={}, query={}, body=body)
|
|
101
|
+
|
|
102
|
+
def connect_backblaze(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
103
|
+
"""Connect a Backblaze B2 bucket. ``POST /api/v1/connectors/backblaze/connect``"""
|
|
104
|
+
return self._t.call('connectBackblaze', path={}, query={}, body=body)
|
|
105
|
+
|
|
106
|
+
def connect_benchling(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
107
|
+
"""Connect a Benchling tenant. ``POST /api/v1/connectors/benchling/connect``"""
|
|
108
|
+
return self._t.call('connectBenchling', path={}, query={}, body=body)
|
|
109
|
+
|
|
110
|
+
def browse_connection(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
111
|
+
"""List one folder of a connection. ``POST /api/v1/connectors/browse``"""
|
|
112
|
+
return self._t.call('browseConnection', path={}, query={}, body=body)
|
|
113
|
+
|
|
114
|
+
def connect_byte_dance(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
115
|
+
"""Connect a ByteDance TOS bucket (Volcengine or BytePlus). ``POST /api/v1/connectors/bytedance/connect``"""
|
|
116
|
+
return self._t.call('connectByteDance', path={}, query={}, body=body)
|
|
117
|
+
|
|
118
|
+
def connect_databricks_shared(self) -> Any:
|
|
119
|
+
"""Connect to Databricks as the organization's service principal. ``POST /api/v1/connectors/databricks/connect_shared``"""
|
|
120
|
+
return self._t.call('connectDatabricksShared', path={}, query={})
|
|
121
|
+
|
|
122
|
+
def import_databricks_table(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
123
|
+
"""Import a Unity Catalog table as a matrix or a sample sheet. ``POST /api/v1/connectors/databricks/tables/import``"""
|
|
124
|
+
return self._t.call('importDatabricksTable', path={}, query={}, body=body)
|
|
125
|
+
|
|
126
|
+
def get_databricks_table_import(self, uuid: str) -> Any:
|
|
127
|
+
"""A table import's progress and outcome. ``GET /api/v1/connectors/databricks/tables/imports/:uuid``"""
|
|
128
|
+
return self._t.call('getDatabricksTableImport', path={'uuid': uuid}, query={})
|
|
129
|
+
|
|
130
|
+
def refresh_databricks_table_import(self, uuid: str, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
131
|
+
"""Read an imported matrix's table again into a new matrix. ``POST /api/v1/connectors/databricks/tables/imports/:uuid/refresh``"""
|
|
132
|
+
return self._t.call('refreshDatabricksTableImport', path={'uuid': uuid}, query={}, body=body)
|
|
133
|
+
|
|
134
|
+
def preview_databricks_table(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
135
|
+
"""Show a Unity Catalog table's columns and first rows. ``POST /api/v1/connectors/databricks/tables/preview``"""
|
|
136
|
+
return self._t.call('previewDatabricksTable', path={}, query={}, body=body)
|
|
137
|
+
|
|
138
|
+
def get_databricks_workspace(self) -> Any:
|
|
139
|
+
"""Get the organization's Databricks workspace registration. ``GET /api/v1/connectors/databricks/workspace``"""
|
|
140
|
+
return self._t.call('getDatabricksWorkspace', path={}, query={})
|
|
141
|
+
|
|
142
|
+
def save_databricks_workspace(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
143
|
+
"""Register or change the organization's Databricks workspace. ``PUT /api/v1/connectors/databricks/workspace``"""
|
|
144
|
+
return self._t.call('saveDatabricksWorkspace', path={}, query={}, body=body)
|
|
145
|
+
|
|
146
|
+
def delete_databricks_workspace(self) -> Any:
|
|
147
|
+
"""Remove the organization's Databricks workspace. ``DELETE /api/v1/connectors/databricks/workspace``"""
|
|
148
|
+
return self._t.call('deleteDatabricksWorkspace', path={}, query={})
|
|
149
|
+
|
|
150
|
+
def check_databricks_workspace(self) -> Any:
|
|
151
|
+
"""Check the organization's Databricks registration. ``POST /api/v1/connectors/databricks/workspace/check``"""
|
|
152
|
+
return self._t.call('checkDatabricksWorkspace', path={}, query={})
|
|
153
|
+
|
|
154
|
+
def disconnect(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
155
|
+
"""Remove a connection. ``POST /api/v1/connectors/disconnect``"""
|
|
156
|
+
return self._t.call('disconnect', path={}, query={}, body=body)
|
|
157
|
+
|
|
158
|
+
def connect_gcs(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
159
|
+
"""Connect a Google Cloud Storage bucket. ``POST /api/v1/connectors/gcs/connect``"""
|
|
160
|
+
return self._t.call('connectGCS', path={}, query={}, body=body)
|
|
161
|
+
|
|
162
|
+
def connect_iqvia(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
163
|
+
"""Connect an IQVIA data delivery bucket. ``POST /api/v1/connectors/iqvia/connect``"""
|
|
164
|
+
return self._t.call('connectIQVIA', path={}, query={}, body=body)
|
|
165
|
+
|
|
166
|
+
def list_connectors(self) -> Any:
|
|
167
|
+
"""List storage providers and your connections. ``GET /api/v1/connectors/list``"""
|
|
168
|
+
return self._t.call('listConnectors', path={}, query={})
|
|
169
|
+
|
|
170
|
+
def connect_oracle(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
171
|
+
"""Connect an Oracle Cloud Object Storage bucket. ``POST /api/v1/connectors/oracle/connect``"""
|
|
172
|
+
return self._t.call('connectOracle', path={}, query={}, body=body)
|
|
173
|
+
|
|
174
|
+
def register_files(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
175
|
+
"""Add files from a connection, optionally with a sample sheet. ``POST /api/v1/connectors/register``"""
|
|
176
|
+
return self._t.call('registerFiles', path={}, query={}, body=body)
|
|
177
|
+
|
|
178
|
+
def connect_s3(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
179
|
+
"""Connect an Amazon S3 bucket. ``POST /api/v1/connectors/s3/connect``"""
|
|
180
|
+
return self._t.call('connectS3', path={}, query={}, body=body)
|
|
181
|
+
|
|
182
|
+
def connect_tencent(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
183
|
+
"""Connect a Tencent Cloud COS bucket. ``POST /api/v1/connectors/tencent/connect``"""
|
|
184
|
+
return self._t.call('connectTencent', path={}, query={}, body=body)
|
|
185
|
+
|
|
186
|
+
def connect_tenx(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
187
|
+
"""Connect a 10x Genomics Cloud account. ``POST /api/v1/connectors/tenx/connect``"""
|
|
188
|
+
return self._t.call('connectTenx', path={}, query={}, body=body)
|
|
189
|
+
|
|
190
|
+
def connect_veeva(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
191
|
+
"""Connect a Veeva Vault. ``POST /api/v1/connectors/veeva/connect``"""
|
|
192
|
+
return self._t.call('connectVeeva', path={}, query={}, body=body)
|
|
193
|
+
|
|
194
|
+
def connect_yandex(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
195
|
+
"""Connect a Yandex Object Storage bucket. ``POST /api/v1/connectors/yandex/connect``"""
|
|
196
|
+
return self._t.call('connectYandex', path={}, query={}, body=body)
|
|
197
|
+
|
|
198
|
+
def get_matrix(self, *, feature_matrix_uuid: Any, no_preview: Any = None) -> Any:
|
|
199
|
+
"""A feature matrix, with a preview. ``GET /api/v1/feature_store/feature_matrix/detail``"""
|
|
200
|
+
return self._t.call('getMatrix', path={}, query={'feature_matrix_uuid': feature_matrix_uuid, 'no_preview': no_preview})
|
|
201
|
+
|
|
202
|
+
def list_matrices(self, *, project_uuid: Any = None, feature_type: Any = None, feature_matrix_name: Any = None, page: Any = None, size: Any = None) -> Any:
|
|
203
|
+
"""List feature matrices. ``GET /api/v1/feature_store/feature_matrix/list``"""
|
|
204
|
+
return self._t.call('listMatrices', path={}, query={'project_uuid': project_uuid, 'feature_type': feature_type, 'feature_matrix_name': feature_matrix_name, 'page': page, 'size': size})
|
|
205
|
+
|
|
206
|
+
def register_run_matrix(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
207
|
+
"""Register the feature matrix a pipeline run produced. ``POST /api/v1/feature_store/feature_matrix/query_store``"""
|
|
208
|
+
return self._t.call('registerRunMatrix', path={}, query={}, body=body)
|
|
209
|
+
|
|
210
|
+
def register_matrix(self, *, data: Optional[Dict[str, Any]] = None, files: Optional[Dict[str, Any]] = None) -> Any:
|
|
211
|
+
"""Register a feature matrix from a CSV. ``POST /api/v1/feature_store/feature_matrix/upload``"""
|
|
212
|
+
return self._t.call('registerMatrix', path={}, query={}, data=data, files=files)
|
|
213
|
+
|
|
214
|
+
def list_feature_types(self) -> Any:
|
|
215
|
+
"""The feature types a matrix can have. ``GET /api/v1/feature_store/feature_type/list``"""
|
|
216
|
+
return self._t.call('listFeatureTypes', path={}, query={})
|
|
217
|
+
|
|
218
|
+
def instrument_heartbeat(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
219
|
+
"""Report that a folder is being watched. ``POST /api/v1/instruments/heartbeat``"""
|
|
220
|
+
return self._t.call('instrumentHeartbeat', path={}, query={}, body=body)
|
|
221
|
+
|
|
222
|
+
def submit_sample_sheet(self, *, data: Optional[Dict[str, Any]] = None, files: Optional[Dict[str, Any]] = None) -> Any:
|
|
223
|
+
"""Register samples from a sample sheet, or check one. ``POST /api/v1/samples/submit_file_v3``"""
|
|
224
|
+
return self._t.call('submitSampleSheet', path={}, query={}, data=data, files=files)
|
|
225
|
+
|
|
226
|
+
def sample_sheet_template(self) -> Any:
|
|
227
|
+
"""Download the sample sheet template. Returns the CSV's bytes. ``GET /api/v1/samples/template_v3``"""
|
|
228
|
+
return self._t.call('sampleSheetTemplate', path={}, query={})
|
|
229
|
+
|
|
230
|
+
def get_run(self, uuid: str) -> Any:
|
|
231
|
+
"""A run's status and details. ``GET /api/v1/tasks/:uuid/detail``"""
|
|
232
|
+
return self._t.call('getRun', path={'uuid': uuid}, query={})
|
|
233
|
+
|
|
234
|
+
def get_run_log(self, uuid: str) -> Any:
|
|
235
|
+
"""A failed run's error report. ``GET /api/v1/tasks/:uuid/log``"""
|
|
236
|
+
return self._t.call('getRunLog', path={'uuid': uuid}, query={})
|
|
237
|
+
|
|
238
|
+
def get_run_result_export(self, uuid: str) -> Any:
|
|
239
|
+
"""Whether a run can be sent to Databricks, and its latest send. ``GET /api/v1/tasks/:uuid/results/export``"""
|
|
240
|
+
return self._t.call('getRunResultExport', path={'uuid': uuid}, query={})
|
|
241
|
+
|
|
242
|
+
def start_run_result_export(self, uuid: str) -> Any:
|
|
243
|
+
"""Send a run's result tables to Databricks. ``POST /api/v1/tasks/:uuid/results/export``"""
|
|
244
|
+
return self._t.call('startRunResultExport', path={'uuid': uuid}, query={})
|
|
245
|
+
|
|
246
|
+
def list_run_results(self, uuid: str, *, path: Any = None) -> Any:
|
|
247
|
+
"""List a run's result files. ``GET /api/v1/tasks/:uuid/results/files``"""
|
|
248
|
+
return self._t.call('listRunResults', path={'uuid': uuid}, query={'path': path})
|
|
249
|
+
|
|
250
|
+
def download_run_result(self, uuid: str, *, path: Any) -> Any:
|
|
251
|
+
"""A download link for one result file. ``GET /api/v1/tasks/:uuid/results/files/download``"""
|
|
252
|
+
return self._t.call('downloadRunResult', path={'uuid': uuid}, query={'path': path})
|
|
253
|
+
|
|
254
|
+
def list_run_result_tables(self, uuid: str) -> Any:
|
|
255
|
+
"""List a run's result tables. ``GET /api/v1/tasks/:uuid/results/tables``"""
|
|
256
|
+
return self._t.call('listRunResultTables', path={'uuid': uuid}, query={})
|
|
257
|
+
|
|
258
|
+
def read_run_result_table(self, uuid: str, name: str) -> Any:
|
|
259
|
+
"""Read one of a run's result tables as CSV. Returns the CSV's bytes. ``GET /api/v1/tasks/:uuid/results/tables/:name/rows``"""
|
|
260
|
+
return self._t.call('readRunResultTable', path={'uuid': uuid, 'name': name}, query={})
|
|
261
|
+
|
|
262
|
+
def stop_run(self, uuid: str) -> Any:
|
|
263
|
+
"""Stop a run. ``POST /api/v1/tasks/:uuid/terminate``"""
|
|
264
|
+
return self._t.call('stopRun', path={'uuid': uuid}, query={})
|
|
265
|
+
|
|
266
|
+
def estimate_analysis(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
267
|
+
"""Estimate an analysis run. ``POST /api/v1/tasks/analyses/cost_predict``"""
|
|
268
|
+
return self._t.call('estimateAnalysis', path={}, query={}, body=body)
|
|
269
|
+
|
|
270
|
+
def submit_analysis(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
271
|
+
"""Submit an analysis run. ``POST /api/v1/tasks/analyses/submit``"""
|
|
272
|
+
return self._t.call('submitAnalysis', path={}, query={}, body=body)
|
|
273
|
+
|
|
274
|
+
def estimate_byop(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
275
|
+
"""Estimate your own pipeline (BYOP) run. ``POST /api/v1/tasks/byop/cost_predict``"""
|
|
276
|
+
return self._t.call('estimateByop', path={}, query={}, body=body)
|
|
277
|
+
|
|
278
|
+
def submit_byop(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
279
|
+
"""Submit your own pipeline (BYOP) run. ``POST /api/v1/tasks/byop/submit``"""
|
|
280
|
+
return self._t.call('submitByop', path={}, query={}, body=body)
|
|
281
|
+
|
|
282
|
+
def upload_run_input(self, *, data: Optional[Dict[str, Any]] = None, files: Optional[Dict[str, Any]] = None) -> Any:
|
|
283
|
+
"""Upload a run's input file (a sample sheet, a params file). ``POST /api/v1/tasks/file/upload``"""
|
|
284
|
+
return self._t.call('uploadRunInput', path={}, query={}, data=data, files=files)
|
|
285
|
+
|
|
286
|
+
def estimate_mlgenie(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
287
|
+
"""Estimate an MLGenie run. ``POST /api/v1/tasks/ml_genie/cost_predict``"""
|
|
288
|
+
return self._t.call('estimateMLGenie', path={}, query={}, body=body)
|
|
289
|
+
|
|
290
|
+
def mlgenie_label(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
291
|
+
"""MLGenie: take the label. ``POST /api/v1/tasks/ml_genie/label/submit``"""
|
|
292
|
+
return self._t.call('mlgenieLabel', path={}, query={}, body=body)
|
|
293
|
+
|
|
294
|
+
def mlgenie_matrices(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
295
|
+
"""MLGenie: take the feature matrices. ``POST /api/v1/tasks/ml_genie/matrix/submit``"""
|
|
296
|
+
return self._t.call('mlgenieMatrices', path={}, query={}, body=body)
|
|
297
|
+
|
|
298
|
+
def submit_mlgenie(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
299
|
+
"""Submit an MLGenie run. ``POST /api/v1/tasks/ml_genie/submit``"""
|
|
300
|
+
return self._t.call('submitMLGenie', path={}, query={}, body=body)
|
|
301
|
+
|
|
302
|
+
def estimate_nf_core(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
303
|
+
"""Estimate an nf-core pipeline run. ``POST /api/v1/tasks/nfcore/cost_predict``"""
|
|
304
|
+
return self._t.call('estimateNfCore', path={}, query={}, body=body)
|
|
305
|
+
|
|
306
|
+
def submit_nf_core(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
307
|
+
"""Submit an nf-core pipeline run. ``POST /api/v1/tasks/nfcore/submit``"""
|
|
308
|
+
return self._t.call('submitNfCore', path={}, query={}, body=body)
|
|
309
|
+
|
|
310
|
+
def get_pipeline_config(self, *, pipeline_id: Any) -> Any:
|
|
311
|
+
"""A pipeline's parameters, as its form shows them. ``GET /api/v1/tasks/pipeline/config``"""
|
|
312
|
+
return self._t.call('getPipelineConfig', path={}, query={'pipeline_id': pipeline_id})
|
|
313
|
+
|
|
314
|
+
def estimate_pipeline(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
315
|
+
"""Estimate a built-in pipeline run. ``POST /api/v1/tasks/pipeline/cost_predict``"""
|
|
316
|
+
return self._t.call('estimatePipeline', path={}, query={}, body=body)
|
|
317
|
+
|
|
318
|
+
def list_pipelines(self, *, pipeline_type: Any = None) -> Any:
|
|
319
|
+
"""List the pipelines you can run. ``GET /api/v1/tasks/pipeline/release``"""
|
|
320
|
+
return self._t.call('listPipelines', path={}, query={'pipeline_type': pipeline_type})
|
|
321
|
+
|
|
322
|
+
def submit_pipeline(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
323
|
+
"""Submit a built-in pipeline run. ``POST /api/v1/tasks/pipeline/submit``"""
|
|
324
|
+
return self._t.call('submitPipeline', path={}, query={}, body=body)
|
|
325
|
+
|
|
326
|
+
def list_runs(self, *, project_uuid: Any = None, task_type: Any = None, status: Any = None, name: Any = None, created_after: Any = None, page: Any = None, limit: Any = None) -> Any:
|
|
327
|
+
"""List runs of every kind. ``GET /api/v1/tasks/runs``"""
|
|
328
|
+
return self._t.call('listRuns', path={}, query={'project_uuid': project_uuid, 'task_type': task_type, 'status': status, 'name': name, 'created_after': created_after, 'page': page, 'limit': limit})
|
|
329
|
+
|
|
330
|
+
def finish_upload(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
331
|
+
"""Assemble the parts into the file. ``POST /api/v1/upload/all_complete``"""
|
|
332
|
+
return self._t.call('finishUpload', path={}, query={}, body=body)
|
|
333
|
+
|
|
334
|
+
def cancel_upload(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
335
|
+
"""Abandon an unfinished upload and discard its parts. ``POST /api/v1/upload/cancel``"""
|
|
336
|
+
return self._t.call('cancelUpload', path={}, query={}, body=body)
|
|
337
|
+
|
|
338
|
+
def complete_part(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
339
|
+
"""Record a stored part. ``POST /api/v1/upload/chunk_complete``"""
|
|
340
|
+
return self._t.call('completePart', path={}, query={}, body=body)
|
|
341
|
+
|
|
342
|
+
def start_upload(self, *, filename: Any, file_hash: Any, total_chunks: Any) -> Any:
|
|
343
|
+
"""Register a file to upload, or resume one. ``GET /api/v1/upload/generate_upload_id``"""
|
|
344
|
+
return self._t.call('startUpload', path={}, query={'filename': filename, 'file_hash': file_hash, 'total_chunks': total_chunks})
|
|
345
|
+
|
|
346
|
+
def list_files(self, *, name: Any = None, page: Any = None, size: Any = None, sort_field: Any = None, sort_order: Any = None) -> Any:
|
|
347
|
+
"""List your files. ``GET /api/v1/upload/paginate_uploaded_files``"""
|
|
348
|
+
return self._t.call('listFiles', path={}, query={'name': name, 'page': page, 'size': size, 'sort_field': sort_field, 'sort_order': sort_order})
|
|
349
|
+
|
|
350
|
+
def sign_part(self, *, body: Optional[Dict[str, Any]] = None) -> Any:
|
|
351
|
+
"""Get a URL to PUT one part to. ``POST /api/v1/upload/signed_url``"""
|
|
352
|
+
return self._t.call('signPart', path={}, query={}, body=body)
|
|
@@ -0,0 +1,410 @@
|
|
|
1
|
+
"""The PromptBio client: an API key, the generated calls, and a few helpers for
|
|
2
|
+
the common path from a table to a finished analysis (PromptBio/Issues#1445)."""
|
|
3
|
+
import csv
|
|
4
|
+
import email.utils
|
|
5
|
+
import io
|
|
6
|
+
import os
|
|
7
|
+
import re
|
|
8
|
+
import time
|
|
9
|
+
from typing import Any, Dict, Iterable, List, Optional, Union
|
|
10
|
+
from urllib.parse import quote, urlsplit
|
|
11
|
+
|
|
12
|
+
import requests
|
|
13
|
+
from urllib3.exceptions import ReadTimeoutError
|
|
14
|
+
|
|
15
|
+
from ._api import API, OPERATIONS
|
|
16
|
+
|
|
17
|
+
DEFAULT_SERVER = "https://platform.promptbio.ai"
|
|
18
|
+
# Where the API sits under each PromptBio web host: the web app serves the site
|
|
19
|
+
# at the root and the API under a prefix. Another host is probed for it.
|
|
20
|
+
API_PREFIXES = {
|
|
21
|
+
"platform.promptbio.ai": "/prod-api",
|
|
22
|
+
"stage.promptbio.ai": "/stage-api",
|
|
23
|
+
"dev.promptbio.ai": "/dev-api",
|
|
24
|
+
}
|
|
25
|
+
# What the probe tries, in the promptbio CLI's order: the address as given (a
|
|
26
|
+
# backend reached directly), then each prefix the web app's proxy uses.
|
|
27
|
+
PROBED_PREFIXES = ("", "/prod-api", "/stage-api", "/dev-api")
|
|
28
|
+
FINISHED = ("done", "error", "stopped")
|
|
29
|
+
# What PromptBio takes as a run's name (nameCommonValidator on the server).
|
|
30
|
+
RUN_NAME = re.compile(r"[A-Za-z0-9_-]{1,50}")
|
|
31
|
+
# Retried with a growing wait: a GET on these statuses or a dropped connection,
|
|
32
|
+
# anything else only on 429 (the request was refused before it was handled).
|
|
33
|
+
# A submission that timed out or got a 5xx may have gone through, so it is not
|
|
34
|
+
# repeated.
|
|
35
|
+
RETRIED_GET_STATUSES = (429, 500, 502, 503, 504)
|
|
36
|
+
MAX_RETRY_WAIT = 60.0
|
|
37
|
+
# The server stages a table read as CSV whole before it sends the first byte,
|
|
38
|
+
# so the reply may take minutes; PromptBio's web proxy waits 10 minutes for
|
|
39
|
+
# it. A read that times out (or a 504 from the proxy) is not retried: the
|
|
40
|
+
# retry would stage the table again from the start.
|
|
41
|
+
TABLE_TIMEOUT = 600.0
|
|
42
|
+
TABLE_TOO_SLOW = ("the server prepares the whole table before sending it, and this one took too long. Download its "
|
|
43
|
+
"result files instead (pb.api.download_run_result), or, calling the API directly rather than "
|
|
44
|
+
"through PromptBio's web address, pass a longer table_timeout= to Client")
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class CSVReply(bytes):
|
|
48
|
+
"""A CSV reply's bytes, with its HTTP ``headers``."""
|
|
49
|
+
|
|
50
|
+
headers: Any = None
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class PromptBioError(Exception):
|
|
54
|
+
"""The API answered with an error: ``code`` is the reply's code (or the
|
|
55
|
+
HTTP status when there was no reply envelope) and ``message`` its reason."""
|
|
56
|
+
|
|
57
|
+
def __init__(self, code: int, message: str, operation: str = ""):
|
|
58
|
+
self.code, self.message, self.operation = code, message, operation
|
|
59
|
+
where = f"{operation}: " if operation else ""
|
|
60
|
+
super().__init__(f"{where}{message} (code {code})")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
class RunFailed(PromptBioError):
|
|
64
|
+
"""A run ended in error or was stopped. ``run`` is its detail."""
|
|
65
|
+
|
|
66
|
+
def __init__(self, run: Dict[str, Any]):
|
|
67
|
+
self.run = run
|
|
68
|
+
status = run.get("status", "")
|
|
69
|
+
super().__init__(0, f"run {run.get('uuid', '')} ended {status}: {run.get('failure_reason') or run.get('message') or ''}".strip())
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _server_address(server: str) -> str:
|
|
73
|
+
"""The address without a trailing slash, https:// when it names no scheme."""
|
|
74
|
+
server = server.strip().rstrip("/")
|
|
75
|
+
if "://" not in server:
|
|
76
|
+
server = "https://" + server
|
|
77
|
+
parts = urlsplit(server)
|
|
78
|
+
if parts.scheme not in ("http", "https") or not parts.hostname:
|
|
79
|
+
raise ValueError(f"{server!r} is not a server address; give one like {DEFAULT_SERVER}")
|
|
80
|
+
return server
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _healthy(session: Any, url: str, timeout: float) -> bool:
|
|
84
|
+
resp = session.request("GET", url, timeout=timeout)
|
|
85
|
+
if resp.status_code != 200:
|
|
86
|
+
return False
|
|
87
|
+
# The web app answers unknown paths with its page and a 200, so only the
|
|
88
|
+
# backend's own reply counts.
|
|
89
|
+
try:
|
|
90
|
+
reply = resp.json()
|
|
91
|
+
except ValueError:
|
|
92
|
+
return False
|
|
93
|
+
return isinstance(reply, dict) and reply.get("status") == "ok"
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def api_base(server: str, *, session: Any = None, timeout: float = 20.0) -> str:
|
|
97
|
+
"""The API's base URL for a PromptBio address (https:// when no scheme is
|
|
98
|
+
given): the address itself when it names a path (".../prod-api"), the
|
|
99
|
+
prefix of a known PromptBio host, else the first of the address and its
|
|
100
|
+
/prod-api, /stage-api and /dev-api whose /health the backend answers, as
|
|
101
|
+
the promptbio CLI finds it."""
|
|
102
|
+
server = _server_address(server)
|
|
103
|
+
parts = urlsplit(server)
|
|
104
|
+
if parts.path:
|
|
105
|
+
return server
|
|
106
|
+
if parts.hostname in API_PREFIXES:
|
|
107
|
+
return server + API_PREFIXES[parts.hostname]
|
|
108
|
+
session = session or requests.Session()
|
|
109
|
+
last: Optional[Exception] = None
|
|
110
|
+
for prefix in PROBED_PREFIXES:
|
|
111
|
+
try:
|
|
112
|
+
if _healthy(session, server + prefix + "/health", timeout):
|
|
113
|
+
return server + prefix
|
|
114
|
+
except requests.RequestException as e:
|
|
115
|
+
last = e
|
|
116
|
+
reason = f": {last}" if last else ""
|
|
117
|
+
raise PromptBioError(0, f"no PromptBio API answers at {server}{reason}", "api_base")
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _retry_after(resp: Any) -> Optional[float]:
|
|
121
|
+
"""The wait a Retry-After header asks for, in seconds or as an HTTP date."""
|
|
122
|
+
value = (getattr(resp, "headers", None) or {}).get("Retry-After")
|
|
123
|
+
if not value:
|
|
124
|
+
return None
|
|
125
|
+
try:
|
|
126
|
+
return max(0.0, float(value))
|
|
127
|
+
except ValueError:
|
|
128
|
+
pass
|
|
129
|
+
try:
|
|
130
|
+
when = email.utils.parsedate_to_datetime(value)
|
|
131
|
+
except (TypeError, ValueError):
|
|
132
|
+
return None
|
|
133
|
+
return max(0.0, when.timestamp() - time.time())
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def _timed_out(err: BaseException) -> bool:
|
|
137
|
+
"""Whether a request failed by waiting too long for the server: requests
|
|
138
|
+
raises ReadTimeout before the reply, ConnectionError during its body."""
|
|
139
|
+
if isinstance(err, requests.exceptions.ReadTimeout):
|
|
140
|
+
return True
|
|
141
|
+
return any(isinstance(a, ReadTimeoutError) for a in getattr(err, "args", ()))
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class _Transport:
|
|
145
|
+
def __init__(self, server: str, api_key: str, session: requests.Session, timeout: float, user_agent: str,
|
|
146
|
+
retries: int = 4, table_timeout: float = TABLE_TIMEOUT):
|
|
147
|
+
self.server, self.session, self.timeout, self.retries = server, session, timeout, retries
|
|
148
|
+
self.table_timeout = table_timeout
|
|
149
|
+
self._base: Optional[str] = None
|
|
150
|
+
self.headers = {"Authorization": f"Bearer {api_key}", "User-Agent": user_agent}
|
|
151
|
+
|
|
152
|
+
@property
|
|
153
|
+
def base(self) -> str:
|
|
154
|
+
"""The API's base URL, found on first use (api_base)."""
|
|
155
|
+
if self._base is None:
|
|
156
|
+
probe = 20.0 if self.timeout is None else min(self.timeout, 20.0)
|
|
157
|
+
self._base = api_base(self.server, session=self.session, timeout=probe)
|
|
158
|
+
return self._base
|
|
159
|
+
|
|
160
|
+
def send(self, method: str, url: str, *, table_read: bool = False, **kwargs: Any) -> Any:
|
|
161
|
+
"""One request, retried as RETRIED_GET_STATUSES says, waiting what
|
|
162
|
+
Retry-After asks or 1, 2, 4, 8 s. A GET is also retried when the
|
|
163
|
+
connection drops, before or during the reply. A table read is not
|
|
164
|
+
retried when it timed out or the proxy gave up on it (504), since the
|
|
165
|
+
server would stage the table again; it raises ReadTimeout instead."""
|
|
166
|
+
attempt = 0
|
|
167
|
+
while True:
|
|
168
|
+
try:
|
|
169
|
+
resp = self.session.request(method, url, **kwargs)
|
|
170
|
+
except (requests.ConnectionError, requests.Timeout, requests.exceptions.ChunkedEncodingError) as err:
|
|
171
|
+
# ChunkedEncodingError: the connection dropped while the body
|
|
172
|
+
# was read, or it ended short of its Content-Length.
|
|
173
|
+
if table_read and _timed_out(err):
|
|
174
|
+
if isinstance(err, requests.exceptions.ReadTimeout):
|
|
175
|
+
raise
|
|
176
|
+
raise requests.exceptions.ReadTimeout(err) from err
|
|
177
|
+
if method != "GET" or attempt >= self.retries:
|
|
178
|
+
raise
|
|
179
|
+
wait = None
|
|
180
|
+
else:
|
|
181
|
+
if table_read and resp.status_code == 504:
|
|
182
|
+
return resp
|
|
183
|
+
retried = resp.status_code == 429 or (method == "GET" and resp.status_code in RETRIED_GET_STATUSES)
|
|
184
|
+
if not retried or attempt >= self.retries:
|
|
185
|
+
return resp
|
|
186
|
+
wait = _retry_after(resp)
|
|
187
|
+
time.sleep(min(MAX_RETRY_WAIT, wait if wait is not None else 2.0 ** attempt))
|
|
188
|
+
attempt += 1
|
|
189
|
+
# An upload is read again from its start.
|
|
190
|
+
for f in (kwargs.get("files") or {}).values():
|
|
191
|
+
fh = f[1] if isinstance(f, tuple) else f
|
|
192
|
+
if hasattr(fh, "seek"):
|
|
193
|
+
fh.seek(0)
|
|
194
|
+
|
|
195
|
+
def call(self, operation: str, path: Dict[str, Any], query: Dict[str, Any], body: Any = None,
|
|
196
|
+
data: Optional[Dict[str, Any]] = None, files: Optional[Dict[str, Any]] = None) -> Any:
|
|
197
|
+
method, template, _, _, kind, response = OPERATIONS[operation]
|
|
198
|
+
url = template
|
|
199
|
+
for name, value in path.items():
|
|
200
|
+
if value is None or str(value) == "":
|
|
201
|
+
raise ValueError(f"{operation}: {name} is required")
|
|
202
|
+
url = url.replace(":" + name, quote(str(value), safe=""))
|
|
203
|
+
params = {k: v for k, v in query.items() if v is not None}
|
|
204
|
+
kwargs: Dict[str, Any] = {"params": params, "headers": self.headers, "timeout": self.timeout}
|
|
205
|
+
if kind == "json" and body is not None:
|
|
206
|
+
kwargs["json"] = body
|
|
207
|
+
elif kind == "multipart":
|
|
208
|
+
kwargs["data"], kwargs["files"] = data or {}, files or {}
|
|
209
|
+
if response == "csv":
|
|
210
|
+
# None, as for requests, waits as long as it takes.
|
|
211
|
+
read = None if self.timeout is None or self.table_timeout is None else max(self.timeout, self.table_timeout)
|
|
212
|
+
kwargs["timeout"] = (self.timeout, read)
|
|
213
|
+
try:
|
|
214
|
+
resp = self.send(method, self.base + url, table_read=True, **kwargs)
|
|
215
|
+
except requests.exceptions.ReadTimeout:
|
|
216
|
+
raise PromptBioError(0, f"no reply within {read:.0f} s: {TABLE_TOO_SLOW}", operation) from None
|
|
217
|
+
if resp.status_code == 504:
|
|
218
|
+
raise PromptBioError(504, f"HTTP 504, the proxy stopped waiting: {TABLE_TOO_SLOW}", operation)
|
|
219
|
+
else:
|
|
220
|
+
resp = self.send(method, self.base + url, **kwargs)
|
|
221
|
+
headers = getattr(resp, "headers", None) or {}
|
|
222
|
+
if response == "csv" and resp.status_code == 200 and (headers.get("Content-Type") or "").lower().startswith("text/csv"):
|
|
223
|
+
out = CSVReply(resp.content)
|
|
224
|
+
out.headers = headers
|
|
225
|
+
return out
|
|
226
|
+
try:
|
|
227
|
+
reply = resp.json()
|
|
228
|
+
except ValueError:
|
|
229
|
+
raise PromptBioError(resp.status_code, f"HTTP {resp.status_code}: {resp.text[:200]}", operation) from None
|
|
230
|
+
if not isinstance(reply, dict) or "code" not in reply:
|
|
231
|
+
raise PromptBioError(resp.status_code, f"HTTP {resp.status_code}: not a PromptBio reply", operation)
|
|
232
|
+
# Most errors still answer with HTTP 200: the envelope's code decides.
|
|
233
|
+
if reply.get("code") != 0:
|
|
234
|
+
raise PromptBioError(int(reply.get("code") or resp.status_code), str(reply.get("msg") or ""), operation)
|
|
235
|
+
return reply.get("data")
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
class Client:
|
|
239
|
+
"""A PromptBio API client.
|
|
240
|
+
|
|
241
|
+
``api_key`` defaults to ``PROMPTBIO_API_KEY`` and ``server`` to
|
|
242
|
+
``PROMPTBIO_SERVER``, else https://platform.promptbio.ai, as for the
|
|
243
|
+
promptbio CLI; an address with no scheme gets https://. Create a key under
|
|
244
|
+
Connections > API Keys; Access "Read and submit" is enough for everything
|
|
245
|
+
here.
|
|
246
|
+
|
|
247
|
+
A GET is retried on HTTP 429 and 5xx and on a dropped connection, any
|
|
248
|
+
other request only on 429, up to ``retries`` times. A result table read
|
|
249
|
+
waits up to ``table_timeout`` seconds for its reply, since the server
|
|
250
|
+
prepares the whole table first, and is not retried after that.
|
|
251
|
+
|
|
252
|
+
``client.api`` has every operation of the public API (generated from its
|
|
253
|
+
OpenAPI file); the methods below cover the usual path from a table to a
|
|
254
|
+
finished analysis.
|
|
255
|
+
"""
|
|
256
|
+
|
|
257
|
+
def __init__(self, api_key: Optional[str] = None, server: Optional[str] = None, *,
|
|
258
|
+
timeout: float = 60.0, retries: int = 4, table_timeout: float = TABLE_TIMEOUT,
|
|
259
|
+
session: Optional[requests.Session] = None):
|
|
260
|
+
from . import __version__
|
|
261
|
+
|
|
262
|
+
api_key = api_key or os.environ.get("PROMPTBIO_API_KEY", "")
|
|
263
|
+
if not api_key:
|
|
264
|
+
raise ValueError("No API key: pass api_key= or set PROMPTBIO_API_KEY (Connections > API Keys).")
|
|
265
|
+
self.server = _server_address(server or os.environ.get("PROMPTBIO_SERVER") or DEFAULT_SERVER)
|
|
266
|
+
self._transport = _Transport(self.server, api_key, session or requests.Session(), timeout,
|
|
267
|
+
f"promptbio-python/{__version__}", retries=retries, table_timeout=table_timeout)
|
|
268
|
+
self.api = API(self._transport)
|
|
269
|
+
|
|
270
|
+
@property
|
|
271
|
+
def base(self) -> str:
|
|
272
|
+
"""The API's base URL (api_base), found on first use."""
|
|
273
|
+
return self._transport.base
|
|
274
|
+
|
|
275
|
+
# -- inputs -------------------------------------------------------------
|
|
276
|
+
|
|
277
|
+
def upload_matrix(self, data: Any, *, project: str, feature_type: str, name: Optional[str] = None,
|
|
278
|
+
description: str = "", **fields: Any) -> str:
|
|
279
|
+
"""Register a Feature Store matrix from a CSV: a pandas DataFrame (written
|
|
280
|
+
with its index as the first column when it is named, else without),
|
|
281
|
+
a path, or bytes. A row per sample, its first column the sample ID
|
|
282
|
+
(``features_as_rows=True`` for the transpose). Returns the matrix's
|
|
283
|
+
uuid."""
|
|
284
|
+
if hasattr(data, "to_csv"):
|
|
285
|
+
index = getattr(data.index, "name", None) is not None
|
|
286
|
+
payload = data.to_csv(index=index).encode()
|
|
287
|
+
filename = f"{name or 'matrix'}.csv"
|
|
288
|
+
elif isinstance(data, (bytes, bytearray)):
|
|
289
|
+
payload, filename = bytes(data), f"{name or 'matrix'}.csv"
|
|
290
|
+
else:
|
|
291
|
+
with open(data, "rb") as f:
|
|
292
|
+
payload = f.read()
|
|
293
|
+
filename = os.path.basename(str(data))
|
|
294
|
+
form = {"project_uuid": project, "feature_type": feature_type, "description": description, **fields}
|
|
295
|
+
if name:
|
|
296
|
+
form["feature_matrix_name"] = name
|
|
297
|
+
reply = self.api.register_matrix(data=form, files={"file": (filename, io.BytesIO(payload), "text/csv")})
|
|
298
|
+
return reply.get("uuid") if isinstance(reply, dict) else reply
|
|
299
|
+
|
|
300
|
+
# -- runs ---------------------------------------------------------------
|
|
301
|
+
|
|
302
|
+
def submit_analysis(self, analysis: str, *, name: str, project: str, params: Dict[str, Any],
|
|
303
|
+
description: str = "", version: Optional[str] = None) -> str:
|
|
304
|
+
"""Submit an analysis run (``de``, ``gsea``, ``gc``, ``scc``, ``ca``) with
|
|
305
|
+
the analysis form's fields as ``params``. Returns the run's uuid. A run
|
|
306
|
+
name has letters, numbers, hyphens and underscores only, up to 50."""
|
|
307
|
+
if not RUN_NAME.fullmatch(name or ""):
|
|
308
|
+
raise ValueError(f"run name {name!r}: PromptBio takes letters, numbers, hyphens and underscores, "
|
|
309
|
+
"no spaces, up to 50 characters")
|
|
310
|
+
body: Dict[str, Any] = {"analyses_type": analysis, "name": name, "project_id": project,
|
|
311
|
+
"description": description or name, "params": params}
|
|
312
|
+
if version:
|
|
313
|
+
body["version"] = version
|
|
314
|
+
return _run_uuid(self.api.submit_analysis(body=body), "submit_analysis")
|
|
315
|
+
|
|
316
|
+
def submit_differential_analysis(self, *, name: str, project: str, feature_matrix: str, design_matrix: str,
|
|
317
|
+
label_column: str, case: Union[str, Iterable[str]],
|
|
318
|
+
control: Union[str, Iterable[str]], method: str = "DESeq2",
|
|
319
|
+
data_type: str = "count", species: str = "human", **params: Any) -> str:
|
|
320
|
+
"""Submit a differential analysis of ``case`` against ``control``, the
|
|
321
|
+
values of ``label_column`` in the design matrix. ``species`` (human or
|
|
322
|
+
mouse, as on the form) says how the feature IDs are read; the run
|
|
323
|
+
fails without one. Further form fields (``pval``, ``fold_change``,
|
|
324
|
+
``covariate``, ...) pass through."""
|
|
325
|
+
def labels(v):
|
|
326
|
+
return [v] if isinstance(v, str) else list(v)
|
|
327
|
+
fields = {"analysis_type": data_type, "method": method, "feature_matrix_id": feature_matrix,
|
|
328
|
+
"label_matrix_id": design_matrix, "label_column": label_column,
|
|
329
|
+
"treat_label": labels(case), "ctrl_label": labels(control), "species": species, **params}
|
|
330
|
+
return self.submit_analysis("de", name=name, project=project, params=fields)
|
|
331
|
+
|
|
332
|
+
def run(self, run: str) -> Dict[str, Any]:
|
|
333
|
+
"""A run's status and details."""
|
|
334
|
+
return self.api.get_run(run) or {}
|
|
335
|
+
|
|
336
|
+
def wait(self, run: str, *, timeout: Optional[float] = None, poll: float = 30.0,
|
|
337
|
+
raise_on_failure: bool = True) -> Dict[str, Any]:
|
|
338
|
+
"""Wait until a run finishes and return its detail. A run that ends in
|
|
339
|
+
error or is stopped raises RunFailed unless ``raise_on_failure`` is off."""
|
|
340
|
+
deadline = None if timeout is None else time.monotonic() + timeout
|
|
341
|
+
while True:
|
|
342
|
+
detail = self.run(run)
|
|
343
|
+
status = detail.get("status")
|
|
344
|
+
if status in FINISHED:
|
|
345
|
+
if status != "done" and raise_on_failure:
|
|
346
|
+
raise RunFailed({"uuid": run, **detail})
|
|
347
|
+
return detail
|
|
348
|
+
if deadline is not None and time.monotonic() >= deadline:
|
|
349
|
+
raise TimeoutError(f"run {run} is still {status} after {timeout} s")
|
|
350
|
+
time.sleep(poll)
|
|
351
|
+
|
|
352
|
+
# -- results ------------------------------------------------------------
|
|
353
|
+
|
|
354
|
+
def result_tables(self, run: str) -> List[Dict[str, Any]]:
|
|
355
|
+
"""The run's result tables, as the result catalogue describes them: name,
|
|
356
|
+
columns with their types, files and row counts."""
|
|
357
|
+
return (self.api.list_run_result_tables(run) or {}).get("tables") or []
|
|
358
|
+
|
|
359
|
+
def read_table(self, run: str, table: str):
|
|
360
|
+
"""Read one result table into a pandas DataFrame: every file it spans,
|
|
361
|
+
under the catalogue's column names (``result_tables`` lists a run's
|
|
362
|
+
tables), typed as the catalogue says (int as Int64, float, bool as
|
|
363
|
+
boolean, string). A missing value is <NA>, or NaN in a float column."""
|
|
364
|
+
import pandas as pd
|
|
365
|
+
|
|
366
|
+
raw = self.api.read_run_result_table(run, table)
|
|
367
|
+
headers = getattr(raw, "headers", None) or {}
|
|
368
|
+
names = next(csv.reader([raw.split(b"\n", 1)[0].decode("utf-8-sig").rstrip("\r")]), [])
|
|
369
|
+
if headers.get("X-Column-Types"):
|
|
370
|
+
types = dict(zip(names, (t.strip() for t in headers["X-Column-Types"].split(","))))
|
|
371
|
+
else:
|
|
372
|
+
# A server from before X-Column-Types: the catalogue says.
|
|
373
|
+
types = {c.get("name"): c.get("type") for t in self.result_tables(run) if t.get("name") == table
|
|
374
|
+
for c in t.get("columns") or []}
|
|
375
|
+
dtypes = {"float": "float64", "bool": "boolean"}
|
|
376
|
+
# Every column is parsed by pandas from the text: a string as written,
|
|
377
|
+
# so a gene named NA or a sample ID with leading zeros keeps its
|
|
378
|
+
# spelling. An empty field is a missing value, and so is NaN in a
|
|
379
|
+
# float column. Ints are read as text and converted below.
|
|
380
|
+
frame = pd.read_csv(io.BytesIO(raw), dtype={n: dtypes.get(types.get(n), "string") for n in names},
|
|
381
|
+
keep_default_na=False,
|
|
382
|
+
na_values={n: ["", "NaN"] if types.get(n) == "float" else [""] for n in names},
|
|
383
|
+
# A row whose one field is empty is a blank line, not nothing.
|
|
384
|
+
skip_blank_lines=False)
|
|
385
|
+
for n in names:
|
|
386
|
+
if types.get(n) == "int":
|
|
387
|
+
# Straight from the text to int64 under a mask: read_csv's
|
|
388
|
+
# Int64 goes through float on older pandas, past 2**53 inexact.
|
|
389
|
+
text = frame[n]
|
|
390
|
+
mask = text.isna().to_numpy()
|
|
391
|
+
values = text.fillna("0").to_numpy(dtype=object).astype("int64")
|
|
392
|
+
frame[n] = pd.arrays.IntegerArray(values, mask)
|
|
393
|
+
expected = headers.get("X-Row-Count")
|
|
394
|
+
if expected is not None and str(expected).isdigit() and int(expected) != len(frame):
|
|
395
|
+
raise PromptBioError(0, f"table {table!r} came back with {len(frame)} of its {expected} rows; read it again",
|
|
396
|
+
"read_table")
|
|
397
|
+
return frame
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
def _run_uuid(reply: Any, operation: str) -> str:
|
|
401
|
+
"""The new run's uuid from a submission's reply, which is the uuid itself or
|
|
402
|
+
an object holding it, as the promptbio CLI reads it."""
|
|
403
|
+
if isinstance(reply, str) and reply:
|
|
404
|
+
return reply
|
|
405
|
+
if isinstance(reply, dict):
|
|
406
|
+
for key in ("task_uuid", "uuid", "task_id", "id"):
|
|
407
|
+
value = reply.get(key)
|
|
408
|
+
if isinstance(value, str) and value:
|
|
409
|
+
return value
|
|
410
|
+
raise PromptBioError(0, f"the reply names no run: {reply!r}", operation)
|