aether-ml 0.1.1__py3-none-any.whl

aether/__init__.py

@@ -0,0 +1,44 @@
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+from aether._utils._lazy import install_lazy_attrs
+from aether.layers import _LAYER_MODULES
+from aether.losses import _LOSS_MODULES
+from aether.metrics import _ACC_MODULES
+from aether.optimizers import _OPTIMIZER_MODULES
+from aether.preprocessing import _PREPROCESSING_MODULES
+
+try:
+    __version__ = _dist_version("aether-ml")
+except PackageNotFoundError:
+    # Running from a source checkout that was never pip-installed. Keep the
+    # attribute defined so `ae.__version__` never falls through to the lazy
+    # __getattr__ and raises a misleading AttributeError.
+    __version__ = "0.0.0.dev0"
+
+_MODEL_MODULES = {
+    "Model": "aether.model",
+}
+_TOP_LEVEL_MODULES = {
+    **_MODEL_MODULES,
+    **_LAYER_MODULES,
+    **_LOSS_MODULES,
+    **_ACC_MODULES,
+    **_OPTIMIZER_MODULES,
+    **_PREPROCESSING_MODULES
+}
+ 
+install_lazy_attrs(globals(), _TOP_LEVEL_MODULES) 
+
+# Clean up private setup variables so ae.<tab> remains clean
+del (
+    install_lazy_attrs,
+    _dist_version,
+    PackageNotFoundError,
+    _LAYER_MODULES, 
+    _LOSS_MODULES, 
+    _ACC_MODULES,
+    _OPTIMIZER_MODULES, 
+    _MODEL_MODULES, 
+    _PREPROCESSING_MODULES,
+    _TOP_LEVEL_MODULES,
+)

aether/__init__.pyi

@@ -0,0 +1,69 @@
+# aether/__init__.pyi
+
+# Static-typing companion to aether/__init__.py.
+# Never executed -- exists purely so each public class
+# gets real autocomplete/type info despite the runtime 
+# __getattr__ lazy loading.
+
+from aether.model import Model as Model
+
+from aether.layers.linear import Dense as Dense, Flatten as Flatten
+from aether.layers.conv import Conv2d as Conv2d
+from aether.layers.activations import ReLU as ReLU, LeakyReLU as LeakyReLU, SoftMax as SoftMax
+from aether.layers.pooling import MaxPool2d as MaxPool2d, AvgPool2d as AvgPool2d, GlobalAvgPool as GlobalAvgPool
+from aether.layers.dropout import Dropout as Dropout, SpatialDropout as SpatialDropout
+from aether.layers.normalization import BatchNorm as BatchNorm
+from aether.losses.categorical_crossentropy import (
+    Loss as Loss,
+    CategoricalCrossEntropy as CategoricalCrossEntropy,
+    SoftmaxCategoricalCrossEntropy as SoftmaxCategoricalCrossEntropy
+)
+
+# Direct module imports resolve stub lookups instantly:
+from aether.metrics.accuracy import (
+    CategoricalAccuracy as CategoricalAccuracy,
+    RegressionAccuracy as RegressionAccuracy,
+)
+
+from aether.optimizers.adam import Adam as Adam, AdamW as AdamW
+
+from aether.preprocessing.transforms import (
+    to_tensor as to_tensor, 
+    ToTensor as ToTensor, 
+    StandardScaler as StandardScaler,
+    Rescale as Rescale,
+    Compose as Compose
+)
+__all__ = [
+    # model
+    "Model",
+    # layers
+    "Dense",
+    "Flatten",
+    "Conv2d",
+    "ReLU",
+    "LeakyReLU",
+    "SoftMax",
+    "MaxPool2d",
+    "AvgPool2d",
+    "GlobalAvgPool",
+    "Dropout",
+    "SpatialDropout",
+    "BatchNorm",
+    # losses
+    "Loss",
+    "CategoricalCrossEntropy",
+    "SoftmaxCategoricalCrossEntropy",
+    # metrics
+    "CategoricalAccuracy",
+    "RegressionAccuracy",
+    # optimizers
+    "Adam",
+    "AdamW",
+    # preprocessing
+    "to_tensor",
+    "ToTensor",
+    "StandardScaler",
+    "Rescale",
+    "Compose"
+]

aether/_utils/__init__.py

@@ -0,0 +1,12 @@
+"""Internal framework utilities. Never exposed outside aether"""
+
+from aether._utils._lazy import install_lazy_attrs
+from aether._utils.null_objects import NullAccuracy, NullOptimizer, NullPreprocessor
+from aether._utils.progress import TrainingProgress
+__all__ = [
+    "install_lazy_attrs",
+    "NullAccuracy",
+    "NullOptimizer",
+    "NullPreprocessor",
+    "TrainingProgress",
+]

aether/_utils/__init__.pyi

@@ -0,0 +1,14 @@
+from aether._utils._lazy import install_lazy_attrs as install_lazy_attrs
+from aether._utils.null_objects import (
+    NullAccuracy as NullAccuracy,
+    NullOptimizer as NullOptimizer,
+    NullPreprocessor as NullPreprocessor
+)
+from aether._utils.progress import TrainingProgress as TrainingProgress
+__all__ = [
+    "install_lazy_attrs",
+    "NullAccuracy",
+    "NullOptimizer",
+    "NullPreprocessor",
+    "TrainingProgress",
+]

aether/_utils/_lazy.py

@@ -0,0 +1,52 @@
+import importlib
+  
+def install_lazy_attrs(module_globals, name_map):
+    """
+    Wire up a lazy __getattr__/__dir__ pair into the CALLING package's
+    module namespace.
+ 
+    Parameters
+    ----------
+    module_globals : dict
+        Must be the literal `globals()` of the __init__.py calling this
+        function. install_lazy_attrs writes __getattr__/__dir__/__all__
+        directly into that dict, which is what actually makes them live
+        on that specific package -- __getattr__ is resolved per-module,
+        not inherited up the package hierarchy, so every __init__.py that
+        wants lazy attribute resolution needs to call this itself.
+    name_map : dict[str, str]
+        {public_name: "fully.qualified.module.path"}. On first access of
+        `package.public_name`, the target module is imported and the
+        attribute is pulled off of it.
+ 
+    Notes
+    -----
+    The resolved value is cached directly into module_globals on first
+    access (module_globals[name] = value), so __getattr__ is only ever
+    invoked once per name -- every subsequent access is a plain,
+    zero-overhead attribute lookup, same as if it had been imported
+    eagerly. Also, While Python 3.15 PEP 810 - Explicit Lazy Imports 
+    circumvents the need for a file like this, its no need for users
+    to be locked out of this package for not being on python >=3.15
+    """
+    module_name = module_globals.get("__name__", "<unknown>")
+ 
+    # Merge rather than clobber: a package may want a handful of names
+    # eagerly imported above the install_lazy_attrs() call (e.g. a
+    # version string) in addition to the lazy ones.
+    existing_all = set(module_globals.get("__all__", ()))
+    module_globals["__all__"] = sorted(existing_all | set(name_map))
+ 
+    def __getattr__(name):
+        if name in name_map:
+            target_module = importlib.import_module(name_map[name])
+            value = getattr(target_module, name)
+            module_globals[name] = value  # cache: next access is a plain lookup
+            return value
+        raise AttributeError(f"module {module_name!r} has no attribute {name!r}")
+ 
+    def __dir__():
+        return sorted(set(module_globals.keys()) | set(name_map))
+ 
+    module_globals["__getattr__"] = __getattr__
+    module_globals["__dir__"] = __dir__

aether/_utils/null_objects.py

@@ -0,0 +1,91 @@
+"""
+Simple null objects that are used by the Model class.
+Avoids making us write needless branch conditionals.
+"""
+from aether.preprocessing.transforms import Preprocess
+
+class NullAccuracy:
+    def calculate(self, *args, **kwargs):
+        return 0.0
+
+    def calculate_accumulated(self):
+        return 0.0
+
+    def new_pass(self):
+        pass
+
+
+class NullOptimizer:
+    def step(self):
+        pass
+
+    @property
+    def current_learning_rate(self):
+        return None
+
+class _NullProgress:
+    """
+    No-op stand-in for ``TrainingProgress`` used when ``verbose == 0``.
+    """
+
+    __slots__ = ()
+
+    def start_epoch(self, epoch: int) -> None:
+        return
+
+    def tick(self, step: int, force: bool = False) -> None:
+        return
+
+    def update_metrics(
+        self,
+        step: int,
+        loss: float,
+        acc: float,
+        lr: float,
+        reg_loss: float | None = None,
+    ) -> None:
+        return
+
+    def commit_epoch(
+        self,
+        epoch: int,
+        epoch_loss: float,
+        epoch_acc: float,
+        lr: float,
+    ) -> None:
+        return
+
+    def commit_validation(self, val_loss: float, val_acc: float) -> None:
+        return
+
+    def close(self) -> None:
+        return
+
+class NullPreprocessor(Preprocess):
+    """Null-object preprocessor for models with no attached preprocessing pipeline.
+
+    A pure identity: ``transform()`` hands back exactly what it was given, and the
+    device/precision hooks are genuine no-ops. Model.finalize() installs this
+    unconditionally so the per-batch dispatch can call ``.transform()`` with zero
+    ``is not None`` branching in the hot loop -- the same role NullOptimizer and
+    NullAccuracy play elsewhere in the codebase.
+
+    Deliberately does NOT absorb device migration or precision casting. Every
+    finalized model owns one of these, so a migrating null object would silently
+    add a host->device copy to every batch of every pipeline-free model -- exactly
+    the per-step PCIe traffic that Model._assert_device_alignment exists to forbid.
+    Device strictness stays with that guard; device migration stays with an
+    explicit ToTensor the user opted into.
+
+    Trivially fit, so it never triggers the implicit-fit path in train().
+    """
+    is_fitted = True
+
+    def _compile_for_device(self, device):
+        return
+
+    def _apply_precision(self, policy):
+        return
+
+    def transform(self, X):
+        return X