mlschema 0.1.2__tar.gz → 0.1.4__tar.gz

{mlschema-0.1.2 → mlschema-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlschema
-Version: 0.1.2
+Version: 0.1.4
 Summary: Lightweight orchestration layer that turns pandas DataFrames into front-end-ready JSON schemas, engineered to pair seamlessly with [mlform](https://github.com/UlloaSP/mlform).
 Project-URL: Homepage, https://github.com/UlloaSP/mlschema
 Project-URL: Documentation, https://ulloasp.github.io/mlschema/
@@ -79,7 +79,7 @@ Description-Content-Type: text/markdown
 
 - Converts analytics data into stable JSON schemas in a few lines of code.
 - Keeps inference logic server-side; no external services or background workers required.
-- Ships with production-tested strategies for text, numeric, categorical, boolean, and temporal data.
+- Ships with production-tested strategies for text, numeric, categorical, boolean, temporal, and two-axis series data.
 - Designed for synchronous use alongside [mlform](https://ulloasp.github.io/mlform/), yet fully usable on its own.
 
 ## Key Features
@@ -111,7 +111,7 @@ Alternative package managers:
 - `conda install -c conda-forge mlschema`
 - `pipenv install mlschema`
 
-Pin a version (for example `mlschema==0.1.2`) when you need deterministic environments.
+Pin a version (for example `mlschema==0.1.3`) when you need deterministic environments.
 
 ## Quick Start
 
@@ -153,6 +153,50 @@ The payload is ready to serialise to JSON and inject into your UI or downstream
 
 `TextStrategy` acts as the default fallback. Make sure it is registered when you want unsupported columns to degrade gracefully.
 
+### Series columns
+
+Columns where each cell is a 2-element compound value (`(v1, v2)`, `[v1, v2]`, or `{"key1": v1, "key2": v2}`) are handled automatically by `SeriesStrategy`. Sub-field schemas are inferred from the element dtypes via the registered strategies:
+
+```python
+import pandas as pd
+from datetime import date
+from mlschema import MLSchema
+from mlschema.strategies import TextStrategy, NumberStrategy, DateStrategy, SeriesStrategy
+
+df = pd.DataFrame({
+    "sensor_id": pd.Categorical(["A", "B", "C"]),
+    "readings": [
+        (date(2024, 1, 1), 23.5),
+        (date(2024, 1, 2), 24.1),
+        (date(2024, 1, 3), 22.8),
+    ],
+})
+
+builder = MLSchema()
+builder.register(TextStrategy())
+builder.register(NumberStrategy())
+builder.register(DateStrategy())
+builder.register(SeriesStrategy())   # claims compound-cell columns automatically
+
+schema = builder.build(df)
+```
+
+```json
+{
+  "inputs": [
+    {"title": "sensor_id", "required": true, "type": "category", "options": ["A", "B", "C"]},
+    {
+      "title": "readings", "required": true, "type": "series",
+      "field1": {"title": "field1", "required": true, "type": "date", "step": 1},
+      "field2": {"title": "field2", "required": true, "type": "number", "step": 0.1}
+    }
+  ],
+  "outputs": []
+}
+```
+
+`min_points` and `max_points` can be set directly on `SeriesField` to document cardinality constraints; they are not inferred from data.
+
 ## How It Works
 
 1. **Registry orchestration** – `MLSchema` keeps an in-memory registry of field strategies, keyed by a logical `type_name` and one or more pandas dtypes.
@@ -164,14 +208,17 @@ The payload is ready to serialise to JSON and inject into your UI or downstream
 
 | Strategy class | `type` name | Supported pandas dtypes | Additional attributes |
 | -------------- | ----------- | ----------------------- | --------------------- |
-| `TextStrategy` | `text`      | `object`, `string`      | `minLength`, `maxLength`, `pattern`, `value`, `placeholder` |
-| `NumberStrategy` | `number`  | `int64`, `int32`, `float64`, `float32` | `min`, `max`, `step`, `value`, `unit`, `placeholder` |
-| `CategoryStrategy` | `category` | `category` | `options`, `value` |
-| `BooleanStrategy` | `boolean` | `bool`, `boolean` | `value` |
-| `DateStrategy` | `date` | `datetime64[ns]`, `datetime64` | `min`, `max`, `value`, `step` |
+| `TextStrategy` | `text`      | `object`, `string`      | `defaultValue` (from `BaseField`), `minLength`, `maxLength`, `pattern`, `placeholder` |
+| `NumberStrategy` | `number`  | `int64`, `int32`, `float64`, `float32` | `defaultValue` (from `BaseField`), `min`, `max`, `step`, `unit`, `placeholder` |
+| `CategoryStrategy` | `category` | `category` | `defaultValue` (from `BaseField`), `options` |
+| `BooleanStrategy` | `boolean` | `bool`, `boolean` | `defaultValue` (from `BaseField`) |
+| `DateStrategy` | `date` | `datetime64[ns]`, `datetime64` | `defaultValue` (from `BaseField`), `min`, `max`, `step` |
+| `SeriesStrategy` | `series` | content-based (2-element cells) | `field1`, `field2`, `min_points`, `max_points` |
 
 Register only the strategies you need. Duplicate registrations raise explicit errors; use `MLSchema.update()` to swap implementations at runtime.
 
+`SeriesStrategy` uses **content-based detection** instead of dtype matching — it automatically claims any `object` column whose cells are all 2-element tuples, lists, or dicts, and infers the sub-field schemas from the element dtypes via the registry.
+
 ## Extending MLSchema
 
 Create bespoke field types by pairing a custom Pydantic model with a strategy implementation:

{mlschema-0.1.2 → mlschema-0.1.4}/README.md

@@ -33,7 +33,7 @@
 
 - Converts analytics data into stable JSON schemas in a few lines of code.
 - Keeps inference logic server-side; no external services or background workers required.
-- Ships with production-tested strategies for text, numeric, categorical, boolean, and temporal data.
+- Ships with production-tested strategies for text, numeric, categorical, boolean, temporal, and two-axis series data.
 - Designed for synchronous use alongside [mlform](https://ulloasp.github.io/mlform/), yet fully usable on its own.
 
 ## Key Features
@@ -65,7 +65,7 @@ Alternative package managers:
 - `conda install -c conda-forge mlschema`
 - `pipenv install mlschema`
 
-Pin a version (for example `mlschema==0.1.2`) when you need deterministic environments.
+Pin a version (for example `mlschema==0.1.3`) when you need deterministic environments.
 
 ## Quick Start
 
@@ -107,6 +107,50 @@ The payload is ready to serialise to JSON and inject into your UI or downstream
 
 `TextStrategy` acts as the default fallback. Make sure it is registered when you want unsupported columns to degrade gracefully.
 
+### Series columns
+
+Columns where each cell is a 2-element compound value (`(v1, v2)`, `[v1, v2]`, or `{"key1": v1, "key2": v2}`) are handled automatically by `SeriesStrategy`. Sub-field schemas are inferred from the element dtypes via the registered strategies:
+
+```python
+import pandas as pd
+from datetime import date
+from mlschema import MLSchema
+from mlschema.strategies import TextStrategy, NumberStrategy, DateStrategy, SeriesStrategy
+
+df = pd.DataFrame({
+    "sensor_id": pd.Categorical(["A", "B", "C"]),
+    "readings": [
+        (date(2024, 1, 1), 23.5),
+        (date(2024, 1, 2), 24.1),
+        (date(2024, 1, 3), 22.8),
+    ],
+})
+
+builder = MLSchema()
+builder.register(TextStrategy())
+builder.register(NumberStrategy())
+builder.register(DateStrategy())
+builder.register(SeriesStrategy())   # claims compound-cell columns automatically
+
+schema = builder.build(df)
+```
+
+```json
+{
+  "inputs": [
+    {"title": "sensor_id", "required": true, "type": "category", "options": ["A", "B", "C"]},
+    {
+      "title": "readings", "required": true, "type": "series",
+      "field1": {"title": "field1", "required": true, "type": "date", "step": 1},
+      "field2": {"title": "field2", "required": true, "type": "number", "step": 0.1}
+    }
+  ],
+  "outputs": []
+}
+```
+
+`min_points` and `max_points` can be set directly on `SeriesField` to document cardinality constraints; they are not inferred from data.
+
 ## How It Works
 
 1. **Registry orchestration** – `MLSchema` keeps an in-memory registry of field strategies, keyed by a logical `type_name` and one or more pandas dtypes.
@@ -118,14 +162,17 @@ The payload is ready to serialise to JSON and inject into your UI or downstream
 
 | Strategy class | `type` name | Supported pandas dtypes | Additional attributes |
 | -------------- | ----------- | ----------------------- | --------------------- |
-| `TextStrategy` | `text`      | `object`, `string`      | `minLength`, `maxLength`, `pattern`, `value`, `placeholder` |
-| `NumberStrategy` | `number`  | `int64`, `int32`, `float64`, `float32` | `min`, `max`, `step`, `value`, `unit`, `placeholder` |
-| `CategoryStrategy` | `category` | `category` | `options`, `value` |
-| `BooleanStrategy` | `boolean` | `bool`, `boolean` | `value` |
-| `DateStrategy` | `date` | `datetime64[ns]`, `datetime64` | `min`, `max`, `value`, `step` |
+| `TextStrategy` | `text`      | `object`, `string`      | `defaultValue` (from `BaseField`), `minLength`, `maxLength`, `pattern`, `placeholder` |
+| `NumberStrategy` | `number`  | `int64`, `int32`, `float64`, `float32` | `defaultValue` (from `BaseField`), `min`, `max`, `step`, `unit`, `placeholder` |
+| `CategoryStrategy` | `category` | `category` | `defaultValue` (from `BaseField`), `options` |
+| `BooleanStrategy` | `boolean` | `bool`, `boolean` | `defaultValue` (from `BaseField`) |
+| `DateStrategy` | `date` | `datetime64[ns]`, `datetime64` | `defaultValue` (from `BaseField`), `min`, `max`, `step` |
+| `SeriesStrategy` | `series` | content-based (2-element cells) | `field1`, `field2`, `min_points`, `max_points` |
 
 Register only the strategies you need. Duplicate registrations raise explicit errors; use `MLSchema.update()` to swap implementations at runtime.
 
+`SeriesStrategy` uses **content-based detection** instead of dtype matching — it automatically claims any `object` column whose cells are all 2-element tuples, lists, or dicts, and infers the sub-field schemas from the element dtypes via the registry.
+
 ## Extending MLSchema
 
 Create bespoke field types by pairing a custom Pydantic model with a strategy implementation:

mlschema-0.1.4/docs/changelog.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to MLSchema 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).
+
+## [0.1.1] - 2025-10-08
+
+### Added
+
+- Initial release of MLSchema
+- Core `MLSchema` class with register, unregister, update, and build methods
+- Strategy pattern architecture for extensible field type handling
+- Built-in strategies:
+  - `NumberStrategy`: Handles int32, int64, float32, float64
+  - `TextStrategy`: Handles object and string types
+  - `BooleanStrategy`: Handles bool and boolean types
+  - `DateStrategy`: Handles datetime64[ns] types
+  - `CategoryStrategy`: Handles categorical types
+- Pydantic-based schema validation
+- Comprehensive test suite (281 tests, 100% coverage)
+- Full type hints with Pyright strict mode
+- Documentation with MkDocs
+- Pre-commit hooks for code quality
+
+### Changed
+
+N/A
+
+### Deprecated
+
+N/A
+
+### Removed
+
+N/A
+
+### Fixed
+
+N/A
+
+### Security
+
+N/A
+
+---
+## [0.1.2] - 2025-10-29
+
+### Added
+
+- Open Software License Headers
+
+### Changed
+
+- Readme
+
+### Deprecated
+
+N/A
+
+### Removed
+
+N/A
+
+### Fixed
+
+N/A
+
+### Security
+
+N/A
+
+## [0.1.3] - 2026-04-16
+
+### Added
+
+- `SeriesStrategy`: content-based strategy for two-axis columns. Each cell must be a 2-element tuple, list, or dict. Sub-field schemas are auto-inferred from element dtypes via the registered strategy registry.
+- `SeriesField`: Pydantic model for series fields with `field1`, `field2`, `min_points`, and `max_points` attributes.
+  - `field1` / `field2` accept any registered sub-field type; nesting `SeriesField` inside itself is explicitly rejected.
+  - `min_points` / `max_points` enforce cardinality constraints (`PositiveInt`; `min_points ≤ max_points`).
+- `add_series_sub_field(cls)`: public helper to register custom `BaseField` subclasses as valid sub-fields inside `SeriesField`.
+- `content_probe(series)` hook on `Strategy` base class (default `False`). Strategies that override this are matched **before** dtype-based lookup, enabling non-dtype detection patterns.
+- `set_registry(registry)` hook on `Strategy` base class (no-op default). Called by `Service.register()` after registration. `SeriesStrategy` uses it to access the registry for sub-field dtype resolution.
+- `Registry.strategy_for_content(series)`: iterates registered strategies and returns the first whose `content_probe()` returns `True`.
+
+### Changed
+
+- `Service._field_payload()`: content-probe lookup now takes priority over dtype and fallback lookups.
+- `FieldTypes` enum: added `SERIES = "series"`.
+- `strategies` public API: `SeriesStrategy` and `add_series_sub_field` now exported at package level.
+
+### Fixed
+
+N/A
+
+### Security
+
+N/A
+
+---
+
+**Legend:**
+
+- 🎉 **Added**: New features
+- 🔄 **Changed**: Changes in existing functionality
+- 🗑️ **Deprecated**: Soon-to-be removed features
+- ❌ **Removed**: Now removed features
+- 🐛 **Fixed**: Bug fixes
+- 🔒 **Security**: Security improvements
+
+---
+
+**Last Updated**: April 16, 2026