### Install TabICL

Source: https://github.com/soda-inria/tabicl/blob/main/docs/index.md

Install the package using pip.

```bash
pip install tabicl
```

--------------------------------

### Install skrub library

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Install the skrub library for advanced tabular data preprocessing.

```bash
pip install skrub -U
```

--------------------------------

### Install tabicl

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Install the tabicl library using pip. Optional dependencies for forecasting, pre-training, or all features can be installed using package extras.

```bash
pip install tabicl
```

```bash
pip install tabicl[forecast]   # time series forecasting
```

```bash
pip install tabicl[pretrain]   # pre-training
```

```bash
pip install tabicl[all]        # everything
```

--------------------------------

### Install PyTorch on Intel Macs

Source: https://github.com/soda-inria/tabicl/blob/main/docs/index.md

Use conda to install PyTorch if pip installation fails on Intel-based Macs.

```bash
conda install pytorch -c pytorch
```

--------------------------------

### Install SHAP dependencies

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Install optional dependencies required for SHAP explainability features.

```bash
pip install tabicl[shap]
```

--------------------------------

### Install Time-Series Dependencies

Source: https://github.com/soda-inria/tabicl/blob/main/docs/index.md

Install additional dependencies required for forecasting tasks.

```bash
pip install tabicl[forecast]
```

--------------------------------

### TabICLClassifier Full Configuration Options

Source: https://context7.com/soda-inria/tabicl/llms.txt

Presents a comprehensive example of initializing TabICLClassifier with a wide range of parameters. This snippet covers settings for ensemble size, normalization and shuffling methods, outlier handling, prediction confidence, batch size, checkpoint version, device selection, and automatic mixed precision.

```python
# Full configuration with all parameters
clf_full = TabICLClassifier(
    n_estimators=8,            # Ensemble size (more = better but slower)
    norm_methods=["none", "power"],  # Normalization methods
    feat_shuffle_method="latin",     # Feature permutation strategy
    class_shuffle_method="shift",    # Class label permutation
    outlier_threshold=4.0,           # Z-score threshold for outliers
    softmax_temperature=0.9,         # Prediction confidence control
    average_logits=True,             # Average logits vs probabilities
    support_many_classes=True,       # Handle >10 classes
    batch_size=8,                    # Memory vs speed trade-off
    kv_cache=False,                  # Enable for repeated inference
    checkpoint_version="tabicl-classifier-v2-20260212.ckpt",
    device=None,                     # Auto-select CUDA/CPU
    use_amp="auto",                  # Automatic mixed precision
    random_state=42,
    verbose=False,
)
```

--------------------------------

### SHAP Feature Importance for Regression with TabICL

Source: https://context7.com/soda-inria/tabicl/llms.txt

Compute and visualize SHAP values for TabICL regressors. This example uses a dataset with mixed data types and demonstrates handling categorical features.

```python
# Regression example
survey = fetch_openml(data_id=534, as_frame=True)
X = survey.data[survey.feature_names]
import pandas as pd
X = pd.get_dummies(X, drop_first=True)  # Handle categorical
y = survey.target.values.ravel()

X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)

reg = TabICLRegressor(n_estimators=4, device="cpu")
reg.fit(X_train, y_train)

# SHAP for regression (uses 'predict' instead of 'predict_proba')
sv = get_shap_values(reg, X_test[:10])
plot_shap(sv, kind="bar")
```

--------------------------------

### SHAP Feature Importance for Classification with TabICL

Source: https://context7.com/soda-inria/tabicl/llms.txt

Compute and visualize SHAP values for TabICL classifiers to understand feature importance. Requires installing TabICL with SHAP dependencies.

```python
import numpy as np
from sklearn.datasets import load_breast_cancer, fetch_openml
from sklearn.model_selection import train_test_split
from tabicl import TabICLClassifier, TabICLRegressor
from tabicl.shap import get_shap_values, plot_shap

# Install SHAP dependencies: pip install tabicl[shap]

# Classification example
X, y = load_breast_cancer(return_X_y=True)
feature_names = load_breast_cancer().feature_names
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.8, random_state=42
)

clf = TabICLClassifier(n_estimators=4, device="cpu")
clf.fit(X_train, y_train)

# Compute SHAP values
shap_values = get_shap_values(
    estimator=clf,
    X_test=X_test[:20],  # Explain first 20 samples
    attribute_names=list(feature_names),  # Optional: feature names
)
```

```python
# Bar plot - aggregate feature importances
plot_shap(shap_values, kind="bar")
```

```python
# Beeswarm plot - per-sample feature contributions
plot_shap(shap_values, kind="beeswarm")
```

```python
# Multiple plot types
plot_shap(shap_values, kind=("bar", "beeswarm"))
```

--------------------------------

### Scikit-learn Pipeline with TabICLClassifier and StandardScaler

Source: https://context7.com/soda-inria/tabicl/llms.txt

Integrate TabICLClassifier into a scikit-learn pipeline with StandardScaler for preprocessing numerical data. This is a basic setup for classification tasks.

```python
from sklearn.pipeline import make_pipeline
from sklearn.model_selection import cross_val_score, GridSearchCV
from sklearn.preprocessing import StandardScaler
from sklearn.datasets import fetch_openml
from tabicl import TabICLClassifier, TabICLRegressor

# Basic pipeline with TabICL
pipeline = make_pipeline(
    StandardScaler(),
    TabICLClassifier(n_estimators=4)
)
```

--------------------------------

### GET has_cache

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Checks if a valid cache is currently stored in the model.

```APIDOC
## GET has_cache

### Description
Checks if a valid cache is stored.

### Method
GET

### Response
#### Success Response (200)
- **has_cache** (bool) - Returns True if a valid cache is stored, otherwise False.
```

--------------------------------

### Initialize TabICLForecaster

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Initialize the TabICLForecaster with optional parameters for context length, temporal features, and point estimation method.

```python
from tabicl import TabICLForecaster

forecaster = TabICLForecaster(
    max_context_length=4096,  # max historical timesteps to use as context
    temporal_features=None,  # timestep index, calendar patterns, and seasonality
    point_estimate="mean",  # point prediction method: "mean" or "median"
    tabicl_config=None,  # passed to TabICLRegressor; None uses default settings
)
```

--------------------------------

### Initialize TabICLClassifier with all parameters

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Instantiate TabICLClassifier with all available parameters, showing default values and their descriptions. Adjust parameters like n_estimators, norm_methods, and device for custom behavior.

```python
from tabicl import TabICLClassifier

clf = TabICLClassifier(
    n_estimators=8,  # number of ensemble members, more = better but slower
    norm_methods=None,  # normalization methods to try
    feat_shuffle_method="latin",  # feature permutation strategy
    class_shuffle_method="shift",  # class permutation strategy
    outlier_threshold=4.0,  # z-score threshold for outlier detection and clipping
    softmax_temperature=0.9,  # temperature to control prediction confidence
    average_logits=True,  # average logits (True) or probabilities (False)
    support_many_classes=True,  # handle >10 classes automatically
    batch_size=8,  # ensemble members processed together, lower to save memory
    kv_cache=False,  # cache training data KV projections for faster repeated inference
    model_path=None,  # path to checkpoint, None downloads from Hugging Face
    allow_auto_download=True,  # auto-download checkpoint if not found locally
    checkpoint_version="tabicl-classifier-v2-20260212.ckpt",  # pretrained checkpoint version
    device=None,  # inference device, None auto-selects CUDA or CPU; specify "mps" for Apple Silicon
    use_amp="auto",  # automatic mixed precision for faster inference
    use_fa3="auto",  # Flash Attention 3 for Hopper GPUs (e.g. H100)
    offload_mode="auto",  # automatically decide when to use cpu/disk offloading
    disk_offload_dir=None,  # directory for disk offloading
    random_state=42,  # random seed for reproducibility
    n_jobs=None,  # number of PyTorch threads for CPU inference
    verbose=False,  # print detailed information during inference
    inference_config=None,  # fine-grained inference control for advanced users
)
```

--------------------------------

### Unsupervised Learning with TabICL

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Demonstrates initializing and fitting the TabICLUnsupervised model for unsupervised learning tasks. Requires NumPy and the TabICL library. The model can be configured with parameters like n_estimators and device.

```python
import numpy as np
from tabicl import TabICLUnsupervised
X = np.random.standard_normal((50, 3))
model = TabICLUnsupervised(n_estimators=4, device="cpu")
model.fit(X)
```

--------------------------------

### Inference Configuration

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Details on how to configure inference, including default settings and overriding options.

```APIDOC
## Inference Configuration

### When Dict with allowed top-level keys “COL_CONFIG”, “ROW_CONFIG”, “ICL_CONFIG”:

* A new `InferenceConfig` object is created with default settings.
* Any values explicitly specified in the dictionary will override default defaults.
* `device`, `use_amp`, `use_fa3`, `offload_mode`, `disk_offload_dir`, and `verbose` from the class initialization are used if they are not specified in the dictionary.

### When `InferenceConfig`:

* The provided `InferenceConfig` object is used directly without modification.
* `device`, `use_amp`, `use_fa3`, `offload_mode`, `disk_offload_dir`, and `verbose` from the class initialization are ignored.
* All settings must be explicitly defined in the provided `InferenceConfig` object.
```

--------------------------------

### TabICLRegressor Basic Regression

Source: https://context7.com/soda-inria/tabicl/llms.txt

Demonstrates the basic usage of TabICLRegressor for regression tasks. It shows how to generate sample regression data, train the regressor, and obtain predictions, which by default represent the mean of the predicted distribution.

```python
import numpy as np
from sklearn.datasets import make_regression
from sklearn.model_selection import train_test_split, cross_val_score
from tabicl import TabICLRegressor

# Generate regression data
X, y = make_regression(
    n_samples=500, n_features=10, n_informative=5, noise=0.5, random_state=42
)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

# Basic regression
reg = TabICLRegressor(n_estimators=8)
reg.fit(X_train, y_train)
predictions = reg.predict(X_test)  # Returns mean by default
```

--------------------------------

### InferenceConfig and TabICLCache

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Configuration and caching utilities for TabICL models.

```APIDOC
## update_from_dict(config_dict)

### Description
Update configurations from a dictionary.

### Parameters
- **config_dict** (Dict[str, Dict]) - Required - Dictionary containing configuration updates.

---

## cache_size_mb()

### Description
Return the memory occupied by cached tensors in MB.

### Response
- **size** (float) - Memory usage in MB.
```

--------------------------------

### TabICLClassifier Configuration

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Demonstrates the advanced configuration parameters available for the TabICLClassifier, including their default values and descriptions.

```APIDOC
## TabICLClassifier Configuration

TabICL offers a set of parameters to customize its behavior. The following example shows all available parameters with their default values and brief descriptions:

```python
from tabicl import TabICLClassifier

clf = TabICLClassifier(
    n_estimators=8,  # number of ensemble members, more = better but slower
    norm_methods=None,  # normalization methods to try
    feat_shuffle_method="latin",  # feature permutation strategy
    class_shuffle_method="shift",  # class permutation strategy
    outlier_threshold=4.0,  # z-score threshold for outlier detection and clipping
    softmax_temperature=0.9,  # temperature to control prediction confidence
    average_logits=True,  # average logits (True) or probabilities (False)
    support_many_classes=True,  # handle >10 classes automatically
    batch_size=8,  # ensemble members processed together, lower to save memory
    kv_cache=False,  # cache training data KV projections for faster repeated inference
    model_path=None,  # path to checkpoint, None downloads from Hugging Face
    allow_auto_download=True,  # auto-download checkpoint if not found locally
    checkpoint_version="tabicl-classifier-v2-20260212.ckpt",  # pretrained checkpoint version
    device=None,  # inference device, None auto-selects CUDA or CPU; specify "mps" for Apple Silicon
    use_amp="auto",  # automatic mixed precision for faster inference
    use_fa3="auto",  # Flash Attention 3 for Hopper GPUs (e.g. H100)
    offload_mode="auto",  # automatically decide when to use cpu/disk offloading
    disk_offload_dir=None,  # directory for disk offloading
    random_state=42,  # random seed for reproducibility
    n_jobs=None,  # number of PyTorch threads for CPU inference
    verbose=False,  # print detailed information during inference
    inference_config=None,  # fine-grained inference control for advanced users
)
```

`TabICLRegressor` accepts the same parameters except for the classification-specific ones: `class_shuffle_method`, `softmax_temperature`, `average_logits`, and `support_many_classes`.
```

--------------------------------

### TabICLClassifier Basic Usage and Cross-Validation

Source: https://context7.com/soda-inria/tabicl/llms.txt

Demonstrates basic classification using TabICLClassifier, including fitting the model, making predictions, and calculating probabilities. It also shows how to perform cross-validation to evaluate model accuracy. The model downloads its checkpoint on first use.

```python
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split, cross_val_score
from tabicl import TabICLClassifier

# Load dataset
X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

# Basic classification
clf = TabICLClassifier(n_estimators=8)
clf.fit(X_train, y_train)  # Downloads checkpoint on first use
predictions = clf.predict(X_test)  # In-context learning happens here
probabilities = clf.predict_proba(X_test)

print(f"Predictions shape: {predictions.shape}")
print(f"Probabilities shape: {probabilities.shape}")

# Cross-validation
scores = cross_val_score(clf, X, y, cv=5, scoring="accuracy")
print(f"Accuracy: {scores.mean():.3f} (+/- {scores.std():.3f})")
```

--------------------------------

### Basic usage of TabICLClassifier and TabICRegressor

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Instantiate and use TabICLClassifier for classification and TabICLRegressor for regression. The model downloads checkpoints on first use. In-context learning occurs during the predict step.

```python
from tabicl import TabICLClassifier, TabICLRegressor

clf = TabICLClassifier()
clf.fit(X_train, y_train)  # downloads checkpoint on first use, otherwise cheap
clf.predict(X_test)  # in-context learning happens here

reg = TabICLRegressor()
reg.fit(X_train, y_train)
reg.predict(X_test)
```

--------------------------------

### Configure Metadata Routing for score

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Configures metadata routing for the 'sample_weight' parameter in the 'score' method. Metadata can be requested, ignored, or cause an error if provided, with options for aliasing.

```python
model.set_score_request(sample_weight=True)
```

--------------------------------

### TabICLClassifier with KV Caching and GPU Acceleration

Source: https://context7.com/soda-inria/tabicl/llms.txt

Illustrates using TabICLClassifier with KV caching enabled for faster repeated inference, along with specifying GPU usage. It shows how fitting the model builds and caches KV projections, leading to significantly faster predictions on subsequent calls.

```python
# With KV caching for faster repeated inference
clf_cached = TabICLClassifier(
    n_estimators=8,
    kv_cache=True,  # Cache key-value projections during fit
    device="cuda",  # Use GPU; omit for auto-detection
)
clf_cached.fit(X_train, y_train)  # Builds and caches KV projections
pred1 = clf_cached.predict(X_test)  # Fast: reuses cached context
pred2 = clf_cached.predict(X_test[:10])  # Also fast
```

--------------------------------

### TabICLRegressor Class

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Initialization parameters for the TabICLRegressor.

```APIDOC
## TabICLRegressor Class

### Description
Tabular In-Context Learning (TabICL) Regressor with scikit-learn interface. This regressor applies TabICL to tabular data regression, using an ensemble of transformed dataset views to improve predictions. The ensemble members are created by applying different normalization methods and feature permutations.

### Parameters
#### Initialization Parameters
- **n_estimators** (int) - Number of estimators for ensemble predictions. Default: 8.
- **norm_methods** (str or list[str] or None) - Normalization methods to apply: 'none', 'power', 'quantile', 'quantile_rtdl', 'robust'. Can be a single string or a list. Default: None (uses ["none", "power"]).
- **feat_shuffle_method** (str) - Feature permutation strategy: 'none', 'shift', 'random', 'latin'. Default: 'latin'.
- **outlier_threshold** (float) - Z-score threshold for outlier detection and clipping. Default: 4.0.
- **batch_size** (Optional[int]) - Batch size for inference. If None, all ensemble members are processed in a single batch. Default: 8.
- **kv_cache** (bool or str) - Controls caching of training data computations. False: No caching. True or "kv": Cache key-value projections. "repr": Cache column embedding KV projections and row interaction outputs. Default: False.
- **model_path** (Optional[str or Path]) - Path to the pre-trained model checkpoint file. If None, downloads from Hugging Face Hub. Default: None.
- **allow_auto_download** (bool) - Whether to allow automatic download if the pretrained checkpoint cannot be found. Default: True.
- **checkpoint_version** (str) - Version of the pre-trained model checkpoint to use when model_path is None or invalid. Default: 'tabicl-regressor-v2-20260212.ckpt'.
- **device** (Optional[str or torch.device]) - Device to use for inference ('cuda', 'cpu', 'mps'). Default: None (auto-select).
- **use_amp** (bool or "auto") - Controls automatic mixed precision (AMP) for inference. Default: "auto".
- **use_fa3** (bool or "auto") - Controls Flash Attention 3 for inference. Default: "auto".
- **offload_mode** (str or "auto") - Controls offloading strategy for large models. Default: "auto".
- **disk_offload_dir** (Optional[str]) - Directory for disk offloading. Default: None.
- **random_state** (Optional[int]) - Seed for random number generator. Default: 42.
- **n_jobs** (Optional[int]) - Number of parallel jobs for computation. Default: None.
- **verbose** (bool) - Whether to print verbose output. Default: False.
- **inference_config** (Optional[dict]) - Configuration for inference. Default: None.

### Example Usage
```python
from tabicl import TabICLRegressor

# Initialize the regressor with default parameters
regressor = TabICLRegressor()

# Or with custom parameters
regressor_custom = TabICLRegressor(
    n_estimators=16,
    norm_methods=['power', 'quantile'],
    feat_shuffle_method='random',
    outlier_threshold=3.0,
    batch_size=16,
    kv_cache=True,
    model_path="./my_model.ckpt",
    device="cuda"
)
```
```

--------------------------------

### Enable KV caching for faster repeated inference

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Enable KV caching during initialization to speed up repeated inference on the same training data. The cache is built during fit and reused across predict calls. Note that this consumes additional memory.

```python
clf = TabICLClassifier(kv_cache=True)
clf.fit(X_train, y_train)  # caches key-value projections for training data
clf.predict(X_test)  # fast: only processes test data by reusing the cached context
```

--------------------------------

### Generate Synthetic Data with TabICLUnsupervised

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Generates synthetic data samples from the learned density using the TabICLUnsupervised model. Specify the desired number of samples to generate.

```python
X_synth = model.generate(n_samples=10)
```

--------------------------------

### Univariate Time Series Forecasting with TabICL

Source: https://github.com/soda-inria/tabicl/blob/main/README.md

Perform univariate time series forecasting using TabICLForecaster. This involves loading data, splitting into train/test sets, preparing context and test dataframes, making predictions, and plotting the forecast.

```python
import pandas as pd
from tabicl import TabICLForecaster
from tabicl.forecast import TimeSeriesDataFrame, plot_forecast

df = pd.read_csv(
    "https://autogluon.s3.amazonaws.com/datasets/timeseries/australian_electricity_subset/test.csv",
    parse_dates=["timestamp"],
)
data = TimeSeriesDataFrame.from_data_frame(df)

prediction_length = 96
selected_items = data.item_ids[:2]
train_data, test_data = data.train_test_split(prediction_length)

context_df = train_data.reset_index()
context_df = context_df[context_df["item_id"].isin(selected_items)]
test_df = test_data.reset_index()
test_df = test_df[test_df["item_id"].isin(selected_items)]
test_df = test_df.groupby("item_id").tail(prediction_length)

forecaster = TabICLForecaster(max_context_length=10240)
pred_df = forecaster.predict_df(context_df, prediction_length=prediction_length)
fig, axes = plot_forecast(context_df=context_df, pred_df=pred_df, test_df=test_df)
```

--------------------------------

### TabICL fit Method

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Documentation for the `fit` method, used to prepare the classifier for predictions.

```APIDOC
## POST /fit

### Description

Fit the classifier to training data. Prepares the model for prediction by encoding class labels, converting input features, fitting the ensemble generator, loading the TabICL model, and optionally pre-computing KV caches.

### Method

POST

### Endpoint

`/fit`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

* **X** (array-like) - Required - Training input data. Shape (n_samples, n_features).
* **y** (array-like) - Required - Training target labels. Shape (n_samples,)

### Request Example

```json
{
  "X": [[1, 2], [3, 4]],
  "y": [0, 1]
}
```

### Response

#### Success Response (200)

* **self** ([TabICLClassifier](#tabicl.TabICLClassifier)) - Fitted classifier instance.

#### Response Example

```json
{
  "message": "Classifier fitted successfully."
}
```

### Raises

* **ValueError** – If the number of classes exceeds the model’s maximum supported classes and many-class support is disabled.
```

--------------------------------

### Scikit-learn Pipeline with TabICLRegressor and TableVectorizer

Source: https://context7.com/soda-inria/tabicl/llms.txt

Demonstrates a scikit-learn pipeline for regression tasks, combining skrub's TableVectorizer for preprocessing with TabICLRegressor for model training.

```python
# Regression pipeline
reg_pipeline = make_pipeline(
    TableVectorizer(),
    TabICLRegressor(n_estimators=4)
)
```

--------------------------------

### Configure Inference and Offloading in TabICL

Source: https://context7.com/soda-inria/tabicl/llms.txt

Use InferenceConfig to manage memory offloading and mixed precision for column, row, and ICL components. Offload modes include auto, gpu, cpu, and disk for large datasets.

```python
from tabicl import TabICLClassifier, TabICLRegressor
from tabicl.model.inference_config import InferenceConfig

# Using inference_config dict for specific components
clf = TabICLClassifier(
    n_estimators=8,
    inference_config={
        "COL_CONFIG": {
            "offload_mode": "cpu",  # Offload column embeddings to CPU
            "use_amp": True,
        },
        "ROW_CONFIG": {
            "use_amp": True,
        },
        "ICL_CONFIG": {
            "offload_mode": "gpu",  # Keep ICL on GPU
            "use_amp": True,
        },
    }
)

# Offload modes for memory management
# - 'auto': Automatically choose based on available memory
# - 'gpu' or False: Keep on GPU (fastest, limited by VRAM)
# - 'cpu' or True: Offload to CPU memory
# - 'disk': Memory-mapped files (for very large datasets)

clf_large_data = TabICLClassifier(
    n_estimators=8,
    offload_mode="auto",
    disk_offload_dir="/tmp/tabicl_cache",  # For disk offloading
    use_amp="auto",  # Auto AMP based on data size
    use_fa3="auto",  # Flash Attention 3 for H100 GPUs
)

# Full InferenceConfig object for complete control
config = InferenceConfig()
config.update_from_dict({
    "COL_CONFIG": {"offload_mode": "cpu"},
    "ICL_CONFIG": {"use_amp": True},
})

clf = TabICLClassifier(inference_config=config)
```

--------------------------------

### TabICLClassifier Initialization

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

This snippet details the parameters available when initializing the TabICLClassifier.

```APIDOC
## TabICLClassifier

### Description
Tabular In-Context Learning (TabICL) Classifier with scikit-learn interface. This classifier applies TabICL to tabular data classification, using an ensemble of transformed dataset views to improve predictions. The ensemble members are created by applying different normalization methods, feature permutations, and class label shifts.

### Parameters

#### Initialization Parameters
- **n_estimators** (int, default=8) – Number of estimators for ensemble predictions.
- **norm_methods** (str or list[str] or None, default=None) – Normalization methods to apply: 'none', 'power', 'quantile', 'quantile_rtdl', 'robust'. Can be a single string or a list of methods. Defaults to ["none", "power"].
- **feat_shuffle_method** (str, default='latin') – Feature permutation strategy: 'none', 'shift', 'random', 'latin'.
- **class_shuffle_method** (str, default='shift') – Class label permutation strategy: 'none', 'shift', 'random', 'latin'.
- **outlier_threshold** (float, default=4.0) – Z-score threshold for outlier detection and clipping.
- **softmax_temperature** (float, default=0.9) – Temperature parameter \(\tau\) for the softmax function, applied as \(\text{softmax}(x / \tau)\).
- **average_logits** (bool, default=True) – Whether to average the logits (True) or probabilities (False) of ensemble members.
- **support_many_classes** (bool, default=True) – Whether to enable many-class support for mixed-radix ensembling and hierarchical classification.
- **batch_size** (Optional[int], default=8) – Batch size for inference. If None, all ensemble members are processed in a single batch.
- **kv_cache** (bool or str, default=False) – Controls caching of training data computations to speed up subsequent `predict_proba`/`predict` calls. Options: False, True or "kv", "repr".
- **model_path** (Optional[str | Path], default=None) – Path to the pre-trained model checkpoint file. If None, downloads from Hugging Face Hub.
```

--------------------------------

### Use TabICL Classifiers and Regressors

Source: https://github.com/soda-inria/tabicl/blob/main/docs/index.md

Standard scikit-learn fit/predict workflow for classification and regression tasks.

```python
from tabicl import TabICLClassifier, TabICLRegressor

# Classification
clf = TabICLClassifier()
clf.fit(X_train, y_train)   # checkpoint downloaded once on first run
clf.predict(X_test)         # in-context learning happens here

# Regression
reg = TabICLRegressor()
reg.fit(X_train, y_train)
reg.predict(X_test)
```

--------------------------------

### Configure Metadata Routing for predict

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Sets metadata routing for the 'alphas' parameter in the 'predict' method. Use 'True' to request metadata, 'False' to ignore, 'None' to raise an error if provided, or a string alias.

```python
model.set_params(alphas=True)
```

--------------------------------

### TabICLUnsupervised Class

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Initializes the TabICLUnsupervised model for unsupervised learning tasks including imputation, outlier detection, and synthetic data generation.

```APIDOC
## class tabicl.TabICLUnsupervised

### Description
Unsupervised learning with TabICL. Estimates joint density by decomposing it via the chain rule of probability using an ensemble of conditional predictors.

### Parameters
- **n_estimators** (int) - Optional - Number of ensemble estimators per conditional prediction. Default is 8.
- **categorical_features** (list[int] or None) - Optional - Indices of categorical features. Default is None.
- **max_categories** (int) - Optional - Maximum unique values for auto-detection of categorical features. Default is 10.
- **batch_size** (int or None) - Optional - Batch size for inner estimator inference. Default is 8.
- **random_state** (int or None) - Optional - Random seed for reproducibility. Default is 42.
- **device** (str or None) - Optional - Device for inference. Default is None.
- **estimator_params** (dict or None) - Optional - Additional keyword arguments forwarded to the inner estimators.
```

--------------------------------

### Perform Time Series Forecasting

Source: https://context7.com/soda-inria/tabicl/llms.txt

Use TabICLForecaster for zero-shot forecasting on single or multiple time series with optional future covariates.

```python
import numpy as np
import pandas as pd
from tabicl import TabICLForecaster
from tabicl.forecast import plot_forecast

# Create synthetic time series with trend and seasonality
rng = np.random.default_rng(0)
n_days = 365 * 2
dates = pd.date_range(start="2022-01-01", periods=n_days, freq="D")
t = np.arange(n_days)

trend = 0.05 * t
weekly = 5.0 * np.sin(2 * np.pi * t / 7)
annual = 10.0 * np.sin(2 * np.pi * t / 365)
noise = rng.normal(scale=1.5, size=n_days)
target = trend + weekly + annual + noise

# Single time series - requires 'timestamp' and 'target' columns
df = pd.DataFrame({"timestamp": dates, "target": target})

# Split into context (history) and test (held-out future)
prediction_length = 30
context_df = df.iloc[:-prediction_length]
test_df = df.iloc[-prediction_length:]

# Forecast
forecaster = TabICLForecaster(
    max_context_length=4096,  # Max historical timesteps to use
    point_estimate="mean",    # Or "median"
)
pred_df = forecaster.predict_df(context_df, prediction_length=prediction_length)
print(pred_df.head())
# Contains: target (point prediction), 0.1, 0.2, ..., 0.9 (quantiles)

# Visualize forecast
fig, axes = plot_forecast(
    context_df=context_df,
    pred_df=pred_df,
    test_df=test_df  # Optional: compare with held-out truth
)

# Multiple time series with item_id
multi_df = pd.DataFrame({
    "timestamp": np.tile(dates[:100], 3),
    "item_id": np.repeat(["A", "B", "C"], 100),
    "target": np.random.randn(300),
})
forecaster = TabICLForecaster()
pred_multi = forecaster.predict_df(multi_df, prediction_length=10)

# Custom quantiles
pred_custom = forecaster.predict_df(
    context_df,
    prediction_length=30,
    quantiles=[0.05, 0.25, 0.5, 0.75, 0.95]
)

# With known future covariates
context_with_covariates = context_df.copy()
context_with_covariates["is_weekend"] = context_with_covariates["timestamp"].dt.dayofweek >= 5

future_timestamps = pd.date_range(
    start=context_df["timestamp"].iloc[-1] + pd.Timedelta(days=1),
    periods=prediction_length,
    freq="D"
)
future_df = pd.DataFrame({
    "timestamp": future_timestamps,
    "is_weekend": future_timestamps.dayofweek >= 5
})

pred_with_cov = forecaster.predict_df(
    context_with_covariates,
    future_df=future_df  # Use instead of prediction_length
)
```

--------------------------------

### TabICLClassifier Model Saving and Loading

Source: https://context7.com/soda-inria/tabicl/llms.txt

Demonstrates how to save and load a trained TabICLClassifier model. This includes options to control whether model weights, training data, and KV cache are saved, allowing for flexible model persistence and retrieval.

```python
# Save and load model
clf_cached.save(
    "classifier.pkl",
    save_model_weights=False,  # Reload from checkpoint on load
    save_training_data=True,   # Include training data
    save_kv_cache=True,        # Save cached KV projections
)
loaded_clf = TabICLClassifier.load("classifier.pkl")
```

--------------------------------

### TabICL Inference Parameters

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Configuration options for controlling TabICL's inference process.

```APIDOC
## TabICL Inference Parameters

This section details the parameters used to configure the inference process for the TabICL model.

### `use_fa3`

*   **Type:** `bool` or `"auto"`
*   **Default:** `"auto"`
*   **Description:** Determines whether to use Flash Attention 3 (FA3). FA3 can accelerate inference for large datasets on NVIDIA Hopper GPUs (e.g., H100). This option is only effective if FA3 is installed.
    *   `True` / `False`: Forces FA3 to be on or off, respectively.
    *   `"auto"`: Automatically enables FA3 based on input data size using a heuristic. The heuristic considers medium (n < 10240) and large (n >= 10240) inputs, with FA3 being off for medium and on for large inputs. This heuristic assumes the training set is large relative to the test set and does not account for KV-cache scenarios. If this heuristic is suboptimal for your workload, set `use_fa3` explicitly.

### `offload_mode`

*   **Type:** `str` or `bool`
*   **Default:** `'auto'`
*   **Description:** Controls the storage location for column-wise embedding outputs during inference. Column-wise embedding generates a large tensor that can be a memory bottleneck. Available options:
    *   `'auto'`: Automatically selects the best offload mode based on available memory (default).
    *   `'gpu'` or `False`: Keeps embeddings on the GPU. This is the fastest option but is limited by GPU VRAM.
    *   `'cpu'` or `True`: Offloads embeddings to CPU memory.
    *   `'disk'`: Offloads embeddings to memory-mapped files. Requires `disk_offload_dir` to be set.
    *   Note: This parameter primarily affects column-wise embeddings (COL_CONFIG). For more granular control over all components, use `inference_config`.

### `disk_offload_dir`

*   **Type:** `Optional[str]`
*   **Default:** `None`
*   **Description:** Specifies the directory for memory-mapped files when `offload_mode` is set to `'disk'` or when `'auto'` defaults to disk offloading. This parameter is relevant only for column-wise embeddings (COL_CONFIG). For finer control, use `inference_config`.

### `random_state`

*   **Type:** `int` or `None`
*   **Default:** `42`
*   **Description:** A random seed to ensure reproducibility of ensemble generation, influencing operations like feature shuffling.

### `n_jobs`

*   **Type:** `int` or `None`
*   **Default:** `None`
*   **Description:** The number of threads to use for PyTorch when the model runs on the CPU. `None` uses the PyTorch default (physical CPU cores). Negative values use $\max(1, n_{\text{logical\_cores}} + 1 + \text{n\_jobs})$ threads; e.g., `n_jobs=-1` uses all logical cores.

### `verbose`

*   **Type:** `bool`
*   **Default:** `False`
*   **Description:** If `True`, prints detailed information during inference.

### `inference_config`

*   **Type:** `Optional[Union[InferenceConfig, Dict[str, Dict[str, Any]]]]`
*   **Default:** `None`
*   **Description:** Provides fine-grained control over the inference settings for the three transformers in TabICL (column-wise, row-wise, and in-context learning). This parameter is intended for advanced users familiar with TabICL's internal architecture.
    *   **When `None` (default):** A new `InferenceConfig` object is created with default settings. Parameters like `device`, `use_amp`, `use_fa3`, `offload_mode`, `disk_offload_dir`, and `verbose` from the class initialization are applied.
    *   **When a `Dict` with keys like “COL_CONFIG”, “ROW_CONFIG”, “ICL_CONFIG”:** A new `InferenceConfig` object is created with default settings. Explicitly specified values in the dictionary override defaults. Class initialization parameters (`device`, `use_amp`, etc.) are used if not specified in the dictionary.
    *   **When an `InferenceConfig` object:** The provided object is used directly. Class initialization parameters are ignored, and all settings must be defined within the `InferenceConfig` object.

### Attributes (Read-only)

These attributes represent the state of the fitted TabICL model.

#### `n_features_in_`

*   **Type:** `int`
*   **Description:** Number of features in the training data.

#### `n_samples_in_`

*   **Type:** `int`
*   **Description:** Number of samples in the training data.

#### `feature_names_in_`

*   **Type:** `ndarray` of shape `(n_features_in_,)` or `None`
*   **Description:** Feature names seen during `fit`, if the input `X` had feature names (e.g., a pandas DataFrame).

#### `X_encoder_`

*   **Type:** `TransformToNumerical`
*   **Description:** Encoder used for transforming input features to numerical values.

#### `y_scaler_`

*   **Type:** `StandardScaler`
*   **Description:** Scaler used for transforming target values.

#### `ensemble_generator_`

*   **Type:** `EnsembleGenerator`
*   **Description:** Fitted ensemble generator responsible for creating multiple dataset views.

#### `model_`

*   **Type:** `[TabICL](#tabicl.model.TabICL)`
*   **Description:** The loaded TabICL model used for predictions.

#### `model_path_`

*   **Type:** `str`
*   **Description:** Path to the loaded model checkpoint file.
```

--------------------------------

### TabICL Inference Parameters

Source: https://github.com/soda-inria/tabicl/blob/main/docs/api.md

Configuration options for TabICL inference.

```APIDOC
## TabICL Inference Parameters

This section details the parameters used to configure the TabICL model for inference.

### Parameters

#### General Inference Settings

- **allow_auto_download** (bool, default=True) – Whether to allow automatic download if the pretrained checkpoint cannot be found at the specified model_path.
- **checkpoint_version** (str, default='tabicl-classifier-v2-20260212.ckpt') – Specifies which version of the pre-trained model checkpoint to use when model_path is None or points to a non-existent file (and allow_auto_download is true). Checkpoints are downloaded from [https://huggingface.co/jingang/TabICL](https://huggingface.co/jingang/TabICL).
  Available versions:
  - ‘tabicl-classifier-v2-20260212.ckpt’ (Default): The latest best-performing version, used in our TabICLv2 paper.
  - ‘tabicl-classifier-v1.1-20250506.ckpt’: An enhanced version of TabICLv1 using a precursor of the v2 prior.
  - ‘tabicl-classifier-v1-20250208.ckpt’: The version used in our TabICLv1 paper.
- **device** (Optional[str or torch.device], default=None) – Device to use for inference. If None, automatically selects CUDA if available, otherwise CPU. Can be specified as a string (`'cuda'`, `'cpu'`, `'mps'`) or a `torch.device` object. MPS (Apple Silicon GPU) is supported but must be explicitly requested.
- **use_amp** (bool or "auto", default="auto") – Controls automatic mixed precision (AMP) for inference.
  - True / False: force on / off.
  - “auto”: Automatically enable AMP based on input data size using the following heuristic:
    > | Regime                          | AMP   | FA3   |
    > |---------------------------------|-------|-------|
    > | Small  (n < 1024 & feat < 60)   | off   | off   |
    > | Medium (above small, n < 10240) | on    | off   |
    > | Large  (n >= 10240)             | on    | on    |
    > The above heuristic is based on the observation that AMP can introduce overhead that outweighs its benefits for small inputs. In addition, it assumes that the training set is large relative to the test set and does not account for KV-cache scenarios. If it is suboptimal for your workload, set it explicitly.
- **use_fa3** (bool or "auto", default="auto") – Whether to use Flash Attention 3 that can speed up inference for large datasets on NVIDIA Hopper GPUs like H100. Only effective when FA3 is installed.
  - True / False: force on / off.
  - “auto”: Automatically enable FA3 based on input data size using a simple heuristic (see above).
- **offload_mode** (str or bool, default='auto') – Controls where column-wise embedding outputs are stored during inference. Column-wise embedding produces a large tensor of shape (batch_size, n_rows, n_columns, embed_dim) which is the main memory bottleneck.
  Available options:
  - `'auto'`: Automatically choose based on available memory (default).
  - `'gpu'` or `False`: Keep on GPU. Fastest but limited by VRAM.
  - `'cpu'` or `True`: Offload to CPU memory.
  - `'disk'`: Offload to memory-mapped files (requires `disk_offload_dir`).
  It only affects column-wise embedding (COL_CONFIG). For finer-grained control over all components, use `inference_config`.
- **disk_offload_dir** (Optional[str], default=None) – Directory for memory-mapped files used when `offload_mode='disk'` or when `offload_mode='auto'` falls back to disk offloading. It only affects column-wise embedding (COL_CONFIG). For finer-grained control over all components, use `inference_config`.
- **random_state** (int or None, default=42) – Random seed for reproducibility of ensemble generation, affecting feature shuffling and other randomized operations.
- **n_jobs** (int or None, default=None) – Number of threads to use for PyTorch in case the model is run on CPU. None means using the PyTorch default, which is the number of physical CPU cores. Negative numbers mean that $\max(1, n_{\text{logical\_cores}} + 1 + \text{n\_jobs})$ threads will be used. In particular, `n_jobs=-1` means that all logical cores will be used.
- **verbose** (bool, default=False) – Whether to print detailed information during inference.

#### Advanced Inference Configuration

- **inference_config** (Optional[InferenceConfig | Dict[str, Dict[str, Any]]], default=None) – Configuration for inference settings. This parameter provides fine-grained control over the three transformers in TabICL (column-wise, row-wise, and in-context learning).

  WARNING: This parameter should only be used by advanced users who understand the internal architecture of TabICL and need precise control over inference.

  When None (default):
  : - A new InferenceConfig object is created with default settings
    - The `device`, `use_amp`, `use_fa3`, `offload_mode`, `disk_offload_dir`, and `verbose` parameters from the class initialization are applied to the relevant components
```