gridlinegpu 0.1.5__tar.gz → 0.1.7__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.
Files changed (58) hide show
  1. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/PKG-INFO +121 -1
  2. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/README.md +117 -0
  3. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/pyproject.toml +7 -1
  4. gridlinegpu-0.1.7/src/gridlinegpu/UNICODE-LICENSE.txt +39 -0
  5. gridlinegpu-0.1.7/src/gridlinegpu/__init__.py +26 -0
  6. gridlinegpu-0.1.7/src/gridlinegpu/_source_admission.py +297 -0
  7. gridlinegpu-0.1.7/src/gridlinegpu/_source_capture.py +1617 -0
  8. gridlinegpu-0.1.7/src/gridlinegpu/_source_casefold.json +1559 -0
  9. gridlinegpu-0.1.7/src/gridlinegpu/_source_contract.py +1633 -0
  10. gridlinegpu-0.1.7/src/gridlinegpu/_source_credits.py +61 -0
  11. gridlinegpu-0.1.7/src/gridlinegpu/_source_errors.py +648 -0
  12. gridlinegpu-0.1.7/src/gridlinegpu/_source_history.py +242 -0
  13. gridlinegpu-0.1.7/src/gridlinegpu/_source_interfaces.py +1348 -0
  14. gridlinegpu-0.1.7/src/gridlinegpu/_source_job.py +755 -0
  15. gridlinegpu-0.1.7/src/gridlinegpu/_source_outputs.py +834 -0
  16. gridlinegpu-0.1.7/src/gridlinegpu/_source_public.py +191 -0
  17. gridlinegpu-0.1.7/src/gridlinegpu/_source_release.py +76 -0
  18. gridlinegpu-0.1.7/src/gridlinegpu/_source_results.py +650 -0
  19. gridlinegpu-0.1.7/src/gridlinegpu/_source_run.py +466 -0
  20. gridlinegpu-0.1.7/src/gridlinegpu/_source_submission.py +341 -0
  21. gridlinegpu-0.1.7/src/gridlinegpu/_source_transfer.py +402 -0
  22. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu/cli.py +54 -3
  23. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu/client.py +105 -7
  24. gridlinegpu-0.1.7/src/gridlinegpu/errors.py +176 -0
  25. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu.egg-info/PKG-INFO +121 -1
  26. gridlinegpu-0.1.7/src/gridlinegpu.egg-info/SOURCES.txt +51 -0
  27. gridlinegpu-0.1.7/src/gridlinegpu.egg-info/requires.txt +5 -0
  28. gridlinegpu-0.1.7/tests/test_cli.py +285 -0
  29. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/tests/test_client.py +63 -0
  30. gridlinegpu-0.1.7/tests/test_client_source.py +579 -0
  31. gridlinegpu-0.1.7/tests/test_source_admission.py +517 -0
  32. gridlinegpu-0.1.7/tests/test_source_canary.py +119 -0
  33. gridlinegpu-0.1.7/tests/test_source_capture.py +791 -0
  34. gridlinegpu-0.1.7/tests/test_source_capture_gaps.py +207 -0
  35. gridlinegpu-0.1.7/tests/test_source_contract.py +1234 -0
  36. gridlinegpu-0.1.7/tests/test_source_credits.py +73 -0
  37. gridlinegpu-0.1.7/tests/test_source_curated_run.py +183 -0
  38. gridlinegpu-0.1.7/tests/test_source_errors.py +183 -0
  39. gridlinegpu-0.1.7/tests/test_source_history.py +158 -0
  40. gridlinegpu-0.1.7/tests/test_source_job.py +702 -0
  41. gridlinegpu-0.1.7/tests/test_source_job_results.py +1066 -0
  42. gridlinegpu-0.1.7/tests/test_source_release.py +51 -0
  43. gridlinegpu-0.1.7/tests/test_source_results.py +278 -0
  44. gridlinegpu-0.1.7/tests/test_source_run.py +641 -0
  45. gridlinegpu-0.1.7/tests/test_source_submission.py +236 -0
  46. gridlinegpu-0.1.7/tests/test_source_transfer.py +432 -0
  47. gridlinegpu-0.1.5/src/gridlinegpu/__init__.py +0 -6
  48. gridlinegpu-0.1.5/src/gridlinegpu/errors.py +0 -20
  49. gridlinegpu-0.1.5/src/gridlinegpu.egg-info/SOURCES.txt +0 -17
  50. gridlinegpu-0.1.5/src/gridlinegpu.egg-info/requires.txt +0 -1
  51. gridlinegpu-0.1.5/tests/test_cli.py +0 -130
  52. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/setup.cfg +0 -0
  53. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu/__main__.py +0 -0
  54. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu/cli_auth.py +0 -0
  55. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu.egg-info/dependency_links.txt +0 -0
  56. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu.egg-info/entry_points.txt +0 -0
  57. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/src/gridlinegpu.egg-info/top_level.txt +0 -0
  58. {gridlinegpu-0.1.5 → gridlinegpu-0.1.7}/tests/test_cli_auth.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: gridlinegpu
3
- Version: 0.1.5
3
+ Version: 0.1.7
4
4
  Summary: Python client for Gridline YAML workload routing
5
5
  Author: Gridline GPU
6
6
  License: Proprietary
@@ -12,6 +12,9 @@ Classifier: Operating System :: OS Independent
12
12
  Requires-Python: >=3.10
13
13
  Description-Content-Type: text/markdown
14
14
  Requires-Dist: PyYAML<7,>=6.0.2
15
+ Provides-Extra: source-contract
16
+ Requires-Dist: rfc8785==0.1.4; extra == "source-contract"
17
+ Requires-Dist: unicodedata2==16.0.0; extra == "source-contract"
15
18
 
16
19
  # Gridline Python SDK
17
20
 
@@ -127,3 +130,120 @@ five seconds; deduplicate by attempt/fence/stage. Missing progress or skipped st
127
130
  mean unavailable evidence, not failure or an inferred stage. Inference completion
128
131
  does not imply stored outputs, job success, cleanup, or settled billing. `wait()` keeps
129
132
  its existing completion behavior and does not stream progress callbacks.
133
+
134
+ ## Source runs (beta)
135
+
136
+ Source runs send your own Python code and inputs to one GPU, run it as a finite job on an
137
+ operator-qualified **curated runtime**, and return your declared output files. They are in
138
+ an invite-only beta, funded by credits Gridline grants to design partners: there is no
139
+ top-up or payment step in the SDK. Install the source extra and turn the beta on in your
140
+ shell:
141
+
142
+ ```sh
143
+ python -m pip install 'gridlinegpu[source-contract]>=0.1.7,<0.2'
144
+ export GRIDLINE_SOURCE_SDK_ENABLED=true
145
+ gridline setup --apply # once: saves a private, scoped token file
146
+ ```
147
+
148
+ Without `GRIDLINE_SOURCE_SDK_ENABLED=true`, `run()` raises `GridlineError` with code
149
+ `source_lane_disabled` and touches no file, token or network.
150
+
151
+ **The workload.** Put a `gridline.yaml` beside your code. Name a curated runtime instead of
152
+ declaring dependencies: `gridline/hf-torch-2.5@r1` provides CPython 3.11 and CUDA 12.4 with
153
+ `torch==2.5.1`, `transformers==4.46.3`, `accelerate==1.1.1`, `safetensors==0.4.5`,
154
+ `tokenizers==0.20.3`, `datasets==3.1.0`, `pandas==2.2.3`, `pyarrow==18.0.0` and
155
+ `numpy==1.26.4`. Do not add `python`, `requirements` or a lockfile next to a curated runtime
156
+ (refused as `source_runtime_curated_conflict`). A curated runtime named before this
157
+ SDK release or the server offers it is refused before anything is uploaded
158
+ (`curated_runtimes_unavailable`).
159
+
160
+ ```yaml
161
+ version: 2
162
+ name: batch-generate
163
+ task:
164
+ kind: application
165
+ class: inference
166
+ source:
167
+ include: [job.py]
168
+ command: [python, job.py]
169
+ runtime: gridline/hf-torch-2.5@r1
170
+ outputs:
171
+ results:
172
+ path: outputs/results.json
173
+ max_bytes: 1048576
174
+ resources:
175
+ gpu:
176
+ count: 1
177
+ minimum_vram_gib: 8
178
+ ```
179
+
180
+ To set environment variables, use the mapping form:
181
+ `runtime: {curated: gridline/hf-torch-2.5@r1, environment: {MY_FLAG: "1"}}`. Temp, cache
182
+ and home directories are the platform's and cannot be redirected (`TMPDIR`,
183
+ `XDG_CACHE_HOME`, `HOME` and `HF_HOME` are refused).
184
+
185
+ **Limits during the beta.**
186
+ - Inputs: each local input file is at most 512 MiB.
187
+ - Outputs: declare each one under `outputs`. Each file is at most 128 MiB (`max_bytes`;
188
+ 8 MiB when omitted), at most 1 GiB in total, and at most 32 outputs per job.
189
+ - No network at run time (details below): the code, inputs and models it needs must
190
+ arrive with the job.
191
+ - Leave out `budget` and `execution.deadline_seconds`: beta routing places jobs best-effort
192
+ and refuses either constraint (`budget_feasibility_unknown` /
193
+ `deadline_feasibility_unknown`).
194
+
195
+ **Run it.** `run()` validates, captures your selected files, uploads them and returns a
196
+ `JobHandle` once the job is admitted. Everything after that happens server-side.
197
+
198
+ ```python
199
+ from gridlinegpu import GridlineClient, SubmissionOutcomeUnknown
200
+
201
+ client = GridlineClient()
202
+ try:
203
+ job = client.run("gridline.yaml")
204
+ except SubmissionOutcomeUnknown as error:
205
+ job = client.resume(error.submission_id) # never run() again for the same submission
206
+ print(job.job_id)
207
+
208
+ result = job.wait() # polls status; a local timeout never cancels the job
209
+ print(result.outcome, result.failure_code)
210
+ if result.succeeded:
211
+ print(job.outputs("results")) # verified files, written under results/
212
+ print(job.report()["settlement"]) # reserved, held, charged and released credits for this job
213
+ ```
214
+
215
+ `job.status()` reads the current state without waiting, and `job.cancel()` requests a stop.
216
+ `client.history(limit=20)` lists your recent jobs, newest first. `report()` and `history()`
217
+ raise `report_unavailable` / `history_unavailable` until those reads are switched on for
218
+ the beta; the job itself is unaffected. A complete minimal
219
+ job is in `examples/workloads/curated-beta/`.
220
+
221
+ The rest of this section describes how source runs behave.
222
+
223
+ **Network.** Source runs have no network access, only Unix domain sockets. No TCP or UDP,
224
+ localhost included. So these fail: local HTTP servers (FastAPI, TGI), Ray, and any pip or
225
+ Hugging Face download at run time. vLLM (offline `LLM()` included) and NCCL or
226
+ torch.distributed (whatever the init method) are expected to fail. The error is typically
227
+ `PermissionError: [Errno 1] Operation not permitted`, or a library's own connection or
228
+ offline error. Declare models and inputs: they are fetched by the platform, not by your
229
+ code, and staged before your code starts. io_uring is not available either. If the
230
+ machine cannot enforce this isolation, your code does not start and the job ends with
231
+ `isolation_unsupported`: "The allocated machine cannot enforce the workload's required
232
+ isolation." Submit a new run; contact support if it repeats.
233
+
234
+ **Pinned models.** Gridline fetches each declared model at its pinned commit. If a pinned
235
+ model file has changed or is missing when it is fetched for your run, the run stops and
236
+ that attempt is used up; it is not retried. A machine was already started, so your
237
+ provider bills its time. During the canary, a used-up attempt costs at most about $0.50:
238
+ up to roughly 20 minutes (15 minutes of startup plus one 5-minute stop cycle) at the $1.50
239
+ per hour price ceiling, disk included.
240
+ Check that pinned models are still public, then run again.
241
+
242
+ **No GPU capacity.** If the selected GPU is not available, no machine is started and that
243
+ attempt is not charged. The status reads "The selected GPU was not available, so no
244
+ machine was started and this attempt was not charged. Trying the next matching offer." If
245
+ no matching GPU is left and no machine was started for the job, it ends with
246
+ `routing_attempts_exhausted`: "No matching GPU was available right now. No machine was
247
+ started for this job, so these attempts were not charged. Try again later or widen the GPU
248
+ choice." A machine that did start is billed by your provider for the time it ran, whatever
249
+ the outcome.
@@ -112,3 +112,120 @@ five seconds; deduplicate by attempt/fence/stage. Missing progress or skipped st
112
112
  mean unavailable evidence, not failure or an inferred stage. Inference completion
113
113
  does not imply stored outputs, job success, cleanup, or settled billing. `wait()` keeps
114
114
  its existing completion behavior and does not stream progress callbacks.
115
+
116
+ ## Source runs (beta)
117
+
118
+ Source runs send your own Python code and inputs to one GPU, run it as a finite job on an
119
+ operator-qualified **curated runtime**, and return your declared output files. They are in
120
+ an invite-only beta, funded by credits Gridline grants to design partners: there is no
121
+ top-up or payment step in the SDK. Install the source extra and turn the beta on in your
122
+ shell:
123
+
124
+ ```sh
125
+ python -m pip install 'gridlinegpu[source-contract]>=0.1.7,<0.2'
126
+ export GRIDLINE_SOURCE_SDK_ENABLED=true
127
+ gridline setup --apply # once: saves a private, scoped token file
128
+ ```
129
+
130
+ Without `GRIDLINE_SOURCE_SDK_ENABLED=true`, `run()` raises `GridlineError` with code
131
+ `source_lane_disabled` and touches no file, token or network.
132
+
133
+ **The workload.** Put a `gridline.yaml` beside your code. Name a curated runtime instead of
134
+ declaring dependencies: `gridline/hf-torch-2.5@r1` provides CPython 3.11 and CUDA 12.4 with
135
+ `torch==2.5.1`, `transformers==4.46.3`, `accelerate==1.1.1`, `safetensors==0.4.5`,
136
+ `tokenizers==0.20.3`, `datasets==3.1.0`, `pandas==2.2.3`, `pyarrow==18.0.0` and
137
+ `numpy==1.26.4`. Do not add `python`, `requirements` or a lockfile next to a curated runtime
138
+ (refused as `source_runtime_curated_conflict`). A curated runtime named before this
139
+ SDK release or the server offers it is refused before anything is uploaded
140
+ (`curated_runtimes_unavailable`).
141
+
142
+ ```yaml
143
+ version: 2
144
+ name: batch-generate
145
+ task:
146
+ kind: application
147
+ class: inference
148
+ source:
149
+ include: [job.py]
150
+ command: [python, job.py]
151
+ runtime: gridline/hf-torch-2.5@r1
152
+ outputs:
153
+ results:
154
+ path: outputs/results.json
155
+ max_bytes: 1048576
156
+ resources:
157
+ gpu:
158
+ count: 1
159
+ minimum_vram_gib: 8
160
+ ```
161
+
162
+ To set environment variables, use the mapping form:
163
+ `runtime: {curated: gridline/hf-torch-2.5@r1, environment: {MY_FLAG: "1"}}`. Temp, cache
164
+ and home directories are the platform's and cannot be redirected (`TMPDIR`,
165
+ `XDG_CACHE_HOME`, `HOME` and `HF_HOME` are refused).
166
+
167
+ **Limits during the beta.**
168
+ - Inputs: each local input file is at most 512 MiB.
169
+ - Outputs: declare each one under `outputs`. Each file is at most 128 MiB (`max_bytes`;
170
+ 8 MiB when omitted), at most 1 GiB in total, and at most 32 outputs per job.
171
+ - No network at run time (details below): the code, inputs and models it needs must
172
+ arrive with the job.
173
+ - Leave out `budget` and `execution.deadline_seconds`: beta routing places jobs best-effort
174
+ and refuses either constraint (`budget_feasibility_unknown` /
175
+ `deadline_feasibility_unknown`).
176
+
177
+ **Run it.** `run()` validates, captures your selected files, uploads them and returns a
178
+ `JobHandle` once the job is admitted. Everything after that happens server-side.
179
+
180
+ ```python
181
+ from gridlinegpu import GridlineClient, SubmissionOutcomeUnknown
182
+
183
+ client = GridlineClient()
184
+ try:
185
+ job = client.run("gridline.yaml")
186
+ except SubmissionOutcomeUnknown as error:
187
+ job = client.resume(error.submission_id) # never run() again for the same submission
188
+ print(job.job_id)
189
+
190
+ result = job.wait() # polls status; a local timeout never cancels the job
191
+ print(result.outcome, result.failure_code)
192
+ if result.succeeded:
193
+ print(job.outputs("results")) # verified files, written under results/
194
+ print(job.report()["settlement"]) # reserved, held, charged and released credits for this job
195
+ ```
196
+
197
+ `job.status()` reads the current state without waiting, and `job.cancel()` requests a stop.
198
+ `client.history(limit=20)` lists your recent jobs, newest first. `report()` and `history()`
199
+ raise `report_unavailable` / `history_unavailable` until those reads are switched on for
200
+ the beta; the job itself is unaffected. A complete minimal
201
+ job is in `examples/workloads/curated-beta/`.
202
+
203
+ The rest of this section describes how source runs behave.
204
+
205
+ **Network.** Source runs have no network access, only Unix domain sockets. No TCP or UDP,
206
+ localhost included. So these fail: local HTTP servers (FastAPI, TGI), Ray, and any pip or
207
+ Hugging Face download at run time. vLLM (offline `LLM()` included) and NCCL or
208
+ torch.distributed (whatever the init method) are expected to fail. The error is typically
209
+ `PermissionError: [Errno 1] Operation not permitted`, or a library's own connection or
210
+ offline error. Declare models and inputs: they are fetched by the platform, not by your
211
+ code, and staged before your code starts. io_uring is not available either. If the
212
+ machine cannot enforce this isolation, your code does not start and the job ends with
213
+ `isolation_unsupported`: "The allocated machine cannot enforce the workload's required
214
+ isolation." Submit a new run; contact support if it repeats.
215
+
216
+ **Pinned models.** Gridline fetches each declared model at its pinned commit. If a pinned
217
+ model file has changed or is missing when it is fetched for your run, the run stops and
218
+ that attempt is used up; it is not retried. A machine was already started, so your
219
+ provider bills its time. During the canary, a used-up attempt costs at most about $0.50:
220
+ up to roughly 20 minutes (15 minutes of startup plus one 5-minute stop cycle) at the $1.50
221
+ per hour price ceiling, disk included.
222
+ Check that pinned models are still public, then run again.
223
+
224
+ **No GPU capacity.** If the selected GPU is not available, no machine is started and that
225
+ attempt is not charged. The status reads "The selected GPU was not available, so no
226
+ machine was started and this attempt was not charged. Trying the next matching offer." If
227
+ no matching GPU is left and no machine was started for the job, it ends with
228
+ `routing_attempts_exhausted`: "No matching GPU was available right now. No machine was
229
+ started for this job, so these attempts were not charged. Try again later or widen the GPU
230
+ choice." A machine that did start is billed by your provider for the time it ran, whatever
231
+ the outcome.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "gridlinegpu"
7
- version = "0.1.5"
7
+ version = "0.1.7"
8
8
  description = "Python client for Gridline YAML workload routing"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -17,6 +17,9 @@ classifiers = [
17
17
  "Operating System :: OS Independent",
18
18
  ]
19
19
 
20
+ [project.optional-dependencies]
21
+ source-contract = ["rfc8785==0.1.4", "unicodedata2==16.0.0"]
22
+
20
23
  [project.scripts]
21
24
  gridline = "gridlinegpu.cli:main"
22
25
 
@@ -26,3 +29,6 @@ Repository = "https://github.com/GridlineGPU/gridline-gpu"
26
29
 
27
30
  [tool.setuptools.packages.find]
28
31
  where = ["src"]
32
+
33
+ [tool.setuptools.package-data]
34
+ gridlinegpu = ["_source_casefold.json", "UNICODE-LICENSE.txt"]
@@ -0,0 +1,39 @@
1
+ UNICODE LICENSE V3
2
+
3
+ COPYRIGHT AND PERMISSION NOTICE
4
+
5
+ Copyright © 1991-2026 Unicode, Inc.
6
+
7
+ NOTICE TO USER: Carefully read the following legal agreement. BY
8
+ DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
9
+ SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
10
+ TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
11
+ DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a
14
+ copy of data files and any associated documentation (the "Data Files") or
15
+ software and any associated documentation (the "Software") to deal in the
16
+ Data Files or Software without restriction, including without limitation
17
+ the rights to use, copy, modify, merge, publish, distribute, and/or sell
18
+ copies of the Data Files or Software, and to permit persons to whom the
19
+ Data Files or Software are furnished to do so, provided that either (a)
20
+ this copyright and permission notice appear with all copies of the Data
21
+ Files or Software, or (b) this copyright and permission notice appear in
22
+ associated Documentation.
23
+
24
+ THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
25
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
26
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
27
+ THIRD PARTY RIGHTS.
28
+
29
+ IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
30
+ BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
31
+ OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
32
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
33
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
34
+ FILES OR SOFTWARE.
35
+
36
+ Except as contained in this notice, the name of a copyright holder shall
37
+ not be used in advertising or otherwise to promote the sale, use or other
38
+ dealings in these Data Files or Software without prior written
39
+ authorization of the copyright holder.
@@ -0,0 +1,26 @@
1
+ """Gridline YAML workload client."""
2
+
3
+ from .client import GridlineClient, PlannedWorkload
4
+ from .errors import (
5
+ GridlineError, LaunchOutcomeUnknown, OutputsIncomplete, ReceiptPersistenceError, SubmissionOutcomeUnknown,
6
+ WaitTimeout, WorkloadValidationError,
7
+ )
8
+
9
+ __all__ = [
10
+ "GridlineClient", "GridlineError", "LaunchOutcomeUnknown", "OutputsIncomplete", "PlannedWorkload",
11
+ "ReceiptPersistenceError", "SubmissionOutcomeUnknown", "WaitTimeout", "WorkloadValidationError",
12
+ ]
13
+
14
+
15
+ def __getattr__(name):
16
+ """PEP 562: ``JobHandle`` needs the optional ``source-contract`` extra, so it is imported on
17
+ first use. Without the extra, ``gridlinegpu.JobHandle`` raises GridlineError
18
+ ``source_dependencies_missing``, which is also an AttributeError (``hasattr`` is False; a
19
+ ``from gridlinegpu import JobHandle`` raises Python's ImportError). It joins ``__all__``
20
+ at activation, when the extra becomes a base dependency."""
21
+ if name == "JobHandle":
22
+ from ._source_public import job_handle_type
23
+
24
+ value = globals()["JobHandle"] = job_handle_type()
25
+ return value
26
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -0,0 +1,297 @@
1
+ """Disabled source-v2 Step 5 SDK admission: turn an ARTIFACTS_READY capture into one durable
2
+ job receipt. Reached only through GridlineClient.run/resume (disabled by default).
3
+
4
+ - ``artifacts_ready`` -> ``admitting``: the exact admission request is persisted before the
5
+ first POST. Every retry resends identical bytes under the same submission UUID, the only
6
+ idempotency key (spec 5.2); the Idempotency-Key header equals it.
7
+ - A validated receipt bound to that request -> ``admitted``, stored before it is returned.
8
+ The local payload is then dropped: the job owns the server-side artifacts.
9
+ - An unknown outcome (transport failure, server error, unreadable or unbound success) is
10
+ reconciled through the read-only lookup, then the identical request is retried, for at
11
+ most 60 seconds per call (spec 5.8). Afterwards SubmissionOutcomeUnknown: resume the same
12
+ submission, never a new one.
13
+ - A definitive rejection -> ``rejected`` (terminal, disposable). Retryable and corrective
14
+ rejections leave ``admitting`` for a later call, which looks up first.
15
+
16
+ Credentials are passed in and sent only in the Authorization header; nothing here stores,
17
+ logs or hashes them.
18
+ """
19
+
20
+ import http.client
21
+ import json
22
+ import re
23
+ import time
24
+ from urllib.error import URLError
25
+
26
+ from ._source_capture import _DESCRIPTOR, _remove_payload, _write_json_atomic, hold_capture_lease
27
+ from ._source_contract import canonical_json
28
+ from ._source_interfaces import (
29
+ source_deadline_at, validate_source_admission_receipt, validate_source_admission_request,
30
+ validate_source_preparation_receipt, validate_source_verified_set,
31
+ )
32
+ from ._source_submission import (
33
+ SOURCE_SDK_TIMINGS, _MAX_RESPONSE_BYTES, _PREPARATIONS, _TERMINAL, _USER_AGENT, ReceiptPersistenceError,
34
+ SourceSubmissionError, SubmissionOutcomeUnknown, UrllibSourceTransport, _error_code, _https_origin, _lookup,
35
+ _persist, _retry_after,
36
+ )
37
+
38
+ _JOB = re.compile(r"job_[a-f0-9]{32}\Z")
39
+ _TRANSPORT_ERRORS = (OSError, URLError, TimeoutError, ValueError, http.client.HTTPException)
40
+ # The server answers an identical existing admission before any of these checks, so they
41
+ # are definitive: this submission can never admit.
42
+ _MISMATCH = frozenset({"submission_payload_mismatch", "policy_binding_mismatch"})
43
+ _ADMISSION_TERMINAL = (_TERMINAL - _MISMATCH) | {
44
+ "definition_binding_mismatch", "invocation_binding_mismatch", "capability_profile_mismatch",
45
+ }
46
+ # Answered before the existing-admission check: definitive only for a very first request.
47
+ # The mismatch codes may mean a job exists under other bindings. Lookup decides both.
48
+ _AMBIGUOUS = _MISMATCH | {"schema_invalid"}
49
+ # This attempt was refused and rolled back; the identical request may succeed later.
50
+ _RETRYABLE = frozenset({"rate_limited", "admission_busy", "admission_capacity_exceeded"})
51
+ # Corrective action needed (sign in, scope, provider access, finish Step 4); state unchanged.
52
+ _CORRECTIVE = frozenset({
53
+ "artifacts_not_ready", "authentication_required", "authentication_invalid", "authentication_expired",
54
+ "authentication_revoked", "scope_insufficient", "account_ineligible", "account_context_mismatch",
55
+ "reference_forbidden", "access_binding_changed", "partner_not_admitted", "partner_suspended",
56
+ # Credits H7: a grant lets the identical request admit later.
57
+ "credit_insufficient",
58
+ })
59
+
60
+
61
+ def _json(data):
62
+ if len(data) > _MAX_RESPONSE_BYTES:
63
+ raise ValueError
64
+ value = json.loads(data.decode("utf-8"))
65
+ if type(value) is not dict:
66
+ raise ValueError
67
+ return value
68
+
69
+
70
+ def _admission_request(descriptor, submission_id):
71
+ """The admission request derived only from stored, mutually bound records (spec 5.1)."""
72
+ try:
73
+ receipt = validate_source_preparation_receipt(descriptor.get("receipt"))
74
+ verified_set = validate_source_verified_set(descriptor.get("verifiedSet"))
75
+ digest = descriptor.get("requestSha256")
76
+ if (receipt["submissionId"] != submission_id or verified_set["submissionId"] != submission_id
77
+ or receipt["requestDigest"] != digest or verified_set["requestDigest"] != digest
78
+ or verified_set["preparationId"] != receipt["preparationId"]):
79
+ raise ValueError
80
+ request = validate_source_admission_request({
81
+ "schemaVersion": 2, "submissionId": submission_id, "requestDigest": digest,
82
+ "verifiedSetId": verified_set["verifiedSetId"], "verifiedSetDigest": verified_set["verifiedSetDigest"],
83
+ "expectedOwnerId": descriptor.get("ownerId"), "effectivePolicyRef": receipt["effectivePolicyRef"],
84
+ "effectivePolicyDigest": receipt["effectivePolicyDigest"],
85
+ })
86
+ except (ValueError, KeyError, TypeError):
87
+ raise SourceSubmissionError("capture_corrupt", submission_id) from None
88
+ return request, receipt
89
+
90
+
91
+ class _Admission:
92
+ """One admission call for one ARTIFACTS_READY capture under its lease."""
93
+
94
+ def __init__(self, submission_id, descriptor, directory, origin, token, transport, sleep, clock):
95
+ self.submission_id, self.descriptor, self.directory = submission_id, descriptor, directory
96
+ self.origin, self.transport, self.sleep, self.clock = origin.rstrip("/"), transport, sleep, clock
97
+ self.request, receipt = _admission_request(descriptor, submission_id)
98
+ self.preparation_id = receipt["preparationId"]
99
+ self.deadline_seconds = receipt["customerConstraints"]["deadlineSeconds"]
100
+ self.body = canonical_json(self.request).encode("utf-8")
101
+ self.read_headers = {"authorization": f"Bearer {token}", "accept": "application/json",
102
+ "user-agent": _USER_AGENT}
103
+ self.post_headers = {**self.read_headers, "content-type": "application/json",
104
+ "idempotency-key": submission_id}
105
+ # Set once any request's outcome was unknown, or a previous call may have admitted.
106
+ self.unknown = False
107
+
108
+ def fail(self, code, *, retry_after=None, status=None, uncertain=False):
109
+ return SourceSubmissionError(code, self.submission_id, uncertain=uncertain, retry_after_seconds=retry_after,
110
+ status=status, stage="admission")
111
+
112
+ def terminal(self, code, status=None):
113
+ """Definitive: this submission can never admit. The capture becomes disposable."""
114
+ self.descriptor = _persist(self.directory, {**self.descriptor, "state": "rejected", "rejectionCode": code})
115
+ return self.fail(code, status=status)
116
+
117
+ def bind(self, value):
118
+ """The receipt must answer exactly this request (spec 5.2/5.5); raises ValueError."""
119
+ receipt = validate_source_admission_receipt(value)
120
+ if (not _JOB.match(receipt["jobId"])
121
+ or any(receipt[key] != self.request[key] for key in (
122
+ "submissionId", "requestDigest", "verifiedSetDigest", "effectivePolicyRef",
123
+ "effectivePolicyDigest"))
124
+ or receipt["deadlineAt"] != source_deadline_at(receipt["admittedAt"], self.deadline_seconds)):
125
+ raise ValueError
126
+ return receipt
127
+
128
+ def admitted(self, receipt):
129
+ """Store the confirmed receipt before returning it, then drop the local payload."""
130
+ descriptor = {**self.descriptor, "state": "admitted", "admissionReceipt": receipt}
131
+ try:
132
+ _write_json_atomic(self.directory, _DESCRIPTOR, descriptor)
133
+ except OSError:
134
+ # Confirmed admission stays confirmed: never resubmit, recover through lookup.
135
+ raise ReceiptPersistenceError(receipt, receipt["jobId"], self.submission_id) from None
136
+ self.descriptor = descriptor
137
+ try:
138
+ _remove_payload(self.directory)
139
+ _write_json_atomic(self.directory, _DESCRIPTOR, {**descriptor, "payloadExpired": True})
140
+ except OSError:
141
+ pass # Best effort: the idle sweep removes the payload later.
142
+ return receipt
143
+
144
+ def post(self):
145
+ """One identical admit request: (receipt, code, retry_after, status); a code of None
146
+ with no receipt means the outcome is unknown."""
147
+ try:
148
+ status, headers, data = self.transport.request(
149
+ "POST", f"{self.origin}{_PREPARATIONS}/{self.preparation_id}/admit", headers=self.post_headers,
150
+ body=self.body)
151
+ except _TRANSPORT_ERRORS:
152
+ return None, None, None, None
153
+ if status in (200, 202):
154
+ try:
155
+ return self.bind(_json(data)["receipt"]), None, None, status
156
+ except (ValueError, KeyError, TypeError):
157
+ # The server may have admitted: an unreadable or unbound success is unknown.
158
+ return None, None, None, status
159
+ code = _error_code(data)
160
+ if status == 429 and code is None:
161
+ # A throttle in front of the API (no envelope) never reached admission.
162
+ code = "rate_limited"
163
+ # A server error proves nothing unless it is the envelope of a rolled-back attempt.
164
+ if status >= 500 and code not in _RETRYABLE:
165
+ code = None
166
+ return None, code, _retry_after(headers), status
167
+
168
+ def reconcile(self, code=None, status=None):
169
+ """Read-only lookup after an unknown outcome or an ambiguous rejection. Returns
170
+ (receipt, retry_after); raises when the lookup settles the submission otherwise."""
171
+ found, retry_after = _lookup(self.transport, self.origin, self.read_headers, self.submission_id)
172
+ state = found.get("state") if found is not None else None
173
+ if state == "admitted":
174
+ try:
175
+ receipt = self.bind(found.get("receipt"))
176
+ if found.get("jobId") != receipt["jobId"]:
177
+ raise ValueError
178
+ return receipt, None
179
+ except (ValueError, KeyError, TypeError):
180
+ # A job exists for this submission under other bindings: it is never replaced
181
+ # and never marked terminal here.
182
+ raise self.fail(code or "remote_contract_invalid", status=status) from None
183
+ if state in ("closed", "expired"):
184
+ # The server answers an existing admission first, so no job exists.
185
+ raise self.terminal("submission_closed" if state == "closed" else "preparation_expired", status)
186
+ if code is not None and state in ("allowed", "not_seen"):
187
+ # No job exists: the rejection of these exact bytes is definitive.
188
+ raise self.terminal(code, status)
189
+ return None, retry_after
190
+
191
+ def exhausted(self, code, wait, status):
192
+ if self.unknown or code is None:
193
+ return SubmissionOutcomeUnknown(self.submission_id, retry_after_seconds=wait)
194
+ return self.fail(code, retry_after=wait, status=status)
195
+
196
+ def run(self, resumed):
197
+ # Spec 5.8: automatic reconciliation lasts at most this long per call.
198
+ deadline = self.clock() + SOURCE_SDK_TIMINGS["admissionWindowSeconds"]
199
+ backoff, wait, code, status = 1, 0, None, None
200
+ attempted = self.unknown = resumed
201
+ if resumed:
202
+ # A previous call may have admitted: look up before sending again (spec 5.8).
203
+ receipt, wait = self.reconcile()
204
+ if receipt is not None:
205
+ return self.admitted(receipt)
206
+ while True:
207
+ if wait:
208
+ if self.clock() + wait > deadline:
209
+ raise self.exhausted(code, wait, status)
210
+ self.sleep(wait)
211
+ receipt, code, retry_after, status = self.post()
212
+ if receipt is not None:
213
+ return self.admitted(receipt)
214
+ first, attempted = not attempted, True
215
+ if code is None and status == 404:
216
+ # Admission is not served (a disabled route answers a bare 404): this attempt
217
+ # was never processed; only the lookup can show an earlier one admitted.
218
+ receipt, _ = self.reconcile(None, status)
219
+ if receipt is not None:
220
+ return self.admitted(receipt)
221
+ raise self.fail("admission_unavailable", status=status, uncertain=self.unknown)
222
+ if code == "admission_capacity_exceeded" and retry_after is None:
223
+ # A capacity refusal without Retry-After (an oversized job) never succeeds by
224
+ # waiting; earlier unknown attempts keep the outcome uncertain.
225
+ raise self.fail(code, status=status, uncertain=self.unknown)
226
+ if code in _RETRYABLE:
227
+ wait = max(retry_after or 0, backoff)
228
+ elif code in _ADMISSION_TERMINAL or (code == "schema_invalid" and first):
229
+ raise self.terminal(code, status)
230
+ elif code in _CORRECTIVE:
231
+ # An auth or access refusal says nothing about an earlier unknown attempt.
232
+ raise self.fail(code, retry_after=retry_after, status=status, uncertain=self.unknown)
233
+ else:
234
+ if self.clock() >= deadline:
235
+ # A slow request used the window up: the outcome stays unknown (spec 5.8).
236
+ self.unknown = True
237
+ raise self.exhausted(code, backoff, status)
238
+ # Unknown outcome, unknown code or an ambiguous rejection: lookup decides.
239
+ receipt, retry_after = self.reconcile(code if code in _AMBIGUOUS else None, status)
240
+ if receipt is not None:
241
+ return self.admitted(receipt)
242
+ self.unknown = True
243
+ wait = max(retry_after or 0, backoff)
244
+ backoff *= 2
245
+
246
+
247
+ def admit_source_submission(submission_id, *, api_origin, owner_id, token, transport=None, now=None,
248
+ sleep=time.sleep, clock=time.monotonic):
249
+ """Admit one ARTIFACTS_READY capture as one durable job and return its bound receipt.
250
+
251
+ ``api_origin`` and ``owner_id`` are the caller's current verified context; they must equal
252
+ the capture's pinned values before any request carries the token. Idempotent: an admitted
253
+ capture returns its stored receipt without a request. Raises SubmissionOutcomeUnknown when
254
+ the outcome stays unknown for the 60-second window, ReceiptPersistenceError when the
255
+ confirmed receipt cannot be stored, SourceSubmissionError otherwise, or SourceCaptureError
256
+ for local cache faults.
257
+ """
258
+ if type(token) is not str or not token or any(ord(char) < 0x21 or ord(char) > 0x7E for char in token):
259
+ raise SourceSubmissionError("authentication_required", submission_id)
260
+ if type(api_origin) is not str or not _https_origin(api_origin) or type(owner_id) is not str:
261
+ raise SourceSubmissionError("account_context_mismatch", submission_id)
262
+ transport = transport or UrllibSourceTransport()
263
+ # Admission needs only the descriptor: the payload may have idle-expired after publication.
264
+ with hold_capture_lease(submission_id, now=now, require_payload=False) as lease:
265
+ directory, descriptor = lease["path"], lease["descriptor"]
266
+ origin = descriptor.get("apiOrigin")
267
+ if type(origin) is not str or not _https_origin(origin):
268
+ raise SourceSubmissionError("capture_corrupt", submission_id)
269
+ # The token never reaches an origin, or acts for an owner, other than the capture's.
270
+ if origin.rstrip("/") != api_origin.rstrip("/") or descriptor.get("ownerId") != owner_id:
271
+ raise SourceSubmissionError("account_context_mismatch", submission_id)
272
+ state = descriptor.get("state")
273
+ if state == "admitted":
274
+ try:
275
+ receipt = validate_source_admission_receipt(descriptor.get("admissionReceipt"))
276
+ if receipt["submissionId"] != submission_id or receipt["requestDigest"] != descriptor["requestSha256"]:
277
+ raise ValueError
278
+ except (ValueError, KeyError, TypeError):
279
+ raise SourceSubmissionError("capture_corrupt", submission_id) from None
280
+ return receipt
281
+ if state == "rejected":
282
+ code = descriptor.get("rejectionCode")
283
+ raise SourceSubmissionError(code if type(code) is str else "submission_closed", submission_id)
284
+ if state not in ("artifacts_ready", "admitting"):
285
+ raise SourceSubmissionError("artifacts_not_ready", submission_id)
286
+ admission = _Admission(submission_id, descriptor, directory, origin, token, transport, sleep, clock)
287
+ if state == "admitting":
288
+ # Resume: the rebuilt request must equal the one that may already have been sent.
289
+ if descriptor.get("admissionRequest") != admission.request:
290
+ raise SourceSubmissionError("capture_corrupt", submission_id)
291
+ else:
292
+ admission.descriptor = _persist(directory, {**descriptor, "state": "admitting",
293
+ "admissionRequest": admission.request})
294
+ return admission.run(resumed=state == "admitting")
295
+
296
+
297
+ __all__ = ["admit_source_submission"]