mini-ml

Machine learning do zero em Python puro — sem numpy, sem scikit-learn, sem framework. Só a matemática, implementada à mão, para você ler e entender o que esses algoritmos realmente fazem. Os três pilares clássicos, com cobertura de testes 100%:

Algoritmo	Faz o quê	Ideia
Regressão linear	prevê um número	acha a reta que minimiza o erro (mínimos quadrados)
K-means	agrupa (cluster)	move centróides até os grupos estabilizarem (Lloyd)
k-NN	classifica	vota entre os k exemplos mais próximos

Por que "do zero"

Frameworks de ML são ótimos — e escondem tudo. model.fit(X, y) é uma caixa preta maravilhosa até o dia em que você precisa entender por que o resultado é estranho. Reimplementar o básico à mão desmistifica: uma regressão linear é uma fórmula fechada; k-means é um laço de "atribui e recalcula a média"; k-NN é literalmente "olha os vizinhos e vota". Nada de mágica.

Tudo aqui é função pura e testada nas propriedades e nos casos de erro (não só o feliz): reta perfeita dá R² = 1, cluster vazio mantém seu centróide, empate no k-NN é desempatado de forma determinística.

Uso

from mini_ml.linear_regression import SimpleLinearRegression
from mini_ml.kmeans import KMeans
from mini_ml.knn import KNN

reg = SimpleLinearRegression().fit([0, 1, 2, 3], [1, 3, 5, 7])
reg.slope, reg.intercept   # 2.0, 1.0
reg.predict(10)            # 21.0

km = KMeans(k=2).fit(pontos, init=[[0, 0], [10, 10]])
km.predict([9, 9])         # índice do cluster mais próximo

knn = KNN(k=3).fit(pontos, rotulos)
knn.predict([0.5, 0.5])    # a classe majoritária entre os 3 vizinhos

Rode a demonstração dos três:

python demo.py

Saída (resumo): a regressão recupera y = 2x + 1 com R² = 1, o k-means separa dois grupos, e o k-NN classifica "gato" vs "cachorro" pela vizinhança.

Stack

• Linguagem: Python 3.12 (sem dependências de runtime)
• Testes/cobertura: pytest + pytest-cov (gate de 100%) · Lint: ruff

Arquitetura

mini_ml/
├── distance.py            # distância euclidiana
├── linear_regression.py   # SimpleLinearRegression (mínimos quadrados)
├── kmeans.py              # KMeans (algoritmo de Lloyd)
└── knn.py                 # KNN (k vizinhos + votação)

Testes e cobertura

pip install -r requirements-dev.txt
pytest            # exige 100% (configurado no pyproject.toml)
ruff check . && ruff format --check .

Licença

MIT.