ucon 0.5.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

ucon/graph.py

@@ -28,7 +28,15 @@ from contextvars import ContextVar
 from dataclasses import dataclass, field
 from typing import Union
 
-from ucon.core import Dimension, Unit, UnitFactor, UnitProduct, Scale
+from ucon.core import (
+    BasisTransform,
+    Dimension,
+    RebasedUnit,
+    Unit,
+    UnitFactor,
+    UnitProduct,
+    Scale,
+)
 from ucon.maps import Map, LinearMap, AffineMap
 
 
@@ -66,6 +74,9 @@ class ConversionGraph:
     # Edges between UnitProducts (keyed by frozen factor representation)
     _product_edges: dict[tuple, dict[tuple, Map]] = field(default_factory=dict)
 
+    # Rebased units: original unit → RebasedUnit (for cross-basis edges)
+    _rebased: dict[Unit, RebasedUnit] = field(default_factory=dict)
+
     # ------------- Edge Management -------------------------------------------
 
     def add_edge(
@@ -74,6 +85,7 @@ class ConversionGraph:
         src: Union[Unit, UnitProduct],
         dst: Union[Unit, UnitProduct],
         map: Map,
+        basis_transform: BasisTransform | None = None,
     ) -> None:
         """Register a conversion edge. Also registers the inverse.
 
@@ -85,15 +97,31 @@ class ConversionGraph:
             Destination unit expression.
         map : Map
             The conversion morphism (src → dst).
+        basis_transform : BasisTransform, optional
+            If provided, creates a cross-basis edge. The src unit is rebased
+            to the dst's dimension and the edge connects the rebased unit
+            to dst.
 
         Raises
         ------
         DimensionMismatch
-            If src and dst have different dimensions.
+            If src and dst have different dimensions (and no basis_transform).
         CyclicInconsistency
             If the reverse edge exists and round-trip is not identity.
         """
-        # Handle Unit vs UnitProduct dispatch
+        # Cross-basis edge with BasisTransform
+        if basis_transform is not None:
+            if isinstance(src, Unit) and not isinstance(src, UnitProduct):
+                if isinstance(dst, Unit) and not isinstance(dst, UnitProduct):
+                    self._add_cross_basis_edge(
+                        src=src,
+                        dst=dst,
+                        map=map,
+                        basis_transform=basis_transform,
+                    )
+                    return
+
+        # Handle Unit vs UnitProduct dispatch (normal case)
         if isinstance(src, Unit) and not isinstance(src, UnitProduct):
             if isinstance(dst, Unit) and not isinstance(dst, UnitProduct):
                 self._add_unit_edge(src=src, dst=dst, map=map)
@@ -142,6 +170,114 @@ class ConversionGraph:
         self._product_edges.setdefault(src_key, {})[dst_key] = map
         self._product_edges.setdefault(dst_key, {})[src_key] = map.inverse()
 
+    def _add_cross_basis_edge(
+        self,
+        *,
+        src: Unit,
+        dst: Unit,
+        map: Map,
+        basis_transform: BasisTransform,
+    ) -> None:
+        """Add cross-basis edge between Units via BasisTransform.
+
+        Creates a RebasedUnit for src in the destination's dimension partition,
+        then stores the edge from the rebased unit to dst.
+        """
+        # Validate that the transform maps src to dst's dimension
+        if not basis_transform.validate_edge(src, dst):
+            raise DimensionMismatch(
+                f"Transform {basis_transform.src.name} -> {basis_transform.dst.name} "
+                f"does not map {src.name} to {dst.name}'s dimension"
+            )
+
+        # Create RebasedUnit in destination's dimension partition
+        rebased = RebasedUnit(
+            original=src,
+            rebased_dimension=dst.dimension,
+            basis_transform=basis_transform,
+        )
+        self._rebased[src] = rebased
+
+        # Store edge from rebased to dst (same dimension now)
+        dim = dst.dimension
+        self._ensure_dimension(dim)
+        self._unit_edges[dim].setdefault(rebased, {})[dst] = map
+        self._unit_edges[dim].setdefault(dst, {})[rebased] = map.inverse()
+
+    def connect_systems(
+        self,
+        *,
+        basis_transform: BasisTransform,
+        edges: dict[tuple[Unit, Unit], Map],
+    ) -> None:
+        """Bulk-add edges between systems.
+
+        Parameters
+        ----------
+        basis_transform : BasisTransform
+            The transform bridging the two systems.
+        edges : dict
+            Mapping from (src_unit, dst_unit) to Map.
+        """
+        for (src, dst), edge_map in edges.items():
+            self.add_edge(
+                src=src,
+                dst=dst,
+                map=edge_map,
+                basis_transform=basis_transform,
+            )
+
+    def list_rebased_units(self) -> dict[Unit, RebasedUnit]:
+        """Return all rebased units in the graph.
+
+        Returns
+        -------
+        dict[Unit, RebasedUnit]
+            Mapping from original unit to its RebasedUnit.
+        """
+        return dict(self._rebased)
+
+    def list_transforms(self) -> list[BasisTransform]:
+        """Return all BasisTransforms active in the graph.
+
+        Returns
+        -------
+        list[BasisTransform]
+            Unique transforms used by rebased units.
+        """
+        seen = set()
+        result = []
+        for rebased in self._rebased.values():
+            bt = rebased.basis_transform
+            if id(bt) not in seen:
+                seen.add(id(bt))
+                result.append(bt)
+        return result
+
+    def edges_for_transform(self, transform: BasisTransform) -> list[tuple[Unit, Unit]]:
+        """Return all edges that use a specific BasisTransform.
+
+        Parameters
+        ----------
+        transform : BasisTransform
+            The transform to filter by.
+
+        Returns
+        -------
+        list[tuple[Unit, Unit]]
+            List of (original_unit, destination_unit) pairs.
+        """
+        result = []
+        for original, rebased in self._rebased.items():
+            if rebased.basis_transform == transform:
+                # Find the destination unit (the one the rebased unit connects to)
+                dim = rebased.dimension
+                if dim in self._unit_edges and rebased in self._unit_edges[dim]:
+                    for dst in self._unit_edges[dim][rebased]:
+                        if not isinstance(dst, RebasedUnit):
+                            result.append((original, dst))
+        return result
+
     def _ensure_dimension(self, dim: Dimension) -> None:
         if dim not in self._unit_edges:
             self._unit_edges[dim] = {}
@@ -206,10 +342,28 @@ class ConversionGraph:
         return self._convert_products(src=src_prod, dst=dst_prod)
 
     def _convert_units(self, *, src: Unit, dst: Unit) -> Map:
-        """Convert between plain Units via BFS."""
+        """Convert between plain Units via BFS.
+
+        Handles cross-basis conversions via rebased units.
+        """
         if src == dst:
             return LinearMap.identity()
 
+        # Check if src has a rebased version that can reach dst
+        if src in self._rebased:
+            rebased = self._rebased[src]
+            if rebased.dimension == dst.dimension:
+                # Convert via the rebased unit
+                return self._bfs_convert(start=rebased, target=dst, dim=dst.dimension)
+
+        # Check if dst has a rebased version (inverse conversion)
+        if dst in self._rebased:
+            rebased_dst = self._rebased[dst]
+            if rebased_dst.dimension == src.dimension:
+                # Convert from src to the rebased dst
+                return self._bfs_convert(start=src, target=rebased_dst, dim=src.dimension)
+
+        # Check for dimension mismatch
         if src.dimension != dst.dimension:
             raise DimensionMismatch(f"{src.dimension} != {dst.dimension}")
 
@@ -217,13 +371,16 @@ class ConversionGraph:
         if self._has_direct_unit_edge(src=src, dst=dst):
             return self._get_direct_unit_edge(src=src, dst=dst)
 
-        # BFS
-        dim = src.dimension
+        # BFS in same dimension
+        return self._bfs_convert(start=src, target=dst, dim=src.dimension)
+
+    def _bfs_convert(self, *, start, target, dim: Dimension) -> Map:
+        """BFS to find conversion path within a dimension."""
         if dim not in self._unit_edges:
             raise ConversionNotFound(f"No edges for dimension {dim}")
 
-        visited: dict[Unit, Map] = {src: LinearMap.identity()}
-        queue = deque([src])
+        visited: dict = {start: LinearMap.identity()}
+        queue = deque([start])
 
         while queue:
             current = queue.popleft()
@@ -239,12 +396,12 @@ class ConversionGraph:
                 composed = edge_map @ current_map
                 visited[neighbor] = composed
 
-                if neighbor == dst:
+                if neighbor == target:
                     return composed
 
                 queue.append(neighbor)
 
-        raise ConversionNotFound(f"No path from {src} to {dst}")
+        raise ConversionNotFound(f"No path from {start} to {target}")
 
     def _convert_products(self, *, src: UnitProduct, dst: UnitProduct) -> Map:
         """Convert between UnitProducts.

ucon/mcp/__init__.py

@@ -0,0 +1,8 @@
+# ucon MCP server
+#
+# Install: pip install ucon[mcp]
+# Run: ucon-mcp
+
+from ucon.mcp.server import main
+
+__all__ = ["main"]

ucon/mcp/server.py

@@ -0,0 +1,250 @@
+# ucon MCP Server
+#
+# Provides unit conversion and dimensional analysis tools for AI agents.
+#
+# Usage:
+#   ucon-mcp              # Run via entry point
+#   python -m ucon.mcp    # Run as module
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import BaseModel
+
+from ucon import Dimension, get_unit_by_name
+from ucon.core import Number, Scale, Unit, UnitProduct
+from ucon.units import UnknownUnitError
+
+
+mcp = FastMCP("ucon")
+
+
+# -----------------------------------------------------------------------------
+# Response Models
+# -----------------------------------------------------------------------------
+
+
+class ConversionResult(BaseModel):
+    """Result of a unit conversion."""
+
+    quantity: float
+    unit: str | None
+    dimension: str
+    uncertainty: float | None = None
+
+
+class UnitInfo(BaseModel):
+    """Information about an available unit."""
+
+    name: str
+    shorthand: str
+    aliases: list[str]
+    dimension: str
+    scalable: bool
+
+
+class ScaleInfo(BaseModel):
+    """Information about a scale prefix."""
+
+    name: str
+    prefix: str
+    factor: float
+
+
+class DimensionCheck(BaseModel):
+    """Result of a dimensional compatibility check."""
+
+    compatible: bool
+    dimension_a: str
+    dimension_b: str
+
+
+# -----------------------------------------------------------------------------
+# Tools
+# -----------------------------------------------------------------------------
+
+
+@mcp.tool()
+def convert(value: float, from_unit: str, to_unit: str) -> ConversionResult:
+    """
+    Convert a numeric value from one unit to another.
+
+    Units can be specified as:
+    - Base units: "meter", "m", "second", "s", "gram", "g"
+    - Scaled units: "km", "mL", "kg", "MHz" (use list_scales for prefixes)
+    - Composite units: "m/s", "kg*m/s^2", "N*m"
+    - Exponents: "m^2", "s^-1" (ASCII) or "m²", "s⁻¹" (Unicode)
+
+    Args:
+        value: The numeric quantity to convert.
+        from_unit: Source unit string.
+        to_unit: Target unit string.
+
+    Returns:
+        ConversionResult with converted quantity, unit, and dimension.
+
+    Raises:
+        UnknownUnitError: If a unit string cannot be parsed.
+        DimensionMismatch: If units have incompatible dimensions.
+    """
+    src = get_unit_by_name(from_unit)
+    dst = get_unit_by_name(to_unit)
+
+    num = Number(quantity=value, unit=src)
+    result = num.to(dst)
+
+    unit_str = None
+    dim_name = "none"
+
+    if result.unit:
+        if isinstance(result.unit, UnitProduct):
+            unit_str = result.unit.shorthand
+            dim_name = result.unit.dimension.name
+        elif isinstance(result.unit, Unit):
+            unit_str = result.unit.shorthand
+            dim_name = result.unit.dimension.name
+
+    return ConversionResult(
+        quantity=result.quantity,
+        unit=unit_str,
+        dimension=dim_name,
+        uncertainty=result.uncertainty,
+    )
+
+
+@mcp.tool()
+def list_units(dimension: str | None = None) -> list[UnitInfo]:
+    """
+    List available units, optionally filtered by dimension.
+
+    Returns base units only. Use scale prefixes (from list_scales) to form
+    scaled variants. For example, "meter" with prefix "k" becomes "km".
+
+    Args:
+        dimension: Optional filter by dimension name (e.g., "length", "mass", "time").
+                   Use list_dimensions() to see available dimensions.
+
+    Returns:
+        List of UnitInfo objects describing available units.
+    """
+    import ucon.units as units_module
+
+    # Units that accept SI scale prefixes
+    SCALABLE_UNITS = {
+        "meter", "gram", "second", "ampere", "kelvin", "mole", "candela",
+        "hertz", "newton", "pascal", "joule", "watt", "coulomb", "volt",
+        "farad", "ohm", "siemens", "weber", "tesla", "henry", "lumen",
+        "lux", "becquerel", "gray", "sievert", "katal",
+        "liter", "byte",
+    }
+
+    result = []
+    seen_names = set()
+
+    for name in dir(units_module):
+        obj = getattr(units_module, name)
+        if isinstance(obj, Unit) and obj.name and obj.name not in seen_names:
+            seen_names.add(obj.name)
+
+            if dimension and obj.dimension.name != dimension:
+                continue
+
+            result.append(
+                UnitInfo(
+                    name=obj.name,
+                    shorthand=obj.shorthand,
+                    aliases=list(obj.aliases) if obj.aliases else [],
+                    dimension=obj.dimension.name,
+                    scalable=obj.name in SCALABLE_UNITS,
+                )
+            )
+
+    return sorted(result, key=lambda u: (u.dimension, u.name))
+
+
+@mcp.tool()
+def list_scales() -> list[ScaleInfo]:
+    """
+    List available scale prefixes for units.
+
+    These prefixes can be combined with scalable units (see list_units).
+    For example, prefix "k" (kilo) with unit "m" (meter) forms "km".
+
+    Includes both SI decimal prefixes (kilo, mega, milli, micro, etc.)
+    and binary prefixes (kibi, mebi, gibi) for information units.
+
+    Note on bytes:
+    - SI prefixes: kB = 1000 B, MB = 1,000,000 B (decimal)
+    - Binary prefixes: KiB = 1024 B, MiB = 1,048,576 B (powers of 2)
+
+    Returns:
+        List of ScaleInfo objects with name, prefix symbol, and numeric factor.
+    """
+    result = []
+    for scale in Scale:
+        if scale == Scale.one:
+            continue  # Skip the identity scale
+        result.append(
+            ScaleInfo(
+                name=scale.name,
+                prefix=scale.shorthand,
+                factor=scale.descriptor.evaluated,
+            )
+        )
+    return sorted(result, key=lambda s: -s.factor)
+
+
+@mcp.tool()
+def check_dimensions(unit_a: str, unit_b: str) -> DimensionCheck:
+    """
+    Check if two units have compatible dimensions.
+
+    Units with the same dimension can be converted between each other.
+    Units with different dimensions cannot be added or directly compared.
+
+    Args:
+        unit_a: First unit string.
+        unit_b: Second unit string.
+
+    Returns:
+        DimensionCheck indicating compatibility and the dimension of each unit.
+    """
+    a = get_unit_by_name(unit_a)
+    b = get_unit_by_name(unit_b)
+
+    dim_a = a.dimension if isinstance(a, Unit) else a.dimension
+    dim_b = b.dimension if isinstance(b, Unit) else b.dimension
+
+    return DimensionCheck(
+        compatible=(dim_a == dim_b),
+        dimension_a=dim_a.name,
+        dimension_b=dim_b.name,
+    )
+
+
+@mcp.tool()
+def list_dimensions() -> list[str]:
+    """
+    List available physical dimensions.
+
+    Dimensions represent fundamental physical quantities (length, mass, time, etc.)
+    and derived quantities (velocity, force, energy, etc.).
+
+    Use these dimension names to filter list_units().
+
+    Returns:
+        List of dimension names.
+    """
+    return sorted([d.name for d in Dimension])
+
+
+# -----------------------------------------------------------------------------
+# Entry Point
+# -----------------------------------------------------------------------------
+
+
+def main():
+    """Run the ucon MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

ucon/pydantic.py

@@ -0,0 +1,199 @@
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
+"""
+ucon.pydantic
+=============
+
+Pydantic v2 integration for ucon.
+
+Provides type-annotated wrappers for use in Pydantic models with full
+JSON serialization support.
+
+Usage
+-----
+>>> from pydantic import BaseModel
+>>> from ucon.pydantic import Number
+>>>
+>>> class Measurement(BaseModel):
+...     value: Number
+...
+>>> m = Measurement(value={"quantity": 5, "unit": "km"})
+>>> print(m.value)
+<5 km>
+>>> print(m.model_dump_json())
+{"value": {"quantity": 5.0, "unit": "km", "uncertainty": null}}
+
+Installation
+------------
+Requires Pydantic v2. Install with::
+
+    pip install ucon[pydantic]
+
+"""
+
+from typing import Annotated, Any
+
+try:
+    from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler
+    from pydantic.json_schema import JsonSchemaValue
+    from pydantic_core import CoreSchema, core_schema
+except ImportError as e:
+    raise ImportError(
+        "Pydantic v2 is required for ucon.pydantic. "
+        "Install with: pip install ucon[pydantic]"
+    ) from e
+
+from ucon.core import Number as _Number
+from ucon.units import UnknownUnitError, get_unit_by_name
+
+
+def _validate_number(v: Any) -> _Number:
+    """
+    Validate and convert input to Number.
+
+    Accepts:
+    - Number instance (passthrough)
+    - dict with 'quantity' and optional 'unit', 'uncertainty'
+
+    Raises:
+        ValueError: If input cannot be converted to Number.
+    """
+    if isinstance(v, _Number):
+        return v
+
+    if isinstance(v, dict):
+        quantity = v.get("quantity")
+        if quantity is None:
+            raise ValueError("Number dict must have 'quantity' field")
+
+        unit_str = v.get("unit")
+        uncertainty = v.get("uncertainty")
+
+        # Parse unit if provided
+        if unit_str:
+            try:
+                unit = get_unit_by_name(unit_str)
+            except UnknownUnitError as e:
+                raise ValueError(f"Unknown unit: {unit_str!r}") from e
+        else:
+            unit = None
+
+        return _Number(
+            quantity=quantity,
+            unit=unit,
+            uncertainty=uncertainty,
+        )
+
+    raise ValueError(
+        f"Cannot parse Number from {type(v).__name__}. "
+        "Expected Number instance or dict with 'quantity' field."
+    )
+
+
+def _serialize_number(n: _Number) -> dict:
+    """
+    Serialize Number to JSON-compatible dict.
+
+    Output format::
+
+        {
+            "quantity": <float>,
+            "unit": <str | null>,
+            "uncertainty": <float | null>
+        }
+    """
+    # Get unit shorthand
+    if n.unit is None:
+        unit_str = None
+    elif hasattr(n.unit, 'shorthand'):
+        unit_str = n.unit.shorthand
+        # Empty shorthand means dimensionless
+        if unit_str == "":
+            unit_str = None
+    else:
+        unit_str = None
+
+    return {
+        "quantity": float(n.quantity),
+        "unit": unit_str,
+        "uncertainty": float(n.uncertainty) if n.uncertainty is not None else None,
+    }
+
+
+class _NumberPydanticAnnotation:
+    """
+    Pydantic annotation helper for ucon Number type.
+
+    This class provides the schema generation hooks that Pydantic v2 needs
+    to properly validate and serialize Number instances without introspecting
+    the internal Unit/UnitProduct types.
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        _source_type: Any,
+        _handler: GetCoreSchemaHandler,
+    ) -> CoreSchema:
+        """
+        Generate Pydantic core schema for Number validation/serialization.
+
+        Uses no_info_plain_validator_function to bypass Pydantic's default
+        introspection of the Number class fields.
+        """
+        return core_schema.no_info_plain_validator_function(
+            _validate_number,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                _serialize_number,
+                info_arg=False,
+                return_schema=core_schema.dict_schema(),
+            ),
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls,
+        _core_schema: CoreSchema,
+        handler: GetJsonSchemaHandler,
+    ) -> JsonSchemaValue:
+        """Generate JSON schema for OpenAPI documentation."""
+        return {
+            "type": "object",
+            "properties": {
+                "quantity": {"type": "number"},
+                "unit": {"type": "string", "nullable": True},
+                "uncertainty": {"type": "number", "nullable": True},
+            },
+            "required": ["quantity"],
+        }
+
+
+Number = Annotated[_Number, _NumberPydanticAnnotation]
+"""
+Pydantic-compatible Number type.
+
+Use this as a type hint in Pydantic models to enable automatic validation
+and JSON serialization of ucon Number instances.
+
+Example::
+
+    from pydantic import BaseModel
+    from ucon.pydantic import Number
+
+    class Measurement(BaseModel):
+        value: Number
+
+    # From dict
+    m = Measurement(value={"quantity": 5, "unit": "m"})
+
+    # From Number instance
+    from ucon import units
+    m2 = Measurement(value=units.meter(10))
+
+    # Serialize to JSON
+    print(m.model_dump_json())
+"""
+
+__all__ = ["Number"]