gridlinegpu 0.1.2__tar.gz → 0.1.4__tar.gz

gridlinegpu-0.1.4/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: gridlinegpu
+Version: 0.1.4
+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. The package also installs
+the `gridline` command in the same Python environment on macOS and Linux.
+
+## Install
+
+```sh
+python -m pip install 'gridlinegpu>=0.1.4,<0.2'
+```
+
+Run browser setup once. It creates a 30-day scoped token in a private file, attempts to
+revoke the temporary browser session, and never prints the token. Keep the token file out of
+source control and AI chats.
+
+```sh
+gridline setup --apply
+```
+
+Use a YAML file beside its referenced inputs. Task, model, engine, providers, output,
+budget, and deadline belong in YAML rather than Python arguments.
+Server-advertised artifact limits govern each submission. Newer Gridline deployments
+use direct, signed resumable Storage uploads for large local inputs; older deployments
+may still cap inputs at 40 MiB and outputs at 8 MiB.
+
+```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"]
+ready = client.wait(job_id, timeout=7200)
+print(ready["job"]["outputs"], ready["job"]["outcome"])
+print(client.outputs(job_id, "results"))
+```
+
+The same installed package supports a terminal flow:
+
+```sh
+gridline workload validate --file workload.yaml
+gridline workload plan --file workload.yaml
+gridline workload run --file workload.yaml --apply --max-cost-usd 5 \
+  --idempotency-key my-job-2026-09-27
+gridline workload status JOB_ID
+gridline workload outputs JOB_ID --directory results
+```
+
+The paid `run` command plans a fresh quote, prints it, and asks for explicit confirmation.
+For an approved noninteractive run, add `--yes` and explicit `--profile production`
+alongside `--apply`, a cost ceiling, and an idempotency key. Cancellation similarly
+requires `--apply` and confirmation. A custom
+token path may be passed as global `--token-file` or through `GRIDLINE_API_TOKEN_FILE`.
+Workload commands also honor `GRIDLINE_API_TOKEN` when no token file is selected.
+The existing standalone Bun CLI remains available during transition; check which
+`gridline` executable your shell selects when both are installed. Run
+`python -m gridlinegpu` to choose this package's command explicitly.
+Use `gridline auth token list` to find a token ID and
+`gridline auth token revoke TOKEN_ID --apply` to revoke it. Both require fresh browser
+approval; the Python CLI never stores a privileged refresh token.
+After revoking a token, remove its local file before running setup again; setup never
+overwrites an existing file.
+
+`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.
+For finite jobs, `wait()` returns when outputs are complete, even if cleanup and billing
+leave `outcome` pending. Check `status()` later for final settlement.
+
+When worker progress is enabled on the hosted API/control service and supported by the
+deployed worker image, `status()` also returns optional `progress`:
+
+```python
+status = client.status(job_id)
+progress = status.get("progress")
+if progress:
+    for event in progress["events"]:
+        print(event["stage"], event["observedAt"])
+```
+
+Events are bounded, ordered worker reports for `progress["attemptId"]` and its fence.
+Stages include input staging, model preparation/loading, inference start/completion,
+and output upload. `observedAt` is the server's receipt time. Poll no faster than every
+five seconds; deduplicate by attempt/fence/stage. Missing progress or skipped stages
+mean unavailable evidence, not failure or an inferred stage. Inference completion
+does not imply stored outputs, job success, cleanup, or settled billing. `wait()` keeps
+its existing completion behavior and does not stream progress callbacks.

gridlinegpu-0.1.4/README.md

@@ -0,0 +1,94 @@
+# 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. The package also installs
+the `gridline` command in the same Python environment on macOS and Linux.
+
+## Install
+
+```sh
+python -m pip install 'gridlinegpu>=0.1.4,<0.2'
+```
+
+Run browser setup once. It creates a 30-day scoped token in a private file, attempts to
+revoke the temporary browser session, and never prints the token. Keep the token file out of
+source control and AI chats.
+
+```sh
+gridline setup --apply
+```
+
+Use a YAML file beside its referenced inputs. Task, model, engine, providers, output,
+budget, and deadline belong in YAML rather than Python arguments.
+Server-advertised artifact limits govern each submission. Newer Gridline deployments
+use direct, signed resumable Storage uploads for large local inputs; older deployments
+may still cap inputs at 40 MiB and outputs at 8 MiB.
+
+```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"]
+ready = client.wait(job_id, timeout=7200)
+print(ready["job"]["outputs"], ready["job"]["outcome"])
+print(client.outputs(job_id, "results"))
+```
+
+The same installed package supports a terminal flow:
+
+```sh
+gridline workload validate --file workload.yaml
+gridline workload plan --file workload.yaml
+gridline workload run --file workload.yaml --apply --max-cost-usd 5 \
+  --idempotency-key my-job-2026-09-27
+gridline workload status JOB_ID
+gridline workload outputs JOB_ID --directory results
+```
+
+The paid `run` command plans a fresh quote, prints it, and asks for explicit confirmation.
+For an approved noninteractive run, add `--yes` and explicit `--profile production`
+alongside `--apply`, a cost ceiling, and an idempotency key. Cancellation similarly
+requires `--apply` and confirmation. A custom
+token path may be passed as global `--token-file` or through `GRIDLINE_API_TOKEN_FILE`.
+Workload commands also honor `GRIDLINE_API_TOKEN` when no token file is selected.
+The existing standalone Bun CLI remains available during transition; check which
+`gridline` executable your shell selects when both are installed. Run
+`python -m gridlinegpu` to choose this package's command explicitly.
+Use `gridline auth token list` to find a token ID and
+`gridline auth token revoke TOKEN_ID --apply` to revoke it. Both require fresh browser
+approval; the Python CLI never stores a privileged refresh token.
+After revoking a token, remove its local file before running setup again; setup never
+overwrites an existing file.
+
+`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.
+For finite jobs, `wait()` returns when outputs are complete, even if cleanup and billing
+leave `outcome` pending. Check `status()` later for final settlement.
+
+When worker progress is enabled on the hosted API/control service and supported by the
+deployed worker image, `status()` also returns optional `progress`:
+
+```python
+status = client.status(job_id)
+progress = status.get("progress")
+if progress:
+    for event in progress["events"]:
+        print(event["stage"], event["observedAt"])
+```
+
+Events are bounded, ordered worker reports for `progress["attemptId"]` and its fence.
+Stages include input staging, model preparation/loading, inference start/completion,
+and output upload. `observedAt` is the server's receipt time. Poll no faster than every
+five seconds; deduplicate by attempt/fence/stage. Missing progress or skipped stages
+mean unavailable evidence, not failure or an inferred stage. Inference completion
+does not imply stored outputs, job success, cleanup, or settled billing. `wait()` keeps
+its existing completion behavior and does not stream progress callbacks.

{gridlinegpu-0.1.2 → gridlinegpu-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gridlinegpu"
-version = "0.1.2"
+version = "0.1.4"
 description = "Python client for Gridline YAML workload routing"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,6 +17,9 @@ classifiers = [
   "Operating System :: OS Independent",
 ]
 
+[project.scripts]
+gridline = "gridlinegpu.cli:main"
+
 [project.urls]
 Documentation = "https://gridlinegpu.com/cli"
 Repository = "https://github.com/GridlineGPU/gridline-gpu"

gridlinegpu-0.1.4/src/gridlinegpu/__main__.py

@@ -0,0 +1,6 @@
+"""Run the packaged customer CLI with ``python -m gridlinegpu``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gridlinegpu-0.1.4/src/gridlinegpu/cli.py

@@ -0,0 +1,198 @@
+"""Customer workload command installed by the gridlinegpu Python package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from decimal import Decimal, InvalidOperation
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any, Sequence, TextIO
+
+from .cli_auth import DeviceAuth, default_token_file
+from .client import GridlineClient
+from .errors import GridlineError, LaunchOutcomeUnknown
+
+_KEY = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\Z")
+
+
+def _version() -> str:
+    try:
+        return version("gridlinegpu")
+    except PackageNotFoundError:
+        return "development"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gridline", description="Gridline Python SDK and workload CLI")
+    parser.add_argument("--version", action="version", version=f"gridline Python CLI {_version()}")
+    parser.add_argument("--profile", choices=["production"],
+                        help="Explicit production target, required with --yes")
+    parser.add_argument("--token-file", type=Path,
+                        help="Private scoped token file (default: GRIDLINE_API_TOKEN_FILE or ~/.config/gridline/python-token)")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    setup = commands.add_parser("setup", help="Approve browser login and create a private workload token")
+    setup.add_argument("--output-file", type=Path, help="New token file; never overwrites")
+    setup.add_argument("--name", default="python-cli", help="Revocable token name")
+    setup.add_argument("--apply", action="store_true", help="Create scoped token after browser approval")
+
+    auth = commands.add_parser("auth", help="List or revoke scoped workload tokens")
+    auth_actions = auth.add_subparsers(dest="auth_action", required=True)
+    tokens = auth_actions.add_parser("token", help="Manage revocable scoped tokens")
+    token_actions = tokens.add_subparsers(dest="token_action", required=True)
+    token_actions.add_parser("list", help="List tokens after browser approval")
+    revoke = token_actions.add_parser("revoke", help="Revoke token after browser approval")
+    revoke.add_argument("token_id")
+    revoke.add_argument("--apply", action="store_true")
+
+    workload = commands.add_parser("workload", help="Validate, plan, launch, and inspect YAML jobs")
+    actions = workload.add_subparsers(dest="action", required=True)
+    for name, help_text in [
+        ("validate", "Validate YAML without allocating a GPU"),
+        ("plan", "Stage inputs and review a route without allocating a GPU"),
+        ("run", "Plan and explicitly launch the same fresh quote"),
+    ]:
+        action = actions.add_parser(name, help=help_text)
+        action.add_argument("--file", type=Path, required=True)
+        if name == "run":
+            action.add_argument("--max-cost-usd", required=True)
+            action.add_argument("--idempotency-key", required=True)
+            action.add_argument("--apply", action="store_true")
+            action.add_argument("--yes", action="store_true",
+                                help="Confirm reviewed plan in a noninteractive terminal")
+    for name, help_text in [
+        ("status", "Read job state"),
+        ("wait", "Wait for job output or terminal outcome"),
+        ("outputs", "Download verified output files"),
+        ("cancel", "Request job cancellation"),
+    ]:
+        action = actions.add_parser(name, help=help_text)
+        action.add_argument("job_id")
+        if name == "outputs":
+            action.add_argument("--directory", type=Path, required=True)
+        if name == "cancel":
+            action.add_argument("--apply", action="store_true")
+            action.add_argument("--yes", action="store_true")
+    actions.add_parser("availability", help="Show account planning and execution gates")
+    return parser
+
+
+def _emit(value: Any, output: TextIO) -> None:
+    print(json.dumps(value, indent=2, sort_keys=True, default=str), file=output)
+
+
+def _warn_unmeasured_duration(review: dict[str, Any], errors: TextIO) -> None:
+    quote = review.get("result", {}).get("quote", {})
+    selected = quote.get("selected", {}) if isinstance(quote, dict) else {}
+    duration = selected.get("expectedDurationMs", {}) if isinstance(selected, dict) else {}
+    if isinstance(duration, dict) and duration.get("source") == "customer_declared":
+        print("Gridline: task-cost ranking uses customer-declared duration, not measured "
+              "GPU-specific performance; estimate is not guaranteed.", file=errors)
+
+
+def _confirm(message: str, *, yes: bool, input_stream: TextIO,
+             output: TextIO) -> None:
+    if yes:
+        return
+    if not input_stream.isatty():
+        raise GridlineError("Interactive confirmation required; use --yes only after reviewing the plan",
+                            code="confirmation_required")
+    print(f"{message} Type yes to continue: ", end="", flush=True, file=output)
+    if input_stream.readline().strip().lower() != "yes":
+        raise GridlineError("Operation was not approved", code="not_approved")
+
+
+def _cost(value: str) -> Decimal:
+    try:
+        amount = Decimal(value)
+    except InvalidOperation as error:
+        raise ValueError("--max-cost-usd must be a positive amount") from error
+    if not amount.is_finite() or amount <= 0:
+        raise ValueError("--max-cost-usd must be a positive amount")
+    return amount
+
+
+def main(argv: Sequence[str] | None = None, *, input_stream: TextIO = sys.stdin,
+         output: TextIO = sys.stdout, errors: TextIO = sys.stderr) -> int:
+    args = _parser().parse_args(argv)
+    token_file = args.token_file or default_token_file()
+    try:
+        if args.command == "setup":
+            if not args.apply:
+                raise GridlineError("setup creates a scoped token; pass --apply to continue",
+                                    code="apply_required")
+            result = DeviceAuth().setup(args.output_file or token_file,
+                                        name=args.name, announce=lambda line: print(line, file=output))
+            _emit(result, output)
+            return 0
+        if args.command == "auth":
+            auth = DeviceAuth()
+            announce = lambda line: print(line, file=output)
+            if args.token_action == "list":
+                result = auth.tokens(announce=announce)
+            else:
+                if not args.apply:
+                    raise GridlineError("Token revocation requires --apply", code="apply_required")
+                result = auth.revoke(args.token_id, announce=announce)
+            _emit(result, output)
+            return 0
+
+        client = GridlineClient(token_file=args.token_file) if args.token_file else GridlineClient()
+        action = args.action
+        if action == "availability":
+            result = client.availability()
+        elif action == "validate":
+            result = client.validate(args.file)
+        elif action == "plan":
+            result = client.plan(args.file).review
+            _warn_unmeasured_duration(result, errors)
+        elif action == "run":
+            if not args.apply:
+                raise GridlineError("Paid launch requires --apply", code="apply_required")
+            if args.yes and args.profile != "production":
+                raise GridlineError("Noninteractive launch requires --profile production",
+                                    code="target_confirmation_required")
+            amount = _cost(args.max_cost_usd)
+            if not _KEY.fullmatch(args.idempotency_key):
+                raise ValueError("--idempotency-key must contain 1–128 safe characters")
+            planned = client.plan(args.file)
+            _emit(planned.review, output)
+            _warn_unmeasured_duration(planned.review, errors)
+            if planned.quote is None:
+                raise GridlineError("Router abstained; inspect plan coverage", code="plan_abstained")
+            _confirm(f"Launch with approved ceiling ${amount}?", yes=args.yes,
+                     input_stream=input_stream, output=output)
+            result = client.launch(planned, max_cost_usd=amount,
+                                   idempotency_key=args.idempotency_key)
+        elif action == "status":
+            result = client.status(args.job_id)
+        elif action == "wait":
+            result = client.wait(args.job_id)
+        elif action == "outputs":
+            result = client.outputs(args.job_id, args.directory)
+        elif action == "cancel":
+            if not args.apply:
+                raise GridlineError("Cancellation requires --apply", code="apply_required")
+            if args.yes and args.profile != "production":
+                raise GridlineError("Noninteractive cancellation requires --profile production",
+                                    code="target_confirmation_required")
+            _confirm(f"Cancel job {args.job_id}?", yes=args.yes,
+                     input_stream=input_stream, output=output)
+            result = client.cancel(args.job_id)
+        else:
+            raise ValueError("Unknown workload action")
+        _emit(result, output)
+        return 0
+    except LaunchOutcomeUnknown as error:
+        print(f"{error}. Check workload status before any retry.", file=errors)
+    except (GridlineError, ValueError, OSError) as error:
+        print(f"Gridline: {error}", file=errors)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())