ucon 0.5.1__tar.gz → 0.6.0__tar.gz

{ucon-0.5.1 → ucon-0.6.0}/.github/workflows/publish.yaml

@@ -16,16 +16,16 @@ jobs:
           fetch-depth: 0  # needed for ancestry check
           ref: ${{ github.ref_name }}
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: '3.14'
 
-      - name: Install dependencies
-        run: pip install -r requirements.txt
-
       - name: Build distribution 📦
-        run: PYTHONWARNINGS=ignore LOCAL_VERSION_SCHEME=true nox -s build
+        run: LOCAL_VERSION_SCHEME=true make build
 
       - name: Publish to Test PyPI
         if: github.ref == 'refs/heads/main'
@@ -39,7 +39,7 @@ jobs:
       - name: Verify tag is on mainline
         if: startsWith(github.ref, 'refs/tags/')
         run: |
-          git fetch origin main --depth=1
+          git fetch origin main --unshallow 2>/dev/null || git fetch origin main
           TAG=${GITHUB_REF#refs/tags/}
           TAG_COMMIT=$(git rev-list -n 1 "$TAG")
           if ! git merge-base --is-ancestor "$TAG_COMMIT" origin/main; then

{ucon-0.5.1 → ucon-0.6.0}/.github/workflows/tests.yaml

@@ -26,18 +26,16 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v5
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-
       - name: Run tests
-        run: nox -s test
+        run: make test PYTHON=${{ matrix.python-version }}
 
       - name: Upload coverage to Codecov
         if: success() && github.repository_owner == 'withtwoemms'

ucon-0.6.0/Makefile

@@ -0,0 +1,129 @@
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
+# --- Configuration ---
+PROJECTNAME := ucon
+PYTHON ?= 3.12
+SUPPORTED_PYTHONS := 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14
+UV_VENV ?= .${PROJECTNAME}-${PYTHON}
+UV_INSTALLED := .uv-installed
+DEPS_INSTALLED := ${UV_VENV}/.deps-installed
+TESTDIR := tests/
+TESTNAME ?=
+COVERAGE ?= true
+
+# --- Color Setup ---
+GREEN := \033[0;32m
+CYAN := \033[0;36m
+YELLOW := \033[1;33m
+RESET := \033[0m
+
+# --- Help Command ---
+.PHONY: help
+help:
+	@echo "\n${YELLOW}ucon Development Commands${RESET}\n"
+	@echo "  ${CYAN}install${RESET}       - Install package with all extras"
+	@echo "  ${CYAN}install-test${RESET}  - Install with test dependencies only"
+	@echo "  ${CYAN}test${RESET}          - Run tests (PYTHON=X.Y for specific version)"
+	@echo "  ${CYAN}test-all${RESET}      - Run tests across all supported Python versions"
+	@echo "  ${CYAN}coverage${RESET}      - Generate coverage report"
+	@echo "  ${CYAN}build${RESET}         - Build source and wheel distributions"
+	@echo "  ${CYAN}venv${RESET}          - Create virtual environment"
+	@echo "  ${CYAN}clean${RESET}         - Remove build artifacts and caches"
+	@echo ""
+	@echo "${YELLOW}Variables:${RESET}\n"
+	@echo "  PYTHON=${PYTHON}		- Python version for test target"
+	@echo "  UV_VENV=${UV_VENV}	- Path to virtual environment"
+	@echo "  TESTNAME=		- Specific test to run (e.g., tests.ucon.test_core)"
+	@echo "  COVERAGE=${COVERAGE}		- Enable coverage (true/false)"
+	@echo ""
+
+# --- uv Installation ---
+${UV_INSTALLED}:
+	@command -v uv >/dev/null 2>&1 || { \
+		echo "${GREEN}Installing uv...${RESET}"; \
+		curl -LsSf https://astral.sh/uv/install.sh | sh; \
+	}
+	@touch ${UV_INSTALLED}
+
+# --- Virtual Environment ---
+${UV_VENV}: ${UV_INSTALLED}
+	@echo "${GREEN}Creating virtual environment at ${UV_VENV}...${RESET}"
+	@uv venv --python ${PYTHON} ${UV_VENV}
+
+${DEPS_INSTALLED}: pyproject.toml uv.lock | ${UV_VENV}
+	@echo "${GREEN}Syncing dependencies into ${UV_VENV}...${RESET}"
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv sync --python ${PYTHON} --extra test --extra pydantic --extra mcp
+	@touch ${DEPS_INSTALLED}
+
+.PHONY: venv
+venv: ${DEPS_INSTALLED}
+	@echo "${CYAN}Virtual environment ready at ${UV_VENV}${RESET}"
+	@echo "${CYAN}Activate with:${RESET} source ${UV_VENV}/bin/activate"
+
+# --- Installation ---
+.PHONY: install-test
+install-test: ${UV_VENV}
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv sync --python ${PYTHON} --extra test
+
+.PHONY: install
+install: ${UV_VENV}
+	@echo "${GREEN}Installing with all extras into ${UV_VENV}...${RESET}"
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv sync --python ${PYTHON} --extra test --extra pydantic --extra mcp
+
+# --- Testing ---
+.PHONY: test
+test: ${DEPS_INSTALLED}
+	@echo "${GREEN}Running tests with Python ${PYTHON}...${RESET}"
+ifeq ($(COVERAGE),true)
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv run --python ${PYTHON} coverage run --source=ucon --branch \
+		--omit="**/tests/*,**/site-packages/*.py,setup.py" \
+		-m unittest $(if $(TESTNAME),$(TESTNAME),discover --start-directory ${TESTDIR} --top-level-directory .)
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv run --python ${PYTHON} coverage report -m
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv run --python ${PYTHON} coverage xml
+else
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv run --python ${PYTHON} -m unittest \
+		$(if $(TESTNAME),$(TESTNAME),discover --start-directory ${TESTDIR} --top-level-directory .)
+endif
+
+.PHONY: test-all
+test-all: ${UV_INSTALLED}
+	@echo "${GREEN}Running tests across all supported Python versions...${RESET}"
+	@for pyver in $(SUPPORTED_PYTHONS); do \
+		echo "\n${CYAN}=== Python $$pyver ===${RESET}"; \
+		uv run --python $$pyver -m unittest discover \
+			--start-directory ${TESTDIR} --top-level-directory . \
+		|| echo "${YELLOW}Python $$pyver: FAILED or not available${RESET}"; \
+	done
+
+# --- Coverage ---
+.PHONY: coverage
+coverage: ${DEPS_INSTALLED}
+	@echo "${GREEN}Generating coverage report...${RESET}"
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv run --python ${PYTHON} coverage report -m
+	@UV_PROJECT_ENVIRONMENT=${UV_VENV} uv run --python ${PYTHON} coverage html
+	@echo "${CYAN}HTML report at htmlcov/index.html${RESET}"
+
+# --- Building ---
+.PHONY: build
+build: ${UV_INSTALLED}
+	@echo "${GREEN}Building distributions...${RESET}"
+	@uv build
+	@echo "${CYAN}Distributions at dist/${RESET}"
+
+# --- Cleaning ---
+.PHONY: clean
+clean:
+	@echo "${GREEN}Cleaning build artifacts...${RESET}"
+	@rm -rf dist/ build/ *.egg-info/
+	@rm -rf ${UV_VENV} ${DEPS_INSTALLED} ${UV_INSTALLED}
+	@rm -rf .uv_cache .pytest_cache htmlcov/
+	@rm -f coverage.xml .coverage
+	@find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	@echo "${CYAN}Clean complete.${RESET}"
+
+.PHONY: clean-all
+clean-all: clean
+	@echo "${YELLOW}Removing uv.lock...${RESET}"
+	@rm -f uv.lock

{ucon-0.5.1/ucon.egg-info → ucon-0.6.0}/PKG-INFO

@@ -1,18 +1,20 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.5.1
-Summary: a tool for dimensional analysis: a "Unit CONverter"
+Version: 0.6.0
+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.
@@ -92,7 +96,11 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 | **`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).                                        |
 | **`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
 
@@ -139,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
@@ -175,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
 
@@ -199,16 +212,16 @@ 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>
 
@@ -216,25 +229,61 @@ print(ratio.to(units.ppm))  # <500000.0 ppm>
 units.radian(1).to(units.percent)  # raises ConversionNotFound
 ```
 
-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>
 ```
 
+### Pydantic Integration
+
+```python
+from pydantic import BaseModel
+from ucon.pydantic import Number
+from ucon import units
+
+class Measurement(BaseModel):
+    value: Number
+
+# From JSON/dict input
+m = Measurement(value={"quantity": 5, "unit": "km"})
+print(m.value)  # <5 km>
+
+# From Number instance
+m2 = Measurement(value=units.meter(10))
+
+# Serialize to JSON
+print(m.model_dump_json())
+# {"value": {"quantity": 5.0, "unit": "km", "uncertainty": null}}
+
+# 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
+```
+
+**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.
+
+### 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)
+
 ---
 
 ## Roadmap Highlights
@@ -245,8 +294,9 @@ print(length_ft)  # <4.048... ± 0.0164... ft>
 | **0.4.x** | Conversion System | `ConversionGraph`, `Number.to()`, callable units | ✅ Complete |
 | **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 | `BasisMap`, `UnitSystem` | 🚧 In Progress |
-| **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.5.x** | Unit Systems | `BasisTransform`, `UnitSystem`, cross-basis conversion | ✅ Complete |
+| **0.6.x** | Pydantic Integration | Type-safe quantity validation, JSON serialization | ✅ Complete |
+| **0.7.x** | NumPy Arrays | Vectorized conversion and arithmetic | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 
@@ -255,14 +305,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
 ```
 ---
 

ucon-0.5.1/PKG-INFO → ucon-0.6.0/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.4
-Name: ucon
-Version: 0.5.1
-Summary: a tool for dimensional analysis: a "Unit CONverter"
-Home-page: https://github.com/withtwoemms/ucon
-Author: Emmanuel I. Obi
-Maintainer: Emmanuel I. Obi
-Maintainer-email: withtwoemms@gmail.com
-License: Apache-2.0
-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
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-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>
     <td width="200">
@@ -68,6 +31,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.
@@ -92,7 +56,11 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 | **`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).                                        |
 | **`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
 
@@ -139,35 +107,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
@@ -175,12 +148,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
 
@@ -199,16 +172,16 @@ 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>
 
@@ -216,25 +189,61 @@ print(ratio.to(units.ppm))  # <500000.0 ppm>
 units.radian(1).to(units.percent)  # raises ConversionNotFound
 ```
 
-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>
 ```
 
+### Pydantic Integration
+
+```python
+from pydantic import BaseModel
+from ucon.pydantic import Number
+from ucon import units
+
+class Measurement(BaseModel):
+    value: Number
+
+# From JSON/dict input
+m = Measurement(value={"quantity": 5, "unit": "km"})
+print(m.value)  # <5 km>
+
+# From Number instance
+m2 = Measurement(value=units.meter(10))
+
+# Serialize to JSON
+print(m.model_dump_json())
+# {"value": {"quantity": 5.0, "unit": "km", "uncertainty": null}}
+
+# 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
+```
+
+**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.
+
+### 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)
+
 ---
 
 ## Roadmap Highlights
@@ -245,8 +254,9 @@ print(length_ft)  # <4.048... ± 0.0164... ft>
 | **0.4.x** | Conversion System | `ConversionGraph`, `Number.to()`, callable units | ✅ Complete |
 | **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 | `BasisMap`, `UnitSystem` | 🚧 In Progress |
-| **0.7.x** | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| **0.5.x** | Unit Systems | `BasisTransform`, `UnitSystem`, cross-basis conversion | ✅ Complete |
+| **0.6.x** | Pydantic Integration | Type-safe quantity validation, JSON serialization | ✅ Complete |
+| **0.7.x** | NumPy Arrays | Vectorized conversion and arithmetic | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 
@@ -255,14 +265,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
 ```
 ---