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