featkit 0.1.0__py3-none-any.whl

featkit/dataset/base.py

@@ -0,0 +1,120 @@
+"""Dataset descriptors — pure schema metadata for the source facts table."""
+
+from __future__ import annotations
+
+from abc import ABC
+
+from featkit.enums import FieldRole
+from featkit.fields.base import AbstractField
+
+
+class AbstractDataset(ABC):  # noqa: B024
+    """Schema descriptor for an input facts table.
+
+    Holds pure metadata — no data access, no materialisation. Derived
+    field-role properties filter :attr:`fields` by role; :meth:`validate`
+    asserts structural consistency.
+
+    Args:
+        source_reference: Fully-qualified table name or SQL string that
+            identifies the source of the facts.
+        fields: All columns in the facts table.
+    """
+
+    def __init__(self, source_reference: str, fields: list[AbstractField]) -> None:
+        self.source_reference = source_reference
+        self.fields: list[AbstractField] = list(fields)
+
+    # ------------------------------------------------------------------
+    # Derived field-role properties
+    # ------------------------------------------------------------------
+
+    @property
+    def id_fields(self) -> list[AbstractField]:
+        """All fields whose role is :attr:`~featkit.enums.FieldRole.ID`."""
+        return [f for f in self.fields if f.role == FieldRole.ID]
+
+    @property
+    def time_field(self) -> AbstractField:
+        """The single TIME field in this dataset.
+
+        Raises:
+            ValueError: If no TIME field exists or more than one does.
+        """
+        time_fields = [f for f in self.fields if f.role == FieldRole.TIME]
+        if len(time_fields) == 0:
+            raise ValueError("no TIME field; exactly one is required")
+        if len(time_fields) > 1:
+            raise ValueError(f"{len(time_fields)} TIME fields; exactly one is required")
+        return time_fields[0]
+
+    @property
+    def categorical_fields(self) -> list[AbstractField]:
+        """All fields whose role is :attr:`~featkit.enums.FieldRole.CATEGORICAL`."""
+        return [f for f in self.fields if f.role == FieldRole.CATEGORICAL]
+
+    @property
+    def measurement_fields(self) -> list[AbstractField]:
+        """All fields whose role is :attr:`~featkit.enums.FieldRole.MEASUREMENT`."""
+        return [f for f in self.fields if f.role == FieldRole.MEASUREMENT]
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    def validate(self) -> None:
+        """Assert structural consistency of the dataset schema.
+
+        Checks:
+        - Exactly one TIME field
+        - At least one ID field
+        - At least one MEASUREMENT field
+        - No duplicate field names
+
+        Raises:
+            ValueError: With a description of every violation found.
+        """
+        violations: list[str] = []
+
+        time_count = sum(1 for f in self.fields if f.role == FieldRole.TIME)
+        if time_count == 0:
+            violations.append("no TIME field; exactly one is required")
+        elif time_count > 1:
+            violations.append(f"{time_count} TIME fields; exactly one is required")
+
+        if not any(f.role == FieldRole.ID for f in self.fields):
+            violations.append("no ID field found; at least one is required")
+
+        if not any(f.role == FieldRole.MEASUREMENT for f in self.fields):
+            violations.append("no MEASUREMENT field found; at least one is required")
+
+        seen: set[str] = set()
+        duplicates: set[str] = set()
+        for f in self.fields:
+            if f.name in seen:
+                duplicates.add(f.name)
+            seen.add(f.name)
+        if duplicates:
+            violations.append(f"duplicate field name(s): {', '.join(sorted(duplicates))}")
+
+        if violations:
+            raise ValueError(
+                "Dataset validation failed:\n" + "\n".join(f"  - {v}" for v in violations)
+            )
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"source_reference={self.source_reference!r}, "
+            f"fields={len(self.fields)})"
+        )
+
+
+class SimpleDataset(AbstractDataset):
+    """Concrete dataset descriptor — the standard entry point for schema definition.
+
+    Accepts ``source_reference`` and ``fields`` directly; no subclassing needed.
+    """
+
+    def __init__(self, source_reference: str, fields: list[AbstractField]) -> None:
+        super().__init__(source_reference, fields)

featkit/enums.py

@@ -0,0 +1,110 @@
+"""Enumerators that form the type system of the featkit framework."""
+
+from enum import Enum
+
+
+class FieldRole(Enum):
+    """Role of a column in the source facts table."""
+
+    ID = "ID"
+    TIME = "TIME"
+    CATEGORICAL = "CATEGORICAL"
+    MEASUREMENT = "MEASUREMENT"
+
+
+class MeasurementType(Enum):
+    """Semantic type of a measurement column.
+
+    Governs which :class:`~featkit.enums.Layer2Aggregator` values are valid
+    for that column at the Layer 1 → Layer 2 boundary.
+    """
+
+    MONTO = "MONTO"
+    CANTIDAD = "CANTIDAD"
+    TICKET = "TICKET"
+    FLAG = "FLAG"
+    FECHA = "FECHA"
+    BALANCE = "BALANCE"
+    TIME_DIFF = "TIME_DIFF"
+    ESTADISTICO = "ESTADISTICO"
+
+
+class TimeGranularity(Enum):
+    """Temporal granularity of a time column."""
+
+    DAILY = "DAILY"
+    WEEKLY = "WEEKLY"
+    MONTHLY = "MONTHLY"
+    QUARTERLY = "QUARTERLY"
+    YEARLY = "YEARLY"
+
+
+class CategoricalTreatment(Enum):
+    """How a categorical column is used when building Layer 2."""
+
+    PIVOT = "PIVOT"
+    DISTRIBUTIONAL = "DISTRIBUTIONAL"
+    BOTH = "BOTH"
+
+
+class Layer2Aggregator(Enum):
+    """SQL aggregation function applied when collapsing facts into Layer 2 columns."""
+
+    SUM = "SUM"
+    COUNT = "COUNT"
+    MAX = "MAX"
+    MIN = "MIN"
+    AVG = "AVG"
+
+
+class DistributionalMetric(Enum):
+    """Statistical metric computed per-categorical in Layer 2B.
+
+    All metrics are implemented as pure SQL aggregate expressions within CTEs —
+    no custom UDAFs or stored procedures are required.
+    """
+
+    ENTROPY = "ENTROPY"
+    HHI = "HHI"
+    DOMINANT_PROPORTION = "DOMINANT_PROPORTION"
+    MODE = "MODE"
+    COUNT = "COUNT"
+
+
+class Layer2OutputType(Enum):
+    """Output type of any Layer 2 column.
+
+    Governs which :class:`~featkit.enums.TemporalOperator` values are valid
+    at the Layer 2 → Layer 3 boundary.
+    """
+
+    NUMERIC = "NUMERIC"
+    FLAG = "FLAG"
+    CATEGORICAL = "CATEGORICAL"
+    TEMPORAL = "TEMPORAL"
+
+
+class TemporalOperator(Enum):
+    """Sliding-window or point-in-time operator applied in Layer 3."""
+
+    PROM_U = "PROM_U"
+    PROM_P = "PROM_P"
+    SUM_U = "SUM_U"
+    SUM_P = "SUM_P"
+    ULT_MES = "ULT_MES"
+    PREV_MES = "PREV_MES"
+    CREC = "CREC"
+    FREQ = "FREQ"
+    MIN_U = "MIN_U"
+    MAX_U = "MAX_U"
+    REC = "REC"
+    XM = "XM"
+    MEDIA_ABS = "MEDIA_ABS"
+    RATIO = "RATIO"
+
+
+class TimeWindowDirection(Enum):
+    """Direction of the temporal sliding window."""
+
+    BACKWARD = "BACKWARD"
+    FORWARD = "FORWARD"

featkit/fields/__init__.py

@@ -0,0 +1,9 @@
+"""Field descriptors for the source facts table columns."""
+
+from featkit.fields.base import AbstractField
+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
+
+__all__ = ["AbstractField", "CategoricalField", "IDField", "MeasurementField", "TimeField"]

featkit/fields/base.py

@@ -0,0 +1,48 @@
+"""Abstract base class for all column descriptors."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from featkit.enums import FieldRole
+
+
+class AbstractField(ABC):
+    """Base descriptor for a column in the source facts table.
+
+    Concrete subclasses fix :attr:`role` to one of the :class:`~featkit.enums.FieldRole`
+    values.  The class carries only schema metadata — no data access.
+    """
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        """Column name as it appears in the source table."""
+        return self._name
+
+    @property
+    @abstractmethod
+    def role(self) -> FieldRole:
+        """The semantic role this column plays in the framework."""
+        ...
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(name={self.name!r})"
+
+    def _key(self) -> tuple[object, ...]:
+        """Return the identity components for equality and hashing.
+
+        Subclasses that carry additional schema-defining metadata should
+        override this method and extend the returned tuple.
+        """
+        return (self.name,)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AbstractField):
+            return NotImplemented
+        return type(self) is type(other) and self._key() == other._key()
+
+    def __hash__(self) -> int:
+        return hash((type(self), self._key()))

featkit/fields/categorical_field.py

@@ -0,0 +1,55 @@
+"""CategoricalField — a column used for pivot or distributional grouping."""
+
+from __future__ import annotations
+
+from featkit.enums import CategoricalTreatment, DistributionalMetric, FieldRole
+from featkit.fields.base import AbstractField
+
+
+class CategoricalField(AbstractField):
+    """Descriptor for a categorical column.
+
+    Can participate in Layer 2A (``PIVOT``), Layer 2B (``DISTRIBUTIONAL``), or both.
+
+    Args:
+        name: Column name in the source table.
+        treatment: How this column is used in Layer 2 construction.
+        distributional_metrics: Metrics to compute in Layer 2B. Required when
+            *treatment* includes ``DISTRIBUTIONAL``.
+        allowed_values: Static list of distinct values. When set, the
+            :class:`~featkit.builders.pivot_space.PivotSpaceBuilder` uses these
+            directly without executing a query. When ``None``, a ``domain_resolver``
+            must be supplied to the builder.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        treatment: CategoricalTreatment,
+        distributional_metrics: list[DistributionalMetric] | None = None,
+        allowed_values: list[str] | None = None,
+    ) -> None:
+        super().__init__(name)
+        self.treatment = treatment
+        self.distributional_metrics: list[DistributionalMetric] = distributional_metrics or []
+        self.allowed_values = allowed_values
+
+        if (
+            treatment in (CategoricalTreatment.DISTRIBUTIONAL, CategoricalTreatment.BOTH)
+            and not self.distributional_metrics
+        ):
+            raise ValueError(
+                f"CategoricalField {name!r}: distributional_metrics must not be empty "
+                f"when treatment is {treatment.name}"
+            )
+
+    @property
+    def role(self) -> FieldRole:
+        return FieldRole.CATEGORICAL
+
+    def _key(self) -> tuple[object, ...]:
+        normalized_metrics = tuple(sorted(self.distributional_metrics, key=lambda m: m.value))
+        normalized_values = (
+            None if self.allowed_values is None else tuple(sorted(self.allowed_values))
+        )
+        return (self.name, self.treatment, normalized_metrics, normalized_values)

featkit/fields/id_field.py

@@ -0,0 +1,14 @@
+"""IDField — identifies the entity being profiled."""
+
+from __future__ import annotations
+
+from featkit.enums import FieldRole
+from featkit.fields.base import AbstractField
+
+
+class IDField(AbstractField):
+    """A column that serves as a GROUP BY key identifying the entity (e.g. customer ID)."""
+
+    @property
+    def role(self) -> FieldRole:
+        return FieldRole.ID

featkit/fields/measurement_field.py

@@ -0,0 +1,42 @@
+"""MeasurementField — a numeric or typed measurement column."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from featkit.enums import FieldRole, MeasurementType
+from featkit.fields.base import AbstractField
+
+if TYPE_CHECKING:
+    # AbstractMeasurementTypeContract is defined in Plan 04
+    # (contracts/measurement/base.py). The TYPE_CHECKING guard keeps this a
+    # static-analysis-only import so the field module has no runtime dependency
+    # on the contracts package.
+    from featkit.contracts.measurement.base import AbstractMeasurementTypeContract
+
+
+class MeasurementField(AbstractField):
+    """Descriptor for a measurement column.
+
+    Carries a :class:`~featkit.enums.MeasurementType` and an optional reference
+    to the contract that governs valid Layer 2 aggregators. The contract is
+    typically injected via :func:`~featkit.contracts.measurement.defaults.get_default_contract`
+    after Plan 04 is available; ``None`` is valid at schema-definition time.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        measurement_type: MeasurementType,
+        contract: AbstractMeasurementTypeContract | None = None,
+    ) -> None:
+        super().__init__(name)
+        self.measurement_type = measurement_type
+        self.contract = contract
+
+    @property
+    def role(self) -> FieldRole:
+        return FieldRole.MEASUREMENT
+
+    def _key(self) -> tuple[object, ...]:
+        return (self.name, self.measurement_type, self.contract)

featkit/fields/time_field.py

@@ -0,0 +1,43 @@
+"""TimeField — the temporal axis of the facts table."""
+
+from __future__ import annotations
+
+from featkit.enums import FieldRole, TimeGranularity
+from featkit.fields.base import AbstractField
+
+
+class TimeField(AbstractField):
+    """Descriptor for the time column.
+
+    Tracks source and target granularity so downstream layers know whether
+    date truncation is required before grouping (e.g. daily source → monthly target).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        source_granularity: TimeGranularity,
+        target_granularity: TimeGranularity,
+    ) -> None:
+        super().__init__(name)
+        self.source_granularity = source_granularity
+        self.target_granularity = target_granularity
+
+    @property
+    def role(self) -> FieldRole:
+        return FieldRole.TIME
+
+    @property
+    def truncation_required(self) -> bool:
+        """``True`` when source and target granularities differ."""
+        return self.source_granularity != self.target_granularity
+
+    def _key(self) -> tuple[object, ...]:
+        return (self.name, self.source_granularity, self.target_granularity)
+
+    def __repr__(self) -> str:
+        return (
+            f"TimeField(name={self.name!r}, "
+            f"source={self.source_granularity.name}, "
+            f"target={self.target_granularity.name})"
+        )

featkit/generators/base.py

@@ -0,0 +1,171 @@
+"""AbstractCodeGenerator — engine-agnostic base for all feature-store code generators."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from featkit.generators.output import (
+    DAG,
+    CodeOutput,
+    DAGNode,
+    FeatureStoreOutput,
+    PySparkOutput,
+    SQLOutput,
+)
+
+if TYPE_CHECKING:
+    from featkit.pipeline import FeatureStorePipeline
+
+# ---------------------------------------------------------------------------
+# Fixed DAG node names
+# ---------------------------------------------------------------------------
+
+_FACTS_TABLE = "facts_table"
+_MOB_TABLE = "mob_table"
+_LAYER2A_PIVOT = "layer2a_pivot"
+_LAYER2B_DIST = "layer2b_distributional_ctes"
+_LAYER2_JOIN = "layer2_join"
+_LAYER3_TEMPORAL = "layer3_temporal"
+_FINAL_OUTPUT = "final_output"
+
+
+class AbstractCodeGenerator(ABC):
+    """Base class for all feature-store code generators.
+
+    Subclasses implement the five abstract ``build_*`` methods; the concrete
+    ``build_dag``, ``build_mermaid``, and ``generate`` methods are shared
+    across all engines.
+
+    The DAG structure is fixed for every generator:
+
+    .. code-block:: text
+
+        facts_table → mob_table
+        facts_table → layer2a_pivot
+        facts_table → layer2b_distributional_ctes
+        layer2a_pivot + layer2b_distributional_ctes → layer2_join
+        layer2_join + mob_table → layer3_temporal
+        layer2_join + layer3_temporal → final_output
+    """
+
+    # ------------------------------------------------------------------
+    # Abstract build steps
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def build_mob_table(self, pipeline: FeatureStorePipeline) -> CodeOutput:
+        """Generate the Month-on-Books (MOB) reference table step."""
+        ...
+
+    @abstractmethod
+    def build_layer2a(self, pipeline: FeatureStorePipeline) -> CodeOutput:
+        """Generate the pivot (Layer 2a) aggregation step."""
+        ...
+
+    @abstractmethod
+    def build_layer2b(self, pipeline: FeatureStorePipeline) -> CodeOutput:
+        """Generate the distributional (Layer 2b) CTE step."""
+        ...
+
+    @abstractmethod
+    def build_layer3(self, pipeline: FeatureStorePipeline) -> CodeOutput:
+        """Generate the temporal features (Layer 3) step."""
+        ...
+
+    @abstractmethod
+    def build_final_join(self, pipeline: FeatureStorePipeline) -> CodeOutput:
+        """Generate the final join that assembles the output feature table."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Concrete DAG / Mermaid helpers
+    # ------------------------------------------------------------------
+
+    def build_dag(self, pipeline: FeatureStorePipeline) -> DAG:  # noqa: ARG002
+        """Return the fixed execution DAG (pipeline argument reserved for future use)."""
+        return DAG(
+            nodes=[
+                DAGNode(_FACTS_TABLE, []),
+                DAGNode(_MOB_TABLE, [_FACTS_TABLE]),
+                DAGNode(_LAYER2A_PIVOT, [_FACTS_TABLE]),
+                DAGNode(_LAYER2B_DIST, [_FACTS_TABLE]),
+                DAGNode(_LAYER2_JOIN, [_LAYER2A_PIVOT, _LAYER2B_DIST]),
+                DAGNode(_LAYER3_TEMPORAL, [_LAYER2_JOIN, _MOB_TABLE]),
+                DAGNode(_FINAL_OUTPUT, [_LAYER2_JOIN, _LAYER3_TEMPORAL]),
+            ]
+        )
+
+    def build_mermaid(self, dag: DAG) -> str:
+        """Render *dag* as a Mermaid ``flowchart TD`` string."""
+        lines = ["flowchart TD"]
+        has_edges: set[str] = set()
+
+        for node in dag.nodes:
+            for dep in node.depends_on:
+                lines.append(f"    {dep} --> {node.step_name}")
+                has_edges.add(dep)
+                has_edges.add(node.step_name)
+
+        # Isolated nodes (neither source nor target of any edge) need explicit declaration.
+        for node in dag.nodes:
+            if node.step_name not in has_edges:
+                lines.append(f"    {node.step_name}")
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Orchestration
+    # ------------------------------------------------------------------
+
+    def _combine_code(self, steps: list[CodeOutput]) -> CodeOutput:
+        """Combine a sequence of per-step code outputs into one.
+
+        Default implementation: concatenates ``SQLOutput`` payloads.
+        Generators that produce :class:`~featkit.generators.output.PySparkOutput`
+        should override :meth:`generate` instead.
+        """
+        sql_steps = [s for s in steps if isinstance(s, SQLOutput) and s.sql]
+        pyspark_steps = [s for s in steps if isinstance(s, PySparkOutput) and s.code]
+
+        if sql_steps and pyspark_steps:
+            msg = (
+                "Mixed non-empty code output types are not supported in "
+                "_combine_code(); found both SQLOutput and PySparkOutput."
+            )
+            raise ValueError(msg)
+
+        if sql_steps:
+            dialects = {s.dialect for s in sql_steps}
+            if len(dialects) > 1:
+                msg = (
+                    f"Mixed SQLOutput dialects are not supported in _combine_code(); "
+                    f"found dialects: {dialects}."
+                )
+                raise ValueError(msg)
+            return SQLOutput(
+                sql="\n\n".join(s.sql for s in sql_steps),
+                dialect=sql_steps[0].dialect,
+            )
+        if pyspark_steps:
+            return PySparkOutput(code="\n\n".join(s.code for s in pyspark_steps))
+        # All steps were empty SQLOutputs — return an empty one.
+        if any(isinstance(s, SQLOutput) for s in steps):
+            return SQLOutput(
+                sql="", dialect=next(s.dialect for s in steps if isinstance(s, SQLOutput))
+            )
+        return PySparkOutput()
+
+    def generate(self, pipeline: FeatureStorePipeline) -> FeatureStoreOutput:
+        """Orchestrate all build steps and return the complete output artefact."""
+        steps: list[CodeOutput] = [
+            self.build_mob_table(pipeline),
+            self.build_layer2a(pipeline),
+            self.build_layer2b(pipeline),
+            self.build_layer3(pipeline),
+            self.build_final_join(pipeline),
+        ]
+        code = self._combine_code(steps)
+        dag = self.build_dag(pipeline)
+        mermaid = self.build_mermaid(dag)
+        return FeatureStoreOutput(code=code, dag=dag, mermaid=mermaid)