tab-foundry on tab-foundry Docs

Artifacts & Inference

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when the question is about the files and contracts this repo owns.

tab-foundry turns manifests, corpora, and training configs into run directories, checkpoints, benchmark results, and export bundles. This repo stops at producing validated handoff artifacts; downstream runtime systems own long-lived serving.

Start With

ML Engineering: the fastest operational route through repo ownership, artifacts, and verification flows
Workflows: command syntax and artifact expectations
Inference Contract: export-bundle schema and runtime handoff boundary
Getting Started: repo orientation and shared terminology

Key Questions

What does a training run emit?
What is the difference between a manifest, a checkpoint, and an export bundle?
How do I inspect one run or validate one bundle?
What does this repo own, and what belongs in downstream runtime systems?

Papers And References

Mon, 01 Jan 0001 00:00:00 +0000

Start here when you want the reading list that actually informs architecture, training, and scaling decisions in tab-foundry.

This list overlaps with ~/dev/dagzoo/reference, but the lens here is architecture, training recipe, and scaling predictability rather than data generation.

Use these alongside this reference set:

Design decisions and repo structure: docs/development/design-decisions.md
Roadmap: docs/development/roadmap.md
Workflow runbooks: docs/workflows.md
Evidence mapping: reference/evidence.md

Adoption Tiers For This Repo

Use this directory to make explicit judgments, not just collect papers.

tab-foundry

Mon, 01 Jan 0001 00:00:00 +0000

A tabular foundation model that generates the data it learns from.

Most tabular foundation models learn from a fixed corpus and stop. You get a .predict() call and a benchmark number, but no control over the data the model trained on, the architecture it uses, or the training loop that produced it.

tab-foundry takes a different approach. It uses dagzoo to generate synthetic tabular datasets, trains them with an active sandwich lane plus a frozen PFN control and historical staged reference lane, benchmarks against real-world tasks, and exports inference bundles you can deploy. You control the full pipeline: what data gets generated, which model surface is active, how training runs, and what gets exported.

Roadmap (202604)

Mon, 01 Jan 0001 00:00:00 +0000

Use this roadmap to understand which questions are active now, which surfaces are frozen, and what evidence the repo still needs before promotion.

The repo-wide plan is now sandwich-first:

keep one frozen PFN-style control lane for trust and comparison
treat tabfoundry_sandwich as the active classification architecture target and scaling-prep family
use the closed TF-RD-010 classification benchmark contract as the fixed anti-saturation regime before the first scaling fit
treat steering-derived dagzoo fronts and other synthetic-surface expansion work as sidecars rather than blockers on the tab-foundry critical path
make bounded kernel/runtime and VRAM optimization a hard prerequisite to later scaling so every scale ladder inherits one measured runtime policy
defer regression from the first classification scaling plan

Use these alongside this roadmap:

Sweeps

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when the question is about the active sweep, the current anchor, or the next allowed research change.

A sweep is the repo’s way of testing one research change at a time without losing attribution. If you need the broader architecture or synthetic-data context, pair this page with Research.

Start With

Sweep Contract: queue discipline, locked surface, artifact requirements, and execution loop
Workflows: command syntax for inspect, execute, promote, render, and validate
Roadmap: which questions are actually next
References: evidence and literature context

Inspect-First Commands

.venv/bin/tab-foundry research sweep list-sweeps
.venv/bin/tab-foundry research sweep list --sweep-id <sweep_id>
.venv/bin/tab-foundry research sweep next --sweep-id <sweep_id>
.venv/bin/tab-foundry research sweep summarize --sweep-id <sweep_id> --include-screened
.venv/bin/tab-foundry research sweep inspect --order <order> --sweep-id <sweep_id>

Problem Formulation

Mon, 01 Jan 0001 00:00:00 +0000

The primary objects are:

data-side prior parameters $\phi$ for the synthetic task generator
model-side parameters $\theta$ for the sandwich model

Everything else in the repo should be understood as machinery for sampling from the induced task distribution and optimizing the resulting objectives.

Use these alongside this page:

architecture reference: Model Architecture
canonical roadmap: Roadmap
workflow runbooks: Workflows
sweep contract: Sweep Contract
reference index: References

Problem Setup

Let a supervised tabular task be

T = (X_{\mathrm{tr}}, Y_{\mathrm{tr}}, X_{\mathrm{te}}, Y_{\mathrm{te}}, \tau).

with:

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

Use this glossary when architecture, sweep, artifact, and workflow terms start to carry too much repo-specific meaning.

Anchor

The locked comparison run for a sweep. New rows are judged against the anchor unless the queue row explicitly declares a different preserved surface.

Architecture-Screen Surface

The canonical benchmark-facing sandwich surface used for current architecture work. Historical staged surfaces still exist for comparison, but they are no longer the default landing zone for new architecture evidence.

Literature Evidence Mapping

Mon, 01 Jan 0001 00:00:00 +0000

Use this map when you need to trace a roadmap claim back to papers and the most important repo-local evidence.

Use these alongside this map:

Canonical roadmap: docs/development/roadmap.md
Design decisions and repo structure: docs/development/design-decisions.md
Architecture reference: docs/development/model-architecture.md
Paper index: reference/papers.md
Detailed research-epic notes: reference/roadmap_evidence/README.md

Conventions:

Confidence: high, medium, or low
Lane: roadmap milestone lane supported by this evidence (Now, Next, Later)

Detailed Research Epic Notes

reference/evidence.md remains the compact cross-epic map. Canonical long-form evidence for TF-RD-018 and later research-oriented epics now lives under reference/roadmap_evidence/.

Model Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Use this reference when you need the live architecture surface, the active model family, and the current sandwich forward path.

The repo now has one active architecture-development lane:

tabfoundry_sandwich: the primary classification architecture target and scaling-prep family

It also keeps two comparison lanes:

tabfoundry_simple: the frozen PFN-style control
tabfoundry_staged: the historical row-first reference line and benchmark comparison surface

Regression is still deferred. The active model surface is classification-only.

Use these alongside this page:

Agent Program

Mon, 01 Jan 0001 00:00:00 +0000

Use this contract when you are running or reviewing a selected anchor-only system-delta sweep in tab-foundry.

Use docs/workflows.md for command syntax and artifact expectations. Use this contract for the objective, the locked comparison surface, the queue discipline, and the interpretation policy.

Treat this as a research-execution contract, not the architecture roadmap. A selected sweep may intentionally hold a PFN-adjacent, hybrid diagnostic, or sandwich-local surface fixed while isolating one question. The long-term direction for the public model surface still comes from docs/development/roadmap.md and docs/development/model-architecture.md.

Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Use this runbook when you need command syntax, artifact expectations, or the smallest safe verification slice.

Use these alongside this runbook:

README.md for repo overview and quickstart
CONTRIBUTING.md for review expectations
Codebase Navigation for ownership
Dataset Curation for license policy
Inference Contract for export/runtime details
program.md for sweep policy

Environment And Verification

Python 3.14 is pinned in .python-version.
Use ./scripts/dev for bootstrap, doctor, verification, and Iris smoke.
Use the packaged CLI for everything else.

Bootstrap the repo-local environment:

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Use this guide when you want to make a bounded change without reopening the entire system.

Start with README.md, then go directly to the owner docs that match your question:

README.md for the repo overview and quickstart
docs/workflows.md for command examples and artifact expectations
program.md for the active system-delta sweep contract
docs/development/roadmap.md for research priorities and TF-RD sequencing
docs/development/model-architecture.md for the live model surface
docs/development/codebase-navigation.md for package ownership and entrypoint boundaries
docs/inference.md for export/runtime handoff details
docs/glossary.md for sweep and architecture vocabulary

If a Markdown file and .venv/bin/tab-foundry ... --help disagree, trust the CLI and update the Markdown file.

Design Decisions

Mon, 01 Jan 0001 00:00:00 +0000

Use this page to understand the durable decisions behind the current architecture, repo structure, and compatibility boundaries.

Use these alongside this page:

quickstart: README.md
problem formulation: docs/development/synthetic-prior-mission.md
workflow runbooks: docs/workflows.md
canonical roadmap: docs/development/roadmap.md
architecture reference: docs/development/model-architecture.md
codebase navigation: docs/development/codebase-navigation.md
maintained dependency map: docs/development/module-dependency-map.md
reference index: reference/README.md
curated references: reference/papers.md
evidence mapping: reference/evidence.md

Direction

tab-foundry should not fragment across multiple live model families.

The active architecture surface is now tabfoundry_sandwich, with tabfoundry_simple retained only as the frozen exact anchor and tabfoundry_staged retained only as the historical reference line. The repo should evolve through:

Inference Contract

Mon, 01 Jan 0001 00:00:00 +0000

Use this contract when you need to know what this repo hands to downstream runtime systems and what must remain stable.

Use these alongside this contract:

quickstart: README.md
workflow runbooks: docs/workflows.md
design decisions and repo structure: docs/development/design-decisions.md
architecture reference: docs/development/model-architecture.md
model config reference: docs/development/model-config.md
canonical roadmap: docs/development/roadmap.md

Planning and architecture rationale live under docs/development/, while this page stays focused on the exported bundle and the validation boundary that downstream consumers rely on.

TF-RD-013 Shape-Aware Support Bundle

Mon, 01 Jan 0001 00:00:00 +0000

Use this support bundle when you need the committed assumptions and comparison surfaces behind TF-RD-013 issue #127.

It is a historical reference-only support surface for that shape-aware follow-up, not the main roadmap or sweep execution guide. Reconstructing these local artifacts is no longer a supported workflow.

Environment assumptions:

TAB_FOUNDRY_ROOT is this repo root.
DAGZOO_ROOT defaults to the sibling checkout ../dagzoo.
The broader dagzoo follow-up uses three config-backed invocations:
- ../dagzoo/configs/benchmark_cpu.yaml with 2048 datasets
- ../dagzoo/configs/default.yaml with 4096 datasets
- ../dagzoo/configs/benchmark_cuda_h100_large_shape.yaml with 128 datasets
The curated comparator baseline remains pinned to data/manifests/bench/openml_classification_large_v1/manifest.parquet.

Historical support surface:

Codebase Navigation

Mon, 01 Jan 0001 00:00:00 +0000

Use this map when you need to find the right package, entry point, or workflow surface before making a change. It complements docs/development/module-dependency-map.md, which records the observed top-level package graph plus the intended dependency direction policy.

This file owns package and entrypoint routing. It does not try to mirror the full packaged CLI surface. For live command names and flags, use .venv/bin/tab-foundry ... --help.

1. Entry Points And Orchestration

These are the user-facing or repo-local control surfaces that bridge commands into the canonical library modules.

Module Dependency Map

Mon, 01 Jan 0001 00:00:00 +0000

Use this map when you need the current package graph or want to plan a refactor without reopening dependency cycles.

The observed graph is synchronized against scripts/audit/module_graph.py --fail-on-doc-drift. Keep the current-state section factual and keep design intent in the policy section below it.

Observed Current Top-Level Package Graph

tab_foundry.__main__ depends on tab_foundry.cli.
tab_foundry.bench depends on tab_foundry.config, tab_foundry.control_baseline_registry, tab_foundry.data, tab_foundry.device, tab_foundry.external_benchmarks, tab_foundry.benchmark_registry, tab_foundry.input_normalization, tab_foundry.model, tab_foundry.preprocessing, tab_foundry.registry, tab_foundry.repo_paths, tab_foundry.task_batching, tab_foundry.timestamps, tab_foundry.training, and tab_foundry.types.
tab_foundry.benchmark_registry depends on tab_foundry.registry and tab_foundry.repo_paths.
tab_foundry.cli depends on tab_foundry.bench, tab_foundry.benchmark_registry, tab_foundry.config, tab_foundry.config_inspection, tab_foundry.control_baseline_registry, tab_foundry.data, tab_foundry.device, tab_foundry.export, tab_foundry.external_benchmarks, tab_foundry.model, tab_foundry.repo_paths, tab_foundry.research, tab_foundry.task_batching, and tab_foundry.training.
tab_foundry.config depends on tab_foundry.repo_paths.
tab_foundry.config_inspection depends on tab_foundry.config, tab_foundry.data, tab_foundry.model, tab_foundry.preprocessing, and tab_foundry.training.
tab_foundry.control_baseline_registry depends on tab_foundry.registry and tab_foundry.repo_paths.
tab_foundry.data depends on tab_foundry.benchmark_registry, tab_foundry.feature_types, tab_foundry.hashing, tab_foundry.preprocessing, tab_foundry.repo_paths, tab_foundry.task_batching, tab_foundry.timestamps, and tab_foundry.types.
tab_foundry.export depends on tab_foundry.feature_types, tab_foundry.hashing, tab_foundry.model, tab_foundry.preprocessing, tab_foundry.repo_paths, and tab_foundry.types.
tab_foundry.model depends on tab_foundry.feature_types, tab_foundry.input_normalization, tab_foundry.likelihoods, and tab_foundry.types.
tab_foundry.preprocessing depends on tab_foundry.feature_types.
tab_foundry.registry depends on tab_foundry.repo_paths.
tab_foundry.research depends on tab_foundry.bench, tab_foundry.benchmark_registry, tab_foundry.config, tab_foundry.control_baseline_registry, tab_foundry.data, tab_foundry.device, tab_foundry.external_benchmarks, tab_foundry.hashing, tab_foundry.model, tab_foundry.repo_paths, tab_foundry.training, and tab_foundry.types.
tab_foundry.task_batching depends on tab_foundry.types.
tab_foundry.training depends on tab_foundry.data, tab_foundry.device, tab_foundry.feature_types, tab_foundry.hashing, tab_foundry.likelihoods, tab_foundry.model, tab_foundry.preprocessing, tab_foundry.repo_paths, tab_foundry.task_batching, tab_foundry.timestamps, and tab_foundry.types.

Observed cycle status:

Model Config Reference

Mon, 01 Jan 0001 00:00:00 +0000

Use this reference when you need to know which model settings matter, where they come from, and how they resolve across training, evaluation, export, and bundle loading.

Use these alongside this reference:

architecture reference: docs/development/model-architecture.md
inference contract: docs/inference.md
canonical model spec: src/tab_foundry/model/spec.py
config defaults: configs/model/default.yaml

Source Of Truth

The model config surface is shared across several layers, but the roles differ:

configs/model/default.yaml
- Canonical repo-level default values for Hydra-composed train and eval runs.
- This is the intended operator-facing default source.
src/tab_foundry/model/spec.py
- Canonical typed representation of model settings.
- Provides fallback defaults for non-Hydra paths such as checkpoint-based evaluation, export reconstruction, and bundle loading.
Checkpoint payload config.model
- Persists the model settings used for a training run.
- Takes precedence over fallback config when evaluating or exporting a checkpoint.
Export manifest model
- Persists the resolved model settings that an inference/runtime loader needs to reconstruct the model.

Current canonical default:

Dataset Curation And License Review

Mon, 01 Jan 0001 00:00:00 +0000

Use this policy when deciding whether a real-data dataset may enter a curated benchmark bundle or manifest-backed comparator surface in tab-foundry.

Use these alongside this policy:

canonical roadmap: docs/development/roadmap.md
operator workflow runbook: docs/workflows.md
review ledger: reference/dataset_license_reviews.csv

Policy

No real-data dataset may be added to an OpenML benchmark bundle, manifest-backed external set, or other curated benchmark ladder until its license review is complete.
Keep one canonical OpenML baseline where the benchmark tooling is already native, and use vetted manifest-backed external real-data datasets as augmentation lanes when they add regimes that OpenML does not cover cleanly.
The source of truth for approval status is the repo-tracked review ledger at reference/dataset_license_reviews.csv.
This gate applies to OpenML datasets and vetted external real-data sources such as Kaggle mirrors.
dagzoo remains the synthetic-data generation lane. It is not an external real-data source, and its synthetic corpora do not replace the review requirement for any real-data comparator set.

Review Record

Each dataset review record must include these fields:

Third-Party Notices

Mon, 01 Jan 0001 00:00:00 +0000

This documentation site includes bundled assets from the following third-party projects.

Font Awesome Free

Website: https://fontawesome.com
License (Icons): CC BY 4.0
License (Fonts): SIL OFL 1.1
License (Code): MIT

Font Awesome Free by @fontawesome is licensed under CC BY 4.0 (icons), SIL OFL 1.1 (fonts), and MIT (code). Copyright (c) Fonticons, Inc.

Bootstrap

Website: https://getbootstrap.com
License: MIT

Copyright (c) 2011-2024 The Bootstrap Authors Copyright (c) 2011-2024 Twitter, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: