AutoCarver

AutoCarver Logo

AutoCarver in one loop: discretize, rank groupings, carve

AutoCarver turns raw numeric, categorical, and ordinal columns into optimal, drift-robust, human-readable bins in a few lines of code. Stop losing model performance to suboptimal manual binning — and stop discovering overfit bins in production monitoring.

Provably optimal — exhaustive search: for a fixed min_freq, max_n_mod and metric (Tschuprow's T by default, or Cramér's V), no other admissible bin combination scores higher.
Robust by construction — every candidate grouping is vetoed unless it holds on a held-out dev set (and optional CV folds), at fit time rather than in monitoring.
Define → carve → model — declare your Features, fit a carver, transform: the whole feature set is carved in one supervised pass, not one notebook per feature. One carver per target type — BinaryCarver, MulticlassCarver, OrdinalCarver, ContinuousCarver (regression) — all with the identical API.
AI-assisted — a local MCP server lets your LLM assistant qualify and carve columns through tool calls, fully on your machine.

Built for credit scoring, fraud detection, and risk modeling.

🆕 What's New

📊 Cross-validated robustness. fit now accepts a cv argument for extra held-out robustness views on top of (or instead of) a dev set: carver.fit(X, y, cv=5). Accepts an int, any scikit-learn splitter, or explicit index pairs, resolved via sklearn.model_selection.check_cv — folds veto over-fit combinations but never reorder them (ranks stay anchored to the full train set). See Cross-validation folds.

🤖 LLM & MCP integration. AutoCarver now ships a local Model Context Protocol server: point an MCP-aware assistant (VS Code Copilot, Claude Desktop, Cursor, …) at a data file and let it qualify the columns and carve them against your target through tool calls. The server runs fully on your machine — your dataset is never sent to AutoCarver or any external service (only your own LLM provider sees what the assistant shares). Carving quality depends on the LLM, so have a human confirm the feature definitions before production use. See the LLM & MCP guide.

pip install "autocarver[mcp]"

Install

pip install autocarver

Quick Start

You already have a DataFrame and a target — that's step 1 of 6 done. The remaining five lines-worth take you to carved, dev-validated bins. Binary classification on the Titanic dataset:

from pathlib import Path

import pandas as pd
from sklearn.model_selection import train_test_split

from AutoCarver import BinaryCarver, Features

# 1. Load data
url = "https://web.stanford.edu/class/archive/cs/cs109/cs109.1166/stuff/titanic.csv"
data = pd.read_csv(url)
target = "Survived"

# 2. Train / dev split, stratified on the target
train, dev = train_test_split(data, test_size=0.33, random_state=42, stratify=data[target])

# 3. Declare features by type
features = Features(
    categoricals=["Sex"],
    numericals=["Age", "Fare", "Siblings/Spouses Aboard", "Parents/Children Aboard"],
    ordinals={"Pclass": ["1", "2", "3"]},
)

# 4. Fit the carver (dev set drives the robustness checks)
carver = BinaryCarver(features=features)
train_processed = carver.fit_transform(train, train[target], X_dev=dev, y_dev=dev[target])
dev_processed = carver.transform(dev)

# 5. Inspect the carved buckets, target rate, and association
print(carver.summary)

# 6. Persist for later use
carver.save(Path("titanic_carver.json"))
# carver = BinaryCarver.load(Path("titanic_carver.json"))

min_freq and max_n_mod are the only two knobs that matter to start with — the defaults (0.02 / 5) reflect common scoring practice, and every behavioral toggle lives in one ProcessingConfig object. Scan, adjust, move on.

For multiclass classification use MulticlassCarver (one binning per feature, against the full K-class target) — or OneVsRestCarver for a separate binning per class; for ordinal targets use OrdinalCarver; for regression use ContinuousCarver — the API is identical. To pre-select features by target association and inter-feature redundancy, pipe the carved output through ClassificationSelector or RegressionSelector.

What you get

No performance left on the table — exhaustive search over admissible bin combinations maximizes Tschuprow's T (default) or Cramér's V: for fixed min_freq, max_n_mod and metric, no other combination scores higher, so you never wonder whether a better grouping existed.
Stop silent overfitting before production — bins that only exist in your training sample degrade quietly under drift. Every candidate combination is validated on a dev set (and optional CV folds): any whose target rates flip or whose buckets fall below min_freq is rejected at fit time, not discovered in monitoring.
First-class ordinal features — OrdinalDiscretizer enforces your declared modality order, so under-represented levels are merged with their nearest neighbour instead of being collapsed by frequency.
You are the final auditor — features.summary and features.history expose the bin definitions, per-bin target rate / frequency, and the full carving trace; disagree with a boundary and you can override it, and transform applies your fix like any carved bin:
```
feature = features("Siblings/Spouses Aboard")  # any fitted feature; labels are [0, 1, 2]
feature.group([1], 2)  # merge two bins you consider equivalent
```
Interpretable buckets — human-readable boundaries you can audit, document, and ship to a scorecard.
Dimensionality reduction — groups under-represented modalities and caps bins per feature (max_n_mod), which is especially useful before one-hot encoding.
Feature pre-selection — ClassificationSelector / RegressionSelector rank features by target association and filter on inter-feature correlation.

How does it compare?

	Manual binning	AutoCarver	optbinning	sklearn KBinsDiscretizer
Supervised (uses `y`)	only as far as your patience goes	yes	yes	no
Algorithm	eyeballing distributions, notebook by notebook	exhaustive search over admissible combinations	mixed-integer program (CBC)	quantile / uniform / k-means
Optimality for given `min_freq` / `max_n_mod` / metric	none — first acceptable grouping wins	guaranteed — best of every admissible combination	provably optimal under MIP constraints	n/a — no target objective
Target types	any, at ~1 feature/hour	binary, multiclass, ordinal, continuous	binary, multiclass, continuous	n/a
Numeric and categorical and ordinal in one `fit`	each feature is its own project	yes	one binner per feature	numeric only
Ordinal features with enforced order	if you remember to	yes — `OrdinalDiscretizer` preserves your declared order	via `user_splits` workaround (loses ordering)	no
`NaN` handled as its own modality	usually forgotten	yes	yes	no (raises)
Held-out dev-set robustness check	rarely — too tedious to script per feature	yes — dev set + optional k-fold CV, built into `fit`	no (script CV yourself)	no
Per-bin stats + carving history after `fit`	scattered notebook cells	`features.summary`, `features.history`	`binning_table`	no
JSON round-trip persistence	copy-pasted bound lists	yes (`carver.save("...json")`)	via `pickle`	via `pickle`
sklearn `Pipeline` compatible	no	yes	yes	yes
Feature pre-selection helpers	no	`ClassificationSelector`, `RegressionSelector`	no	no

Side-by-side runnable snippets and a "when to pick which" guide live on the comparison page.

Documentation

Full reference, tutorials, and end-to-end notebook examples on ReadTheDocs.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

autocarver-7.5.3.tar.gz (156.6 kB view details)

Uploaded Jul 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

autocarver-7.5.3-py3-none-any.whl (208.0 kB view details)

Uploaded Jul 12, 2026 Python 3

File details

Details for the file autocarver-7.5.3.tar.gz.

File metadata

Download URL: autocarver-7.5.3.tar.gz
Upload date: Jul 12, 2026
Size: 156.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for autocarver-7.5.3.tar.gz
Algorithm	Hash digest
SHA256	`ce8bbf66aa22590fc3e8b2a50e32cac5c209bbf4d1c2c81f4a3b988ba422c7f2`
MD5	`0390367fdfc0322401326804e2eacaa5`
BLAKE2b-256	`12f880eaf7097028644575763358a42a0fd0b306853c46e2ca3bd72d68499797`

See more details on using hashes here.

Provenance

The following attestation bundles were made for autocarver-7.5.3.tar.gz:

Publisher: release.yml on mdefrance/AutoCarver

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: autocarver-7.5.3.tar.gz
- Subject digest: ce8bbf66aa22590fc3e8b2a50e32cac5c209bbf4d1c2c81f4a3b988ba422c7f2
- Sigstore transparency entry: 2153978429
- Sigstore integration time: Jul 12, 2026
Source repository:
- Permalink: mdefrance/AutoCarver@2c732382e8c72d7fc4dc7b23d0981516842922cf
- Branch / Tag: refs/heads/main
- Owner: https://github.com/mdefrance
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@2c732382e8c72d7fc4dc7b23d0981516842922cf
- Trigger Event: pull_request