easymodd 0.1.0__tar.gz

easymodd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vnex Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

easymodd-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: easymodd
+Version: 0.1.0
+Summary: A configurable, training-first numerical machine learning library
+Author: Vnex Lab
+Maintainer: Vnex Lab
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vnex-lab/EasyMoDD
+Project-URL: Repository, https://github.com/vnex-lab/EasyMoDD
+Project-URL: Issues, https://github.com/vnex-lab/EasyMoDD/issues
+Project-URL: Documentation, https://github.com/vnex-lab/EasyMoDD#readme
+Project-URL: Support, https://ko-fi.com/vnexlab
+Keywords: machine-learning,deep-learning,numpy,cuda,training,transformers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Provides-Extra: cuda
+Requires-Dist: cupy-cuda12x>=13.6; extra == "cuda"
+Provides-Extra: data
+Requires-Dist: pandas>=2.0; extra == "data"
+Requires-Dist: pyarrow>=15.0; extra == "data"
+Requires-Dist: scikit-learn>=1.4; extra == "data"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# EasyMoDD
+
+EasyMoDD is a configurable, training-first machine-learning library. It is
+programmable from Python like a numerical library, with reusable tensors,
+modules, datasets, losses, optimizers, trainers, model families, and checkpoint
+policies.
+
+Models initialize randomly unless a consuming project explicitly resumes from
+its own checkpoint. EasyMoDD does not include a chatbot, web application,
+built-in corpus, project `config.txt`, generated checkpoints, or demo data.
+
+## Install
+
+```powershell
+python -m pip install easymodd
+```
+
+For a local checkout:
+
+```powershell
+python -m pip install -e .
+```
+
+## Publish to PyPI
+
+The package is configured for GitHub Actions Trusted Publishing. Before the
+first release, create a PyPI project named `easymodd`, then add this trusted
+publisher on PyPI:
+
+- Owner: `vnex-lab`
+- Repository: `EasyMoDD`
+- Workflow: `publish.yml`
+- Environment: `pypi`
+
+After that one-time setup, publish a release from GitHub. The workflow builds
+the wheel and source archive, validates both with Twine, and publishes them
+without a stored PyPI token.
+
+For a local dry run:
+
+```powershell
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+The package version is controlled by `project.version` in `pyproject.toml`.
+Increase it for every PyPI release, and do not reuse an already-uploaded
+version.
+
+Optional integrations:
+
+```powershell
+python -m pip install easymodd[cuda]
+python -m pip install easymodd[data]
+python -m pip install easymodd[dev]
+```
+
+## Python API
+
+```python
+import numpy as np
+from easymodd import ArrayDataset, MSELoss, SGD, Trainer, build_mlp
+
+model = build_mlp(input_size=1, hidden_sizes=[8], output_size=1)
+dataset = ArrayDataset(
+    np.array([[1.0], [2.0], [3.0]], dtype=np.float32),
+    np.array([[2.0], [4.0], [6.0]], dtype=np.float32),
+)
+history = Trainer(
+    SGD(model.parameters(), learning_rate=0.01),
+    MSELoss(),
+    max_steps=100,
+).fit(model, dataset)
+print(history.values["loss"][-1])
+```
+
+The programmable foundation includes:
+
+- NumPy and explicit CUDA backend helpers
+- `Module`, `Parameter`, `Linear`, `ReLU`, and `Sequential`
+- GELU, sigmoid, tanh, and dropout layers
+- MLP model factory
+- Model registries for custom factories
+- `ArrayDataset` and packed `TextDataset`
+- `BatchLoader`, deterministic splits, and `Subset`
+- Composable transforms and batch collation
+- MSE and cross-entropy loss contracts
+- L1 and Huber losses
+- SGD, Adam, and AdamW optimizers
+- Cosine and warmup learning-rate schedulers
+- Reusable `Trainer` and `TrainingHistory`
+- Accuracy, MAE, and perplexity metrics
+- JSONL metrics logging and early stopping callbacks
+- Local experiment tracking and dependency-free summaries
+- Versioned model/optimizer/scheduler serialization
+- Environment-only secrets for optional integrations
+- Config loading and validation for consuming projects
+- Checkpoint enable/disable, retention, and compression policy
+- Separate text Transformer and Vision Transformer configuration modules
+
+The restored prototype scripts remain available as compatibility programs for
+existing custom checkpoints. New projects should import EasyMoDD directly.
+
+## Consumer Project Configuration
+
+EasyMoDD does not force users into one project layout. A consuming project can
+create its own `config.txt` using TOML syntax and load it with:
+
+```python
+from easymodd import load_config
+config = load_config("config.txt")
+```
+
+The config loader supports project-defined paths for datasets, runs, models,
+logs, and checkpoints. The library never assumes a filename such as
+`best.bin`.
+
+A consumer project can configure checkpoint behavior like this:
+
+```toml
+[checkpoints]
+enabled = true
+keep_recent = 2
+compress_old = true
+```
+
+When disabled, `CheckpointManager` creates no directory or files. When enabled,
+older numbered checkpoints can be compressed while recent checkpoints remain
+available.
+
+## Package Layout
+
+```text
+src/easymodd/
+  models/
+    mlp.py
+    text_transformer.py
+    vision_transformer.py
+  data.py
+  losses.py
+  nn.py
+  tensor.py
+  optim.py
+  training.py
+  checkpoints.py
+  config.py
+  cli.py
+```
+
+Each model family has its own module. The shared training contracts are designed
+so new model types can be added without changing dataset or checkpoint code.
+
+## Extending EasyMoDD
+
+Register a custom model factory:
+
+```python
+from easymodd import ModelRegistry
+
+registry = ModelRegistry()
+registry.register("my_model", lambda width=8: build_my_model(width))
+model = registry.create("my_model", width=32)
+```
+
+Optional integrations can read environment variables without storing secrets:
+
+```python
+from easymodd import SecretStore
+
+secrets = SecretStore(prefix="MY_APP_")
+token = secrets.get("TRACKING_TOKEN")
+```
+
+EasyMoDD never writes API keys to configs, checkpoints, experiment files, or
+logs. Provider-specific integrations can be built on top of this helper.
+
+## Data and Training
+
+The library does not ship a general-purpose training database. Users provide
+legally obtained text, image, or tabular data in their own projects. EasyMoDD
+provides dataset contracts and validation helpers; it does not pretend that a
+small demo corpus can produce a general assistant.
+
+## Development Status
+
+The tensor/module API, programmable MLP training loop, dataset contracts,
+checkpoint policy, model-family layout, and config loader are implemented.
+Text Transformer training, Vision Transformer training, full resume manifests,
+evaluation, schedulers, callbacks, and additional model families are active
+parts of the public-library roadmap.
+
+Support development on [Ko-fi](https://ko-fi.com/vnexlab).

easymodd-0.1.0/README.md

@@ -0,0 +1,193 @@
+# EasyMoDD
+
+EasyMoDD is a configurable, training-first machine-learning library. It is
+programmable from Python like a numerical library, with reusable tensors,
+modules, datasets, losses, optimizers, trainers, model families, and checkpoint
+policies.
+
+Models initialize randomly unless a consuming project explicitly resumes from
+its own checkpoint. EasyMoDD does not include a chatbot, web application,
+built-in corpus, project `config.txt`, generated checkpoints, or demo data.
+
+## Install
+
+```powershell
+python -m pip install easymodd
+```
+
+For a local checkout:
+
+```powershell
+python -m pip install -e .
+```
+
+## Publish to PyPI
+
+The package is configured for GitHub Actions Trusted Publishing. Before the
+first release, create a PyPI project named `easymodd`, then add this trusted
+publisher on PyPI:
+
+- Owner: `vnex-lab`
+- Repository: `EasyMoDD`
+- Workflow: `publish.yml`
+- Environment: `pypi`
+
+After that one-time setup, publish a release from GitHub. The workflow builds
+the wheel and source archive, validates both with Twine, and publishes them
+without a stored PyPI token.
+
+For a local dry run:
+
+```powershell
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+The package version is controlled by `project.version` in `pyproject.toml`.
+Increase it for every PyPI release, and do not reuse an already-uploaded
+version.
+
+Optional integrations:
+
+```powershell
+python -m pip install easymodd[cuda]
+python -m pip install easymodd[data]
+python -m pip install easymodd[dev]
+```
+
+## Python API
+
+```python
+import numpy as np
+from easymodd import ArrayDataset, MSELoss, SGD, Trainer, build_mlp
+
+model = build_mlp(input_size=1, hidden_sizes=[8], output_size=1)
+dataset = ArrayDataset(
+    np.array([[1.0], [2.0], [3.0]], dtype=np.float32),
+    np.array([[2.0], [4.0], [6.0]], dtype=np.float32),
+)
+history = Trainer(
+    SGD(model.parameters(), learning_rate=0.01),
+    MSELoss(),
+    max_steps=100,
+).fit(model, dataset)
+print(history.values["loss"][-1])
+```
+
+The programmable foundation includes:
+
+- NumPy and explicit CUDA backend helpers
+- `Module`, `Parameter`, `Linear`, `ReLU`, and `Sequential`
+- GELU, sigmoid, tanh, and dropout layers
+- MLP model factory
+- Model registries for custom factories
+- `ArrayDataset` and packed `TextDataset`
+- `BatchLoader`, deterministic splits, and `Subset`
+- Composable transforms and batch collation
+- MSE and cross-entropy loss contracts
+- L1 and Huber losses
+- SGD, Adam, and AdamW optimizers
+- Cosine and warmup learning-rate schedulers
+- Reusable `Trainer` and `TrainingHistory`
+- Accuracy, MAE, and perplexity metrics
+- JSONL metrics logging and early stopping callbacks
+- Local experiment tracking and dependency-free summaries
+- Versioned model/optimizer/scheduler serialization
+- Environment-only secrets for optional integrations
+- Config loading and validation for consuming projects
+- Checkpoint enable/disable, retention, and compression policy
+- Separate text Transformer and Vision Transformer configuration modules
+
+The restored prototype scripts remain available as compatibility programs for
+existing custom checkpoints. New projects should import EasyMoDD directly.
+
+## Consumer Project Configuration
+
+EasyMoDD does not force users into one project layout. A consuming project can
+create its own `config.txt` using TOML syntax and load it with:
+
+```python
+from easymodd import load_config
+config = load_config("config.txt")
+```
+
+The config loader supports project-defined paths for datasets, runs, models,
+logs, and checkpoints. The library never assumes a filename such as
+`best.bin`.
+
+A consumer project can configure checkpoint behavior like this:
+
+```toml
+[checkpoints]
+enabled = true
+keep_recent = 2
+compress_old = true
+```
+
+When disabled, `CheckpointManager` creates no directory or files. When enabled,
+older numbered checkpoints can be compressed while recent checkpoints remain
+available.
+
+## Package Layout
+
+```text
+src/easymodd/
+  models/
+    mlp.py
+    text_transformer.py
+    vision_transformer.py
+  data.py
+  losses.py
+  nn.py
+  tensor.py
+  optim.py
+  training.py
+  checkpoints.py
+  config.py
+  cli.py
+```
+
+Each model family has its own module. The shared training contracts are designed
+so new model types can be added without changing dataset or checkpoint code.
+
+## Extending EasyMoDD
+
+Register a custom model factory:
+
+```python
+from easymodd import ModelRegistry
+
+registry = ModelRegistry()
+registry.register("my_model", lambda width=8: build_my_model(width))
+model = registry.create("my_model", width=32)
+```
+
+Optional integrations can read environment variables without storing secrets:
+
+```python
+from easymodd import SecretStore
+
+secrets = SecretStore(prefix="MY_APP_")
+token = secrets.get("TRACKING_TOKEN")
+```
+
+EasyMoDD never writes API keys to configs, checkpoints, experiment files, or
+logs. Provider-specific integrations can be built on top of this helper.
+
+## Data and Training
+
+The library does not ship a general-purpose training database. Users provide
+legally obtained text, image, or tabular data in their own projects. EasyMoDD
+provides dataset contracts and validation helpers; it does not pretend that a
+small demo corpus can produce a general assistant.
+
+## Development Status
+
+The tensor/module API, programmable MLP training loop, dataset contracts,
+checkpoint policy, model-family layout, and config loader are implemented.
+Text Transformer training, Vision Transformer training, full resume manifests,
+evaluation, schedulers, callbacks, and additional model families are active
+parts of the public-library roadmap.
+
+Support development on [Ko-fi](https://ko-fi.com/vnexlab).

easymodd-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "easymodd"
+version = "0.1.0"
+description = "A configurable, training-first numerical machine learning library"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Vnex Lab" }]
+maintainers = [{ name = "Vnex Lab" }]
+keywords = ["machine-learning", "deep-learning", "numpy", "cuda", "training", "transformers"]
+classifiers = [
+	"Development Status :: 3 - Alpha",
+	"Intended Audience :: Developers",
+	"Intended Audience :: Science/Research",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"Programming Language :: Python :: 3.14",
+	"Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["numpy>=2.0"]
+
+[project.urls]
+Homepage = "https://github.com/vnex-lab/EasyMoDD"
+Repository = "https://github.com/vnex-lab/EasyMoDD"
+Issues = "https://github.com/vnex-lab/EasyMoDD/issues"
+Documentation = "https://github.com/vnex-lab/EasyMoDD#readme"
+Support = "https://ko-fi.com/vnexlab"
+
+[project.optional-dependencies]
+cuda = ["cupy-cuda12x>=13.6"]
+data = ["pandas>=2.0", "pyarrow>=15.0", "scikit-learn>=1.4"]
+dev = ["build>=1.2", "pytest>=8.0", "twine>=5.0"]
+
+[project.scripts]
+easymodd = "easymodd.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+easymodd = ["py.typed"]

easymodd-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

easymodd-0.1.0/src/easymodd/__init__.py

@@ -0,0 +1,85 @@
+"""EasyMoDD: configurable, training-first numerical machine learning tools."""
+
+from .config import EasyMoDDConfig, load_config
+from .tensor import Device, array, backend_of, get_backend, matmul, ones, randn, seed, zeros
+from .nn import Dropout, GELU, Linear, Module, Parameter, ReLU, Sequential, Sigmoid, Tanh
+from .optim import Adam, AdamW, SGD
+from .schedulers import CosineScheduler, WarmupScheduler
+from .metrics import accuracy, mean_absolute_error, perplexity
+from .callbacks import EarlyStopping, MetricsLogger
+from .serialization import load_state, save_state
+from .training import Trainer, TrainingHistory
+from .data import ArrayDataset, BatchLoader, Dataset, Subset, TextDataset, collate_batch, split_dataset
+from .losses import CrossEntropyLoss, HuberLoss, L1Loss, MSELoss
+from .checkpoints import CheckpointManager
+from .experiments import Experiment
+from .registry import ModelRegistry, models
+from .secret_store import SecretStore
+from .transforms import Compose, Flatten, MapTransform, Normalize, Standardize, ToFloat32
+from .visualization import summarize_history, summarize_model
+from .models import MLP, TextTransformerConfig, VisionTransformerConfig, build_mlp
+
+__all__ = [
+    "Device",
+    "ArrayDataset",
+    "BatchLoader",
+    "Adam",
+    "AdamW",
+    "CheckpointManager",
+    "Compose",
+    "CrossEntropyLoss",
+    "CosineScheduler",
+    "Dataset",
+    "Dropout",
+    "EarlyStopping",
+    "EasyMoDDConfig",
+    "Experiment",
+    "Flatten",
+    "GELU",
+    "HuberLoss",
+    "L1Loss",
+    "Linear",
+    "MSELoss",
+    "MapTransform",
+    "ModelRegistry",
+    "Normalize",
+    "MetricsLogger",
+    "Module",
+    "Parameter",
+    "ReLU",
+    "Sequential",
+    "SGD",
+    "SecretStore",
+    "Sigmoid",
+    "Standardize",
+    "Tanh",
+    "ToFloat32",
+    "WarmupScheduler",
+    "Trainer",
+    "TrainingHistory",
+    "TextDataset",
+    "Subset",
+    "array",
+    "accuracy",
+    "backend_of",
+    "MLP",
+    "TextTransformerConfig",
+    "VisionTransformerConfig",
+    "build_mlp",
+    "get_backend",
+    "load_config",
+    "load_state",
+    "matmul",
+    "mean_absolute_error",
+    "perplexity",
+    "collate_batch",
+    "models",
+    "ones",
+    "randn",
+    "seed",
+    "save_state",
+    "zeros",
+    "split_dataset",
+    "summarize_history",
+    "summarize_model",
+]

easymodd-0.1.0/src/easymodd/callbacks.py

@@ -0,0 +1,40 @@
+"""Reusable training callbacks."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+class MetricsLogger:
+    """Append one JSON object per training event."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def __call__(self, *, step: int, metrics: dict[str, float]) -> None:
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps({"step": step, **metrics}) + "\n")
+
+
+class EarlyStopping:
+    def __init__(self, metric: str = "loss", patience: int = 10, minimum_delta: float = 0.0):
+        if patience < 1:
+            raise ValueError("patience must be at least 1")
+        self.metric = metric
+        self.patience = patience
+        self.minimum_delta = minimum_delta
+        self.best = float("inf")
+        self.bad_steps = 0
+
+    def __call__(self, *, step: int, metrics: dict[str, float]) -> bool:
+        value = metrics.get(self.metric)
+        if value is None:
+            return False
+        if value < self.best - self.minimum_delta:
+            self.best = value
+            self.bad_steps = 0
+        else:
+            self.bad_steps += 1
+        return self.bad_steps >= self.patience

easymodd-0.1.0/src/easymodd/checkpoints.py

@@ -0,0 +1,59 @@
+"""Config-controlled checkpoint management."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import zipfile
+from .serialization import save_state
+
+
+class CheckpointManager:
+    """Checkpoint policy that creates no files when disabled."""
+
+    def __init__(self, directory: str | Path, enabled: bool = True,
+                 keep_recent: int = 2, compress_old: bool = True):
+        if keep_recent < 1:
+            raise ValueError("keep_recent must be at least 1")
+        self.directory = Path(directory)
+        self.enabled = bool(enabled)
+        self.keep_recent = keep_recent
+        self.compress_old = bool(compress_old)
+
+    def save(self, state: dict, step: int) -> Path | None:
+        if not self.enabled:
+            return None
+        self.directory.mkdir(parents=True, exist_ok=True)
+        path = self.directory / f"step_{step:07d}.json"
+        path.write_text(json.dumps(state, indent=2), encoding="utf-8")
+        self._compress_old()
+        return path
+
+    def save_training_state(self, step: int, *, model, optimizer=None,
+                            scheduler=None, config=None, metrics=None) -> Path | None:
+        if not self.enabled:
+            return None
+        self.directory.mkdir(parents=True, exist_ok=True)
+        path = self.directory / f"step_{step:07d}.pkl"
+        save_state(path, model=model, optimizer=optimizer, scheduler=scheduler,
+                   config=config, metrics=metrics)
+        self._compress_artifacts()
+        return path
+
+    def _compress_old(self) -> None:
+        files = sorted(self.directory.glob("step_*.json"), key=lambda item: item.stat().st_mtime)
+        for path in files[:-self.keep_recent]:
+            archive = path.with_suffix(".zip")
+            if self.compress_old and not archive.exists():
+                with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as handle:
+                    handle.write(path, arcname=path.name)
+                path.unlink()
+
+    def _compress_artifacts(self) -> None:
+        files = sorted(self.directory.glob("step_*.pkl"), key=lambda item: item.stat().st_mtime)
+        for path in files[:-self.keep_recent]:
+            archive = path.with_suffix(".zip")
+            if self.compress_old and not archive.exists():
+                with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as handle:
+                    handle.write(path, arcname=path.name)
+                path.unlink()