qupai-lab 0.2.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.
- qupai_lab-0.2.0/LICENSE +21 -0
- qupai_lab-0.2.0/MANIFEST.in +2 -0
- qupai_lab-0.2.0/PKG-INFO +219 -0
- qupai_lab-0.2.0/README.md +202 -0
- qupai_lab-0.2.0/pyproject.toml +37 -0
- qupai_lab-0.2.0/setup.cfg +4 -0
- qupai_lab-0.2.0/src/qupai_lab/__init__.py +16 -0
- qupai_lab-0.2.0/src/qupai_lab/__main__.py +3 -0
- qupai_lab-0.2.0/src/qupai_lab/changes.py +63 -0
- qupai_lab-0.2.0/src/qupai_lab/cli.py +94 -0
- qupai_lab-0.2.0/src/qupai_lab/config.py +152 -0
- qupai_lab-0.2.0/src/qupai_lab/errors.py +56 -0
- qupai_lab-0.2.0/src/qupai_lab/lab.py +600 -0
- qupai_lab-0.2.0/src/qupai_lab/metric.py +26 -0
- qupai_lab-0.2.0/src/qupai_lab/record.py +86 -0
- qupai_lab-0.2.0/src/qupai_lab/runner.py +269 -0
- qupai_lab-0.2.0/src/qupai_lab/stop.py +107 -0
- qupai_lab-0.2.0/src/qupai_lab.egg-info/PKG-INFO +219 -0
- qupai_lab-0.2.0/src/qupai_lab.egg-info/SOURCES.txt +20 -0
- qupai_lab-0.2.0/src/qupai_lab.egg-info/dependency_links.txt +1 -0
- qupai_lab-0.2.0/src/qupai_lab.egg-info/entry_points.txt +2 -0
- qupai_lab-0.2.0/src/qupai_lab.egg-info/top_level.txt +1 -0
qupai_lab-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 QuSpect
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
qupai_lab-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: qupai-lab
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: The QuPai Lab SDK: work a QuPai lab's instruments from Python scripts through InstruCore's REST API.
|
|
5
|
+
Author: QuSpect
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/QuSpect/qupai-lab-plugin
|
|
8
|
+
Project-URL: Repository, https://github.com/QuSpect/qupai-lab-plugin
|
|
9
|
+
Keywords: qupai,lab,instruments,instrucore
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Topic :: Scientific/Engineering
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Dynamic: license-file
|
|
17
|
+
|
|
18
|
+
# QuPai Lab SDK (`qupai-lab`)
|
|
19
|
+
|
|
20
|
+
Work a QuPai lab's instruments from Python: the lab's machines, sessions on simulated copies, instruments by
|
|
21
|
+
role, the files an experiment keeps, and live runs in the lab's queue. It calls InstruCore's own REST API (not
|
|
22
|
+
MCP), so one script runs in a QuPai lab project's sandbox and at the lab PC. Python 3.10 or later, standard
|
|
23
|
+
library only.
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
pip install qupai-lab
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
A QuPai sandbox has it already. From a checkout of this repository instead: `pip install ./sdk/python`.
|
|
32
|
+
|
|
33
|
+
**Releasing.** A tag `sdk-vX.Y.Z` on this repository, equal to `qupai_lab.__version__`, runs
|
|
34
|
+
`.github/workflows/sdk-release.yml`: it tests the SDK on Python 3.10 and 3.13, builds the sdist and the wheel, checks
|
|
35
|
+
the tag against them, and publishes to PyPI through Trusted Publishing (no token is kept anywhere).
|
|
36
|
+
|
|
37
|
+
Then check that this sandbox (or PC) reaches its lab:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
$ qupai-lab machines
|
|
41
|
+
Lab http://door.example/lab/lab-sim
|
|
42
|
+
MACHINE KIND STATE INSTRUMENTS BY ROLE
|
|
43
|
+
signal-bench-sim pool 3 of 4 free
|
|
44
|
+
signal-bench-sim-1 simulated free generator=signal_bench_sim_1_generator, scope=signal_bench_sim_1_scope
|
|
45
|
+
…
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`qupai-lab machines --json` prints the same as JSON; `qupai-lab --version` the version.
|
|
49
|
+
|
|
50
|
+
## Where the lab is
|
|
51
|
+
|
|
52
|
+
`Lab.from_env()` reads `QUPAI_LAB_URL` and `QUPAI_LAB_KEY` from the environment, else from the nearest `.env` up
|
|
53
|
+
from the working directory, else from `/workspace/project/.env`. In a QuPai lab project the project's `.env`
|
|
54
|
+
holds both: the lab's address at the sandbox door and the project key. At a lab PC, give InstruCore's address and
|
|
55
|
+
a local key: `Lab("http://127.0.0.1:59220", "ick_…")`.
|
|
56
|
+
|
|
57
|
+
## A script
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
import sys
|
|
61
|
+
from qupai_lab import Lab
|
|
62
|
+
|
|
63
|
+
lab = Lab.from_env(record="calls.jsonl")
|
|
64
|
+
with lab.machine(sys.argv[1]) as m: # a pool: holds a free copy, or waits in its queue for one
|
|
65
|
+
gen, scope = m.role("generator"), m.role("scope")
|
|
66
|
+
rows = []
|
|
67
|
+
for f in [100, 300, 1e3, 3e3, 1e4, 3e4, 1e5]:
|
|
68
|
+
gen.write("set_waveform", channel=1, shape="sine", frequency_hz=f, amplitude_v=1.0)
|
|
69
|
+
scope.write("set_timebase", scale_s=0.5 / f, offset_s=0.0)
|
|
70
|
+
trace = scope.read("acquire", channel=1, points=2000)
|
|
71
|
+
rows.append({"frequency_hz": f, **lab.save(f"data/raw/trace_{f:g}.json", trace)})
|
|
72
|
+
lab.table("data/response.csv", rows)
|
|
73
|
+
lab.changes("changes.json") # the writes above, for a live run's card
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`python run.py signal-bench-sim` runs it on a simulated copy. The roles are the machine's: `qupai-lab machines`
|
|
77
|
+
lists them. A script addresses instruments by role, so the same script works on any copy of a pool and on the
|
|
78
|
+
machine the pool simulates, when their roles have the same names.
|
|
79
|
+
|
|
80
|
+
| Call | What it does |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| `lab.machines()` | Each live machine and simulated copy: `id` (public id), `internal_id`, `name`, `kind`, `state`, `status`, `pool`, `roles` (role → instrument id) |
|
|
83
|
+
| `lab.machine(id, *, purpose="", wait_s=None)` | A machine for a `with` block (below) |
|
|
84
|
+
| `m.role(name)` | The instrument in that role |
|
|
85
|
+
| `inst.read(op, **args)` | A read op; answers its result. Anyone may read |
|
|
86
|
+
| `inst.write(op, **args)` | A write op in the machine's session; the lab checks its limits first |
|
|
87
|
+
| `inst.check(op, **args)` | Would this write pass policy, arguments and limits? `{"ok": true, "kind": "write"}` or the refusal, without a session |
|
|
88
|
+
| `inst.reference()`, `m.reference()` | The reference document (`mhs-reference/0`): ops, units, limits, notes |
|
|
89
|
+
| `m.renew()` | Restarts the held session's time limit, unless someone waits |
|
|
90
|
+
| `lab.save(path, value, **meta)` | Writes `value` as JSON (folders made as needed); answers `{"file": path, **meta}` |
|
|
91
|
+
| `lab.table(path, rows)` | Writes a list of dicts as CSV; answers `{"file": path, "rows": n}` |
|
|
92
|
+
| `lab.changes(path)` | Writes the writes made through this `Lab` as JSON (below) and answers it |
|
|
93
|
+
| `lab.request(method, path, body)` | Any other InstruCore route, with the same headers, record and errors |
|
|
94
|
+
|
|
95
|
+
## What holds a machine
|
|
96
|
+
|
|
97
|
+
| `lab.machine(…)` names | In the `with` block |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| A simulated pool (`signal-bench-sim`) | A free copy is held for the block. When none is free the block waits in the pool's queue, asking again when a copy is offered; `wait_s` gives up and leaves the queue. The copy is released at the block's end, also when the block raises, and reset for the next user |
|
|
100
|
+
| One simulated copy (`signal-bench-sim-2`) | That copy, the same way |
|
|
101
|
+
| The run's live machine, inside a [live run](#live-runs) (`QUPAI_LAB_RUN_MACHINE`, by id or public id) | Held for the block: `POST sessions` with `{"purpose": "run <run id>", "queue": true}`. While others hold or wait for it, the block waits in the machine's queue and asks again when it is offered; the lab holds it for the run's longest time. Released at the block's end, as a copy is |
|
|
102
|
+
| Any other live machine (`signal-bench`) | Nothing is held. The member holds a live machine, in the conversation; the lab answers a script's session there with `RUN_REQUIRED` and a write the member did not allow with `APPROVAL_REQUIRED` |
|
|
103
|
+
|
|
104
|
+
Code holds a live machine only as a run the member approved. Rehearse on a copy first.
|
|
105
|
+
|
|
106
|
+
SIGTERM and SIGINT while a block holds a machine (a copy, or a run's live machine) release it before the script
|
|
107
|
+
exits: the first one raises `SystemExit(143)` (SIGTERM) or `KeyboardInterrupt` (SIGINT) in the block, the block's
|
|
108
|
+
end releases the session with the reason `qupai-lab: stopped by SIGTERM`, and a request still in the queue is
|
|
109
|
+
withdrawn. A signal that comes while a session starts or ends waits until that call is done; a repeat while the
|
|
110
|
+
script stops is ignored. The handlers are installed when the block starts and the script's own are back at its
|
|
111
|
+
end (a signal the script ignores stays ignored). Only the main thread installs them.
|
|
112
|
+
|
|
113
|
+
## The record and `changes.json`
|
|
114
|
+
|
|
115
|
+
`record` (a path) gets one JSON line per call, appended: `time`, `method`, `path`, `args`, `ok`, `status`,
|
|
116
|
+
`code` (the error code, or null), `message` on a refusal, `req_id`, and for an op call `machine`, `role`,
|
|
117
|
+
`instrument`, `kind` and `op`. A successful call's line carries its `result`, or `file` when the script saved that
|
|
118
|
+
result with `lab.save` straight after the call. The line of a call that answered a dict or a list is written with
|
|
119
|
+
the next call (or at the block's end), so it can name the file.
|
|
120
|
+
|
|
121
|
+
`lab.changes(path)` groups the writes by role and op: one numeric argument that moved is a range, several a box,
|
|
122
|
+
the rest fixed. `channel` never moves: each channel is its own change.
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{"script": "experiments/2026-11-21-frequency-response/run.py@3f2a91c", "machines": ["signal-bench-sim-1"],
|
|
126
|
+
"changes": [
|
|
127
|
+
{"role": "generator", "op": "set_waveform", "calls": 7, "quantity": "frequency_hz", "min": 100, "max": 100000.0,
|
|
128
|
+
"fixed": {"channel": 1, "shape": "sine", "amplitude_v": 1.0}},
|
|
129
|
+
{"role": "scope", "op": "set_timebase", "calls": 7, "quantity": "scale_s", "min": 5e-06, "max": 0.005,
|
|
130
|
+
"fixed": {"offset_s": 0.0}}]}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
A box reads `"ranges": {"x": [min, max], "y": [min, max]}` in place of `quantity`, `min` and `max`.
|
|
134
|
+
|
|
135
|
+
Every request sends `Authorization: Bearer <key>` and `X-InstruCore-Script: <script>@<commit>`: the running
|
|
136
|
+
script's path in its git repository and the short commit, so the lab's record shows the code behind each call.
|
|
137
|
+
Outside a git repository the header is left out; `Lab(…, script_ref="…")` sets it, `script_ref=""` sends none.
|
|
138
|
+
|
|
139
|
+
## Live runs
|
|
140
|
+
|
|
141
|
+
When the member approves a live run (QuPai's `lab_run`, or Run on an experiment folder), QuPai writes the run's key
|
|
142
|
+
file into the place's repository and starts, in the repository's root:
|
|
143
|
+
|
|
144
|
+
```
|
|
145
|
+
qupai-lab run --key-file .qupai/runs/<run>/key.env --commit <sha> experiments/2026-11-21-freq signal-bench
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
1. It reads `QUPAI_LAB_URL`, `QUPAI_LAB_KEY` (the run's key), `QUPAI_LAB_RUN` (the run's id) and
|
|
149
|
+
`QUPAI_LAB_RUN_MACHINE` from the key file (`KEY=VALUE` lines) and deletes it at once, whatever it holds. The
|
|
150
|
+
machine must be the one named on the command line.
|
|
151
|
+
2. It checks the commit out into `/tmp/qupai-run-<run>` (`git worktree add --detach`, in the repository found from
|
|
152
|
+
the working directory). The experiment folder's committed `data/`, `figures/`, `calls.jsonl` and
|
|
153
|
+
`changes.json` (a rehearsal's) are removed from that checkout, so what the run keeps is its own.
|
|
154
|
+
3. It runs `python run.py <machine>` in `<checkout>/<experiment>` with the Python it runs in, with the four
|
|
155
|
+
settings in place of any other `QUPAI_*` variable and `PYTHONUNBUFFERED=1`. The script's output is the
|
|
156
|
+
command's own, as it is printed. The script's `Lab.from_env()` gets the run's key, and `lab.machine(<machine>)`
|
|
157
|
+
holds the live machine (above).
|
|
158
|
+
4. When the script ends it copies the `data/`, `figures/`, `calls.jsonl` and `changes.json` the script left to
|
|
159
|
+
`<experiment>/runs/<run>/` in the repository, and removes the checkout, also when the script failed.
|
|
160
|
+
5. It exits with the script's exit code (128 + the signal's number when a signal ended the script).
|
|
161
|
+
|
|
162
|
+
SIGTERM and SIGINT are passed to the script, which releases the machine and exits; a script that has not ended
|
|
163
|
+
20 s later is killed. What it left is still copied and the checkout removed. A run that cannot start (a key file
|
|
164
|
+
without the four settings, another machine, no repository, no such commit, no `run.py` in the experiment at that
|
|
165
|
+
commit) says why on stderr and exits with 2, after deleting the key file.
|
|
166
|
+
|
|
167
|
+
### Points for QuPai (`QUPAI_METRIC`)
|
|
168
|
+
|
|
169
|
+
Inside a run (`QUPAI_LAB_RUN` set) the SDK prints the run's progress on stdout as lines QuPai's Runtime takes from
|
|
170
|
+
a background job's output, one point each:
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
QUPAI_METRIC {"key": "queue_position", "value": 2}
|
|
174
|
+
QUPAI_METRIC {"key": "held", "value": 1}
|
|
175
|
+
QUPAI_METRIC {"key": "calls", "value": 14}
|
|
176
|
+
QUPAI_METRIC {"key": "held", "value": 0}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
| Key | When |
|
|
180
|
+
| --- | --- |
|
|
181
|
+
| `queue_position` | The request's position in the machine's queue, when it is queued and each time it moves |
|
|
182
|
+
| `held` | 1 when the session starts, 0 when it is released |
|
|
183
|
+
| `calls` | The instrument calls made so far (reads, writes and checks, refused ones too), at most every 5 s, and when the session is released and the script exits |
|
|
184
|
+
|
|
185
|
+
Outside a run nothing is printed on stdout.
|
|
186
|
+
|
|
187
|
+
## Errors
|
|
188
|
+
|
|
189
|
+
A refusal raises `LabError`, with `code`, `message` (the lab's sentence as it sent it), `detail` and `status`
|
|
190
|
+
(the HTTP status, 0 when no answer came). It reads InstruCore's `{"error": {code, message, detail}}` and the QuPai
|
|
191
|
+
gateway's problem documents (`urn:qupai:problem:rate` becomes `RATE`, `invalid-key` `INVALID_KEY`). A 429 waits
|
|
192
|
+
for `Retry-After` (2 s without one) and asks again, up to 5 times.
|
|
193
|
+
|
|
194
|
+
| Code | What it means |
|
|
195
|
+
| --- | --- |
|
|
196
|
+
| `LIMIT_EXCEEDED`, `POLICY_DENIED`, `FORBIDDEN` | The lab refuses this value or op. Save what you have and report the limit; never retry with another value or through another op |
|
|
197
|
+
| `APPROVAL_REQUIRED` | A write on a live machine the member has not allowed |
|
|
198
|
+
| `RUN_REQUIRED` | A script asked to hold a live machine: only a run the member approved holds one |
|
|
199
|
+
| `SESSION_REQUIRED`, `MACHINE_IN_SESSION` | The write needs your session on that machine, or someone else holds it |
|
|
200
|
+
| `INVALID_KEY`, `FORBIDDEN`, `RATE`, `UNAVAILABLE` (the gateway's) | The key, your role on the lab, too many calls, the lab not reachable through QuPai |
|
|
201
|
+
| `UNREACHABLE`, `NOT_CONFIGURED` | No answer from the address; no address or key found |
|
|
202
|
+
| `UNKNOWN_ROLE`, `NOT_HELD`, `WAIT_TIMEOUT`, `REQUEST_EXPIRED`, `REQUEST_CANCELLED` | The SDK's own: no such role, the machine used outside `with`, no copy offered in `wait_s`, the queue request ended |
|
|
203
|
+
|
|
204
|
+
## Tests
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
cd sdk/python
|
|
208
|
+
python3 -m venv .venv && .venv/bin/pip install -e . pytest
|
|
209
|
+
.venv/bin/pytest -q
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
They run against a fake InstruCore in a thread; `qupai-lab run`'s tests make git repositories under the test's
|
|
213
|
+
temporary folder and checkouts in `/tmp/qupai-run-<run>`, and send signals to scripts in subprocesses. `tests/test_integration.py` also runs against a real InstruCore
|
|
214
|
+
with a simulated pool when `QUPAI_LAB_IT_URL` and `QUPAI_LAB_IT_KEY` (a read-write key) are set;
|
|
215
|
+
`QUPAI_LAB_IT_POOL` picks the pool.
|
|
216
|
+
|
|
217
|
+
## License
|
|
218
|
+
|
|
219
|
+
MIT
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# QuPai Lab SDK (`qupai-lab`)
|
|
2
|
+
|
|
3
|
+
Work a QuPai lab's instruments from Python: the lab's machines, sessions on simulated copies, instruments by
|
|
4
|
+
role, the files an experiment keeps, and live runs in the lab's queue. It calls InstruCore's own REST API (not
|
|
5
|
+
MCP), so one script runs in a QuPai lab project's sandbox and at the lab PC. Python 3.10 or later, standard
|
|
6
|
+
library only.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
pip install qupai-lab
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
A QuPai sandbox has it already. From a checkout of this repository instead: `pip install ./sdk/python`.
|
|
15
|
+
|
|
16
|
+
**Releasing.** A tag `sdk-vX.Y.Z` on this repository, equal to `qupai_lab.__version__`, runs
|
|
17
|
+
`.github/workflows/sdk-release.yml`: it tests the SDK on Python 3.10 and 3.13, builds the sdist and the wheel, checks
|
|
18
|
+
the tag against them, and publishes to PyPI through Trusted Publishing (no token is kept anywhere).
|
|
19
|
+
|
|
20
|
+
Then check that this sandbox (or PC) reaches its lab:
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
$ qupai-lab machines
|
|
24
|
+
Lab http://door.example/lab/lab-sim
|
|
25
|
+
MACHINE KIND STATE INSTRUMENTS BY ROLE
|
|
26
|
+
signal-bench-sim pool 3 of 4 free
|
|
27
|
+
signal-bench-sim-1 simulated free generator=signal_bench_sim_1_generator, scope=signal_bench_sim_1_scope
|
|
28
|
+
…
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
`qupai-lab machines --json` prints the same as JSON; `qupai-lab --version` the version.
|
|
32
|
+
|
|
33
|
+
## Where the lab is
|
|
34
|
+
|
|
35
|
+
`Lab.from_env()` reads `QUPAI_LAB_URL` and `QUPAI_LAB_KEY` from the environment, else from the nearest `.env` up
|
|
36
|
+
from the working directory, else from `/workspace/project/.env`. In a QuPai lab project the project's `.env`
|
|
37
|
+
holds both: the lab's address at the sandbox door and the project key. At a lab PC, give InstruCore's address and
|
|
38
|
+
a local key: `Lab("http://127.0.0.1:59220", "ick_…")`.
|
|
39
|
+
|
|
40
|
+
## A script
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
import sys
|
|
44
|
+
from qupai_lab import Lab
|
|
45
|
+
|
|
46
|
+
lab = Lab.from_env(record="calls.jsonl")
|
|
47
|
+
with lab.machine(sys.argv[1]) as m: # a pool: holds a free copy, or waits in its queue for one
|
|
48
|
+
gen, scope = m.role("generator"), m.role("scope")
|
|
49
|
+
rows = []
|
|
50
|
+
for f in [100, 300, 1e3, 3e3, 1e4, 3e4, 1e5]:
|
|
51
|
+
gen.write("set_waveform", channel=1, shape="sine", frequency_hz=f, amplitude_v=1.0)
|
|
52
|
+
scope.write("set_timebase", scale_s=0.5 / f, offset_s=0.0)
|
|
53
|
+
trace = scope.read("acquire", channel=1, points=2000)
|
|
54
|
+
rows.append({"frequency_hz": f, **lab.save(f"data/raw/trace_{f:g}.json", trace)})
|
|
55
|
+
lab.table("data/response.csv", rows)
|
|
56
|
+
lab.changes("changes.json") # the writes above, for a live run's card
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`python run.py signal-bench-sim` runs it on a simulated copy. The roles are the machine's: `qupai-lab machines`
|
|
60
|
+
lists them. A script addresses instruments by role, so the same script works on any copy of a pool and on the
|
|
61
|
+
machine the pool simulates, when their roles have the same names.
|
|
62
|
+
|
|
63
|
+
| Call | What it does |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| `lab.machines()` | Each live machine and simulated copy: `id` (public id), `internal_id`, `name`, `kind`, `state`, `status`, `pool`, `roles` (role → instrument id) |
|
|
66
|
+
| `lab.machine(id, *, purpose="", wait_s=None)` | A machine for a `with` block (below) |
|
|
67
|
+
| `m.role(name)` | The instrument in that role |
|
|
68
|
+
| `inst.read(op, **args)` | A read op; answers its result. Anyone may read |
|
|
69
|
+
| `inst.write(op, **args)` | A write op in the machine's session; the lab checks its limits first |
|
|
70
|
+
| `inst.check(op, **args)` | Would this write pass policy, arguments and limits? `{"ok": true, "kind": "write"}` or the refusal, without a session |
|
|
71
|
+
| `inst.reference()`, `m.reference()` | The reference document (`mhs-reference/0`): ops, units, limits, notes |
|
|
72
|
+
| `m.renew()` | Restarts the held session's time limit, unless someone waits |
|
|
73
|
+
| `lab.save(path, value, **meta)` | Writes `value` as JSON (folders made as needed); answers `{"file": path, **meta}` |
|
|
74
|
+
| `lab.table(path, rows)` | Writes a list of dicts as CSV; answers `{"file": path, "rows": n}` |
|
|
75
|
+
| `lab.changes(path)` | Writes the writes made through this `Lab` as JSON (below) and answers it |
|
|
76
|
+
| `lab.request(method, path, body)` | Any other InstruCore route, with the same headers, record and errors |
|
|
77
|
+
|
|
78
|
+
## What holds a machine
|
|
79
|
+
|
|
80
|
+
| `lab.machine(…)` names | In the `with` block |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| A simulated pool (`signal-bench-sim`) | A free copy is held for the block. When none is free the block waits in the pool's queue, asking again when a copy is offered; `wait_s` gives up and leaves the queue. The copy is released at the block's end, also when the block raises, and reset for the next user |
|
|
83
|
+
| One simulated copy (`signal-bench-sim-2`) | That copy, the same way |
|
|
84
|
+
| The run's live machine, inside a [live run](#live-runs) (`QUPAI_LAB_RUN_MACHINE`, by id or public id) | Held for the block: `POST sessions` with `{"purpose": "run <run id>", "queue": true}`. While others hold or wait for it, the block waits in the machine's queue and asks again when it is offered; the lab holds it for the run's longest time. Released at the block's end, as a copy is |
|
|
85
|
+
| Any other live machine (`signal-bench`) | Nothing is held. The member holds a live machine, in the conversation; the lab answers a script's session there with `RUN_REQUIRED` and a write the member did not allow with `APPROVAL_REQUIRED` |
|
|
86
|
+
|
|
87
|
+
Code holds a live machine only as a run the member approved. Rehearse on a copy first.
|
|
88
|
+
|
|
89
|
+
SIGTERM and SIGINT while a block holds a machine (a copy, or a run's live machine) release it before the script
|
|
90
|
+
exits: the first one raises `SystemExit(143)` (SIGTERM) or `KeyboardInterrupt` (SIGINT) in the block, the block's
|
|
91
|
+
end releases the session with the reason `qupai-lab: stopped by SIGTERM`, and a request still in the queue is
|
|
92
|
+
withdrawn. A signal that comes while a session starts or ends waits until that call is done; a repeat while the
|
|
93
|
+
script stops is ignored. The handlers are installed when the block starts and the script's own are back at its
|
|
94
|
+
end (a signal the script ignores stays ignored). Only the main thread installs them.
|
|
95
|
+
|
|
96
|
+
## The record and `changes.json`
|
|
97
|
+
|
|
98
|
+
`record` (a path) gets one JSON line per call, appended: `time`, `method`, `path`, `args`, `ok`, `status`,
|
|
99
|
+
`code` (the error code, or null), `message` on a refusal, `req_id`, and for an op call `machine`, `role`,
|
|
100
|
+
`instrument`, `kind` and `op`. A successful call's line carries its `result`, or `file` when the script saved that
|
|
101
|
+
result with `lab.save` straight after the call. The line of a call that answered a dict or a list is written with
|
|
102
|
+
the next call (or at the block's end), so it can name the file.
|
|
103
|
+
|
|
104
|
+
`lab.changes(path)` groups the writes by role and op: one numeric argument that moved is a range, several a box,
|
|
105
|
+
the rest fixed. `channel` never moves: each channel is its own change.
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{"script": "experiments/2026-11-21-frequency-response/run.py@3f2a91c", "machines": ["signal-bench-sim-1"],
|
|
109
|
+
"changes": [
|
|
110
|
+
{"role": "generator", "op": "set_waveform", "calls": 7, "quantity": "frequency_hz", "min": 100, "max": 100000.0,
|
|
111
|
+
"fixed": {"channel": 1, "shape": "sine", "amplitude_v": 1.0}},
|
|
112
|
+
{"role": "scope", "op": "set_timebase", "calls": 7, "quantity": "scale_s", "min": 5e-06, "max": 0.005,
|
|
113
|
+
"fixed": {"offset_s": 0.0}}]}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
A box reads `"ranges": {"x": [min, max], "y": [min, max]}` in place of `quantity`, `min` and `max`.
|
|
117
|
+
|
|
118
|
+
Every request sends `Authorization: Bearer <key>` and `X-InstruCore-Script: <script>@<commit>`: the running
|
|
119
|
+
script's path in its git repository and the short commit, so the lab's record shows the code behind each call.
|
|
120
|
+
Outside a git repository the header is left out; `Lab(…, script_ref="…")` sets it, `script_ref=""` sends none.
|
|
121
|
+
|
|
122
|
+
## Live runs
|
|
123
|
+
|
|
124
|
+
When the member approves a live run (QuPai's `lab_run`, or Run on an experiment folder), QuPai writes the run's key
|
|
125
|
+
file into the place's repository and starts, in the repository's root:
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
qupai-lab run --key-file .qupai/runs/<run>/key.env --commit <sha> experiments/2026-11-21-freq signal-bench
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
1. It reads `QUPAI_LAB_URL`, `QUPAI_LAB_KEY` (the run's key), `QUPAI_LAB_RUN` (the run's id) and
|
|
132
|
+
`QUPAI_LAB_RUN_MACHINE` from the key file (`KEY=VALUE` lines) and deletes it at once, whatever it holds. The
|
|
133
|
+
machine must be the one named on the command line.
|
|
134
|
+
2. It checks the commit out into `/tmp/qupai-run-<run>` (`git worktree add --detach`, in the repository found from
|
|
135
|
+
the working directory). The experiment folder's committed `data/`, `figures/`, `calls.jsonl` and
|
|
136
|
+
`changes.json` (a rehearsal's) are removed from that checkout, so what the run keeps is its own.
|
|
137
|
+
3. It runs `python run.py <machine>` in `<checkout>/<experiment>` with the Python it runs in, with the four
|
|
138
|
+
settings in place of any other `QUPAI_*` variable and `PYTHONUNBUFFERED=1`. The script's output is the
|
|
139
|
+
command's own, as it is printed. The script's `Lab.from_env()` gets the run's key, and `lab.machine(<machine>)`
|
|
140
|
+
holds the live machine (above).
|
|
141
|
+
4. When the script ends it copies the `data/`, `figures/`, `calls.jsonl` and `changes.json` the script left to
|
|
142
|
+
`<experiment>/runs/<run>/` in the repository, and removes the checkout, also when the script failed.
|
|
143
|
+
5. It exits with the script's exit code (128 + the signal's number when a signal ended the script).
|
|
144
|
+
|
|
145
|
+
SIGTERM and SIGINT are passed to the script, which releases the machine and exits; a script that has not ended
|
|
146
|
+
20 s later is killed. What it left is still copied and the checkout removed. A run that cannot start (a key file
|
|
147
|
+
without the four settings, another machine, no repository, no such commit, no `run.py` in the experiment at that
|
|
148
|
+
commit) says why on stderr and exits with 2, after deleting the key file.
|
|
149
|
+
|
|
150
|
+
### Points for QuPai (`QUPAI_METRIC`)
|
|
151
|
+
|
|
152
|
+
Inside a run (`QUPAI_LAB_RUN` set) the SDK prints the run's progress on stdout as lines QuPai's Runtime takes from
|
|
153
|
+
a background job's output, one point each:
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
QUPAI_METRIC {"key": "queue_position", "value": 2}
|
|
157
|
+
QUPAI_METRIC {"key": "held", "value": 1}
|
|
158
|
+
QUPAI_METRIC {"key": "calls", "value": 14}
|
|
159
|
+
QUPAI_METRIC {"key": "held", "value": 0}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
| Key | When |
|
|
163
|
+
| --- | --- |
|
|
164
|
+
| `queue_position` | The request's position in the machine's queue, when it is queued and each time it moves |
|
|
165
|
+
| `held` | 1 when the session starts, 0 when it is released |
|
|
166
|
+
| `calls` | The instrument calls made so far (reads, writes and checks, refused ones too), at most every 5 s, and when the session is released and the script exits |
|
|
167
|
+
|
|
168
|
+
Outside a run nothing is printed on stdout.
|
|
169
|
+
|
|
170
|
+
## Errors
|
|
171
|
+
|
|
172
|
+
A refusal raises `LabError`, with `code`, `message` (the lab's sentence as it sent it), `detail` and `status`
|
|
173
|
+
(the HTTP status, 0 when no answer came). It reads InstruCore's `{"error": {code, message, detail}}` and the QuPai
|
|
174
|
+
gateway's problem documents (`urn:qupai:problem:rate` becomes `RATE`, `invalid-key` `INVALID_KEY`). A 429 waits
|
|
175
|
+
for `Retry-After` (2 s without one) and asks again, up to 5 times.
|
|
176
|
+
|
|
177
|
+
| Code | What it means |
|
|
178
|
+
| --- | --- |
|
|
179
|
+
| `LIMIT_EXCEEDED`, `POLICY_DENIED`, `FORBIDDEN` | The lab refuses this value or op. Save what you have and report the limit; never retry with another value or through another op |
|
|
180
|
+
| `APPROVAL_REQUIRED` | A write on a live machine the member has not allowed |
|
|
181
|
+
| `RUN_REQUIRED` | A script asked to hold a live machine: only a run the member approved holds one |
|
|
182
|
+
| `SESSION_REQUIRED`, `MACHINE_IN_SESSION` | The write needs your session on that machine, or someone else holds it |
|
|
183
|
+
| `INVALID_KEY`, `FORBIDDEN`, `RATE`, `UNAVAILABLE` (the gateway's) | The key, your role on the lab, too many calls, the lab not reachable through QuPai |
|
|
184
|
+
| `UNREACHABLE`, `NOT_CONFIGURED` | No answer from the address; no address or key found |
|
|
185
|
+
| `UNKNOWN_ROLE`, `NOT_HELD`, `WAIT_TIMEOUT`, `REQUEST_EXPIRED`, `REQUEST_CANCELLED` | The SDK's own: no such role, the machine used outside `with`, no copy offered in `wait_s`, the queue request ended |
|
|
186
|
+
|
|
187
|
+
## Tests
|
|
188
|
+
|
|
189
|
+
```
|
|
190
|
+
cd sdk/python
|
|
191
|
+
python3 -m venv .venv && .venv/bin/pip install -e . pytest
|
|
192
|
+
.venv/bin/pytest -q
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
They run against a fake InstruCore in a thread; `qupai-lab run`'s tests make git repositories under the test's
|
|
196
|
+
temporary folder and checkouts in `/tmp/qupai-run-<run>`, and send signals to scripts in subprocesses. `tests/test_integration.py` also runs against a real InstruCore
|
|
197
|
+
with a simulated pool when `QUPAI_LAB_IT_URL` and `QUPAI_LAB_IT_KEY` (a read-write key) are set;
|
|
198
|
+
`QUPAI_LAB_IT_POOL` picks the pool.
|
|
199
|
+
|
|
200
|
+
## License
|
|
201
|
+
|
|
202
|
+
MIT
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "qupai-lab"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "The QuPai Lab SDK: work a QuPai lab's instruments from Python scripts through InstruCore's REST API."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "QuSpect" }]
|
|
14
|
+
keywords = ["qupai", "lab", "instruments", "instrucore"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Operating System :: OS Independent",
|
|
18
|
+
"Topic :: Scientific/Engineering",
|
|
19
|
+
]
|
|
20
|
+
dependencies = []
|
|
21
|
+
|
|
22
|
+
[project.urls]
|
|
23
|
+
Homepage = "https://github.com/QuSpect/qupai-lab-plugin"
|
|
24
|
+
Repository = "https://github.com/QuSpect/qupai-lab-plugin"
|
|
25
|
+
|
|
26
|
+
[project.scripts]
|
|
27
|
+
qupai-lab = "qupai_lab.cli:main"
|
|
28
|
+
|
|
29
|
+
[tool.setuptools.dynamic]
|
|
30
|
+
version = { attr = "qupai_lab.__version__" }
|
|
31
|
+
|
|
32
|
+
[tool.setuptools.packages.find]
|
|
33
|
+
where = ["src"]
|
|
34
|
+
|
|
35
|
+
[tool.pytest.ini_options]
|
|
36
|
+
testpaths = ["tests"]
|
|
37
|
+
markers = ["integration: needs a real InstruCore (QUPAI_LAB_IT_URL, QUPAI_LAB_IT_KEY)"]
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""The QuPai Lab SDK: work a lab's instruments from Python through InstruCore's REST API (LS4).
|
|
2
|
+
|
|
3
|
+
from qupai_lab import Lab
|
|
4
|
+
|
|
5
|
+
lab = Lab.from_env(record="calls.jsonl")
|
|
6
|
+
with lab.machine("signal-bench-sim") as m:
|
|
7
|
+
gen = m.role("dg822_pro_usb")
|
|
8
|
+
gen.write("set_waveform", channel=1, shape="sine", frequency_hz=1000, amplitude_v=1.0)
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
__version__ = "0.2.0"
|
|
12
|
+
|
|
13
|
+
from qupai_lab.errors import LabError # noqa: E402 (after __version__, which lab.py imports)
|
|
14
|
+
from qupai_lab.lab import Instrument, Lab, Machine # noqa: E402
|
|
15
|
+
|
|
16
|
+
__all__ = ["Instrument", "Lab", "LabError", "Machine", "__version__"]
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""The writes a script made, grouped as a live run's card shows them (LS9): ranges, boxes and fixed arguments."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from qupai_lab.record import jsonable
|
|
10
|
+
|
|
11
|
+
# Arguments that pick what is written to rather than a value: CH1 and CH2 are two changes, never a range.
|
|
12
|
+
SELECTORS = frozenset({"channel"})
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass
|
|
16
|
+
class Write:
|
|
17
|
+
role: str
|
|
18
|
+
op: str
|
|
19
|
+
args: dict[str, Any]
|
|
20
|
+
machine: str
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _numeric(value: Any) -> bool:
|
|
24
|
+
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _key(value: Any) -> str:
|
|
28
|
+
return json.dumps(value, sort_keys=True, default=jsonable)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def group(writes: list[Write]) -> list[dict[str, Any]]:
|
|
32
|
+
"""Group writes by role and op.
|
|
33
|
+
|
|
34
|
+
Within a group the numeric arguments that took more than one value move: one gives
|
|
35
|
+
``{quantity, min, max}``, several a box ``{ranges: {quantity: [min, max]}}``. Every other argument is
|
|
36
|
+
``fixed``. Writes whose other arguments differ (another shape, another channel, another set of names) are
|
|
37
|
+
separate groups of the same role and op, in the order they were first written.
|
|
38
|
+
"""
|
|
39
|
+
groups: dict[tuple[str, str, str], list[Write]] = {}
|
|
40
|
+
for w in writes:
|
|
41
|
+
names = sorted(w.args)
|
|
42
|
+
held = {k: v for k, v in w.args.items() if k in SELECTORS or not _numeric(v)}
|
|
43
|
+
groups.setdefault((w.role, w.op, _key([names, held])), []).append(w)
|
|
44
|
+
out: list[dict[str, Any]] = []
|
|
45
|
+
for (role, op, _), members in groups.items():
|
|
46
|
+
first = members[0].args
|
|
47
|
+
moving: dict[str, list[Any]] = {}
|
|
48
|
+
fixed: dict[str, Any] = {}
|
|
49
|
+
for name, value in first.items():
|
|
50
|
+
values = [m.args[name] for m in members]
|
|
51
|
+
if name not in SELECTORS and _numeric(value) and len({float(v) for v in values}) > 1:
|
|
52
|
+
moving[name] = [min(values, key=float), max(values, key=float)]
|
|
53
|
+
else:
|
|
54
|
+
fixed[name] = value
|
|
55
|
+
entry: dict[str, Any] = {"role": role, "op": op, "calls": len(members)}
|
|
56
|
+
if len(moving) == 1:
|
|
57
|
+
(quantity, (low, high)), = moving.items()
|
|
58
|
+
entry |= {"quantity": quantity, "min": low, "max": high}
|
|
59
|
+
elif moving:
|
|
60
|
+
entry["ranges"] = moving
|
|
61
|
+
entry["fixed"] = fixed
|
|
62
|
+
out.append(entry)
|
|
63
|
+
return out
|