polars-learn 0.1.0__tar.gz

polars_learn-0.1.0/.github/workflows/create-release.yml

@@ -0,0 +1,99 @@
+name: Create GitHub Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: create-release
+  cancel-in-progress: false
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install Python
+        run: uv python install 3.11
+      - name: Install locked dependencies
+        run: uv sync --locked --extra pandas --python 3.11
+      - name: Validate package
+        run: |
+          uv run --locked --extra pandas pytest --doctest-modules src tests
+          uv run --locked --extra pandas ruff check .
+          uv run --locked --extra pandas ruff format --check .
+          uv run --locked --extra pandas pyright
+      - name: Read package version
+        id: version
+        run: |
+          uv run --locked --extra pandas python - <<'PY'
+          import os
+          import re
+          import tomllib
+
+          with open("pyproject.toml", "rb") as source:
+              version = tomllib.load(source)["project"]["version"]
+          from polars_learn import __version__
+
+          if __version__ != version:
+              raise SystemExit("Package __version__ must match project.version")
+          if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", version):
+              raise SystemExit("Release version must have the form X.Y.Z")
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              output.write(f"tag=v{version}\n")
+          PY
+      - name: Reject an existing release tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          gh api "repos/$GH_REPO/git/matching-refs/tags/$RELEASE_TAG" > /tmp/release-refs.json
+          uv run --locked --extra pandas python - <<'PY'
+          import json
+          import tomllib
+
+          with open("pyproject.toml", "rb") as source:
+              tag = "v" + tomllib.load(source)["project"]["version"]
+          with open("/tmp/release-refs.json") as source:
+              refs = json.load(source)
+          if any(ref["ref"] == f"refs/tags/{tag}" for ref in refs):
+              raise SystemExit(f"{tag} already exists; bump project.version before releasing")
+          PY
+      - name: Build and validate wheel and source archive
+        run: |
+          uv build
+          uvx twine check --strict dist/*
+      - name: Save distributions for PyPI publishing
+        uses: actions/upload-artifact@v4
+        with:
+          name: created-release-dists
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+      - name: Create release with distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          gh release create "$RELEASE_TAG" dist/*.whl dist/*.tar.gz \
+            --target "$GITHUB_SHA" \
+            --title "$RELEASE_TAG" \
+            --generate-notes
+
+  publish:
+    needs: create-release
+    permissions:
+      contents: read
+      id-token: write
+    uses: ./.github/workflows/python-publish.yml
+    with:
+      artifact-name: created-release-dists
+    secrets: inherit

polars_learn-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,87 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_call:
+    inputs:
+      artifact-name:
+        description: Existing distribution artifact from the calling workflow
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Use distributions supplied by caller
+        if: inputs.artifact-name != ''
+        run: echo "Using the calling workflow's distribution artifact"
+      - uses: actions/checkout@v4
+        if: inputs.artifact-name == ''
+      - uses: astral-sh/setup-uv@v5
+        if: inputs.artifact-name == ''
+      - name: Install Python
+        if: inputs.artifact-name == ''
+        run: uv python install 3.11
+      - name: Install locked dependencies
+        if: inputs.artifact-name == ''
+        run: uv sync --locked --extra pandas --python 3.11
+      - name: Check release version and package
+        if: inputs.artifact-name == ''
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run --locked --extra pandas python - <<'PY'
+          import os
+          import tomllib
+
+          with open("pyproject.toml", "rb") as source:
+              version = tomllib.load(source)["project"]["version"]
+          from polars_learn import __version__
+
+          if __version__ != version:
+              raise SystemExit("Package __version__ must match project.version")
+          expected = f"v{version}"
+          if os.environ["RELEASE_TAG"] != expected:
+              raise SystemExit(f"Release tag must match project.version: {expected}")
+          PY
+          uv run --locked --extra pandas pytest --doctest-modules src tests
+          uv run --locked --extra pandas ruff check .
+          uv run --locked --extra pandas ruff format --check .
+          uv run --locked --extra pandas pyright
+      - name: Build release distributions
+        if: inputs.artifact-name == ''
+        run: |
+          uv build
+          uvx twine check --strict dist/*
+      - name: Upload distributions
+        if: inputs.artifact-name == ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+          if-no-files-found: error
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: release-build
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/polars-learn/
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ inputs.artifact-name || 'release-dists' }}
+          path: dist/
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          password: ${{ secrets.PYPI_API_TOKEN }}

polars_learn-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,34 @@
+name: Tests
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12']
+        pandas: [false, true]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install Python
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install locked core dependencies
+        if: '!matrix.pandas'
+        run: uv sync --locked --python ${{ matrix.python-version }}
+      - name: Install locked pandas dependencies
+        if: matrix.pandas
+        run: uv sync --locked --extra pandas --python ${{ matrix.python-version }}
+      - name: Test
+        run: uv run --locked pytest --doctest-modules src tests
+      - name: Lint
+        run: uv run --locked ruff check .
+      - name: Check formatting
+        run: uv run --locked ruff format --check .
+      - name: Check types
+        run: uv run --locked pyright

polars_learn-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Package builds
+/build/
+/dist/
+/wheels/
+*.egg-info/
+.eggs/
+
+# Virtual environments and local tool caches
+/.venv/
+/venv/
+/env/
+.uv-cache/
+
+# Test, lint, type-checking, and coverage output
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+junit.xml
+
+# Local credentials and environment configuration
+.env
+.env.*
+!.env.example
+/.aws/
+
+# Editor and operating-system files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db

polars_learn-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

polars_learn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

polars_learn-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: polars-learn
+Version: 0.1.0
+Summary: Native Polars feature engineering and schema validation for scikit-learn
+Author: Jack
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: polars>=1.20
+Requires-Dist: scikit-learn>=1.6
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == 'pandas'
+Requires-Dist: pyarrow>=14; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# polars-learn
+
+High-performance feature engineering for scikit-learn, powered by Polars.
+
+## Features
+
+- Composable native Polars expressions, evaluated in dependency order.
+- Learned schemas with strict, semi-strict, and permissive validation.
+- scikit-learn estimators with cloning, parameters, and feature names.
+- Native Polars output and optional, explicit pandas conversion.
+- Python 3.11+, Polars 1.20+, and scikit-learn 1.6+.
+
+## Installation
+
+```bash
+uv add polars-learn
+# From a local checkout:
+uv pip install .
+# Optional pandas and PyArrow support:
+uv pip install '.[pandas]'
+```
+
+## Quick Start
+
+```python
+import polars as pl
+from polars_learn import FeatureEngineer, FeatureSpec, SchemaValidator
+
+X = pl.DataFrame({"price": [10.0, 20.0, 30.0], "quantity": [2, 3, 4]})
+validator = SchemaValidator(mode="strict").fit(X)
+validated = validator.transform(X)
+
+engineer = FeatureEngineer(
+    [
+        FeatureSpec(pl.col("price") * pl.col("quantity"), alias="notional"),
+        FeatureSpec(
+            pl.col("notional").log1p(),
+            alias="log_notional",
+            drop=["quantity"],
+        ),
+    ]
+)
+result = engineer.fit_transform(validated)
+print(result)
+print(engineer.get_feature_names_out())
+# ['price' 'notional' 'log_notional']
+```
+
+## Feature Engineering
+
+`FeatureSpec` accepts exactly one of `expression` (one `pl.Expr`) or `expressions` (a nonempty sequence of expressions). It stores a single canonical expression tuple. Names follow Polars conventions: an existing alias or a native output name needs no additional alias. An explicit `alias` overrides the name of one output; it is rejected for multiple outputs. Selectors and expression expansion are supported, with their output names resolved against the frame.
+
+```python
+spec = FeatureSpec(
+    expressions=[
+        (pl.col("ask") - pl.col("bid")).alias("spread"),
+        ((pl.col("ask") + pl.col("bid")) / 2).alias("mid"),
+    ],
+    drop=["ask", "bid"],
+    name="quote_features",
+)
+quotes = pl.DataFrame({"ask": [11.0], "bid": [9.0]})
+print(FeatureEngineer([spec]).fit_transform(quotes))
+```
+
+Expressions within one specification are evaluated together and cannot reference new columns created by siblings. Separate specifications execute sequentially; later ones can use earlier outputs. Drops happen after each specification. Missing expression inputs, missing drop columns, and duplicate output names raise `FeatureEngineeringError` (duplicate names detectable at construction raise `ValueError`). Overwriting existing columns is allowed and keeps Polars' column position. For example, `FeatureSpec(pl.col("price") + 1)` replaces `price`.
+
+`fit` executes the training transformation to validate expressions and learn output names and dtypes. `transform` requires the fitted input column names and order and the exact fitted output schema. Input dtype differences are acceptable only when the resulting schema remains identical; use `SchemaValidator` first for explicit input type policies. Empty feature lists are identity transforms. The public API accepts eager DataFrames; internally, lazy stages preserve sequential semantics and collect once per execution. Expressions are stateless; training transformations do not learn statistics. Use deterministic expressions to keep training and inference consistent.
+
+## Schema Validation
+
+```python
+validator = SchemaValidator(
+    mode="semi-strict",
+    allow_extra_columns=False,
+    enforce_column_order=True,
+)
+validator.fit(X)  # Always learns the raw input schema
+print(validator.schema_)
+validated = validator.transform(X)  # Always validates against that schema
+```
+
+| Mode               | Policy for differing dtypes                             |
+| ------------------ | ------------------------------------------------------- |
+| `strict` (default) | Reject every dtype difference.                          |
+| `semi-strict`      | Allow only the explicit lossless widening policy below. |
+| `permissive`       | Use Polars `cast(strict=True)` and report failures.     |
+
+Semi-strict allows integer widening when the entire source dtype's range fits inside the target integer dtype (including compatible unsigned-to-signed widening), Float32 → Float64, and integer → Float64 only when **every non-null value round-trips exactly**. For example, Int64 `2**53` and `2**54` are accepted, but `2**53 + 1` is rejected. It rejects narrowing, strings to numbers, and Null dtype to a different dtype. Null values in already compatible columns are preserved; nullability constraints are not part of this version.
+
+Permissive casts may be lossy according to Polars semantics, such as floats to integers. Failed casts never silently replace invalid values with nulls. Missing required columns always fail; multiple schema mismatches are reported in `SchemaValidationError`. Strict mode does not cast or rename columns.
+
+Extra columns fail by default. Set `allow_extra_columns=True` to preserve them, or also set `extra_columns="drop"` to explicitly remove them. Column order checks compare the relative order of required columns; permitted extras may appear anywhere. With `enforce_column_order=False`, output is normalised to fitted column order, followed by preserved extras in their input order. `get_feature_names_out()` describes fitted required columns; inference-only extras are not included. Avoid preserving inference-only extras before a fixed-width downstream estimator or `FeatureEngineer`.
+
+The shorthand `strict=True` means strict mode, and `strict=False` means permissive mode. Conflicting `strict` and `mode` arguments are rejected. Schemas learned by the validator and feature engineer are independent.
+
+## scikit-learn Pipelines
+
+```python
+import numpy as np
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+pipeline = Pipeline(
+    [
+        ("schema", SchemaValidator(mode="semi-strict")),
+        ("features", engineer),
+        ("scale", StandardScaler().set_output(transform="polars")),
+        ("model", RandomForestRegressor(n_estimators=20, random_state=0)),
+    ]
+)
+pipeline.fit(X, np.array([1.0, 2.0, 3.0]))
+print(pipeline.predict(X))
+print(pipeline[:-1].get_feature_names_out())
+```
+
+These transformers implement `fit`, `transform`, `fit_transform`, `get_params`, `set_params`, and `get_feature_names_out`. Fitted attributes include `feature_names_in_`, `n_features_in_`, and `output_features_`. Cloning discards fitted state. Supplied `input_features` must exactly match fitted input names.
+
+Data stays in Polars between our transformers. Both support `set_output(transform="default")` and `set_output(transform="polars")`, which return native Polars frames. They reject `"pandas"` output and deliberately bypass scikit-learn's automatic output wrapping, including global output settings, to preserve native names and allowed extras. No automatic NumPy conversion occurs. Downstream estimator support for Polars depends on the estimator and installed scikit-learn version; arbitrary string columns do not work with random forests.
+
+Tests run applicable scikit-learn constructor, parameter, and cloning checks. Generic checks requiring NumPy array input do not apply to this deliberately DataFrame-only API. No LazyFrame, sparse-array, or NumPy input is accepted.
+
+## Optional Pandas Support
+
+```bash
+uv sync --extra pandas
+```
+
+```python
+# Requires the pandas extra; both transformers expose these options.
+import pandas as pd
+
+pandas_X = pd.DataFrame({"price": [10.0, 20.0], "quantity": [2, 3]})
+validator = SchemaValidator(convert_pandas=True, warn_on_conversion=False)
+polars_X = validator.fit_transform(pandas_X)
+```
+
+Pandas input is rejected unless `convert_pandas=True`. Conversion returns Polars and emits `PandasConversionWarning` about memory and performance overhead unless `warn_on_conversion=False`. Imports are lazy; core functionality works without pandas or PyArrow. The extra includes PyArrow because nullable, extension, and other non-NumPy-backed pandas dtypes can require it for `pl.from_pandas`. Conversion follows Polars conventions (including NaN-to-null and ignoring the pandas index). Unsupported conversion dtypes raise rather than falling back to row-wise operations.
+
+## Development
+
+```bash
+uv sync
+uv sync --extra pandas     # Optional interoperability test coverage
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv build
+```
+
+`uv.lock` pins reproducible development dependencies. Pyright includes its Node runtime through the development extra, so no system Node installation is needed. Pandas tests use `pytest.importorskip("pandas")`; core tests also run without the optional extra. The package ships `py.typed` for downstream typing tools.
+
+Library requirements use minimum versions without speculative upper bounds. Add an upper bound or exclude a release only when a known incompatibility requires it; the lockfile pins the development environment without constraining downstream applications.
+
+### Releases
+
+GitHub Actions follows the same release setup as Conformity. Configure the repository or `pypi` environment secret `PYPI_API_TOKEN` with a PyPI upload token for `polars-learn`. The publishing job uses the `pypi` environment. No API token belongs in this repository.
+
+Update `project.version` in `pyproject.toml` and `__version__` in `src/polars_learn/__init__.py`, run `uv lock`, and push the changes. Then run **Create GitHub Release** from the Actions tab. It checks tests, linting, formatting, and types; rejects an existing `vX.Y.Z` tag; builds and validates distributions; creates a GitHub release with those files; and passes the same artifacts directly to **Upload Python Package** for PyPI publishing. The reusable workflow call is necessary because a release created with GitHub's workflow token does not trigger another release workflow.
+
+Alternatively, publish a GitHub release tagged `vX.Y.Z` matching `project.version`. **Upload Python Package** checks the package, builds distributions, and publishes them automatically. Pushes and pull requests run **Tests** on Python 3.11 and 3.12, both with and without the pandas extra. Creating or publishing a release uploads that version to PyPI; ordinary pushes do not publish packages.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

polars_learn-0.1.0/README.md

@@ -0,0 +1,167 @@
+# polars-learn
+
+High-performance feature engineering for scikit-learn, powered by Polars.
+
+## Features
+
+- Composable native Polars expressions, evaluated in dependency order.
+- Learned schemas with strict, semi-strict, and permissive validation.
+- scikit-learn estimators with cloning, parameters, and feature names.
+- Native Polars output and optional, explicit pandas conversion.
+- Python 3.11+, Polars 1.20+, and scikit-learn 1.6+.
+
+## Installation
+
+```bash
+uv add polars-learn
+# From a local checkout:
+uv pip install .
+# Optional pandas and PyArrow support:
+uv pip install '.[pandas]'
+```
+
+## Quick Start
+
+```python
+import polars as pl
+from polars_learn import FeatureEngineer, FeatureSpec, SchemaValidator
+
+X = pl.DataFrame({"price": [10.0, 20.0, 30.0], "quantity": [2, 3, 4]})
+validator = SchemaValidator(mode="strict").fit(X)
+validated = validator.transform(X)
+
+engineer = FeatureEngineer(
+    [
+        FeatureSpec(pl.col("price") * pl.col("quantity"), alias="notional"),
+        FeatureSpec(
+            pl.col("notional").log1p(),
+            alias="log_notional",
+            drop=["quantity"],
+        ),
+    ]
+)
+result = engineer.fit_transform(validated)
+print(result)
+print(engineer.get_feature_names_out())
+# ['price' 'notional' 'log_notional']
+```
+
+## Feature Engineering
+
+`FeatureSpec` accepts exactly one of `expression` (one `pl.Expr`) or `expressions` (a nonempty sequence of expressions). It stores a single canonical expression tuple. Names follow Polars conventions: an existing alias or a native output name needs no additional alias. An explicit `alias` overrides the name of one output; it is rejected for multiple outputs. Selectors and expression expansion are supported, with their output names resolved against the frame.
+
+```python
+spec = FeatureSpec(
+    expressions=[
+        (pl.col("ask") - pl.col("bid")).alias("spread"),
+        ((pl.col("ask") + pl.col("bid")) / 2).alias("mid"),
+    ],
+    drop=["ask", "bid"],
+    name="quote_features",
+)
+quotes = pl.DataFrame({"ask": [11.0], "bid": [9.0]})
+print(FeatureEngineer([spec]).fit_transform(quotes))
+```
+
+Expressions within one specification are evaluated together and cannot reference new columns created by siblings. Separate specifications execute sequentially; later ones can use earlier outputs. Drops happen after each specification. Missing expression inputs, missing drop columns, and duplicate output names raise `FeatureEngineeringError` (duplicate names detectable at construction raise `ValueError`). Overwriting existing columns is allowed and keeps Polars' column position. For example, `FeatureSpec(pl.col("price") + 1)` replaces `price`.
+
+`fit` executes the training transformation to validate expressions and learn output names and dtypes. `transform` requires the fitted input column names and order and the exact fitted output schema. Input dtype differences are acceptable only when the resulting schema remains identical; use `SchemaValidator` first for explicit input type policies. Empty feature lists are identity transforms. The public API accepts eager DataFrames; internally, lazy stages preserve sequential semantics and collect once per execution. Expressions are stateless; training transformations do not learn statistics. Use deterministic expressions to keep training and inference consistent.
+
+## Schema Validation
+
+```python
+validator = SchemaValidator(
+    mode="semi-strict",
+    allow_extra_columns=False,
+    enforce_column_order=True,
+)
+validator.fit(X)  # Always learns the raw input schema
+print(validator.schema_)
+validated = validator.transform(X)  # Always validates against that schema
+```
+
+| Mode               | Policy for differing dtypes                             |
+| ------------------ | ------------------------------------------------------- |
+| `strict` (default) | Reject every dtype difference.                          |
+| `semi-strict`      | Allow only the explicit lossless widening policy below. |
+| `permissive`       | Use Polars `cast(strict=True)` and report failures.     |
+
+Semi-strict allows integer widening when the entire source dtype's range fits inside the target integer dtype (including compatible unsigned-to-signed widening), Float32 → Float64, and integer → Float64 only when **every non-null value round-trips exactly**. For example, Int64 `2**53` and `2**54` are accepted, but `2**53 + 1` is rejected. It rejects narrowing, strings to numbers, and Null dtype to a different dtype. Null values in already compatible columns are preserved; nullability constraints are not part of this version.
+
+Permissive casts may be lossy according to Polars semantics, such as floats to integers. Failed casts never silently replace invalid values with nulls. Missing required columns always fail; multiple schema mismatches are reported in `SchemaValidationError`. Strict mode does not cast or rename columns.
+
+Extra columns fail by default. Set `allow_extra_columns=True` to preserve them, or also set `extra_columns="drop"` to explicitly remove them. Column order checks compare the relative order of required columns; permitted extras may appear anywhere. With `enforce_column_order=False`, output is normalised to fitted column order, followed by preserved extras in their input order. `get_feature_names_out()` describes fitted required columns; inference-only extras are not included. Avoid preserving inference-only extras before a fixed-width downstream estimator or `FeatureEngineer`.
+
+The shorthand `strict=True` means strict mode, and `strict=False` means permissive mode. Conflicting `strict` and `mode` arguments are rejected. Schemas learned by the validator and feature engineer are independent.
+
+## scikit-learn Pipelines
+
+```python
+import numpy as np
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+pipeline = Pipeline(
+    [
+        ("schema", SchemaValidator(mode="semi-strict")),
+        ("features", engineer),
+        ("scale", StandardScaler().set_output(transform="polars")),
+        ("model", RandomForestRegressor(n_estimators=20, random_state=0)),
+    ]
+)
+pipeline.fit(X, np.array([1.0, 2.0, 3.0]))
+print(pipeline.predict(X))
+print(pipeline[:-1].get_feature_names_out())
+```
+
+These transformers implement `fit`, `transform`, `fit_transform`, `get_params`, `set_params`, and `get_feature_names_out`. Fitted attributes include `feature_names_in_`, `n_features_in_`, and `output_features_`. Cloning discards fitted state. Supplied `input_features` must exactly match fitted input names.
+
+Data stays in Polars between our transformers. Both support `set_output(transform="default")` and `set_output(transform="polars")`, which return native Polars frames. They reject `"pandas"` output and deliberately bypass scikit-learn's automatic output wrapping, including global output settings, to preserve native names and allowed extras. No automatic NumPy conversion occurs. Downstream estimator support for Polars depends on the estimator and installed scikit-learn version; arbitrary string columns do not work with random forests.
+
+Tests run applicable scikit-learn constructor, parameter, and cloning checks. Generic checks requiring NumPy array input do not apply to this deliberately DataFrame-only API. No LazyFrame, sparse-array, or NumPy input is accepted.
+
+## Optional Pandas Support
+
+```bash
+uv sync --extra pandas
+```
+
+```python
+# Requires the pandas extra; both transformers expose these options.
+import pandas as pd
+
+pandas_X = pd.DataFrame({"price": [10.0, 20.0], "quantity": [2, 3]})
+validator = SchemaValidator(convert_pandas=True, warn_on_conversion=False)
+polars_X = validator.fit_transform(pandas_X)
+```
+
+Pandas input is rejected unless `convert_pandas=True`. Conversion returns Polars and emits `PandasConversionWarning` about memory and performance overhead unless `warn_on_conversion=False`. Imports are lazy; core functionality works without pandas or PyArrow. The extra includes PyArrow because nullable, extension, and other non-NumPy-backed pandas dtypes can require it for `pl.from_pandas`. Conversion follows Polars conventions (including NaN-to-null and ignoring the pandas index). Unsupported conversion dtypes raise rather than falling back to row-wise operations.
+
+## Development
+
+```bash
+uv sync
+uv sync --extra pandas     # Optional interoperability test coverage
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv build
+```
+
+`uv.lock` pins reproducible development dependencies. Pyright includes its Node runtime through the development extra, so no system Node installation is needed. Pandas tests use `pytest.importorskip("pandas")`; core tests also run without the optional extra. The package ships `py.typed` for downstream typing tools.
+
+Library requirements use minimum versions without speculative upper bounds. Add an upper bound or exclude a release only when a known incompatibility requires it; the lockfile pins the development environment without constraining downstream applications.
+
+### Releases
+
+GitHub Actions follows the same release setup as Conformity. Configure the repository or `pypi` environment secret `PYPI_API_TOKEN` with a PyPI upload token for `polars-learn`. The publishing job uses the `pypi` environment. No API token belongs in this repository.
+
+Update `project.version` in `pyproject.toml` and `__version__` in `src/polars_learn/__init__.py`, run `uv lock`, and push the changes. Then run **Create GitHub Release** from the Actions tab. It checks tests, linting, formatting, and types; rejects an existing `vX.Y.Z` tag; builds and validates distributions; creates a GitHub release with those files; and passes the same artifacts directly to **Upload Python Package** for PyPI publishing. The reusable workflow call is necessary because a release created with GitHub's workflow token does not trigger another release workflow.
+
+Alternatively, publish a GitHub release tagged `vX.Y.Z` matching `project.version`. **Upload Python Package** checks the package, builds distributions, and publishes them automatically. Pushes and pull requests run **Tests** on Python 3.11 and 3.12, both with and without the pandas extra. Creating or publishing a release uploads that version to PyPI; ordinary pushes do not publish packages.
+
+## License
+
+MIT. See [LICENSE](LICENSE).