ucon 0.3.5rc1__tar.gz → 0.4.0__tar.gz

{ucon-0.3.5rc1 → ucon-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.5rc1
+Version: 0.4.0
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -55,8 +55,8 @@ Dynamic: summary
 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.)
+- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - 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.
@@ -70,20 +70,24 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 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²`). |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the 8-component exponent tuple of a physical quantity's base dimensions (T, L, M, I, Θ, J, N, B). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Dimension`**               | `ucon.core`                             | 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).         |
 | **`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.    |
+| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
+| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
+| **`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).                     |
-| **`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.).                               |                                                   |
+| **`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.                                  |
+| **`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.).                             |
 
 ### Under the Hood
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/5df6a7fb2a6426ee6804096c092c10bed1b30b6f/ucon.data-model_v040.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -91,24 +95,22 @@ Python already has mature libraries for handling units and physical quantities
 
 | 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. |
+| **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.
+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:
+`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
 
@@ -136,7 +138,8 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, Units, Ratio
+from ucon import Number, Scale, units
+from ucon.quantity import Ratio
 
 # Two milliliters of bromine
 mL = Scale.milli * units.liter
@@ -149,27 +152,52 @@ bromine_density = Ratio(
 )
 
 # Multiply to find mass
-grams_bromine = two_mL_bromine * bromine_density
-print(grams_bromine)  # <6.238 gram>
+grams_bromine = bromine_density.evaluate() * two_mL_bromine
+print(grams_bromine)  # <6.238 g>
 ```
 
-Scale conversion is automatic and precise:
+Scale prefixes compose naturally:
+```python
+km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
+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:
 ```python
-grams_bromine.to(Scale.milli)  # <6238.0 milligram>
-grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+from ucon import units, Scale
+
+# Callable syntax: unit(quantity) → Number
+height = units.meter(1.8)
+speed = (units.mile / units.hour)(60)
+
+# Convert between units
+height_ft = height.to(units.foot)
+print(height_ft)  # <5.905... ft>
+
+# Scaled units work too
+km = Scale.kilo * units.meter
+distance = km(5)
+distance_mi = distance.to(units.mile)
+print(distance_mi)  # <3.107... mi>
 ```
 
 ---
 
 ## 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 |
+| Version | Theme | Focus | Status |
+|----------|-------|--------|--------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()`, callable units | 🚧 In Progress |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 
@@ -182,13 +210,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (agains all supported python versions) before committing:
+Then run the full test suite (against all supported python versions) before committing:
 
 ```bash
 nox -s test
 ```
 ---
 
-> “If it can be measured, it can be represented.
+> "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.”
+If it can be validated, it can be trusted."

{ucon-0.3.5rc1 → ucon-0.4.0}/README.md

@@ -18,8 +18,8 @@
 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.)
+- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - 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.
@@ -33,20 +33,24 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 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²`). |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the 8-component exponent tuple of a physical quantity's base dimensions (T, L, M, I, Θ, J, N, B). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Dimension`**               | `ucon.core`                             | 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).         |
 | **`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.    |
+| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
+| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
+| **`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).                     |
-| **`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.).                               |                                                   |
+| **`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.                                  |
+| **`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.).                             |
 
 ### Under the Hood
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/5df6a7fb2a6426ee6804096c092c10bed1b30b6f/ucon.data-model_v040.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -54,24 +58,22 @@ Python already has mature libraries for handling units and physical quantities
 
 | 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. |
+| **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.
+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:
+`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
 
@@ -99,7 +101,8 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, Units, Ratio
+from ucon import Number, Scale, units
+from ucon.quantity import Ratio
 
 # Two milliliters of bromine
 mL = Scale.milli * units.liter
@@ -112,27 +115,52 @@ bromine_density = Ratio(
 )
 
 # Multiply to find mass
-grams_bromine = two_mL_bromine * bromine_density
-print(grams_bromine)  # <6.238 gram>
+grams_bromine = bromine_density.evaluate() * two_mL_bromine
+print(grams_bromine)  # <6.238 g>
 ```
 
-Scale conversion is automatic and precise:
+Scale prefixes compose naturally:
+```python
+km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
+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:
 ```python
-grams_bromine.to(Scale.milli)  # <6238.0 milligram>
-grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+from ucon import units, Scale
+
+# Callable syntax: unit(quantity) → Number
+height = units.meter(1.8)
+speed = (units.mile / units.hour)(60)
+
+# Convert between units
+height_ft = height.to(units.foot)
+print(height_ft)  # <5.905... ft>
+
+# Scaled units work too
+km = Scale.kilo * units.meter
+distance = km(5)
+distance_mi = distance.to(units.mile)
+print(distance_mi)  # <3.107... mi>
 ```
 
 ---
 
 ## 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 |
+| Version | Theme | Focus | Status |
+|----------|-------|--------|--------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()`, callable units | 🚧 In Progress |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 
@@ -145,13 +173,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (agains all supported python versions) before committing:
+Then run the full test suite (against all supported python versions) before committing:
 
 ```bash
 nox -s test
 ```
 ---
 
-> “If it can be measured, it can be represented.
+> "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.”
+If it can be validated, it can be trusted."

ucon-0.4.0/ROADMAP.md

@@ -0,0 +1,244 @@
+# 🧭 ucon Roadmap
+
+> *A clear path from algebraic foundation to a stable 1.0 release.*
+
+---
+
+## 🪜 Current Version: **v0.4.0** (in progress)
+
+Building on v0.3.5 baseline:
+- `ucon.core` (`Dimension`, `Scale`, `Unit`, `UnitFactor`, `UnitProduct`, `Number`, `Ratio`)
+- `ucon.maps` (`Map`, `LinearMap`, `AffineMap`, `ComposedMap`)
+- `ucon.graph` (`ConversionGraph`, default graph, `get_default_graph()`, `using_graph()`)
+- `ucon.units` (SI + imperial + information units, callable syntax)
+- Callable unit API: `meter(5)`, `(mile / hour)(60)`
+- `Number.simplify()` for base-scale normalization
+- `Dimension.information` with `units.bit`, `units.byte`
+
+---
+
+## ✅ v0.3.x — Dimensional Algebra (Complete)
+
+### 🔹 Summary
+> Introduces dimensional algebra and establishes the Unit/Scale separation
+> that underpins all downstream work.
+
+### ✅ Goals
+- [x] Implement `Vector` and `Dimension` classes
+- [x] Integrate dimensions into `Unit`
+- [x] Refactor `ucon.units` to use dimensional definitions
+- [x] Publish documentation for dimensional operations
+- [x] Verify uniqueness and hashing correctness across all Dimensions
+- [x] Redesign `Exponent` to support algebraic operations (`__mul__`, `__truediv__`, `to_base`, etc.)
+- [x] Remove redundant evaluated caching in favor of property-based computation
+- [x] Integrate `Scale` with Exponent for consistent prefix arithmetic
+- [x] Add regression tests for prefix math (`kilo / milli → mega`, `2¹⁰ / 10³ → 1.024×`)
+- [x] Separate `scale` from `Unit`; delegate to `UnitFactor(unit, scale)`
+- [x] Introduce `UnitProduct` with `fold_scale()` and `_residual_scale_factor`
+- [x] `Number.value` returns as-expressed magnitude; `_canonical_magnitude` folds scale internally
+- [x] Remove dead code and unify naming (`UnitFactor`, `UnitProduct`) across all docstrings and repr
+
+### 🧩 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
+- Clean Unit/Scale separation: `Unit` is an atomic symbol, `UnitFactor` pairs it with a `Scale`
+- `UnitProduct` correctly tracks residual scale from cancelled units
+- Type system is ready for a `ConversionGraph` to be built on top
+
+---
+
+## ⚙️ v0.4.x — Conversion System Foundations (In Progress)
+
+### 🔹 Summary
+> Implements unified conversion engine for standard, linear, and affine conversions.
+> Introduces callable unit API for ergonomic quantity construction.
+
+### ✅ Goals
+- [x] Introduce `ConversionGraph` registry keyed by `Dimension`
+- [x] Add support for `standard`, `linear`, and `affine` conversion types
+- [x] Implement `Number.to(target_unit)` conversion API
+- [x] Scale-only conversions short-circuit without graph lookup
+- [x] Composite-to-composite conversion via per-component decomposition
+- [x] Round-trip validation for reversible conversions (inverse maps)
+- [x] Callable unit syntax: `meter(5)`, `(mile / hour)(60)`
+- [x] Default graph with common SI and imperial conversions
+- [x] Imperial units: `foot`, `mile`, `yard`, `inch`, `pound`, `ounce`, `fahrenheit`, `gallon`
+- [x] `Number.simplify()` — Express in base scale
+- [x] `Dimension.information` with `units.bit` and `units.byte`
+- [x] `Vector` extended to 8 components (added B for information)
+- [x] Information unit conversions in default graph (byte ↔ bit)
+- [ ] Extend tests to include temperature, pressure, and base SI conversions
+- [ ] Document Exponent/Scale relationship in developer guide
+
+### 🧩 Outcomes
+- Unified conversion taxonomy
+- Reversible, dimension-checked conversions
+- Scale-aware graph that leverages the `Unit`/`UnitFactor` separation from v0.3.x
+- Ergonomic API: units are callable, returning `Number` instances
+- Information dimension support (bit, byte) with binary prefix compatibility
+- `Number.simplify()` for expressing quantities in base scale
+- 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 | Status |
+|----------|--------|------------|---------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| **0.4.0** | Conversion Engine | `ConversionGraph`, `Number.to()`, callable units | 🚧 In Progress |
+| **0.5.0** | Unit Systems & Registries | Extensible registry system | ⏳ Planned |
+| **0.6.0** | Nonlinear Conversions | Logarithmic / exponential families | ⏳ Planned |
+| **0.7.0** | Testing & API Polish | Coverage, ergonomics, stability | ⏳ Planned |
+| **0.8.0** | Pydantic Integration | Typed validation, serialization | ⏳ Planned |
+| **0.9.x** | Documentation & RC | Freeze API, publish docs, RCs | ⏳ Planned |
+| **1.0.0** | Stable Release | Publish production-ready core | 🔮 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]
+  ```