featkit 0.1.0__tar.gz → 0.3.0__tar.gz

featkit-0.3.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 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]
+
+## [0.3.0] - 2026-06-08
+
+### Added
+- `AdapterCombinationResolver` — replaces per-field `SELECT DISTINCT` queries with a single multi-column query returning only observed combinations (`feat(builders)`)
+- `verbose` logging option on `PivotSpaceBuilder`, `DistributionalSpaceBuilder`, and `TemporalSpaceBuilder`, configurable via `FeatureStoreConfig` (`feat(config)`)
+
+### Fixed
+- Marginal fields no longer contribute their name to pivot column names; e.g. `SUM__amount__channel__region_north` → `SUM__amount__region_north` (`fix(layer2)`)
+
+## [0.2.0] - 2026-06-02
+
+### Added
+- Execution layer with adapter-based domain resolution (`feat(execution)`)
+
+### Fixed
+- Lazy-import `AdapterDomainResolver`; added `pandas` to dev dependencies

{featkit-0.1.0 → featkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: featkit
-Version: 0.1.0
+Version: 0.3.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
@@ -49,6 +49,7 @@ 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: pandas>=1.5; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
@@ -57,6 +58,8 @@ 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: execution
+Requires-Dist: pandas>=1.5; extra == 'execution'
 Provides-Extra: ibis
 Requires-Dist: ibis-framework>=9.0; extra == 'ibis'
 Provides-Extra: spark

featkit-0.3.0/docs/example_databricks_notebook.md

@@ -0,0 +1,209 @@
+# Example — Observed-combinations pivot in a Databricks notebook
+
+This example shows how featkit resolves pivot combinations at runtime by
+querying the facts table directly from a Databricks notebook.
+
+When an adapter is configured, `FeatureStorePipeline` constructs an
+`AdapterCombinationResolver` and passes it to `PivotSpaceBuilder`.  Instead of
+generating the full Cartesian product of per-field domains, the builder issues a
+**single `SELECT DISTINCT`** query for all pivot categoricals and builds only the
+combinations that actually exist in the data.  Marginals are then derived from
+those observed combinations via subset-projection.
+
+`DatabricksNotebookAdapter` discovers the pre-injected `spark` session
+automatically — no constructor arguments are needed.
+
+## Notebook cells
+
+### Cell 1 — imports
+
+```python
+from featkit.config import FeatureStoreConfig
+from featkit.dataset.base import SimpleDataset
+from featkit.enums import CategoricalTreatment, MeasurementType, TimeGranularity
+from featkit.execution.adapters import DatabricksNotebookAdapter
+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.databricks import DatabricksSQLCodeGenerator
+from featkit.pipeline import FeatureStorePipeline
+```
+
+### Cell 2 — define the dataset
+
+```python
+ds = SimpleDataset(
+    "mydb.myschema.silver_transactions",
+    [
+        IDField("client_id"),
+        TimeField("period", TimeGranularity.MONTHLY, TimeGranularity.MONTHLY),
+        MeasurementField("amount", MeasurementType.MONTO),
+        MeasurementField("txn_count", MeasurementType.CANTIDAD),
+        # allowed_values used as WHERE IN-filter; omit to query with no filter
+        CategoricalField(
+            "segment",
+            CategoricalTreatment.PIVOT,
+            allowed_values=["retail", "sme", "corporate"],
+        ),
+        CategoricalField(
+            "product_type",
+            CategoricalTreatment.PIVOT,
+            allowed_values=["loan", "deposit", "card"],
+        ),
+    ],
+)
+```
+
+### Cell 3 — configure with the notebook adapter
+
+```python
+adapter = DatabricksNotebookAdapter()
+
+cfg = FeatureStoreConfig(
+    dataset=ds,
+    output_schema="analytics",
+    output_table_prefix="feat_",
+    time_windows=[3, 6, 12],
+    include_marginals=True,
+    adapter=adapter,   # triggers SELECT DISTINCT combination query at build()
+)
+```
+
+### Cell 4 — build and generate
+
+```python
+# build() issues ONE SELECT DISTINCT for all pivot categoricals:
+#
+#   SELECT DISTINCT product_type, segment
+#   FROM mydb.myschema.silver_transactions
+#   WHERE product_type IS NOT NULL
+#     AND segment IS NOT NULL
+#     AND product_type IN ('loan', 'deposit', 'card')
+#     AND segment IN ('retail', 'sme', 'corporate')
+#   ORDER BY 1, 2
+#
+# Only the returned combinations (plus their marginal projections) become
+# pivot columns — unobserved cross-combinations are never generated.
+pipeline = FeatureStorePipeline(config=cfg).build()
+
+print(f"Layer 2A columns : {len(pipeline.layer2a)}")
+print(f"Layer 3  features: {len(pipeline.layer3)}")
+
+result = DatabricksSQLCodeGenerator().generate(pipeline)
+print(result.code.sql[:500])
+```
+
+### Cell 5 — save the artefacts to DBFS
+
+```python
+result.save("/dbfs/mnt/output/features/")
+# Writes:
+#   /dbfs/mnt/output/features/script.sql
+#   /dbfs/mnt/output/features/dag.json
+#   /dbfs/mnt/output/features/diagram.md
+```
+
+## How it works
+
+`FeatureStorePipeline.build()` constructs an `AdapterCombinationResolver` and
+passes it to `PivotSpaceBuilder` as the `combination_resolver` callable.  The
+resolver executes a single multi-column `SELECT DISTINCT`:
+
+```sql
+SELECT DISTINCT product_type, segment
+FROM mydb.myschema.silver_transactions
+WHERE product_type IS NOT NULL
+  AND segment IS NOT NULL
+  AND product_type IN ('loan', 'deposit', 'card')
+  AND segment IN ('retail', 'sme', 'corporate')
+ORDER BY 1, 2
+```
+
+Suppose the query returns three rows:
+
+| product_type | segment   |
+|-------------|-----------|
+| loan        | retail    |
+| loan        | sme       |
+| deposit     | corporate |
+
+With `include_marginals=True`, the builder derives every subset-projection of
+those rows:
+
+| product_type | segment   | interpretation                          |
+|-------------|-----------|------------------------------------------|
+| loan        | retail    | observed combination                    |
+| loan        | sme       | observed combination                    |
+| deposit     | corporate | observed combination                    |
+| loan        | `∅`       | all segments for loan                   |
+| deposit     | `∅`       | all segments for deposit                |
+| `∅`         | retail    | all products for retail                 |
+| `∅`         | sme       | all products for sme                    |
+| `∅`         | corporate | all products for corporate              |
+| `∅`         | `∅`       | unconditional aggregate (always present)|
+
+Unobserved combinations (e.g. `deposit × retail`) are **never generated**,
+keeping the feature space lean.
+
+## Fields without `allowed_values`
+
+If a field has no `allowed_values`, it is still included in the `SELECT DISTINCT`
+but its column is not filtered in the WHERE clause — all distinct values present
+in the table are returned for that dimension:
+
+```python
+ds = SimpleDataset(
+    "mydb.myschema.silver_transactions",
+    [
+        IDField("client_id"),
+        TimeField("period", TimeGranularity.MONTHLY, TimeGranularity.MONTHLY),
+        MeasurementField("amount", MeasurementType.MONTO),
+        # Static domain — used as IN-filter in the combined query
+        CategoricalField(
+            "channel",
+            CategoricalTreatment.PIVOT,
+            allowed_values=["branch", "online", "mobile"],
+        ),
+        # No allowed_values — column included without an IN-filter
+        CategoricalField("segment", CategoricalTreatment.PIVOT),
+    ],
+)
+```
+
+## Using a different adapter
+
+Swap `DatabricksNotebookAdapter` for any other adapter without changing the
+rest of the code:
+
+```python
+from featkit.execution.adapters import DatabricksAdapter
+
+adapter = DatabricksAdapter(
+    host="<workspace>.azuredatabricks.net",
+    token="<pat>",
+    http_path="/sql/1.0/warehouses/<warehouse-id>",
+    catalog="mydb",
+    schema="myschema",
+)
+
+cfg = FeatureStoreConfig(..., adapter=adapter)
+```
+
+## Using `AdapterCombinationResolver` directly
+
+The resolver can also be wired manually to `PivotSpaceBuilder` without going
+through the pipeline:
+
+```python
+from featkit.execution.domain_resolver import AdapterCombinationResolver
+from featkit.builders.pivot_space import PivotSpaceBuilder
+
+resolver = AdapterCombinationResolver(adapter, "mydb.myschema.silver_transactions")
+
+columns = PivotSpaceBuilder(
+    dataset=ds,
+    include_marginals=True,
+    combination_resolver=resolver,
+).build()
+```

{featkit-0.1.0 → featkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "featkit"
-version = "0.1.0"
+version = "0.3.0"
 description = "featkit — automated feature store generation from relational facts tables"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -35,6 +35,7 @@ dependencies = [
 ibis = ["ibis-framework>=9.0"]
 spark = ["pyspark>=3.4"]
 databricks = ["databricks-sql-connector>=3.0"]
+execution = ["pandas>=1.5"]
 docs = [
     "mkdocs>=1.6",
     "mkdocs-material>=9.5",
@@ -48,6 +49,7 @@ dev = [
     "hatch>=1.9",
     "build>=1.0",
     "twine>=5.0",
+    "pandas>=1.5",
 ]
 
 [project.urls]

{featkit-0.1.0 → featkit-0.3.0}/src/featkit/builders/distributional_space.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from typing import cast
 
 from featkit.contracts.measurement.defaults import get_default_contract
@@ -11,6 +12,8 @@ from featkit.fields.categorical_field import CategoricalField
 from featkit.fields.measurement_field import MeasurementField
 from featkit.layer2.distributional import DistributionalColumn
 
+_log = logging.getLogger(__name__)
+
 
 class DistributionalSpaceBuilder:
     """Generates the full set of DistributionalColumn objects for a dataset.
@@ -26,18 +29,27 @@ class DistributionalSpaceBuilder:
             An empty list produces no columns. Every entry must be present in the
             dataset (compared by name, type, and contract); a ``ValueError`` is
             raised for unknown fields.
+        verbose: When ``True``, emits ``DEBUG``-level log messages at key
+            milestones: builder start/end, and for each generated column the
+            ``(categorical, measurement, aggregator, metric)`` combination dict
+            and the resulting column name.
     """
 
     def __init__(
         self,
         dataset: AbstractDataset,
         value_measurements: list[MeasurementField] | None = None,
+        verbose: bool = False,
     ) -> None:
         self.dataset = dataset
         self.value_measurements = value_measurements
+        self.verbose = verbose
 
     def build(self) -> list[DistributionalColumn]:
         """Build and return all DistributionalColumn objects."""
+        if self.verbose:
+            _log.debug("DistributionalSpaceBuilder.build() started")
+
         all_cats = [cast(CategoricalField, f) for f in self.dataset.categorical_fields]
         dist_cats = [
             c
@@ -70,8 +82,30 @@ class DistributionalSpaceBuilder:
                 for agg in aggs:
                     for metric in cat.distributional_metrics:
                         col = DistributionalColumn(mf, agg, cat, metric)
+                        if self.verbose:
+                            _log.debug(
+                                "combo: cat=%r, measurement=%r, aggregator=%s, metric=%s",
+                                cat.name,
+                                mf.name,
+                                agg.value,
+                                metric.value,
+                            )
+                            _log.debug(
+                                "combination: %s",
+                                {
+                                    "categorical": cat.name,
+                                    "measurement": mf.name,
+                                    "aggregator": agg.value,
+                                    "metric": metric.value,
+                                },
+                            )
+                            _log.debug("column_name: %r", col.column_name)
                         if col.column_name not in seen:
                             seen.add(col.column_name)
                             results.append(col)
 
+        if self.verbose:
+            _log.debug(
+                "DistributionalSpaceBuilder.build() done — %d column(s) generated", len(results)
+            )
         return results

featkit-0.3.0/src/featkit/builders/pivot_space.py

@@ -0,0 +1,219 @@
+"""PivotSpaceBuilder — generates all PivotedColumn objects from a dataset."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from itertools import combinations as _icombinations
+from itertools import product
+from typing import cast
+
+from featkit.contracts.measurement.defaults import get_default_contract
+from featkit.dataset.base import AbstractDataset
+from featkit.enums import CategoricalTreatment, Layer2Aggregator, MeasurementType
+from featkit.fields.categorical_field import CategoricalField
+from featkit.fields.measurement_field import MeasurementField
+from featkit.layer2.pivoted import PivotedColumn
+
+_log = logging.getLogger(__name__)
+
+
+def _with_marginals(
+    observed: list[dict[CategoricalField, str]],
+    cats: list[CategoricalField],
+) -> list[dict[CategoricalField, str | None]]:
+    """Expand *observed* combinations with all ∅-substituted variants.
+
+    For each observed combination and each subset of fields, a new
+    combination is produced where those fields are replaced with ``None``
+    (the ∅ marginal sentinel).  The all-None combination is always included
+    even when *observed* is empty, since it represents an unconditional
+    aggregate over all data.
+
+    Duplicates are suppressed so overlapping projections of different
+    observed combinations appear only once.
+    """
+    seen: set[tuple[tuple[str, str | None], ...]] = set()
+    result: list[dict[CategoricalField, str | None]] = []
+
+    def _append(combo: dict[CategoricalField, str | None]) -> None:
+        key = tuple(sorted((f.name, combo[f]) for f in cats))
+        if key not in seen:
+            seen.add(key)
+            result.append(combo)
+
+    _append({f: None for f in cats})
+
+    for combo in observed:
+        for r in range(len(cats)):  # r == len(cats) (all-None) already added above
+            for nulled in _icombinations(cats, r):
+                c: dict[CategoricalField, str | None] = dict(combo)
+                for f in nulled:
+                    c[f] = None
+                _append(c)
+
+    return result
+
+
+class PivotSpaceBuilder:
+    """Generates the full set of PivotedColumn objects for a dataset.
+
+    Two combination strategies are supported:
+
+    * **Observed combinations** (preferred when an adapter is available):
+      supply a ``combination_resolver`` callable.  It receives the list of
+      pivot categorical fields and returns only the combinations that
+      actually exist in the source table.  Marginals are then derived from
+      those observed combinations rather than from the full Cartesian
+      product.
+
+    * **Cartesian product** (default, no adapter required): per-field
+      domains are resolved from ``allowed_values`` or ``domain_resolver``
+      and the full product is generated.
+
+    Args:
+        dataset: The source facts-table schema.
+        include_marginals: When True, ∅-substituted combinations are added
+            on top of the base combinations (observed or Cartesian).
+        aggregators_override: Per-measurement-type override list. Only
+            aggregators that are also contract-valid for the measurement
+            type are used.
+        combination_resolver: Callable that takes the list of pivot
+            ``CategoricalField`` objects and returns the observed
+            combinations as a list of ``{field: value}`` dicts.  When
+            provided, ``domain_resolver`` is not used.
+        domain_resolver: Callable invoked per-field to resolve the domain
+            of a categorical whose ``allowed_values`` is None.  Used only
+            in the Cartesian product path (i.e. when
+            ``combination_resolver`` is not provided).  Raises
+            ``ValueError`` at build time if a dynamic field is encountered
+            and this is not provided.
+        verbose: When ``True``, emits ``DEBUG``-level log messages at key
+            milestones: builder start/end, each ``domain_resolver``
+            invocation with its resolved values, each ``cat_combination``
+            dict, and every generated column name.
+    """
+
+    def __init__(
+        self,
+        dataset: AbstractDataset,
+        include_marginals: bool = True,
+        aggregators_override: dict[MeasurementType, list[Layer2Aggregator]] | None = None,
+        combination_resolver: (
+            Callable[[list[CategoricalField]], list[dict[CategoricalField, str]]] | None
+        ) = None,
+        domain_resolver: Callable[[CategoricalField], list[str]] | None = None,
+        verbose: bool = False,
+    ) -> None:
+        self.dataset = dataset
+        self.include_marginals = include_marginals
+        self.aggregators_override = aggregators_override
+        self.combination_resolver = combination_resolver
+        self.domain_resolver = domain_resolver
+        self.verbose = verbose
+
+    def build(self) -> list[PivotedColumn]:
+        """Build and return all PivotedColumn objects."""
+        if self.verbose:
+            _log.debug("PivotSpaceBuilder.build() started")
+
+        all_cats = [cast(CategoricalField, f) for f in self.dataset.categorical_fields]
+        pivot_cats = [
+            c
+            for c in all_cats
+            if c.treatment in {CategoricalTreatment.PIVOT, CategoricalTreatment.BOTH}
+        ]
+        measurements = [cast(MeasurementField, f) for f in self.dataset.measurement_fields]
+
+        all_combos: list[dict[CategoricalField, str | None]]
+
+        if self.combination_resolver is not None and pivot_cats:
+            observed_raw = self.combination_resolver(pivot_cats)
+            pivot_key_set = set(pivot_cats)
+            pivot_map = {c: c for c in pivot_cats}
+            observed: list[dict[CategoricalField, str]] = []
+            for combo in observed_raw:
+                if set(combo.keys()) != pivot_key_set:
+                    raise ValueError(
+                        "combination_resolver must return dicts keyed by all "
+                        "pivot categorical fields"
+                    )
+                if any(v is None for v in combo.values()):
+                    raise ValueError(
+                        "combination_resolver returned None; "
+                        "None is reserved as the ∅ marginal sentinel"
+                    )
+                observed.append({pivot_map[f]: str(v) for f, v in combo.items()})
+            if self.include_marginals:
+                all_combos = _with_marginals(observed, pivot_cats)
+            else:
+                all_combos = [dict(c) for c in observed]
+        else:
+            cat_domains: dict[CategoricalField, list[str | None]] = {}
+            for cat in pivot_cats:
+                if cat.allowed_values is not None:
+                    raw: list[str] = list(cat.allowed_values)
+                elif self.domain_resolver is not None:
+                    if self.verbose:
+                        _log.debug("domain_resolver: resolving domain for categorical %r", cat.name)
+                    raw = list(self.domain_resolver(cat))
+                    if self.verbose:
+                        _log.debug(
+                            "domain_resolver: resolved %d value(s) for %r: %s",
+                            len(raw),
+                            cat.name,
+                            raw,
+                        )
+                else:
+                    raise ValueError(
+                        f"CategoricalField {cat.name!r} has no allowed_values and no "
+                        f"domain_resolver was provided"
+                    )
+                if any(v is None for v in raw):
+                    raise ValueError(
+                        f"CategoricalField {cat.name!r}: resolved domain contains None; "
+                        f"None is reserved as the ∅ marginal sentinel"
+                    )
+                domain: list[str | None] = list(raw)
+                if self.include_marginals:
+                    domain = domain + [None]
+                cat_domains[cat] = domain
+
+            cats = list(cat_domains.keys())
+            combos = product(*(cat_domains[c] for c in cats)) if cats else ((),)
+            all_combos = [
+                {cats[i]: combo[i] for i in range(len(cats))} if cats else {} for combo in combos
+            ]
+
+        results: list[PivotedColumn] = []
+        seen: dict[str, PivotedColumn] = {}
+
+        for cat_combination in all_combos:
+            if self.verbose:
+                _log.debug(
+                    "cat_combination: %s",
+                    {c.name: v for c, v in cat_combination.items()},
+                )
+            for mf in measurements:
+                for agg in self._valid_aggregators(mf):
+                    col = PivotedColumn(mf, agg, cat_combination)
+                    if col.column_name in seen:
+                        raise ValueError(
+                            f"Duplicate pivot column name generated: {col.column_name!r}. "
+                            f"Conflicting columns: {seen[col.column_name]!r} and {col!r}"
+                        )
+                    if self.verbose:
+                        _log.debug("column_name: %r", col.column_name)
+                    seen[col.column_name] = col
+                    results.append(col)
+
+        if self.verbose:
+            _log.debug("PivotSpaceBuilder.build() done — %d column(s) generated", len(results))
+        return results
+
+    def _valid_aggregators(self, mf: MeasurementField) -> list[Layer2Aggregator]:
+        contract = mf.contract or get_default_contract(mf.measurement_type)
+        valid = contract.valid_layer2_aggregators
+        if self.aggregators_override and mf.measurement_type in self.aggregators_override:
+            return [a for a in self.aggregators_override[mf.measurement_type] if a in valid]
+        return sorted(valid, key=lambda a: a.value)

{featkit-0.1.0 → featkit-0.3.0}/src/featkit/builders/temporal_space.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
+import logging
 from collections.abc import Sequence
 
 from featkit.enums import Layer2OutputType, TemporalOperator, TimeWindowDirection
 from featkit.layer2.base import AbstractLayer2Column
 from featkit.layer3.temporal_feature import _POINT_IN_TIME_OPERATORS, TemporalFeature
 
+_log = logging.getLogger(__name__)
+
 #: Operators that require composed (MEDIA_ABS / RATIO) window sizes.
 _COMPOSED_OPERATORS: frozenset[TemporalOperator] = frozenset(
     {TemporalOperator.MEDIA_ABS, TemporalOperator.RATIO}
@@ -33,6 +36,10 @@ class TemporalSpaceBuilder:
         direction: Sliding-window direction applied to every feature.
         operators_override: Per-output-type override. Only operators that are
             also contract-valid for the column's output type are used.
+        verbose: When ``True``, emits ``DEBUG``-level log messages at key
+            milestones: builder start/end, and for each generated feature the
+            ``(layer2_column, operator, window)`` combination dict and the
+            resulting column name.
     """
 
     def __init__(
@@ -42,15 +49,20 @@ class TemporalSpaceBuilder:
         composed_windows: list[int] | None = None,
         direction: TimeWindowDirection = TimeWindowDirection.BACKWARD,
         operators_override: dict[Layer2OutputType, list[TemporalOperator]] | None = None,
+        verbose: bool = False,
     ) -> None:
         self.layer2_columns = layer2_columns
         self.time_windows = time_windows
         self.composed_windows = composed_windows
         self.direction = direction
         self.operators_override = operators_override
+        self.verbose = verbose
 
     def build(self) -> list[TemporalFeature]:
         """Build and return all TemporalFeature objects."""
+        if self.verbose:
+            _log.debug("TemporalSpaceBuilder.build() started")
+
         results: list[TemporalFeature] = []
         seen: set[str] = set()
 
@@ -79,8 +91,26 @@ class TemporalSpaceBuilder:
 
                 for ws in window_sizes:
                     feat = TemporalFeature(col, op, self.direction, window_size=ws)
+                    if self.verbose:
+                        _log.debug(
+                            "combo: layer2_column=%r, operator=%s, window=%s",
+                            col.column_name,
+                            op.value,
+                            ws,
+                        )
+                        _log.debug(
+                            "combination: %s",
+                            {
+                                "layer2_column": col.column_name,
+                                "operator": op.value,
+                                "window": ws,
+                            },
+                        )
+                        _log.debug("column_name: %r", feat.column_name)
                     if feat.column_name not in seen:
                         seen.add(feat.column_name)
                         results.append(feat)
 
+        if self.verbose:
+            _log.debug("TemporalSpaceBuilder.build() done — %d feature(s) generated", len(results))
         return results

{featkit-0.1.0 → featkit-0.3.0}/src/featkit/config.py

@@ -3,10 +3,14 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 
 from featkit.dataset.base import AbstractDataset
 from featkit.enums import Layer2Aggregator, Layer2OutputType, MeasurementType, TemporalOperator
 
+if TYPE_CHECKING:
+    from featkit.execution.adapters.base import DataSourceAdapter
+
 
 @dataclass
 class FeatureStoreConfig:
@@ -26,6 +30,14 @@ class FeatureStoreConfig:
             aggregators. Only contract-valid aggregators are used.
         operators_override: Per-output-type override for temporal operators.
             Only contract-valid operators are used.
+        adapter: Optional execution adapter.  When provided, categorical fields
+            with no ``allowed_values`` have their domain resolved at
+            ``FeatureStorePipeline.build()`` time via a ``SELECT DISTINCT``
+            query against the facts table.
+        verbose: When ``True``, the space builders emit ``DEBUG``-level log
+            messages at key milestones: builder start/end, ``domain_resolver``
+            invocations (PivotSpaceBuilder only), and each generated column name
+            together with the combination that produced it.
     """
 
     dataset: AbstractDataset
@@ -36,3 +48,5 @@ class FeatureStoreConfig:
     include_marginals: bool = True
     aggregators_override: dict[MeasurementType, list[Layer2Aggregator]] | None = None
     operators_override: dict[Layer2OutputType, list[TemporalOperator]] | None = field(default=None)
+    adapter: DataSourceAdapter | None = None
+    verbose: bool = False