gridlinegpu 0.1.0__tar.gz

gridlinegpu-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: gridlinegpu
+Version: 0.1.0
+Summary: Python client for Gridline YAML workload routing
+Author: Gridline GPU
+License: Proprietary
+Project-URL: Documentation, https://gridlinegpu.com/cli
+Project-URL: Repository, https://github.com/GridlineGPU/gridline-gpu
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML<7,>=6.0.2
+
+# Gridline Python SDK
+
+Submit one YAML workload through Gridline's authenticated API. The Python client stages
+files referenced by YAML, returns a route for review, then launches only that exact
+fresh plan when you supply a cost ceiling and idempotency key.
+
+## Install
+
+```sh
+python -m pip install gridlinegpu
+```
+
+Create a scoped token using the Gridline CLI after browser sign-in. The token stays in a
+private file; do not paste it into source code or an AI chat.
+
+```sh
+gridline --profile production auth login --apply
+gridline --profile production auth token create --name python-workloads --scopes read,routing:write --output-file "$HOME/.config/gridline/python-token" --apply
+export GRIDLINE_API_TOKEN_FILE="$HOME/.config/gridline/python-token"
+```
+
+Use a YAML file beside its referenced inputs. Task, model, engine, providers, output,
+budget, and deadline belong in YAML rather than Python arguments.
+Current hosted artifact limits are 40 MiB per local input and 8 MiB per output.
+
+```python
+from gridlinegpu import GridlineClient
+
+client = GridlineClient()
+plan = client.plan("workload.yaml")
+print(plan.review)  # Check selected GPU, exclusions, estimate, and maximum.
+
+# Launch only after reviewing the fresh plan and accepting its maximum spend.
+launch = client.launch(plan, max_cost_usd="5.00", idempotency_key="my-job-2026-09-27")
+job_id = launch["jobId"]
+print(client.wait(job_id, timeout=7200)["job"]["outcome"])
+print(client.outputs(job_id, "results"))
+```
+
+`plan()` stages input bytes but does not allocate a GPU. `launch()` never silently
+changes a plan or retries an ambiguous paid request. If launch outcome is unknown,
+inspect `LaunchOutcomeUnknown.workload_id` with the same idempotency key; do not use a
+new key. `outputs()` verifies byte count and SHA-256 before creating private files.
+Cancellation requests stop; cleanup and final provider billing can remain pending.

gridlinegpu-0.1.0/README.md

@@ -0,0 +1,44 @@
+# Gridline Python SDK
+
+Submit one YAML workload through Gridline's authenticated API. The Python client stages
+files referenced by YAML, returns a route for review, then launches only that exact
+fresh plan when you supply a cost ceiling and idempotency key.
+
+## Install
+
+```sh
+python -m pip install gridlinegpu
+```
+
+Create a scoped token using the Gridline CLI after browser sign-in. The token stays in a
+private file; do not paste it into source code or an AI chat.
+
+```sh
+gridline --profile production auth login --apply
+gridline --profile production auth token create --name python-workloads --scopes read,routing:write --output-file "$HOME/.config/gridline/python-token" --apply
+export GRIDLINE_API_TOKEN_FILE="$HOME/.config/gridline/python-token"
+```
+
+Use a YAML file beside its referenced inputs. Task, model, engine, providers, output,
+budget, and deadline belong in YAML rather than Python arguments.
+Current hosted artifact limits are 40 MiB per local input and 8 MiB per output.
+
+```python
+from gridlinegpu import GridlineClient
+
+client = GridlineClient()
+plan = client.plan("workload.yaml")
+print(plan.review)  # Check selected GPU, exclusions, estimate, and maximum.
+
+# Launch only after reviewing the fresh plan and accepting its maximum spend.
+launch = client.launch(plan, max_cost_usd="5.00", idempotency_key="my-job-2026-09-27")
+job_id = launch["jobId"]
+print(client.wait(job_id, timeout=7200)["job"]["outcome"])
+print(client.outputs(job_id, "results"))
+```
+
+`plan()` stages input bytes but does not allocate a GPU. `launch()` never silently
+changes a plan or retries an ambiguous paid request. If launch outcome is unknown,
+inspect `LaunchOutcomeUnknown.workload_id` with the same idempotency key; do not use a
+new key. `outputs()` verifies byte count and SHA-256 before creating private files.
+Cancellation requests stop; cleanup and final provider billing can remain pending.

gridlinegpu-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gridlinegpu"
+version = "0.1.0"
+description = "Python client for Gridline YAML workload routing"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Gridline GPU" }]
+dependencies = ["PyYAML>=6.0.2,<7"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Documentation = "https://gridlinegpu.com/cli"
+Repository = "https://github.com/GridlineGPU/gridline-gpu"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gridlinegpu-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gridlinegpu-0.1.0/src/gridlinegpu/__init__.py

@@ -0,0 +1,6 @@
+"""Gridline YAML workload client."""
+
+from .client import GridlineClient, PlannedWorkload
+from .errors import GridlineError, LaunchOutcomeUnknown
+
+__all__ = ["GridlineClient", "GridlineError", "LaunchOutcomeUnknown", "PlannedWorkload"]

gridlinegpu-0.1.0/src/gridlinegpu/client.py

@@ -0,0 +1,415 @@
+"""Small, synchronous client for Gridline's YAML-only workload API.
+
+All task settings live in YAML. Methods never select a GPU or retry a paid launch.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlparse
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+import yaml
+
+from .errors import GridlineError, LaunchOutcomeUnknown
+
+_API = "/api/workloads/yaml"
+_ID = re.compile(r"^[A-Za-z0-9_-]{1,80}$")
+_KEY = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+_SHA = re.compile(r"^[0-9a-f]{64}$")
+_MAX_YAML = 65_536
+_MAX_DOWNLOAD = 8 * 1024 * 1024
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, request: Request, fp: Any, code: int, msg: str, headers: Any, url: str) -> None:
+        return None
+
+
+@dataclass(frozen=True)
+class PlannedWorkload:
+    path: Path
+    yaml_sha256: str
+    workload_id: str
+    response: dict[str, Any]
+
+    @property
+    def quote(self) -> dict[str, Any] | None:
+        result = self.response.get("result", {})
+        return result.get("quote") if result.get("status") == "planned" else None
+
+    @property
+    def review(self) -> dict[str, Any]:
+        """Return server plan, including coverage, chosen GPU and price estimates."""
+        return self.response
+
+
+class GridlineClient:
+    """Use a scoped Gridline automation token; never put it in YAML or source code.
+
+    Create a token with ``gridline auth token create`` and pass its 0600 file path.
+    The SDK also reads ``GRIDLINE_API_TOKEN_FILE`` or ``GRIDLINE_API_TOKEN``.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str | None = None,
+        token_file: str | Path | None = None,
+        base_url: str = "https://gridlinegpu.com",
+        timeout: float = 30,
+        opener: Any = None,
+    ) -> None:
+        if token and token_file:
+            raise ValueError("Choose token or token_file")
+        if not token and not token_file:
+            token_file = os.getenv("GRIDLINE_API_TOKEN_FILE")
+            token = os.getenv("GRIDLINE_API_TOKEN") if not token_file else None
+        if not token and not token_file:
+            raise ValueError("Set GRIDLINE_API_TOKEN_FILE or pass token_file")
+        parsed = urlparse(base_url)
+        if parsed.scheme != "https" or not parsed.netloc or parsed.path not in ("", "/"):
+            raise ValueError("base_url must be an HTTPS origin")
+        if timeout <= 0 or timeout > 120:
+            raise ValueError("timeout must be between 0 and 120 seconds")
+        self._token = token
+        self._token_file = Path(token_file).expanduser() if token_file else None
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._opener = opener or build_opener(_NoRedirect())
+
+    def availability(self) -> dict[str, Any]:
+        return self._json("GET", f"{_API}/availability")
+
+    def validate(self, yaml_path: str | Path) -> dict[str, Any]:
+        _, source, _ = _read_yaml(yaml_path)
+        return self._json(
+            "POST", f"{_API}/validate", {"schemaVersion": 1, "yaml": source, "attachmentBindings": []}
+        )
+
+    def plan(self, yaml_path: str | Path) -> PlannedWorkload:
+        path, source, document = _read_yaml(yaml_path)
+        validated = self.validate(path)
+        available = self.availability()
+        if not available.get("planningAvailable"):
+            raise GridlineError("YAML planning is unavailable for this account", code="planning_unavailable")
+        inputs = _local_inputs(document)
+        if validated.get("requiredAttachments") != [name for name, _ in inputs]:
+            raise GridlineError("Input names differ from server validation", code="remote_contract_invalid")
+        if inputs and not available.get("artifactStagingAvailable"):
+            raise GridlineError("Input staging is unavailable for this account", code="staging_unavailable")
+        ceiling = available.get("maximumAttachmentBytes")
+        if not isinstance(ceiling, int) or ceiling < 1:
+            raise GridlineError("Invalid server attachment limit", code="remote_contract_invalid")
+        bindings = [self._stage(path.parent, name, item, ceiling) for name, item in inputs]
+        body = {"schemaVersion": 1, "yaml": source, "attachmentBindings": bindings}
+        stable = _sha(json.dumps(body, sort_keys=True, separators=(",", ":")).encode())
+        submitted = self._json("POST", f"{_API}/submit", body, key=f"sdk-submit-{stable}")
+        workload_id = _id(submitted.get("workloadId"), "workloadId")
+        result = self._json("POST", f"{_API}/{quote(workload_id)}/plan")
+        if result.get("workloadId") != workload_id or result.get("workloadHash") != submitted.get("workloadHash"):
+            raise GridlineError("Plan identity differs from submitted workload", code="remote_contract_invalid")
+        return PlannedWorkload(path, _sha(source.encode()), workload_id, result)
+
+    def launch(
+        self,
+        planned: PlannedWorkload,
+        *,
+        max_cost_usd: Decimal | str | int | float,
+        idempotency_key: str,
+    ) -> dict[str, Any]:
+        """Launch only same fresh plan after caller has reviewed it and set a ceiling."""
+        if not _KEY.fullmatch(idempotency_key):
+            raise ValueError("idempotency_key must contain 1–128 safe characters")
+        _, source, _ = _read_yaml(planned.path)
+        if _sha(source.encode()) != planned.yaml_sha256:
+            raise GridlineError("YAML changed since plan review", code="plan_changed")
+        earlier = planned.quote
+        if earlier is None:
+            raise GridlineError("Router abstained; inspect plan coverage", code="plan_abstained")
+        if not self.availability().get("executionEnabled"):
+            raise GridlineError("YAML execution is disabled for this account", code="execution_disabled")
+        micros = earlier.get("maximumTotalMicros")
+        if not isinstance(micros, int) or micros <= 0:
+            raise GridlineError("Plan has no valid maximum", code="remote_contract_invalid")
+        try:
+            accepted = Decimal(str(max_cost_usd))
+        except Exception as error:
+            raise ValueError("max_cost_usd must be a number") from error
+        if not accepted.is_finite() or accepted < Decimal(micros) / 1_000_000:
+            raise GridlineError("Approved cost ceiling is below YAML plan maximum", code="cost_limit")
+        current = self._json("POST", f"{_API}/{quote(planned.workload_id)}/plan")
+        fresh = current.get("result", {})
+        new_quote = fresh.get("quote", {})
+        if (
+            current.get("workloadId") != planned.workload_id
+            or fresh.get("status") != "planned"
+            or fresh.get("planHash") != planned.response.get("result", {}).get("planHash")
+            or new_quote.get("quoteHash") != earlier.get("quoteHash")
+            or new_quote.get("quoteId") != earlier.get("quoteId")
+            or not _future(new_quote.get("expiresAt"))
+        ):
+            raise GridlineError("Plan changed or expired; review a new plan", code="plan_changed")
+        consent = new_quote.get("fallbackConsent", {})
+        fallback_ids = consent.get("acceptedChoiceIds", []) if consent.get("mode") == "accepted_ordered" else []
+        launch = {
+            "schemaVersion": 1,
+            "quoteId": new_quote["quoteId"],
+            "quoteHash": new_quote["quoteHash"],
+            "planHash": fresh["planHash"],
+            "acceptedFallbackChoiceIds": fallback_ids,
+        }
+        try:
+            result = self._json(
+                "POST", f"{_API}/{quote(planned.workload_id)}/launch", launch, key=idempotency_key
+            )
+        except (GridlineError, OSError) as error:
+            if isinstance(error, GridlineError) and error.status is not None and error.status < 500:
+                raise
+            try:
+                recovered = self.lookup_launch(planned.workload_id, idempotency_key)
+            except (GridlineError, OSError):
+                recovered = None
+            if recovered and recovered.get("planHash") == fresh["planHash"]:
+                return recovered
+            raise LaunchOutcomeUnknown(planned.workload_id, idempotency_key) from error
+        if result.get("workloadId") != planned.workload_id or result.get("planHash") != fresh["planHash"]:
+            raise GridlineError("Launch identity mismatch", code="remote_contract_invalid")
+        return result
+
+    def lookup_launch(self, workload_id: str, idempotency_key: str) -> dict[str, Any] | None:
+        try:
+            return self._json(
+                "POST", f"{_API}/launches/lookup",
+                {"schemaVersion": 1, "workloadId": _id(workload_id, "workloadId"), "idempotencyKey": idempotency_key},
+            )
+        except GridlineError as error:
+            if error.status == 404:
+                return None
+            raise
+
+    def status(self, job_id: str) -> dict[str, Any]:
+        result = self._json("GET", f"{_API}/jobs/{quote(_id(job_id, 'jobId'))}")
+        if result.get("job", {}).get("jobId") != job_id:
+            raise GridlineError("Job identity mismatch", code="remote_contract_invalid")
+        return result
+
+    def wait(self, job_id: str, *, timeout: float = 3600, interval: float = 5) -> dict[str, Any]:
+        if timeout <= 0 or interval <= 0:
+            raise ValueError("timeout and interval must be positive")
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.status(job_id)
+            state = result["job"].get("outcome")
+            if state in ("succeeded", "failed", "cancelled", "timed_out"):
+                return result
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Job {job_id} did not finish before timeout")
+            time.sleep(min(interval, max(0, deadline - time.monotonic())))
+
+    def outputs(self, job_id: str, directory: str | Path) -> dict[str, Any]:
+        job_id = _id(job_id, "jobId")
+        result = self._json("GET", f"{_API}/jobs/{quote(job_id)}/output")
+        if result.get("jobId") != job_id:
+            raise GridlineError("Output identity mismatch", code="remote_contract_invalid")
+        if result.get("state") == "pending":
+            return {"jobId": job_id, "state": "pending", "downloaded": []}
+        manifest = result.get("manifest", {})
+        target = Path(directory)
+        target.mkdir(parents=True, exist_ok=True)
+        downloaded = []
+        for item in manifest.get("outputs", []):
+            if not item.get("completed"):
+                continue
+            name = item.get("name")
+            artifact_id = _id(item.get("artifactId"), "artifactId")
+            if not isinstance(name, str) or name in ("", ".", "..") or Path(name).name != name:
+                raise GridlineError("Unsafe output name", code="remote_contract_invalid")
+            digest, size = item.get("sha256"), item.get("bytes")
+            if not isinstance(digest, str) or not _SHA.fullmatch(digest) or not isinstance(size, int) or size > _MAX_DOWNLOAD:
+                raise GridlineError("Invalid output digest or size", code="remote_contract_invalid")
+            grant = self._json("GET", f"{_API}/jobs/{quote(job_id)}/output/{quote(artifact_id)}/grant")
+            if (grant.get("jobId"), grant.get("artifactId"), grant.get("sha256"), grant.get("byteLength")) != (job_id, artifact_id, digest, size):
+                raise GridlineError("Output grant identity mismatch", code="remote_contract_invalid")
+            access = grant.get("download", {})
+            if not _future(access.get("expiresAt")):
+                raise GridlineError("Output grant expired", code="grant_expired")
+            data = self._bytes("GET", access.get("url"), maximum=_MAX_DOWNLOAD)
+            if len(data) != size or _sha(data) != digest:
+                raise GridlineError("Output checksum mismatch", code="output_hash_mismatch")
+            destination = target / name
+            with destination.open("xb") as handle:
+                os.chmod(destination, 0o600)
+                handle.write(data)
+            downloaded.append({"name": name, "path": str(destination), "sha256": digest})
+        return {"jobId": job_id, "state": result.get("state"), "downloaded": downloaded,
+                "missingRequiredOutputs": manifest.get("missingRequiredOutputs", [])}
+
+    def cancel(self, job_id: str) -> dict[str, Any]:
+        job_id = _id(job_id, "jobId")
+        result = self._json("POST", f"{_API}/jobs/{quote(job_id)}/cancel")
+        if result.get("jobId") != job_id:
+            raise GridlineError("Cancellation identity mismatch", code="remote_contract_invalid")
+        return result
+
+    def _stage(self, base: Path, name: str, item: dict[str, Any], ceiling: int) -> dict[str, Any]:
+        path = _local_path(base, item["path"])
+        data = _bounded_file(path, min(ceiling, 40 * 1024 * 1024))
+        digest = _sha(data)
+        if item.get("sha256") not in (None, digest) or item.get("bytes") not in (None, len(data)):
+            raise GridlineError(f"Input {name} differs from YAML digest or size", code="input_changed")
+        format_name = item["format"]
+        reserved = self._json(
+            "POST", f"{_API}/attachments",
+            {"schemaVersion": 1, "format": format_name, "sha256": digest, "byteLength": len(data)},
+            key=f"sdk-attachment-{_sha((format_name + digest).encode())}",
+        )
+        artifact_id = _id(reserved.get("artifactId"), "artifactId")
+        if (reserved.get("sha256"), reserved.get("byteLength"), reserved.get("format")) != (digest, len(data), format_name):
+            raise GridlineError("Attachment reservation mismatch", code="remote_contract_invalid")
+        if reserved.get("state") != "ready":
+            upload = reserved.get("upload", {})
+            if upload.get("method") != "PUT" or not isinstance(upload.get("headers", {}).get("Authorization"), str):
+                raise GridlineError("Invalid attachment upload grant", code="remote_contract_invalid")
+            self._bytes("PUT", upload.get("url"), data=data, headers={"Authorization": upload["headers"]["Authorization"]}, maximum=16_384)
+            confirmed = self._json("POST", f"{_API}/attachments/{quote(artifact_id)}/confirm")
+            if (confirmed.get("state"), confirmed.get("artifactId"), confirmed.get("sha256")) != ("ready", artifact_id, digest):
+                raise GridlineError("Attachment confirmation mismatch", code="remote_contract_invalid")
+        return {"logicalName": name, "artifactId": artifact_id, "sha256": digest, "bytes": len(data)}
+
+    def _json(self, method: str, path: str, body: dict[str, Any] | None = None, *, key: str | None = None) -> dict[str, Any]:
+        headers = {"Authorization": f"Bearer {self._read_token()}", "Accept": "application/json"}
+        if key:
+            headers["Idempotency-Key"] = key
+        data = None if body is None else json.dumps(body, separators=(",", ":")).encode()
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        raw = self._bytes(method, self._base_url + path, data=data, headers=headers, maximum=2 * 1024 * 1024)
+        try:
+            value = json.loads(raw)
+        except (ValueError, UnicodeDecodeError) as error:
+            raise GridlineError("Invalid JSON response", code="remote_contract_invalid") from error
+        if not isinstance(value, dict):
+            raise GridlineError("Invalid response shape", code="remote_contract_invalid")
+        return value
+
+    def _bytes(self, method: str, url: str | None, *, data: bytes | None = None,
+               headers: dict[str, str] | None = None, maximum: int) -> bytes:
+        if not isinstance(url, str) or urlparse(url).scheme != "https":
+            raise GridlineError("Grant URL must use HTTPS", code="remote_contract_invalid")
+        request = Request(url, data=data, headers=headers or {}, method=method)
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                raw = response.read(maximum + 1)
+        except HTTPError as error:
+            detail = {}
+            try:
+                detail = json.loads(error.read(16_384))
+            except (ValueError, UnicodeDecodeError):
+                pass
+            info = detail.get("error", {}) if isinstance(detail, dict) else {}
+            code = info.get("code", "http_error") if isinstance(info, dict) else "http_error"
+            raise GridlineError(f"Gridline request failed: HTTP {error.code}", code=code, status=error.code) from error
+        except URLError as error:
+            raise GridlineError("Network request failed", code="network_error") from error
+        if len(raw) > maximum:
+            raise GridlineError("Response exceeded size limit", code="response_too_large")
+        return raw
+
+    def _read_token(self) -> str:
+        if self._token_file:
+            stat = self._token_file.stat()
+            if self._token_file.is_symlink() or not self._token_file.is_file() or stat.st_mode & 0o077 or stat.st_size > 256:
+                raise GridlineError("Token file must be a private regular file", code="token_file_invalid")
+            token = self._token_file.read_text(encoding="utf-8").strip()
+        else:
+            token = self._token or ""
+        if not re.fullmatch(r"gla_[A-Za-z0-9_-]{43}", token):
+            raise GridlineError("Invalid Gridline automation token", code="token_invalid")
+        return token
+
+
+def _read_yaml(value: str | Path) -> tuple[Path, str, dict[str, Any]]:
+    path = Path(value).expanduser().absolute()
+    data = _bounded_file(path, _MAX_YAML)
+    try:
+        source = data.decode("utf-8")
+        document = yaml.safe_load(source)
+    except (UnicodeDecodeError, yaml.YAMLError) as error:
+        raise GridlineError("Invalid YAML encoding or syntax", code="invalid_yaml") from error
+    if not isinstance(document, dict):
+        raise GridlineError("YAML root must be a mapping", code="invalid_yaml")
+    return path, source, document
+
+
+def _local_inputs(document: dict[str, Any]) -> list[tuple[str, dict[str, Any]]]:
+    if "apiVersion" in document:
+        inputs = document.get("inputs", [])
+        if not isinstance(inputs, list):
+            raise GridlineError("Invalid YAML inputs", code="invalid_yaml")
+        found = []
+        for item in inputs:
+            if not isinstance(item, dict):
+                raise GridlineError("Invalid YAML input", code="invalid_yaml")
+            source = item.get("source", {})
+            if isinstance(source, dict) and source.get("type") == "package_file":
+                found.append((item["name"], {"path": source["path"], "format": item["format"],
+                                              "sha256": source.get("sha256"), "bytes": source.get("bytes")}))
+        return found
+    inputs = document.get("inputs", {})
+    if not isinstance(inputs, dict):
+        raise GridlineError("Invalid YAML inputs", code="invalid_yaml")
+    return [(name, {"path": item["file"], "format": item["format"],
+                    "sha256": item.get("sha256"), "bytes": item.get("bytes")})
+            for name, item in inputs.items() if isinstance(item, dict) and "file" in item]
+
+
+def _local_path(base: Path, value: str) -> Path:
+    if not isinstance(value, str) or not value or Path(value).is_absolute() or ".." in Path(value).parts:
+        raise GridlineError("Input path must stay beside YAML", code="invalid_input_path")
+    path = (base / value).resolve()
+    if not path.is_relative_to(base.resolve()):
+        raise GridlineError("Input path leaves YAML directory", code="invalid_input_path")
+    return path
+
+
+def _bounded_file(path: Path, maximum: int) -> bytes:
+    if path.is_symlink() or not path.is_file():
+        raise GridlineError("File must be a readable regular file", code="invalid_file")
+    if path.stat().st_size < 1 or path.stat().st_size > maximum:
+        raise GridlineError("File exceeds allowed size", code="file_size")
+    with path.open("rb") as handle:
+        data = handle.read(maximum + 1)
+    if not data or len(data) > maximum:
+        raise GridlineError("File exceeds allowed size", code="file_size")
+    return data
+
+
+def _id(value: Any, label: str) -> str:
+    if not isinstance(value, str) or not _ID.fullmatch(value):
+        raise GridlineError(f"Invalid {label}", code="remote_contract_invalid")
+    return value
+
+
+def _sha(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _future(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    try:
+        moment = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return moment.tzinfo is not None and moment > datetime.now(timezone.utc)
+    except ValueError:
+        return False

gridlinegpu-0.1.0/src/gridlinegpu/errors.py

@@ -0,0 +1,20 @@
+"""Public, secret-free SDK errors."""
+
+
+class GridlineError(Exception):
+    def __init__(self, message: str, *, code: str = "gridline_error", status: int | None = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class LaunchOutcomeUnknown(GridlineError):
+    """Paid launch may have been accepted; reuse the same idempotency key."""
+
+    def __init__(self, workload_id: str, idempotency_key: str):
+        super().__init__(
+            "Launch outcome unknown. Check status or retry lookup with the same idempotency key.",
+            code="launch_outcome_unknown",
+        )
+        self.workload_id = workload_id
+        self.idempotency_key = idempotency_key

gridlinegpu-0.1.0/src/gridlinegpu.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: gridlinegpu
+Version: 0.1.0
+Summary: Python client for Gridline YAML workload routing
+Author: Gridline GPU
+License: Proprietary
+Project-URL: Documentation, https://gridlinegpu.com/cli
+Project-URL: Repository, https://github.com/GridlineGPU/gridline-gpu
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML<7,>=6.0.2
+
+# Gridline Python SDK
+
+Submit one YAML workload through Gridline's authenticated API. The Python client stages
+files referenced by YAML, returns a route for review, then launches only that exact
+fresh plan when you supply a cost ceiling and idempotency key.
+
+## Install
+
+```sh
+python -m pip install gridlinegpu
+```
+
+Create a scoped token using the Gridline CLI after browser sign-in. The token stays in a
+private file; do not paste it into source code or an AI chat.
+
+```sh
+gridline --profile production auth login --apply
+gridline --profile production auth token create --name python-workloads --scopes read,routing:write --output-file "$HOME/.config/gridline/python-token" --apply
+export GRIDLINE_API_TOKEN_FILE="$HOME/.config/gridline/python-token"
+```
+
+Use a YAML file beside its referenced inputs. Task, model, engine, providers, output,
+budget, and deadline belong in YAML rather than Python arguments.
+Current hosted artifact limits are 40 MiB per local input and 8 MiB per output.
+
+```python
+from gridlinegpu import GridlineClient
+
+client = GridlineClient()
+plan = client.plan("workload.yaml")
+print(plan.review)  # Check selected GPU, exclusions, estimate, and maximum.
+
+# Launch only after reviewing the fresh plan and accepting its maximum spend.
+launch = client.launch(plan, max_cost_usd="5.00", idempotency_key="my-job-2026-09-27")
+job_id = launch["jobId"]
+print(client.wait(job_id, timeout=7200)["job"]["outcome"])
+print(client.outputs(job_id, "results"))
+```
+
+`plan()` stages input bytes but does not allocate a GPU. `launch()` never silently
+changes a plan or retries an ambiguous paid request. If launch outcome is unknown,
+inspect `LaunchOutcomeUnknown.workload_id` with the same idempotency key; do not use a
+new key. `outputs()` verifies byte count and SHA-256 before creating private files.
+Cancellation requests stop; cleanup and final provider billing can remain pending.

gridlinegpu-0.1.0/src/gridlinegpu.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/gridlinegpu/__init__.py
+src/gridlinegpu/client.py
+src/gridlinegpu/errors.py
+src/gridlinegpu.egg-info/PKG-INFO
+src/gridlinegpu.egg-info/SOURCES.txt
+src/gridlinegpu.egg-info/dependency_links.txt
+src/gridlinegpu.egg-info/requires.txt
+src/gridlinegpu.egg-info/top_level.txt
+tests/test_client.py

gridlinegpu-0.1.0/src/gridlinegpu.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gridlinegpu-0.1.0/src/gridlinegpu.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML<7,>=6.0.2

gridlinegpu-0.1.0/src/gridlinegpu.egg-info/top_level.txt

@@ -0,0 +1 @@
+gridlinegpu

gridlinegpu-0.1.0/tests/test_client.py

@@ -0,0 +1,116 @@
+import io
+import json
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from gridlinegpu import GridlineClient, GridlineError
+
+
+TOKEN = "gla_" + "a" * 43
+YAML = """name: speech
+task:
+  operation: asr_transcription
+  model: Systran/faster-whisper-large-v3
+inputs:
+  audio: { file: audio.wav, format: wav }
+limits: { maxCostUSD: 5, deadline: 1h }
+"""
+
+
+class Response(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+class FakeOpener:
+    def __init__(self):
+        self.calls = []
+        self.changed = False
+        self.expiry = (datetime.now(timezone.utc) + timedelta(minutes=2)).isoformat()
+
+    def open(self, request, timeout):
+        path = request.full_url.removeprefix("https://gridlinegpu.com")
+        self.calls.append((request.get_method(), path, request.headers, request.data))
+        if path == "/api/workloads/yaml/validate":
+            result = {"schemaVersion": 1, "requiredAttachments": ["audio"]}
+        elif path == "/api/workloads/yaml/availability":
+            result = {"schemaVersion": 1, "planningAvailable": True, "executionEnabled": True,
+                      "artifactStagingAvailable": True, "maximumAttachmentBytes": 1024}
+        elif path == "/api/workloads/yaml/attachments":
+            result = {"artifactId": "input_1", "sha256": self.digest, "byteLength": 4,
+                      "format": "wav", "state": "ready"}
+        elif path == "/api/workloads/yaml/submit":
+            result = {"workloadId": "yaml_1", "workloadHash": "b" * 64}
+        elif path == "/api/workloads/yaml/yaml_1/plan":
+            result = {"workloadId": "yaml_1", "workloadHash": "b" * 64,
+                      "result": {"status": "planned", "planHash": "x" * 64 if self.changed else "c" * 64,
+                                 "quote": {"quoteId": "quote_1", "quoteHash": "d" * 64,
+                                           "expiresAt": self.expiry, "maximumTotalMicros": 5_000_000,
+                                           "fallbackConsent": {"mode": "none"}}}}
+        elif path == "/api/workloads/yaml/yaml_1/launch":
+            result = {"workloadId": "yaml_1", "planHash": "c" * 64, "jobId": "job_1"}
+        elif path == "/api/workloads/yaml/jobs/job_1":
+            result = {"job": {"jobId": "job_1", "outcome": "succeeded"}}
+        elif path == "/api/workloads/yaml/jobs/job_1/output":
+            result = {"jobId": "job_1", "state": "available", "manifest": {"outputs": [{
+                "name": "result.json", "artifactId": "output_1", "sha256": self.output_digest,
+                "bytes": 2, "completed": True}], "missingRequiredOutputs": []}}
+        elif path == "/api/workloads/yaml/jobs/job_1/output/output_1/grant":
+            result = {"jobId": "job_1", "artifactId": "output_1", "sha256": self.output_digest,
+                      "byteLength": 2, "download": {"url": "https://storage.example/result",
+                          "expiresAt": self.expiry}}
+        elif path == "https://storage.example/result":
+            return Response(b"{}")
+        else:
+            raise AssertionError(f"Unexpected request: {path}")
+        return Response(json.dumps(result).encode())
+
+
+class ClientTest(unittest.TestCase):
+    def setUp(self):
+        import hashlib
+        self.folder = tempfile.TemporaryDirectory()
+        self.addCleanup(self.folder.cleanup)
+        root = Path(self.folder.name)
+        (root / "workload.yaml").write_text(YAML)
+        (root / "audio.wav").write_bytes(b"RIFF")
+        self.path = root / "workload.yaml"
+        self.opener = FakeOpener()
+        self.opener.digest = hashlib.sha256(b"RIFF").hexdigest()
+        self.opener.output_digest = hashlib.sha256(b"{}").hexdigest()
+        self.client = GridlineClient(token=TOKEN, opener=self.opener)
+
+    def test_plan_launch_and_verified_download(self):
+        plan = self.client.plan(self.path)
+        self.assertEqual(plan.workload_id, "yaml_1")
+        self.assertFalse(any(path.endswith("/launch") for _, path, _, _ in self.opener.calls))
+        launched = self.client.launch(plan, max_cost_usd="5", idempotency_key="test-job-1")
+        self.assertEqual(launched["jobId"], "job_1")
+        self.assertEqual(self.client.wait("job_1", timeout=1)["job"]["outcome"], "succeeded")
+        saved = self.client.outputs("job_1", Path(self.folder.name) / "results")
+        self.assertEqual(Path(saved["downloaded"][0]["path"]).read_bytes(), b"{}")
+        self.assertRaises(FileExistsError, self.client.outputs, "job_1", Path(self.folder.name) / "results")
+
+    def test_changed_plan_cannot_launch(self):
+        plan = self.client.plan(self.path)
+        self.opener.changed = True
+        with self.assertRaisesRegex(GridlineError, "changed"):
+            self.client.launch(plan, max_cost_usd="5", idempotency_key="same-key")
+        self.assertFalse(any(path.endswith("/launch") for _, path, _, _ in self.opener.calls))
+
+    def test_cost_ceiling_and_yaml_change_cannot_launch(self):
+        plan = self.client.plan(self.path)
+        with self.assertRaisesRegex(GridlineError, "ceiling"):
+            self.client.launch(plan, max_cost_usd="4.99", idempotency_key="same-key")
+        self.path.write_text(YAML + "# changed\n")
+        with self.assertRaisesRegex(GridlineError, "changed"):
+            self.client.launch(plan, max_cost_usd="5", idempotency_key="same-key")
+
+
+if __name__ == "__main__":
+    unittest.main()