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 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", row_creation_time="listed_at")
db.add_table("orders", orders_lf, primary_key="id", row_creation_time="placed_at")
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))],
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 region
Datetime[us] signed_up_at "row creation time"
}
"products" {
Int64 id PK
String category
Float64 price
Datetime[us] listed_at "row creation time"
}
"orders" {
Int64 id PK
Int64 customer_id FK "-> customers"
Int64 product_id FK "-> products"
Int64 quantity
Datetime[us] placed_at "row creation time"
}
"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
1 maintainer
Metadata
1 maintainer
Release files for tusk-ml 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tusk_ml-0.1.8.tar.gz | 45.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tusk_ml-0.1.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 100.7 kB
Release files / tusk_ml-0.1.8.tar.gz
| Download URL | tusk_ml-0.1.8.tar.gz |
|---|---|
| Size | 45.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d912287e107903423bb64637999df24a95612084bc2ce9de98b29cb689001dc
|
|
BLAKE2b-256 checksum How to use checksums |
4b8fe5159914b32e79685b5820f8abc2f57e6906729b27d74ed790d8109aebca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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.8-py3-none-any.whl
| Download URL | tusk_ml-0.1.8-py3-none-any.whl |
|---|---|
| Size | 55.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bf1fc3314387b0a69a54fd7e1794a1ad2b37369efaeb1e8297e37ccdec1a8cd9
|
|
BLAKE2b-256 checksum How to use checksums |
4587707ee65f178ddd2468fe770f3b18975894527409b05628c22d296bb9f267
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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}
|
