Development Docs on tab-foundry Docs

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:

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:

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:

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: