featkit 0.1.0__tar.gz

featkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install lint dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Run Ruff lint
+        run: ruff check .
+
+      - name: Check formatting
+        run: ruff format --check .
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run mypy
+        run: mypy .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

featkit-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build and deploy docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

featkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check distribution
+        run: twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

featkit-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+site/
+*.log

featkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

featkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mirko
+
+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.

featkit-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: featkit
+Version: 0.1.0
+Summary: featkit — automated feature store generation from relational facts tables
+Project-URL: Repository, https://github.com/Mirkiux/featkit
+Project-URL: Documentation, https://mirkiux.github.io/featkit
+Project-URL: Changelog, https://github.com/Mirkiux/featkit/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/Mirkiux/featkit/issues
+Author: Mirko
+License: MIT License
+        
+        Copyright (c) 2026 Mirko
+        
+        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.
+License-File: LICENSE
+Keywords: analytics,data engineering,databricks,feature engineering,feature store,pivot,pyspark,snowflake
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: sqlglot>=23.0
+Provides-Extra: databricks
+Requires-Dist: databricks-sql-connector>=3.0; extra == 'databricks'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hatch>=1.9; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: ibis
+Requires-Dist: ibis-framework>=9.0; extra == 'ibis'
+Provides-Extra: spark
+Requires-Dist: pyspark>=3.4; extra == 'spark'
+Description-Content-Type: text/markdown
+
+# featkit
+
+**featkit** is a Python framework for automated feature store generation from relational facts tables.
+
+It implements a three-layer architecture:
+
+- **Layer 1** — input facts table with typed columns (ID, time, categorical, measurement)
+- **Layer 2** — horizontal concept table built via pivot (2A) and distributional aggregations (2B)
+- **Layer 3** — temporal feature table produced by sliding operators over the Layer 2 columns
+
+The framework is engine-agnostic: the same pipeline definition produces either a standalone SQL script (Snowflake, Databricks SQL, Spark SQL) or a lazy PySpark execution plan, with the choice abstracted behind a code generator interface.
+
+## Key concepts
+
+| Layer | What it does |
+|---|---|
+| Layer 2A — Pivot | `GROUP BY (ID, time)` + `CASE WHEN` per categorical combination × measurement × aggregator |
+| Layer 2B — Distributional | Per-categorical CTEs computing entropy, HHI, dominant proportion, mode, count |
+| Layer 3 — Temporal | Sliding window operators (PROM_U, SUM_U, CREC, FREQ, REC, …) over all Layer 2 columns |
+
+## Installation
+
+```bash
+pip install featkit
+```
+
+## Quickstart
+
+```python
+from featkit import FeatureStorePipeline, FeatureStoreConfig
+from featkit.dataset import SimpleDataset
+from featkit.fields import IDField, TimeField, CategoricalField, MeasurementField
+from featkit.enums import MeasurementType, TimeGranularity, CategoricalTreatment
+from featkit.generators.sql import SnowflakeSQLCodeGenerator
+
+# Define schema
+fields = [
+    IDField(name="ID_CLIENTE"),
+    TimeField(name="PERIODO",
+              source_granularity=TimeGranularity.MONTHLY,
+              target_granularity=TimeGranularity.MONTHLY),
+    CategoricalField(name="SECTOR", treatment=CategoricalTreatment.PIVOT,
+                     allowed_values=["RETAIL", "CORP", "PYME"]),
+    CategoricalField(name="CANAL",  treatment=CategoricalTreatment.PIVOT,
+                     allowed_values=["DIGITAL", "PRESENCIAL", "TELEFONO"]),
+    MeasurementField(name="MTO", measurement_type=MeasurementType.MONTO),
+    MeasurementField(name="TRX", measurement_type=MeasurementType.CANTIDAD),
+]
+
+dataset = SimpleDataset(
+    source_reference="MY_DB.MY_SCHEMA.FACTS_TABLE",
+    fields=fields,
+)
+
+config = FeatureStoreConfig(
+    dataset=dataset,
+    output_schema="MY_DB.MY_SCHEMA",
+    output_table_prefix="FS",
+    time_windows=[3, 6, 9, 12],
+)
+
+pipeline = FeatureStorePipeline(config).build()
+output = pipeline.run(SnowflakeSQLCodeGenerator())
+
+output.save("./output")
+# Writes: output/script.sql, output/dag.json, output/diagram.md
+```
+
+## Architecture
+
+See [docs/general_plan.md](docs/general_plan.md) for the full implementation plan.
+
+## License
+
+MIT

featkit-0.1.0/README.md

@@ -0,0 +1,75 @@
+# featkit
+
+**featkit** is a Python framework for automated feature store generation from relational facts tables.
+
+It implements a three-layer architecture:
+
+- **Layer 1** — input facts table with typed columns (ID, time, categorical, measurement)
+- **Layer 2** — horizontal concept table built via pivot (2A) and distributional aggregations (2B)
+- **Layer 3** — temporal feature table produced by sliding operators over the Layer 2 columns
+
+The framework is engine-agnostic: the same pipeline definition produces either a standalone SQL script (Snowflake, Databricks SQL, Spark SQL) or a lazy PySpark execution plan, with the choice abstracted behind a code generator interface.
+
+## Key concepts
+
+| Layer | What it does |
+|---|---|
+| Layer 2A — Pivot | `GROUP BY (ID, time)` + `CASE WHEN` per categorical combination × measurement × aggregator |
+| Layer 2B — Distributional | Per-categorical CTEs computing entropy, HHI, dominant proportion, mode, count |
+| Layer 3 — Temporal | Sliding window operators (PROM_U, SUM_U, CREC, FREQ, REC, …) over all Layer 2 columns |
+
+## Installation
+
+```bash
+pip install featkit
+```
+
+## Quickstart
+
+```python
+from featkit import FeatureStorePipeline, FeatureStoreConfig
+from featkit.dataset import SimpleDataset
+from featkit.fields import IDField, TimeField, CategoricalField, MeasurementField
+from featkit.enums import MeasurementType, TimeGranularity, CategoricalTreatment
+from featkit.generators.sql import SnowflakeSQLCodeGenerator
+
+# Define schema
+fields = [
+    IDField(name="ID_CLIENTE"),
+    TimeField(name="PERIODO",
+              source_granularity=TimeGranularity.MONTHLY,
+              target_granularity=TimeGranularity.MONTHLY),
+    CategoricalField(name="SECTOR", treatment=CategoricalTreatment.PIVOT,
+                     allowed_values=["RETAIL", "CORP", "PYME"]),
+    CategoricalField(name="CANAL",  treatment=CategoricalTreatment.PIVOT,
+                     allowed_values=["DIGITAL", "PRESENCIAL", "TELEFONO"]),
+    MeasurementField(name="MTO", measurement_type=MeasurementType.MONTO),
+    MeasurementField(name="TRX", measurement_type=MeasurementType.CANTIDAD),
+]
+
+dataset = SimpleDataset(
+    source_reference="MY_DB.MY_SCHEMA.FACTS_TABLE",
+    fields=fields,
+)
+
+config = FeatureStoreConfig(
+    dataset=dataset,
+    output_schema="MY_DB.MY_SCHEMA",
+    output_table_prefix="FS",
+    time_windows=[3, 6, 9, 12],
+)
+
+pipeline = FeatureStorePipeline(config).build()
+output = pipeline.run(SnowflakeSQLCodeGenerator())
+
+output.save("./output")
+# Writes: output/script.sql, output/dag.json, output/diagram.md
+```
+
+## Architecture
+
+See [docs/general_plan.md](docs/general_plan.md) for the full implementation plan.
+
+## License
+
+MIT

featkit-0.1.0/docs/examples.md

@@ -0,0 +1,245 @@
+# Examples
+
+## Example 1 — Pivot categoricals with marginals
+
+Generate features for every category value plus the unconditional total (∅ marginal).
+
+```python
+from featkit.config import FeatureStoreConfig
+from featkit.dataset.base import SimpleDataset
+from featkit.enums import CategoricalTreatment, MeasurementType, TimeGranularity
+from featkit.fields.categorical_field import CategoricalField
+from featkit.fields.id_field import IDField
+from featkit.fields.measurement_field import MeasurementField
+from featkit.fields.time_field import TimeField
+from featkit.generators.sql.snowflake import SnowflakeSQLCodeGenerator
+from featkit.pipeline import FeatureStorePipeline
+
+ds = SimpleDataset(
+    "mydb.silver_sales",
+    [
+        IDField("client_id"),
+        TimeField("period", TimeGranularity.MONTHLY, TimeGranularity.MONTHLY),
+        MeasurementField("amount", MeasurementType.MONTO),
+        MeasurementField("txn_count", MeasurementType.CANTIDAD),
+        CategoricalField(
+            "channel",
+            CategoricalTreatment.PIVOT,
+            allowed_values=["branch", "online", "mobile"],
+        ),
+        CategoricalField(
+            "product",
+            CategoricalTreatment.PIVOT,
+            allowed_values=["current_account", "savings", "loan"],
+        ),
+    ],
+)
+
+cfg = FeatureStoreConfig(
+    dataset=ds,
+    output_schema="analytics",
+    output_table_prefix="feat_",
+    time_windows=[3, 6, 12],
+    include_marginals=True,   # include ∅ (unconditional) totals
+)
+
+pipeline = FeatureStorePipeline(config=cfg).build()
+print(f"Layer 2A columns : {len(pipeline.layer2a)}")
+print(f"Layer 3  features: {len(pipeline.layer3)}")
+
+result = SnowflakeSQLCodeGenerator().generate(pipeline)
+result.save("output/snowflake/")
+```
+
+
+## Example 2 — Distributional metrics
+
+Measure concentration, diversity, and dominant value of a categorical over time.
+
+```python
+from featkit.enums import CategoricalTreatment, DistributionalMetric, MeasurementType, TimeGranularity
+from featkit.fields.categorical_field import CategoricalField
+
+# All five distributional metrics
+region_field = CategoricalField(
+    "region",
+    CategoricalTreatment.DISTRIBUTIONAL,
+    distributional_metrics=[
+        DistributionalMetric.ENTROPY,            # diversity index
+        DistributionalMetric.HHI,                # Herfindahl–Hirschman index
+        DistributionalMetric.DOMINANT_PROPORTION, # share of the top category
+        DistributionalMetric.MODE,               # most frequent category
+        DistributionalMetric.COUNT,              # number of active categories
+    ],
+)
+```
+
+The generated `feat_layer2b` table will have one column per
+`(categorical × measurement × aggregator × metric)` combination.
+For `ENTROPY` and `HHI` the output type is `NUMERIC`; for `MODE` it is
+`CATEGORICAL`, which restricts the set of valid temporal operators
+(`ULT_MES`, `PREV_MES`, `REC` only).
+
+
+## Example 3 — Mixed pivot and distributional on the same field
+
+Use `BOTH` treatment to get pivot columns *and* distributional metrics from a
+single categorical field.
+
+```python
+from featkit.enums import CategoricalTreatment, DistributionalMetric
+
+product_field = CategoricalField(
+    "product_type",
+    CategoricalTreatment.BOTH,
+    allowed_values=["A", "B", "C"],
+    distributional_metrics=[DistributionalMetric.ENTROPY, DistributionalMetric.HHI],
+)
+```
+
+
+## Example 4 — Multiple entity keys
+
+The pipeline supports composite primary keys. List every ID field; all generated
+`GROUP BY` and join clauses will include all of them.
+
+```python
+from featkit.fields.id_field import IDField
+
+ds = SimpleDataset(
+    "mydb.silver_transactions",
+    [
+        IDField("country_code"),
+        IDField("client_id"),
+        # ... other fields
+    ],
+)
+```
+
+
+## Example 5 — Targeting Databricks SQL
+
+```python
+from featkit.generators.sql.databricks import DatabricksSQLCodeGenerator
+
+result = DatabricksSQLCodeGenerator().generate(pipeline)
+
+# Databricks uses backtick quoting; syntax is otherwise identical to Snowflake
+print(result.code.sql[:200])
+result.save("output/databricks/")
+```
+
+
+## Example 6 — Generating a PySpark script
+
+```python
+from featkit.generators.pyspark.databricks import PySparkCodeGenerator
+
+result = PySparkCodeGenerator().generate(pipeline)
+
+# result.code is a PySparkOutput; .code contains the full Python script
+script = result.code.code
+print(script[:500])
+
+# Save — writes script.py instead of script.sql
+result.save("output/pyspark/")
+```
+
+The generated script is a self-contained Python file. Execute it by submitting
+it to a Databricks job or a `spark-submit` invocation:
+
+```bash
+databricks jobs submit --existing-cluster-id <id> --python-file output/pyspark/script.py
+```
+
+
+## Example 7 — Operators override
+
+Restrict which temporal operators are applied to each Layer 2 output type.
+Useful when you only need a subset of features.
+
+```python
+from featkit.enums import Layer2OutputType, TemporalOperator
+from featkit.config import FeatureStoreConfig
+
+cfg = FeatureStoreConfig(
+    dataset=ds,
+    output_schema="analytics",
+    output_table_prefix="feat_",
+    time_windows=[3, 6],
+    operators_override={
+        # Only rolling averages and latest-month snapshots for numeric columns
+        Layer2OutputType.NUMERIC: [
+            TemporalOperator.PROM_U,
+            TemporalOperator.SUM_U,
+            TemporalOperator.ULT_MES,
+        ],
+    },
+)
+```
+
+
+## Example 8 — Inspecting the DAG
+
+```python
+import json
+
+result = SnowflakeSQLCodeGenerator().generate(pipeline)
+
+# Programmatic access
+for node in result.dag.nodes:
+    print(f"{node.step_name:35s} depends on: {node.depends_on}")
+
+# JSON (suitable for CI artefacts or a lineage tool)
+print(json.dumps(json.loads(result.dag.to_json()), indent=2))
+
+# Mermaid diagram (paste into any Mermaid renderer)
+print(result.mermaid)
+```
+
+Expected output:
+
+```
+facts_table                         depends on: []
+mob_table                           depends on: ['facts_table']
+layer2a_pivot                       depends on: ['facts_table']
+layer2b_distributional_ctes         depends on: ['facts_table']
+layer2_join                         depends on: ['layer2a_pivot', 'layer2b_distributional_ctes']
+layer3_temporal                     depends on: ['layer2_join', 'mob_table']
+final_output                        depends on: ['layer2_join', 'layer3_temporal']
+```
+
+
+## Example 9 — Dynamic categorical domain resolution
+
+When the categorical domain is not known at configuration time, supply a
+`domain_resolver` callable. featkit will call it at `build()` time; no
+database adapter or executor is built into the framework.
+
+```python
+from featkit.builders.pivot_space import PivotSpaceBuilder
+from featkit.config import FeatureStoreConfig
+
+# Provide your own query executor
+def resolve_domain(field):
+    return conn.execute(
+        f"SELECT DISTINCT {field.name} FROM mydb.silver_transactions"
+    ).fetchall()
+
+ds = SimpleDataset(
+    "mydb.silver_transactions",
+    [
+        IDField("client_id"),
+        TimeField("period", TimeGranularity.MONTHLY, TimeGranularity.MONTHLY),
+        MeasurementField("amount", MeasurementType.MONTO),
+        CategoricalField("segment", CategoricalTreatment.PIVOT),  # no allowed_values
+    ],
+)
+
+# Build the pivot space manually with the resolver, then pass to the config
+pivot_cols = PivotSpaceBuilder(
+    dataset=ds,
+    include_marginals=True,
+    domain_resolver=resolve_domain,
+).build()
+```