mlschema 0.1.0__py3-none-any.whl

mlschema/core/util/dtypes.py

@@ -0,0 +1,8 @@
+@staticmethod
+def normalize_dtype(dtype) -> str:
+    """Normalize dtype to string representation."""
+    return (
+        str(dtype)
+        if not hasattr(dtype, "name") or getattr(dtype, "names", None) is not None
+        else dtype.name
+    )

mlschema/mls.py

@@ -0,0 +1,68 @@
+from typing import Any
+
+from pandas import DataFrame
+
+from mlschema.core.app import Service, Strategy
+
+
+class MLSchema:
+    """Facade that orchestrates strategy registration and schema generation.
+
+    The class wraps an internal :class:`mlschema.core.app.Service` instance and
+    surfaces a minimal, stable API for client code.  It is therefore the
+    canonical entry point when integrating **mlschema** into an application or
+    pipeline.
+
+    Attributes:
+        field_service: Internal service component that performs the heavy lifting (registry management and JSON payload generation).
+    """
+
+    def __init__(self) -> None:
+        self.field_service = Service()
+
+    def register(self, strategy: Strategy) -> None:
+        """Register a **new** strategy.
+
+        Args:
+            strategy: Instance of a concrete :class:`mlschema.core.app.Strategy`.
+
+        Raises:
+            StrategyNameAlreadyRegisteredError: If a strategy with the same name is already registered.
+            StrategyDtypeAlreadyRegisteredError: If a strategy with the same dtype is already registered.
+        """
+        self.field_service.register(strategy)
+
+    def unregister(self, strategy: Strategy) -> None:
+        """Remove a **previously registered** strategy.
+
+        Args:
+            strategy: Strategy instance to be removed from the registry.
+        """
+        self.field_service.unregister(strategy)
+
+    def update(self, strategy: Strategy) -> None:
+        """Replace an existing strategy **in-place**.
+
+        If either the ``type_name`` or any of the advertised ``dtypes``
+        already exist, they are overwritten with the supplied strategy.
+
+        Args:
+            strategy: Instance of `Strategy` to update.
+        """
+        self.field_service.update(strategy)
+
+    def build(self, df: DataFrame) -> dict[str, list[dict[str, Any]]]:
+        """Translate a DataFrame into a JSON-serialisable form schema
+
+        Args:
+            df: Source data whose columns will be analysed and mapped to field definitions.
+
+        Returns:
+            Dictionary with the schema information, where keys are field names
+
+        Raises:
+            EmptyDataFrameError: If the DataFrame is empty.
+            FallbackStrategyMissingError: If no fallback strategy is available for the DataFrame.
+            PydanticCustomError: If there are validation errors in the schema.
+        """
+        return self.field_service.build_schema(df)

mlschema/strategies/__init__.py

@@ -0,0 +1,41 @@
+"""Strategies sub-package for **MLSchema**
+
+This namespace aggregates the concrete `Strategy` implementations that map
+pandas dtypes to **validated JSON field definitions**.  All classes inherit from
+`mlschema.core.Strategy` and are **opt-in**, they become active only after an
+explicit `MLSchema.register()` call.
+
+Strategies Available:
+    | Class               | Description                                        |
+    |---------------------|----------------------------------------------------|
+    | BooleanStrategy     | Strategy for handling boolean data types.          |
+    | CategoryStrategy    | Strategy for handling categorical data types.      |
+    | DateStrategy        | Strategy for handling date and datetime data types.|
+    | NumberStrategy      | Strategy for handling numeric data types.          |
+    | TextStrategy        | Strategy for handling text and string data types.  |
+
+Design notes
+------------
+
+| Principle                 | Description                                                                                                                     |
+|---------------------------|-------------------------------------------------------------------------------------------------------------------------------- |
+| **Single-responsibility** | Each strategy handles *one* logical field type.                                                                                 |
+| **Pluggable**             | New strategies register via `MLSchema.register()`, replace via `MLSchema.update()`, and deregister via `MLSchema.unregister()`. |
+| **Declarative output**    | Strategies emit validated `BaseField` subclasses, ensuring schema integrity from ingestion to UI rendering.                     |
+"""
+
+from .app import (
+    BooleanStrategy,
+    CategoryStrategy,
+    DateStrategy,
+    NumberStrategy,
+    TextStrategy,
+)
+
+__all__ = [
+    "BooleanStrategy",
+    "DateStrategy",
+    "TextStrategy",
+    "NumberStrategy",
+    "CategoryStrategy",
+]

mlschema/strategies/app/__init__.py

@@ -0,0 +1,13 @@
+from .boolean_strategy import BooleanStrategy
+from .category_strategy import CategoryStrategy
+from .date_strategy import DateStrategy
+from .number_strategy import NumberStrategy
+from .text_strategy import TextStrategy
+
+__all__ = [
+    "BooleanStrategy",
+    "DateStrategy",
+    "TextStrategy",
+    "NumberStrategy",
+    "CategoryStrategy",
+]

mlschema/strategies/app/boolean_strategy.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from mlschema.core import Strategy
+from mlschema.strategies.domain import BooleanField, FieldTypes
+
+
+class BooleanStrategy(Strategy):
+    """Instance of Strategy for boolean fields.
+
+    Name:
+        `boolean`
+
+    Dtypes:
+        | Name     | Type              |
+        | -------- | ----------------- |
+        | bool     | `BooleanDtype`    |
+        | boolean  | `BooleanDtype`    |
+
+    Model Attributes:
+        | Name        | Type                 | Description                                |
+        | ----------- | -------------------- | ------------------------------------------ |
+        | type        | `Literal["boolean"]` | Fixed type for the strategy.               |
+        | value       | `bool | None`        | The current value of the field.            |
+
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            type_name=FieldTypes.BOOLEAN,
+            schema_cls=BooleanField,
+            dtypes=("bool", "boolean"),
+        )

mlschema/strategies/app/category_strategy.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from pandas import CategoricalDtype, Series
+
+from mlschema.core import Strategy
+from mlschema.strategies.domain import CategoryField, FieldTypes
+
+
+class CategoryStrategy(Strategy):
+    """Instance of Strategy for category fields.
+
+    Name:
+        `category`
+
+    Dtypes:
+        | Name     | Type              |
+        | -------- | ----------------- |
+        | category | `CategoricalDtype`|
+
+    Model Attributes:
+        | Name    | Type                  | Description                      |
+        | ------- | --------------------- | -------------------------------- |
+        | type    | `Literal["category"]` | Fixed type for the strategy.     |
+        | options | `list[str]`           | List of allowed categories.      |
+        | value   | `str | None`          | Current value of the field.      |
+
+    Model Restrictions:
+        | Description           | Error Type            | Error Message                                     |
+        | --------------------- | --------------------- | ------------------------------------------------- |
+        | `value` in `options`  | `PydanticCustomError` | `value {value} must be in options {options}`      |
+
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            type_name=FieldTypes.CATEGORY,
+            schema_cls=CategoryField,
+            dtypes=("category",),
+        )
+
+    def attributes_from_series(self, series: Series) -> dict:
+        """Derives the list of *options* from the series.
+
+        Args:
+            series: Pandas series with categorical values.
+
+        Returns:
+            Dictionary with the ``options`` key and the list of unique values.
+        """
+        if isinstance(series.dtype, CategoricalDtype):
+            options = list(series.cat.categories)
+        else:
+            options = list(series.dropna().unique())
+        return {"options": options}

mlschema/strategies/app/date_strategy.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from mlschema.core import Strategy
+from mlschema.strategies.domain import DateField, FieldTypes
+
+
+class DateStrategy(Strategy):
+    """Instance of Strategy for date fields.
+
+    Name:
+        `date`
+
+    Dtypes:
+        | Name           | Type                |
+        | -------------- | ------------------- |
+        | datetime64[ns] | `DatetimeTZDtype`   |
+        | datetime64     | `DatetimeDtype`     |
+
+    Model Attributes:
+        | Name        | Type                | Description                                |
+        | ----------- | ------------------- | ------------------------------------------ |
+        | type        | `Literal["date"]`   | Fixed type for the strategy.               |
+        | value       | `date | None`       | The current value of the field.            |
+        | min         | `date | None`       | Minimum allowed date.                      |
+        | max         | `date | None`       | Maximum allowed date.                      |
+        | step        | `PositiveInt`       | Increment in days.                         |
+
+    Model Restrictions:
+        | Description           | Error Type            | Error Message                                     |
+        | --------------------- | --------------------- | ------------------------------------------------- |
+        | `min` ≤ `max`         | `PydanticCustomError` | `min {min} must be ≤ max {max}`                   |
+        | `value` ≥ `min`       | `PydanticCustomError` | `value {value} must be ≥ min {min}`               |
+        | `value` ≤ `max`       | `PydanticCustomError` | `value {value} must be ≤ max {max}`               |
+
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            type_name=FieldTypes.DATE,
+            schema_cls=DateField,
+            dtypes=("datetime64[ns]", "datetime64"),
+        )

mlschema/strategies/app/number_strategy.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from pandas import Series, api
+
+from mlschema.core import Strategy
+from mlschema.strategies.domain import FieldTypes, NumberField
+
+
+class NumberStrategy(Strategy):
+    """Instance of Strategy for number fields.
+
+    Name:
+        `number`
+
+    Dtypes:
+        | Name     | Type              |
+        | -------- | ----------------- |
+        | int64    | `Int64Dtype`      |
+        | float64  | `Float64Dtype`    |
+        | int32    | `Int32Dtype`      |
+        | float32  | `Float32Dtype`    |
+
+    Model Attributes:
+        | Name        | Type                | Description                                |
+        | ----------- | ------------------- | ------------------------------------------ |
+        | type        | `Literal["number"]` | Fixed type for the strategy.               |
+        | value       | `int | float | None`| The current value of the field.            |
+        | step        | `float | int`       | Increment for numeric values.              |
+        | min         | `int | float | None`| Minimum allowed value.                     |
+        | max         | `int | float | None`| Maximum allowed value.                     |
+        | unit        | `str | None`        | Unit of measurement for the numeric value. |
+        | placeholder | `str | None`        | Placeholder text for the field.            |
+
+    Model Restrictions:
+        | Description           | Error Type            | Error Message                                     |
+        | --------------------- | --------------------- | ------------------------------------------------- |
+        | `min` ≤ `max`         | `PydanticCustomError` | `min {min} must be ≤ max {max}`                   |
+        | `value` ≥ `min`       | `PydanticCustomError` | `value {value} must be ≥ min {min}`               |
+        | `value` ≤ `max`       | `PydanticCustomError` | `value {value} must be ≤ max {max}`               |
+
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            type_name=FieldTypes.NUMBER,
+            schema_cls=NumberField,
+            dtypes=("int64", "float64", "int32", "float32"),
+        )
+
+    def attributes_from_series(self, series: Series) -> dict:
+        """Derives the ``step`` attribute from the ``dtype``.
+
+        Args:
+            series: Pandas series with numeric values.
+
+        Returns:
+            Dictionary with the ``step`` key.
+        """
+        # Default step: 0.1 for floats, 1 for integers
+        step = 0.1 if api.types.is_float_dtype(series.dtype) else 1
+        return {"step": step}

mlschema/strategies/app/text_strategy.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from mlschema.core import Strategy
+from mlschema.strategies.domain import FieldTypes, TextField
+
+
+class TextStrategy(Strategy):
+    """Instance of Strategy for text fields.
+
+    Name:
+        `text`
+
+    Dtypes:
+        | Name     | Type              |
+        | -------- | ----------------- |
+        | object   | `object`          |
+        | string   | `StringDtype`     |
+
+    Model Attributes:
+        | Name        | Type              | Description                                |
+        | ----------- | ----------------- | ------------------------------------------ |
+        | type        | `Literal["text"]` | Fixed type for the strategy.               |
+        | value       | `str | None`      | The current value of the field.            |
+        | placeholder | `str | None`      | Placeholder text for the field.            |
+        | min_length  | `int | None`      | Minimum length of the text.                |
+        | max_length  | `int | None`      | Maximum length of the text.                |
+        | pattern     | `str | None`      | Regular expression pattern for validation. |
+
+    Model Restrictions:
+        | Description                   | Error Type            | Error Message                                                 |
+        | ----------------------------- | --------------------- | ------------------------------------------------------------- |
+        | `min_length` ≤ `max_length`   | `PydanticCustomError` | `minLength {minLength} must be ≤ maxLength {maxLength}`       |
+        | `value` length ≥ `min_length` | `PydanticCustomError` | `value length {value_length} must be ≥ minLength {minLength}` |
+        | `value` length ≤ `max_length` | `PydanticCustomError` | `value length {value_length} must be ≤ maxLength {maxLength}` |
+
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            type_name=FieldTypes.TEXT,
+            schema_cls=TextField,
+            dtypes=("object", "string"),
+        )

mlschema/strategies/domain/__init__.py

@@ -0,0 +1,15 @@
+from .boolean_field import BooleanField
+from .category_field import CategoryField
+from .date_field import DateField
+from .field_types import FieldTypes
+from .number_field import NumberField
+from .text_field import TextField
+
+__all__ = [
+    "BooleanField",
+    "DateField",
+    "NumberField",
+    "CategoryField",
+    "TextField",
+    "FieldTypes",
+]

mlschema/strategies/domain/boolean_field.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from mlschema.core.domain import BaseField
+from mlschema.strategies.domain.field_types import FieldTypes
+
+
+class BooleanField(BaseField):
+    type: Literal[FieldTypes.BOOLEAN] = FieldTypes.BOOLEAN
+    value: bool | None = None

mlschema/strategies/domain/category_field.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import Field, model_validator
+from pydantic_core import PydanticCustomError
+
+from mlschema.core.domain import BaseField
+from mlschema.strategies.domain.field_types import FieldTypes
+
+
+class CategoryField(BaseField):
+    type: Literal[FieldTypes.CATEGORY] = FieldTypes.CATEGORY
+    value: str | None = None
+    options: Annotated[list[str], Field(min_length=1)]
+
+    @model_validator(mode="after")
+    def _check_value_in_options(self) -> CategoryField:
+        if self.value is not None and self.value not in self.options:
+            raise PydanticCustomError(
+                "value_error", "Value must match one of the allowed options"
+            )
+        return self

mlschema/strategies/domain/date_field.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from datetime import date
+from typing import Literal
+
+from pydantic import PositiveInt, model_validator
+from pydantic_core import PydanticCustomError
+
+from mlschema.core.domain import BaseField
+from mlschema.strategies.domain.field_types import FieldTypes
+
+
+class DateField(BaseField):
+    type: Literal[FieldTypes.DATE] = FieldTypes.DATE
+    value: date | None = None
+    min: date | None = None
+    max: date | None = None
+    step: PositiveInt = 1
+
+    @model_validator(mode="after")
+    def _check_dates(self) -> DateField:
+        if self.min and self.max and self.min > self.max:
+            raise PydanticCustomError(
+                "date_range_error",
+                "Minimum date must be earlier than or equal to maximum date",
+            )
+
+        if self.value:
+            if self.min and self.value < self.min:
+                raise PydanticCustomError(
+                    "date_min_error", "Date must be later than or equal to minimum date"
+                )
+            if self.max and self.value > self.max:
+                raise PydanticCustomError(
+                    "date_max_error",
+                    "Date must be earlier than or equal to maximum date",
+                )
+        return self

mlschema/strategies/domain/field_types.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class FieldTypes(str, Enum):
+    TEXT = "text"
+    NUMBER = "number"
+    BOOLEAN = "boolean"
+    CATEGORY = "category"
+    DATE = "date"

mlschema/strategies/domain/number_field.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import model_validator
+from pydantic_core import PydanticCustomError
+
+from mlschema.core.domain import BaseField
+from mlschema.strategies.domain.field_types import FieldTypes
+
+
+class NumberField(BaseField):
+    type: Literal[FieldTypes.NUMBER] = FieldTypes.NUMBER
+    min: float | None = None
+    max: float | None = None
+    step: float | None = 1
+    placeholder: str | None = None
+    value: float | None = None
+    unit: str | None = None
+
+    @model_validator(mode="after")
+    def _check_numeric_constraints(self) -> NumberField:
+        if self.min is not None and self.max is not None and self.min > self.max:
+            raise PydanticCustomError(
+                "min_max_constraint",
+                "min ({min}) must be ≤ max ({max})",
+                {"min": self.min, "max": self.max},
+            )
+
+        if self.value is not None:
+            if self.min is not None and self.value < self.min:
+                raise PydanticCustomError(
+                    "value_min_constraint",
+                    "value ({value}) must be ≥ min ({min})",
+                    {"value": self.value, "min": self.min},
+                )
+            if self.max is not None and self.value > self.max:
+                raise PydanticCustomError(
+                    "value_max_constraint",
+                    "value ({value}) must be ≤ max ({max})",
+                    {"value": self.value, "max": self.max},
+                )
+        return self

mlschema/strategies/domain/text_field.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+from pydantic_core import PydanticCustomError
+
+from mlschema.core.domain import BaseField
+from mlschema.strategies.domain.field_types import FieldTypes
+
+
+class TextField(BaseField):
+    type: Literal[FieldTypes.TEXT] = FieldTypes.TEXT
+    value: str | None = None
+    placeholder: str | None = None
+    minLength: int | None = None
+    maxLength: int | None = None
+    pattern: str | None = Field(
+        default=None,
+        description=(
+            "Regular expression in Python notation; Pydantic does not preserve "
+            "re.Pattern instances in JSON serialization."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _check_lengths(self) -> TextField:
+        if (
+            self.minLength is not None
+            and self.maxLength is not None
+            and self.minLength > self.maxLength
+        ):
+            raise PydanticCustomError(
+                "length_validation",
+                "minLength ({min_length}) must be ≤ maxLength ({max_length})",
+                {"min_length": self.minLength, "max_length": self.maxLength},
+            )
+
+        if (
+            self.value is not None
+            and self.minLength is not None
+            and len(self.value) < self.minLength
+        ):
+            raise PydanticCustomError(
+                "min_length_validation",
+                "value length ({value_length}) must be ≥ minLength ({min_length})",
+                {"value_length": len(self.value), "min_length": self.minLength},
+            )
+
+        if (
+            self.value is not None
+            and self.maxLength is not None
+            and len(self.value) > self.maxLength
+        ):
+            raise PydanticCustomError(
+                "max_length_validation",
+                "value length ({value_length}) must be ≤ maxLength ({max_length})",
+                {"value_length": len(self.value), "max_length": self.maxLength},
+            )
+
+        return self