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

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/units.py

@@ -140,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',))
 # ----------------------------------------------------------------------
 
 
@@ -203,6 +204,10 @@ def have(name: str) -> bool:
 _UNIT_REGISTRY: Dict[str, Unit] = {}
 _UNIT_REGISTRY_CASE_SENSITIVE: Dict[str, Unit] = {}
 
+# Priority aliases that must match exactly before prefix decomposition.
+# Prevents ambiguous parses like "min" -> milli-inch instead of minute.
+_PRIORITY_ALIASES: set = {'min'}
+
 # Scale prefix mapping (shorthand -> Scale)
 # Sorted by length descending for greedy matching
 _SCALE_PREFIXES: Dict[str, Scale] = {
@@ -293,7 +298,10 @@ 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.
+    Prioritizes prefix+unit interpretation over direct unit lookup,
+    except for priority aliases (like 'min') which are checked first
+    to avoid ambiguous parses.
+
     This means "kg" returns (gram, Scale.kilo) rather than (kilogram, Scale.one).
 
     Examples:
@@ -302,6 +310,7 @@ def _lookup_factor(s: str) -> Tuple[Unit, Scale]:
     - 'km' -> (meter, Scale.kilo)
     - 'kg' -> (gram, Scale.kilo)
     - 'mL' -> (liter, Scale.milli)
+    - 'min' -> (minute, Scale.one)  # priority alias, not milli-inch
 
     Returns:
         Tuple of (unit, scale).
@@ -309,7 +318,15 @@ def _lookup_factor(s: str) -> Tuple[Unit, Scale]:
     Raises:
         UnknownUnitError: If the unit cannot be resolved.
     """
-    # Try scale prefix + unit first (prioritize decomposition)
+    # Check priority aliases first (prevents "min" -> milli-inch)
+    if s in _PRIORITY_ALIASES:
+        if s in _UNIT_REGISTRY_CASE_SENSITIVE:
+            return _UNIT_REGISTRY_CASE_SENSITIVE[s], Scale.one
+        s_lower = s.lower()
+        if s_lower in _UNIT_REGISTRY:
+            return _UNIT_REGISTRY[s_lower], Scale.one
+
+    # Try scale prefix + unit (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):

{ucon-0.6.0.dist-info → ucon-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.6.0
+Version: 0.6.2
 Summary: A tool for dimensional analysis: a 'Unit CONverter'
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -94,7 +94,7 @@ 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`.                              |
@@ -227,6 +227,10 @@ 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 Propagation
@@ -278,6 +282,47 @@ m4 = Measurement(value={"quantity": 9.8, "unit": "m/s²"})   # Unicode
 - **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).
@@ -295,7 +340,7 @@ See full example: [docs/examples/basis-transform-fantasy-units.md](./docs/exampl
 | **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, JSON serialization | ✅ Complete |
+| **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)

ucon-0.6.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+ucon/__init__.py,sha256=SAXuDNMmxzaLVr4JpUHsz-feQotVhpzsCUj2WiXYA-0,2361
+ucon/algebra.py,sha256=6QrPyD23L93XSrnIORcYEx2CLDv4WDcrh6H_hxeeOus,8668
+ucon/core.py,sha256=V10GfKTf28GFgoO9NMI7ciqKHI_p8wG8qICR6u85gv0,63300
+ucon/graph.py,sha256=vBIKwppYCAu5sw6R_3zTBlnOk2WmYMClIb6j5kDvJHI,21342
+ucon/maps.py,sha256=-rPMOHylcQYUn62R9IU23bXdCRCRNBhdH3UD4G5IUEk,9123
+ucon/pydantic.py,sha256=64ZR1EYFRnBGHj3VIF5pc3swdAiR2ZlYrgcntdbKN4k,5189
+ucon/quantity.py,sha256=GBxZ_96nocx-8F-usNWGbPvWHRhRgdZzqfH9Sx69iC4,465
+ucon/units.py,sha256=3reuG-G-BAAOiH_es8CE5jxAFTg5bkrd2JQ5C1iBTFg,16676
+ucon/mcp/__init__.py,sha256=WoFOQ7JeDIzbjjkFIJ0Uv53VVLu-4lrjzG5vpVGGfT4,123
+ucon/mcp/server.py,sha256=uUrdevEaR65Qjh9xn8Q-_IusNjPGxdkLF9iQmiSTs0g,7016
+ucon-0.6.2.dist-info/licenses/LICENSE,sha256=LtimSYBSw1L_X6n1-VEdZRdwuROzPumrMUNX21asFuI,11356
+ucon-0.6.2.dist-info/licenses/NOTICE,sha256=bh4fBOItio3kM4hSNYhqfFpcaAvOoixjD7Du8im-sYA,1079
+ucon-0.6.2.dist-info/METADATA,sha256=5fBukT2t1v_OV17FdanlgFq6mFsKhXZuovhN6yJmg2s,17397
+ucon-0.6.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ucon-0.6.2.dist-info/entry_points.txt,sha256=jbfLf0FbOulgGa0nM_sRiTNfiCAkJcHnSSK_oj3g0cQ,50
+ucon-0.6.2.dist-info/top_level.txt,sha256=Vv3KDuZ86fmH5yOYLbYap9DbBblK1YUkmlThffF71jA,5
+ucon-0.6.2.dist-info/RECORD,,

ucon-0.6.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-ucon/__init__.py,sha256=SAXuDNMmxzaLVr4JpUHsz-feQotVhpzsCUj2WiXYA-0,2361
-ucon/algebra.py,sha256=6QrPyD23L93XSrnIORcYEx2CLDv4WDcrh6H_hxeeOus,8668
-ucon/core.py,sha256=V10GfKTf28GFgoO9NMI7ciqKHI_p8wG8qICR6u85gv0,63300
-ucon/graph.py,sha256=Ec0Q2QiAGUm2RaxrKnpFHtwpNvTf4PYbvo62BWtGJG8,21159
-ucon/maps.py,sha256=tWP4ayYCEazJzf81EP1_fmtADhg18D1eHldudAMEY0U,5460
-ucon/pydantic.py,sha256=64ZR1EYFRnBGHj3VIF5pc3swdAiR2ZlYrgcntdbKN4k,5189
-ucon/quantity.py,sha256=GBxZ_96nocx-8F-usNWGbPvWHRhRgdZzqfH9Sx69iC4,465
-ucon/units.py,sha256=mcZ6LtHPjP4RYtzWTbf-tdjKtazcM1bDmxTI_tKrMxk,15924
-ucon/mcp/__init__.py,sha256=WoFOQ7JeDIzbjjkFIJ0Uv53VVLu-4lrjzG5vpVGGfT4,123
-ucon/mcp/server.py,sha256=uUrdevEaR65Qjh9xn8Q-_IusNjPGxdkLF9iQmiSTs0g,7016
-ucon-0.6.0.dist-info/licenses/LICENSE,sha256=LtimSYBSw1L_X6n1-VEdZRdwuROzPumrMUNX21asFuI,11356
-ucon-0.6.0.dist-info/licenses/NOTICE,sha256=bh4fBOItio3kM4hSNYhqfFpcaAvOoixjD7Du8im-sYA,1079
-ucon-0.6.0.dist-info/METADATA,sha256=qdS_SH1wMJHnmWRTebu1VzWO3T935GmRMIcD9vjZ9XM,16375
-ucon-0.6.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-ucon-0.6.0.dist-info/entry_points.txt,sha256=jbfLf0FbOulgGa0nM_sRiTNfiCAkJcHnSSK_oj3g0cQ,50
-ucon-0.6.0.dist-info/top_level.txt,sha256=Vv3KDuZ86fmH5yOYLbYap9DbBblK1YUkmlThffF71jA,5
-ucon-0.6.0.dist-info/RECORD,,