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.
@@ -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.
@@ -0,0 +1,2 @@
1
+ # The package on PyPI is the library: its tests (and their stand-in lab) stay in the repository.
2
+ prune tests
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,3 @@
1
+ from qupai_lab.cli import main
2
+
3
+ raise SystemExit(main())
@@ -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