Metadata-Version: 2.4
Name: gridlinegpu
Version: 0.1.3
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.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.

```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.
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"]
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.
