Release Notes 0.4.2 - Stochastic Hotfix

A critical hotfix release following the 0.4.x series. This update addresses a fatal initialization bug in the stochastic physics engine and enhances the framework's internal documentation for better IDE discoverability.

Stochastic Hotfix (AttributeError)

We discovered that in v0.4.1, the RandomState engine would fail with an AttributeError if a user attempted to generate random values without first calling ptn.random.seed().

• The Fix: Re-implemented the __init__ constructor for RandomState to ensure the internal BitGenerator (_rng) is instantiated immediately upon package import.

Metadata & Documentation Refinery

• Rich Docstrings: Overhauled the package-level documentation in __init__.py. When inspecting Phaethon in high-end IDEs (VS Code, PyCharm), you will now see a structured architectural overview of the framework's core modules (Units, Schema, Dataset, ML, PINNs) along with clickable documentation links.

Release Notes 0.4.1 - Stability, Type Refinery & Isolated Stochastic Engine

This release marks a significant milestone in framework stability and developer experience. We've tackled the "Ouroboros" recursion bugs, refined our static typing engine, and deployed a completely isolated stochastic physics module.

Algebraic Stability

• Recursion Guard: Fixed the Ouroboros bug where complex unit synthesis could trigger infinite recursion.
• Context Preservation: Fixed the "Amnesia" bug; environmental contexts (like FX rates) now persist through every step of the conversion pipeline.
• Strict Semantics: Better guardrails for bitwise operations on anonymous units.

Stochastic Physics Engine

We have overhauled phaethon.random to move away from global NumPy state.

• Isolated RNG: Using np.random.default_rng(), your physics simulations are now thread-safe and reproducible via ptn.random.seed().
• New Methods: Added randint, choice, shuffle, and permutation—all natively aware of physical dimensions.

Developer Experience (DX)

• Stub Refinery: New .pyi files provide perfect IDE highlighting (Variables appear Blue/Callable) with full parameter autocompletion.
• Ragged Masking: phaethon.Dataset now supports advanced boolean masking for complex data filtering.
• SEO & Docs: Fixed social preview cards on ReadTheDocs for better documentation sharing.

Release Notes 0.4.0 - The Sci-ML, Neural PDEs, and Rust Parsing Overhaul

Version 0.4.0 represents the most massive architectural leap in Phaethon's history. The framework has evolved from a dimensional data pipeline into a comprehensive Scientific Machine Learning (Sci-ML) ecosystem. We have deeply integrated PyTorch and Scikit-Learn, deployed a zero-allocation Rust backend, and expanded our native physics capabilities to encompass complex differential calculus and linear algebra.

Deep PyTorch Integration (Neural PDEs & PINNs)

Phaethon now ships with the phaethon.pinns module. At its core is the PTensor—a strict PyTorch autograd subclass injected with dimensional DNA. You can now execute native differential calculus (pnn.grad, pnn.laplace, pnn.div, pnn.curl) across the computational graph, automatically synthesizing derivative physical units.
Furthermore, training loops are now guarded by Physics-Informed Loss Tribunals (ResidualLoss and AxiomLoss), violently enforcing equation balancing and physical boundaries during backpropagation. The update also introduces Spectral Convolutions (SpectralConv1d) and SVD projection layers (BuckinghamPi) for advanced Neural Operator architectures.

Classic Sci-ML & Scientific Computing

For traditional machine learning, we've introduced Scikit-Learn Meta-Estimators (DimensionalEstimator, AxiomValidator) that automatically infer training dimensions, safely strip units for high-speed C/Cython execution, and resurrect exact physical units on final predictions.
The newly introduced phaethon.linalg and phaethon.random modules extend physical tracking into matrix inversions, determinants, and stochastic distributions natively built atop NumPy.

Rust-Powered Data Engineering & Polyglot I/O

The heavy string-extraction layer has been rewritten entirely in Rust via PyO3/Maturin (phaethon._rust_core). This custom backend bypasses the Python GIL, natively executing min/max physical boundaries and semantic clipping directly at the memory level for extreme-speed parsing.
Once normalized, data pipelines can be seamlessly bridged into Deep Learning via Schema.astensor(), which automatically factorizes semantic string concepts into integer tensors. Finally, the new phaethon.Dataset securely serializes complex physical tensors to disk using .phx archives (equipped with cryptographic SHA-256 integrity validation), .parquet, and .h5 formats.

Breaking Changes & Migration

• Python 3.11+: Phaethon now drops support for Python 3.10 to leverage advanced typing and structural pattern matching.
• Build System: The package is now compiled via maturin instead of setuptools.
• Deprecation: The legacy list syntax in @axiom.derive(mul=[...], div=[...]) is deprecated in favor of direct mathematical metaclass synthesis.

Release Notes 0.3.1 - Polars Optional Dependency Hotfix

This is a rapid hotfix release addressing a critical startup crash for users operating in Pandas-only environments.

Bug Fixes

• fix(compat): While Polars was correctly defined as an optional dependency in pyproject.toml, internal engine imports were previously unguarded. We have introduced strict HAS_POLARS runtime flags across the compatibility and backend layers. Phaethon now boots flawlessly regardless of which backend (Pandas or Polars) is present in the host environment.

Release Notes 0.3.0 - The Industrial FinTech, Majestic DX Update & Polars Support

This release marks a major architectural leap, consolidating high-performance data engineering with physical, financial, and semantic intelligence. Version 0.3.0 introduces native Polars support via Rust-backed expressions, a multi-tier configuration hierarchy, massive dimensional expansions, and a complete overhaul of Developer Experience (DX) utilizing Python 3.10+ declarative standards.

High-Performance Backends

• feat(polars): Introduced native support for polars.DataFrame as an optional dependency (installable via [polars] or [all]). Phaethon now implements a backend-agnostic protocol that detects Polars objects and executes normalization using high-speed Polars Expressions (pl.Expr).
• feat(engine): Developed a vectorized NumPy bridge via map_batches for Polars, allowing complex physical axiom validation to run at near-native speeds while maintaining 100% mathematical parity with the Pandas engine.
• feat(engine): Implemented a "NaN Sweeper" and "Struct Wrapper" logic for the Polars backend to ensure that regex-rejected strings and axiom violations are correctly neutralized to null values, matching the behavior of the established Pandas engine.

Dimensional Core & Tensor Algebra

• feat(api): Overhauled the Fluent Data Engineering API (ptn.convert().to().use().context().resolve()). This chainable, lazily-evaluated builder pattern now fully supports lists of Phaethon objects, N-dimensional NumPy tensors, mixed-unit iterables, and raw scalars natively without Python loop overheads on vectorized operations.
• feat(api): Implemented strict calculation engine interception via .use(dtype=...). The pipeline automatically handles safe upcasting to high-precision Decimal (bypassing native Python float degradation via string casting) and strict downcasting to float64 for raw performance before dimensional algebra is executed.
• feat(api): Upgraded OOP Conversion Interface. The BaseUnit.to() method now accepts localized, on-the-fly context injections (obj.to(Target, context={...})). This allows safe, isolated financial conversions without mutating the underlying object's state or relying on global configs.
• feat(tensor): Integrated native NumPy proxying directly into BaseUnit. Instances wrapping NumPy arrays now natively support array slicing (__getitem__), properties (shape, ndim, T), and shape manipulation (reshape, flatten) while preserving their physical unit wrappers.
• feat(vmath): Added native vectorized statistical methods to BaseUnit (sum, mean, max, min). Reductions along specific axes now correctly return structurally instantiated physical tensors rather than naked float64 arrays.
• feat(algebra): Engineered Syntactic Sugar for Cross-Entity Operations and Dimensionless Collapse. The physics engine seamlessly executes mathematics between Instances and naked Classes implicitly. Furthermore, operations that mathematically cancel out (e.g., u.Meter / u.Meter) now intelligently collapse into a dimensionless BaseUnit object rather than a primitive float, preserving strict OOP API contracts.
• feat(algebra): Introduced Class-Level Hierarchy Comparisons (<, >, <=, >=). Developers can inherently sort and validate unit hierarchies without instantiating them (e.g., u.Gigabyte > u.Megabyte natively evaluates to True).
• feat(algebra): Engineered Dynamic Context Inheritance for Derived Units. Metaclass-synthesized units (e.g., Euro / Gram) now dynamically evaluate their base multipliers at runtime. This guarantees that complex econo-physics units instantly react to real-time context injections without suffering from static multiplier lock-in.
• feat(operators): Implemented advanced physics dunder methods. The engine now fully supports Matrix Multiplication / Dot Products (@) for dimensional synthesis, Floor Division (//) for discrete quantization, Modulo (%) for phase/cycle resets, and vector manipulations (-, +, abs, round).
• fix(engine): Overhauled the _normalize_types mathematical router. Eliminated forced Decimal casting ("The Decimal Dictatorship"). The engine now dynamically preserves native float64 for maximum computational speed, only escalating to high-precision Decimal mathematics when explicitly requested by the user.
• fix(security): Eradicated Global Mutable State in the dimensional registry. The _DIMENSIONAL_DNA is now strictly encapsulated within a private singleton (_PhysicsGenome) utilizing Python name mangling (__dna), preventing accidental global namespace pollution or malicious mutation of physical axioms.

Semantic Intelligence & Machine Learning

• feat(semantics): Introduced the Declarative Semantic Transformation API (ptn.Ontology, ptn.Concept, ptn.SemanticState, ptn.Condition). Users can now map discrete raw strings to canonical concepts, or classify continuous physical vectors into discrete logical states strictly bounded by dimensional physics (e.g., mapping u.Celsius ranges into "Cold", "Warm", "Hot").
• feat(semantics): Integrated RapidFuzz (now promoted to a mandatory core dependency) for Vectorized Semantic Matching. Added fuzzy_match=True and confidence thresholds to ptn.Field, enabling the engine to automatically auto-correct typos in categorical/ontology data using C++ string metrics.
• feat(schema): Introduced ptn.DerivedField and ptn.col(). Users can now synthesize new Machine Learning features (e.g., computing Power from Voltage and Current) safely across dimensional bounds via a custom Abstract Syntax Tree (AST) evaluator.
• feat(schema): Implemented Schema.blueprint(). Generates a strict, JSON-serializable TypedDict structural blueprint of the schema, perfect for automated Data Catalogs and enterprise Data Governance.

Tiered Configuration & Industrial Quality

• feat(config): Engineered a 3-Tier Configuration Hierarchy for managing engine state (Global -> Block -> Field). This allows for thread-safe localization (decimal marks/thousands separators) and dynamic alias management without global state pollution.
• feat(schema): Added Physics-Aware Boundaries (min, max) to ptn.Field. The engine now automatically performs cross-unit conversion before evaluating boundary constraints (e.g., rejecting "120 lbs" against a "50 kg" limit).
• feat(schema): Introduced Dimensional Imputation (impute_by) and Statistical Anomaly Rejection (outlier_std). Users can rescue NaN values using statistical methods ("mean", "median", "mode") or physically identify and neutralize data points exceeding a specified Standard Deviation (Z-Score).
• feat(engine): Expanded on_error='clip' Behavior. The pipeline now correctly forces invalid numbers to strictly attach to the nearest mathematical bound defined by either the user's Schema min/max or the unit's intrinsic @axiom.bound limit across both Pandas and Polars backends.
• feat(engine): Introduced "God Mode" (ignore_axiom_bound=True). Developers can now strategically override and bypass all intrinsic physical laws (e.g., allowing temperatures below Absolute Zero) for experimental testing and simulation logic, deployable via Field, Block (using), or Global Config.

Majestic Developer Experience (DX) & Typing Overhaul

• feat(dx): Engineered "Type-State" Generic Overloads for the Fluent API. The _ConversionBuilder is now a true Generic[_T_Out]. Deployed 5 precise @overload signatures for convert() and 16 massive overloads for .use() to completely eradicate Any types. IDEs now perfectly predict the exact structural return type of .resolve() (locking to Decimal, list[BaseUnit], list[float], str, or np.ndarray). Also refactored .use() parameters: renamed mode to dtype and format to out for a more native Data Science feel.
• feat(dx): Implemented the IDE Tooltip Hack (__init__ routing). Docstrings for highly complex declarative classes (ptn.Field, ptn.Concept, ptn.Condition) have been surgically routed to their __init__ methods. Strict IDEs (VS Code/Pylance) will now reliably render comprehensive parameter tooltips during instantiation.
• fix(dx): Eliminated Union Method Pollution. By surgically separating scalar, iterable, and array type-hints at the convert() entry point, strict IDEs (Pylance/Mypy) no longer hallucinate NumPy array methods on simple floating-point scalars.
• refactor(typing): Upgraded minimum requirement to Python 3.10+. The entire codebase has been refactored to utilize PEP 604 (| operator) and native types, discarding legacy typing modules for an incredibly clean, "Majestic" code structure.
• refactor(typing): Enforced absolute boundary separation between Metaclass (Blueprint) and Instance operations. Purged Any fallbacks in _PhaethonUnitMeta return types. Strict IDEs now structurally recognize dynamically synthesized units as formal Classes (semantic highlighting), fully activating constructor autocompletion.
• refactor(typing): Formalized unified type aliases (ConvertibleInput, ContextDict, ErrorAction, ImputeMethod, etc) across the physics engine. This provides crystal-clear signature documentation for scalar, NumPy array, and unit instance inputs.
• feat(typing): Added PEP 561 py.typed compliance. IDEs (VS Code, PyCharm) and strict Type Checkers (Mypy, Pylance) now fully recognize Phaethon's complex @overload signatures, TypeVar generics, and Protocol bindings.
• fix(typing): Resolved strict type hinting for core properties (.mag, .exact) using explicit unions (float | np.ndarray | Decimal), successfully activating full IDE intelligence and autocomplete for NumPy array methods.
• feat(dx): Implemented Dynamic Metaclass Docstrings. Dynamically synthesized classes (e.g., `Me...

Release Notes 0.2.3 - The Quantum Precision Patch

This release solidifies Phaethon's core physics engine and massively upgrades the Developer Experience (DX). By eliminating extreme-scale float truncation and introducing rigorous property-based parity benchmarks, Phaethon now guarantees absolute mathematical precision from quantum levels to astronomical masses.

Core Physics & Precision

• fix(engine): Eradicated the default prec=9 float truncation from the core _PhaethonEngine. The physics engine now retains absolute native float64 precision during internal calculations. This resolves a critical underflow vulnerability where microscopic quantum values (e.g., eV to Joules) or astronomical scales were incorrectly truncated to 0.0.
• fix(mass): Resolved semantic unit collisions in the mass dimension. Corrected the symbol for Planck Mass from the standard proton notation (m_p) to the correct scientific notation (m_P), and purged the "gr" alias from the Gram registry to prevent namespace conflicts with the Grain unit.

Enterprise Developer Experience (DX)

• feat(typing): Upgraded the core registry (registry.py) with strict Type['BaseUnit'] forward references and @overload typing paradigms for methods like unitsin(). This unlocks full IDE autocomplete (IntelliSense) for dynamically resolved unit classes, massively accelerating developer workflows and reducing runtime typing errors.

Benchmarks & Parity Validation

• test(benchmarks): Engineered and deployed a robust property-based testing suite (benchmarks/test_pint_parity.py) utilizing the hypothesis framework. Phaethon has now empirically proven 100% mathematical parity against the industry-standard Pint library across 300+ randomized extreme-value cross-conversions, whilst successfully parsing 65+ specialized units that Pint natively fails to process due to string hyphenation bugs.

Release Notes 0.2.2 - Architectural Cleansing & Trusted Deployment

Following the Grand Pivot, this release focuses on deep architectural hygiene, entirely purging legacy references from the codebase, and modernizing the DevOps pipeline. Phaethon now boasts a fully automated, military-grade CI/CD publishing system.

Core Architecture Refactoring

• refactor(core): Conducted a deep codebase sweep to eradicate all legacy "Chisa" zombie references. Renamed internal engine classes (e.g., ChisaEngine is now PhaethonEngine) and updated all docstrings and internal logging mechanisms to reflect the new identity.
• fix(imports): Standardized all internal and external example scripts to strictly utilize the import phaethon as ptn convention, eliminating any lingering ModuleNotFoundError issues from the pivot.

Ecosystem & CI/CD Automation

• ci(actions): Engineered a fully automated Continuous Deployment (CD) pipeline using GitHub Actions (publish.yml).
• sec(oidc): Integrated PyPI Trusted Publishing (OIDC). Phaethon deployments are now completely passwordless and tokenless, eliminating secret-leak vulnerabilities and ensuring that only tagged GitHub Releases can securely trigger PyPI package generation.

Documentation Polish

• docs(readme): Completely overhauled the primary README.md and the advanced_physics.md documentation to feature the new namespace.
• docs(examples): Renamed and refactored the entire interactive tutorial suite. Google Colab notebooks (now T01_Phaethon_Fundamentals.ipynb and T02_Phaethon_RealWorld_Workflow.ipynb) have been updated to ensure new users can seamlessly test the framework without local installation breaking.

Release Notes 0.2.1 - The Grand Pivot (Renamed to Phaethon)

This release marks a monumental architectural pivot. The project has officially transitioned from its legacy identity ("Chisa") to Phaethon. This rebrand definitively aligns the framework with its true purpose: taming massive, fast-moving Data Engineering pipelines with strict, logic-driven physical axioms.

The Namespace Takeover

• chore(rebrand): The package has been globally renamed to phaethon on PyPI. The legacy chisa package has been deprecated. All current and future development, including the vectorization engine and declarative schemas, will exclusively continue under the Phaethon namespace.
• feat(alias): Established ptn as the official, standardized import alias (e.g., import phaethon as ptn). This explicitly prevents namespace collisions and ensures rapid, phonetic developer typing without overlapping with existing tools like PyTorch (pt) or Matplotlib (plt).

Core Engine Continuity

• refactor(migration): Successfully migrated 100% of the core Axiom Engine, Metaclass Algebra, and Vectorization logic from the v0.2.0 build into the new Phaethon core. All DataFrame normalization speeds (~0.046 seconds per 100k rows) remain perfectly intact.

Release Notes 0.2.0 - Declarative Schemas & Unit-Safe Data Pipelines

This major release officially evolves Chisa into a Unit-Safe Data Pipeline Schema, introducing declarative validation for Pandas DataFrames, unparalleled error intelligence, and pure object-oriented Metaclass Algebra.

Declarative Data Schemas

• feat(schema): Introduced chisa.Schema and chisa.Field for strict, declarative data normalization.
  • Allows Data Engineers to ingest messy, heterogeneous Pandas DataFrames and convert them into clean, dimensionally-validated datasets natively.
• feat(integration): Officially elevated Pandas (pandas>=2.0.0) to a core dependency alongside NumPy, unlocking native vectorized Boolean masking and high-speed schema execution.
• feat(schema): Added smart metadata management with keep_unmapped=True and drop_raw=True to seamlessly drop dirty columns while preserving vital pipeline tracking IDs.
• feat(schema): Implemented Lifecycle Hooks (@cs.pre_normalize and @cs.post_normalize) allowing developers to inject custom domain logic directly into the validation flow.
• feat(parsing): Massively expanded unit aliases across all dimensions to supercharge the parse_string=True method, allowing Chisa to autonomously capture and standardize highly irregular textual data.

Smart Error Intelligence

• feat(exceptions): Introduced NormalizationError. Data pipelines no longer just crash silently. When on_error='raise' is triggered, Chisa now provides unparalleled Developer Experience (DX) by printing pinpoint debugging context:
  • Exact index of the failure.
  • Expected physical dimension vs. received anomaly.
  • Snippet of the raw dirty string.
  • Actionable suggestions to fix the data or adjust schema rules.

The Axiom Engine & Self-Learning Registry

• feat(metaclass): Introduced direct Object-Oriented Metaclass Algebra. Users can now synthesize physical laws by directly dividing/multiplying classes (e.g., @axiom.derive(u.Kilogram / u.KilowattHour)).
• feat(registry): Implemented a "Self-Learning" DNA injection mechanism. The UnitRegistry now dynamically listens to __init_subclass__ and autonomously registers new dimensional signatures and custom aliases at runtime.
  • Impact: Custom dimensions (like ESG Carbon Metrics) synthesized in scripts are instantly recognized by Schema.normalize().

Fluent API Flexibility

• fix(fluent): Patched a logic trap in the convert() engine's internal _compute() method.
  • The Fluent API can now seamlessly handle all four permutations of input targets without crashing: String-to-String ('km' -> 'm'), Class-to-String (u.Kilometer -> 'm'), String-to-Class ('km' -> u.Meter), and Class-to-Class (u.Kilometer -> u.Meter).

Documentation Overhaul

• docs(readme): Completely restructured the documentation architecture.
  • The main README.md is now strictly focused on Data Engineering (Schemas, Pipeline Hooks, Vectorization, and Pandas integration). Deep-dive scientific computing features have been cleanly migrated to docs/advanced_physics.md.
• docs(examples): Completely overhauled the examples/ directory with 14 brutal, real-world Data Engineering scripts (e.g., Cloud Compute Billing, ESG Carbon Tracking, Sensor Drift Neutralization).
• docs(notebooks): Re-architected the interactive Google Colab notebooks. T01 covers core fundamentals/Schemas, while T02 provides a masterclass on cleaning a dirty IoT Pandas pipeline, complete with Matplotlib visualizations.

Release Notes 0.1.1 - Type Safety Hotfix & Ecosystem Integration

This patch focuses on strictly enforcing cross-library data compatibility and expanding the documentation with real-world Data Science workflows.

Core Engine & Type Safety (Hotfix)

• fix(core): Standardized native Python float (C-level float64) as the absolute default for all scalar outputs.
  • Resolves an inconsistency where scalars could be auto-casted to integers or Decimals, preventing unexpected TypeError crashes when integrating with external ML libraries (e.g., SciPy, Scikit-Learn).
• fix(fluent): Removed the redundant exact format option from the Fluent API's .use(format=...) method.
  • Decimal extraction is now strictly explicitly opt-in. Users must initialize with a Decimal object (e.g., Meter(Decimal('10'))) or use .use(mode='decimal') to trigger audit-level precision.

Documentation & Ecosystem

• docs(examples): Added a comprehensive suite of 15 standalone Python scripts in the examples/ directory demonstrating the full capability of the Axiom Engine, Custom Domains, and Error Handling.
• docs(notebooks): Introduced interactive Jupyter Notebooks (T01_Chisa_Fundamentals.ipynb and T02_Chisa_RealWorld_Workflow.ipynb) with direct Google Colab integration for seamless onboarding.
• feat(integration): Validated and documented zero-bottleneck integration patterns with the broader Data Science ecosystem, including Pandas, Matplotlib, SciPy, SymPy, and Scikit-Learn.