trueml

Why Choose a No-Abstraction Philosophy?

Most machine learning frameworks present a black-box contract: data goes in, a trained model comes out. sklearn.linear_model.LinearRegression().fit(X, y) conceals the forward pass, the loss evaluation, the gradient computation, and the parameter update behind a single method call. While convenient for production, this opacity is antithetical to understanding.

TrueML adopts the opposite stance: zero abstraction. Every mathematical operation in the learning pipeline is a first-class function you invoke explicitly. The library provides the primitive operations; you write the protocol.

How Does the Four-Step Pipeline Work?

Every supervised learning experiment in TrueML follows this canonical sequence:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

┌─────────────────────────────────────────────────────────┐
│                     TRAINING LOOP                       │
│                                                         │
│  1. FORWARD     y_pred = model.forward(X)               │
│       ŷ = Xw + b                                        │
│                                                         │
│  2. LOSS        error = loss_fn(y, y_pred)              │
│       L = |y – ŷ|                                       │
│                                                         │
│  3. GRADIENT    dw, db = loss_fn.grad(X, error)         │
│       ∂L/∂w = (1/n) Xᵀ · ∂L/∂ŷ                          │
│                                                         │
│  4. BACKWARD      model.backward(dw, db)                │
│       w ← w – η · ∂L/∂w                                 │
└─────────────────────────────────────────────────────────┘

There is no .fit(). There is no hidden state. The user controls every step.

Why is Statelessness a Core Design Principle?

TrueML models are stateless with respect to data. They hold parameters (weights, bias) but never cache a training example. This means:

  • No accidental leakage: a model cannot remember a previous batch.
  • Explicit dataflow: you always know what data produced what gradient.
  • Composability: any step can be replaced, inspected, or debugged in isolation.

If you want to log gradients before the update, you print them. If you want to try a custom update rule, you write it yourself. The library does not abstract away what you need to see.

Who is This Library Built For?

  • Researchers who want to read every line of their training loop.
  • Students learning how gradients actually flow through a linear model.
  • Practitioners who need a minimal, auditable baseline before layering complexity.