gridlinegpu 0.1.3__tar.gz → 0.1.5__tar.gz

{gridlinegpu-0.1.3 → gridlinegpu-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridlinegpu
-Version: 0.1.3
+Version: 0.1.5
 Summary: Python client for Gridline YAML workload routing
 Author: Gridline GPU
 License: Proprietary
@@ -23,7 +23,7 @@ the `gridline` command in the same Python environment on macOS and Linux.
 ## Install
 
 ```sh
-python -m pip install 'gridlinegpu>=0.1.3,<0.2'
+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
@@ -36,12 +36,16 @@ 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.
+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.
 
@@ -56,6 +60,7 @@ 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 \
@@ -79,6 +84,13 @@ 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
@@ -86,3 +98,32 @@ new key. `outputs()` verifies byte count and SHA-256 before creating private fil
 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.

{gridlinegpu-0.1.3 → gridlinegpu-0.1.5}/README.md

@@ -8,7 +8,7 @@ the `gridline` command in the same Python environment on macOS and Linux.
 ## Install
 
 ```sh
-python -m pip install 'gridlinegpu>=0.1.3,<0.2'
+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
@@ -21,12 +21,16 @@ 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.
+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.
 
@@ -41,6 +45,7 @@ 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 \
@@ -64,6 +69,13 @@ 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
@@ -71,3 +83,32 @@ new key. `outputs()` verifies byte count and SHA-256 before creating private fil
 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.

{gridlinegpu-0.1.3 → gridlinegpu-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gridlinegpu"
-version = "0.1.3"
+version = "0.1.5"
 description = "Python client for Gridline YAML workload routing"
 readme = "README.md"
 requires-python = ">=3.10"

{gridlinegpu-0.1.3 → gridlinegpu-0.1.5}/src/gridlinegpu/cli.py

@@ -49,8 +49,11 @@ def _parser() -> argparse.ArgumentParser:
     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")
+    workload = commands.add_parser("workload", help="Search catalogs, plan, launch, and inspect YAML jobs")
     actions = workload.add_subparsers(dest="action", required=True)
+    search = actions.add_parser("search", help="Search connected-provider catalogs without staging inputs")
+    search.add_argument("yaml_path", type=Path, nargs="?")
+    search.add_argument("--file", type=Path)
     for name, help_text in [
         ("validate", "Validate YAML without allocating a GPU"),
         ("plan", "Stage inputs and review a route without allocating a GPU"),
@@ -77,7 +80,7 @@ def _parser() -> argparse.ArgumentParser:
         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")
+    actions.add_parser("availability", help="Show account search, planning, and execution gates")
     return parser
 
 
@@ -85,6 +88,15 @@ 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:
@@ -136,10 +148,15 @@ def main(argv: Sequence[str] | None = None, *, input_stream: TextIO = sys.stdin,
         action = args.action
         if action == "availability":
             result = client.availability()
+        elif action == "search":
+            if (args.yaml_path is None) == (args.file is None):
+                raise ValueError("workload search requires YAML or --file YAML, exactly once")
+            result = client.search(args.yaml_path or args.file)
         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")
@@ -151,6 +168,7 @@ def main(argv: Sequence[str] | None = None, *, input_stream: TextIO = sys.stdin,
                 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,