mlschema 0.1.0__py3-none-any.whl

mlschema/__init__.py

@@ -0,0 +1,33 @@
+"""Production-grade orchestration for translating **pandas** DataFrames into
+validated JSON field schemas.
+
+The package exports a single façade—:class:`mlschema.MLSchema`
+(alias :pydata:`mlform.MLForm`) which wraps the internal *Service/Registry*
+subsystem.  Client code typically:
+
+1. **Registers** concrete field strategies.
+2. **Builds** a JSON-serialisable schema from a DataFrame.
+
+Public surface:
+    * `MLSchema`                 — canonical entry point
+    * `mlschema.core.Strategy`   — extension contract (advanced)
+    * `mlschema.core.BaseField`  — Pydantic base model (advanced)
+    * All runtime errors derive from `mlschema.core.MLSchemaError`.
+
+Example:
+    ```python
+    from mlschema import MLSchema
+    from mlschema.strategies import NumberStrategy
+    import pandas as pd
+
+    ms = MLSchema()
+    ms.register(NumberStrategy())
+
+    df = pd.DataFrame({"age": [22, 37, 29]})
+    schema = ms.build(df)
+    ```
+"""
+
+from .mls import MLSchema
+
+__all__ = ["MLSchema"]

mlschema/core/__init__.py

@@ -0,0 +1,33 @@
+"""Core abstractions and error contracts for **MLSchema**.
+
+This module defines the *extension surface* on which all custom behaviour
+is built.  Integrators subclass the abstractions below to introduce new data
+types or override default processing logic, and they trap the accompanying
+exceptions to maintain deterministic error handling across the pipeline.
+"""
+
+from mlschema.core.app import Strategy
+from mlschema.core.domain import BaseField
+from mlschema.core.exceptions import (
+    EmptyDataFrameError,
+    FallbackStrategyMissingError,
+    FieldRegistryError,
+    FieldServiceError,
+    InvalidValueError,
+    MLSchemaError,
+    StrategyDtypeAlreadyRegisteredError,
+    StrategyNameAlreadyRegisteredError,
+)
+
+__all__ = [
+    "Strategy",
+    "BaseField",
+    "MLSchemaError",
+    "InvalidValueError",
+    "FieldRegistryError",
+    "FieldServiceError",
+    "EmptyDataFrameError",
+    "FallbackStrategyMissingError",
+    "StrategyDtypeAlreadyRegisteredError",
+    "StrategyNameAlreadyRegisteredError",
+]

mlschema/core/app/__init__.py

@@ -0,0 +1,5 @@
+from .registry import Registry
+from .service import Service
+from .strategy import Strategy
+
+__all__ = ["Strategy", "Registry", "Service"]

mlschema/core/app/registry.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from numpy import dtype as np_dtype
+
+from mlschema.core.app.strategy import Strategy
+from mlschema.core.exceptions import (
+    StrategyDtypeAlreadyRegisteredError,
+    StrategyNameAlreadyRegisteredError,
+)
+from mlschema.core.util import normalize_dtype
+
+
+class Registry:
+    """Manages the lifecycle of registered *Strategy* instances."""
+
+    def __init__(self) -> None:
+        """Initialize empty internal containers.
+
+        The registry maintains two parallel indexes for efficient lookups:
+
+        * ``_by_name`` - Maps logical type names (e.g., "number") to Strategy instances
+        * ``_by_dtype`` - Maps normalized dtype names (e.g., "float64") to Strategy instances
+
+        Both structures are kept coherent in each registration, update, or
+        removal operation. The registry is not thread-safe by design (the
+        expected usage is write-once, read-many in inference processes).
+        """
+        self._by_name: dict[str, Strategy] = {}
+        self._by_dtype: dict[str, Strategy] = {}
+
+    def register(self, strategy: Strategy, *, overwrite: bool = False) -> None:
+        """Register a new strategy.
+
+        Args:
+            strategy: Instance of :class:`Strategy` to register.
+            overwrite: If True, an existing registration with the same type_name or dtype will be replaced instead of raising an exception.
+
+        Raises:
+            StrategyNameAlreadyRegisteredError: If a strategy already exists for that type_name and overwrite is False.
+            StrategyDtypeAlreadyRegisteredError: If a strategy already exists for any of its dtype and overwrite is False.
+        """
+        if not overwrite and strategy.type_name in self._by_name:
+            raise StrategyNameAlreadyRegisteredError(strategy.type_name)
+
+        normalized_keys = set(map(normalize_dtype, strategy.dtypes))
+
+        for key in normalized_keys:
+            if not overwrite and key in self._by_dtype:
+                raise StrategyDtypeAlreadyRegisteredError(key)
+
+        self._by_name[strategy.type_name] = strategy
+
+        for key in normalized_keys:
+            self._by_dtype[key] = strategy
+
+    def update(self, strategy: Strategy) -> None:
+        """Replace the existing strategy with the same ``type_name``.
+
+        Equivalent to calling :meth:`register` with ``overwrite=True``.
+
+        Args:
+            strategy: Instance of :class:`Strategy` to update.
+        """
+        self.register(strategy, overwrite=True)
+
+    def unregister(self, type_name: str) -> None:
+        """Remove a strategy from the registry.
+
+        Args:
+            type_name: The logical identifier of the strategy to remove.
+        """
+        strat = self._by_name.pop(type_name, None)
+        if strat is not None:
+            self._by_dtype = {k: v for k, v in self._by_dtype.items() if v is not strat}
+
+    def strategy_for_name(self, type_name: str) -> Strategy | None:
+        """Return the strategy associated with ``type_name`` or ``None``.
+
+        Args:
+            type_name: Logical identifier of the field type to look up.
+
+        Returns:
+            Strategy instance for the given type name, or None if not found.
+        """
+        return self._by_name.get(type_name)
+
+    def strategy_for_dtype(self, dtype: str | np_dtype) -> Strategy | None:
+        """Return the strategy capable of handling ``dtype`` or ``None``.
+
+        Args:
+            dtype: NumPy dtype string or dtype object to look up.
+
+        Returns:
+            Strategy instance that handles the given dtype, or None if not found.
+        """
+        return self._by_dtype.get(normalize_dtype(dtype))

mlschema/core/app/service.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from pandas import DataFrame, Series
+
+from mlschema.core.app.registry import Registry
+from mlschema.core.exceptions.service import (
+    EmptyDataFrameError,
+    FallbackStrategyMissingError,
+)
+from mlschema.core.util import normalize_dtype
+
+from .strategy import Strategy
+
+
+class Service:
+    """Translates a :class:`pandas.DataFrame` to the JSON spec consumed by the front-end.
+
+    The Service class acts as the main orchestrator for converting pandas DataFrame
+    structures into JSON schema payloads. It uses a registry-based strategy pattern
+    to handle different data types and their corresponding schema representations.
+
+    The service generates JSON payloads in the format:
+    {"inputs": [...], "outputs": [...]}
+
+    Attributes:
+        _registry: Internal registry that manages field strategies for different data types.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the Service with an empty Registry."""
+        self._registry = Registry()
+
+    def register(self, strategy: Strategy) -> None:
+        """Register a new field strategy.
+
+        Args:
+            strategy: Instance of :class:`Strategy` to register.
+
+        Raises:
+            StrategyNameAlreadyRegisteredError: If a strategy with the same type_name already exists.
+            StrategyDtypeAlreadyRegisteredError: If a strategy with the same dtype already exists.
+        """
+
+        self._registry.register(strategy)
+
+    def unregister(self, strategy: Strategy) -> None:
+        """Unregister a previously registered strategy.
+
+        Args:
+            strategy: Instance of :class:`Strategy` to unregister.
+        """
+        self._registry.unregister(strategy.type_name)
+
+    def update(self, strategy: Strategy) -> None:
+        """Update an already registered strategy.
+
+        If the strategy doesn't exist, it's registered as new.
+
+        Args:
+            strategy: Instance of :class:`Strategy` to update.
+        """
+        self._registry.update(strategy)
+
+    # ------------------------------------------------------------------ #
+    # Internal helpers                                                   #
+    # ------------------------------------------------------------------ #
+    def _field_payload(self, series: Series) -> dict:
+        """Generate the schema for a specific column.
+
+        If the series dtype is not associated with any strategy,
+        a fallback strategy under the ``type_name`` "text" is attempted.
+
+        Args:
+            series: Pandas series to inspect.
+
+        Returns:
+            Dictionary with the column schema.
+
+        Raises:
+            FallbackStrategyMissingError: If no fallback strategy exists.
+        """
+        dtype = normalize_dtype(series.dtype)
+        strat = self._registry.strategy_for_dtype(
+            dtype
+        ) or self._registry.strategy_for_name("text")
+        if strat is None:
+            raise FallbackStrategyMissingError(dtype)
+        return strat.build_dict(series)
+
+    # ------------------------------------------------------------------ #
+    # Public API                                                         #
+    # ------------------------------------------------------------------ #
+    def _schema_payload(self, df: DataFrame) -> list[dict]:
+        """Build the list of schemas for each column.
+
+        Args:
+            df: Source DataFrame.
+
+        Returns:
+            Ordered list of schemas.
+
+        Raises:
+            EmptyDataFrameError: If the DataFrame has no columns or is empty.
+        """
+        if df.columns.empty or df.empty:
+            raise EmptyDataFrameError(df)
+        return [self._field_payload(col) for _, col in df.items()]
+
+    def build_schema(self, df: DataFrame) -> dict[str, list[dict]]:
+        """Return the final payload ready for injection into the front-end.
+
+        Args:
+            df: Source DataFrame.
+
+        Returns:
+            JSON payload with the schema of each column.
+        """
+        return {"inputs": self._schema_payload(df), "outputs": []}

mlschema/core/app/strategy.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from numpy import dtype as np_dtype
+from pandas import Series
+
+from mlschema.core.domain import BaseField
+from mlschema.core.util import normalize_dtype
+
+
+class Strategy:
+    """
+    Abstract base class for all MLSchema field strategies.
+
+    Each concrete strategy maps a *single* pandas dtype (or group of dtypes) to a
+    validated JSON field specification. Strategies are **opt-in**: they influence
+    schema generation only after being registered via `MLSchema.register()`.
+
+    Usage contract:
+        * Do **not** mutate the incoming `Series`; treat it as read-only.
+        * Subclasses should override `attributes_from_series()` to emit extra
+        metadata, but must avoid the reserved keys: `"title"`, `"type"`,
+        `"required"`, `"description"`.
+        * Registration is idempotent—duplicate `type_name`'s must be replaced via
+        `MLSchema.update()`.
+    """
+
+    def __init__(
+        self,
+        *,
+        type_name: str,
+        schema_cls: type[BaseField],
+        dtypes: Sequence[str | np_dtype],
+    ) -> None:
+        """
+
+        Args:
+            type_name:  Identifier for the strategy type.
+            schema_cls: Pydantic class that models the field.
+            dtypes:     Sequence of ``dtype`` (instances or names) to which the strategy applies.
+        """
+        self._type_name: str = type_name
+        self._schema_cls: type[BaseField] = schema_cls
+        self._dtypes: tuple[str, ...] = tuple(
+            normalize_dtype(dtype) for dtype in dtypes
+        )
+
+    @property
+    def type_name(self) -> str:
+        """Identifier for the strategy type."""
+        return self._type_name
+
+    @property
+    def schema_cls(self) -> type[BaseField]:
+        """Pydantic class used to serialize the schema."""
+        return self._schema_cls
+
+    @property
+    def dtypes(self) -> tuple[str, ...]:
+        """Tuple of supported ``dtype`` names."""
+        return self._dtypes
+
+    def attributes_from_series(self, series: Series) -> dict:
+        """Calculate field-specific attributes.
+
+        This method can be overridden by subclasses to add
+        implementation-specific metadata to the schema.
+
+        Args:
+            series: Dataframe column to analyze.
+
+        Returns:
+            Dictionary with additional attributes; never includes the standard keys ``title``, ``type``, ``required``, ``description``.
+        """
+        return {}
+
+    def build_dict(self, series: Series) -> dict:
+        """Create the JSON representation of the schema.
+
+        Combines the standard attributes with those returned by `attributes_from_series` and serializes the result with the associated Pydantic class.
+
+        Args:
+            series: Dataframe column to analyze.
+
+        Returns:
+            JSON with the field schema.
+        """
+        base_attrs: dict = {
+            "title": series.name,
+            "required": not series.isna().any(),
+            "description": None,
+            "type": self.type_name,
+        }
+
+        # Incorporate implementation-specific attributes
+        base_attrs.update(self.attributes_from_series(series))
+
+        # Instantiate the Pydantic class and dump to JSON
+        return self._schema_cls(**base_attrs).model_dump(
+            mode="json",
+            exclude_unset=False,
+            exclude_none=True,
+        )

mlschema/core/domain/__init__.py

@@ -0,0 +1,3 @@
+from .base_field import BaseField
+
+__all__ = ["BaseField"]

mlschema/core/domain/base_field.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseField(BaseModel):
+    """Standard metadata present in **all** fields.
+
+    Extend this class to define custom field types.
+
+    Attributes:
+        title: Human-readable field identifier (1-100 characters).
+        description: Optional description (max. 500 characters).
+        required: True if the original column contains no null values.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=False)
+
+    title: Annotated[str, Field(min_length=1, max_length=100)]
+    description: Annotated[str | None, Field(max_length=500)] = None
+    required: bool = True

mlschema/core/exceptions/__init__.py

@@ -0,0 +1,22 @@
+from mlschema.core.exceptions._base import InvalidValueError, MLSchemaError
+from mlschema.core.exceptions.registry import (
+    FieldRegistryError,
+    StrategyDtypeAlreadyRegisteredError,
+    StrategyNameAlreadyRegisteredError,
+)
+from mlschema.core.exceptions.service import (
+    EmptyDataFrameError,
+    FallbackStrategyMissingError,
+    FieldServiceError,
+)
+
+__all__ = [
+    "MLSchemaError",
+    "InvalidValueError",
+    "FieldRegistryError",
+    "FieldServiceError",
+    "StrategyNameAlreadyRegisteredError",
+    "StrategyDtypeAlreadyRegisteredError",
+    "EmptyDataFrameError",
+    "FallbackStrategyMissingError",
+]

mlschema/core/exceptions/_base.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class MLSchemaError(Exception):
+    """Project-root for every **mlschema** runtime failure.
+
+    All domain-specific exceptions ultimately derive from this class,
+    enabling both narrow and broad interception patterns:
+
+    ```python
+    try:
+        schema = ms.build(df)
+    except MLSchemaError as exc:          # catch-all
+        logger.error("Schema failure: %s", exc, exc_info=True)
+        raise HTTPException(422, detail=str(exc)) from exc
+    ```
+
+    Attributes:
+        context: Optional, machine-friendly diagnostics (e.g., offending
+            `dtype`, column name, strategy ID).  Contents are *stable* only
+            for the public leaf exceptions; treat additional keys as
+            informational.
+    """
+
+    def __init__(
+        self, message: str | None = None, *, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(message or self.__class__.__name__)
+        self.context: dict[str, Any] | None = context
+
+
+class InvalidValueError(MLSchemaError, ValueError):
+    """Standard signal for configuration or user-input violations.
+
+    Raised when a supplied argument, configuration value, or runtime
+    artefact fails validation.  Subclasses narrow the scope to
+    specific domains (e.g., *registry* vs. *service* faults).
+
+    Args
+    ----
+    param: Logical argument name that triggered the failure
+        (``"dtype"``, ``"type_name"``, …).
+    value: Offending value already *normalised* by the caller.
+    message: Human-readable description.  If *None*, a neutral default is
+        auto-generated.
+    context: Arbitrary diagnostics for observability pipelines
+        (e.g., ``{"strategy": "NumberStrategy"}``).
+
+    Attributes:
+    param: Same as the *param* constructor argument.
+    value: Same as the *value* constructor argument.
+    context: Same as the *context* constructor argument.
+        Same as the *context* constructor argument.
+
+    Examples
+    --------
+    ```python
+    if dtype_key in registry:
+        raise InvalidValueError(
+            param="dtype",
+            value=dtype_key,
+            message=f"dtype {dtype_key!r} already mapped",
+            context={"registered_strategy": registry[dtype_key]},
+        )
+    ```
+    """
+
+    def __init__(
+        self,
+        param: str,
+        value: Any,
+        message: str | None = None,
+        *,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        self.param: str = param
+        self.value: Any = value
+        default = f'Invalid value for "{param}": {value!r}.'
+        super().__init__(message or default, context=context)

mlschema/core/exceptions/registry.py

@@ -0,0 +1,73 @@
+# mlschema/core/exceptions/registry.py
+from __future__ import annotations
+
+from typing import Any
+
+from mlschema.core.exceptions._base import InvalidValueError
+
+
+class FieldRegistryError(InvalidValueError):
+    """Domain-root for **registry-layer** validation failures.
+
+    Triggered when an operation on the strategy registry receives an
+    invalid, conflicting, or otherwise disallowed value.
+
+    Args:
+        param: Logical argument name that caused the fault
+        value: Offending value (already normalised by the caller).
+        message: Human-readable description.  If *None*, a neutral default is autogenerated.
+        context: Arbitrary diagnostics—module, strategy ID, etc.
+
+    Attributes:
+        param: Same as the *param* constructor argument.
+        value: Same as the *value* constructor argument.
+        context: Same as the *context* constructor argument.
+
+    Example
+    -------
+    ```python
+    if type_name in registry:
+        raise FieldRegistryError(
+            param="type_name",
+            value=type_name,
+            message=f"Strategy {type_name!r} already exists",
+            context={"existing_cls": registry[type_name]},
+        )
+    ```
+    """
+
+    def __init__(
+        self,
+        param: str,
+        value: Any,
+        message: str | None = None,
+        *,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        # build default fallback only if the caller omitted a custom message
+        default_msg = f"Registry received an invalid value for {param!r}: {value!r}."
+        super().__init__(param, value, message or default_msg, context=context)
+
+
+class StrategyNameAlreadyRegisteredError(FieldRegistryError):
+    """Conflict: two strategies contend for the same **type_name**."""
+
+    def __init__(self, type_name: str) -> None:
+        super().__init__(
+            param="type_name",
+            value=type_name,
+            message=f'Strategy for type_name "{type_name}" is already registered.',
+            context={"offender": type_name},
+        )
+
+
+class StrategyDtypeAlreadyRegisteredError(FieldRegistryError):
+    """Conflict: two strategies contend for the same **dtype** key."""
+
+    def __init__(self, dtype_key: str) -> None:
+        super().__init__(
+            param="dtype",
+            value=dtype_key,
+            message=f'Strategy for dtype "{dtype_key}" is already registered.',
+            context={"offender": dtype_key},
+        )

mlschema/core/exceptions/service.py

@@ -0,0 +1,81 @@
+# mlschema/core/exceptions/service.py
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import InvalidValueError
+
+
+class FieldServiceError(InvalidValueError):
+    """Domain-root for **service-layer** validation failures.
+
+    Triggered when runtime data or configuration supplied to the *Service*
+    component is missing, malformed, or otherwise unusable.
+
+    Args:
+        param: Logical argument name that caused the fault
+            (e.g., ``"dataframe"``, ``"dtype"``, ``"fallback_strategy"``).
+        value: Offending value—typically the incoming DataFrame, a dtype string,
+            or a strategy identifier.
+        message: Human-readable description.  If *None*, a neutral default is
+            autogenerated.
+        context: Arbitrary diagnostics for logs or metrics
+            (row/column counts, offending dtype, etc.).
+
+    Attributes:
+        param: Mirrors the *param* constructor argument.
+        value: Mirrors the *value* constructor argument.
+        context: Mirrors the *context* constructor argument.
+
+    Example
+    -------
+    ```python
+    if df.empty:
+        raise FieldServiceError(
+            param="dataframe",
+            value=df,
+            message="Input DataFrame is empty",
+            context={"rows": 0, "cols": 0},
+        )
+    ```
+    """
+
+    def __init__(
+        self,
+        param: str,
+        value: Any,
+        message: str | None = None,
+        *,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        default = f"Service received an invalid value for {param!r}: {value!r}."
+        super().__init__(param, value, message or default, context=context)
+
+
+class EmptyDataFrameError(FieldServiceError):
+    """Conflict: Service received a DataFrame with **zero** rows *or* columns."""
+
+    def __init__(self, df) -> None:
+        super().__init__(
+            param="dataframe",
+            value=df,
+            message="DataFrame contains no columns or rows.",
+            context={"rows": len(df.index), "cols": len(df.columns)},
+        )
+
+
+class FallbackStrategyMissingError(FieldServiceError):
+    """
+    Conflict: No registered strategy matches the column dtype, and the fallback ``"text"`` strategy is absent.
+    """
+
+    def __init__(self, dtype_str: str) -> None:
+        super().__init__(
+            param="dtype",
+            value=dtype_str,
+            message=(
+                f'No strategy registered for dtype "{dtype_str}"; attempted '
+                'fallback "text" but it is not available.'
+            ),
+            context={"dtype": dtype_str},
+        )

mlschema/core/util/__init__.py

@@ -0,0 +1,3 @@
+from mlschema.core.util.dtypes import normalize_dtype
+
+__all__ = ["normalize_dtype"]