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

ucon/__init__.py

@@ -53,6 +53,7 @@ from ucon.core import (
     Ratio,
 )
 from ucon.graph import get_default_graph, using_graph
+from ucon.units import UnknownUnitError, get_unit_by_name
 
 
 __all__ = [
@@ -69,7 +70,9 @@ __all__ = [
     'UnitFactor',
     'UnitProduct',
     'UnitSystem',
+    'UnknownUnitError',
     'get_default_graph',
-    'using_graph',
+    'get_unit_by_name',
     'units',
+    'using_graph',
 ]

ucon/core.py

@@ -1108,16 +1108,21 @@ class UnitProduct:
         part = getattr(unit, "shorthand", "") or getattr(unit, "name", "") or ""
         if not part:
             return
+
+        def fmt_exp(p: float) -> str:
+            """Format exponent, using int when possible to avoid '2.0' → '²·⁰'."""
+            return str(int(p) if p == int(p) else p).translate(cls._SUPERSCRIPTS)
+
         if power > 0:
             if power == 1:
                 num.append(part)
             else:
-                num.append(part + str(power).translate(cls._SUPERSCRIPTS))
+                num.append(part + fmt_exp(power))
         elif power < 0:
             if power == -1:
                 den.append(part)
             else:
-                den.append(part + str(-power).translate(cls._SUPERSCRIPTS))
+                den.append(part + fmt_exp(-power))
 
     @property
     def shorthand(self) -> str:

ucon/graph.py

@@ -37,7 +37,7 @@ from ucon.core import (
     UnitProduct,
     Scale,
 )
-from ucon.maps import Map, LinearMap, AffineMap
+from ucon.maps import Map, LinearMap, AffineMap, LogMap
 
 
 class DimensionMismatch(Exception):
@@ -589,10 +589,12 @@ def _build_standard_graph() -> ConversionGraph:
     graph.add_edge(src=units.steradian, dst=units.square_degree, map=LinearMap((180 / math.pi) ** 2))
 
     # --- Ratio ---
-    graph.add_edge(src=units.ratio_one, dst=units.percent, map=LinearMap(100))
-    graph.add_edge(src=units.ratio_one, dst=units.permille, map=LinearMap(1000))
-    graph.add_edge(src=units.ratio_one, dst=units.ppm, map=LinearMap(1e6))
-    graph.add_edge(src=units.ratio_one, dst=units.ppb, map=LinearMap(1e9))
-    graph.add_edge(src=units.ratio_one, dst=units.basis_point, map=LinearMap(10000))
+    graph.add_edge(src=units.fraction, dst=units.percent, map=LinearMap(100))
+    graph.add_edge(src=units.fraction, dst=units.permille, map=LinearMap(1000))
+    graph.add_edge(src=units.fraction, dst=units.ppm, map=LinearMap(1e6))
+    graph.add_edge(src=units.fraction, dst=units.ppb, map=LinearMap(1e9))
+    graph.add_edge(src=units.fraction, dst=units.basis_point, map=LinearMap(10000))
+    # nines: -log₁₀(1 - availability) for SRE uptime (0.99999 → 5 nines)
+    graph.add_edge(src=units.fraction, dst=units.nines, map=LogMap(scale=-1) @ AffineMap(a=-1, b=1))
 
     return graph

ucon/maps.py

@@ -14,10 +14,13 @@ Classes
 - :class:`Map` — Abstract base for conversion morphisms.
 - :class:`LinearMap` — y = a * x
 - :class:`AffineMap` — y = a * x + b
+- :class:`LogMap` — y = scale * log_base(x) + offset
+- :class:`ExpMap` — y = base^(scale * x + offset)
 - :class:`ComposedMap` — Generic composition fallback: g(f(x))
 """
 from __future__ import annotations
 
+import math
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 
@@ -145,6 +148,119 @@ class AffineMap(Map):
         return self.a
 
 
+@dataclass(frozen=True)
+class LogMap(Map):
+    """
+    Logarithmic map: ``y = scale * log_base(x) + offset``
+
+    Examples::
+
+        LogMap()                  # log₁₀(x)
+        LogMap(scale=10)          # 10·log₁₀(x) — decibels (power)
+        LogMap(scale=20)          # 20·log₁₀(x) — decibels (amplitude)
+        LogMap(scale=-1)          # -log₁₀(x)   — pH-style
+        LogMap(base=math.e)       # ln(x)       — neper
+
+    For transforms like nines ``(-log₁₀(1-x))``, compose with AffineMap::
+
+        LogMap(scale=-1) @ AffineMap(a=-1, b=1)
+    """
+
+    scale: float = 1.0
+    base: float = 10.0
+    offset: float = 0.0
+
+    def __call__(self, x: float) -> float:
+        if x <= 0:
+            raise ValueError(f"Logarithm argument must be positive, got {x}")
+        return self.scale * math.log(x, self.base) + self.offset
+
+    @property
+    def invertible(self) -> bool:
+        return self.scale != 0
+
+    def inverse(self) -> 'ExpMap':
+        """Return the inverse exponential map."""
+        if not self.invertible:
+            raise ZeroDivisionError("LogMap with scale=0 is not invertible.")
+        return ExpMap(
+            scale=1.0 / self.scale,
+            base=self.base,
+            offset=-self.offset / self.scale,
+        )
+
+    def __matmul__(self, other: Map) -> Map:
+        if not isinstance(other, Map):
+            return NotImplemented
+        return ComposedMap(self, other)
+
+    def __pow__(self, exp: float) -> Map:
+        if exp == 1:
+            return self
+        if exp == -1:
+            return self.inverse()
+        raise ValueError("LogMap only supports exp=1 or exp=-1")
+
+    def derivative(self, x: float) -> float:
+        """Derivative: d/dx[scale * log_base(x) + offset] = scale / (x * ln(base))"""
+        if x <= 0:
+            raise ValueError(f"Derivative undefined for x={x}")
+        return self.scale / (x * math.log(self.base))
+
+    def is_identity(self, tol: float = 1e-9) -> bool:
+        return False  # Logarithm is never identity
+
+
+@dataclass(frozen=True)
+class ExpMap(Map):
+    """
+    Exponential map: ``y = base^(scale * x + offset)``
+
+    This is the inverse of :class:`LogMap`. Typically obtained via
+    ``LogMap.inverse()`` rather than constructed directly.
+    """
+
+    scale: float = 1.0
+    base: float = 10.0
+    offset: float = 0.0
+
+    def __call__(self, x: float) -> float:
+        return self.base ** (self.scale * x + self.offset)
+
+    @property
+    def invertible(self) -> bool:
+        return self.scale != 0
+
+    def inverse(self) -> LogMap:
+        """Return the inverse logarithmic map."""
+        if not self.invertible:
+            raise ZeroDivisionError("ExpMap with scale=0 is not invertible.")
+        return LogMap(
+            scale=1.0 / self.scale,
+            base=self.base,
+            offset=-self.offset / self.scale,
+        )
+
+    def __matmul__(self, other: Map) -> Map:
+        if not isinstance(other, Map):
+            return NotImplemented
+        return ComposedMap(self, other)
+
+    def __pow__(self, exp: float) -> Map:
+        if exp == 1:
+            return self
+        if exp == -1:
+            return self.inverse()
+        raise ValueError("ExpMap only supports exp=1 or exp=-1")
+
+    def derivative(self, x: float) -> float:
+        """Derivative: d/dx[base^(scale*x + offset)] = ln(base) * scale * base^(scale*x + offset)"""
+        return math.log(self.base) * self.scale * self(x)
+
+    def is_identity(self, tol: float = 1e-9) -> bool:
+        return False  # Exponential is never identity
+
+
 @dataclass(frozen=True)
 class ComposedMap(Map):
     """Generic composition fallback: ``(outer ∘ inner)(x) = outer(inner(x))``."""

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"]