agentleFS
NVIDIAKnown publisherNVIDIA/NuRec/skills/nurec-onboard/nurec-onboard/steps/build-ncore-converter/SKILL.md

build-ncore-converter

Skill33 starsChanged 17 days agoApache-2.0View on GitHub

Source execution: Read $NUREC_WORKDIR/nurec-runtime.md, generated by run.sh, before executing commands. For every root-workspace bazel command below, use its literal Docker/Bazel prefix with the same target and arguments. Only the standalone converter workspace runs Bazel on the host. Do not extract release archives into host caches or invent module overrides. This is the operating specification for an autonomous step that scaffolds, implements, and iteratively fixes an NCore V4 data converter. The agent reads this file, receives an input description, and executes…

  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

33 rules. About 0 are common, 8 are distinctive, and 25 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 25

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Source execution: Read $NUREC_WORKDIR/nurec-runtime.md, generated by run.sh, before executing commands.

    line 8
  2. Distinctive:

    Only the standalone converter workspace runs Bazel on the host.

    line 11
  3. Distinctive:

    When building or fixing a converter the agent MUST draw implementation decisions exclusively from:

    line 22
  4. Very specific:

    Every implementation decision must be recorded as a critical_parameter_justification with evidence drawn from sources (1)–(4) above.

    line 31
  5. Very specific:

    If ncore.converter_dir is not provided, derive it: $NUREC_WORKDIR/ncore-<data.name>.

    line 85
  6. Very specific:

    Treat lib/parse_input.py as the source of truth for input shape and scope validation before the step starts.

    line 88
  7. Very specific:

    If ncore is present, use its camera_ids and lidar_ids as the conversion output scope.

    line 89
  8. Very specific:

    If both seek_sec and duration_sec are absent, convert the full available sequence.

    line 91
  9. Distinctive:

    If exactly one is present, fail fast with a clear input error.

    line 92
  10. Very specific:

    If both are present, require non-negative numeric values and pass them unchanged to the converter run as --seek-sec <seek_sec> …

    line 93
  11. Very specific:

    Structured profile precedence: If data.profile is present, read it before data.description.

    line 109
  12. Very specific:

    Calibration direction evidence: When data.profile records a transform direction convention or known calibration mismatch, use that evidence …

    line 117
  13. Very specific:

    Operator-scoped sensors: when camera_ids / lidar_ids is provided, every listed id must resolve to a discovered sensor directory (fail fast …

    line 157
  14. Distinctive:

    Every sensor's calibration: intrinsics, extrinsics, model, rolling-shutter direction.

    line 163
  15. Very specific:

    Every field of a LiDAR sample -- flag any field whose shape matches a range-image spatial dim ([H, W, ...], [H], or [W]) and whose values …

    line 184
  16. Very specific:

    Write the summary to <data.name>_meta.json at the workdir root.

    line 198
  17. Very specific:

    Use data.name as the canonical <dataset> token (the same value that derives ncore.converter_dir).

    line 263
  18. Very specific:

    Update ncore_<dataset>/BUILD.bazel to reflect the new filenames if any non-converter.py/dataset_probe.py modules were added.

    line 271
  19. Very specific:

    Add any remaining pip deps to deps/pip/requirements_3_X.in (whichever Python the converter is currently pinned to), regenerate the …

    line 272
  20. Very specific:

    Before running the converter, sanity-check the output against the conventions.md "NCore convention checklist": frames, timestamps, pose …

    line 291
  21. Very specific:

    When the input supplies seek_sec / duration_sec, append them as --seek-sec=<seek_sec> --duration-sec=<duration_sec> to the bazel command …

    line 315
  22. Very specific:

    Add requirement("package-name") to the converter's BUILD.bazel deps.

    line 326
  23. Very specific:

    Consider whether the failure is fixable by bumping python_version per the Python-bump rule (e.g.

    line 331
  24. Very specific:

    Check the output directory contains the sequence directory and {sequence_id}.json meta file.

    line 342
  25. Distinctive:

    Read the relevant converter code section.

    line 406
  26. Distinctive:

    If multiple fixes are needed, apply them all before re-running.

    line 408
  27. Very specific:

    FILL IN check: run grep -rn "FILL IN" $ncore_converter_dir/ncore_*/.

    line 425
  28. Distinctive:

    Must return no matches.

    line 426
  29. Very specific:

    Justifications validator: if any critical parameter was changed by a fix, re-run cd "$NUREC_ONBOARD_DIR" && bazel run …

    line 428
  30. Very specific:

    No system pip: never run pip install. All packages go through deps/pip/requirements_3_X.in.

    line 471
  31. Very specific:

    Never invoke system Python (python3 -c, python3 script.py, or any other system Python call) for code that imports ncore — system Python …

    line 474
  32. Distinctive:

    No git writes: do not commit or push. Track original files for revert if needed.

    line 479
  33. Very specific:

    Bazel commands: always cd $ncore_converter_dir first.

    line 480

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 -->

Build NCore V4 Converter

Source execution: Read $NUREC_WORKDIR/nurec-runtime.md, generated by run.sh, before executing commands. For every root-workspace bazel command below, use its literal Docker/Bazel prefix with the same target and arguments. Only the standalone converter workspace runs Bazel on the host. Do not extract release archives into host caches or invent module overrides.

This is the operating specification for an autonomous step that scaffolds, implements, and iteratively fixes an NCore V4 data converter. The agent reads this file, receives an input description, and executes without user interaction.


Permitted sources

When building or fixing a converter the agent MUST draw implementation decisions exclusively from:

  1. Converter template — scaffold, helpers, and example code inside the converter workdir (materialized from the bundled template at $NUREC_ONBOARD_DIR/ncore_template/).
  2. NCore public documentation and SDK — ncore/docs/, ncore/tools/data_converter/, the NCore Python API.
  3. data.docs — the dataset's own documentation (URL, file, or inline text from the input YAML).
  4. Direct data exploration — empirical measurements from data.path via the probe script and Bazel run targets.

The agent MUST NOT consult any pre-existing converter for this dataset (prior runs under the working directory, NCore in-tree converters for other datasets, or any third-party converter on disk).

Every implementation decision must be recorded as a critical_parameter_justification with evidence drawn from sources (1)–(4) above.


1. Input Schema

# Required
data:
  name: <string> # Short dataset identifier, filesystem-safe (alphanumeric, dash, underscore)
  path: <string> # Path to raw sensor data
  description: <string> # Short high-level overview of the dataset.

  # Optional
  # Dataset documentation: each entry is a file path, URL, or inline text.
  # Pass a single string for one source, or a list for multiple (paper +
  # devkit + datasheet, etc.). All entries are read and cited individually in
  # critical_parameter_justifications evidence.
  docs: <string> | [<string>, ...]
  # Optional structured dataset facts from audit-dataset. When present, read
  # this before description. Evidence-backed facts are authoritative;
  # UNRESOLVED high-risk facts are hypotheses to verify.
  profile: <mapping>

ncore:
  camera_ids: [<string>, ...] # Optional conversion camera scope.
  lidar_ids: [<string>, ...] # Optional conversion LiDAR scope.
  seek_sec: <number|null> # Optional conversion start offset.
  duration_sec: <number|null> # Optional conversion duration.
  converter_dir: <string|null> # Default: $NUREC_WORKDIR/ncore-<data.name>
  output_dir: <string|null> # Default: <ncore.converter_dir>-out

# Present only in fix mode (passed by nurec-onboard orchestrator)
diagnosis:
  source: <string> # "validate-ncore-data" or "run-nurec"
  errors: [<string>] # Validation error messages or NuRec symptoms
  metrics: { <string>: <value> } # Eval metrics that are out of range
  suggested_fixes: [<string>] # Mapped fix suggestions from ../validate-ncore-data/common-failures.md

Mode detection

  • Scaffold mode: diagnosis field is absent. First run -- explore data, scaffold converter, implement, run conversion.
  • Fix mode: diagnosis field is present. Re-invocation -- apply targeted fixes to the converter based on the diagnosis, re-run conversion.

2. Scaffold Mode

Step attempt entry anchor (scaffold mode): capture runs[*].started_at here, before the "Parse input" actions below; see nurec-onboard/SKILL.md "Timestamp capture rules" for the step-attempt definition.

Parse input and infer sensor properties

  1. Parse input: extract data.name, data.path, data.description, optional data.profile, optional data.docs, optional ncore.converter_dir, optional ncore.output_dir (default: <ncore.converter_dir>-out), and optional conversion scope from top-level ncore.
    • If ncore.converter_dir is not provided, derive it: $NUREC_WORKDIR/ncore-<data.name>.
    • If ncore.converter_dir does not yet exist, create it by materializing the bundled template with rsync -a --exclude='tests/' "$NUREC_ONBOARD_DIR/ncore_template/" "<ncore.converter_dir>/". The tests/ exclusion drops the template's platform self-verification regression test (ncore_example_test.py), which is CI-only and not part of the operator's converter; every other file -- including the committed MODULE.bazel.lock -- is copied verbatim. Preserving that lock file is what lets the converter workspace's first bazel invocation skip module-extension re-evaluation (and the unreliable pypi.org metadata fetch it would trigger from inside the sandbox). The trailing slash on the source path is required by rsync to copy the directory's contents into <ncore.converter_dir>/ rather than nesting another template/ level inside.
    • Maintainers who change the bundled template's MODULE.bazel or deps/pip/requirements_3_13.txt must refresh ncore_template/MODULE.bazel.lock outside the sandbox with bazel build //... --lockfile_mode=update --nobuild from the template root before publishing the template.
    • Treat lib/parse_input.py as the source of truth for input shape and scope validation before the step starts.
    • If ncore is present, use its camera_ids and lidar_ids as the conversion output scope. These fields control which components are written, not which sensor implementations the converter supports. Cuboids are governed by data.profile.cuboids; always write a CuboidsComponent, even with zero observations.
    • Validate the optional conversion time window from ncore:
      • If both seek_sec and duration_sec are absent, convert the full available sequence.
      • If exactly one is present, fail fast with a clear input error.
      • If both are present, require non-negative numeric values and pass them unchanged to the converter run as --seek-sec <seek_sec> --duration-sec <duration_sec>.
  2. Read documentation (if data.docs is provided):
    • data.docs accepts either a single string or a list of strings. Each item is one of: a file path (/ or ./ prefix), a URL (http:// or https:// prefix), or inline text. Read every item and treat them collectively as the dataset's documentation surface; cite the specific item by URL / filename in evidence so the operator can trace claims back to a source. When an item fails to load (URL fetch fails after one retry, or path missing), record the failure in notes and derive the affected sections empirically.
    • Mandatory citation coverage. For camera_timestamp_meaning, lidar_frame_timestamp_meaning, and cuboid_centroid_convention, evidence must either quote one of the data.docs items with a section/page anchor, or -- when all docs are silent or absent -- explicitly say so AND back the chosen value with an inline empirical measurement (cross-sensor offset, ground-clearance histogram, etc.). build_ncore_converter_validator.py fails on blank or placeholder evidence.
    • Structured profile precedence. If data.profile is present, read it before data.description. Treat evidence-backed profile entries as the authoritative structured statement of operator/audit-supplied dataset facts. Treat UNRESOLVED: entries, especially high-risk geometric and optical facts from audit-dataset, as hypotheses to verify through the critical-parameter justification step. Treat data.description as a high-level overview only and do not mine it for detailed facts that conflict with evidence-backed data.profile entries.
    • Calibration direction evidence. When data.profile records a transform direction convention or known calibration mismatch, use that evidence before trusting a raw field name. NCore stores poses as source-to-target transforms, so a field label is not sufficient evidence that the matrix is already in the direction required by store_static_pose or store_dynamic_pose.
  3. Add dataset-specific dependencies early. Determine which Python package(s) parse this dataset. The converter imports the reader directly so its decoder logic (frame corrections, calibration accessors, point-cloud extraction) runs as-shipped rather than re-implemented. Pick from the ladder below in order; record the choice as dependency_strategy in inferred_parameters. Exploration scripts default to bazel run; system Python is allowed only when the chosen strategy is the preprocess-step fallback, where the reader is not Bazel-resolvable -- see the data-exploration step's probe spec for the matching probe invocation.

    The four options (direct pip dep → Bazel dep + sys.path shim → vendor a slice → preprocess-step fallback), their escalation triggers, and the preprocess script's hard requirement are in dependency-strategies.md. Default to Option 1 and escalate only when the current option actually fails.

  4. Explore the raw data directory (data.path) via a reusable reconnaissance script. The template materialized into the converter dir already includes $ncore_converter_dir/ncore_example/dataset_probe.py -- fill in the dataset-specific logic in place (no rename of this file is required; the scaffold step's single-token rename moves the whole package directory to ncore_<dataset>/, after which the probe is at ncore_<dataset>/dataset_probe.py). Run it under the toolchain matching dependency_strategy: bazel run :probe -- --root-dir <path> --output <path> for Bazel-resident strategies, python3 ncore_<dataset>/dataset_probe.py --root-dir <path> --output <path> under the dataset SDK's external env for the preprocess-step fallback. It MUST enumerate:

    • Every subdirectory under data.path with an explicit decision per directory: include / exclude, modality (camera / lidar / radar / pose / annotation / other), and a one-line reason. Resolve ambiguous directories by inspecting a sample frame -- never silently drop or include. Record under sensor_inventory_decisions. Operator-scoped sensors: when camera_ids / lidar_ids is provided, every listed id must resolve to a discovered sensor directory (fail fast otherwise); listed ids are included, every other discovered camera / LiDAR is excluded (non-camera / non-LiDAR decisions unchanged). Set decision_source to operator_include, operator_exclude, or agent_decided per entry.
    • Sequence directory layout (list of sequences, one canonical id per sequence).
    • Every sensor's calibration: intrinsics, extrinsics, model, rolling-shutter direction.
    • Every per-ray metadata stream alongside each LiDAR frame's (x, y, z). Streams appear as (a) extra fields in the primary payload, (b) companion files in the frame dir, or (c) implicit structured ordering on a dense n_rows x n_columns grid. Check all three. For each stream record the form, semantic role (ring / column / azimuth / timestamp / intensity / ...), dtype, and length relative to point count. See conventions.md "Per-ray metadata discovery".
    • One representative frame of every timestamp field (per-frame camera, per-frame LiDAR, per-point LiDAR, pose, cuboid) with unit and min/max/delta across the sequence.
    • Sequence frame-range intersection. Compute each required modality's [min, max] timestamp envelope (every camera, every LiDAR, pose, cuboids); the authoritative sequence interval is their intersection. Record the bounds, the limiting modality per side, the excluded-frame count, and the cuboid track counts expected versus stored under sequence_frame_range_decision. See conventions.md "Sequence frame-range intersection" for the silent-degradation rationale.
    • Cross-sensor frame correspondence. Record retained key/index ranges, frame counts, gaps, and duplicates per stream, and establish correspondence by shared source keys or by timestamp -- never by zipping independently filtered arrays. See conventions.md "Sequence frame-range intersection" for the pairing rules and the offset diagnostics.
    • Every field of a LiDAR sample -- flag any field whose shape matches a range-image spatial dim ([H, W, ...], [H], or [W]) and whose values look like poses or per-ray timestamps. That is per-ray motion metadata and indicates a polar range image.
    • Metrics that feed critical_parameter_justifications: per-sensor Z-offset, LiDAR sweep duration, camera exposure/readout durations, per-frame LiDAR↔camera midpoint deltas, cuboid ground-clearance histogram.
    • One example of every label type (cuboid, 2D box, segmentation mask, ...) with raw field names preserved.
    • Image / point-cloud format details (JPEG/PNG, resolution; cartesian vs. polar; units).
    • Whether cuboid annotations exist; determine the centroid convention if so. If absent, _write_cuboids must still write an empty CuboidsComponent (ncore-aux-data asserts the component exists).
    • The meaning of the LiDAR per-frame timestamp (sweep start / center / end / pose ref).

    Write the summary to <data.name>_meta.json at the workdir root. critical_parameter_justifications may cite keys in that file instead of restating measurements. Re-running the script after writing the converter is the fastest way to confirm the raw data hasn't changed.

  5. Record inferred parameters in the output summary based on the exploration:
inferred_parameters:
  sensor_suite:
    cameras: [{ id, model, resolution: [w, h], rolling_shutter: <bool> }]
    lidars: [{ id, type, rows, cols }]
    radars: [{ id }]
  rig_frame: { x, y, z } # e.g. forward, left, up
  timestamp_unit: <string> # Must become microseconds in the converted NCore data.
  data_layout: <string>
  has_annotations: <bool>
  dependency_strategy: pip | bazel_dep_shim | vendored | preprocess # Chosen ladder option from the input-inference step.
  python_version_bump: <string|null> # New `MODULE.bazel` python_version if bumped under Option 1; null otherwise.
  1. Justify critical parameters in the output summary -- silent failure modes that validate.py and build_ncore_converter_validator.py validate. Every entry must populate all four required fields (parameter, value, evidence, wrong_value_consequence). See critical-parameters.md for the entry schema, evidence rules, the worked_example requirement on T_lidar_rig / spinning_lidar_model_frame_choice (single-ray prediction), T_camera_rig (per-camera rotation + conditionally-mandatory translation prediction), camera_model_family (per-camera source-derived projection samples), and sequence_frame_range_decision (per-track check count and sampled source cuboid tracks), the authoritative_source sub-block required on T_lidar_rig and T_camera_rig (including its verification sub-block), and the value domain plus conventions.md anchor for each parameter. Required parameter names, by category:
    • LiDAR model: spinning_direction, row_elevations_rad, column_azimuths_rad, row_azimuth_offsets_rad, spinning_lidar_model_frame_choice
    • Sensor enumeration: sensor_inventory_decisions
    • NuRec LiDAR selection: nurec_lidar_selection
    • Sequence frame range: sequence_frame_range_decision
    • LiDAR model provenance: lidar_model_source
    • Extrinsics: T_lidar_rig, camera_frame_convention, T_camera_rig, rig_frame_convention
    • Cuboids: cuboid_dim_axis_ordering, cuboid_centroid_convention, cuboid_world_anchored_frame
    • Timestamps: timestamp_unit, camera_timestamp_meaning, lidar_frame_timestamp_meaning
    • Camera shutter: shutter_type_and_direction — include the rolling-shutter period (T_rs) source. A documented rolling shutter keeps its directional rolling type even when T_rs is unpublished; never guess T_rs. Use ShutterType.GLOBAL with start == end only when the documentation is silent on shutter type and no source provides T_rs. See conventions.md "Frame timestamps" for the rationale (a wrong T_rs causes multi-camera blur).
    • LiDAR data: lidar_raw_format, lidar_motion_compensation, image_distortion_state
    • Camera intrinsics: camera_model_family -- include per-camera projection samples derived independently from the source data (for example, LiDAR-to-image correspondences) so the validator can project through the stored NCore camera model and catch pinhole/fisheye/ftheta mismatches.
    • Camera masks: camera_static_mask_handling
    • Pose trajectory: pose_trajectory_source, lidar_point_frame
    • LiDAR intensity: intensity_normalization_method

Scaffold the converter

The materialized template is scaffolding -- rename and adapt it for the target dataset using a single-token substitution: replace example with <dataset> everywhere it appears as a token in the workdir. The placeholder is encoded so that one consistent rename produces a working converter package whose target labels, file names, and class names all line up.

  1. Use data.name as the canonical <dataset> token (the same value that derives ncore.converter_dir); do not infer it from data.description or the data directory name.
  2. cd $ncore_converter_dir
  3. Apply the single-token rename across the workdir:
    • Package directory: ncore_example/ → ncore_<dataset>/.
    • Class names inside ncore_<dataset>/converter.py: ExampleConverter → <Dataset>Converter, ExampleConverterConfig → <Dataset>ConverterConfig. Also update the corresponding cli.command("example") decorator and example_cmd function name to cli.command("<dataset>") / <dataset>_cmd.
    • Import lines anywhere in the workdir: any from ncore_example.<module> import ... → from ncore_<dataset>.<module> import .... This covers both converter and utils (and any future internal modules added under the package). Intra-package imports must stay in the absolute from ncore_<dataset>.<module> import ... form -- bazel run :convert and bazel run :probe execute their entry-point module as __main__, where from .<sibling> import ... raises ImportError: attempted relative import with no known parent package.
    • File names inside the package (converter.py, dataset_probe.py) and the Bazel target name (convert) are dataset-neutral and stay unchanged. No file renames inside ncore_<dataset>/ are required after the package rename.
  4. Do not rename the Bazel module or pip hub identifiers -- specifically, leave module(name = "ncore_template"), pip.parse(hub_name = "ncore_template_pip_deps"), and use_repo(pip, "ncore_template_pip_deps") exactly as shipped. The Bazel module name and pip hub name are internal identifiers that no Python code or BUILD target depends on; touching them at scaffold time invalidates MODULE.bazel.lock (the warm copy inherited from the bundled template) and forces Bazel to re-evaluate module extensions on the next agent invocation. From inside the sandbox that re-evaluation is unreliable -- rules_python's publish-deps pip.parse fetches metadata over Bazel's JVM HTTP client, which several network setups don't pass cleanly. Once scaffold has produced a working converter, the operator can rename the module identifiers later (e.g. for namespacing or eventual publishing) by running bazel mod deps --lockfile_mode=update outside the sandbox to refresh the lock, then resuming agent work; that's an operator maintenance task, not a scaffold-step one. Other MODULE.bazel edits -- adding bazel_dep / http_archive per Option 2, bumping python_version per the Option 1 escalation, or updating existing bazel_dep versions -- are allowed when justified by the dependency-strategy ladder; those edits invalidate the lock at a finer granularity that the same step regenerates.
  5. Update ncore_<dataset>/BUILD.bazel to reflect the new filenames if any non-converter.py/dataset_probe.py modules were added; the shipped lib (py_library) and convert (py_binary) target names stay the same.
  6. Add any remaining pip deps to deps/pip/requirements_3_X.in (whichever Python the converter is currently pinned to), regenerate the lockfile, and add requirement() entries in the renamed BUILD.bazel (see the dependency-strategy ladder for the full process and the four sanctioned options).

Fill in the skeleton

The skeleton has FILL IN markers at every dataset-specific value. Every marker must be resolved -- either replaced with a real value derived from the dataset, or removed when the surrounding code is rewritten. After this step, grep "FILL IN" <converter>.py must return no matches (this is verified in Verify output).

Complete each marker using the inferred sensor properties from Parse input and infer sensor properties. The scaffolded converter documents every marker inline: each FILL IN comment in ncore_<dataset>/converter.py states what to implement, the dtype / convention traps, and the validate.py check it must satisfy. Work through those comments directly and consult conventions.md for the per-parameter rationale and deep dives.

NCore convention checklist

Before running the converter, sanity-check the output against the conventions.md "NCore convention checklist": frames, timestamps, pose dtypes, pose trajectory, camera frame_timestamps_us, LiDAR frames, and cuboids. Each item is enforced by the NCore V4 writer or the shard validator at //skills/nurec-onboard/ncore_validation:validate.

Run the converter

cd $ncore_converter_dir && bazel run //ncore_<dataset>:convert -- \
  --root-dir=<data.path> \
  --output-dir=<ncore_output_dir> \
  [--seek-sec=<seek_sec> --duration-sec=<duration_sec>] \
  <subcommand> --store-type itar

(Before the scaffold rename has run, the label is //ncore_example:convert; the :convert target name is dataset-neutral and does not change after the rename.)

--store-type itar is required (not optional). NuRec consumes .zarr.itar archive stores; directory-format stores (.zarr/) load-fail with an assertion that surfaces on the sequence JSON path rather than the store itself, making the root cause hard to recognize.

When the input supplies seek_sec / duration_sec, append them as --seek-sec=<seek_sec> --duration-sec=<duration_sec> to the bazel command above (both flags together; input parsing already enforced both-or-neither). Omit both flags when the input omits the fields.

If bazel run fails with ModuleNotFoundError, the missing package is not in the Bazel pip graph. Do not fall back to system Python -- add the dependency to Bazel instead:

  1. Append the missing package to deps/pip/requirements_3_X.in (whichever Python the converter is currently pinned to).
  2. Regenerate the lockfile: bazel run //deps/pip:requirements
  3. Add requirement("package-name") to the converter's BUILD.bazel deps.
  4. Retry bazel run //ncore_<dataset>:convert -- ...

If lockfile resolution fails (No matching distribution, conflicting transitive pins, build wheel exited with 1 on a transitive dep): do not keep retrying version pins. Consider whether the failure is fixable by bumping python_version per the Python-bump rule (e.g. the reader requires a Python ABI the template doesn't currently ship). If so, bump and retry. Otherwise, step back to the dependency-strategy ladder and pick the next option (Option 1 → 2 → 3 → 4); update dependency_strategy in inferred_parameters and record the reason the previous option was unreachable in notes.

Verify output

  1. FILL IN check (mandatory): run grep -rn "FILL IN" $ncore_converter_dir/ncore_*/. This must return no matches. If any remain, go back to filling in the skeleton and resolve them.
  2. Check the output directory contains the sequence directory and {sequence_id}.json meta file.
  3. The platform self-verification regression test (ncore_template/tests/ncore_example_test.py) is not materialized into the converter workdir (rsync --exclude='tests/'). It runs only in the platform CI against the placeholder. The converter workdir has no tests/ directory by design; do not attempt to run bazel test from inside it.
  4. Justifications validator (mandatory): write the full output summary (including critical_parameter_justifications) to a temporary file and run cd "$NUREC_ONBOARD_DIR" && bazel run //skills/nurec-onboard/validators:build_ncore_converter_validator -- <summary.yaml> --store <sequence_meta>. The validator asserts every required parameter from the critical-parameter justification step is present with non-empty parameter, value, evidence, and wrong_value_consequence fields, and that no field contains a placeholder (FILL IN, TODO, TBD, [ ... ], etc.). --store <sequence_meta> additionally verifies every worked_example blocks against the converted NCore store (single-ray LiDAR prediction for T_lidar_rig / spinning_lidar_model_frame_choice; per-camera rotation + conditionally-mandatory translation prediction for T_camera_rig; per-camera projection samples for camera_model_family; cuboid counts and sampled source tracks for sequence_frame_range_decision). Without --store the worked-example blocks are checked for structure only, and any author-computed geometric or projection prediction would land unverified -- the convert step has just produced the sequence JSON, so always pass it. For .itar stores, pass the {sequence_id}.json sequence meta path, not the output directory or sequence subdirectory; directory-format stores follow the same sequence-meta entry point.
    • Exit 0 -> verification passed; proceed to emit the output summary.
    • Exit 1 -> one or more required parameters is missing or incomplete, OR a worked-example prediction failed the store check. You MUST emit status: partial and list every diagnostic verbatim in notes. Do not attempt to silently drop or rename parameters to pass the check -- the required list is normative.
    • Exit 2 -> the summary is malformed YAML. Fix the YAML before returning.

Output

Return a structured summary:

mode: scaffold
ncore_converter_dir: <string>
output_data_path: <string>
sequence_meta: <path to .json>
inferred_parameters: { ... }
critical_parameter_justifications: [...] # from the critical-parameter justification step -- must be present
fill_in_remaining: 0 # grep "FILL IN" match count -- must be 0
status: success | partial
notes: [<string>]

Step attempt exit anchor (scaffold mode): capture runs[*].ended_at here, after validators/build_ncore_converter_validator.py returns (or after status: partial is written). Compute duration_sec.


3. Fix Mode

Step attempt entry anchor (fix mode): capture runs[*].started_at here, before reading the diagnosis. Each fix-mode invocation is its own runs[*] entry, not a continuation.

Parse diagnosis

  1. Parse input: extract ncore_converter_dir, diagnosis.source, diagnosis.errors, diagnosis.metrics, diagnosis.suggested_fixes.
  2. Read the converter source code in $ncore_converter_dir to understand the current implementation.

Apply fixes

For each error/suggestion in the diagnosis:

  1. Map the error to a specific converter function using the suggested fixes and ../validate-ncore-data/common-failures.md patterns.
  2. Read the relevant converter code section.
  3. Apply the targeted fix.
  4. If multiple fixes are needed, apply them all before re-running.

Re-run conversion

cd $ncore_converter_dir && bazel run //ncore_<dataset>:convert -- \
  --root-dir=<data.path> \
  --output-dir=<ncore_output_dir> \
  [--seek-sec=<seek_sec> --duration-sec=<duration_sec>] \
  <subcommand> --store-type itar

Forward --seek-sec / --duration-sec whenever the original input supplied them (Scaffold-mode converter-run semantics apply unchanged in fix mode).

Verify and test

  1. FILL IN check: run grep -rn "FILL IN" $ncore_converter_dir/ncore_*/. Must return no matches.
  2. The converter workdir has no in-tree test directory (rsync --exclude='tests/' strips the platform's placeholder regression test). Validation is performed by the platform validator binary; invoke it from $NUREC_ONBOARD_DIR per the validate-ncore-data step.
  3. Justifications validator: if any critical parameter was changed by a fix, re-run cd "$NUREC_ONBOARD_DIR" && bazel run //skills/nurec-onboard/validators:build_ncore_converter_validator -- <summary.yaml> --store <sequence_meta> on the updated summary (see Scaffold Mode output's Justifications validator for the exact semantics). The re-converted sequence meta JSON is the input to --store, so any worked-example geometric prediction whose value drifted with the fix is caught here. Exit 0 is required to proceed; any other exit code forces status: partial.

Output

Return a structured summary:

mode: fix
ncore_converter_dir: <string>
output_data_path: <string>
sequence_meta: <path to .json>
diagnosis_source: <string>
fixes_applied: [<string>]
critical_parameter_justifications: [...] # re-justify any critical params that were changed by a fix
fill_in_remaining: 0
status: success | partial
notes: [<string>]

Step attempt exit anchor (fix mode): capture runs[*].ended_at here, after smoke tests pass and the justifications validator (if re-run) returns. Compute duration_sec.


4. Camera Model Quick Reference

ModelNCore classKey parameters
PinholeOpenCVPinholeCameraModelParametersfx, fy, cx, cy, distortion_coefficients, width, height
FisheyeOpenCVFisheyeCameraModelParametersfx, fy, cx, cy, distortion_coefficients, width, height, max_angle (compute from calibration via OpenCVFisheyeCameraModelParameters.compute_max_angle() — never from the sensor spec's declared FOV; see conventions.md "Camera model selection")
FThetaFThetaCameraModelParametersaffine_transform, distortion_coefficients, width, height

For fisheye max_angle, see conventions.md "Camera model selection" for the ncore.data / ncore.sensors import split and keyword-argument call shape.

5. Constraints

  • No user interaction: infer everything from the data directory and description.
  • No system pip: never run pip install. All packages go through deps/pip/requirements_3_X.in; all execution via bazel run. Use the dependency-strategy ladder (Options 1-4) — Option 4 is last resort. Never invoke system Python (python3 -c, python3 script.py, or any other system Python call) for code that imports ncore — system Python does not have access to the Bazel-pinned nvidia-ncore version. For ad-hoc NCore checks, write a temporary script in the converter repo and run it with bazel run.
  • Validator and eval tools live in NuRec Onboard, not in the converter workdir. The shard validators (//skills/nurec-onboard/ncore_validation:validate, //skills/nurec-onboard/ncore_validation:eval) are platform code at $NUREC_ONBOARD_DIR/ncore_validation/; they are not materialized into $ncore_converter_dir and the agent's sandbox mounts $NUREC_ONBOARD_DIR read-only. Fix the converter when validation reports a failure, not the checks.
  • No git writes: do not commit or push. Track original files for revert if needed.
  • Bazel commands: always cd $ncore_converter_dir first.

6. Additional Resources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.