ucon 0.3.0__tar.gz → 0.3.1rc2__tar.gz

ucon-0.3.1rc2/.github/workflows/publish.yaml

@@ -0,0 +1,53 @@
+name: publish
+
+on:
+  push:
+    branches: [main]   # mainline merges → Test PyPI
+    tags: ['*']        # tags → Test & Prod PyPI
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # needed for ancestry check
+
+      - 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
+
+      - name: Publish to Test PyPI
+        if: github.ref == 'refs/heads/main'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.test_pypi_password }}
+          skip_existing: true
+          repository_url: https://test.pypi.org/legacy/
+
+      - name: 🧪 Publish tag build to Test PyPI
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.test_pypi_password }}
+          skip_existing: true
+          repository_url: https://test.pypi.org/legacy/
+
+      - name: 🚀 Publish to Prod PyPI
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}
+          skip_existing: true

ucon-0.3.1rc2/.github/workflows/tests.yaml

@@ -0,0 +1,51 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ['**']
+
+jobs:
+  run_tests:
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - '3.7'
+          - '3.8'
+          - '3.9'
+          - '3.10'
+          - '3.11'
+          - '3.12'
+          - '3.13'
+          - '3.14'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@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
+
+      - name: Upload coverage to Codecov
+        if: success() && github.repository_owner == 'withtwoemms'
+        run: bash <(curl -s https://codecov.io/bash) -t ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Archive coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-${{ matrix.python-version }}-coverage-${{ github.run_id }}
+          path: ${{ github.workspace }}/coverage.xml

ucon-0.3.1rc2/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: ucon
+Version: 0.3.1rc2
+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: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT 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
+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
+
+<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="420" />
+
+# ucon
+
+> Pronounced: _yoo · cahn_
+> A lightweight, **unit-aware computation library** for Python — built on first-principles.
+
+[![tests](https://github.com/withtwoemms/ucon/workflows/tests/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Atests)
+[![codecov](https://codecov.io/gh/withtwoemms/ucon/graph/badge.svg?token=BNONQTRJWG)](https://codecov.io/gh/withtwoemms/ucon)
+[![publish](https://github.com/withtwoemms/ucon/workflows/publish/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Apublish)
+
+---
+
+## Overview
+
+`ucon` helps Python understand the *physical meaning* of your numbers.
+It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
+
+- Dimensional analysis through `Number` and `Ratio`
+- Scale-aware arithmetic and conversions
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
+- 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.
+
+## Introduction
+
+The crux of this tiny library is to provide abstractions that simplify the answering of questions like:
+
+> _"If given two milliliters of bromine (liquid Br<sub>2</sub>), how many grams of bromine does one have?"_
+
+To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
+| Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
+| ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
+| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
+| **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
+| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible 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).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
+
+### Under the Hood
+
+`ucon` models unit math through a hierarchy where each layer builds on the last:
+
+![Alt text](./docs/assets/ucon.data-model.svg "Data Model Diagram")
+
+## Why `ucon`?
+
+Python already has mature libraries for handling units and physical quantities — Pint, SymPy, and Unum — each solving part of the same problem from different angles:
+
+| Library   | Focus                                                   | Limitation                                                                                                             |
+| --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
+| **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
+| **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
+
+Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
+
+That’s the gap `ucon` fills.
+
+It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
+This allows you to:
+- Represent dimensional meaning explicitly (`Dimension`, `Vector`);
+- Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
+- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
+- Serialize and validate measurements with Pydantic integration;
+- Extend the system with custom unit registries and conversion families.
+
+Where Pint, Unum, and SymPy focus on _how_ to compute with units,
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
+```python
+from ucon import Number, units
+
+length = Number(quantity=5, unit=units.meter)
+time = Number(quantity=2, unit=units.second)
+
+speed = length / time     # ✅ valid: L / T = velocity
+invalid = length + time   # ❌ raises: incompatible dimensions
+```
+
+## Setup
+
+Simple:
+```bash
+pip install ucon
+```
+
+## Usage
+
+This sort of dimensional analysis:
+```
+ 2 mL bromine | 3.119 g bromine
+--------------x-----------------  #=> 6.238 g bromine
+      1       |  1 mL bromine
+```
+becomes straightforward when you define a measurement:
+```python
+from ucon import Number, Scale, Units, Ratio
+
+# Two milliliters of bromine
+two_mL_bromine = Number(unit=Units.liter, scale=Scale.milli, quantity=2)
+
+# Density of bromine: 3.119 g/mL
+bromine_density = Ratio(
+    numerator=Number(unit=Units.gram, quantity=3.119),
+    denominator=Number(unit=Units.liter, scale=Scale.milli),
+)
+
+# Multiply to find mass
+grams_bromine = two_mL_bromine * bromine_density
+print(grams_bromine)  # <6.238 gram>
+```
+
+Scale conversion is automatic and precise:
+
+```python
+grams_bromine.to(Scale.milli)  # <6238.0 milligram>
+grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+```
+
+---
+
+## Roadmap Highlights
+
+| Version | Theme | Focus |
+|----------|-------|--------|
+| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
+
+See full roadmap: [ROADMAP.md](./ROADMAP.md)
+
+---
+
+## Contributing
+
+Contributions, issues, and pull requests are welcome!
+Ensure `nox` is installed.
+```
+pip install -r requirements.txt
+```
+Then run the full test suite (agains all supported python versions) before committing:
+
+```bash
+nox -s test
+```
+---
+
+> “If it can be measured, it can be represented.
+If it can be represented, it can be validated.
+If it can be validated, it can be trusted.”

ucon-0.3.1rc2/README.md

@@ -0,0 +1,155 @@
+<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="420" />
+
+# ucon
+
+> Pronounced: _yoo · cahn_
+> A lightweight, **unit-aware computation library** for Python — built on first-principles.
+
+[![tests](https://github.com/withtwoemms/ucon/workflows/tests/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Atests)
+[![codecov](https://codecov.io/gh/withtwoemms/ucon/graph/badge.svg?token=BNONQTRJWG)](https://codecov.io/gh/withtwoemms/ucon)
+[![publish](https://github.com/withtwoemms/ucon/workflows/publish/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Apublish)
+
+---
+
+## Overview
+
+`ucon` helps Python understand the *physical meaning* of your numbers.
+It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
+
+- Dimensional analysis through `Number` and `Ratio`
+- Scale-aware arithmetic and conversions
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
+- 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.
+
+## Introduction
+
+The crux of this tiny library is to provide abstractions that simplify the answering of questions like:
+
+> _"If given two milliliters of bromine (liquid Br<sub>2</sub>), how many grams of bromine does one have?"_
+
+To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
+| Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
+| ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
+| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
+| **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
+| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible 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).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
+
+### Under the Hood
+
+`ucon` models unit math through a hierarchy where each layer builds on the last:
+
+![Alt text](./docs/assets/ucon.data-model.svg "Data Model Diagram")
+
+## Why `ucon`?
+
+Python already has mature libraries for handling units and physical quantities — Pint, SymPy, and Unum — each solving part of the same problem from different angles:
+
+| Library   | Focus                                                   | Limitation                                                                                                             |
+| --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
+| **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
+| **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
+
+Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
+
+That’s the gap `ucon` fills.
+
+It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
+This allows you to:
+- Represent dimensional meaning explicitly (`Dimension`, `Vector`);
+- Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
+- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
+- Serialize and validate measurements with Pydantic integration;
+- Extend the system with custom unit registries and conversion families.
+
+Where Pint, Unum, and SymPy focus on _how_ to compute with units,
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
+```python
+from ucon import Number, units
+
+length = Number(quantity=5, unit=units.meter)
+time = Number(quantity=2, unit=units.second)
+
+speed = length / time     # ✅ valid: L / T = velocity
+invalid = length + time   # ❌ raises: incompatible dimensions
+```
+
+## Setup
+
+Simple:
+```bash
+pip install ucon
+```
+
+## Usage
+
+This sort of dimensional analysis:
+```
+ 2 mL bromine | 3.119 g bromine
+--------------x-----------------  #=> 6.238 g bromine
+      1       |  1 mL bromine
+```
+becomes straightforward when you define a measurement:
+```python
+from ucon import Number, Scale, Units, Ratio
+
+# Two milliliters of bromine
+two_mL_bromine = Number(unit=Units.liter, scale=Scale.milli, quantity=2)
+
+# Density of bromine: 3.119 g/mL
+bromine_density = Ratio(
+    numerator=Number(unit=Units.gram, quantity=3.119),
+    denominator=Number(unit=Units.liter, scale=Scale.milli),
+)
+
+# Multiply to find mass
+grams_bromine = two_mL_bromine * bromine_density
+print(grams_bromine)  # <6.238 gram>
+```
+
+Scale conversion is automatic and precise:
+
+```python
+grams_bromine.to(Scale.milli)  # <6238.0 milligram>
+grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+```
+
+---
+
+## Roadmap Highlights
+
+| Version | Theme | Focus |
+|----------|-------|--------|
+| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
+
+See full roadmap: [ROADMAP.md](./ROADMAP.md)
+
+---
+
+## Contributing
+
+Contributions, issues, and pull requests are welcome!
+Ensure `nox` is installed.
+```
+pip install -r requirements.txt
+```
+Then run the full test suite (agains all supported python versions) before committing:
+
+```bash
+nox -s test
+```
+---
+
+> “If it can be measured, it can be represented.
+If it can be represented, it can be validated.
+If it can be validated, it can be trusted.”

ucon-0.3.1rc2/ROADMAP.md

@@ -0,0 +1,222 @@
+# 🧭 ucon Roadmap
+
+> *A clear path from algebraic foundation to a stable 1.0 release.*
+
+---
+
+## 🪜 Current Version: **v0.3.0**
+
+Stable baseline for:
+- `ucon.core` (`Number`, `Scale`, `Ratio`)
+- `ucon.unit` (basic unit representation and composition)
+- `ucon.units` (canonical SI definitions)
+- Initial CI, testing, and packaging
+
+---
+
+## 🚀 v0.3.x — Dimensional Algebra (In Progress)
+
+### 🔹 Summary
+> Introduces `ucon.dimension` as the foundation for algebraic reasoning.
+
+### ✅ Goals
+- [x] Implement `Vector` and `Dimension` classes  
+- [x] Integrate dimensions into `Unit`  
+- [x] Refactor `ucon.units` to use dimensional definitions  
+- [ ] Publish documentation for dimensional operations  
+- [x] Verify uniqueness and hashing correctness across all Dimensions  
+- [ ] Redesign `Exponent` to support algebraic operations (`__mul__`, `__truediv__`, `to_base`, etc.)  
+- [ ] Remove redundant evaluated caching in favor of property-based computation  
+- [ ] Integrate `Scale` with Exponent for consistent prefix arithmetic  
+- [ ] Update `Number` and `Ratio` to use Exponent-driven scaling  
+- [ ] Add regression tests for prefix math (`kilo / milli → mega`, `2¹⁰ / 10³ → 1.024×`)  
+- [ ] Document Exponent/Scale relationship in developer guide 
+
+### 🧩 Outcomes
+- All units acquire explicit dimensional semantics  
+- Enables composable and type-safe dimensional operations  
+- Establishes the mathematical foundation for future conversions  
+- Unified algebraic foundation for all scaling and magnitude operations  
+- Precise, reversible cross-base math (`2ⁿ ↔ 10ᵐ`)  
+- Simplified, consistent `Scale` and `Number` behavior  
+- Ready for integration into the conversion engine (`ucon.conversions`)
+
+---
+
+## ⚙️ v0.4.x — Conversion System Foundations
+
+### 🔹 Summary
+> Implements unified conversion engine for standard, linear, and affine conversions.
+
+### ✅ Goals
+- [ ] Introduce `ucon.conversions` registry keyed by `Dimension`  
+- [ ] Add support for `standard`, `linear`, and `affine` conversion types  
+- [ ] Implement `.to(target_unit)` for `Number`  
+- [ ] Round-trip validation for reversible conversions  
+- [ ] Extend tests to include temperature, pressure, and base SI conversions  
+
+### 🧩 Outcomes
+- Unified conversion taxonomy  
+- Reversible, dimension-checked conversions  
+- Forms the basis for nonlinear and domain-specific conversion families  
+
+---
+
+## 🧱 v0.5.x — Unit Systems & Registries
+
+### 🔹 Summary
+> Introduces an extensible registry system for custom units and aliases.
+
+### ✅ Goals
+- [x] Implement `have(name)` membership check  
+- [ ] Add `UnitSystem` abstraction  
+- [ ] Support `registry.add(unit)` and dynamic system registration  
+- [ ] Validate alias uniqueness and collision prevention  
+- [ ] Include examples for user-defined unit extensions  
+
+### 🧩 Outcomes
+- Registry-based extensibility for domain-specific systems  
+- Dynamic unit registration and discovery  
+- Groundwork for plugin-style system extensions  
+
+---
+
+## 🧪 v0.6.x — Nonlinear & Specialized Conversions
+
+### 🔹 Summary
+> Adds support for logarithmic, fractional, and other specialized dimensionless conversions.
+
+### ✅ Goals
+- [ ] Extend conversion registry schema with `"nonlinear"` family  
+- [ ] Add `to_base` / `from_base` lambdas for function-based mappings  
+- [ ] Define sample nonlinear conversions (`decibel`, `bel`, `pH`)  
+- [ ] Add tolerance-aware tests for nonlinear conversions  
+- [ ] Introduce structured dimensionless unit family (`radian`, `percent`, `ppm`, `count`, etc.)
+- [ ] Define canonical dimensionless subtypes for angular, fractional, and count semantics
+- [ ] Ensure automatic collapse of equivalent units (`m/m → none`, `J/J → none`) via Ratio
+
+### 🧩 Outcomes
+- Support for function-based (nonlinear) physical conversions  
+- Unified algebraic framework across all conversion types  
+- Rich, semantically meaningful representation of dimensionless quantities
+- Enables acoustics (dB), geometry (rad, sr), statistics (probability), and fractional scales (%, ppm)
+  
+---
+
+## 🧰 v0.7.x — Testing, Developer Experience, & API Polish
+
+### 🔹 Summary
+> Strengthens tests, developer ergonomics, and runtime feedback.
+
+### ✅ Goals
+- [ ] Reach 95%+ test coverage  
+- [ ] Add property-based tests for dimensional invariants  
+- [ ] Improve error reporting, `__repr__`, and exception messaging  
+- [ ] Validate public API imports and maintain consistent naming  
+- [ ] Add CI coverage reports and build badges  
+
+### 🧩 Outcomes
+- Reliable, developer-friendly foundation  
+- Consistent runtime behavior and output clarity  
+- Prepares API for public documentation and 1.0 freeze  
+
+---
+
+## 🧩 v0.8.x — Pydantic Integration
+
+### 🔹 Summary
+> Introduces seamless integration with **Pydantic v2**, enabling validation, serialization, and typed dimensional models.
+
+### ✅ Goals
+- [ ] Define Pydantic-compatible field types (`UnitType`, `NumberType`)  
+- [ ] Implement `__get_pydantic_core_schema__` for Units and Numbers  
+- [ ] Support automatic conversion/validation for user-defined models  
+- [ ] Add YAML / JSON encoding for quantities (`Number(unit="meter", quantity=5)`)  
+- [ ] Add Pydantic-based examples (API config, simulation parameters)  
+
+### 🧩 Outcomes
+- Native validation and serialization for dimensioned quantities  
+- Enables safe configuration in data models and APIs  
+- Bridges `ucon`’s algebraic model with modern Python typing ecosystems  
+
+---
+
+## 📘 v0.9.x — Documentation & RC Phase
+
+### 🔹 Summary
+> Completes documentation, finalizes examples, and preps release candidates.
+
+### ✅ Goals
+- [ ] Write comprehensive README and developer guide  
+- [ ] Publish API reference docs (Sphinx / MkDocs)  
+- [ ] Add SymPy / Pint comparison appendix  
+- [ ] Freeze and document all public APIs  
+- [ ] Publish one or more release candidates (RC1, RC2)  
+
+### 🧩 Outcomes
+- Complete public-facing documentation  
+- API frozen and versioned for stability  
+- Ready for final testing and validation before 1.0  
+
+---
+
+## 🏁 v1.0.0 — Stable, Introspective Core
+
+### 🔹 Summary
+> First major release: a unified algebra for composable, type-safe, and semantically clear unit conversion.
+
+### ✅ Goals
+- [ ] Tag and release to PyPI  
+- [ ] Validate packaging and dependency metadata  
+- [ ] Include examples and tutorials in docs  
+- [ ] Announce 1.0 on GitHub and PyPI  
+
+### 🧩 Outcomes
+- Stable, well-tested release  
+- Fully type-safe and validated core  
+- Production-ready for integration into scientific and engineering workflows  
+
+---
+
+## 🧠 Post-1.0 Vision
+
+| Future Direction | Description |
+|------------------|-------------|
+| **Graph-based conversion paths** | Automatically discover multi-hop conversions between compatible units |
+| **Type-safe generics** | `Number[Dimension.length]` support for type checking and IDE hints |
+| **Symbolic bridge to SymPy** | Export units and expressions for symbolic manipulation |
+| **Visualization** | Dimensional relationship graphs and dependency trees |
+| **Plugin architecture** | Load conversions and systems dynamically (YAML/JSON plugins) |
+
+---
+
+## 🗓️ Milestone Summary
+
+| Version | Theme | Key Focus | Target | Status |
+|----------|--------|------------|---------|---------|
+| **0.3.0** | Dimensional Algebra | Introduce `ucon.dimension` | **Nov 2025** | 🚧 In Progress |
+| **0.4.0** | Conversion Engine | Standard, linear, affine conversions | **Jan 2026** | ⏳ Planned |
+| **0.5.0** | Unit Systems & Registries | Extensible registry system | **Mar 2026** | ⏳ Planned |
+| **0.6.0** | Nonlinear Conversions | Logarithmic / exponential families | **May 2026** | ⏳ Planned |
+| **0.7.0** | Testing & API Polish | Coverage, ergonomics, stability | **Jul 2026** | ⏳ Planned |
+| **0.8.0** | 🧩 **Pydantic Integration** | Typed validation, serialization | **Sep 2026** | 🧭 Newly Added |
+| **0.9.x** | Documentation & RC | Freeze API, publish docs, RCs | **Nov 2026** | ⏳ Planned |
+| **1.0.0** | Stable Release | Publish production-ready core | **Jan 2027** | 🔮 Future |
+
+---
+
+### ✨ Guiding Principle
+
+> “If it can be measured, it can be represented.  
+> If it can be represented, it can be validated.  
+> If it can be validated, it can be trusted.”
+
+---
+
+### 💡 Why Pydantic Integration Matters
+
+- Enables **runtime validation** of dimensional correctness:
+  ```python
+  class Config(BaseModel):
+      length: NumberType[Dimension.length]
+      time: NumberType[Dimension.time]