mlkit

Machine Learning Toolkit: a small, readable machine learning library built on NumPy.

mlkit has the familiar fit / predict / transform estimator interface and a handful of classic algorithms, each implemented in a few dozen lines of plain NumPy. Use it to learn how the algorithms work, to teach them, or for small projects where a large ML stack is too much. NumPy is its only dependency.

Features

• Estimator API: fit, predict, transform, score, get_params / set_params, clone
• Linear models: LinearRegression (least squares), Ridge (L2, closed form), LogisticRegression (multinomial, gradient descent, optional L2)
• Neighbours: KNeighborsClassifier, KNeighborsRegressor (uniform or inverse-distance weights)
• Clustering: KMeans (k-means++ seeding, multiple restarts, reproducible via random_state)
• Preprocessing: StandardScaler, MinMaxScaler (both with inverse_transform)
• Model selection: train_test_split, KFold, cross_val_score
• Metrics: accuracy, confusion matrix, precision / recall / F1 (binary and macro), MSE, MAE, R²
• Datasets: make_blobs, make_regression synthetic generators
• Input validation with clear errors, and NotFittedError when an estimator is used before fit
• Type hints throughout (ships py.typed)

Installation

pip install mlkit

From a source checkout:

python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest

Requires Python 3.9+ and NumPy 1.22+.

Quickstart

from mlkit import KMeans, LinearRegression, LogisticRegression, StandardScaler, train_test_split
from mlkit.datasets import make_blobs, make_regression
from mlkit.metrics import accuracy_score, r2_score

# Classification: scale the features, then fit a logistic regression
X, y = make_blobs(n_samples=300, centers=3, random_state=0)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.25, random_state=0)

scaler = StandardScaler().fit(X_train)
clf = LogisticRegression(learning_rate=0.5, max_iter=2000)
clf.fit(scaler.transform(X_train), y_train)
print("accuracy:", accuracy_score(y_test, clf.predict(scaler.transform(X_test))))

# Regression
X, y, true_coef = make_regression(n_samples=200, n_features=3, noise=0.5, random_state=1)
reg = LinearRegression().fit(X, y)
print("R^2:", r2_score(y, reg.predict(X)), "coef:", reg.coef_)

# Clustering
km = KMeans(n_clusters=3, random_state=0).fit(X_train)
print("inertia:", km.inertia_, "labels:", km.labels_[:10])

Cross-validation:

from mlkit import KFold, KNeighborsClassifier, cross_val_score

scores = cross_val_score(KNeighborsClassifier(n_neighbors=5), X_train, y_train,
                         cv=KFold(n_splits=5, shuffle=True, random_state=0))
print(scores.mean())

API overview

All estimators subclass mlkit.BaseEstimator. Hyper-parameters are the constructor arguments. Learned attributes end in _ and exist only after fit. Every fit returns self. Calling predict or transform before fit raises mlkit.NotFittedError.

mlkit (top level)

mlkit.linear_model

mlkit.neighbors

mlkit.cluster

mlkit.preprocessing

mlkit.model_selection

mlkit.metrics

mlkit.datasets

mlkit.base

Contains the ClassifierMixin, RegressorMixin, TransformerMixin and ClusterMixin mixins for writing your own estimators, plus the validation helpers check_array, check_X_y and check_is_fitted.

Scope and limitations

mlkit puts clarity ahead of speed. k-NN uses brute-force distances, and logistic regression uses plain full-batch gradient descent, so scale your features first. It is not a replacement for scikit-learn on large datasets.

License

MIT