ucon

Pronounced: yoo · cahn

A lightweight, unit-aware computation library for Python — built on first-principles.

Documentation · Quickstart · API Reference

What is ucon?

ucon helps Python understand the physical meaning of your numbers. It treats units, dimensions, and scales as first-class objects — enforcing physics, not just labels.

from ucon import units

length = units.meter(5)
time = units.second(2)

speed = length / time      # <2.5 m/s>
invalid = length + time    # raises: incompatible dimensions

Installation

pip install ucon

With extras:

pip install ucon[numpy]     # NumPy array support
pip install ucon[pandas]    # Pandas DataFrame integration
pip install ucon[polars]    # Polars DataFrame integration
pip install ucon[pydantic]  # Pydantic v2 integration
pip install ucon-tools[mcp] # MCP server for AI agents (separate package)

Quick Examples

Parse Quantities

from ucon import parse

velocity = parse("9.81 m/s^2")       # <9.81 m/s²>
measurement = parse("1.234 ± 0.005 m")  # <1.234 ± 0.005 m>

Unit Conversion

from ucon import units, Scale

km = Scale.kilo * units.meter
distance = km(5)

print(distance.to(units.mile))  # <3.107... mi>

Dimensional Safety

from ucon import Number, Dimension, enforce_dimensions

@enforce_dimensions
def speed(
    distance: Number[Dimension.length],
    time: Number[Dimension.time],
) -> Number:
    return distance / time

speed(units.meter(100), units.second(10))   # <10.0 m/s>
speed(units.second(100), units.second(10))  # raises ValueError

NumPy Arrays

from ucon import units

# Vectorized operations on arrays
heights = units.meter([1.7, 1.8, 1.9, 2.0])
heights_ft = heights.to(units.foot)  # <[5.577, 5.906, 6.234, 6.562] ft>

# Arithmetic with unit tracking
areas = heights * units.meter([2, 2, 2, 2])  # m^2

# Statistical reductions preserve units
avg = heights.mean()  # <1.85 m>

Pydantic Integration

from pydantic import BaseModel
from ucon.integrations.pydantic import Number

class Measurement(BaseModel):
    value: Number

m = Measurement(value={"quantity": 9.8, "unit": "m/s^2"})
print(m.model_dump_json())
# {"value": {"quantity": 9.8, "unit": "m/s^2", "uncertainty": null}}

MCP Server for AI Agents

Install ucon-tools and configure in Claude Desktop:

pip install ucon-tools[mcp]

{
  "mcpServers": {
    "ucon": {
      "command": "uvx",
      "args": ["--from", "ucon-tools[mcp]", "ucon-mcp"]
    }
  }
}

AI agents can then convert units, check dimensions, and perform factor-label calculations with dimensional validation at each step.

Composable Unit Systems

import ucon
from ucon import use

with use(ucon.active_system().restrict(units=["meter", "second", "kilogram"])):
    parse("9.81 m/s^2")    # ok — length and time are in scope
    parse("100 °F")        # raises — temperature is not

UnitSystem is an immutable value. extend / restrict / merge compose systems; use(...) activates one per scope via a ContextVar — no module-global state. Full walkthrough: examples/system/README.md.

Features

NumPy arrays — Vectorized operations with NumberArray for batch computations
Pandas/Polars — Unit-aware DataFrames with NumberSeries and NumberColumn
Physical constants — CODATA 2022 values with uncertainty propagation (E = m * c**2)
Custom constants — Define domain-specific constants with uncertainty propagation
String parsing — parse("9.81 m/s^2") with uncertainty support (1.234 ± 0.005 m)
Dimensional algebra — Units combine through multiplication/division with automatic dimension tracking
Scale prefixes — Full SI (kilo, milli, micro, etc.) and binary (kibi, mebi) prefix support
Uncertainty propagation — Measurement errors propagate through arithmetic and conversions; conversion factor uncertainty from measured constants (Planck, atomic) propagates on opt-in
Pseudo-dimensions — Semantically isolated handling of angles, ratios, and counts
Natural units — Custom dimensional bases where c=ℏ=k_B=1 for particle physics
Logarithmic units — dB, pH, and neper conversions with uncertainty propagation
Pydantic v2 — Type-safe API validation and JSON serialization
MCP server — AI agent integration with Claude, Cursor, and other MCP clients
ConversionGraph — Extensible conversion registry with custom unit support

Roadmap Highlights

Version	Theme	Status
0.x	Algebraic foundation: Unit/Scale separation, `ConversionGraph`, dimension/basis abstraction, uncertainty propagation, NumPy/Pandas/Polars, Pydantic, MCP	Complete
1.0.0	API stability + 2-year LTS commitment, ~215 units across 67+ dimensions	Complete
1.2.0	TOML round-trip `ConversionGraph` serialization	Complete
1.3.0	Graph-independent arithmetic via `BaseForm` decomposition	Complete
1.4.0	Basis isomorphisms: Atomic and Planck units as first-class bases	Complete
1.5.0	Conversion factor uncertainty (GUM propagation)	Complete
1.6.0	TOML takeover — single source of truth for unit definitions	Complete
1.7.0	Basis subpackage layout: `types`/`vector` extraction	Complete
1.8.0	`UnitSystem` as a value type, strict same-basis `Vector`, explicit cross-basis `ops`	Complete
1.9.0	Kind-of-Quantity (KOQ) sortal lattice and formula registry — opt-in preview surface	Complete
1.10.0	`Number.to()` routed through the active `UnitSystem`; top-level `active()` / `use()` exports	Complete
1.11.0	Eager `UnitSystem` initialization on import; module-global default-graph singletons deprecated	Complete
1.12.0	Cycle-break completion: `_active` and `AlgebraCache` as Layer-0 leaves; AST audit against cross-module injection	Complete
2.0.0	`UnitSystem` algebra (`extend` / `restrict` / `merge` / `with_*`), relations (`subsystem_of` / `compatible_with` / `diff`), cross-system movement (`adopt`, `Bridge`), first-class `Number.kind` with arithmetic dispatch, `ActiveContext` substrate, `strict=True` default, marshal-based graph cache	Complete

See full roadmap: ROADMAP.md

Documentation

Section	Description
Getting Started	Why ucon, quickstart, installation
Guides	NumPy/Pandas/Polars, MCP server, Pydantic, custom units
Reference	API docs, unit tables, MCP tool schemas
Architecture	Design principles, ConversionGraph, comparison with Pint

Contributing

make venv                        # Create virtual environment
source .ucon-3.12/bin/activate   # Activate
make test                        # Run tests
make test-all                    # Run tests across all Python versions

When modifying ucon/dimension.py (adding/removing dimensions), regenerate the type stubs:

make stubs                       # Regenerate ucon/dimension.pyi
make stubs-check                 # Verify stubs are current (used in CI)

All pull requests must include a CHANGELOG.md entry under the [Unreleased] section:

## [Unreleased]

### Added

- Your new feature description (#PR_NUMBER)

Use the appropriate category: Added, Changed, Deprecated, Removed, Fixed, or Security.

Policies

Security — Vulnerability reporting and dependency policy
Support — Versioning, LTS, and backward-compatibility guarantees

License

Apache 2.0. See LICENSE.

Release files for ucon 2.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ucon 2.2.2
File	Size	Uploaded
ucon-2.2.2.tar.gz	472.9 kB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ucon 2.2.2
File	Interpreter	ABI	Platform	Reset
ucon-2.2.2-py3-none-any.whl 237.8 kB Sep 18, 2026	Python 3	none	any	Details

Total release size: 710.6 kB

Release files / ucon-2.2.2.tar.gz

Download URL	ucon-2.2.2.tar.gz
Size	472.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`020e9987569cc5a24a45c79bae843284831d74e7d46845879cf1b8a98a533698`
BLAKE2b-256 checksum How to use checksums	`bf5ddd83e989c70ff16c02883015dc622ba4eb64a586a906b84aee0e6f372ce9`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / ucon-2.2.2-py3-none-any.whl

Download URL	ucon-2.2.2-py3-none-any.whl
Size	237.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3071e298a3567785acd38fc3b33121065ac4ab780d7d13be5b40b3ba7137515d`
BLAKE2b-256 checksum How to use checksums	`11375001636fd592479e655d29fb9a4e011aa82590cb61f711b5ef277701755f`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`