Reference

Tables and cards

The pointwise decision table and the feature card that turns it into columns.

A DecisionTable pairs a DataFrame with a DecisionSpec that names the structural columns. A FeatureCard declares the features computed from it. See Decision kinds.

DecisionSpec dataclass

DecisionSpec(
    kind: Kind,
    group: str,
    label: str,
    candidate: str | None = None,
    decision: tuple[str, ...] = (),
    reward: str | None = None,
    eval: tuple[str, ...] = (),
    strata: str | None = None,
)

The structural columns of a decision table (see the module docstring for each role).

kind is ranking, multilabel, single or policy. Single-class decisions have no candidate column; every other kind needs one, and policies also need a reward column.

decision_cols property

decision_cols: tuple[str, ...]

The columns identifying one decision: decision, or the group when it is empty.

outcome_cols property

outcome_cols: tuple[str, ...]

Columns that carry the outcome of a decision. They are never features.

structural_cols property

structural_cols: tuple[str, ...]

Every column with a structural role (ids, candidate, strata and outcomes).

DecisionTable dataclass

DecisionTable(
    df: DataFrame, spec: DecisionSpec, has_labels: bool = True, _decision_ids: Series | None = None
)

A validated pointwise table plus its DecisionSpec.

has_labels is False for views produced by drop_labels, which is what a model sees at scoring time: the outcome columns are physically absent.

groups property

groups: ndarray

Unique group ids in order of first appearance.

labels property

labels: ndarray

The label column (raises LeakageError on a label-free view).

decision_ids property

decision_ids: Series

One string id per row identifying its decision (slate).

subset

subset(groups: Iterable) -> DecisionTable

The rows of the given groups, in their original order.

drop_labels

drop_labels() -> DecisionTable

A label-free view: the outcome columns are removed (what a model sees at scoring time).

LeakageError

Bases: RuntimeError

Raised when post-decision information could reach the features or a held-out fold: a feature that reproduces the label, an outcome column used as a feature, or a score computed from labels.

FeatureCard dataclass

FeatureCard(
    name: str,
    spec: DecisionSpec,
    features: list[Feature],
    synth_text: list[str] = list(),
    synth_k: int = 0,
    provenance: dict[str, Any] = dict(),
    extractor: dict[str, Any] | None = None,
    card_version: int = CARD_VERSION,
    _fitted: dict[str, FittedFeature] | None = None,
)

A decision's feature card: its DecisionSpec, its features and the text TabSynth may paraphrase.

fit learns the fitted features' statistics on labeled training rows; transform computes every feature for any rows. Cards are saved and loaded as YAML (save, load).

Parameters:

Name	Type	Description	Default
name	str	the card name.	required
spec	DecisionSpec	the decision roles.	required
features	list[Feature]	the Feature list, in column order.	required
synth_text	list[str]	free-text feature columns TabSynth may paraphrase.	list()
synth_k	int	the card's TabSynth variants per row (TabSynth uses it when no k is given).	0
provenance	dict[str, Any]	who or what authored the card, and the paper result it backs.	dict()
extractor	dict[str, Any] | None	the compiled TabSchema extractor it needs (path, sha256), if any.	None

types property

types: dict[str, str]

Feature name -> declared type.

feature_names property

feature_names: list[str]

Feature names in column order.

is_fitted property

is_fitted: bool

True after fit.

context_text_columns

context_text_columns() -> list[str]

Free-text features describing the decision context (text features of the state family).

candidate_text_columns

candidate_text_columns() -> list[str]

Features describing the candidate in words (text or categorical features of the schema family), for example its id, name and description. The extractor's per-candidate features are not among them: the LLM computed them, they are not the candidate's own text.

clone

clone() -> FeatureCard

An unfitted deep copy.

fit

fit(table: DecisionTable) -> FeatureCard

Fit the dependency statistics on the (real, labeled) training rows.

transform

transform(table: DecisionTable) -> DataFrame

The feature frame for table (labeled or label-free), columns in card order.

to_dict

to_dict() -> dict[str, Any]

The card as the plain dict written to card.yaml.

from_dict classmethod

from_dict(d: dict[str, Any], trust_code: bool = False) -> FeatureCard

Build a card from to_dict output. Features computed by modules outside tabagent (python: sources) are refused unless trust_code.

save

save(path: str | Path) -> Path

Write card.yaml (path may be a directory or a .yaml file).

load classmethod

load(path_or_name: str | Path, trust_code: bool = False) -> FeatureCard

Load from a YAML file, a directory containing card.yaml, or a bundled card name.

A card whose features import code from a module outside tabagent (python:<module>:<fn>) raises PermissionError unless trust_code=True.

Feature dataclass

Feature(
    name: str,
    family: Family,
    type: FeatureType,
    source: str = "column",
    args: dict[str, Any] = dict(),
    description: str = "",
    provenance: dict[str, Any] = dict(),
)

One feature of a card.

Parameters:

Name	Type	Description	Default
name	str	the output column name.	required
family	Family	schema, state or dependency (paper Fig. 1).	required
type	FeatureType	text, num or cat; declared, never inferred per fold.	required
source	str	column (the column name itself), a stateless primitive, python:<module>:<fn>, fitted:<name> (fitted on training rows), extractor (produced by TabSchema's extractor), extractor_candidate (produced by its per-candidate function, per candidate row), or relative_rank / relative_gap (another feature's position within its decision).	'column'
args	dict[str, Any]	arguments of the source.	dict()
description	str	free-form documentation.	''
provenance	dict[str, Any]	free-form documentation.	dict()

fitted property

fitted: bool

True for a dependency statistic fitted on training rows (fitted:<name>).