[skycap] Pull a run's records and step index from W&B

[kouroshHakha]

What does this PR do?

TLDR: record_index pull turns a run's W&B record index (#2351) back into a local record directory: the step's records, read from the mirror (#2350), plus the step index. Stacked on #2351.

uv run --isolated --extra skyrl-train --extra harbor --extra skycap \
  python -m examples.train_integrations.harbor_skycap.record_index \
  pull <entity>/<project>/skycap-records-train-<run id>[:<alias>] <out_dir>

How it works

• Versions: an alias (train-step-3, v7) pulls that version; with no alias, every version is pulled.
• Per version:
  • Only step.json comes from W&B, written as out_dir/index/<phase>/step-<N>.json.
  • Each mirrored record's files are read straight from the mirror through fsspec with the caller's credentials (s3fs for s3://, gcsfs for gs://), so read access to the mirror is enough. W&B's own reference download isn't used: for s3:// it needs s3:ListBucketVersions, which a reader may not have.
  • Files land in out_dir with an atomic rename from a scratch directory inside it. A file already there and identical is left alone, so pulling again only adds what's new.
• Fails open per record:
  • a record with an unreadable file is reported missing, naming the files;
  • a record that can't move in is reported, and files it newly placed are taken back out;
  • a file name that isn't a plain basename is refused;
  • a version without a readable step.json is reported, and the other versions still pull.
• Local-only records (no mirror) are indexed and reported at host:path, so they can be fetched from the node that wrote them.
• Output: the command prints a summary and exits non-zero only when nothing was pulled.

Test plan

• tests/integrations/harbor_skycap/test_record_pull.py, with a fake W&B API and an in-memory mirror: one version and all versions; identical files left alone; an unreadable file; a record that can't move in; an unsafe name; a bad version; local-only rows; exit codes. pytest tests/integrations/harbor_skycap: 66 passed.
• On a real run (Qwen3-4B, 1 step, mirror on S3): 8 records and 16 files pulled, byte-identical to the training node's record_dir, plus index/train/step-1.json.

🤖 Generated with Claude Code

---

Note

Low Risk
Offline tooling with defensive path validation and isolated test coverage; no changes to training or W&B indexing callbacks.

Overview
Adds record_index pull, a CLI (and pull() API) that reconstructs a local skycap record directory from W&B training artifacts so runs can be opened in skycap-viewer.

For each artifact version it downloads step.json from W&B, writes it under index/<phase>/step-<N>.json, and fetches mirrored record bytes directly from the object-store mirror via fsspec (avoiding W&B reference downloads that need extra S3 permissions). Optional alias pulls one version; omitting it pulls all versions. Fails open per version/record (missing files skip whole records; local-only rows are reported with host:path). Idempotent moves use SHA256 checks so re-pulls only add new content. PullSummary and exit code 1 only when nothing was pulled.

README documents usage; tests/integrations/harbor_skycap/test_record_pull.py covers the flow with a fake W&B API and memory mirror.

^{Reviewed by Cursor Bugbot for commit d2f7dca. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request introduces a pull command-line utility to the record_index module, allowing users to retrieve a run's records and step index from Weights & Biases (W&B) into a local directory. It includes comprehensive unit tests mocking the W&B API and updates the documentation accordingly. The feedback suggests optimizing the file comparison in _move_in by checking file sizes before computing SHA-256 digests to avoid unnecessary hashing.

[greptile-apps]

Confidence Score: 3/5

[Medium risk] Adds a pull command to fetch run records from W&B.

The PR should not merge until downloaded filenames are prevented from overwriting files outside the selected directory.

Findings

1.   Downloaded filenames escape the directory ▶
2.  One error stops a version ▶

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["Artifact reference"] --> B{"Alias supplied?"}
  B -->|Yes| C["Resolve one version"]
  B -->|No| D["List all versions"]
  C --> E["Download into scratch directory"]
  D --> E
  E -->|Download raises| F["Fetch entries individually"]
  E --> G["Read step.json"]
  F --> G
  G --> H{"All record files present?"}
  H -->|No| I["Report missing record"]
  H -->|Yes| J["Move sidecars, then document"]
  I --> K["Write step index"]
  J --> K
  K --> L["Return pull summary"]

Loading

_{Reviews (1) · Last reviewed commit: "[skycap] Pull a run's records and step i..." · Reviewed by Greptile}

[kouroshHakha]

leaving reviews.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d2f7dca. Configure here.}

[cursor]

Partial fetches treated as complete

Medium Severity

A failed fs.get_file can leave an empty or partial file in the scratch directory. _move_record only checks that each name is_file(), so that leftover is treated as a complete fetch and the record is moved in and counted as pulled.

Additional Locations (1)

• examples/train_integrations/harbor_skycap/record_index.py#L633-L637

 

^{Reviewed by Cursor Bugbot for commit d2f7dca. Configure here.}