Bundle Framework is the desktop tool that produced the 93%-accurate Desertflow framework — now being packaged so anyone can run leakage-audited per-region machine learning on their own regions and drivers, without writing the pipeline plumbing.
Pre-release · Active development · Internal use complete on the Desertflow bundle · Open-source release planned alongside the EarthArXiv preprint (Q4 2026 / Q1 2027)
What it does
1Workflow
From raw parquet to leakage-audited predictions — without writing pipeline code
Point the GUI at your per-region data files. Pick which features to use (the schema widget tells you which ones are leaky). Hit Wave. The tool trains a specialist per region, calibrates the router, evaluates on a held-out test split, and writes a bundle artifact you can load anywhere.
The same tool produced every number on the Desertflow page. Re-running it on different regions or different drivers is a Wave configuration change — not a code change.
What makes it different from a notebook
⚙
Schema-agnostic
The Bundle Core doesn't hardcode columns. Bring your own regions, your own driver matrix, your own target. The schema widget reads your parquet headers, classifies each column as feature / target / identifier / leakage-flagged, and you click through to confirm.
0 framework files to edit when your schema changes
⌘
Wave workflow
One Wave configuration fans out across hundreds of regions, training years, and calibration windows in a single deterministic pipeline run. Per-specialist crash recovery: if specialist #47 dies, you re-run just that one — the other 88 stay trained.
3 time windows (train / cal / predict) configurable per Wave
🔍
Leakage audit built in
Every column is checked against the published leakage_features.yaml at training time. Matched columns are auto-set to "(ignore)" with a FAIL-2030 marker, and a banner alerts you. The same V/O/C/P audit that runs in Desertflow ships as a first-class GUI feature.
4 leakage channels caught automatically (V/O/C/P)
Who it's for
Anyone running per-region prediction problems where one global model would smooth over what's actually happening in each place.
EO
Remote-sensing researchers studying vegetation, fire, soil moisture, surface temperature, or any per-region variable
ML
Practitioners working on geographic prediction problems who need leakage-safe cross-region validation
EDU
Students learning per-region modeling who want a teaching tool that enforces methodology, not just metrics
REPRO
Reviewers and replication researchers verifying Desertflow's results — the tool is the same one we used
What this replaces
Ad-hoc Jupyter notebooks that train one specialist at a time, accumulate state across cells, and silently leak features between train and test splits.
One-off training scripts with hardcoded column names that break the moment your driver list changes.
Pipeline orchestration boilerplate — task graphs, retries, partial-failure recovery — that every team writes from scratch.
Manual leakage checking — the kind of audit that gets skipped under deadline pressure and ends up in published papers as inflated R² values.
How a Wave runs, end to end
Step 1
Load your data
Point the streaming file loader at a folder of parquet files (one per region, or one big file with a region column). It handles hundreds of files without memory blowup. The schema widget shows what's there.
Step 2
Configure the Wave
Pick your train years, calibration years, and prediction years (three separate windows). Pick your base learner (CatBoost / XGBoost / LightGBM / RF / ElasticNet). Pick your hyperparameters — or hit Auto-tune and let Optuna run ~30 trials per region.
Step 3
Hit Wave, get a bundle
The tool trains each specialist in isolation, saves them incrementally (so a crash on region 47 doesn't kill the other 88), calibrates the router, runs the leakage audit, evaluates on the held-out test split, and writes a single .bundle file you can load anywhere.
TL;DR: Drop parquet in. Click which features to use. Hit Wave. Get a leakage-audited per-region ML system in one artifact — no pipeline code written.
Feature overview
Bundle Framework v0.5 (the current internal build) wraps the per-region ML workflow that Desertflow's methodology requires. The headline features:
Data loading
Streaming parquet loader (handles 100s of files / 100s of GB)
Auto-detection of region column, year column, target column
Schema widget with leakage-flag warnings
Custom driver YAML per region
Training
CatBoost / XGBoost / LightGBM / Random Forest / ElasticNet
Full hyperparameter control (CatBoost: all 30+ params exposed)
Optuna auto-tune (~30 trials per region, parallel-safe)
Memory-safe per-region training (no 26+ GiB OOM)
Per-specialist incremental save (crash recovery)
Wave workflow
Three independent time windows: train / cal / predict
Fan out across N regions in one config
Per-region progress + status streaming
Resume-from-checkpoint after partial failure
Validation & audit
Leakage-features YAML auto-applied at training time
FAIL-2030 marker on auto-ignored columns
Per-cell + per-region R² / MAE reporting
Cross-continental held-out evaluation harness
UX
Dark mode
Scrollable tabs · opens maximized
Live training progress + log streaming
No internet required at training time
Output
Single .bundle artifact: weights + router + metadata
Loadable into a 3-line Python predict() call
Reproducible from a single Wave config file
Versioned metadata (schema spec, audit results, training time)
GUI layout — the tabs
The desktop app is organized as five tabs, each one a discrete phase of the workflow. You can jump between them, but the natural flow is left-to-right:
┌──────────┬──────────┬──────────┬──────────┬──────────┐
│ Schema │ Train │ Wave │ Predict │ Audit │
├──────────┼──────────┼──────────┼──────────┼──────────┤
│ Load │ Single- │ Multi- │ Apply a │ Inspect │
│ parquet │ region │ region │ trained │ leakage │
│ files, │ training │ training │ bundle │ checks, │
│ classify │ + hyper- │ across │ to new │ verify │
│ columns, │ param │ regions, │ data & │ feature │
│ flag │ tuning, │ years, │ get NDVI │ inclusion│
│ leaky │ Optuna │ windows │ forecast │ decisions│
│ ones │ search │ in one │ │ │
│ │ │ click │ │ │
└──────────┴──────────┴──────────┴──────────┴──────────┘
Each tab persists its state, so you can configure a Schema in tab 1, train one specialist in tab 2 to sanity-check, then jump to tab 3 to fan out across all regions.
The Wave workflow in detail
The Wave tab is the centerpiece. A single Wave run encodes a complete experiment:
Pick the regions. All of them (89 trained), a biome subset (e.g., "all arid regions"), or a single region for fast iteration.
Pick the three time windows. Train years (e.g., 2002–2018), calibration years (e.g., 2019–2021), prediction year (e.g., 2022). These are independent so you can stress-test temporal generalization.
Pick the base learner. CatBoost is the default (matches Desertflow). Switch to XGBoost / LightGBM / RF / ElasticNet for ablations.
Pick hyperparameters or auto-tune. Either lock the hyperparameters globally, or let Optuna search per-region. Auto-tune adds ~30 trials × N regions but typically lifts R² by 0.02–0.05.
Hit Wave. The tool sequentially trains each specialist, saves it to disk immediately (no in-memory accumulation), calibrates the router, runs the audit, and evaluates on the held-out test split.
Inspect the bundle. Per-region R², MAE, and audit-skip log all stream live during the run. The final .bundle artifact lands in your output folder.
Crash recovery. If region 47 fails (data corruption, hyperparameter divergence, you ran out of disk), the other 88 stay trained. Re-running the Wave skips already-trained specialists by default — you can iterate on the broken one without recomputing the entire bundle.
Schema-agnostic Bundle Core
The framework's design constraint is that no column name is hardcoded anywhere except in the YAML metadata. You describe your schema in a one-page YAML file:
The Bundle Core reads this schema and routes columns through the training pipeline accordingly. Switching from NDVI forecasting to (say) soil-moisture forecasting is a schema swap, not a code change.
Leakage audit integration
The audit isn't a separate post-hoc check — it's a gate at the start of every training run. The framework loads leakage_features.yaml (the canonical V/O/C/P channel list documented on the Desertflow page), matches it against your schema, and:
Sets any matched column to "(ignore)" with a FAIL-2030 marker.
Logs the exclusion in the training metadata (so reviewers can verify what was skipped).
Shows an in-app banner with the count of auto-ignored columns and the option to override (with a confirmation prompt — overriding the audit requires explicit user action).
The leakage_features.yaml file ships with the framework and is versioned. As new leakage channels are discovered, the file is updated and all subsequent training runs benefit automatically.
The desktop app is bundled as a single Python package; the trained .bundle artifacts have a much smaller runtime dependency (CatBoost + numpy + scikit-learn).
Release status & roadmap
Now — v0.5 (internal use)
All five tabs functional (Schema, Train, Wave, Predict, Audit)
Companion tutorial: "Reproduce the 93% Desertflow result on your machine"
2027 — v1.x (extensions)
Cloud-runner mode (run a Wave on a remote machine, get results back)
Plugin SDK for custom routers
Web-based viewer for .bundle artifacts (drag-and-drop inspection)
FAQ
How is this different from sklearn / PyCaret / AutoML tools?
Most AutoML tools train one model on one dataset. Bundle Framework is built around the per-region case: one specialist per region, combined by a router that handles new regions. It also enforces a leakage audit by default, which AutoML tools generally don't. If your problem is "one model, one dataset," you don't need this — use sklearn. If your problem is "133 regions, each with its own response curve, and I need it to generalize to a 134th region," this is what you want.
Do I need Google Earth Engine to use it?
No. Earth Engine is only used to fetch the per-region driver data in the Desertflow project. Once you have parquet files (from any source — EE, your own sensors, a public dataset), the framework runs entirely offline. You only need EE if you want to reproduce Desertflow's exact data pipeline.
Can I use it for problems other than NDVI?
Yes — that's the schema-agnostic design's whole point. The framework doesn't know what NDVI is; it knows what a target column is. Soil moisture, surface temperature, fire risk, crop yield — anything where per-region specialists make sense as a modeling approach.
What hardware does it need?
The Desertflow Wave (89 specialists × 22 years × ~33 features) trains in a few hours on a laptop with 16 GB RAM. Auto-tune (Optuna ~30 trials per specialist) takes substantially longer — typically overnight. The framework is memory-safe; it streams data per-region rather than loading everything at once.
When can I download it?
Open-source release is planned for Q4 2026 / Q1 2027, alongside the Desertflow EarthArXiv preprint. If you're a researcher who wants early access for a specific replication or extension, email and I'll arrange it.
Is it stable enough to bet a paper on?
The internal v0.5 has been used to produce every number on the Desertflow page, including the 93% headline. The API surface will stabilize in v0.6; v1.0 will be the version we recommend for external replication. Until then, treat it as research-grade software: it works, but expect rough edges.
Get in touch
Questions about the tool, early-access requests, or replication offers — (click to copy)