workbench-tool git:20260925.8dd8ed3A

Immutable. This exact content never changes and is served at /api/v1/blob/0278d80f430d2b83.

---
name: workbench-tool
description: Use when adding, changing, deploying, or calling any NPA workbench tool; captures the API/CLI/SDK/container architecture and data-flow contract.
---

# 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 workflows follow the selected kubeconfig context namespace; an unset
namespace means `default`. Use `npa workbench namespace apply <name> --context
<context>` to create a namespace or reuse it unchanged, then `namespace context`
to prepare private kubeconfig and SkyPilot configuration using existing access.
The context command preserves existing SkyPilot settings and workload identities;
it does not create service accounts or grant RBAC. See
`docs/workbench/namespaces.md`. Registry pull-secret checks, model-cache lookup,
controller probes, and diagnostics follow the context namespace. Service commands
retain their explicit `--namespace` options and historical defaults.

## 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.