modularml 0.1.1

A library for modular, fast, and reproducible ML experimentation built for R&D.

ModularML

Modular, fast, and reproducible ML experimentation built for R&D.

---

Why ModularML?

ModularML is a flexible, backend-agnostic machine learning framework for designing, training, and evaluating modular ML pipelines, tailored specifically for research and scientific workflows. It enables rapid experimentation with complex model architectures, supports domain-specific feature engineering, and provides full reproducibility through configuration-driven declaration.

ModularML provides a plug-and-play ecosystem of interoperable components for data preprocessing, sampling, modeling, training, and evaluation — all wrapped in a unified experiment container.

Figure 1. Overview of the ModularML framework, highlighting the three core abstractions: feature set preprocessing and splitting, modular model graph construction, and staged training orchestration.

Features

ModularML includes a comprehensive set of components for scientific ML workflows:

Data Handling

• FeatureSet abstraction for organizing structured datasets with features, targets, tags, and metadata.
• Data class with unified support for multiple backends (torch.Tensor, tf.Tensor, np.ndarray).
• Built-in splitters: Supports sample-based and rule-based splitting with condition-based filtering by feature, target, or tags values.
• Sample grouping and multi-part splits for paired, triplet, or grouped training tasks.

Advanced Sampling

• Flexible FeatureSampler interface with support for advanced sampling during different stages of model training, including:
  • Triplet sampling (e.g., anchor/positive/negative)
  • Paired samples
  • Class-balanced, cluster-based, or time-windowed sampling strategies.
• Condition-aware sampling using any tags or metadata fields.

Model Architecture

• ModelGraph: A Directed Acyclic Graph (DAG)-based model builder where:
  • Each node is a ModelStage (e.g., encoder, head, discriminator).
  • Each stage can use a different backend (PyTorch, TensorFlow, scikit-learn, LightGBM, etc).
  • Mixed-backend models are supported with seamless input/output routing.
• Stage-wise training: Custom TrainingStage configuration enables fine-tuning, freezing, and transfer learning across sub-models.

Training & Experiments

• Experiment class encapsulates all training logic (via multiple TrainingStage objects), ModelGraph and FeatureSet definition, and a TrackingManager that logs all configuration files and training, validation, and evaluation metrics for rapid and reproducible ML experimentation.
• Each TrainingStage defines training loop logic with early stopping, validation hooks, loss weighting, and optimizer configs.
• Multi-objective loss support with configurable stage-level targets, sample-based loss functions, and weighted combinations.
• Config-driven experiments: Every experiment is fully seriallizable and reproducible from a single configuration file.
• Built-in experiment tracking via a TrackingManager, with optional integration into external managers like MLflow or other logging backends.

Getting Started

Requires Python >= 3.9

Installation

Install from PyPI:

pip install modularml

To install the latest development version:

pip install git+https://github.com/REIL-UConn/modular-ml.git

Explore More

• Examples – Explore complete examples of how to set up FeatureSets, samplers, model graphs, and training configurations.
• Documentation – API reference, component explanations, YAML configuration guides, and tutorials.
• Discussions – Join the community, ask questions, suggest features, or share use cases.

---

License

Apache 2.0