Reference

scikit-learn estimators¶

The full TabAgent recipe behind fit and predict, for a decision table you already have.

The estimators infer a feature card from your columns, pick TabSynth and the candidate prior by nested grouped validation on the training data only, and fit a CatBoost TabHead. They follow the scikit-learn contract (clone, get_params, cross_val_score with GroupKFold). The guide is Bring your own table.

from tabagent import TabAgentRanker

ranker = TabAgentRanker(group_col="task_id", candidate_col="tool")
ranker.fit(X, y)  # X: one row per (decision, candidate); y: 1 if the candidate was chosen
ranker.rank(X_new, k=5)  # top-5 candidates per decision

TabAgentRanker ¶

TabAgentRanker(
    *,
    group_col: str | None = None,
    candidate_col: str | None = None,
    text_cols: Sequence[str] | None = None,
    pair_embeddings: bool | None = None,
    synth: str | int = "auto",
    prior: str | bool = "auto",
    preset: str | None = None,
    search: str = "fast",
    inner_folds: int = 3,
    threshold: float = 0.5,
    iterations: int | None = None,
    random_state: int = 0,
)

Bases: _TabAgentBase

Rank the candidates of each decision (tool, skill, API, GUI element shortlisting).

The three estimators share their constructor parameters (group_col, candidate_col, synth, prior, preset, search, threshold, ...; see _TabAgentBase). predict decodes a multi-label decision (every candidate at or above threshold, backing off to the best one); rank returns the top k per decision.

Examples:

from tabagent import TabAgentRanker

ranker = TabAgentRanker(group_col="task_id", candidate_col="tool")
ranker.fit(X, y)  # X: one row per (decision, candidate); y: 1 if the agent chose the candidate
ranker.rank(X_new, k=5)  # decision, candidate, score, rank
ranker.selection_  # every recipe the nested validation tried, with its score

Parameters:

Name	Type	Description	Default
`group_col`	`str \| None`	the decision-group (task) column; rows of one group never straddle folds.	`None`
`candidate_col`	`str \| None`	the candidate id column (not used by `TabAgentClassifier`).	`None`
`text_cols`	`Sequence[str] \| None`	columns to treat as free text (otherwise inferred, see `tabagent.auto.infer_type`).	`None`
`pair_embeddings`	`bool \| None`	add the e5 context-candidate similarity; None adds it when the embed extra is installed.	`None`
`synth`	`str \| int`	TabSynth variants per row, `0`/`"off"`, or `"auto"` (chosen by nested validation).	`'auto'`
`prior`	`str \| bool`	the in-fold candidate prior: `True`, `False` or `"auto"` (chosen by nested validation).	`'auto'`
`preset`	`str \| None`	the CatBoost preset with `search="fast"` (default `paper`, the paper's configuration); `search="full"` chooses the preset itself, so passing one there is an error.	`None`
`search`	`str`	`fast` or `full` recipe grid (`tabagent.auto.recipes`).	`'fast'`
`inner_folds`	`int`	folds of the nested selection.	`3`
`threshold`	`float`	the multi-label decision threshold of `TabAgentRanker.predict`.	`0.5`
`iterations`	`int \| None`	override the CatBoost iteration count (for quick runs).	`None`
`random_state`	`int`	seed of the head and of the inner folds.	`0`

fit ¶

fit(X, y, groups=None)

Infer the card from X, select the recipe by nested validation and fit the head.

X has one row per (decision, candidate) (one row per decision for the classifier); groups overrides group_col. Sets card_, recipe_, selection_, agent_ and classes_.

rank ¶

rank(X, groups=None, k: int | None = None) -> DataFrame

Top-k candidates per decision: columns decision, candidate, score, rank (ties ordered by candidate id).

predict ¶

predict(X, groups=None) -> ndarray

Multi-label decoding: 1 where p >= threshold, backing off to the top-1 candidate per decision.

predict_proba ¶

predict_proba(X, groups=None) -> ndarray

Class probabilities: [p(not chosen), p(chosen)] per row, or one column per class of classes_ for the classifier.

decision_function ¶

decision_function(X, groups=None) -> ndarray

p(candidate is chosen) per row (rankings and policies).

score ¶

score(X, y, groups=None) -> float

Mean P@R over decisions (the paper's headline shortlisting metric; ties in expectation, App. L).

report ¶

report(
    X,
    y,
    groups=None,
    *,
    n_splits: int = 5,
    llm_cost_per_call: float | None = None,
    embedding_baseline: bool = False,
)

Grouped-CV evaluation report of the fitted recipe on X, y (see tabagent.report.evaluate).

The recipe (TabSynth, prior, preset) was selected on the data passed to fit; if that is the same data, the report is slightly optimistic about the selection step (noted in the report). embedding_baseline adds the zero-shot e5 baseline; llm_cost_per_call reports the savings.

TabAgentRouter ¶

TabAgentRouter(
    *,
    group_col: str | None = None,
    candidate_col: str | None = None,
    text_cols: Sequence[str] | None = None,
    pair_embeddings: bool | None = None,
    synth: str | int = "auto",
    prior: str | bool = "auto",
    preset: str | None = None,
    search: str = "fast",
    inner_folds: int = 3,
    threshold: float = 0.5,
    iterations: int | None = None,
    random_state: int = 0,
)

Bases: _TabAgentBase

Route each decision to one arm (model, sub-agent, skill on/off). y is the arm's success (0/1).

route returns the chosen arm per decision (the arm with the highest predicted success); score is route@1, the mean realized reward of the chosen arm (App. B.7).

Examples:

from tabagent import TabAgentRouter

router = TabAgentRouter(group_col="task_id", candidate_col="model")
router.fit(X, y)  # one row per (task, model); y: 1 if that model solved the task
router.route(X_new)  # the chosen model per task

Parameters:

Name	Type	Description	Default
`group_col`	`str \| None`	the decision-group (task) column; rows of one group never straddle folds.	`None`
`candidate_col`	`str \| None`	the candidate id column (not used by `TabAgentClassifier`).	`None`
`text_cols`	`Sequence[str] \| None`	columns to treat as free text (otherwise inferred, see `tabagent.auto.infer_type`).	`None`
`pair_embeddings`	`bool \| None`	add the e5 context-candidate similarity; None adds it when the embed extra is installed.	`None`
`synth`	`str \| int`	TabSynth variants per row, `0`/`"off"`, or `"auto"` (chosen by nested validation).	`'auto'`
`prior`	`str \| bool`	the in-fold candidate prior: `True`, `False` or `"auto"` (chosen by nested validation).	`'auto'`
`preset`	`str \| None`	the CatBoost preset with `search="fast"` (default `paper`, the paper's configuration); `search="full"` chooses the preset itself, so passing one there is an error.	`None`
`search`	`str`	`fast` or `full` recipe grid (`tabagent.auto.recipes`).	`'fast'`
`inner_folds`	`int`	folds of the nested selection.	`3`
`threshold`	`float`	the multi-label decision threshold of `TabAgentRanker.predict`.	`0.5`
`iterations`	`int \| None`	override the CatBoost iteration count (for quick runs).	`None`
`random_state`	`int`	seed of the head and of the inner folds.	`0`

route ¶

route(X, groups=None) -> DataFrame

The chosen arm per decision: columns decision, candidate, score, rank.

predict ¶

predict(X, groups=None) -> ndarray

1 for the chosen arm of each decision, 0 elsewhere.

score ¶

score(X, y, groups=None) -> float

Mean route@1: the realized reward of the chosen arm (App. B.7).

TabAgentClassifier ¶

TabAgentClassifier(
    *,
    group_col: str | None = None,
    candidate_col: str | None = None,
    text_cols: Sequence[str] | None = None,
    pair_embeddings: bool | None = None,
    synth: str | int = "auto",
    prior: str | bool = "auto",
    preset: str | None = None,
    search: str = "fast",
    inner_folds: int = 3,
    threshold: float = 0.5,
    iterations: int | None = None,
    random_state: int = 0,
)

Bases: ClassifierMixin, _TabAgentBase

Single-class decisions (e.g. operation type): a standard sklearn classifier.

One row per decision and no candidate column: y is the class (operation type, task category). It follows the scikit-learn contract (classes_, predict, predict_proba, decision_function).

Examples:

from tabagent import TabAgentClassifier

clf = TabAgentClassifier(group_col="task_id")
clf.fit(X, y)  # X: one row per decision; y: its class
clf.predict(X_new)

Parameters:

Name	Type	Description	Default
`group_col`	`str \| None`	the decision-group (task) column; rows of one group never straddle folds.	`None`
`candidate_col`	`str \| None`	the candidate id column (not used by `TabAgentClassifier`).	`None`
`text_cols`	`Sequence[str] \| None`	columns to treat as free text (otherwise inferred, see `tabagent.auto.infer_type`).	`None`
`pair_embeddings`	`bool \| None`	add the e5 context-candidate similarity; None adds it when the embed extra is installed.	`None`
`synth`	`str \| int`	TabSynth variants per row, `0`/`"off"`, or `"auto"` (chosen by nested validation).	`'auto'`
`prior`	`str \| bool`	the in-fold candidate prior: `True`, `False` or `"auto"` (chosen by nested validation).	`'auto'`
`preset`	`str \| None`	the CatBoost preset with `search="fast"` (default `paper`, the paper's configuration); `search="full"` chooses the preset itself, so passing one there is an error.	`None`
`search`	`str`	`fast` or `full` recipe grid (`tabagent.auto.recipes`).	`'fast'`
`inner_folds`	`int`	folds of the nested selection.	`3`
`threshold`	`float`	the multi-label decision threshold of `TabAgentRanker.predict`.	`0.5`
`iterations`	`int \| None`	override the CatBoost iteration count (for quick runs).	`None`
`random_state`	`int`	seed of the head and of the inner folds.	`0`

predict ¶

predict(X, groups=None) -> ndarray

The predicted class per row.

decision_function ¶

decision_function(X, groups=None) -> ndarray

Class scores in the sklearn convention: p(classes_[1]) per row for two classes, else one probability column per class of classes_.

pointwise ¶

pointwise(
    decisions: DataFrame,
    *,
    chosen: str,
    catalog: Iterable | DataFrame,
    candidate_col: str = "candidate",
    candidates: str | None = None,
    label_col: str = "chosen",
) -> DataFrame

Expand one-row-per-decision logs into (decision, candidate) rows.

chosen names a column of list-likes with the candidates the agent selected. catalog is either an iterable of candidate ids or a DataFrame whose candidate_col column holds the ids (its other columns, such as descriptions, are joined onto every row). candidates optionally names a column of per-decision candidate lists (when each decision has its own legal set).

scorer ¶

scorer(metric: str = 'p@r')

A scoring= callable for sklearn model selection, using the estimator's group_col.

metric is any name of tabagent.evaluation.metrics.per_decision (p@r, recall@K, route@1, accuracy, ...); the score is its mean over decisions, ties in expectation (App. L).