Reference

Command line

Every `tabagent` command and flag, rendered from the argparse parser of the installed version.

tabagent is installed with the package. Each command below shows its usage line, its description and its options, exactly as tabagent COMMAND --help prints them. Add -v to any command to log progress and -vv to see tracebacks.

$ tabagent --help
usage: tabagent [-h] [--version] [-v] COMMAND ...

TabAgent: replace an LLM agent's closed-set decisions with cheap tabular classifiers.

positional arguments:
  COMMAND
    scan         find the LLM calls in agent logs that TabAgent can replace
    components   list the decision components in agent logs
    check-logs   diagnose agent logs before onboarding (no LLM call)
    onboard      discover features, train and evaluate a head from agent logs
    runs         inspect TabSchema run directories
    serve        serve a saved head over HTTP
    verify-head  re-run a saved head's extractor tests, for CI and deployment gates
    datasets     list, describe or build the public benchmark datasets
    cite         print how to cite TabAgent

options:
  -h, --help     show this help message and exit
  --version      show program's version number and exit
  -v, --verbose  log progress (-vv: also tracebacks)

Exit status

A command returns 0 success, 1 partial failure, 2 user error, 3 a stop that a rerun with the same run directory resumes from (a spent budget, a provider that stayed down), 130 interrupted.

tabagent scan

Find the LLM calls in agent logs that TabAgent can replace.

Rank every component of the agent that calls an LLM: its calls per run and, where the logs record usage, its share of the agent's LLM tokens, latency and cost; whether its outputs come from a closed set of candidates (the decisions TabAgent replaces), with the evidence; how many successful runs contain it; and the onboard command for the top candidates. Reads the logs only: no LLM is called.

usage: tabagent scan [-h] [-v] [--no-lazy] [--on-other-formats {skip,error}]
                     [--price-in PRICE_IN] [--price-out PRICE_OUT]
                     [--format {text,markdown,json}] [--top TOP]
                     logs

Argument	Description
logs	a log file or a directory of logs

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--no-lazy	hold every run in memory; by default, from 256 MB of logs, runs are read again from their files when needed (and a file that changes meanwhile stops the command)
--on-other-formats	what to do with runs of another log format in the folder: skip them with a warning, or stop	skip, error	skip
--price-in PRICE_IN	USD per 1M input tokens, to price every call from its recorded tokens
--price-out PRICE_OUT	USD per 1M output tokens (with --price-in)
--format	output format	text, markdown, json	text
--top TOP	closed-set candidates to detail, with their next step		3

tabagent components

List the decision components in agent logs.

List the decision components found in the successful runs of agent logs, by count.

usage: tabagent components [-h] [-v] [--no-lazy] [--on-other-formats {skip,error}]
                           logs

Argument	Description
logs	a log file or a directory of logs

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--no-lazy	hold every run in memory; by default, from 256 MB of logs, runs are read again from their files when needed (and a file that changes meanwhile stops the command)
--on-other-formats	what to do with runs of another log format in the folder: skip them with a warning, or stop	skip, error	skip

tabagent check-logs

Diagnose agent logs before onboarding (no LLM call).

Read the logs as onboard would and report what is wrong, where and how to fix it: the files read, skipped or repaired; the runs and their outcomes; and, for each decision, its decision points, candidates and labels (chosen candidates missing from the offered ones, with near-miss names), whether live prefixes are rebuilt exactly as in training, and the check that no prefix holds post-decision data. Exits with status 1 when a problem would stop an onboarding.

usage: tabagent check-logs [-h] [-v] [--no-lazy] [--on-other-formats {skip,error}]
                           [--decision DECISION] [--format {text,json}]
                           [--sample SAMPLE]
                           logs

Argument	Description
logs	a log file or a directory of logs

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--no-lazy	hold every run in memory; by default, from 256 MB of logs, runs are read again from their files when needed (and a file that changes meanwhile stops the command)
--on-other-formats	what to do with runs of another log format in the folder: skip them with a warning, or stop	skip, error	skip
--decision DECISION	the decision to check (default: every decision the adapter builds)
--format	output format	text, json	text
--sample SAMPLE	decision points whose live prefix is rebuilt and compared		200

tabagent onboard

Discover features, train and evaluate a head from agent logs.

Discover a feature card with TabSchema, train and evaluate a head, and save it. The LLM comes from environment keys: OpenAI, Azure OpenAI or any OpenAI-compatible server (OPENAI_API_KEY, OPENAI_BASE_URL), or Anthropic, Gemini and others through LiteLLM (tabagent[llm]).

usage: tabagent onboard [-h] [-v] [--no-lazy] [--on-other-formats {skip,error}]
                        [--decision DECISION] [--model MODEL]
                        [--kind {ranking,multilabel,single}] [--out OUT]
                        [--config FILE] [--n-analyze N_ANALYZE] [--accept DECISIONS]
                        [--sample-strategy {coverage,tasks}] [--max-cost MAX_COST]
                        [--workers WORKERS] [--timeout TIMEOUT]
                        [--llm-retries LLM_RETRIES] [--audit-samples AUDIT_SAMPLES]
                        [--request-timeout SECONDS] [--price-in PRICE_IN]
                        [--price-out PRICE_OUT] [--stage-model STAGE=MODEL]
                        [--fallback-model FALLBACK_MODEL] [--price MODEL=IN,OUT]
                        [--catalog CATALOG] [--search {fast,full}]
                        [--llm-cost-per-call LLM_COST_PER_CALL] [--trust-extractor]
                        [--run-dir RUN_DIR] [--gate-coverage GATE_COVERAGE]
                        [--redact MODULE:FUNCTION] [--no-audit]
                        [--no-verify-extractor] [--no-verify-adapter]
                        [--no-usefulness] [--no-compile-repair] [--no-context-text]
                        [--no-last-step-text] [--no-positional-guard]
                        [--no-relative-features] [--prune-harmful] [--dry-run]
                        logs

Argument	Description
logs	a log file or a directory of logs

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--no-lazy	hold every run in memory; by default, from 256 MB of logs, runs are read again from their files when needed (and a file that changes meanwhile stops the command)
--on-other-formats	what to do with runs of another log format in the folder: skip them with a warning, or stop	skip, error	skip
--decision DECISION	the component to replace (see tabagent components)
--model MODEL	LLM for TabSchema (default: GPT-5.4, or the provider found in the environment)
--kind	the decision pattern (default: the adapter's for the decision, else ranking)	ranking, multilabel, single
--out OUT	directory for the saved head
--config FILE	TabSchemaConfig fields as JSON or YAML (e.g. {"n_analyze": 10, "audit_samples": 8}); the flags below override it
--n-analyze N_ANALYZE	decision points the LLM analyzes (default 20)
--accept DECISIONS	MetaJudge outcomes compiled into the card, comma-separated (default accept,conditional; e.g. accept for the strict policy)
--sample-strategy	how the analyzed decision points are sampled (default coverage)	coverage, tasks
--max-cost MAX_COST	stop TabSchema before a call that could take its LLM cost past this (USD); needs prices. The run stops resumable (exit status 3): rerun with the same --run-dir and a larger budget
--workers WORKERS	TabSchema LLM calls at once (default 8)
--timeout TIMEOUT	seconds the generated code may run on one trajectory (default 30)
--llm-retries LLM_RETRIES	retries of an LLM call that fails transiently (rate limit, timeout, server error; default 5)
--audit-samples AUDIT_SAMPLES	decision points the OutputAuditor judges (default 12)
--request-timeout SECONDS	seconds one LLM request may take (default: max(300, 120 + output-token limit / 40))
--price-in PRICE_IN	the model's price, USD per 1M input tokens
--price-out PRICE_OUT	the model's price, USD per 1M output tokens
--stage-model STAGE=MODEL	a model for one TabSchema stage (analyzer, extractor, validator, aggregator, judges, meta_judge, auditor); repeatable
--fallback-model FALLBACK_MODEL	asked once, for any stage, when the provider's content filter stops an answer
--price MODEL=IN,OUT	a model's price, USD per 1M input and output tokens (for --stage-model and --fallback-model models); repeatable
--catalog CATALOG	a tool catalog file (OpenAI or Anthropic tool schemas, MCP tools, or {name: description}): the candidates' names, descriptions and argument hints, when the logs do not carry them
--search	training recipe search grid	fast, full	fast
--llm-cost-per-call LLM_COST_PER_CALL	cost of the replaced LLM call (USD), for the report
--trust-extractor	run the LLM-written extractor in-process instead of in the sandbox (review it first)
--run-dir RUN_DIR	TabSchema run directory (default under $TABAGENT_CACHE/runs)
--gate-coverage GATE_COVERAGE	calibrate the confidence gate to keep this share of decisions
--redact MODULE:FUNCTION	a function applied to every trajectory before any LLM call (an import path, e.g. mypkg.privacy:scrub); recorded in head.json, and applied when serving only if passed again
--no-audit	skip the OutputAuditor, the LLM check of the extracted values (saves its LLM calls)
--no-verify-extractor	skip the compile-time checks of the extracted values (determinism, outcome and future invariance, robustness)
--no-verify-adapter	skip only the check that the log adapter's prefixes hold no post-decision data (it runs before any LLM call and stops a leaking adapter); for an adapter whose prefixes hold the decision step's own input, declare decision_input_keys instead
--no-usefulness	skip the usefulness estimate (drop-feature grouped CV on the onboarding rows; no LLM calls)
--no-compile-repair	do not ask the CodeExtractor once more for the features the CodeValidator flags at compile
--no-context-text	do not append the fixed context-text function to the extractor
--no-last-step-text	do not append the fixed last-step-text function to the extractor
--no-positional-guard	keep prefix columns that index the candidates by position, and do not ask the CodeExtractor to compute their features per candidate
--no-relative-features	leave each candidate feature's rank and gap within its decision out of the card
--prune-harmful	drop the features whose removal clearly helps in grouped CV on the onboarding rows (by default the usefulness estimate is a report only)
--dry-run	estimate the work and cost, call no LLM

tabagent runs

Inspect TabSchema run directories.

show: a run directory's anatomy, stage by stage: what each stage produced, what was dropped and why, what failed, the LLM calls, tokens and cost, from run.json (or rebuilt from the stage files of an older run). list: the run directories under ROOT (default $TABAGENT_CACHE/runs).

usage: tabagent runs [-h] [-v] [--json] {show,list} [path]

Argument	Description
action	show one run, or list the runs under a root
path	the run directory (show) or the root directory (list)

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--json	print the machine-readable summary

tabagent serve

Serve a saved head over HTTP.

Serve a head saved by onboard over HTTP (needs pip install "tabagent[serve]").

usage: tabagent serve [-h] [-v] [--host HOST] [--port PORT] [--trust-extractor]
                      [--sandbox {warm,subprocess,docker,docker:IMAGE}]
                      [--workers WORKERS] [--request-timeout SECONDS]
                      [--threads THREADS] [--log-format {json,text}] [--log-content]
                      [--no-drift] [--drift-window DRIFT_WINDOW]
                      [--graceful-timeout SECONDS] [--redact MODULE:FUNCTION]
                      [--allow-unpinned] [--allow-unchecked-extractor]
                      path

Argument	Description
path	a head saved by onboard: its directory, or hf://OWNER/REPO[@REVISION]

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--host HOST	interface to listen on		127.0.0.1
--port PORT	port to listen on		8077
--trust-extractor	run the extractor in-process (reviewed code only)
--sandbox {warm,subprocess,docker,docker:IMAGE}	where the untrusted extractor runs: persistent resource-limited worker processes (warm), a fresh resource-limited subprocess per decision, or Docker with no network and a read-only filesystem		warm
--workers WORKERS	warm extractor workers, i.e. extractions at once (default min(4, CPUs))
--request-timeout SECONDS	seconds the extractor gets per decision; a later answer is deferred to the LLM (0: no limit)		10.0
--threads THREADS	decisions computed at once		8
--log-format	log record format	json, text	json
--log-content	also log each request's prefix, run, candidates, answer and error message (off: the agent's data stays out of the logs)
--no-drift	do not monitor feature drift
--drift-window DRIFT_WINDOW	recent decisions compared for drift		500
--graceful-timeout SECONDS	on SIGTERM or Ctrl+C, how long in-flight decisions may finish before the workers stop		30.0
--redact MODULE:FUNCTION	the redaction function the head was onboarded with, applied to every run before its prefix
--allow-unpinned	serve a head whose card pins no hash for extract.py (saved by an earlier version); review extract.py first, and save the head again to pin it
--allow-unchecked-extractor	run, still in the sandbox, an extract.py that fails the extraction rules (a head saved by an earlier version that imports time, say); review it first: the sandbox is not a security boundary

tabagent verify-head

Re-run a saved head's extractor tests, for CI and deployment gates.

Check a head saved by onboard: extract.py matches the card's hash, and re-running it in the sandbox on the golden prefixes of extractor_tests.json reproduces every recorded feature, twice, with outcome fields making no difference. Exits with status 1 when a check fails.

usage: tabagent verify-head [-h] [-v] [--sandbox {subprocess,docker,docker:IMAGE}]
                            [--require-goldens]
                            path

Argument	Description
path	a head saved by onboard: its directory, or hf://OWNER/REPO[@REVISION]

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--sandbox {subprocess,docker,docker:IMAGE}	where the extractor runs (docker for a head you do not trust, e.g. from the Hub)		subprocess
--require-goldens	fail when the head has no golden prefixes (by default that passes with a warning: a head onboarded with goldens=0 carries no trajectory text)

tabagent datasets

List, describe or build the public benchmark datasets.

Without arguments, list the datasets. With NAME, describe it; add --download to build it. --all --download fetches and builds every dataset that needs no license opt-in or local copy.

usage: tabagent datasets [-h] [-v] [--all] [--download] [--accept-license] [name]

Argument	Description
name	a dataset name, for example skillsbench/skill-select

Option	Description	Choices	Default
-v, --verbose	log progress (-vv: also tracebacks)
--all	every registered dataset
--download	fetch missing source files and build the table
--accept-license	confirm the upstream terms of datasets that ask for it

tabagent cite

Print how to cite TabAgent.

Print the citation of the TabAgent paper: BibTeX (the default), APA or a line of text.

usage: tabagent cite [-h] [--format {bibtex,apa,text}]

Option	Description	Choices	Default
--format	the citation style	bibtex, apa, text	bibtex