Skip to content

docs(ADR-272): zero-shot tabular foundation model for RuVector (research + plan)#630

Open
shaal wants to merge 1 commit into
ruvnet:mainfrom
shaal:docs/tabfm-tabpfn-foundation-model-adr272
Open

docs(ADR-272): zero-shot tabular foundation model for RuVector (research + plan)#630
shaal wants to merge 1 commit into
ruvnet:mainfrom
shaal:docs/tabfm-tabpfn-foundation-model-adr272

Conversation

@shaal

@shaal shaal commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Refs #629.

Research + plan only — no product code. Adds the artifacts needed for @ruvnet to decide whether and how to add a zero-shot tabular foundation model to RuVector (the tabular sibling of ruvector-timesfm).

What's in this PR

  • docs/adr/ADR-272-*.md — the decision record: motivation, the license gate + pivot, the four highest-impact surfaces, two-track plan, consequences.
  • docs/research/tabfm/PLAN.md — full write-up: TabFM architecture, licensing scorecard, crate-by-crate reimplementation map, and the Track A results.
  • docs/research/tabfm/track_a_benchmark.py + track_a_results.json — the reproducible, license-clean benchmark and its raw output.

TL;DR of the findings

  • License: TabFM + TabPFN-2.5/2.6/3 weights are non-commercial / non-redistributable → can't ship. TabPFN-v2 (clf+reg) is Apache-2.0 + attribution → shippable.
  • Track A (GO): shippable TabPFN-v2 zero-shot on CPU is top-or-tied 5/6 vs tuned XGBoost/HistGBM (mean rank 1.33 vs 2.83), big multiclass win on vehicle. The model we're legally allowed to ship is good enough to own.
  • Ranked uses: (1) core candle port, (2) row-compression tabular-row embedder (row→vector, native to the vector DB), (3) inward zero-shot autotuner for HNSW/IVF/quant knobs, (4) Postgres tab_predict() = local AI.PREDICT.

What this PR deliberately does NOT do

No crate scaffold, no weights vendored, no dependency changes. Direction (which surface first, whether to benchmark the gated v2.5/v3 ceiling, whether to eventually train our own weights) is left open for maintainer decision — merge as a research record, or use as the basis for a scoped implementation issue.

Reproducing the benchmark

python -m venv venv --system-site-packages && source venv/bin/activate
pip install tabpfn xgboost         # sklearn/numpy/pandas assumed present
python docs/research/tabfm/track_a_benchmark.py

(macOS: XGBoost needs libomp; the run used the copy shipped in torch/lib. TabPFN-v2 Apache-2.0 weights auto-download; the gated v2.5/v3 columns are skipped unless a Prior Labs license is accepted — internal benchmarking is license-exempt.)

Research + plan (no implementation) for adding a zero-shot tabular FM to RuVector, framed as the tabular sibling of ruvector-timesfm (port + point inward at the DB's own index/SONA tuning).

Key findings:
- License gate: TabFM weights are non-commercial/non-redistributable -> cannot ship. TabPFN 2.5/2.6/3 likewise. TabPFN-v2 (clf+reg) is Apache-2.0 + attribution (Prior Labs License) -> shippable Track-B base.
- Track A benchmark (docs/research/tabfm/track_a_benchmark.py, license-clean): shippable TabPFN-v2 zero-shot on CPU is top-or-tied on 5/6 OpenML datasets vs tuned XGBoost/HistGBM (mean rank 1.33 vs 2.83); big multiclass win on vehicle (+0.034 AUC). Verdict: GO.
- Highest-impact uses: (1) core candle port, (2) row-compression tabular-row embedder (row->vector, native to the vector DB), (3) inward zero-shot autotuner (predict HNSW/IVF/quant knobs), (4) Postgres tab_predict() = local AI.PREDICT.

Adds ADR-272 + docs/research/tabfm/ (plan, benchmark script, results). No product code; direction left open for maintainer decision.
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