Train a real AI model that fits in a single pixel.
ai-pixel takes your data, runs actual gradient descent to learn a classifier, then encodes the entire trained model into the RGB values of a 1x1 PNG image. Three parameters (two weights and a bias), three color channels, one pixel.
Load that pixel later to run predictions. The pixel is the model.
Open the demo in your browser. Click to place data points, hit Train, and watch the model collapse into a single colored pixel you can download.
pip install git+https://github.com/dvelton/ai-pixel.git
Requires Python 3.9+. For visualization support, also install matplotlib:
pip install matplotlib
from aipixel import PixelModel
from aipixel.datasets import umbrella
# Load example data
X, y, meta = umbrella()
# Train
model = PixelModel(n_inputs=2)
model.train(X, y)
# The model is a pixel
pixel = model.to_pixel()
print(f"Your AI: RGB({pixel[0]}, {pixel[1]}, {pixel[2]})")
# Save as a 1x1 PNG
model.to_image("model.png")
# Load it back
loaded = PixelModel.from_image("model.png")
loaded.predict([[0.8, 0.7]]) # => array([1]) "Bring umbrella"A single-neuron binary classifier has three learnable parameters for two inputs:
- Weight 1: how much input 1 matters
- Weight 2: how much input 2 matters
- Bias: the threshold offset
ai-pixel trains this classifier using gradient descent with sigmoid activation and binary cross-entropy loss. Weights are bounded to [-4.0, 4.0] during training so they always fit in one byte each. After training, each parameter is quantized to 8 bits and mapped to a color channel:
| Channel | Parameter | Range |
|---|---|---|
| R | Weight 1 | [-4.0, 4.0] in 256 steps |
| G | Weight 2 | [-4.0, 4.0] in 256 steps |
| B | Bias | [-4.0, 4.0] in 256 steps |
The resulting color IS the model. Different training data produces different colors.
from aipixel.datasets import umbrella, sunscreen, escalate, xor
# Each returns (X, y, metadata)
X, y, meta = umbrella() # Rain chance + wind -> bring umbrella?
X, y, meta = sunscreen() # UV index + hours outside -> wear sunscreen?
X, y, meta = escalate() # Sentiment + severity -> escalate ticket?
X, y, meta = xor() # XOR pattern (unsolvable — demonstrates limits)from aipixel.viz import plot_decision_boundary, plot_pixel
# Decision boundary with confidence heatmap
plot_decision_boundary(model, X, y, meta)
# Display the pixel as a color swatch
plot_pixel(model)# Train from CSV (last column = label, all others = features)
ai-pixel train data.csv --output model.png
# Inspect a pixel model
ai-pixel inspect model.png
# Run a prediction
ai-pixel predict model.png --input "0.8,0.6"ai-pixel reports how much accuracy is lost when the model is compressed to a pixel:
report = model.quantization_report()
print(report["max_param_error"]) # Max error per parameter (typically < 0.016)
print(report["pixel_hex"]) # The model's colorA single neuron draws a straight line through your data. It works well for linearly separable problems but cannot learn patterns like XOR, circles, or anything requiring a curved decision boundary.
Try the XOR example to see it fail:
from aipixel.datasets import xor
X, y, meta = xor()
model = PixelModel(n_inputs=2)
model.train(X, y)
print(f"XOR accuracy: {model.accuracy(X, y):.1%}") # ~50% (random chance)This is why deeper networks exist. ai-pixel is an educational tool and a compression experiment, not a production ML framework.
ai-pixel uses PNG exclusively. The format is lossless, which matters because the model's weights are encoded in exact byte values. Saving as JPEG, taking a screenshot, or running through image optimization will corrupt the model.
MIT