trueml 0.0.2

Machine learning without hidden abstractions.

[!CAUTION] Library Under Development TrueML is currently in early development. APIs are subject to change.

What is TrueML?

TrueML is a Python machine learning library built on a single, uncompromising principle: every mathematical operation in the learning pipeline is a first-class function you invoke explicitly.

There is no .fit(). There is no hidden state. There are no implicit optimizers or black-box solvers.

Instead, TrueML provides the primitive mathematical operations (forward passes, loss functions, Jacobians, and parameter updates) and you write the training loop.

If you are a student learning how gradients flow, a researcher auditing an optimization landscape, or a practitioner who wants a maximally transparent baseline before layering complexity, TrueML is built for you.

Quick Start

The core of TrueML is the four-step explicit pipeline: forward $\rightarrow$ loss $\rightarrow$ gradient $\rightarrow$ backward.

import numpy as np
from trueml.linearmodel import LinearRegression
from trueml.losses import MSEloss

# 1. Prepare data
X = np.random.randn(100, 3)
y = X @ np.array([1.5, -2.0, 0.5]) + 0.1

# 2. Initialize Model and Loss
model = LinearRegression(n_features=3, lr=0.01)
loss_fn = MSEloss()

# 3. The Explicit Training Loop
for epoch in range(500):
    
    # Step 1: Forward Pass (ŷ = Xw + b)
    y_pred = model.forward(X)
    
    # Step 2: Loss Computation (L = mean((y - ŷ)²))
    loss = loss_fn(y, y_pred)
    
    # Step 3: Gradient Computation 
    dloss = loss_fn.grad(y, y_pred)     # ∂L/∂ŷ
    dw, db = model.grad(X, dloss)       # ∂L/∂w = Xᵀ · ∂L/∂ŷ (Chain Rule)
    
    # Step 4: Backward Update (w ← w - η · ∂L/∂w)
    model.backward(dw, db)
    
    if epoch % 100 == 0:
        print(f"Epoch {epoch} | Loss: {loss:.4f}")

Features

• Transparent Calculus: The multivariable chain rule is exposed directly in code. You pass the derivative of the loss (dloss) into the model's Jacobian (model.grad()) explicitly.
• Strictly Stateless: Models hold weights and bias, but never cache data (X_train_ or y_train_). You must supply the data every time you compute a forward pass or gradient.
• Auditable Math: Every intermediate step (y_pred, loss, dloss, dw) is a standard NumPy array. You can intercept, print, clip, or plot them at any time.
• Native Visualizations: Includes built-in Matplotlib (trueml.viz) and Plotly (trueml.visualize) backends for plotting 2D/3D functions, loss surfaces, and live training metrics in Jupyter notebooks.

Installation

TrueML requires Python 3.13+ and relies heavily on numpy and matplotlib.

It is available on PyPI (but still in the developing stage):

pip install trueml

Alternatively, you can install it from source:

git clone https://github.com/iamprasadraju/trueml.git
cd trueml
pip install -r requirements.txt

Documentation

TrueML features comprehensive, production-grade documentation styled as a "Laboratory Manual" using the Diátaxis framework.

Explore the full documentation here

Highlights from the Docs:

• No-Abstraction Philosophy: Read about why TrueML intentionally avoids .fit().
• Tutorials: Build your first training loop and compare the behavior of L1 vs L2 losses.
• How-to Guides: Learn how to implement minibatch gradient descent, train on real pandas DataFrames, and debug exploding/vanishing gradients.
• API Reference: Rigorous "Mathematical Contracts" for every module, including full LaTeX proofs of all derivatives.

Contributing

Contributions are welcome! If you want to add new models, loss functions, or mathematical tools, please ensure they strictly adhere to the "No-Abstraction Philosophy":

1. No hidden state.
2. No implicit optimizations.
3. Every operation must clearly map to a mathematical equation.
4. Don't push AI generated code. We value human-written, deeply understood mathematical implementations.

License

This project is licensed under the MIT License - see the LICENSE file for details.