Add unit-aware Param() field and with_units()/to_example() to meshly (#24)

* Add unit-aware parameter support with Param() and update README for installation instructions

* Bump version to 3.5.0-alpha in pyproject.toml

Author: afshawnlotfi

python/README.md

@@ -6,6 +6,9 @@ A Python library for efficient 3D mesh serialization using [meshoptimizer](https
 
 ```bash
 pip install meshly
+
+# With unit conversion support (pint)
+pip install meshly[units]
 ```
 
 ## Features
@@ -15,6 +18,7 @@ pip install meshly
 - **`Packable`**: Base class for automatic numpy/JAX array serialization to zip files
 - **`Mesh`**: 3D mesh representation extending Packable with meshoptimizer encoding. Use factory methods: `from_triangles()`, `from_polygons()`, `create()`
 - **`ArrayUtils`**: Utility class for extracting/reconstructing individual arrays
+- **`Param`**: Unit-aware parameter field for Pydantic models (drop-in replacement for `Field`)
 - **`PackableStore`**: File-based store for persistent storage with deduplication
 - **`LazyModel`**: Lazy proxy that defers asset loading until field access
 - **`Resource`**: Binary data reference that serializes by content checksum
@@ -28,6 +32,13 @@ pip install meshly
 - **`IndexSequence`**: Optimized encoding for mesh indices (1D array)
 - **`InlineArray`**: Array serialized as inline JSON list (no binary compression)
 
+### Unit-Aware Parameters
+
+- **`Param()`**: Drop-in replacement for `pydantic.Field()` that adds `units`, `shape`, and `example` metadata to the JSON schema
+- **`ParamInfo`**: `FieldInfo` subclass backing `Param()` — carries units/shape/example through Pydantic's schema generation
+- **`Packable.to_example()`**: Class method that builds an instance from `Param()` example/default values
+- **`Packable.with_units()`**: Returns a clone with numeric/array fields converted to `pint.Quantity` objects
+
 ### Key Capabilities
 
 - Automatic encoding/decoding of numpy array attributes via `Array`, `IndexSequence`, `InlineArray` type annotations
@@ -184,6 +195,54 @@ class OptimizedMesh(Packable):
 
 > **Note:** All dtypes are supported. Arrays with non-4-byte dtypes (e.g., `float16`, `int8`, `uint8`) are automatically padded to 4-byte alignment during encoding and unpadded during decoding (meshoptimizer requirement). For best performance, prefer 4-byte aligned dtypes like `float32`, `int32`, or `float64`.
 
+### Unit-Aware Parameters with Param()
+
+`Param()` is a drop-in replacement for `pydantic.Field()` that adds units, shape, and example metadata to the JSON schema. It works on any Pydantic `BaseModel` or `Packable` field, including `InlineArray`:
+
+```python
+from meshly import Packable, Param, InlineArray
+
+class Simulation(Packable):
+    velocity: InlineArray = Param(units="m/s", example=[30.0, 0, 0], shape=(3,),
+                                  description="Flow velocity vector [vx, vy, vz]")
+    temperature: float = Param(300.0, units="K", description="Fluid temperature")
+    pressure: float = Param(101325.0, units="Pa", description="Outlet pressure")
+    name: str = Param("default", units="dimensionless", description="Simulation name")
+
+# Units appear in the JSON schema
+schema = Simulation.model_json_schema()
+print(schema["properties"]["temperature"])
+# {'default': 300.0, 'description': 'Fluid temperature', 'title': 'Temperature',
+#  'type': 'number', 'units': 'K'}
+
+# Create from example values
+sim = Simulation.to_example()
+print(sim.velocity)     # [30.  0.  0.]
+print(sim.temperature)  # 300.0
+
+# Convert to pint Quantities (requires `pip install meshly[units]`)
+sim_units = sim.with_units()
+print(sim_units.velocity)                # [30.0 0.0 0.0] meter / second
+print(sim_units.velocity.to("km/h"))     # [108.0 0.0 0.0] kilometer / hour
+print(sim_units.temperature.to("degC"))  # 26.85 degree_Celsius
+
+# Convert to SI base units
+sim_base = sim.with_units(base_units=True)
+print(sim_base.pressure)  # 101325.0 kilogram / meter / second ** 2
+```
+
+`Param()` requires either a default value or an `example`:
+```python
+# With default
+velocity: float = Param(10.0, units="m/s")
+
+# With example (no default, field is required)
+velocity: float = Param(units="m/s", example=10.0)
+
+# Error: neither default nor example
+velocity: float = Param(units="m/s")  # ValueError!
+```
+
 ### Dict of Pydantic BaseModel Objects
 
 You can also use dictionaries containing Pydantic `BaseModel` instances with numpy arrays:
@@ -645,6 +704,34 @@ class MyData(Packable):
     color: InlineArray            # Small arrays as inline JSON (no $ref)
 ```
 
+### Param
+
+```python
+def Param(
+    default: Any = ...,
+    *,
+    units: str,                    # Required: unit string (e.g., "m/s", "Pa", "dimensionless")
+    shape: tuple[int, ...] = None, # Optional: expected array shape
+    example: Any = None,           # Optional: example value for to_example()
+    description: str = None,       # Optional: field description
+    # ... all other pydantic.Field kwargs supported (gt, ge, lt, le, etc.)
+) -> ParamInfo
+```
+
+### ParamInfo
+
+```python
+class ParamInfo(FieldInfo):
+    """FieldInfo subclass that adds units, shape, and example to the JSON schema.
+    
+    Works on any Pydantic BaseModel. When used with InlineArray, the units
+    are preserved in the JSON schema output via json_schema_extra.
+    """
+    units: str
+    shape: tuple[int, ...] | None
+    example: Any
+```
+
 ### ArrayUtils
 
 ```python
@@ -702,6 +789,11 @@ class Packable(BaseModel):
     # Array conversion
     def convert_to(self, array_type: ArrayType) -> T
 
+    # Param-aware helpers
+    @classmethod
+    def to_example(cls) -> T         # Build instance from Param() example/default values
+    def with_units(self, base_units: bool = False) -> T  # Clone with pint Quantities (requires pint)
+    
     # Extract/Encode (instance methods)
     def extract(self) -> ExtractedPackable  # Cached for efficiency
     def encode(self) -> bytes  # Calls extract() internally

python/examples/units_example.ipynb

@@ -0,0 +1,184 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Unit-Aware Parameters with `Param()`\n",
+    "\n",
+    "Demonstrates `Param()`, `to_example()`, `with_units()`, and automatic pint Quantity stripping using a single comprehensive model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from meshly import Packable, Param, InlineArray, Array\n",
+    "from pint import UnitRegistry\n",
+    "import numpy as np\n",
+    "\n",
+    "ureg = UnitRegistry()\n",
+    "\n",
+    "class Simulation(Packable):\n",
+    "    \"\"\"Covers all field types: float, InlineArray, Array, nested Packable.\"\"\"\n",
+    "    velocity: InlineArray = Param(units=\"m/s\", example=[30.0, 0, 0], shape=(3,), description=\"Inlet velocity\")\n",
+    "    temperature: float = Param(300.0, units=\"K\", description=\"Fluid temperature\")\n",
+    "    pressure: float = Param(101325.0, units=\"Pa\", description=\"Static pressure\")\n",
+    "    displacements: Array = Param(units=\"m\", example=np.zeros((4, 3), dtype=np.float32), shape=(None, 3), description=\"Nodal displacements\")\n",
+    "    label: str = Param(\"default\", units=\"dimensionless\", description=\"Run label\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "velocity: units=m/s\n",
+      "temperature: units=K\n",
+      "pressure: units=Pa\n",
+      "displacements: units=m\n"
+     ]
+    }
+   ],
+   "source": [
+    "import json\n",
+    "\n",
+    "# Units appear in the JSON schema (this is what MCP tools / UIs see)\n",
+    "schema = Simulation.model_json_schema()\n",
+    "for name in [\"velocity\", \"temperature\", \"pressure\", \"displacements\"]:\n",
+    "    props = schema[\"properties\"][name]\n",
+    "    print(f\"{name}: units={props.get('units')}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "velocity:      [30.  0.  0.]\n",
+      "temperature:   300.0\n",
+      "displacements: (4, 3)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# to_example() builds an instance from Param example/default values\n",
+    "sim = Simulation.to_example()\n",
+    "print(f\"velocity:      {sim.velocity}\")\n",
+    "print(f\"temperature:   {sim.temperature}\")\n",
+    "print(f\"displacements: {sim.displacements.shape}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "velocity:    [30.0 0.0 0.0] meter / second\n",
+      "to km/h:     [108.0 0.0 0.0] kilometer / hour\n",
+      "temperature: 300.0 kelvin\n",
+      "to Celsius:  26.850000000000023 degree_Celsius\n",
+      "pressure:    1.0 standard_atmosphere\n",
+      "displace mm: [[0.0 0.0 0.0] [0.0 0.0 0.0] [0.0 0.0 0.0] [0.0 0.0 0.0]] millimeter\n"
+     ]
+    }
+   ],
+   "source": [
+    "# with_units() converts fields to pint Quantities\n",
+    "su = sim.with_units()\n",
+    "print(f\"velocity:    {su.velocity}\")\n",
+    "print(f\"to km/h:     {su.velocity.to('km/h')}\")\n",
+    "print(f\"temperature: {su.temperature}\")\n",
+    "print(f\"to Celsius:  {su.temperature.to('degC')}\")\n",
+    "print(f\"pressure:    {su.pressure.to('atm')}\")\n",
+    "print(f\"displace mm: {su.displacements.to('mm')}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "velocity (m/s):      [30.  0.  0.] (ndarray)\n",
+      "temperature (K):     300.0 (float)\n",
+      "pressure (Pa):       101325.0 (float)\n",
+      "displacements (m):   [[0.001 0.    0.   ]] (ndarray)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Pass pint Quantities directly — auto-converted to declared units, stored as plain values\n",
+    "sim2 = Simulation(\n",
+    "    velocity=ureg.Quantity([108.0, 0, 0], \"km/h\"),\n",
+    "    temperature=ureg.Quantity(26.85, \"degC\"),\n",
+    "    pressure=ureg.Quantity(1.0, \"atm\"),\n",
+    "    displacements=ureg.Quantity(np.array([[1, 0, 0]], dtype=np.float32), \"mm\"),\n",
+    ")\n",
+    "print(f\"velocity (m/s):      {sim2.velocity} ({type(sim2.velocity).__name__})\")\n",
+    "print(f\"temperature (K):     {sim2.temperature} ({type(sim2.temperature).__name__})\")\n",
+    "print(f\"pressure (Pa):       {sim2.pressure} ({type(sim2.pressure).__name__})\")\n",
+    "print(f\"displacements (m):   {sim2.displacements} ({type(sim2.displacements).__name__})\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Expected error: Field 'value' on NoUnits received a pint Quantity with units 'meter / second', but no Param(units=...) is defined for this field. Either add Param(units=...) or pass a plain value.\n",
+      "dimensionless OK: 42.0\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Error: passing units to a field without Param raises TypeError\n",
+    "class NoUnits(Packable):\n",
+    "    value: float = 0.0\n",
+    "\n",
+    "try:\n",
+    "    NoUnits(value=ureg.Quantity(42.0, \"m/s\"))\n",
+    "except TypeError as e:\n",
+    "    print(f\"Expected error: {e}\")\n",
+    "\n",
+    "# Dimensionless quantities on non-Param fields are fine\n",
+    "m = NoUnits(value=ureg.Quantity(42.0, \"dimensionless\"))\n",
+    "print(f\"dimensionless OK: {m.value}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

python/meshly/__init__.py

@@ -23,6 +23,7 @@
     IndexSequence,
     InlineArray,
 )
+from meshly.param import Param, ParamInfo
 from meshly.cell_types import (
     CellType,
     CellTypeUtils,
@@ -53,6 +54,9 @@
     # Mesh classes
     "Mesh",
     "TMesh",
+    # Parameter metadata
+    "Param",
+    "ParamInfo",
     # Array types and utilities
     "Array",
     "InlineArray",

python/meshly/array.py

@@ -86,7 +86,11 @@ def __eq__(self, other):
 
 
 class _InlineArrayAnnotation:
-    """Pydantic annotation for arrays serialized as inline JSON lists."""
+    """Pydantic annotation for arrays serialized as inline JSON lists.
+
+    When the field is defined with Param(units=...), the units/shape/description
+    are preserved in the JSON schema output via json_schema_extra on the FieldInfo.
+    """
 
     def __get_pydantic_core_schema__(
         self, source_type: Any, handler: GetCoreSchemaHandler