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

python -m pip install 'gridlinegpu>=0.1.3,<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.

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. Current hosted artifact limits are 40 MiB per local input and 8 MiB per output.

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:

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.