gridlinegpu 0.1.10__tar.gz → 0.2.0__tar.gz

{gridlinegpu-0.1.10 → gridlinegpu-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridlinegpu
-Version: 0.1.10
+Version: 0.2.0
 Summary: Python client for Gridline YAML workload routing
 Author: Gridline GPU
 License: Proprietary
@@ -28,13 +28,13 @@ Linux.
 1. **Sign up** at https://gridlinegpu.com/signup and verify your email.
 2. **Request access** at https://gridlinegpu.com/get-started: accept the partner beta terms and
    describe your use case in a few lines.
-3. **Wait for approval.** Gridline approves each request by hand and grants your account beta
-   credit; the get-started page shows the status. There is no payment step: jobs draw on that
-   credit.
+3. **Wait for approval.** Gridline checks each request; approval grants your account beta
+   credit, and the get-started page shows the status. There is no payment step: jobs draw on
+   that credit.
 4. **Install** the SDK with the source extra (Python 3.10 or newer):
 
    ```sh
-   python -m pip install 'gridlinegpu[source-contract]>=0.1.10,<0.2'
+   python -m pip install 'gridlinegpu[source-contract]>=0.2.0,<0.3'
    ```
 
 5. **Create a token** once. Browser approval saves a private, scoped token file; it is never
@@ -151,6 +151,116 @@ compiler. Without it, the YAML commands and `client.access()` still work and sou
 `source_dependencies_missing` with the install line. The "Source runs (beta)" section below has the
 limits, costs and failure codes.
 
+## Functions: `App`, `@app.function`, `.remote()` and `.spawn()` (preview)
+
+Decorate a Python function instead of writing YAML. Each call becomes one ordinary source job,
+with the same access, credit holds, limits, isolation and billing as `run()`:
+
+```python
+import gridlinegpu as gl
+
+app = gl.App("transcribe")
+image = gl.Image.curated("gridline/hf-torch-2.5@r1")
+
+@app.function(image=image, gpu="any:16GB", outputs={"transcript": "transcript.txt"})
+def transcribe(audio: gl.File, language: str = "en") -> dict:
+    text = run_model(audio.path, language)
+    (gl.output_dir() / "transcript.txt").write_text(text)
+    return {"chars": len(text)}
+
+print(transcribe.remote(gl.File("audio/a.flac")))   # waits; files land in gridline-outputs/
+call = transcribe.spawn(gl.File("audio/b.flac"))     # returns once the job is admitted
+print(call.job_id, call.get())
+```
+
+How the parts work:
+
+- **Code.** The function's module and the local modules and packages it imports (read from the
+  source, never run) are sent with the job. Add data files with `include=["data/*.json"]`. Inside
+  the job, `gridlinegpu` is a small stand-in, so the module imports in any image; only the
+  function runs, never `local_entrypoint` or `if __name__ == "__main__"` code.
+- **Arguments and return values** are JSON data plus `gl.File` arguments. There is no pickle.
+  Each `gl.File` is uploaded as an input file (at most 512 MiB). The return value is at most
+  8 MiB. Larger results are files written under `gl.output_dir()` and declared in `outputs`
+  (at most 128 MiB each).
+- **Options:**
+  - `gpu="any:<N>GB"` sets the minimum GPU memory (default 8 GB).
+  - `models={"base": gl.Model.hf(repo, revision)}` is fetched by the platform and found at
+    `gl.model_path("base")`.
+  - `kind="training"` marks a training job.
+  - `timeout=` is a local limit, enforced best-effort while the SDK waits; past it the job is
+    cancelled.
+- **Not yet available:** named GPU types, `max_price`, `capacity` and built images. Each
+  raises when used.
+
+**Many calls: `.map()` and `.starmap()`.** These return a `MapRun`; iterating it submits the calls
+and yields their values. Nothing is submitted before that.
+
+```python
+for value in transcribe.map([gl.File(path) for path in sorted(Path("audio").glob("*.flac"))],
+                           kwargs={"language": "en"}):
+    print(value)
+results = list(transcribe.starmap([(gl.File("a.flac"), "en"), (gl.File("b.flac"), "de")],
+                                  max_spend_usd=5.0, return_exceptions=True))
+```
+
+A map runs one of two ways:
+
+- **Warm pool.** With `max_spend_usd` (and `warm=None`, the default) or `warm=True`, a worker
+  pool of 1 to `max_workers` (at most 4) GPU workers runs the calls. The module loads once per
+  worker.
+  - Each call is one item, delivered at least once, with exactly one result committed.
+  - The function's `timeout` is the item timeout (60 to 3,600 seconds).
+  - A pooled function declares at most 7 outputs, each a file name directly in
+    `gl.output_dir()`.
+  - An account without pools falls back to chunks, unless `warm=True`.
+- **Chunks of ordinary jobs.** `per_job` calls per job (default 16; 1 when the function
+  declares outputs), at most `max_running` jobs at once (default 2, the account's
+  running-jobs limit). A call that raises is recorded and the job runs its next call.
+
+Common to both:
+
+- Values come back in input order (`order="completed"` yields each as it finishes).
+- `@app.function(retries=N)` (0 to 4) gives each failed call N more attempts.
+- A call that still fails raises `gl.FunctionError` (`function_raised`, the job's failure code,
+  or `item_dead`). With `return_exceptions=True` it is yielded instead.
+- Each job's or item's files land under `gridline-outputs/<function>/<job or pool id>/`.
+
+Inside a job, a decorated function is the plain function: call other functions with
+`.local()`. `.remote()` and `.map()` are refused there, because the job has no network.
+
+**Fine-tuning in one call.** `gl.finetune.lora()` and `gl.finetune.qlora()` submit one training job on
+`gridline/hf-finetune-2.5@r1`. The job runs Gridline's recipe, trl `SFTTrainer` with a peft LoRA:
+bf16 for LoRA, 4-bit NF4 for QLoRA. The platform fetches the base model at its pinned revision;
+the dataset is a JSON-lines file whose rows have a `text` field:
+
+```python
+run = gl.finetune.qlora(gl.Model.hf("HuggingFaceTB/SmolLM2-135M", revision="93efa2f097d58c2a74874c7e644dbc9b0cee75a2"),
+                        "data/train.jsonl", eval_dataset="data/eval.jsonl", epochs=2, rank=16)
+metrics = run.get(outputs_dir="adapters/smol")   # adapter_model.safetensors, adapter_config.json, metrics.json
+print(metrics["eval_loss_before"], metrics["eval_loss_after"])
+```
+
+Options: `epochs`, `learning_rate`, `rank`, `alpha`, `dropout`, `max_seq_length`,
+`batch_size`, `max_steps`, `target_modules` and `gpu` (default `"any:16GB"`). The adapter is at
+most 128 MiB. Full fine-tunes (all weights) are not offered yet.
+
+**From the command line.** Running submits paid jobs, so it needs `--apply`:
+
+```sh
+gridline app show transcribe_app.py                 # each function's generated YAML; nothing is sent
+gridline run --apply transcribe_app.py --folder audio   # the local_entrypoint, arguments typed from it
+gridline run --apply transcribe_app.py::transcribe --audio a.flac --language en
+gridline run --apply --detach transcribe_app.py::transcribe --audio a.flac   # print the job id and exit
+gridline pools status <pool id>                     # also: items, close, cancel --apply
+```
+
+`gridline run` imports the file the way `python app.py` would. Each `--name value` is converted
+by the parameter's annotation or default: `int`, `float`, `bool`, `str`, or `gl.File` for a path.
+- **Failures:** a failed job raises `gl.FunctionError` with the job's failure code. An uncertain
+  submission raises `SubmissionOutcomeUnknown`, as `run()` does; continue it with
+  `transcribe.resume(error.submission_id)`.
+
 ## Many files: batches of ordinary jobs
 
 `client.run_batch()` (0.1.10 or newer) runs one workload over many files, at most `per_job` files
@@ -272,7 +382,7 @@ files referenced by YAML, returns a route for review, then launches only that ex
 fresh plan when you supply a cost ceiling and idempotency key.
 
 ```sh
-python -m pip install 'gridlinegpu>=0.1.10,<0.2'
+python -m pip install 'gridlinegpu>=0.2.0,<0.3'
 ```
 
 Run browser setup once. It creates a 30-day scoped token in a private file, attempts to
@@ -386,7 +496,7 @@ step in the SDK. Request access first (see the quickstart above); `client.access
 `gridline access` show where your request stands.
 
 ```sh
-python -m pip install 'gridlinegpu[source-contract]>=0.1.10,<0.2'
+python -m pip install 'gridlinegpu[source-contract]>=0.2.0,<0.3'
 gridline setup --apply   # once: saves a private, scoped token file
 gridline access          # "approved" before your first run
 ```

{gridlinegpu-0.1.10 → gridlinegpu-0.2.0}/README.md

@@ -10,13 +10,13 @@ Linux.
 1. **Sign up** at https://gridlinegpu.com/signup and verify your email.
 2. **Request access** at https://gridlinegpu.com/get-started: accept the partner beta terms and
    describe your use case in a few lines.
-3. **Wait for approval.** Gridline approves each request by hand and grants your account beta
-   credit; the get-started page shows the status. There is no payment step: jobs draw on that
-   credit.
+3. **Wait for approval.** Gridline checks each request; approval grants your account beta
+   credit, and the get-started page shows the status. There is no payment step: jobs draw on
+   that credit.
 4. **Install** the SDK with the source extra (Python 3.10 or newer):
 
    ```sh
-   python -m pip install 'gridlinegpu[source-contract]>=0.1.10,<0.2'
+   python -m pip install 'gridlinegpu[source-contract]>=0.2.0,<0.3'
    ```
 
 5. **Create a token** once. Browser approval saves a private, scoped token file; it is never
@@ -133,6 +133,116 @@ compiler. Without it, the YAML commands and `client.access()` still work and sou
 `source_dependencies_missing` with the install line. The "Source runs (beta)" section below has the
 limits, costs and failure codes.
 
+## Functions: `App`, `@app.function`, `.remote()` and `.spawn()` (preview)
+
+Decorate a Python function instead of writing YAML. Each call becomes one ordinary source job,
+with the same access, credit holds, limits, isolation and billing as `run()`:
+
+```python
+import gridlinegpu as gl
+
+app = gl.App("transcribe")
+image = gl.Image.curated("gridline/hf-torch-2.5@r1")
+
+@app.function(image=image, gpu="any:16GB", outputs={"transcript": "transcript.txt"})
+def transcribe(audio: gl.File, language: str = "en") -> dict:
+    text = run_model(audio.path, language)
+    (gl.output_dir() / "transcript.txt").write_text(text)
+    return {"chars": len(text)}
+
+print(transcribe.remote(gl.File("audio/a.flac")))   # waits; files land in gridline-outputs/
+call = transcribe.spawn(gl.File("audio/b.flac"))     # returns once the job is admitted
+print(call.job_id, call.get())
+```
+
+How the parts work:
+
+- **Code.** The function's module and the local modules and packages it imports (read from the
+  source, never run) are sent with the job. Add data files with `include=["data/*.json"]`. Inside
+  the job, `gridlinegpu` is a small stand-in, so the module imports in any image; only the
+  function runs, never `local_entrypoint` or `if __name__ == "__main__"` code.
+- **Arguments and return values** are JSON data plus `gl.File` arguments. There is no pickle.
+  Each `gl.File` is uploaded as an input file (at most 512 MiB). The return value is at most
+  8 MiB. Larger results are files written under `gl.output_dir()` and declared in `outputs`
+  (at most 128 MiB each).
+- **Options:**
+  - `gpu="any:<N>GB"` sets the minimum GPU memory (default 8 GB).
+  - `models={"base": gl.Model.hf(repo, revision)}` is fetched by the platform and found at
+    `gl.model_path("base")`.
+  - `kind="training"` marks a training job.
+  - `timeout=` is a local limit, enforced best-effort while the SDK waits; past it the job is
+    cancelled.
+- **Not yet available:** named GPU types, `max_price`, `capacity` and built images. Each
+  raises when used.
+
+**Many calls: `.map()` and `.starmap()`.** These return a `MapRun`; iterating it submits the calls
+and yields their values. Nothing is submitted before that.
+
+```python
+for value in transcribe.map([gl.File(path) for path in sorted(Path("audio").glob("*.flac"))],
+                           kwargs={"language": "en"}):
+    print(value)
+results = list(transcribe.starmap([(gl.File("a.flac"), "en"), (gl.File("b.flac"), "de")],
+                                  max_spend_usd=5.0, return_exceptions=True))
+```
+
+A map runs one of two ways:
+
+- **Warm pool.** With `max_spend_usd` (and `warm=None`, the default) or `warm=True`, a worker
+  pool of 1 to `max_workers` (at most 4) GPU workers runs the calls. The module loads once per
+  worker.
+  - Each call is one item, delivered at least once, with exactly one result committed.
+  - The function's `timeout` is the item timeout (60 to 3,600 seconds).
+  - A pooled function declares at most 7 outputs, each a file name directly in
+    `gl.output_dir()`.
+  - An account without pools falls back to chunks, unless `warm=True`.
+- **Chunks of ordinary jobs.** `per_job` calls per job (default 16; 1 when the function
+  declares outputs), at most `max_running` jobs at once (default 2, the account's
+  running-jobs limit). A call that raises is recorded and the job runs its next call.
+
+Common to both:
+
+- Values come back in input order (`order="completed"` yields each as it finishes).
+- `@app.function(retries=N)` (0 to 4) gives each failed call N more attempts.
+- A call that still fails raises `gl.FunctionError` (`function_raised`, the job's failure code,
+  or `item_dead`). With `return_exceptions=True` it is yielded instead.
+- Each job's or item's files land under `gridline-outputs/<function>/<job or pool id>/`.
+
+Inside a job, a decorated function is the plain function: call other functions with
+`.local()`. `.remote()` and `.map()` are refused there, because the job has no network.
+
+**Fine-tuning in one call.** `gl.finetune.lora()` and `gl.finetune.qlora()` submit one training job on
+`gridline/hf-finetune-2.5@r1`. The job runs Gridline's recipe, trl `SFTTrainer` with a peft LoRA:
+bf16 for LoRA, 4-bit NF4 for QLoRA. The platform fetches the base model at its pinned revision;
+the dataset is a JSON-lines file whose rows have a `text` field:
+
+```python
+run = gl.finetune.qlora(gl.Model.hf("HuggingFaceTB/SmolLM2-135M", revision="93efa2f097d58c2a74874c7e644dbc9b0cee75a2"),
+                        "data/train.jsonl", eval_dataset="data/eval.jsonl", epochs=2, rank=16)
+metrics = run.get(outputs_dir="adapters/smol")   # adapter_model.safetensors, adapter_config.json, metrics.json
+print(metrics["eval_loss_before"], metrics["eval_loss_after"])
+```
+
+Options: `epochs`, `learning_rate`, `rank`, `alpha`, `dropout`, `max_seq_length`,
+`batch_size`, `max_steps`, `target_modules` and `gpu` (default `"any:16GB"`). The adapter is at
+most 128 MiB. Full fine-tunes (all weights) are not offered yet.
+
+**From the command line.** Running submits paid jobs, so it needs `--apply`:
+
+```sh
+gridline app show transcribe_app.py                 # each function's generated YAML; nothing is sent
+gridline run --apply transcribe_app.py --folder audio   # the local_entrypoint, arguments typed from it
+gridline run --apply transcribe_app.py::transcribe --audio a.flac --language en
+gridline run --apply --detach transcribe_app.py::transcribe --audio a.flac   # print the job id and exit
+gridline pools status <pool id>                     # also: items, close, cancel --apply
+```
+
+`gridline run` imports the file the way `python app.py` would. Each `--name value` is converted
+by the parameter's annotation or default: `int`, `float`, `bool`, `str`, or `gl.File` for a path.
+- **Failures:** a failed job raises `gl.FunctionError` with the job's failure code. An uncertain
+  submission raises `SubmissionOutcomeUnknown`, as `run()` does; continue it with
+  `transcribe.resume(error.submission_id)`.
+
 ## Many files: batches of ordinary jobs
 
 `client.run_batch()` (0.1.10 or newer) runs one workload over many files, at most `per_job` files
@@ -254,7 +364,7 @@ files referenced by YAML, returns a route for review, then launches only that ex
 fresh plan when you supply a cost ceiling and idempotency key.
 
 ```sh
-python -m pip install 'gridlinegpu>=0.1.10,<0.2'
+python -m pip install 'gridlinegpu>=0.2.0,<0.3'
 ```
 
 Run browser setup once. It creates a 30-day scoped token in a private file, attempts to
@@ -368,7 +478,7 @@ step in the SDK. Request access first (see the quickstart above); `client.access
 `gridline access` show where your request stands.
 
 ```sh
-python -m pip install 'gridlinegpu[source-contract]>=0.1.10,<0.2'
+python -m pip install 'gridlinegpu[source-contract]>=0.2.0,<0.3'
 gridline setup --apply   # once: saves a private, scoped token file
 gridline access          # "approved" before your first run
 ```

{gridlinegpu-0.1.10 → gridlinegpu-0.2.0}/pyproject.toml

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

{gridlinegpu-0.1.10 → gridlinegpu-0.2.0}/src/gridlinegpu/__init__.py

@@ -2,16 +2,20 @@
 
 from ._batch import BatchResult, BatchRun, batch
 from ._batch import slot_names as batch_slots
+from .app import (App, File, Function, FunctionCall, FunctionError, Image, MapRun, Model, Output, model_path,
+                  output_dir)
 from .client import GridlineClient, PlannedWorkload
 from .errors import (
     GridlineError, LaunchOutcomeUnknown, OutputsIncomplete, ReceiptPersistenceError, SubmissionOutcomeUnknown,
     WaitTimeout, WorkloadValidationError,
 )
+from . import finetune  # noqa: E402 - after app's names, which its job module imports
 
 __all__ = [
-    "BatchResult", "BatchRun", "GridlineClient", "GridlineError", "LaunchOutcomeUnknown", "OutputsIncomplete",
-    "PlannedWorkload", "ReceiptPersistenceError", "SubmissionOutcomeUnknown", "WaitTimeout", "WorkloadValidationError",
-    "batch", "batch_slots",
+    "App", "BatchResult", "BatchRun", "File", "Function", "FunctionCall", "FunctionError", "GridlineClient",
+    "GridlineError", "Image", "LaunchOutcomeUnknown", "MapRun", "Model", "Output", "OutputsIncomplete", "PlannedWorkload",
+    "ReceiptPersistenceError", "SubmissionOutcomeUnknown", "WaitTimeout", "WorkloadValidationError", "batch",
+    "batch_slots", "finetune", "model_path", "output_dir",
 ]
 
 

gridlinegpu-0.2.0/src/gridlinegpu/_app_entry.py

@@ -0,0 +1,114 @@
+"""The job's entry for ``gridlinegpu.App`` functions (stdlib only; staged as _gridline_entry.py).
+
+Reads the call file, imports the app module (its ``gridlinegpu`` is the staged stub) and calls
+the plain function once per call, writing the JSON results as the declared return output. With
+``strict`` (one ``spawn()`` call) an exception propagates: the traceback goes to the job's log
+and the job fails as any job whose code fails. Otherwise (a chunk of ``map()`` calls) each
+exception is recorded for its call and the next call runs.
+
+In a pool worker (``mode: pool``) the module is imported once and each item is one call: its
+input is a zip of ``call.json`` and the call's files, and its outputs are the item's output
+directory (the JSON return value plus the files the function wrote there). An exception hands
+the item back failed with its type and message; the pool retries it up to its attempts.
+"""
+import importlib
+import json
+import os
+import shutil
+import sys
+import tempfile
+import traceback
+import zipfile
+
+ROOT = os.path.dirname(os.path.abspath(__file__))
+ERROR_TEXT = 2_000
+
+
+def error_of(exception):
+    """A call's exception as JSON: its type and last line, bounded (the log has the traceback)."""
+    return {"type": type(exception).__name__, "message": str(exception)[:ERROR_TEXT]}
+
+
+def run_call(gridlinegpu, function, call, paths):
+    args = gridlinegpu.decode_value(call["args"], paths)
+    kwargs = gridlinegpu.decode_value(call["kwargs"], paths)
+    return gridlinegpu.encode_value(function(*args, **kwargs), where="return value")
+
+
+def unpack(gridlinegpu, archive_path, scratch):
+    """(call, local paths of its files) from one item's zip, its files written under scratch."""
+    with zipfile.ZipFile(archive_path) as archive:
+        call = json.loads(archive.read(gridlinegpu.ITEM_CALL))
+        paths = []
+        for index, name in enumerate(call["files"]):
+            target = os.path.join(scratch, os.path.basename(gridlinegpu.input_path(index, name)))
+            with archive.open(f"files/{index}") as source, open(target, "wb") as sink:
+                shutil.copyfileobj(source, sink, 1_048_576)
+            paths.append(target)
+    return call, paths
+
+
+def serve_pool(gridlinegpu, function):
+    from gridlinegpu import worker
+
+    for item in worker.items():
+        scratch = tempfile.mkdtemp(prefix="gridline-item-")
+        try:
+            call, paths = unpack(gridlinegpu, item.input_path, scratch)
+            gridlinegpu._current_output = str(item.output_dir)
+            value = run_call(gridlinegpu, function, call, paths)
+            data = json.dumps({"results": [{"value": value}]}, allow_nan=False, separators=(",", ":"))
+            if len(data) > gridlinegpu.RETURN_MAX_BYTES:
+                raise ValueError("the return value is larger than 8 MiB; write it under output_dir() instead")
+            with open(os.path.join(item.output_dir, os.path.basename(gridlinegpu.RETURN_PATH)), "w",
+                      encoding="utf-8") as handle:
+                handle.write(data)
+        except Exception as exception:  # noqa: BLE001 - the item goes back failed; the log has the traceback
+            traceback.print_exc()
+            error = error_of(exception)
+            try:
+                item.fail(f"{error['type']}: {error['message']}")
+            except worker.WorkerError:
+                traceback.print_exc()
+            continue
+        finally:
+            gridlinegpu._current_output = None
+            shutil.rmtree(scratch, ignore_errors=True)
+        try:
+            item.done()
+        except worker.WorkerError:
+            traceback.print_exc()  # handed back (outputs invalid) or retried elsewhere
+
+
+def main():
+    os.environ.setdefault("GRIDLINE_APP_ROOT", ROOT)
+    sys.path.insert(0, ROOT)
+    import gridlinegpu  # the staged stub, which owns the call codec
+
+    with open(os.path.join(ROOT, gridlinegpu.CALL_FILE), encoding="utf-8") as handle:
+        document = json.load(handle)
+    function = getattr(importlib.import_module(document["module"]), document["function"])
+    if document.get("mode") == "pool":
+        serve_pool(gridlinegpu, function)
+        return
+    paths = [os.path.join(ROOT, path) for path in document["files"]]
+    results = []
+    for call in document["calls"]:
+        if document["strict"]:
+            results.append({"value": run_call(gridlinegpu, function, call, paths)})
+            continue
+        try:
+            results.append({"value": run_call(gridlinegpu, function, call, paths)})
+        except Exception as exception:  # noqa: BLE001 - recorded per call; the log has the traceback
+            traceback.print_exc()
+            results.append({"error": error_of(exception)})
+    data = json.dumps({"results": results}, allow_nan=False, separators=(",", ":")).encode("utf-8")
+    if len(data) > gridlinegpu.RETURN_MAX_BYTES:
+        raise ValueError("the return values are larger than 8 MiB; write results under output_dir() instead")
+    gridlinegpu.output_dir()
+    with open(os.path.join(ROOT, gridlinegpu.RETURN_PATH), "wb") as handle:
+        handle.write(data)
+
+
+if __name__ == "__main__":
+    main()

gridlinegpu-0.2.0/src/gridlinegpu/_app_remote.py

@@ -0,0 +1,175 @@
+"""The job side of ``gridlinegpu.App`` (stdlib only).
+
+``App`` stages this file's text as ``gridlinegpu/__init__.py`` beside the app's own modules, so
+the app module imports inside the GPU job even when the image has no ``gridlinegpu`` (or an
+older one): its ``App``, ``Image``, ``Model`` and ``File`` names exist and do nothing, and the
+job's entry calls the plain function. The local package imports the call codec from here, so
+both sides encode a call the same way. Nothing here touches the network or a credential.
+"""
+import json
+import math
+import os
+import pathlib
+
+CALL_FILE = "_gridline_call.json"
+ENTRY_FILE = "_gridline_entry.py"
+RETURN_OUTPUT = "gl_return"
+RETURN_PATH = "outputs/_gridline_return.json"
+RETURN_MAX_BYTES = 8 * 1024 * 1024
+_MARK = "$gridline"
+_ROOT = pathlib.Path(os.environ.get("GRIDLINE_APP_ROOT") or os.getcwd())
+# A pool worker sets this to the current item's output directory while the item runs.
+_current_output = None
+ITEM_CALL = "call.json"
+
+
+class File:
+    """A file argument. Locally, a path to send; inside the job, the staged input (read-only)."""
+
+    def __init__(self, path):
+        self.path = pathlib.Path(path)
+
+    @property
+    def name(self):
+        return self.path.name
+
+    def __fspath__(self):
+        return os.fspath(self.path)
+
+    def __repr__(self):
+        return f"File({os.fspath(self.path)!r})"
+
+
+def encode_value(value, files=None, *, where="argument"):
+    """JSON-safe form of ``value``. ``File`` objects become references and, when ``files`` is a
+    list, are appended to it (locally: the files to stage). Anything that is not JSON data or a
+    ``File`` raises TypeError: calls carry JSON data and files only (no pickle)."""
+    if value is None or type(value) in (bool, str, int):
+        return value
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise TypeError(f"a function {where} must be finite (NaN and infinity are not JSON)")
+        return value
+    if isinstance(value, File):
+        if files is None:
+            raise TypeError(f"a function {where} cannot be a File; write it under output_dir() instead")
+        files.append(value)
+        return {_MARK: "file", "index": len(files) - 1, "name": value.name}
+    if type(value) in (list, tuple):
+        return [encode_value(item, files, where=where) for item in value]
+    if type(value) is dict:
+        encoded = {}
+        for key, item in value.items():
+            if type(key) is not str:
+                raise TypeError(f"a function {where}'s dictionary keys must be strings")
+            if key == _MARK:
+                raise TypeError(f"a function {where}'s dictionary cannot use the key {_MARK!r}")
+            encoded[key] = encode_value(item, files, where=where)
+        return encoded
+    if isinstance(value, os.PathLike):
+        raise TypeError(f"a function {where} that is a path must be wrapped: gridlinegpu.File({os.fspath(value)!r}) "
+                        "sends the file; str(path) sends the text")
+    raise TypeError(f"a function {where} must be JSON data or gridlinegpu.File, not {type(value).__name__}")
+
+
+def decode_value(value, file_paths=None):
+    """The inverse of ``encode_value``; ``file_paths[index]`` is where each file landed."""
+    if type(value) is list:
+        return [decode_value(item, file_paths) for item in value]
+    if type(value) is dict:
+        if value.get(_MARK) == "file":
+            if file_paths is None:
+                raise ValueError("a file reference outside a call")
+            return File(file_paths[value["index"]])
+        return {key: decode_value(item, file_paths) for key, item in value.items()}
+    return value
+
+
+def input_name(index):
+    return f"arg_{index}"
+
+
+def input_path(index, name):
+    suffix = "".join(pathlib.PurePosixPath(name).suffixes)[-16:]
+    return f"inputs/{input_name(index)}{suffix}"
+
+
+def output_dir():
+    """The directory whose declared files become the call's outputs (in a pool, the item's)."""
+    if _current_output is not None:
+        return pathlib.Path(_current_output)
+    directory = _ROOT / "outputs"
+    directory.mkdir(exist_ok=True)
+    return directory
+
+
+def model_path(name):
+    """Where the platform staged the model declared as ``models={name: Model.hf(...)}``."""
+    return _ROOT / "models" / name
+
+
+class _Inert:
+    """Accepts any construction or chained call; the job never builds or routes anything."""
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __getattr__(self, name):
+        if name.startswith("__"):
+            raise AttributeError(name)
+        return lambda *args, **kwargs: self
+
+    @classmethod
+    def _make(cls, *args, **kwargs):
+        return cls()
+
+
+class Image(_Inert):
+    curated = from_base = from_dockerfile = from_registry = classmethod(_Inert._make.__func__)
+
+
+class Model(_Inert):
+    hf = classmethod(_Inert._make.__func__)
+
+
+class Output(_Inert):
+    pass
+
+
+class Secret(_Inert):
+    from_name = classmethod(_Inert._make.__func__)
+
+
+class FunctionError(Exception):
+    pass
+
+
+def _in_job(name):
+    def refuse(*args, **kwargs):
+        raise RuntimeError(f".{name}() is not available inside a Gridline job (no network); call .local()")
+    return refuse
+
+
+def _plain(fn):
+    """The plain function, with ``.local`` (itself) and the remote calls refused."""
+    fn.local = fn
+    for name in ("remote", "spawn", "map", "starmap"):
+        setattr(fn, name, _in_job(name))
+    return fn
+
+
+class App:
+    """Inside the job: decorators return the plain function and the entrypoint never runs."""
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def function(self, *args, **kwargs):
+        if args and callable(args[0]) and not kwargs:
+            return _plain(args[0])
+        return _plain
+
+    def local_entrypoint(self, *args, **kwargs):
+        if args and callable(args[0]) and not kwargs:
+            return args[0]
+        return lambda fn: fn