mlschema 0.2.0__tar.gz → 0.2.1__tar.gz

{mlschema-0.2.0 → mlschema-0.2.1}/CONTRIBUTING.md

@@ -329,7 +329,7 @@ What actually happens
 ## Environment
 - OS: [OS independent]
 - Python version: [e.g., 3.14.0]
-- MLSchema version: [e.g., 0.2.0]
+- MLSchema version: [e.g., 0.2.1]
 - pandas version: [e.g., 3.0.3]
 
 ## Additional Context

{mlschema-0.2.0 → mlschema-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlschema
-Version: 0.2.0
+Version: 0.2.1
 Summary: Infer validated, frontend-ready field schemas from pandas DataFrames.
 Project-URL: Homepage, https://github.com/UlloaSP/mlschema
 Project-URL: Documentation, https://ulloasp.github.io/mlschema/
@@ -59,7 +59,7 @@ It pairs naturally with [mlform](https://github.com/UlloaSP/mlform), but the gen
 
 DataFrame columns already carry useful contract information: names, dtypes, categories, nullability, dates, numeric values, and structured pairs. MLSchema turns that information into a validated field list.
 
-Instead of maintaining separate form definitions beside the data pipeline, use `infer_schema(df)` as the baseline and refine only what is genuinely product-specific: labels, bounds, defaults, units, placeholders, UI hints, or custom field kinds.
+Instead of maintaining separate form definitions beside the data pipeline, use `infer_schema(df)` as the baseline and refine only what is genuinely product-specific: labels, bounds, defaults, units, placeholders, or custom field kinds.
 
 ```python id="54fwnz"
 import pandas as pd
@@ -83,24 +83,28 @@ schema = infer_schema(df)
   {
     "kind": "text",
     "label": "name",
-    "required": true
+    "required": true,
+    "mappedTo": "name"
   },
   {
     "kind": "number",
     "label": "score",
     "required": true,
+    "mappedTo": "score",
     "step": 0.1
   },
   {
     "kind": "category",
     "label": "role",
     "required": true,
+    "mappedTo": "role",
     "options": ["engineer", "scientist"]
   },
   {
     "kind": "boolean",
     "label": "active",
-    "required": true
+    "required": true,
+    "mappedTo": "active"
   }
 ]
 ```
@@ -108,7 +112,7 @@ schema = infer_schema(df)
 ## Key Features
 
 * Function-first API: `infer_schema(df)`.
-* Builtin inference for `text`, `number`, `category`, `boolean`, `date`, and two-axis `series` fields.
+* Builtin inference for `text`, `number`, `category`, `onehot-category`, `boolean`, `date`, and two-axis `series` fields.
 * Pydantic v2 validation before any schema is returned.
 * JSON-serialisable field-list output for frontend and service integration.
 * Field refinements through `overrides`.
@@ -141,7 +145,7 @@ poetry add mlschema
 Pin a version when reproducible environments matter:
 
 ```bash id="yrqcr7"
-uv add "mlschema==0.2.0"
+uv add "mlschema==0.2.1"
 ```
 
 ## Quick Start
@@ -178,24 +182,28 @@ There is no top-level envelope by default. MLSchema returns the contract directl
   {
     "kind": "text",
     "label": "customer",
-    "required": true
+    "required": true,
+    "mappedTo": "customer"
   },
   {
     "kind": "number",
     "label": "age",
     "required": true,
+    "mappedTo": "age",
     "step": 1
   },
   {
     "kind": "category",
     "label": "tier",
     "required": true,
+    "mappedTo": "tier",
     "options": ["free", "pro"]
   },
   {
     "kind": "date",
     "label": "created",
-    "required": true
+    "required": true,
+    "mappedTo": "created"
   }
 ]
 ```
@@ -215,14 +223,21 @@ Builtin kinds are enabled by default and resolved in a fixed order.
 
 | Kind       | Detection                                                    | Notes                                                                  |
 | ---------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| `series`   | Non-null cells are 2-element tuples, lists, or dictionaries. | Infers `field1` and `field2` recursively.                              |
-| `boolean`  | `bool`, `boolean`                                            | Emits a boolean field contract.                                        |
-| `category` | `category`                                                   | Emits `options` from categorical categories.                           |
-| `date`     | `datetime64[ns]`, `datetime64[us]`, `datetime64`             | Emits a date field contract.                                           |
-| `number`   | `int64`, `int32`, `float64`, `float32`                       | Emits `step: 1` for integer columns and `step: 0.1` for float columns. |
-| `text`     | fallback                                                     | Claims columns not handled by earlier kinds.                           |
+| `series`          | Non-null cells are 2-element tuples, lists, or dictionaries. | Infers `field1` and `field2` recursively.                              |
+| `onehot-category` | 0/1 columns grouped by `onehot_separator`.                   | Emits one category field with `options[].mappedTo`.                    |
+| `boolean`         | `bool`, `boolean`                                            | Emits a boolean field contract.                                        |
+| `category`        | `category`                                                   | Emits `options` from categorical categories.                           |
+| `date`            | `datetime64[ns]`, `datetime64[us]`, `datetime64`             | Emits a date field contract.                                           |
+| `number`          | `int64`, `int32`, `float64`, `float32`                       | Emits `step: 1` for integer columns and `step: 0.1` for float columns. |
+| `text`            | fallback                                                     | Claims columns not handled by earlier kinds.                           |
+
+The order matters. `series` runs before `text` because it detects pair-shaped object cells by content. `onehot-category` groups strict 0/1 named feature columns such as `color__red` and `color__blue`. Positional binary columns stay as ordinary fields with integer `mappedTo` targets. `text` runs last as the safe fallback.
+
+## Feature Mapping
+
+Normal fields always include `mappedTo`. Named DataFrame columns emit string targets matching the column name. Positional columns emit numeric targets and generated labels such as `feature_0`.
 
-The order matters. `series` runs before `text` because it detects pair-shaped object cells by content. `text` runs last as the safe fallback.
+`onehot-category` puts `mappedTo` on each option instead of the parent field. Options map like fields: strings for named feature columns, integers for positional inputs. The default one-hot separator is `"__"`.
 
 ## Series Columns
 
@@ -279,7 +294,7 @@ Nested series are rejected. Cardinality constraints such as `minPoints` and `max
 
 ## Refining Fields With Overrides
 
-Inference provides the structural baseline. Production interfaces often need clearer labels, ranges, defaults, units, placeholders, or UI metadata.
+Inference provides the structural baseline. Production interfaces often need clearer labels, ranges, defaults, units, or placeholders.
 
 ```python id="v9tboo"
 schema = infer_schema(
@@ -320,6 +335,7 @@ def money_builder(series: Series, ctx: FieldContext) -> dict | None:
         "kind": "number",
         "label": "Amount",
         "required": ctx.required,
+        "mappedTo": ctx.mappedTo,
         "step": 0.01,
         "unit": "EUR",
         "min": 0,
@@ -351,6 +367,7 @@ def duration_builder(series: Series, ctx: FieldContext) -> dict | None:
         "kind": "duration",
         "label": ctx.name,
         "required": ctx.required,
+        "mappedTo": ctx.mappedTo,
         "unit": "seconds",
         "minSeconds": int(series.min().total_seconds()),
         "maxSeconds": int(series.max().total_seconds()),

{mlschema-0.2.0 → mlschema-0.2.1}/README.md

@@ -15,7 +15,7 @@ It pairs naturally with [mlform](https://github.com/UlloaSP/mlform), but the gen
 
 DataFrame columns already carry useful contract information: names, dtypes, categories, nullability, dates, numeric values, and structured pairs. MLSchema turns that information into a validated field list.
 
-Instead of maintaining separate form definitions beside the data pipeline, use `infer_schema(df)` as the baseline and refine only what is genuinely product-specific: labels, bounds, defaults, units, placeholders, UI hints, or custom field kinds.
+Instead of maintaining separate form definitions beside the data pipeline, use `infer_schema(df)` as the baseline and refine only what is genuinely product-specific: labels, bounds, defaults, units, placeholders, or custom field kinds.
 
 ```python id="54fwnz"
 import pandas as pd
@@ -39,24 +39,28 @@ schema = infer_schema(df)
   {
     "kind": "text",
     "label": "name",
-    "required": true
+    "required": true,
+    "mappedTo": "name"
   },
   {
     "kind": "number",
     "label": "score",
     "required": true,
+    "mappedTo": "score",
     "step": 0.1
   },
   {
     "kind": "category",
     "label": "role",
     "required": true,
+    "mappedTo": "role",
     "options": ["engineer", "scientist"]
   },
   {
     "kind": "boolean",
     "label": "active",
-    "required": true
+    "required": true,
+    "mappedTo": "active"
   }
 ]
 ```
@@ -64,7 +68,7 @@ schema = infer_schema(df)
 ## Key Features
 
 * Function-first API: `infer_schema(df)`.
-* Builtin inference for `text`, `number`, `category`, `boolean`, `date`, and two-axis `series` fields.
+* Builtin inference for `text`, `number`, `category`, `onehot-category`, `boolean`, `date`, and two-axis `series` fields.
 * Pydantic v2 validation before any schema is returned.
 * JSON-serialisable field-list output for frontend and service integration.
 * Field refinements through `overrides`.
@@ -97,7 +101,7 @@ poetry add mlschema
 Pin a version when reproducible environments matter:
 
 ```bash id="yrqcr7"
-uv add "mlschema==0.2.0"
+uv add "mlschema==0.2.1"
 ```
 
 ## Quick Start
@@ -134,24 +138,28 @@ There is no top-level envelope by default. MLSchema returns the contract directl
   {
     "kind": "text",
     "label": "customer",
-    "required": true
+    "required": true,
+    "mappedTo": "customer"
   },
   {
     "kind": "number",
     "label": "age",
     "required": true,
+    "mappedTo": "age",
     "step": 1
   },
   {
     "kind": "category",
     "label": "tier",
     "required": true,
+    "mappedTo": "tier",
     "options": ["free", "pro"]
   },
   {
     "kind": "date",
     "label": "created",
-    "required": true
+    "required": true,
+    "mappedTo": "created"
   }
 ]
 ```
@@ -171,14 +179,21 @@ Builtin kinds are enabled by default and resolved in a fixed order.
 
 | Kind       | Detection                                                    | Notes                                                                  |
 | ---------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| `series`   | Non-null cells are 2-element tuples, lists, or dictionaries. | Infers `field1` and `field2` recursively.                              |
-| `boolean`  | `bool`, `boolean`                                            | Emits a boolean field contract.                                        |
-| `category` | `category`                                                   | Emits `options` from categorical categories.                           |
-| `date`     | `datetime64[ns]`, `datetime64[us]`, `datetime64`             | Emits a date field contract.                                           |
-| `number`   | `int64`, `int32`, `float64`, `float32`                       | Emits `step: 1` for integer columns and `step: 0.1` for float columns. |
-| `text`     | fallback                                                     | Claims columns not handled by earlier kinds.                           |
+| `series`          | Non-null cells are 2-element tuples, lists, or dictionaries. | Infers `field1` and `field2` recursively.                              |
+| `onehot-category` | 0/1 columns grouped by `onehot_separator`.                   | Emits one category field with `options[].mappedTo`.                    |
+| `boolean`         | `bool`, `boolean`                                            | Emits a boolean field contract.                                        |
+| `category`        | `category`                                                   | Emits `options` from categorical categories.                           |
+| `date`            | `datetime64[ns]`, `datetime64[us]`, `datetime64`             | Emits a date field contract.                                           |
+| `number`          | `int64`, `int32`, `float64`, `float32`                       | Emits `step: 1` for integer columns and `step: 0.1` for float columns. |
+| `text`            | fallback                                                     | Claims columns not handled by earlier kinds.                           |
+
+The order matters. `series` runs before `text` because it detects pair-shaped object cells by content. `onehot-category` groups strict 0/1 named feature columns such as `color__red` and `color__blue`. Positional binary columns stay as ordinary fields with integer `mappedTo` targets. `text` runs last as the safe fallback.
+
+## Feature Mapping
+
+Normal fields always include `mappedTo`. Named DataFrame columns emit string targets matching the column name. Positional columns emit numeric targets and generated labels such as `feature_0`.
 
-The order matters. `series` runs before `text` because it detects pair-shaped object cells by content. `text` runs last as the safe fallback.
+`onehot-category` puts `mappedTo` on each option instead of the parent field. Options map like fields: strings for named feature columns, integers for positional inputs. The default one-hot separator is `"__"`.
 
 ## Series Columns
 
@@ -235,7 +250,7 @@ Nested series are rejected. Cardinality constraints such as `minPoints` and `max
 
 ## Refining Fields With Overrides
 
-Inference provides the structural baseline. Production interfaces often need clearer labels, ranges, defaults, units, placeholders, or UI metadata.
+Inference provides the structural baseline. Production interfaces often need clearer labels, ranges, defaults, units, or placeholders.
 
 ```python id="v9tboo"
 schema = infer_schema(
@@ -276,6 +291,7 @@ def money_builder(series: Series, ctx: FieldContext) -> dict | None:
         "kind": "number",
         "label": "Amount",
         "required": ctx.required,
+        "mappedTo": ctx.mappedTo,
         "step": 0.01,
         "unit": "EUR",
         "min": 0,
@@ -307,6 +323,7 @@ def duration_builder(series: Series, ctx: FieldContext) -> dict | None:
         "kind": "duration",
         "label": ctx.name,
         "required": ctx.required,
+        "mappedTo": ctx.mappedTo,
         "unit": "seconds",
         "minSeconds": int(series.min().total_seconds()),
         "maxSeconds": int(series.max().total_seconds()),

{mlschema-0.2.0 → mlschema-0.2.1}/docs/changelog.md

@@ -8,6 +8,29 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 No unreleased changes documented yet.
 
+## [0.2.1] - 2026-06-18
+
+### Added
+
+* Added mandatory `mappedTo` output for normal fields.
+* Added `onehot-category` inference for named one-hot encoded feature columns.
+* Added `options[].mappedTo` targets for `onehot-category` options.
+* Added `onehot_separator` to `infer_schema()`; the default separator is `"__"` for `feature__value` columns.
+* Added positional-column fallback labels such as `feature_0`, `feature_1`, and integer `mappedTo` targets.
+
+### Changed
+
+* Changed named DataFrame columns to emit string `mappedTo` targets matching the column name.
+* Changed positional DataFrame columns to emit generated labels and zero-based integer `mappedTo` targets.
+* Changed one-hot grouping to require named encoded feature columns; positional binary columns now remain ordinary fields.
+* Updated README, usage docs, and schema-standard docs for the `mappedTo` and `onehot-category` contracts.
+
+### Fixed
+
+* Fixed schema mapping ambiguity between display labels and backend targets.
+* Fixed one-hot output so the parent field has no `mappedTo`; each option owns its backend target.
+* Fixed regression coverage for named feature mappings, positional mappings, custom one-hot separators, and positional binary columns.
+
 ## [0.2.0] - 2026-06-01
 
 `0.2.0` is a breaking release. MLSchema moves from the previous class-and-registry API to a smaller function-first API centred on `infer_schema(df)`. The schema output is now the field list itself, not a top-level object containing `fields`, `reports`, or `explanations`.

{mlschema-0.2.0 → mlschema-0.2.1}/docs/index.md

@@ -35,18 +35,21 @@ The result is a validated field list:
   {
     "kind": "text",
     "label": "name",
-    "required": true
+    "required": true,
+    "mappedTo": 0
   },
   {
     "kind": "number",
     "label": "score",
     "required": true,
+    "mappedTo": 1,
     "step": 0.1
   },
   {
     "kind": "boolean",
     "label": "active",
-    "required": true
+    "required": true,
+    "mappedTo": 2
   }
 ]
 ```
@@ -72,7 +75,7 @@ The library is useful when the goal is not to build a form manually, but to deri
 | **Frontend-ready contracts**  | Output is JSON-serialisable and designed to be consumed by UI libraries such as `mlform`.           |
 | **Safe defaults**             | Builtin kinds are enabled by default; no registry setup is required for common DataFrame workflows. |
 | **Controlled extension**      | Custom builders and custom kinds allow domain-specific behaviour without changing consumer code.    |
-| **Column-level refinement**   | Overrides provide final labels, bounds, defaults, placeholders, units, and UI metadata.             |
+| **Column-level refinement**   | Overrides provide final labels, bounds, defaults, placeholders, and units.                          |
 
 ---
 
@@ -112,20 +115,21 @@ MLSchema ships with builtin inference for the standard field types used in most
 
 | Kind       | Detection                                                    |
 | ---------- | ------------------------------------------------------------ |
-| `series`   | Non-null cells are 2-element tuples, lists, or dictionaries. |
-| `boolean`  | `bool`, `boolean`                                            |
-| `category` | `category`                                                   |
-| `date`     | `datetime64[ns]`, `datetime64[us]`, `datetime64`             |
-| `number`   | `int64`, `int32`, `float64`, `float32`                       |
-| `text`     | Fallback for columns not claimed by an earlier kind.         |
+| `series`          | Non-null cells are 2-element tuples, lists, or dictionaries. |
+| `onehot-category` | 0/1 columns grouped by `onehot_separator`.                   |
+| `boolean`         | `bool`, `boolean`                                            |
+| `category`        | `category`                                                   |
+| `date`            | `datetime64[ns]`, `datetime64[us]`, `datetime64`             |
+| `number`          | `int64`, `int32`, `float64`, `float32`                       |
+| `text`            | Fallback for columns not claimed by an earlier kind.         |
 
-The order matters. More specific detections run first, and `text` runs last as the safe fallback.
+The order matters. More specific detections run first, one-hot encoded columns such as `color__red` are grouped before ordinary numeric fields, and `text` runs last as the safe fallback.
 
 ---
 
 ## Refining Inferred Schemas
 
-Inference gives the structural baseline. Production interfaces usually need a more explicit product contract: clearer labels, minimum and maximum values, defaults, units, placeholders, descriptions, or UI hints.
+Inference gives the structural baseline. Production interfaces usually need a more explicit product contract: clearer labels, minimum and maximum values, defaults, units, placeholders, or descriptions.
 
 Use `overrides` for those final column-specific refinements.
 
@@ -164,6 +168,7 @@ def money_builder(series: Series, ctx: FieldContext) -> dict | None:
         "kind": "number",
         "label": "Amount",
         "required": ctx.required,
+        "mappedTo": ctx.mappedTo,
         "step": 0.01,
         "unit": "EUR",
         "min": 0,
@@ -195,6 +200,7 @@ def duration_builder(series: Series, ctx: FieldContext) -> dict | None:
         "kind": "duration",
         "label": ctx.name,
         "required": ctx.required,
+        "mappedTo": ctx.mappedTo,
         "unit": "seconds",
         "minSeconds": int(series.min().total_seconds()),
         "maxSeconds": int(series.max().total_seconds()),

{mlschema-0.2.0 → mlschema-0.2.1}/docs/installation.md

@@ -29,7 +29,7 @@ uv add mlschema
 Pin a specific version when the environment must be reproducible:
 
 ```bash
-uv add "mlschema==0.2.0"
+uv add "mlschema==0.2.1"
 ```
 
 `uv` updates the project dependency metadata and lockfile, so this is the preferred option for applications, libraries, and CI workflows that already use `uv`.
@@ -47,7 +47,7 @@ pip install mlschema
 Pinned installation:
 
 ```bash
-pip install "mlschema==0.2.0"
+pip install "mlschema==0.2.1"
 ```
 
 When working inside a Conda environment, use `pip` after activating the environment:
@@ -69,7 +69,7 @@ poetry add mlschema
 Pinned installation:
 
 ```bash
-poetry add "mlschema==0.2.0"
+poetry add "mlschema==0.2.1"
 ```
 
 ---
@@ -155,9 +155,9 @@ Expected shape:
 
 ```python
 [
-    {"kind": "text", "label": "name", "required": True},
-    {"kind": "number", "label": "score", "required": True, "step": 0.1},
-    {"kind": "boolean", "label": "active", "required": True},
+    {"kind": "text", "label": "name", "required": True, "mappedTo": 0},
+    {"kind": "number", "label": "score", "required": True, "mappedTo": 1, "step": 0.1},
+    {"kind": "boolean", "label": "active", "required": True, "mappedTo": 2},
 ]
 ```
 
@@ -214,7 +214,7 @@ Patch releases should be safe for compatible fixes. Minor releases may add suppo
 For production systems, pin a known version and upgrade deliberately:
 
 ```bash
-uv add "mlschema==0.2.0"
+uv add "mlschema==0.2.1"
 ```
 
 ---