Metadata-Version: 2.4
Name: gridlinegpu
Version: 0.1.7
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
Provides-Extra: source-contract
Requires-Dist: rfc8785==0.1.4; extra == "source-contract"
Requires-Dist: unicodedata2==16.0.0; extra == "source-contract"

# 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()
search = client.search("workload.yaml")
print(search["coverage"], search["offers"])  # Catalog facts may be unknown; coverage may be partial.
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 search workload.yaml
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()` validates YAML and checks advertised task readiness before reserving or
uploading inputs. An explicitly unavailable managed ASR/LLM runtime, minimal managed
model resolver, or custom finite path raises `GridlineError` with code
`planning_unavailable`. Qualify the custom container and enable its launch path, or
use available managed runtime/full YAML settings as indicated by the error. Missing
task readiness fields on older servers preserve existing behavior. Custom endpoint
support remains a server planning decision; finite readiness does not describe it.
`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.

`search()` reads only YAML and connected-provider catalogs. It does not inspect or
upload referenced inputs, resolve a model or image, create a workload, or allocate a
GPU. `availability()["searchAvailable"]` is separate from planning and execution
readiness. Missing price, VRAM, capacity, or topology facts remain unknown. Partial
catalog coverage and unsupported execution remain visible; a search result is not a
launch quote. `scopeStatus: "empty_scope"` with `catalogCompleteness: "not_applicable"`
means no accounts were searched. Servers with catalog search disabled return a
search availability error. The CLI prints the same JSON response and also accepts
`gridline workload search --file workload.yaml`.

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.

## Source runs (beta)

Source runs send your own Python code and inputs to one GPU, run it as a finite job on an
operator-qualified **curated runtime**, and return your declared output files. They are in
an invite-only beta, funded by credits Gridline grants to design partners: there is no
top-up or payment step in the SDK. Install the source extra and turn the beta on in your
shell:

```sh
python -m pip install 'gridlinegpu[source-contract]>=0.1.7,<0.2'
export GRIDLINE_SOURCE_SDK_ENABLED=true
gridline setup --apply   # once: saves a private, scoped token file
```

Without `GRIDLINE_SOURCE_SDK_ENABLED=true`, `run()` raises `GridlineError` with code
`source_lane_disabled` and touches no file, token or network.

**The workload.** Put a `gridline.yaml` beside your code. Name a curated runtime instead of
declaring dependencies: `gridline/hf-torch-2.5@r1` provides CPython 3.11 and CUDA 12.4 with
`torch==2.5.1`, `transformers==4.46.3`, `accelerate==1.1.1`, `safetensors==0.4.5`,
`tokenizers==0.20.3`, `datasets==3.1.0`, `pandas==2.2.3`, `pyarrow==18.0.0` and
`numpy==1.26.4`. Do not add `python`, `requirements` or a lockfile next to a curated runtime
(refused as `source_runtime_curated_conflict`). A curated runtime named before this
SDK release or the server offers it is refused before anything is uploaded
(`curated_runtimes_unavailable`).

```yaml
version: 2
name: batch-generate
task:
  kind: application
  class: inference
  source:
    include: [job.py]
  command: [python, job.py]
runtime: gridline/hf-torch-2.5@r1
outputs:
  results:
    path: outputs/results.json
    max_bytes: 1048576
resources:
  gpu:
    count: 1
    minimum_vram_gib: 8
```

To set environment variables, use the mapping form:
`runtime: {curated: gridline/hf-torch-2.5@r1, environment: {MY_FLAG: "1"}}`. Temp, cache
and home directories are the platform's and cannot be redirected (`TMPDIR`,
`XDG_CACHE_HOME`, `HOME` and `HF_HOME` are refused).

**Limits during the beta.**
- Inputs: each local input file is at most 512 MiB.
- Outputs: declare each one under `outputs`. Each file is at most 128 MiB (`max_bytes`;
  8 MiB when omitted), at most 1 GiB in total, and at most 32 outputs per job.
- No network at run time (details below): the code, inputs and models it needs must
  arrive with the job.
- Leave out `budget` and `execution.deadline_seconds`: beta routing places jobs best-effort
  and refuses either constraint (`budget_feasibility_unknown` /
  `deadline_feasibility_unknown`).

**Run it.** `run()` validates, captures your selected files, uploads them and returns a
`JobHandle` once the job is admitted. Everything after that happens server-side.

```python
from gridlinegpu import GridlineClient, SubmissionOutcomeUnknown

client = GridlineClient()
try:
    job = client.run("gridline.yaml")
except SubmissionOutcomeUnknown as error:
    job = client.resume(error.submission_id)  # never run() again for the same submission
print(job.job_id)

result = job.wait()            # polls status; a local timeout never cancels the job
print(result.outcome, result.failure_code)
if result.succeeded:
    print(job.outputs("results"))  # verified files, written under results/
print(job.report()["settlement"])  # reserved, held, charged and released credits for this job
```

`job.status()` reads the current state without waiting, and `job.cancel()` requests a stop.
`client.history(limit=20)` lists your recent jobs, newest first. `report()` and `history()`
raise `report_unavailable` / `history_unavailable` until those reads are switched on for
the beta; the job itself is unaffected. A complete minimal
job is in `examples/workloads/curated-beta/`.

The rest of this section describes how source runs behave.

**Network.** Source runs have no network access, only Unix domain sockets. No TCP or UDP,
localhost included. So these fail: local HTTP servers (FastAPI, TGI), Ray, and any pip or
Hugging Face download at run time. vLLM (offline `LLM()` included) and NCCL or
torch.distributed (whatever the init method) are expected to fail. The error is typically
`PermissionError: [Errno 1] Operation not permitted`, or a library's own connection or
offline error. Declare models and inputs: they are fetched by the platform, not by your
code, and staged before your code starts. io_uring is not available either. If the
machine cannot enforce this isolation, your code does not start and the job ends with
`isolation_unsupported`: "The allocated machine cannot enforce the workload's required
isolation." Submit a new run; contact support if it repeats.

**Pinned models.** Gridline fetches each declared model at its pinned commit. If a pinned
model file has changed or is missing when it is fetched for your run, the run stops and
that attempt is used up; it is not retried. A machine was already started, so your
provider bills its time. During the canary, a used-up attempt costs at most about $0.50:
up to roughly 20 minutes (15 minutes of startup plus one 5-minute stop cycle) at the $1.50
per hour price ceiling, disk included.
Check that pinned models are still public, then run again.

**No GPU capacity.** If the selected GPU is not available, no machine is started and that
attempt is not charged. The status reads "The selected GPU was not available, so no
machine was started and this attempt was not charged. Trying the next matching offer." If
no matching GPU is left and no machine was started for the job, it ends with
`routing_attempts_exhausted`: "No matching GPU was available right now. No machine was
started for this job, so these attempts were not charged. Try again later or widen the GPU
choice." A machine that did start is billed by your provider for the time it ran, whatever
the outcome.
