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

python -m pip install 'gridlinegpu>=0.1.2,<0.2'

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.

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.

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"))

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.