CPPML: High-Performance Machine Learning CLI in C++

A lightweight, zero-dependency, high-performance Machine Learning Command Line Interface (CLI) built entirely from scratch in C++. This framework implements Linear and Polynomial Regression pipelines using matrix mathematics and gradient descent optimization, tailored for structured numerical datasets.

---

🚀 Architectural Blueprint

The framework uses an objective-oriented architecture decoupling data ingestion, matrix mathematics, algorithmic models, and statistical evaluation metrics.

Project Structure

📁 cppml/
│
├── 📁 include/cppml/              # Header definitions
│   ├── Dataset.hpp               # Data ingestion, cleaning, and Z-score normalization
│   ├── Matrix.hpp                # Custom linear algebra engine (dot products, transpositions, etc.)
│   ├── Model.hpp                 # Abstract base class for all ML models
│   ├── LinearRegression.hpp     # Multivariate linear regression implementation
│   ├── PolynomialRegression.hpp # Polynomial feature engineering and training pipeline
│   └── Metrics.hpp              # Evaluation metrics (MSE, RMSE, MAE, R²)
│
├── 📁 src/                       # Source implementations
│   ├── Dataset.cpp              # CSV parsing, missing data handling, feature scaling
│   ├── Matrix.cpp               # Vectorized matrix operations (row/column computations)
│   ├── LinearRegression.cpp     # Gradient descent / analytical solution implementation
│   ├── PolynomialRegression.cpp # Polynomial feature transformation and training logic
│   └── Metrics.cpp              # Statistical evaluation computations
│
└── 📄 Source.cpp                 # Main application entry point (CLI orchestration)

Directory Layout

Core Engine Mechanisms

1. Mathematical Stability: Features are processed via a custom Z-score Standardization Engine inside Dataset.cpp translating raw inputs into standardized deviations ($x_{\text{scaled}} = \frac{x - \mu}{\sigma}$), preventing gradient explosions during matrix dot products.
2. Persistence Layer: Models save and load optimized parameter weights along with calculated historical feature scalers into compact binary files (model.bin) for swift cross-execution operational integrity.

---

🛠️ Compilation & Requirements

Technical Pre-requisites

• Operating System: Windows 10/11, Linux, or macOS.
• Compiler: C++17 compliant compiler (MSVC v143+, GCC 9+, or Clang 10+).
• Build Configuration: Recommended compiling in Release Mode to unlock loop vectorization optimization on custom matrix multiplications.

Compiling via MSVC (Developer PowerShell / Command Prompt)

# Navigate to the workspace directory
cd C:\\Projects\\CPPML\\cppml

# Compile manually via CL or open the provided 'cppml.sln' in Visual Studio 2022
cl.exe /EHsc /O2 /std:c++17 src/*.cpp Source.cpp /Fe:x64\\Release\\cppml.exe

💻 CLI Execution Parameters & Usage The application handles operations via distinct execution channels directly controlled by runtime parameters.

1. Training Pipeline (train) Instructs the engine to load raw training metrics, auto-clean null instances, calculate structural normalization bounds, and perform multivariate gradient descent tracking structural loss convergence.

# General Syntax
./cppml train <dataset.csv> [--poly <degree>] [--lr <rate>] [--epochs <count>]

# Example: Training a robust Linear Regression with customized hyperparameters
./cppml train dataset.csv --epochs 5000 --lr 0.01

# Example: High-degree Feature Transformation (Polynomial Training)
./cppml train dataset.csv --poly 2 --epochs 3000 --lr 0.005

Parameters Explained:

dataset.csv: Pathway to your structured comma-separated data matrix. Target column must sit as the final trailing element.
--lr: Learning rate modifier adjusting gradient step increments. Recommendation: Use 0.01 to 0.001 on scaled data.
--epochs: The concrete cap on weight update iterations across your global data rows.
--poly: Activates feature exponent transformations. Omit or set to 1 for pure linear evaluations.

2. Prediction Pipeline (predict) Evaluates raw parameter conditions on an optimized runtime model binary file to calculate target inferences.

# General Syntax
./cppml predict <model.bin> <feature_1> <feature_2> ... <feature_n>

# Example: Predicting Energy Consumption using raw structural markers
./cppml predict model.bin 7063 76 10 29.84

3. Evaluation Pipeline (evaluate) Scores data frames against a saved binary configuration checkpoint to return structural standard error profiles.

./cppml evaluate dataset.csv --poly 1

📝 Roadmap & Future Upgrades Tracker An active tracking index targeting optimizations to lift model performance metrics beyond current validation baselines:

[ ] Native Feature Scaler Persistence Implementation: Embed structural means and stds straight into saveModel() binary sequences to make predictions automatically adapt to raw numerical CLI inputs without altering target variables.
[ ] Automated Feature Selection (Pearson Correlation Filter): Construct a analytical correlation matrix drop-layer into Dataset.cpp discarding inputs with sub-threshold dependency ratios to streamline cross-matrix multiplications.
[ ] Advanced Gradient Solvers (Adam / Momentum): Move past basic stochastic gradient updates by adding decaying moving averages of past gradients to clear flattening loss plateaus faster.
[ ] Regularization Layers (Ridge & Lasso): Inject L1​ and L2​ structural penalties into loss calculations to stabilize weights and control overfitting tendencies on high-degree polynomial states.
[ ] Cross-Validation Split Pipeline: Build structural data shuffling and partition engines (train_test_split) within the Dataset module to yield unbiased structural performance profiles out-of-the-box.