cdf-simulation

Files (9)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• class-filter-taxonomy.md · references/
• fixed-defaults.md · references/
• payload-contract.md · references/
• reference-flows.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# cdf-simulation

Turns DIG Flow Catalog prompt templates and equivalent direct requests into
`cdf` jobs through the declarative Python API. This skill is the
**component-owned guidance** for `cdf-simulation`: a caller supplies a board
USD and output root, this skill builds and compiles the job, and the caller
can pass the payload to its own executor. Airflow may inject those required
inputs, or the caller may provide them directly. If either is missing and
interaction is possible, ask once. All optional ambiguity is resolved with
fixed, documented defaults. If a request truly cannot be served (an
unsupported defect type, a non-USD input), say so rather than guessing at a
fake capability or silently doing nothing.

**This skill does not execute.** It produces a validated `CDFJob` build and
its compiled JobOrder payload, then stops. An Airflow DAG or another executor
chosen by the caller performs rendering.

## Catalog coverage

This skill implements five DIG Flow Catalog rows, all taking a board USD as
input:

| # | Row | Status |
|---|---|---|
| 1 | Golden board (THT) | Implemented |
| 2 | Variation type (THT pin geometry) | Implemented |
| 3 | Good images (SMT) | Implemented |
| 4 | Structural defects (SMT) | Implemented |
| 5 | Texture defects (SMT solder) | Implemented, except `bridge` (unsupported — see below) |

### Reference flows

Beside the catalog rows, the skill serves the five **reference flows** in
[`references/reference-flows.md`](references/reference-flows.md): complete
inspection jobs, each phrased as one prompt whose compiled plan must equal
the equivalent YAML config. A prompt carrying a flow marker -- a scan grid
and "stitched", a defect on a **named refdes** ("shift on C33",
"insufficient solder on J17", "missing-component defect on LS1"),
"component-focus" or "pin-focus" crops -- is a flow, not a catalog row, and
takes its fixed values from that file (they differ from the catalog
defaults: shift is `translate_range=0.5, rotate_z_range=5.0` with no
`variant_index`, crops are ROI captures rather than `postprocess.crop`).

| Flow | Prompt marker |
|---|---|
| G golden scan | "golden board dataset ... NxM scan ... stitched" (single board or panel) |
| C component defects | "shift/tombstone/sideflip/reverse polarity on <refdes>" + "component-focus crops" |
| S SMT solder defects | "insufficient/excess/interrupted/missing solder on <refdes>" + "component-focus crops" |
| M missing component | "missing-component defect on <refdes>" |
| T THT solder defects | six THT solder defects on refdes + "pin-focus crops from the bottom" (single board or panel) |

## Fixed defaults

Every unspecified optional detail resolves to a documented default rather
than a question. The full table -- board identity and paths, the rule that a
named component must resolve on the attachment, THT board requirements,
pin-variation magnitude ranges, **the required structural-defect magnitudes**
(`translate_range`, `rotate_z_range`, `angle_range` -- the API has no
defaults for these and a catalog prompt never states them), the coverage
ratio, how multiple defect types combine, and the solder texture-defect
mapping -- is in
[`references/fixed-defaults.md`](references/fixed-defaults.md).

**Read it before building any script.** The values are not obvious and
several of them are load-bearing: the coverage ratio applies to structural
*and* solder defects, and the crop `class_filter` taxonomy is not the same as
`component_types`.

## Payload contract

What this skill returns to its caller, what it accepts, and how each value is
validated is in
[`references/payload-contract.md`](references/payload-contract.md). The short
version: the output is a `CDFJob` build plus the compiled `JobOrderPlan` from
`job.compile_orders(...)`, serialized with `JobOrderCodec.dumps(plan)` (a
bare `plan.model_dump()` is not JSON-serializable), together with a
resolved-inputs summary naming every default that applied. The caller supplies
the board USD and output root -- both **required**, with no fallback. This
skill supplies everything else from the catalog row and fixed defaults, and
marks each variant for an independent process.

## Instructions

Four steps, in order. Step 1 decides everything downstream, so do not start
writing a script before the row is settled.

1. **Match the prompt to exactly one catalog row or one reference flow.**
   Check the flow markers first (`references/reference-flows.md`, "Routing"):
   a named refdes target, a scan grid with "stitched", "component-focus" /
   "pin-focus" crops. With a marker present the prompt is that flow; without
   one it is a catalog row. A prompt matching **no row and no flow**
   explains the supported request shapes and asks the caller to choose one;
   it never assembles a best-effort substitute out of the pieces that do
   exist.
2. **Resolve every input from the precedence order in [Inputs](#inputs).**
   Anything still unset takes its documented default from
   [`references/fixed-defaults.md`](references/fixed-defaults.md).
3. **Build one `cdf.CDFJob` script**, following the row's shape in
   [Workflow](#workflow). One job per variant: the executing side must launch
   each variant as its own process, because sequential
   `job.capture.render(...)` calls in one process crash the second Kit
   subprocess -- so the payload says one variant, never a loop.
4. **Validate, then return** -- compile the job with
   `job.compile_orders(...)`, read the result, and return the build plus the
   compiled plan to the caller. Do not call `render()` here. Report what was
   assumed alongside the payload.

## Inputs

Each value is resolved from the first source that supplies it:

**state file -> explicit prompt arguments -> agent context -> user prompt text**

| Input | Required | Where it comes from if unset |
|---|---|---|
| Catalog row | yes | Matched from the prompt shape; no default. No match asks the caller to choose a supported shape |
| Board USD (attachment path) | yes, caller-provided | **No fallback.** Ask for a missing path when interaction is possible; for non-interactive automation, stop with refusal case 3. Never substitute a sample board |
| Output root | yes, caller-provided | **No fallback.** Ask for a missing path when interaction is possible; for non-interactive automation, stop with refusal case 3. Never synthesize a directory |
| Component sidecar | optional legacy input | Prefer embedded USD metadata with `source="usd"`. Attach a matching `<stem>.components.json` only when a legacy standalone board relies on it or the caller explicitly selects that source; file presence alone does not select it. Instanced panels require embedded metadata |

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills