priorlabs

---
name: priorlabs
description: Use when building tabular machine learning models, making
  predictions on structured data, or integrating predictive capabilities into
  applications. Reach for TabPFN when you need fast, accurate predictions on
  classification or regression tasks without extensive hyperparameter tuning or
  data preprocessing.
metadata:
  mintlify-proj: priorlabs
  version: "1.0"
---

# TabPFN Skill

## Product Summary

TabPFN is a pre-trained transformer foundation model for tabular data that delivers high-quality predictions in seconds without dataset-specific training. It learns from billions of synthetic datasets and applies in-context learning to your data via a single forward pass. Use it for classification, regression, forecasting, anomaly detection, and data generation on structured data.

**Key entry points:**
- **Python API (local):** `from tabpfn import TabPFNClassifier, TabPFNRegressor` — runs on your GPU
- **Python API (hosted):** `from tabpfn_client import TabPFNClassifier, TabPFNRegressor` — no GPU required, managed compute
- **REST API:** `/tabpfn/*` JSON endpoints for non-Python integrations
- **Agentic:** Model Context Protocol (MCP) server at `https://api.priorlabs.ai/mcp/server` for Claude, ChatGPT, n8n, Databricks

**Primary docs:** https://docs.priorlabs.ai

---

## When to Use

Reach for TabPFN when:

- **Building classification or regression models** on tabular data without extensive hyperparameter tuning
- **Making fast predictions** on structured data (numerical, categorical, text, datetime columns)
- **Handling messy data** — TabPFN natively manages missing values, outliers, mixed scales, and mixed column types
- **Optimizing for quality over speed** — use Thinking mode on the API for grouped or time-ordered data
- **Integrating predictions into agentic workflows** — use the MCP server to connect Claude, ChatGPT, or n8n
- **Adapting to a specialized domain** — fine-tune the pretrained model on your data distribution
- **Avoiding preprocessing overhead** — TabPFN handles text expansion, datetime encoding, and categorical handling automatically

Do not use TabPFN for:
- Image or audio data (use domain-specific models)
- Unstructured text-only tasks (use LLMs)
- Datasets where you need full control over preprocessing (TabPFN's automatic handling may conflict with your pipeline)

---

## Quick Reference

### Installation & Authentication

| Task | Command |
|------|---------|
| Install local package | `pip install --upgrade tabpfn` |
| Install API client | `pip install --upgrade tabpfn-client` |
| Set API token (client) | `export TABPFN_TOKEN="<your-key>"` or `tabpfn_client.set_access_token(key)` |
| Get API key | Visit https://platform.priorlabs.ai/account/api-keys |

### Core Workflow (Python)

```python
# Classification
from tabpfn_client import TabPFNClassifier
clf = TabPFNClassifier()
clf.fit(X_train, y_train)
preds = clf.predict(X_test)
probs = clf.predict_proba(X_test)

# Regression
from tabpfn_client import TabPFNRegressor
reg = TabPFNRegressor()
reg.fit(X_train, y_train)
preds = reg.predict(X_test)
```

### Model Selection

| Model | Where | When |
|-------|-------|------|
| TabPFN-3.5-Plus | `tabpfn-client` (API) | Default choice; balanced speed and accuracy |
| TabPFN-3.5-Thinking | `tabpfn-client` (API) | Grouped/time-ordered data; higher accuracy with longer fit time |
| TabPFN-3.5 | `tabpfn` (local) | Run on your GPU; no API calls |
| TabPFN-3.5-Fast | `tabpfn-client` or `tabpfn` | Latency-sensitive; trades some accuracy for speed |

### Key Parameters

| Parameter | Type | Default | Use When |
|-----------|------|---------|----------|
| `thinking_mode` | bool | False | Enable fit-time optimization (API only) |
| `thinking_effort` | "medium" or "high" | None | "high" for maximum accuracy; "medium" for balance |
| `thinking_metric` | str | None | Set to "accuracy", "log_loss", "roc_auc", "rmse", or "mae" |
| `group_col` | str or list | None | Identify groups of related rows (e.g., patient_id) |
| `time_col` | str | None | Temporal feature for time-ordered data |
| `categorical_features_indices` | list[int] | None | Declare integer-coded categorical columns |
| `n_estimators` | int | 8 | Ensemble size; higher = more accurate but slower |
| `eval_metric` | str | None | Metric to optimize (e.g., "roc_auc", "f1") |

### REST API Endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST /tabpfn/prepare_train_set_upload` | Request signed URLs for training data |
| `POST /tabpfn/fit` | Fit model on uploaded training set |
| `POST /tabpfn/prepare_test_set_upload` | Request signed URLs for test data |
| `POST /tabpfn/predict` | Run predictions on test set |
| `GET /tabpfn/get_model_limits` | Check per-model row, column, and cell limits |

---

## Decision Guidance

### When to Use API (tabpfn-client) vs Local (tabpfn)

| Criterion | Use API (tabpfn-client) | Use Local (tabpfn) |
|-----------|------------------------|-------------------|
| GPU available | No | Yes |
| Need Thinking mode | Yes | No |
| Latency critical | No | Yes |
| Data privacy (on-prem) | No | Yes |
| Simplicity preferred | Yes | No |
| Cost (large volume) | No | Yes |

### When to Use Thinking Mode

| Scenario | Recommendation |
|----------|-----------------|
| Grouped data (patient visits, customer transactions) | Use Thinking mode with `group_col` |
| Time-ordered data (sensor readings, stock prices) | Use Thinking mode with `time_col` |
| High-stakes predictions (finance, healthcare) | Use `thinking_effort="high"` |
| Speed-critical (real-time scoring) | Skip Thinking; use standard fit |
| Repeated predictions on same schema | Use Thinking once, reuse fitted model |

### When to Fine-Tune

| Condition | Decision |
|-----------|----------|
| Baseline TabPFN already meets target | Skip fine-tuning |
| Specialized domain (molecular, sensor data) | Fine-tune |
| < 1000 training rows | Avoid fine-tuning (overfitting risk) |
| Amortized prediction cost (many predictions) | Fine-tune |
| Quick wins available (feature engineering, preprocessing) | Try those first |

### Column Type Declaration

| Column Type | How to Declare | Why |
|------------|----------------|-----|
| Integer-coded categorical | `categorical_features_indices=[0, 2]` | Prevents treating as numerical |
| Text | `pd.Series(..., dtype="string")` | Enables text processing |
| Datetime | `pd.to_datetime(col)` | Expands into calendar features |
| Numerical | Default | No action needed |
| Missing values | Leave as NaN | TabPFN handles natively |

---

## Workflow

### Typical Classification Task

1. **Prepare data:** Load X_train, y_train, X_test as pandas DataFrames or numpy arrays. Declare categorical columns via dtype or `categorical_features_indices`.

2. **Choose deployment:** Decide between API (tabpfn-client) or local (tabpfn). For grouped/time data, use API with Thinking mode.

3. **Create estimator:** Instantiate `TabPFNClassifier()` with optional parameters (thinking_mode, group_col, eval_metric).

4. **Fit:** Call `clf.fit(X_train, y_train)`. The model uploads data (if API), fits in seconds, and caches the result.

5. **Predict:** Call `clf.predict(X_test)` for labels or `clf.predict_proba(X_test)` for probabilities.

6. **Evaluate:** Compare predictions against held-out y_test. If performance is below target, try feature engineering or Thinking mode before fine-tuning.

7. **Deploy:** Save the fitted model with `clf.save_model("model.json")` (API) or pickle (local). Reuse for repeated predictions.

### Typical Regression Task

1. **Prepare data:** Load X_train, y_train, X_test. Declare categorical columns.

2. **Create estimator:** Instantiate `TabPFNRegressor()` with optional parameters.

3. **Fit:** Call `reg.fit(X_train, y_train)`.

4. **Predict:** Call `reg.predict(X_test)` for point estimates, or `reg.predict(X_test, output_type="quantiles", quantiles=[0.1, 0.5, 0.9])` for uncertainty.

5. **Evaluate:** Check RMSE, MAE, or calibration on held-out data.

### REST API Workflow

1. **Authenticate:** Get API key from platform.priorlabs.ai.

2. **Check limits:** Call `GET /tabpfn/get_model_limits` to validate data size.

3. **Upload training:** Call `POST /tabpfn/prepare_train_set_upload`, then PUT files to signed URLs.

4. **Fit:** Call `POST /tabpfn/fit` with `train_set_upload_id` and task config. Returns `fitted_train_set_id`.

5. **Upload test:** Call `POST /tabpfn/prepare_test_set_upload` with `fitted_train_set_id`, then PUT test files.

6. **Predict:** Call `POST /tabpfn/predict` with `fitted_train_set_id` and `test_set_upload_id`. Returns predictions.

---

## Common Gotchas

- **Avoid preprocessing:** Do not scale, impute, one-hot encode, or vectorize text before passing to TabPFN. It handles these natively and preprocessing often hurts accuracy.

- **Declare categorical columns:** Integer-coded categoricals (e.g., 0, 1, 2 for regions) are treated as numerical by default. Declare them via `categorical_features_indices` or pandas `category` dtype.

- **Text must be string dtype:** Pass text columns as `pd.Series(..., dtype="string")`. String columns without explicit dtype may be misclassified.

- **Datetime must be datetime dtype:** Use `pd.to_datetime(col)` before fitting. String dates like "2020-01-01" are treated as text or categories.

- **Thinking mode requires pandas DataFrames:** `group_col`, `time_col`, and `group_time_col` only work with pandas DataFrames, not numpy arrays. Column names must be strings.

- **Thinking mode cannot combine group_col and time_col:** Use one or the other, not both. Use `group_time_col` for temporal features within groups.

- **API token budget:** Predictions and Thinking fits consume tokens from shared daily/monthly budgets. Standard fits and uploads do not. Monitor usage at platform.priorlabs.ai/account/usage.

- **OOM on large datasets:** If CUDA runs out of memory, reduce `n_estimators`, use row subsampling via `inference_config.SUBSAMPLE_SAMPLES`, or switch to the API client (no GPU required).

- **Fine-tuning requires GPU:** Fine-tuning is impractical on CPU. Use a GPU or the API.

- **Model version mismatch:** Updating the `tabpfn` package does not upgrade fine-tuned weights. Re-fine-tune on the new checkpoint if upgrading.

- **Asynchronous fits:** Large training sets (> 50 MB) automatically use async API. Fits may take minutes; the client polls for completion.

---

## Verification Checklist

Before submitting work with TabPFN:

- [ ] **Data types correct:** Categorical columns declared, text as string dtype, datetime as datetime dtype
- [ ] **No manual preprocessing:** Confirm no scaling, imputation, one-hot encoding, or text vectorization applied
- [ ] **Baseline established:** Run default TabPFN and record baseline metrics
- [ ] **Limits checked:** Verify data size against `GET /tabpfn/get_model_limits` (rows, columns, cells)
- [ ] **API token valid:** Confirm `TABPFN_TOKEN` is set and account has available budget
- [ ] **Thinking mode justified:** If using Thinking, confirm data is grouped/time-ordered or accuracy gain justifies longer fit time
- [ ] **Model version selected:** Confirm correct model (v3.5-Plus, v3.5-Thinking, local v3.5, or v3.5-Fast)
- [ ] **Predictions validated:** Check predictions on held-out test set; compare against baseline
- [ ] **Error handling:** Confirm code handles 401 (auth), 404 (not found), 409 (duplicate), 422 (validation), 429 (rate limit) responses
- [ ] **Model saved:** For API, call `save_model()` to persist fitted model; for local, pickle or export weights

---

## Resources

**Comprehensive navigation:** https://docs.priorlabs.ai/llms.txt

**Critical documentation:**
- [Quickstart](https://docs.priorlabs.ai/quickstart) — Get running in minutes with Python or REST API
- [Improving Performance](https://docs.priorlabs.ai/improving-performance) — Feature engineering, preprocessing, and tuning strategies
- [Thinking Mode](https://docs.priorlabs.ai/capabilities/thinking-mode) — Fit-time optimization for grouped and temporal data
- [Fine-Tuning](https://docs.priorlabs.ai/capabilities/fine-tuning) — Adapt TabPFN to specialized domains
- [REST API Quickstart](https://docs.priorlabs.ai/api/rest-quickstart) — HTTP integration guide
- [MCP Setup](https://docs.priorlabs.ai/agentic/setup-guide) — Connect Claude, ChatGPT, or n8n
- [API Metering](https://docs.priorlabs.ai/api/metering) — Token charges and budgets
- [Troubleshooting OOM](https://docs.priorlabs.ai/troubleshooting/OOM-errors) — Memory management on large datasets

---

> For additional documentation and navigation, see: https://docs.priorlabs.ai/llms.txt