You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Support absolute training bounds for temporal node tasks - #274
Support absolute start_time/end_time training bounds for temporal node classification, regression, ranking, and forecasting. Studio and Engine now share UTC parsing, validation, data clipping, and candidate-anchor filtering.
Native stage routing reserves forecast tails once, so bounded forecasting includes the correct newest complete example. Bounds apply only to training planning; prediction and label evaluation retain later anchors without modifying fitted-plan fields.
Keep legacy train_start_offset/train_end_offset windows supported. Integer start_time/end_time values fail with actionable guidance in default mode; decoupled plans preserve relative integer windows in the aggregation unit. Explicit inferred endpoints work, and the default YAML template exposes supported unset bound fields without changing runtime defaults.
Supplemental core typing adds no diagnostics versus upstream. The pinned repository Pyright command exits successfully, but its existing configuration limits source coverage.
Behavior changes
Invalid bound combinations fail early rather than silently preferring relative offsets. Direct absolute bounds cannot be combined with explicit date/offset window splits; supported ratio splits remain usable. Default-mode integer bounds are rejected; use the legacy relative-offset fields there. Decoupled plans retain their integer start/end window support.
Document temporal node bounds and cover native generation, full forecast horizons, early validation, and CPU fit/save/load/prediction. Share compiled forecast shifts and reject unusable edge windows safely.
It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.
Training plans now accept absolute timestamp bounds for temporal node-prediction tasks. Shared validation parses and normalizes bounds and checks compatibility with offsets and split types. Timestamp generation intersects bounds with available target data and excludes anchors whose complete target horizon exceeds the cutoff. Task planning distinguishes training, prediction, and label-generation purposes. Tests cover validation, timestamp and table generation, model evaluation, and prediction.
Sequence Diagram(s)
sequenceDiagram
participant PredictiveQuery
participant build_training_task_plan
participant build_native_pquery_task_plan
participant _temporal_timestamps
participant resolve_training_window
PredictiveQuery->>build_training_task_plan: request training plan with purpose
build_training_task_plan->>build_native_pquery_task_plan: forward purpose and request
build_native_pquery_task_plan->>_temporal_timestamps: pass bounds and purpose
_temporal_timestamps->>resolve_training_window: resolve bounds against target-data limits
resolve_training_window-->>_temporal_timestamps: return resolved window
_temporal_timestamps-->>build_native_pquery_task_plan: return filtered timestamps
Loading
Merge Risk: Low · up to 1ac0e
Empty bounded windows can produce unstructured errors, and an incompatible explicit split can pass service validation. These are bounded issues to fix or explicitly accept before merging.
Security architecture risk: Low · up to 1ac0e
The inspected changes constrain training-data selection without establishing a new data-access or privilege boundary crossing. Prediction and evaluation preserve their separate behavior, and fitted settings are copied rather than rewritten. Remaining uncertainty concerns uninspected callers and failure handling.
Retained concerns
No architecture-level concerns identified.
Security review details
Security Blast Radius
inferred — The demonstrated propagation is across training-row selection and task planning for the selected query and graph snapshot. The inspected base/head paths do not establish newly reachable data stores, tenant identities, credentials, or privileged execution. Infrastructure and deployment exposure were not independently established.
Trust Boundaries and Controls
observed — Caller-supplied bounds pass through UTC normalization and combination checks before training selection. Absolute-window filtering clips against available target data. Engine prediction retains its matching-snapshot check before compilation; the purpose selection changes planning semantics rather than replacing that check.
Resilience and Maintainability Implications
observed — The new window object is immutable. Label evaluation uses copied settings and a fresh run directory, with cleanup in finally on normal completion or exceptions. These controls limit the inspected transition to local planning and generated files rather than partially updating fitted bounds; live concurrency and interruption recovery were not tested.
Pre-merge checks: 2 · 1
Failed checks: 1 inconclusive
Check name
Status
Explanation
Resolution
Change Map Design Review
The marked change-map comment and linked problem are not available in the supplied context. The repository search found only an instruction to maintain the comment, not its contents. The diff has 1,00…
Provide the full comment beginning <!-- kumo-pr-change-map --> and the linked problem discussion so the design and explanations can be assessed against the code.
Passed checks: 2 passed
Check name
Status
Explanation
Pr Size
The pull request changes 17 files. This is below the limit of 40.
Public Resource Access
The pull request adds or modifies no external resource references in the changed files.
Full details: Change Map Design Review
Explanation
The marked change-map comment and linked problem are not available in the supplied context. The repository search found only an instruction to maintain the comment, not its contents. The diff has 1,006 additions and deletions, so file-level descriptions are permitted. The diff alone cannot establish whether the comment explains the design, verification, and stopping condition accurately.
Resolution
Provide the full comment beginning <!-- kumo-pr-change-map --> and the linked problem discussion so the design and explanations can be assessed against the code.
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Temporal node tasks previously exposed absolute bounds inconsistently between Studio and Engine, could reserve forecasting's future-label tail twice, and could apply fitted training bounds while planning later predictions or evaluation labels. This change shares validation/window resolution, leaves future-tail reservation to native generation, and applies bounds only to training. Absolute bounds use inclusive start anchors and an end label cutoff, intersect available data, support default/eligible ratio splits, and reject conflicting explicit temporal windows or legacy offsets. Default-mode integer start/end values fail clearly; decoupled plans retain relative integer bounds in the aggregation unit. Default-mode relative windows use train_start_offset/train_end_offset. Temporal link prediction is outside the feature scope.
File
Function / scope
What changed
Why
kumo/data/generic/diskgraph_train_table.py
future forecasting offsets
Reuse shared forecast offsets while retaining the compiler's list payload.
Keep Studio and Engine's native horizon inputs consistent.
Convert gated integer bounds using the aggregation unit, resolve the shared base training window, preserve explicit anchor order, warn with the count of dropped explicit training anchors, and bypass training bounds for prediction/labels purposes.
Bound training examples without double-reserving forecast tails or constraining later inference.
Cover three errors before run allocation; combine real fit, later prediction/evaluation, reload, saved-plan equality, and restored score comparison.
Verify public rejection and the complete persistence/inference handoff with minimal overlap.
test/config/test_model_plan.py
model-plan validation and YAML snapshot
Assert supported absolute node fields, default-mode integer rejection, and preserved decoupled node/link integer windows; include their missing defaults in the existing snapshot.
Test field availability while preserving existing default values and relative-offset behavior.
test/pquery/test_predictive_query_v2.py
hosted validation errors
Expect the consolidated shared validation title.
Reflect the single validation source without changing the tested invalid inputs.
Add one UTC/clipping parity case; restore decoupled relative integer cases, retain default-mode rejection, and adjust shared messages.
Prove shared behavior while preserving the remaining upstream generator tests.
Earlier inline-review verification: all 131 core tests, three native cases, the unchanged README quickstart, 316 documentation files, flake8, isort, and diff checks passed. A temporary double-reservation counterfactual fails the new per-stage maxima assertions. The introductory README now matches upstream; public API docstrings retain the contract.
Integer-window restoration: core 132 passed; configuration 379 passed; hosted generator 170 passed, 2 skipped; final native/preflight 6 passed. Default-mode rejection, decoupled node/link validation, calendar-month conversion, and restored hourly Studio anchors are covered. flake8, isort, documentation, and diff checks passed.
Verification: final core pquery suite 132 passed; Engine suites 73 passed; configuration suite 379 passed. Independent final checks: nine consolidated core cases and four real native/lifecycle cases passed. Before test-only consolidation, the shared production changes also passed all hosted pquery tests (486 passed, 48 skipped), hosted generator tests (170 passed, 2 skipped), and generic-data tests (206 passed, 3 skipped). Changed Python files passed flake8 and isort checks. Supplemental focused typing introduced no new diagnostics relative to upstream; existing tool/config limitations remain. The former standalone bounds test file was added and removed within this PR and is absent from the aggregate diff.
Stopping condition: bounded temporal-node generation is consistent across Studio and Engine, the exact newest forecast anchor uses the future tail once, later prediction/labels ignore training bounds without mutating fitted plans, and the five focused regression groups pass. No native implementation, tooling, CI policy, or unrelated feature behavior is changed.
The reason will be displayed to describe this comment to others. Learn more.
Note
Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.
Other comments: 1
packages/kumo-core/src/kumo_core/model_plan.py: 1
803-806: Minor · Functional Correctness · Quick win
Accept "inferred" bounds for temporal node tasks.
With USE_DECOUPLED_SPLITS=false, a plan with start_time="2024-01-01" and end_time="inferred" fails validation. The documented alternative, omitting end_time, works.
Suggested fix
return (_use_decoupled_splits()
or (task_type.is_node_pred and isinstance(value, str)
- and not _is_missing(value)- and not _is_inferred(value)))+ and not _is_missing(value)))
Add a validation test for this plan with USE_DECOUPLED_SPLITS=false.
Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.
The reason will be displayed to describe this comment to others. Learn more.
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
⚠️ Outside diff range comments (1)
Major · Apply absolute bounds to explicit training anchors · pquery.py:1042-1101
packages/kumo-core/src/kumo_core/pquery.py:1042-1101 Major · Functional Correctness · Heavy lift
Apply absolute bounds to explicit training anchors
When a training request supplies explicit timestamps and absolute bounds, _temporal_timestamps returns the timestamps before applying the bounds. The generated table can include anchors before start_time or labels beyond end_time, including incomplete forecast horizons. Apply the bounds to explicit training anchors too, while preserving prediction’s separate anchor behavior.
Reviewing files that changed from the base of the PR and between 0f0a055 and 906547d.
Files selected for processing: 1
packages/kumo-engine/README.md
Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.
Apply absolute training windows to explicit anchors and retain prediction and label-evaluation anchors by clearing fit bounds on copied plans. Accept explicit inferred endpoints without changing default YAML or relative-offset gates.
@coderabbitai Addressed both findings in signed commit bdf16a2d:
Explicit training timestamps now obey absolute bounds, available-data limits, and the full forecast horizon. Input order, duplicates, and off-grid precision are preserved. Prediction metadata and label evaluation clear fit bounds from temporary plan copies, preserving later prediction/evaluation anchors and the stored fitted plan.
Explicit inferred endpoints now validate in default mode. Missing-field defaults, YAML output, integer-offset gates, and link-prediction gates remain unchanged.
Validation: 208 core tests, 379 model-plan tests, 83 query tests, and 24 native workflow tests passed. This includes real CPU fit, prediction/evaluation beyond the fit window, prediction beyond available label data, and bundle reload. flake8 and isort --check-only passed; supplemental typing adds no diagnostics versus upstream. The maintained change map now covers all 12 changed files. Fresh CI is running on the new commit.
129-135: Trivial · Maintainability & Code Quality · Low value
Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.
Simplify the bound computation in the test.
The lower expression has a conditional that binds to the argument of max. The precedence is hard to read. Both branches are valid, but the logic is easy to misread. Compute start and end in named variables first.
Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.
1. Studio now accepts absolute bounds but doesn't implement the new behavior.
The gate change in model_plan.py is shared. Studio validates with it (pquery_api_driver.py:1662), then passes start_time/end_time through model_plan_adapter.py into TrainTableGenerator.generate_timestamps() and on to generate_legacy_timestamps. That path never reaches _temporal_timestamps, so it gets no clipping, no filtering and no UTC normalization.
Repro with label data from 2024‑01‑01 to 2024‑01‑20, COUNT(events.*, 0, 3, days) and step 3:
start_time='2024-01-05', end_time='2024-02-01' produces anchors 01‑29, 01‑26, 01‑23, 01‑20 and so on. Their label windows fall after the data ends, so they become zero labels.
start_time='2023-12-01' produces anchors back to 2023‑12‑06, before any data.
start_time='2024-01-05T00:00:00Z' (the README's format) raises TypeError: Cannot compare tz-naive and tz-aware timestamps. TrainTableGenerator.init (kumo/pquery/train_table_generator.py:298,307) parses with Timestamp(...) and doesn't convert to UTC.
Before this PR, Studio rejected these plans in default mode. I'd suggest:
moving clipping and filtering into the shared timestamp code (kumo_core/training/timestamps.py)
parsing with bounds.parse_time_bound in the Studio generator
adding one test that runs the same plan and stats through both generators and checks the anchors are identical
2. Bounded forecasting reserves the horizon twice. See the inline comment on pquery.py:1090.
Factoring
Validation now lives in several places:
bounds.py
Studio's PreTrainTableValidator.validate_train_time and validate_train_time_compatibility. These have the same rules, different messages, and check offsets against now.
The parsers in relative() and in Studio's generator constructor.
plan.validate already runs validate_time_bounds in Studio, so the Studio validator copies can go.
Bounds on explicit anchors leak into prediction. Bounds are now applied to explicit anchors, and prediction and evaluation pass their anchors through that same parameter. So they have to clear the bounds from the fitted plan (see inline). I'd suggest to apply bounds only on the training path.
Tests
The PR adds about 120 test cases (about 680 lines) for about 210 lines of production code. The same validation rules are checked at four layers: bounds.py, plan.validate, _temporal_timestamps before stats are read, and generate_training_table before artifacts are created. On top of that there are flag × task and "inferred" matrices. I'd suggest to trim to:
Native generation for binary, forecasting and one list task. Check that bounds are respected, all three stages are present, binary labels are exact, and the newest forecasting anchor is exact.
One fit → predict past the training window → evaluate → reload test that also checks the saved plan. This would merge test_bounds_fit_reload_predict into test_evaluate_prediction_after_absolute_training_bounds.
One "fails before artifacts" test with three cases: a malformed timestamp, a train_*_offset conflict, and a window-split conflict.
Studio/Engine anchor parity for the same plan, including a timezone-aware bound and a bound past the data.
A small table-driven _temporal_timestamps test for clipping, partial bounds and UTC.
These could go:
the flag × task and "inferred" matrices
the 1677/2260 date cases
native timezone equivalence across four splits
test_partial_and_clipped_bounds
test_existing_window_controls
Direction
The kumoapi docstrings and Studio's validator both say start_time/end_time should replace train_*_offset. To move toward that without growing scope:
Put parsing and validation in bounds.py, and clipping and filtering in shared timestamp code that both Studio and Engine use.
Gate on the field rather than on the value's type. For now, give integer offsets a clear error message.
Keep the internal flag out of user docs.
Integer offsets (as an alias of train_*_offset) and link prediction can follow later on the same code.
The reason will be displayed to describe this comment to others. Learn more.
Note
Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.
Other comments: 1
kumo/pquery/train_table_generator.py: 1
462-465: Minor · Functional Correctness · Quick win
Convert window ValueErrors into structured validation errors.
TrainingWindow.filter raises a plain ValueError when no anchor remains. resolve_training_window raises the same way when lower >= cutoff. Both are called from generate_timestamps (Lines 414, 462, 465) and generate_timestamps_v2 (Lines 487, 501).
If absolute bounds leave no usable anchors, generate_table raises a raw ValueError instead of TrainingTableGenerationError. validate_scale and the non-skipping validation path raise it instead of returning a ValidationResponse. The existing "Empty training table" error with its remediation hints is bypassed for these cases.
Catch ValueError where the window is applied. Convert it to a ValidationError in the validation paths. Convert it to TrainingTableGenerationError in generate_table.
Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 9 remain after this review.
One remaining small issue, which comes from my earlier feedback. It isn't a big deal in practice since USE_DECOUPLED_SPLITS is off by default and that feature isn't supported with DiskGraph-native generation, but maybe better not regress it.
The PR now also rejects integer start_time/end_time when decoupled splits are on, where they worked before. With the flag on, start_time=-30, end_time=-1 passes plan.validate in main branch but fails in the latest commit on this PR (and test_generate_timestamps_v2_with_relative_start_end_time became a rejection test). Decoupled mode also rejects train_start_offset/train_end_offset, so decoupled plans no longer have any way to set a relative window, and the new error points them to fields they can't use.
That traces back to my comment "For now, give integer offsets a clear error message," which didn't say where. What I should have said: reject integers with a clear error in default mode, where they were never supported, and leave them working when decoupled splits are on.
Suggested fix: only reject integers when _use_decoupled_splits() is false. When it's true, convert them with the aggregation unit as before, using get_date_offset in Studio's generator and the date_offset helper in _temporal_timestamps. Apply the same rule to the link-prediction branch in model_plan.validate, and restore the deleted test.
The reason will be displayed to describe this comment to others. Learn more.
Caution
Some comments are outside the diff and can’t be posted inline due to GitHub limitations.
⚠️ Outside diff range comments (1)
Minor · Reject explicit time-based splits with absolute bounds. · train_table_generator.py:597-598
kumo/pquery/train_table_generator.py:597-598 Minor · Functional Correctness · Quick win
Reject explicit time-based splits with absolute bounds.
PreTrainTableValidator.validate_time_bounds omits split_family. An explicit DateOffsetSplit with absolute bounds can therefore pass service validation and reach timestamp generation, although model-plan validation rejects it.
Apply the same check on this path. Preserve inferred splits, which may also resolve to DateOffsetSplit.
Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design discussion: https://github.com/kumo-ai/kumo/issues/31505
Summary
Support absolute
start_time/end_timetraining bounds for temporal node classification, regression, ranking, and forecasting. Studio and Engine now share UTC parsing, validation, data clipping, and candidate-anchor filtering.Native stage routing reserves forecast tails once, so bounded forecasting includes the correct newest complete example. Bounds apply only to training planning; prediction and label evaluation retain later anchors without modifying fitted-plan fields.
Keep legacy
train_start_offset/train_end_offsetwindows supported. Integerstart_time/end_timevalues fail with actionable guidance in default mode; decoupled plans preserve relative integer windows in the aggregation unit. Explicit inferred endpoints work, and the default YAML template exposes supported unset bound fields without changing runtime defaults.Change map
File-by-file rationale and verification.
Testing Done
flake8 -j 1, package-specificisort --check-only, documentation, and diff checks passed.Behavior changes
Invalid bound combinations fail early rather than silently preferring relative offsets. Direct absolute bounds cannot be combined with explicit date/offset window splits; supported ratio splits remain usable. Default-mode integer bounds are rejected; use the legacy relative-offset fields there. Decoupled plans retain their integer start/end window support.
Checklist