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 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)

Looking at the schema

plot() draws the database you just built. It runs no query against the data.

db.plot()

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" : ""

In a notebook it renders inline; 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

Metadata

Release files for tusk-ml 0.1.18

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.18
File	Size	Uploaded
tusk_ml-0.1.18.tar.gz	59.2 kB	Sep 21, 2026	Details

Built distribution (wheel)

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

Total release size: 127.9 kB

Release files / tusk_ml-0.1.18.tar.gz

Download URL	tusk_ml-0.1.18.tar.gz
Size	59.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`e08db9b044b0c06be8807098bc7a5475ea785404fd32077d0502e7294d859dac`
BLAKE2b-256 checksum How to use checksums	`972601cfba3db2e65fab1d017db7ada85bac767f12f8174babf98c048639c667`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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.18-py3-none-any.whl

Download URL	tusk_ml-0.1.18-py3-none-any.whl
Size	68.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`04cc3b9d8426d6eb2ca728dbd59bfd220a324fa205faf8900fede82bd0932482`
BLAKE2b-256 checksum How to use checksums	`c41f248313a777c78d68a189a5cfcbc0c497c427d388adb8b79675499df5ea21`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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}`