File binding

A File becomes useful in two moves: it is uploaded into the workspace as a typed artifact, then bound into a slot on a backend vertex. Upload makes the artifact addressable; binding wires it into a graph that can run. The two are separate on purpose — the same uploaded File can be bound into many backends, and re-pointing a binding is how you swap one artifact for another without touching the component.

Uploading

Upload pushes a local file or directory into the workspace file store and registers it with a type, a display name, and a description:

ppl file upload <path> --type <file_type> --name "<display>" --readme @./README.mdCopy
ppl file upload <path> --type <file_type> --name "<display>" --readme @./README.md --config ./file.config.ymlCopy

--type is the load-bearing flag. It determines what kind of artifact the upload is and which file_schema slots will accept the resulting File. A wrong type here surfaces later — either the bind rejects it, or it binds and the runtime reaches an incompatible loader. The platform exposes a broad vocabulary (model artifacts, data fixtures, config and document types); the full list is in File types.

The Triton case is worth singling out because it is the most common upload mistake: --type model expects a Triton model repository directory passed as a directory path, not a pre-tarred archive. A description is also required — --readme inline or --readme @<path> from disk — because an upload that omits it stalls on an editor prompt that an agent flow cannot answer.

Carrying config with the file

A File can carry a --config document, and that is the pattern for an artifact that should bring its own runtime defaults:

tags:
  - detector
  - warehouse

config_schema:
  confidence_threshold:
    type: Double
    default: 0.35
  labels:
    type: String
    default: warehouse_labels

The tags are searchable workspace metadata. The config_schema defaults match by name: each entry whose name matches a parameter on the consuming vertex replaces that parameter's value at bind time. A detector that ships confidence=0.35 lands the backend at 0.35 with no separate parameter step. The side-effect is load-bearing — a value previously set with ppl backend change-parameter is replaced for the parameters the file owns, so anything in config_schema belongs to the file and everything else stays under graph control.

Binding to a vertex

Binding attaches a file_id to a named slot on a specific vertex:

ppl backend add-file <backend_id> --vertex <vertex_id> --key <file_schema_key> --file <file_id>Copy

--key is the slot the consuming component declared (see File schema). The platform validates that the File's type satisfies the slot, so a mismatch rejects at bind rather than at runtime. The bind is a single operation in the event-sourced backend log — it adds the binding, applies any config defaults the File carried, and becomes part of the backend's reproducible history. The next deploy picks it up, and the prior binding is undoable.

Proving the binding

A bound File means the platform accepted its type for the slot. It does not mean the artifact produces correct output: a detector can bind and load the wrong labels, a tokenizer can bind and mismatch the model vocabulary, a Triton repository can bind and reference a backend the container lacks. Each of those surfaces only when the runtime exercises the File. The proof step is a fixture run through the deployed backend — the cheap form is a live-backend test, the thorough form is the version-comparison loop in Prove behavior.

Related

• File schema — the slot a bind targets.
• File types — the file_type values a slot accepts.
• File upload and backend binding — the hands-on walkthrough.
• Prove behavior — confirm the bound File behaves.
• Backend operations — how the bind lands in the operation log.