tusk

In nature, narwhals use their tusk to find mates. In data science, you can use tusk to connect dataframes via narwhals.

This package helps to automate feature engineering with Deep Feature Synthesis for (almost) any dataframe library. Powered by narwhals, inspired by featuretools.

Install

uv add tusk-ml

Usage

from datetime import datetime

import narwhals as nw

import tusk
from tusk.primitives import Quantiles

db = tusk.Database("shop")
db.add_table(
    "customers",
    customers_lf,
    primary_key="id",
    row_creation_time="signed_up_at",
)
db.add_table("products", products_lf, primary_key="id")
db.add_table(
    "orders",
    orders_lf,
    primary_key="id",
    row_creation_time="placed_at",
    row_update_times={"payed_at": {"payed_at": None, "payment_method": None}},
    where={"large": nw.col("amount") >= 100.0},
    when={
        "open": lambda cutoff: (
            nw.col("closed_at").is_null() | (nw.col("closed_at") > cutoff)
        )
    },
)

db.add_relationship(parent="customers", child="orders", foreign_key="customer_id")
db.add_relationship(parent="products", child="orders", foreign_key="product_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))],
    conditional_primitives=("count", "sum"),
    trans_primitives=["month", "weekday"],
    max_depth=2,
    cutoff_time=datetime(2026, 1, 1),
)

feature_matrix comes back as a data frame of the backend you put in, changed to a lazy frame if that supports has one.

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)

Looking at the schema

plot() draws the database you just built, from the schema alone.

db.plot()

---
title: "shop"
---
erDiagram
  "customers" {
    Int64 id PK
    String city
    Datetime[us] signed_up_at "row creation time"
  }
  "products" {
    Int64 id PK
    Categorical category
    Float64 price
  }
  "orders" {
    Int64 id PK
    Int64 customer_id FK "-> customers"
    Int64 product_id FK "-> products"
    Int64 quantity
    Float64 amount
    Datetime[us] placed_at "row creation time"
    Datetime[us] payed_at "row update time"
    Categorical payment_method "@ payed_at"
    Datetime[us] closed_at
  }
  "customers" 1 to 0+ "orders" : ""
  "products" 1 to 0+ "orders" : ""

The database's name becomes the title. In a notebook the diagram renders inline, and so does the database itself; print(db.plot()) gives the Mermaid source, and db.plot().save("schema.svg") writes an image with tusk-ml[plot] installed.

Documentation

Full documentation lives here. Or build the site locally with:

just docs-test