Workbench Tool Pattern

This skill is the architectural contract. For the procedures built on it:

• Adding a tool end to end: skills/workflows/add-workbench-tool/SKILL.md
• Writing the CLI and SDK: skills/atomic/npa-cli-conventions/SKILL.md
• Wiring it into a workflow: skills/atomic/toolref-argv-contract/SKILL.md
• Validating before you push: skills/atomic/pre-pr-validation/SKILL.md

Every workbench tool is a containerized FastAPI service. The container is the unit of deployment; the service endpoint is the unit of invocation; the CLI and SDK are clients.

Each capability must have one source of truth. Put behavior in the service or shared implementation layer, then have all access paths call it. Never duplicate training, inference, import, or status logic separately across API, CLI, and SDK layers.

Three Access Modes

• API: HTTP endpoints exposed by the FastAPI service.
• CLI: npa workbench <tool> ....
• SDK: npa.sdk.workbench.<tool>.

Standard Endpoints

Workbench services should expose these standard surfaces unless a tool-specific skill documents an exception:

• GET /health
• POST /train or POST /run
• GET /status
• GET /system-info
• GET /list

Deployment

Resolve the endpoint for the operator's explicitly selected artifact bucket through the supported private configuration. Pass that verified endpoint when deploying or configuring a tool; do not inherit another cluster's regional endpoint. Prove the selected bucket and credentials together with health-preflight before provisioning or submitting.

Kubernetes namespace split:

• workbench: deployed workbench services.
• default: SkyPilot task pods.

Cross-Tool Data Flow

Tools communicate through S3, never by directly calling each other for data transfer. All tool commands must support --input-path and --output-path so pipelines can pass S3 URIs across stages.

Exception / gotcha: a few tools historically use --input-uri / --output-uri instead (e.g. npa workbench cosmos2 transfer, cosmos3 reason). When you wire a tool into an npa.workflow toolRef (npa/src/npa/orchestration/npa_workflow/catalog.py), the argv template MUST match that tool's actual CLI option names and include required flags (e.g. --run-id). A mismatch passes validate-spec/plan-spec but crashes on real submit with an unknown-option error. Verify against the CLI signature, and keep catalog.py and docs/workbench/npa-workflow-tool-catalog.md in sync. Prefer standardizing new tools on --input-path/--output-path.

The full contract — literal-value rules, wrapper templates, reachability, image routing, and the local check that proves an argv can run — is in skills/atomic/toolref-argv-contract/SKILL.md.

Generated Video Publication

Publish generated video bytes unchanged unless the tool explicitly declares a required transform, such as removing repeated conditioning frames at segment joins. Never alpha-blend source and generated frames to claim preservation of motion, geometry, or identity: unaligned scenes produce double exposures. Source-motion preservation belongs in model conditioning and quality validation.

Keep source video, model output, and labeled comparison media distinct. Record any declared transform and retain its input artifacts. Validate the exact bytes delivered to downstream consumers; a source-heavy composite must not substitute for the model output in an acceptance evaluation. Test publication with model output that differs from the source, and verify artifact hashes after readback.

The PAIDF Cosmos3 publisher enforces this through a zero-only legacy source_motion_weight setting and publishes an output SHA-256. The restriction applies to every workflow invoking workbench.cosmos3.generate_variants, independently of dataset, camera, prompt, or workflow name. Transfer 2.5 and the general Cosmos3 publisher already upload model videos directly; Nano augmentation removes duplicate conditioning prefixes and concatenates without blending.