ucon 0.5.2__py3-none-any.whl → 0.6.1__py3-none-any.whl

ucon/units.py

@@ -28,7 +28,18 @@ Notes
 The design allows for future extensibility: users can register their own units,
 systems, or aliases dynamically, without modifying the core definitions.
 """
-from ucon.core import Dimension, Unit, UnitSystem
+import re
+from typing import Dict, Tuple, Union
+
+from ucon.core import Dimension, Scale, Unit, UnitFactor, UnitProduct, UnitSystem
+
+
+class UnknownUnitError(Exception):
+    """Raised when a unit string cannot be resolved to a known unit."""
+
+    def __init__(self, name: str):
+        self.name = name
+        super().__init__(f"Unknown unit: {name!r}")
 
 
 none = Unit()
@@ -79,23 +90,23 @@ day = Unit(name='day', dimension=Dimension.time, aliases=('d',))
 
 # -- Imperial / US Customary Units -------------------------------------
 # Length
-foot = Unit(name='foot', dimension=Dimension.length, aliases=('ft',))
-inch = Unit(name='inch', dimension=Dimension.length, aliases=('in',))
-yard = Unit(name='yard', dimension=Dimension.length, aliases=('yd',))
-mile = Unit(name='mile', dimension=Dimension.length, aliases=('mi',))
+foot = Unit(name='foot', dimension=Dimension.length, aliases=('ft', 'feet'))
+inch = Unit(name='inch', dimension=Dimension.length, aliases=('in', 'inches'))
+yard = Unit(name='yard', dimension=Dimension.length, aliases=('yd', 'yards'))
+mile = Unit(name='mile', dimension=Dimension.length, aliases=('mi', 'miles'))
 
 # Mass
 pound = Unit(name='pound', dimension=Dimension.mass, aliases=('lb', 'lbs'))
-ounce = Unit(name='ounce', dimension=Dimension.mass, aliases=('oz',))
+ounce = Unit(name='ounce', dimension=Dimension.mass, aliases=('oz', 'ounces'))
 
 # Temperature
 fahrenheit = Unit(name='fahrenheit', dimension=Dimension.temperature, aliases=('°F', 'degF'))
 
 # Volume
-gallon = Unit(name='gallon', dimension=Dimension.volume, aliases=('gal',))
+gallon = Unit(name='gallon', dimension=Dimension.volume, aliases=('gal', 'gallons'))
 
 # Energy
-calorie = Unit(name='calorie', dimension=Dimension.energy, aliases=('cal',))
+calorie = Unit(name='calorie', dimension=Dimension.energy, aliases=('cal', 'calories'))
 btu = Unit(name='btu', dimension=Dimension.energy, aliases=('BTU',))
 
 # Power
@@ -103,14 +114,14 @@ horsepower = Unit(name='horsepower', dimension=Dimension.power, aliases=('hp',))
 
 # Pressure
 bar = Unit(name='bar', dimension=Dimension.pressure, aliases=('bar',))
-psi = Unit(name='psi', dimension=Dimension.pressure, aliases=('lbf/in²',))
+psi = Unit(name='psi', dimension=Dimension.pressure, aliases=('psi', 'lbf/in²'))
 atmosphere = Unit(name='atmosphere', dimension=Dimension.pressure, aliases=('atm',))
 # ----------------------------------------------------------------------
 
 
 # -- Information Units -------------------------------------------------
-bit = Unit(name='bit', dimension=Dimension.information, aliases=('b',))
-byte = Unit(name='byte', dimension=Dimension.information, aliases=('B',))
+bit = Unit(name='bit', dimension=Dimension.information, aliases=('b', 'bits'))
+byte = Unit(name='byte', dimension=Dimension.information, aliases=('B', 'bytes'))
 # ----------------------------------------------------------------------
 
 
@@ -129,12 +140,13 @@ square_degree = Unit(name='square_degree', dimension=Dimension.solid_angle, alia
 
 
 # -- Ratio Units -------------------------------------------------------
-ratio_one = Unit(name='one', dimension=Dimension.ratio, aliases=('1',))
+fraction = Unit(name='fraction', dimension=Dimension.ratio, aliases=('frac', '1'))
 percent = Unit(name='percent', dimension=Dimension.ratio, aliases=('%',))
 permille = Unit(name='permille', dimension=Dimension.ratio, aliases=('‰',))
 ppm = Unit(name='ppm', dimension=Dimension.ratio, aliases=())
 ppb = Unit(name='ppb', dimension=Dimension.ratio, aliases=())
 basis_point = Unit(name='basis_point', dimension=Dimension.ratio, aliases=('bp', 'bps'))
+nines = Unit(name='nines', dimension=Dimension.ratio, aliases=('9s',))
 # ----------------------------------------------------------------------
 
 
@@ -184,3 +196,240 @@ def have(name: str) -> bool:
             if any((alias or "").lower() == target for alias in getattr(val, "aliases", ())):
                 return True
     return False
+
+
+# -- Unit String Parsing Infrastructure ------------------------------------
+
+# Module-level registries (populated by _build_registry at module load)
+_UNIT_REGISTRY: Dict[str, Unit] = {}
+_UNIT_REGISTRY_CASE_SENSITIVE: Dict[str, Unit] = {}
+
+# Scale prefix mapping (shorthand -> Scale)
+# Sorted by length descending for greedy matching
+_SCALE_PREFIXES: Dict[str, Scale] = {
+    # Binary (IEC) - must come before single-char metric
+    'Gi': Scale.gibi,
+    'Mi': Scale.mebi,
+    'Ki': Scale.kibi,
+    # Metric (decimal) - multi-char first
+    'da': Scale.deca,
+    # Single-char metric
+    'P': Scale.peta,
+    'T': Scale.tera,
+    'G': Scale.giga,
+    'M': Scale.mega,
+    'k': Scale.kilo,
+    'h': Scale.hecto,
+    'd': Scale.deci,
+    'c': Scale.centi,
+    'm': Scale.milli,
+    'u': Scale.micro,  # ASCII alternative
+    'μ': Scale.micro,  # Unicode micro sign
+    'µ': Scale.micro,  # Unicode mu (common substitute)
+    'n': Scale.nano,
+    'p': Scale.pico,
+    'f': Scale.femto,
+}
+
+# Sorted by length descending for greedy prefix matching
+_SCALE_PREFIXES_SORTED = sorted(_SCALE_PREFIXES.keys(), key=len, reverse=True)
+
+# Unicode superscript translation table
+_SUPERSCRIPT_TO_DIGIT = str.maketrans('⁰¹²³⁴⁵⁶⁷⁸⁹⁻', '0123456789-')
+
+
+def _build_registry() -> None:
+    """
+    Populate the unit registry from module globals.
+
+    Called once at module load time. Builds both case-insensitive and
+    case-sensitive lookup tables.
+    """
+    for obj in globals().values():
+        if isinstance(obj, Unit) and obj.name:
+            # Case-insensitive registry (for lookups by name)
+            _UNIT_REGISTRY[obj.name.lower()] = obj
+            # Case-sensitive registry (for alias lookups like 'L' for liter)
+            _UNIT_REGISTRY_CASE_SENSITIVE[obj.name] = obj
+            for alias in obj.aliases:
+                if alias:
+                    _UNIT_REGISTRY[alias.lower()] = obj
+                    _UNIT_REGISTRY_CASE_SENSITIVE[alias] = obj
+
+
+def _parse_exponent(s: str) -> Tuple[str, float]:
+    """
+    Extract exponent from unit factor string.
+
+    Handles both formats:
+    - Unicode: 'm²' -> ('m', 2.0), 's⁻¹' -> ('s', -1.0)
+    - ASCII:  'm^2' -> ('m', 2.0), 's^-1' -> ('s', -1.0)
+
+    Returns:
+        Tuple of (base_unit_str, exponent) where exponent defaults to 1.0.
+    """
+    # Try ASCII caret notation first: "m^2", "s^-1"
+    if '^' in s:
+        base, exp_str = s.rsplit('^', 1)
+        try:
+            return base.strip(), float(exp_str)
+        except ValueError:
+            raise UnknownUnitError(s)
+
+    # Try Unicode superscripts: "m²", "s⁻¹"
+    match = re.search(r'[⁰¹²³⁴⁵⁶⁷⁸⁹⁻]+$', s)
+    if match:
+        base = s[:match.start()]
+        exp_str = match.group().translate(_SUPERSCRIPT_TO_DIGIT)
+        try:
+            return base, float(exp_str)
+        except ValueError:
+            raise UnknownUnitError(s)
+
+    # No exponent found
+    return s, 1.0
+
+
+def _lookup_factor(s: str) -> Tuple[Unit, Scale]:
+    """
+    Look up a single unit factor, handling scale prefixes.
+
+    Prioritizes prefix+unit interpretation over direct unit lookup.
+    This means "kg" returns (gram, Scale.kilo) rather than (kilogram, Scale.one).
+
+    Examples:
+    - 'meter' -> (meter, Scale.one)
+    - 'm' -> (meter, Scale.one)
+    - 'km' -> (meter, Scale.kilo)
+    - 'kg' -> (gram, Scale.kilo)
+    - 'mL' -> (liter, Scale.milli)
+
+    Returns:
+        Tuple of (unit, scale).
+
+    Raises:
+        UnknownUnitError: If the unit cannot be resolved.
+    """
+    # Try scale prefix + unit first (prioritize decomposition)
+    # Only case-sensitive matching for remainder (e.g., "fT" = femto-tesla, "ft" = foot)
+    for prefix in _SCALE_PREFIXES_SORTED:
+        if s.startswith(prefix) and len(s) > len(prefix):
+            remainder = s[len(prefix):]
+            if remainder in _UNIT_REGISTRY_CASE_SENSITIVE:
+                return _UNIT_REGISTRY_CASE_SENSITIVE[remainder], _SCALE_PREFIXES[prefix]
+
+    # Fall back to exact case-sensitive match (for aliases like 'L', 'B', 'm')
+    if s in _UNIT_REGISTRY_CASE_SENSITIVE:
+        return _UNIT_REGISTRY_CASE_SENSITIVE[s], Scale.one
+
+    # Fall back to case-insensitive match
+    s_lower = s.lower()
+    if s_lower in _UNIT_REGISTRY:
+        return _UNIT_REGISTRY[s_lower], Scale.one
+
+    raise UnknownUnitError(s)
+
+
+def _parse_composite(s: str) -> UnitProduct:
+    """
+    Parse composite unit string into UnitProduct.
+
+    Accepts both Unicode and ASCII notation:
+    - Unicode: 'm/s²', 'kg·m/s²', 'N·m'
+    - ASCII:  'm/s^2', 'kg*m/s^2', 'N*m'
+
+    Delimiters:
+    - Division: '/'
+    - Multiplication: '·' (Unicode) or '*' (ASCII)
+
+    Returns:
+        UnitProduct representing the parsed composite unit.
+    """
+    # Normalize multiplication operator
+    s = s.replace('*', '·')
+
+    # Split numerator and denominator
+    if '/' in s:
+        num_part, den_part = s.split('/', 1)
+    else:
+        num_part, den_part = s, ''
+
+    factors: Dict[UnitFactor, float] = {}
+
+    # Parse numerator factors
+    if num_part:
+        for factor_str in num_part.split('·'):
+            factor_str = factor_str.strip()
+            if not factor_str:
+                continue
+            base_str, exp = _parse_exponent(factor_str)
+            unit, scale = _lookup_factor(base_str)
+            uf = UnitFactor(unit, scale)
+            factors[uf] = factors.get(uf, 0) + exp
+
+    # Parse denominator factors (negative exponents)
+    if den_part:
+        for factor_str in den_part.split('·'):
+            factor_str = factor_str.strip()
+            if not factor_str:
+                continue
+            base_str, exp = _parse_exponent(factor_str)
+            unit, scale = _lookup_factor(base_str)
+            uf = UnitFactor(unit, scale)
+            factors[uf] = factors.get(uf, 0) - exp
+
+    return UnitProduct(factors)
+
+
+def get_unit_by_name(name: str) -> Union[Unit, UnitProduct]:
+    """
+    Look up a unit by name, alias, or shorthand.
+
+    Handles:
+    - Plain units: "meter", "m", "second", "s"
+    - Scaled units: "km", "mL", "kg"
+    - Composite units: "m/s", "kg*m/s^2", "N·m"
+    - Exponents: "m²", "m^2", "s⁻¹", "s^-1"
+
+    Args:
+        name: Unit string to parse.
+
+    Returns:
+        Unit for simple unscaled units, UnitProduct for scaled or composite.
+
+    Raises:
+        UnknownUnitError: If the unit cannot be resolved.
+
+    Examples:
+        >>> get_unit_by_name("meter")
+        <Unit m>
+        >>> get_unit_by_name("km")
+        <UnitProduct km>
+        >>> get_unit_by_name("m/s^2")
+        <UnitProduct m/s²>
+    """
+    if not name or not name.strip():
+        raise UnknownUnitError(name if name else "")
+
+    name = name.strip()
+
+    # Check for composite (has operators)
+    if '/' in name or '·' in name or '*' in name:
+        return _parse_composite(name)
+
+    # Check for exponent
+    base_str, exp = _parse_exponent(name)
+    if exp != 1.0:
+        unit, scale = _lookup_factor(base_str)
+        return UnitProduct({UnitFactor(unit, scale): exp})
+
+    # Simple unit or scaled unit
+    unit, scale = _lookup_factor(name)
+    if scale == Scale.one:
+        return unit
+    else:
+        return UnitProduct({UnitFactor(unit, scale): 1})
+
+
+# Build the registry at module load time
+_build_registry()

{ucon-0.5.2.dist-info → ucon-0.6.1.dist-info}/METADATA

@@ -1,18 +1,20 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.5.2
-Summary: a tool for dimensional analysis: a "Unit CONverter"
+Version: 0.6.1
+Summary: A tool for dimensional analysis: a 'Unit CONverter'
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
+Author-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>
 Maintainer: Emmanuel I. Obi
-Maintainer-email: withtwoemms@gmail.com
+Maintainer-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>
 License: Apache-2.0
+Project-URL: Homepage, https://github.com/withtwoemms/ucon
+Project-URL: Repository, https://github.com/withtwoemms/ucon
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Software Development :: Build Tools
-Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -21,19 +23,20 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=5.5; extra == "test"
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == "pydantic"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; python_version >= "3.10" and extra == "mcp"
 Dynamic: author
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
 Dynamic: home-page
-Dynamic: license
 Dynamic: license-file
 Dynamic: maintainer
-Dynamic: maintainer-email
-Dynamic: summary
 
 <table>
   <tr>
@@ -68,6 +71,7 @@ It combines **units**, **scales**, and **dimensions** into a composable algebra
 - Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - Pseudo-dimensions for angles, solid angles, and ratios with semantic isolation
 - Uncertainty propagation through arithmetic and conversions
+- Pydantic v2 integration for API validation and JSON serialization
 - A clean foundation for physics, chemistry, data modeling, and beyond
 
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -90,12 +94,13 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 | **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
 | **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
 | **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
-| **`Map`** hierarchy           | `ucon.maps`                             | Composable conversion morphisms: `LinearMap`, `AffineMap`, `ComposedMap`.                           | Defining conversion functions between units (e.g., meter→foot, celsius→kelvin).                                        |
+| **`Map`** hierarchy           | `ucon.maps`                             | Composable conversion morphisms: `LinearMap`, `AffineMap`, `LogMap`, `ExpMap`, `ComposedMap`.       | Defining conversion functions between units (e.g., meter→foot, celsius→kelvin, availability→nines).                    |
 | **`ConversionGraph`**         | `ucon.graph`                            | Registry of unit conversion edges with BFS path composition.                                        | Converting between units via `Number.to(target)`; managing default and custom graphs.                                  |
 | **`UnitSystem`**              | `ucon.core`                             | Named mapping from dimensions to base units (e.g., SI, Imperial).                                   | Defining coherent unit systems; grouping base units by dimension.                                                      |
 | **`BasisTransform`**          | `ucon.core`                             | Matrix-based transformation between dimensional exponent spaces.                                    | Converting between incompatible dimensional structures; exact arithmetic with `Fraction`.                              |
 | **`RebasedUnit`**             | `ucon.core`                             | A unit rebased to another system's dimension, preserving provenance.                                | Cross-basis conversions; tracking original unit through basis changes.                                                 |
 | **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI, imperial, information, and derived units).                    | Quick access to standard physical units (`units.meter`, `units.foot`, `units.byte`, etc.).                             |
+| **`pydantic` module**         | `ucon.pydantic`                         | Pydantic v2 integration with `Number` type for model validation and JSON serialization.             | Using `Number` in Pydantic models; API request/response validation; JSON round-trip serialization.                     |
 
 ### Under the Hood
 
@@ -142,35 +147,40 @@ Simple:
 pip install ucon
 ```
 
+With Pydantic v2 support:
+```bash
+pip install ucon[pydantic]
+```
+
 ## Usage
 
-This sort of dimensional analysis:
+### Quantities and Arithmetic
+
+Dimensional analysis like this:
 ```
  2 mL bromine | 3.119 g bromine
 --------------x-----------------  #=> 6.238 g bromine
       1       |  1 mL bromine
 ```
-becomes straightforward when you define a measurement:
+becomes straightforward:
 ```python
 from ucon import Number, Scale, units
 from ucon.quantity import Ratio
 
-# Two milliliters of bromine
 mL = Scale.milli * units.liter
 two_mL_bromine = Number(quantity=2, unit=mL)
 
-# Density of bromine: 3.119 g/mL
 bromine_density = Ratio(
     numerator=Number(unit=units.gram, quantity=3.119),
     denominator=Number(unit=mL),
 )
 
-# Multiply to find mass
 grams_bromine = bromine_density.evaluate() * two_mL_bromine
 print(grams_bromine)  # <6.238 g>
 ```
 
-Scale prefixes compose naturally:
+### Scale Prefixes
+
 ```python
 km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
 mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
@@ -178,12 +188,12 @@ mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
 print(km.shorthand)  # 'km'
 print(mg.shorthand)  # 'mg'
 
-# Scale arithmetic
 print(km.fold_scale())  # 1000.0
 print(mg.fold_scale())  # 0.001
 ```
 
-Units are callable for ergonomic quantity construction:
+### Callable Units and Conversion
+
 ```python
 from ucon import units, Scale
 
@@ -202,118 +212,122 @@ distance_mi = distance.to(units.mile)
 print(distance_mi)  # <3.107... mi>
 ```
 
-Dimensionless units have semantic isolation — angles, solid angles, and ratios are distinct:
+### Dimensionless Units
+
+Angles, solid angles, and ratios are semantically isolated:
 ```python
 import math
 from ucon import units
 
-# Angle conversions
 angle = units.radian(math.pi)
 print(angle.to(units.degree))  # <180.0 deg>
 
-# Ratio conversions
 ratio = units.percent(50)
 print(ratio.to(units.ppm))  # <500000.0 ppm>
 
 # Cross-family conversions are prevented
 units.radian(1).to(units.percent)  # raises ConversionNotFound
+
+# SRE "nines" for availability (99.999% = 5 nines)
+uptime = units.percent(99.999)
+print(uptime.to(units.nines))  # <5.0 nines>
 ```
 
-Uncertainty propagates through arithmetic and conversions:
+### Uncertainty Propagation
+
 ```python
 from ucon import units
 
-# Measurements with uncertainty
 length = units.meter(1.234, uncertainty=0.005)
 width = units.meter(0.567, uncertainty=0.003)
 
 print(length)  # <1.234 ± 0.005 m>
 
-# Uncertainty propagates through arithmetic (quadrature)
+# Propagates through arithmetic (quadrature)
 area = length * width
 print(area)  # <0.699678 ± 0.00424... m²>
 
-# Uncertainty propagates through conversion
+# Propagates through conversion
 length_ft = length.to(units.foot)
 print(length_ft)  # <4.048... ± 0.0164... ft>
 ```
 
-Unit systems and basis transforms enable conversions between incompatible dimensional structures.
-This goes beyond simple unit conversion (meter → foot) into structural transformation:
+### Pydantic Integration
 
 ```python
-from fractions import Fraction
-from ucon import BasisTransform, Dimension, Unit, UnitSystem, units
-from ucon.graph import ConversionGraph
-from ucon.maps import LinearMap
-
-# The realm of Valdris has three fundamental dimensions:
-#   - Aether (A): magical energy substrate
-#   - Resonance (R): vibrational frequency of magic
-#   - Substance (S): physical matter
-#
-# These combine into SI dimensions via a transformation matrix:
-#
-#   | L |   | 2  0  0 |   | A |
-#   | M | = | 1  0  1 | × | R |
-#   | T |   |-2 -1  0 |   | S |
-#
-# Reading the columns:
-#   - 1 aether contributes: L², M, T⁻²  (energy-like)
-#   - 1 resonance contributes: T⁻¹      (frequency-like)
-#   - 1 substance contributes: M         (mass-like)
-
-# Fantasy base units
-mote = Unit(name='mote', dimension=Dimension.energy, aliases=('mt',))
-chime = Unit(name='chime', dimension=Dimension.frequency, aliases=('ch',))
-ite = Unit(name='ite', dimension=Dimension.mass, aliases=('it',))
-
-valdris = UnitSystem(
-    name="Valdris",
-    bases={
-        Dimension.energy: mote,
-        Dimension.frequency: chime,
-        Dimension.mass: ite,
-    }
-)
+from pydantic import BaseModel
+from ucon.pydantic import Number
+from ucon import units
 
-# The basis transform encodes how Valdris dimensions compose into SI
-valdris_to_si = BasisTransform(
-    src=valdris,
-    dst=units.si,
-    src_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
-    dst_dimensions=(Dimension.energy, Dimension.frequency, Dimension.mass),
-    matrix=(
-        (2, 0, 0),    # energy: 2 × aether
-        (1, 0, 1),    # frequency: aether + substance
-        (-2, -1, 0),  # mass: -2×aether - resonance
-    ),
-)
+class Measurement(BaseModel):
+    value: Number
 
-# Physical calibration: how many SI units per fantasy unit
-graph = ConversionGraph()
-graph.connect_systems(
-    basis_transform=valdris_to_si,
-    edges={
-        (mote, units.joule): LinearMap(42),           # 1 mote = 42 J
-        (chime, units.hertz): LinearMap(7),           # 1 chime = 7 Hz
-        (ite, units.kilogram): LinearMap(Fraction(1, 2)),  # 1 ite = 0.5 kg
-    }
-)
+# From JSON/dict input
+m = Measurement(value={"quantity": 5, "unit": "km"})
+print(m.value)  # <5 km>
 
-# Game engine converts between physics systems
-energy_map = graph.convert(src=mote, dst=units.joule)
-energy_map(10)  # 420 joules from 10 motes
+# From Number instance
+m2 = Measurement(value=units.meter(10))
 
-# Inverse: display real-world values in game units
-joule_to_mote = graph.convert(src=units.joule, dst=mote)
-joule_to_mote(420)  # 10 motes
+# Serialize to JSON
+print(m.model_dump_json())
+# {"value": {"quantity": 5.0, "unit": "km", "uncertainty": null}}
 
-# The transform is invertible with exact Fraction arithmetic
-valdris_to_si.is_invertible  # True
+# Supports both Unicode and ASCII unit notation
+m3 = Measurement(value={"quantity": 9.8, "unit": "m/s^2"})  # ASCII
+m4 = Measurement(value={"quantity": 9.8, "unit": "m/s²"})   # Unicode
 ```
 
-This enables fantasy game physics, or any field where the dimensional structure differs from SI.
+**Design notes:**
+- **Serialization format**: Units serialize as human-readable shorthand strings (`"km"`, `"m/s^2"`) rather than structured dicts, aligning with how scientists express units.
+- **Parsing priority**: When parsing `"kg"`, ucon returns `Scale.kilo * gram` rather than looking up a `kilogram` Unit, ensuring consistent round-trip serialization and avoiding redundant unit definitions.
+
+### MCP Server
+
+ucon ships with an MCP server for AI agent integration (Claude Desktop, Claude Code, Cursor, etc.):
+
+```bash
+pip install ucon[mcp]
+```
+
+Configure in Claude Desktop (`claude_desktop_config.json`):
+
+**Via uvx (recommended, zero-install):**
+```json
+{
+  "mcpServers": {
+    "ucon": {
+      "command": "uvx",
+      "args": ["--from", "ucon[mcp]", "ucon-mcp"]
+    }
+  }
+}
+```
+
+**Local development:**
+```json
+{
+  "mcpServers": {
+    "ucon": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/ucon", "--extra", "mcp", "ucon-mcp"]
+    }
+  }
+}
+```
+
+Available tools:
+- `convert(value, from_unit, to_unit)` — Unit conversion with dimensional validation
+- `list_units(dimension?)` — Discover available units
+- `list_scales()` — List SI and binary prefixes
+- `check_dimensions(unit_a, unit_b)` — Check dimensional compatibility
+- `list_dimensions()` — List physical dimensions
+
+### Custom Unit Systems
+
+`BasisTransform` enables conversions between incompatible dimensional structures (e.g., fantasy game physics, CGS units, domain-specific systems).
+
+See full example: [docs/examples/basis-transform-fantasy-units.md](./docs/examples/basis-transform-fantasy-units.md)
 
 ---
 
@@ -326,7 +340,7 @@ This enables fantasy game physics, or any field where the dimensional structure
 | **0.5.0** | Dimensionless Units | Pseudo-dimensions for angle, solid angle, ratio | ✅ Complete |
 | **0.5.x** | Uncertainty | Propagation through arithmetic and conversions | ✅ Complete |
 | **0.5.x** | Unit Systems | `BasisTransform`, `UnitSystem`, cross-basis conversion | ✅ Complete |
-| **0.6.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.6.x** | Pydantic + MCP | API validation, AI agent integration | ✅ Complete |
 | **0.7.x** | NumPy Arrays | Vectorized conversion and arithmetic | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
@@ -336,14 +350,21 @@ See full roadmap: [ROADMAP.md](./ROADMAP.md)
 ## Contributing
 
 Contributions, issues, and pull requests are welcome!
-Ensure `nox` is installed.
+
+Set up your development environment:
+```bash
+make venv
+source .ucon-3.12/bin/activate
 ```
-pip install -r requirements.txt
+
+Run the test suite before committing:
+```bash
+make test
 ```
-Then run the full test suite (against all supported python versions) before committing:
 
+Run tests across all supported Python versions:
 ```bash
-nox -s test
+make test-all
 ```
 ---