tusk-ml 0.1.0__tar.gz

tusk_ml-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.3
+Name: tusk-ml
+Version: 0.1.0
+Summary: Deep feature synthesis for narwhals dataframes
+Requires-Dist: narwhals>=2.24
+Requires-Dist: scikit-learn>=1.4 ; extra == 'sklearn'
+Requires-Python: >=3.10
+Provides-Extra: sklearn
+Description-Content-Type: text/markdown
+
+# tusk
+
+In nature, narwhals use their tusk to find mates.
+
+In data science, you can use tusk to connect [narwhals](https://narwhals-dev.github.io/narwhals/) dataframes.
+
+This package implements deep feature synthesis to automate feature engineering with the power of your favorite dataframe library.
+Powered by [narwhals](https://narwhals-dev.github.io/narwhals/), inspired by [featuretools](https://featuretools.alteryx.com/).
+
+## Install
+
+```bash
+uv add tusk-ml
+```
+
+## Usage
+
+```python
+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:
+
+```python
+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:
+
+```python
+matrix = features.apply(db_new)
+```
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/index.md):
+
+- [Databases](docs/guide/databases.md) — tables, keys, relationships, and
+  [validating](docs/guide/databases.md#validation) them against the data.
+- [Running DFS](docs/guide/deep-feature-synthesis.md) — depth, cutoff times, and the column naming scheme.
+- [Primitives](docs/guide/primitives.md) — what ships with tusk and how it behaves.
+- [Custom primitives](docs/guide/custom-primitives.md) — the extension point.
+- [scikit-learn pipelines](docs/guide/sklearn.md) — DFS as a pipeline step, and
+  computing only the features you keep.
+- [Differences from featuretools](docs/guide/featuretools.md) — if you are porting.
+- [API reference](docs/api/index.md) — every public symbol.
+
+Build the site locally with:
+
+```bash
+uv run --group docs zensical serve
+```

tusk_ml-0.1.0/README.md

@@ -0,0 +1,77 @@
+# tusk
+
+In nature, narwhals use their tusk to find mates.
+
+In data science, you can use tusk to connect [narwhals](https://narwhals-dev.github.io/narwhals/) dataframes.
+
+This package implements deep feature synthesis to automate feature engineering with the power of your favorite dataframe library.
+Powered by [narwhals](https://narwhals-dev.github.io/narwhals/), inspired by [featuretools](https://featuretools.alteryx.com/).
+
+## Install
+
+```bash
+uv add tusk-ml
+```
+
+## Usage
+
+```python
+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:
+
+```python
+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:
+
+```python
+matrix = features.apply(db_new)
+```
+
+## Documentation
+
+Full documentation lives in [`docs/`](docs/index.md):
+
+- [Databases](docs/guide/databases.md) — tables, keys, relationships, and
+  [validating](docs/guide/databases.md#validation) them against the data.
+- [Running DFS](docs/guide/deep-feature-synthesis.md) — depth, cutoff times, and the column naming scheme.
+- [Primitives](docs/guide/primitives.md) — what ships with tusk and how it behaves.
+- [Custom primitives](docs/guide/custom-primitives.md) — the extension point.
+- [scikit-learn pipelines](docs/guide/sklearn.md) — DFS as a pipeline step, and
+  computing only the features you keep.
+- [Differences from featuretools](docs/guide/featuretools.md) — if you are porting.
+- [API reference](docs/api/index.md) — every public symbol.
+
+Build the site locally with:
+
+```bash
+uv run --group docs zensical serve
+```

tusk_ml-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "tusk-ml"
+version = "0.1.0"
+description = "Deep feature synthesis for narwhals dataframes"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["narwhals>=2.24"]
+
+[project.optional-dependencies]
+sklearn = ["scikit-learn>=1.4"]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tusk"
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "benchmarks",
+]
+markers = [
+    "differential: cross-checks values against featuretools (opt-in)",
+    "benchmark: relbench performance runs (opt-in)",
+]
+addopts = "-m 'not differential and not benchmark'"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "D",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.interrogate]
+fail-under = 100
+ignore-init-module = true
+ignore-private = true
+ignore-magic = true
+ignore-nested-functions = true
+exclude = [
+    "tests",
+    ".venv",
+    ".claude",
+]
+
+[tool.pydoclint]
+style = "google"
+exclude = "tests|benchmarks"
+arg-type-hints-in-docstring = false
+check-return-types = false
+allow-init-docstring = true
+
+[[tool.ty.overrides]]
+include = [
+    "src/tusk/primitives/**",
+    "tests/**",
+]
+
+[tool.ty.overrides.rules]
+invalid-method-override = "ignore"
+
+[dependency-groups]
+dev = [
+    "duckdb>=1.0",
+    "interrogate>=1.7.0",
+    "pre-commit-uv>=4.3.0",
+    "pydoclint>=0.9.1",
+    "pytest>=8.0",
+    "polars>=1.43",
+    "pyarrow>=17",
+    "ruff>=0.16.3",
+    "scikit-learn>=1.4",
+    "ty>=0.0.72",
+]
+validation = [
+    "featuretools>=1.31",
+    "pandas>=2.0",
+    "setuptools<81",
+]
+benchmark = [
+    "relbench>=2.1",
+    "duckdb>=1.0",
+]
+docs = [
+    "mkdocstrings[python]>=1.0.6",
+    "zensical>=0.0.56",
+]

tusk_ml-0.1.0/pyproject.toml.orig

@@ -0,0 +1,93 @@
+[project]
+name = "tusk-ml"
+version = "0.1.0"
+description = "Deep feature synthesis for narwhals dataframes"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["narwhals>=2.24"]
+
+[project.optional-dependencies]
+sklearn = ["scikit-learn>=1.4"]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# The distribution is named tusk-ml because tusk is taken on PyPI; the
+# import name stays tusk.
+module-name = "tusk"
+
+
+[dependency-groups]
+dev = [
+    "duckdb>=1.0",
+    "interrogate>=1.7.0",
+    "pre-commit-uv>=4.3.0",
+    "pydoclint>=0.9.1",
+    "pytest>=8.0",
+    "polars>=1.43",
+    "pyarrow>=17",
+    "ruff>=0.16.3",
+    "scikit-learn>=1.4",
+    "ty>=0.0.72",
+]
+validation = [
+    "featuretools>=1.31",
+    "pandas>=2.0",
+    "setuptools<81",
+]
+benchmark = [
+    "relbench>=2.1",
+    "duckdb>=1.0",
+]
+docs = [
+    "mkdocstrings[python]>=1.0.6",
+    "zensical>=0.0.56",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "benchmarks"]
+markers = [
+    "differential: cross-checks values against featuretools (opt-in)",
+    "benchmark: relbench performance runs (opt-in)",
+]
+addopts = "-m 'not differential and not benchmark'"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.interrogate]
+fail-under = 100
+ignore-init-module = true
+ignore-private = true
+ignore-magic = true
+ignore-nested-functions = true
+exclude = ["tests", ".venv", ".claude"]
+
+[tool.pydoclint]
+style = "google"
+exclude = "tests|benchmarks"
+arg-type-hints-in-docstring = false
+check-return-types = false
+# ruff (D107) and interrogate both require __init__ to carry its own
+# docstring; without this flag pydoclint's DOC301 forbids exactly that
+# whenever the class also has a docstring.
+allow-init-docstring = true
+
+[[tool.ty.overrides]]
+include = ["src/tusk/primitives/**", "tests/**"]
+
+[tool.ty.overrides.rules]
+# Primitive.build is variadic in the ABC and fixed-arity in each concrete
+# primitive. Arity is guaranteed by construction: synthesis supplies exactly
+# len(input_dtypes) expressions to outputs(), which is build()'s only caller.
+# Scoped rather than project-wide so override checking stays active everywhere
+# else.
+invalid-method-override = "ignore"

tusk_ml-0.1.0/src/tusk/__init__.py

@@ -0,0 +1,21 @@
+"""Deep feature synthesis for narwhals dataframes."""
+
+from __future__ import annotations
+
+from tusk import exceptions
+from tusk.api import apply_features, deep_feature_synthesis
+from tusk.database import Database, Relationship, TableSchema
+from tusk.feature_list import FeatureList
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Database",
+    "FeatureList",
+    "Relationship",
+    "TableSchema",
+    "apply_features",
+    "deep_feature_synthesis",
+    "exceptions",
+]

tusk_ml-0.1.0/src/tusk/api.py

@@ -0,0 +1,125 @@
+"""The public entry points.
+
+:func:`deep_feature_synthesis` builds feature definitions and computes them;
+:func:`apply_features` computes existing ones.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from datetime import datetime
+from typing import Any
+
+from tusk.database import Database
+from tusk.feature_list import FeatureList
+from tusk.features import Feature
+from tusk.primitives.base import Primitive
+from tusk.synthesis import synthesize
+
+
+def deep_feature_synthesis(
+    database: Database,
+    target_table: str,
+    agg_primitives: Iterable[str | Primitive] | None = None,
+    trans_primitives: Iterable[str | Primitive] | None = None,
+    groupby_trans_primitives: Iterable[str | Primitive] | None = None,
+    max_depth: int = 2,
+    cutoff_time: datetime | None = None,
+    features_only: bool = False,
+) -> Any:
+    """Run deep feature synthesis over a database.
+
+    Synthesis raises :class:`~tusk.exceptions.SchemaError` if the target table
+    is unknown or the walk generates no features at all, and
+    :class:`~tusk.exceptions.PrimitiveError` for an unknown primitive name or
+    an order-dependent primitive on a table with no ``row_creation_time``.
+    Compilation raises :class:`~tusk.exceptions.SchemaError` if the target
+    table has no ``primary_key``, and whatever :func:`apply_features`
+    documents for ``cutoff_time``.
+
+    Args:
+        database: The tables and relationships to synthesize over.
+        target_table: Table to build features for. The result has one
+            row per *visible* row of this table, keyed by its ``primary_key``.
+            With no ``cutoff_time`` that is every row; with one, the target is
+            filtered like any other table, so the matrix may have fewer rows.
+        agg_primitives: Aggregation primitives, as names or instances. None
+            selects the documented defaults.
+        trans_primitives: Transform primitives. None selects the defaults.
+        groupby_trans_primitives: Transforms applied within foreign-key groups.
+            None means none.
+        max_depth: Maximum number of stacked primitive applications.
+        cutoff_time: Only rows whose ``row_creation_time`` is at or before this
+            value are visible, on the target table as well as its relatives.
+            Its tz awareness must match the database's row creation times'.
+            A table with no ``row_creation_time`` is timeless and passes
+            through unfiltered, so a cutoff on a database that declares none is
+            silently a no-op. None disables filtering. Ignored entirely when
+            ``features_only`` is true, since nothing is computed: the cutoff
+            belongs to compilation, and feature definitions do not record it.
+        features_only: Return the feature definitions without computing them.
+
+    Returns:
+        feature_matrix: An uncomputed query plan in the caller's native frame
+            type. On a backend with a lazy frame type you get one back, so call
+            ``.collect()`` to compute it. Not returned when ``features_only``
+            is true.
+        features (FeatureList): The feature definitions, reusable with
+            :meth:`~tusk.FeatureList.apply` or :func:`apply_features`.
+
+    Warns:
+        CategoricalDtypeWarning: If a Categorical or Enum column is skipped
+            because a requested primitive requires a string input.
+        UnmatchedPrimitiveWarning: If a requested primitive matched no column
+            of its input dtypes anywhere in the walk.
+    """
+    features = synthesize(
+        database=database,
+        target_table=target_table,
+        agg_primitives=agg_primitives,
+        trans_primitives=trans_primitives,
+        groupby_trans_primitives=groupby_trans_primitives,
+        max_depth=max_depth,
+    )
+    if features_only:
+        return features
+    return features.apply(database, cutoff_time), features
+
+
+def apply_features(
+    features: Sequence[Feature],
+    database: Database,
+    cutoff_time: datetime | None = None,
+) -> Any:
+    """Apply existing feature definitions to a database.
+
+    Use this to apply a feature set fitted on training data to new data. It
+    accepts any sequence of features; a :class:`~tusk.FeatureList` can compute
+    itself with :meth:`~tusk.FeatureList.apply` instead.
+
+    Raises :class:`~tusk.exceptions.SchemaError` if ``features`` is empty,
+    spans more than one table, or targets a table with no ``primary_key``, and
+    :class:`~tusk.exceptions.PrimitiveError` if an order-dependent primitive
+    lands on a table with no ``row_creation_time``.
+    :class:`~tusk.exceptions.ValidationError` is raised if ``cutoff_time``
+    differs from the database's row creation times in tz awareness, or if
+    those disagree among themselves, and ``TypeError`` if ``cutoff_time`` is
+    not a ``datetime``.
+
+    Args:
+        features: Feature definitions, all on the same target table.
+        database: The database to compute over.
+        cutoff_time: Only rows whose ``row_creation_time`` is at or before this
+            value are visible, on the target table as well as its relatives, so
+            the matrix may have fewer rows than the target. Its tz awareness
+            must match the database's row creation times'. A table with no
+            ``row_creation_time`` is timeless and passes through unfiltered,
+            so a cutoff on a database that declares none is silently a no-op.
+            None disables filtering.
+
+    Returns:
+        feature_matrix: An uncomputed query plan in the caller's native frame
+            type, with one row per visible target row. tusk never collects, so
+            on a backend with a lazy frame type you decide when to compute.
+    """
+    return FeatureList(features).apply(database, cutoff_time)