tusk

In nature, narwhals use their tusk to find mates.

In data science, you can use tusk to connect narwhals dataframes.

This package implements deep feature synthesis to automate feature engineering with the power of your favorite dataframe library. Powered by narwhals, inspired by featuretools.

Install

uv add tusk-ml

Usage

from datetime import datetime

import tusk
from tusk.primitives import Quantiles

db = tusk.Database("retail")
db.add_table("customers", customers_lf, primary_key="id", row_creation_time="signed_up_at")
db.add_table("sessions", sessions_lf, primary_key="id", row_creation_time="started_at")
db.add_table("transactions", tx_lf, primary_key="id", row_creation_time="occurred_at")

db.add_relationship(parent="customers", child="sessions", foreign_key="customer_id")
db.add_relationship(parent="sessions", child="transactions", foreign_key="session_id")

db.validate()  # optional: confirm the keys really are keys, before you trust the numbers

feature_matrix, features = tusk.deep_feature_synthesis(
    database=db,
    target_table="customers",
    agg_primitives=["mean", "count", Quantiles(qs=(0.25, 0.5, 0.75))],
    trans_primitives=["month", "weekday"],
    max_depth=2,
    cutoff_time=datetime(2026, 1, 1),
)

feature_matrix comes back as an uncomputed query plan — tusk never collects — so on a backend with a lazy frame type you get one back and decide when to compute:

matrix = feature_matrix.collect()

features is a FeatureList — a sequence of inspectable definitions that knows its target table and can re-apply itself to new data:

matrix = features.apply(db_new)

Documentation

Full documentation lives in docs/:

Databases — tables, keys, relationships, and validating them against the data.
Running DFS — depth, cutoff times, and the column naming scheme.
Primitives — what ships with tusk and how it behaves.
Custom primitives — the extension point.
scikit-learn pipelines — DFS as a pipeline step, and computing only the features you keep.
Differences from featuretools — if you are porting.
API reference — every public symbol.

Build the site locally with:

uv run --group docs zensical serve

Metadata

Release files for tusk-ml 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tusk-ml 0.1.4
File	Size	Uploaded
tusk_ml-0.1.4.tar.gz	40.3 kB	Sep 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tusk-ml 0.1.4
File	Interpreter	ABI	Platform	Reset
tusk_ml-0.1.4-py3-none-any.whl 49.5 kB Sep 2, 2026	Python 3	none	any	Details

Total release size: 89.8 kB

Release files / tusk_ml-0.1.4.tar.gz

Download URL	tusk_ml-0.1.4.tar.gz
Size	40.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`6293edf61c915fd5134afa20d868c175f1c4f6a45e50bec7830e3d371c8a70d8`
BLAKE2b-256 checksum How to use checksums	`66f48b3ad03230711d4d45b188b5ecb6bad20e356cb5150e42c1ffb6b6bfa523`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / tusk_ml-0.1.4-py3-none-any.whl

Download URL	tusk_ml-0.1.4-py3-none-any.whl
Size	49.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`07e1e380c849713563b104e9c3b1ca5f8ea4a047e01c1f6899d6f380a4046c57`
BLAKE2b-256 checksum How to use checksums	`d2aeff0f99ca8374011f190d49ef1547f8bcf61fe872ba4b1a3ce2c375f683d8`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`