Skip to content

Use DiskGraph-owned SamplingOptions for runtime iteration - #449

Draft
haoweiyu-kumo wants to merge 3 commits into
hyu-diskgraph-sampling-plan-dataclassfrom
hyu-diskgraph-sampling-options
Draft

haoweiyu-kumo wants to merge 3 commits into
hyu-diskgraph-sampling-plan-dataclassfrom
hyu-diskgraph-sampling-options

Conversation

@haoweiyu-kumo

@haoweiyu-kumo haoweiyu-kumo commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Stacked on #445, rebased onto its latest head ca82b8f32c.

DiskGraph's runtime iterator currently takes a long list of keyword arguments, forcing Ray clients to duplicate that configuration schema. Add DiskGraph-owned frozen Python SamplingOptions and WeightedSeedSampling dataclasses, and change the Python API to index.iter(options). The existing Rust iterator implementation is unchanged.

Migrate the local DataModule, native-anchor adapter, native tests/benchmark helper, and engine regression callers. The two Ray branches are integrated separately. This is an API break: keyword/positional iterator options must move into SamplingOptions, and weighted seed settings must use WeightedSeedSampling.

InheritEngineSeed.DEFAULT preserves omitted-seed behavior across pickle: an omitted seed inherits the index seed; explicit None still disables the seed and fails with shuffle enabled. Dataclass fields are frozen; nested list/dict inputs retain native formats and must remain read-only during iteration. No generic freeze, JSON conversion, or configuration-copy framework is added.

The rebase retains #445's CI fixes. Also migrate its new named-neighborhood regression to SamplingOptions and fix the remaining engine CI failure: link-prediction explanation graphs now retain predicted items omitted by residual aggregation. A deterministic regression covers zero, one, and two retained neighbors.

Change map

File-by-file change map.

Testing Done

  • Native options, plans, and stateless sampling: 84 cases pass across focused runs.
  • DataModule: 161 passed; prediction selection: 6 passed.
  • New explanation export regression: 3 passed; the same test fails in 2 aggregation cases before the fix.
  • Loaded-model link explanation integration: passed after the export fix.
  • Focused mypy, Ruff, formatting, repository isort, and git diff --check pass.
  • Targeted experimental PyTorch suites: 475 cases pass across runs (468 initially passed; the 7 documentation subprocess import failures passed in the isolated interpreter, with all 26 documentation cases green). A broader run passed 390 cases before interruption during conformance checks.
  • Fresh GitHub native DiskGraph, isort, and change-map checks pass; remaining CI is running.

Validation uses prepared Python 3.12 CPU dependencies and this checkout's Python source with the matching #445 native build. Existing Torch, pytest configuration, and worker warnings remain. No cloud/cluster benchmarks were run.

CI follow-up (e7775dc384): the previously failing pyright and kumo-pytorch-tests jobs both pass on GitHub, including the full PyTorch test suite, Ruff checks, and wheel build. Fixed the formatter expression and narrowed the explanation RHS table name for ty. Locally, pinned Ruff 0.17.3, ty 0.0.23 (one existing unused-ignore warning), mypy, and 43 focused regression cases pass.

@copy-pr-bot

copy-pr-bot Bot commented Nov 20, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@haoweiyu-kumo
haoweiyu-kumo temporarily deployed to gha-kumo-workflow-tests November 20, 2026 23:58 — with GitHub Actions Inactive
@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

Parsing warnings: 1

Validation error: Unrecognized key: "tone_instructions" at "reviews"
Configuration instructions

  • Please see the configuration documentation for more information.
  • You can also validate your configuration using the online YAML validator.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
Pre-merge checks: Passed 2 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Change Map Design Review Warning (previously flagged, unaddressed) Details from the previous assessment are unavailable.
Passed Passed checks: 2 passed

Check name Status Explanation
Pr Size Passed PR size check: the pull request changes 20 files, below the limit of 40. Lines were ignored, as the check requires. Evidence: - The provider-reported target branch is hyu-diskgraph-sampling-plan-datac…
Public Resource Access Passed The check applies only to external resource references (URLs, repository locations, package source locations) added or modified by this PR. I diffed the PR's three commits (0d8d8f6, 163ac01, e7775dc…
Full details: Pr Size

Explanation

PR size check: the pull request changes 20 files, below the limit of 40. Lines were ignored, as the check requires. Evidence: - The provider-reported target branch is hyu-diskgraph-sampling-plan-dataclass. The PR description says the PR is stacked on #445 and rebased onto its head ca82b8f. That commit exists locally. - The PR's own commits are 0d8d8f6, 163ac01, and e7775dc, which sit on top of ca82b8f. - git diff --name-only ca82b8f3..e7775dc3 lists 20 files: 17 modified and 3 added. The diffstat is 20 files changed, 628 insertions, 247 deletions. Caveat: the target branch itself was not available locally, so I used the stacked base commit ca82b8f as the base. Against main, the diff is much larger (1725 files). That larger number includes the inherited #445 changes. The PR's own diff against its declared base is 20 files, so the check passes.

Full details: Public Resource Access

Explanation

The check applies only to external resource references (URLs, repository locations, package source locations) added or modified by this PR. I diffed the PR's three commits (0d8d8f6, 163ac01, e7775dc) against 0d8d8f6^, covering 20 changed files. The added lines contain no http(s) URLs, git+ or git@ references, GitHub/GitLab/Bitbucket links, package index or find-links settings, registry or container image references, or markdown links. The only regex hit was a false positive (options.target_node_type matched a .tar pattern). The non-Python change is a README.md section that adds an API usage code sample with no links. No removed lines contain external references either. With no added or modified external resource reference, the check passes and no public-access verification is needed. The PR's target branch is not present in this checkout, so I used the first PR commit's parent as the base; that does not change the result because the added-line scan covers the full commit range.

Latest assessment: Change Map Design Review

Latest assessment: The latest assessment was inconclusive; the previous failure remains unresolved.

Latest explanation: The check reviews the PR conversation comment that starts with <!-- kumo-pr-change-map -->. This comment is not available to this run. Its text is absent from the checkout, and the only PR-related evidence is the reference in the description to issuecomment-7053655671. No available tool retrieves PR conversation comments. I searched the repository and git refs for the marker and for "Change map". The only hit for the marker is the process note in docs/development/review.md. That note describes the expected comment but does not contain its content. I checked the implementation evidence that the check can use. The repository has a DiskGraph-owned SamplingOptions and WeightedSeedSampling API in diskgraph.sampling_options. Callers in the tests and the DataModule use index.iter(SamplingOptions(...)). The Rust iterator code is unchanged, as the description states. This evidence does not assess the change map. I did not evaluate whether each mapped change is necessary, placed at the right layer, or preserves behavior. I also did not check whether the map states the observed failure, the smallest sufficient change, focused verification, or a stopping condition. The standing previous FAIL has no retained details. I cannot confirm or refute its claims. Missing evidence cannot establish PASS. The check does not define a FAIL condition for an unavailable change-map comment.

Latest resolution: Make the <!-- kumo-pr-change-map --> conversation comment available to the reviewer. Use the comment at #449 (comment) or the current comment with that marker. Then rerun this check. The rerun should also re-review the previous FAIL, which has no retained details. Each mapped change should state the observed failure or release requirement, the inspected existing behavior, the smallest sufficient change, focused verification, and a stopping condition. The reviewer should also check whether the map omits material behavior, such as the explicit None seed behavior and the frozen read-only list and dict handling that the description mentions.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@haoweiyu-kumo

haoweiyu-kumo commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator Author

Change map

Requirement: make DiskGraph own the typed sampling configuration so the Ray backend can reuse it. The old Python iterator accepted individual keywords; the smallest API change is one Python dataclass plus field forwarding at the existing native boundary, with existing local callers migrated. Rebased onto #445 at ca82b8f; its native-plan and import fixes are retained. Validation: 84 native options/plan/stateless cases, 161 DataModule cases, 6 prediction-selection cases, 3 deterministic explanation-export cases, 1 loaded-model link explanation integration, and 475 targeted experimental PyTorch cases pass across runs. The new regression reproduces 2 failures before the fix; CI passed all 2,630 PyTorch tests and the engine shard. Follow-up static-check fixes pass pinned Ruff 0.17.3 and ty 0.0.23 locally (one existing unused-ignore warning), plus 43 focused tests; Both previously failing GitHub jobs, pyright and kumo-pytorch-tests, pass at e7775dc, including the full PyTorch suite, style checks, and wheel build. Ruff, isort, and focused mypy pass. This PR stops at the local API: Ray integration, native encoding, transport, and threading changes stay separate.

File Function / scope What changed Why
packages/diskgraph/diskgraph-pybind/python/diskgraph/sampling_options.py Public sampling configuration Define concrete frozen SamplingOptions, WeightedSeedSampling, and the pickleable inherited-seed sentinel. Give local and remote clients one DiskGraph-owned schema without JSON adapters.
packages/diskgraph/diskgraph-pybind/python/diskgraph/runtime_batch_iterator.py RuntimeIndex.iter; weighted sidecar resolver Accept SamplingOptions directly and forward fields to the unchanged native iterator; read weighted settings from typed fields. Remove the duplicate keyword schema while preserving selection, weighting, seed inheritance, and native validation.
packages/diskgraph/diskgraph-pybind/python/diskgraph/__init__.py Public exports Export options, weighted settings, and inherited-seed sentinel. Make the shared configuration available as diskgraph.SamplingOptions without importing training code.
packages/kumo-core/src/kumo_core/diskgraph/lightning_data.py DiskgraphTaskBatchIterable iterator setup Construct SamplingOptions and typed weighted settings before opening the runtime iterator. Keep local training, explanation, prediction, grouped stages, and replay on the new API.
packages/experimental/kumo-pytorch/src/kumo/pytorch/engines/native_anchors.py NativeAnchors._iter Wrap native-anchor iterator configuration in SamplingOptions and use the directly imported typed empty plan default in the formatter-compliant expression. Migrate the experimental Python consumer of the changed signature.
packages/diskgraph/diskgraph-pybind/python/tests/test_sampling_options.py Configuration and native-boundary tests Check frozen fields, pickle, typed defaults, rejection before graph access, and inherited/explicit null/zero RNG seeds. Prevent API and RNG behavior regressions.
packages/diskgraph/diskgraph-pybind/python/tests/test_sampling_plan.py Typed plan regression callers Pass typed plans inside SamplingOptions while keeping wrong-plan rejection and sampling parity tests. Retain #445 guarantees through the new options boundary.
packages/diskgraph/diskgraph-pybind/python/tests/test_runtime_batch_iterator_e2e.py Native E2E helper and weighted fixtures Construct SamplingOptions in the existing one-shot helper and use typed weighted draw settings. Keep native selection, weighted sampling, projections, and graph batches covered.
packages/diskgraph/diskgraph-pybind/python/tests/test_stateless_sampling.py Stateful/stateless parity cases Open reference iterators with SamplingOptions. Preserve explicit request and standalone seed-schedule parity.
packages/diskgraph/diskgraph-pybind/python/tests/test_task_dataset_mock.py Metadata and forwarding tests Update the helper to typed options and weighted draw settings. Verify field forwarding and weighted sidecar resolution without external data.
packages/diskgraph/diskgraph-pybind/python/tests/test_pseudo_time.py Static-link native regression callers Pass pseudo-time and stage settings via SamplingOptions. Preserve split visibility and override behavior.
packages/diskgraph/diskgraph-pybind/python/tests/test_timestamp_shuffle.py Timestamp iterator regression caller Construct SamplingOptions for shuffled timestamp batches. Keep ordering and no-repeat coverage on the new API.
packages/diskgraph/diskgraph-pybind/python/tests/test_ttng.py Native iterator helper Open the iterator with SamplingOptions. Keep TTNG tests compatible without changing their assertions.
packages/diskgraph/diskgraph-pybind/python/tests/bench_runtime_batch_iterator.py Benchmark iterator helper Construct SamplingOptions before opening the iterator. Keep the existing workload compatible; no benchmark parameters or measurements change.
test/train/datamodule/test_diskgraph_lightning_data.py Fake runtime interfaces and assertions Accept SamplingOptions in runtime doubles and assert typed weighted fields/defaults. Verify training scheduling and loader behavior against the new interface.
packages/kumo-engine/test/test_static_link_pseudo_time.py Static-link runtime comparison Open native reference iterators through SamplingOptions. Retain split visibility and CPU training regression coverage.
packages/kumo-engine/test/test_timestamp_batch_cap.py Grouped timestamp native reference Construct SamplingOptions in the reference iterator helper. Retain exact cap/refit behavior across loader worker counts.
packages/diskgraph/README.md Runtime sampling API Document the dataclass API, replace-based epoch changes, seed inheritance, and shallow frozen semantics. Make the intentional API migration and container ownership clear.
packages/kumo-core/src/kumo_core/explain/subgraph_collector.py Link prediction graph export Check predicted RHS membership in exported nodes, including nodes omitted by residual aggregation; narrow the RHS table name before dictionary lookup. Preserve predicted items in explanation artifacts.
packages/kumo-core/tests/explain/test_subgraph_collector_predictions.py Prediction export regression Force aggregation at zero, one, and two retained neighbors; verify sampled and unsampled predictions appear exactly once. Cover the engine CI failure deterministically without training or filesystem access.

@haoweiyu-kumo
haoweiyu-kumo force-pushed the hyu-diskgraph-sampling-options branch from d92e911 to 163ac01 Compare November 21, 2026 05:57
@haoweiyu-kumo
haoweiyu-kumo temporarily deployed to gha-kumo-workflow-tests November 21, 2026 05:57 — with GitHub Actions Inactive
@haoweiyu-kumo
haoweiyu-kumo temporarily deployed to gha-kumo-workflow-tests November 21, 2026 07:53 — with GitHub Actions Inactive

This branch was previously deployed

1 inactive deployment
gha-kumo-workflow-tests — e7775dc3 Deployed Nov 21, 2026 by haoweiyu-kumo via import #2896
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant