color-ai-core
A trainable color-naming AI, built to be used as code, not just commands — import it, choose which model to use, automate it in a script, or train it on your own photos. No web page, no Flask, no object detection (YOLO), no pretrained files bundled.
Install
pip install color_ai_core-0.2.0-py3-none-any.whl
Pulls in scikit-learn, joblib, numpy, and Pillow. Nothing heavier.
The actual API
from color_ai_core import (
load_color_model, load_model, predict_color, dominant_rgb,
train_synthetic, train_from_images, NANO_ANCHORS, MICRO_ANCHORS,
)
# --- use one of the three built-in tiers ---
clf = load_color_model("nano") # or "micro" / "microsuper"
name, confidence, used_fallback = predict_color(clf, [220, 40, 30], tier="nano")
print(name) # "red"
# --- choose your own hyperparameters / color set, fully in code ---
clf, accuracy = train_synthetic(
anchors=NANO_ANCHORS + [("teal", 175, 0.7, 0.6)],
samples_per_color=600,
n_estimators=100,
max_depth=14,
output_path="models/my_custom.joblib",
)
# --- train on YOUR OWN photos instead of synthetic data ---
clf, report = train_from_images("my_photos/", output_path="models/mine.joblib")
print(report) # {'classes': [...], 'class_counts': {...}, 'accuracy': 0.94, ...}
# --- automate it: classify a whole folder of images in a loop ---
from pathlib import Path
from color_ai_core import image_to_dominant_rgb
for photo in Path("some_folder").glob("*.jpg"):
dom = image_to_dominant_rgb(photo)
name, _, _ = predict_color(clf, dom)
print(photo.name, "->", name)
Nothing here requires shelling out to a command — every piece is a plain function you call, with return values (not just printed output), so it drops into a script, a loop, a pipeline, whatever you're building.
train_from_images() — training on your own photos
Point it at a folder laid out one subfolder per color name:
my_photos/
red/
shirt1.jpg
car.png
navy/
jacket.jpg
turquoise/
pool.jpg
Each image's overall dominant color becomes one training example, labeled with the folder it came from. Class names are whatever you name the folders — not limited to the built-in tiers' colors. A few dozen images per color is a reasonable starting point.
CLI wrappers (optional, thin convenience layer over the same functions)
color-ai-train # builds the 3 built-in tiers
color-ai-train-images my_photos/ --out models/mine.joblib
color-classify-rgb 220 40 30 --model micro
color-classify-image photo.jpg --model microsuper
The three built-in tiers
| Tier | Code name | Colors | Trees | Samples/class |
|---|---|---|---|---|
| Nano | chromav1n-clf |
12 (red, orange, yellow, green, teal, blue, purple, pink, brown, black, gray, white) | 60 | 400 |
| Micro | chromav1u-clf |
Nano's 12 + 12 more (maroon, navy, olive, lime, cyan, magenta, indigo, coral, mint, lavender, beige, charcoal) | 80 | 500 |
| Micro Super | chromav1us-clf |
Same 24 as Micro | 80 | 800 |
Micro and Micro Super use a two-stage fallback: if the model isn't
confident (below 50%) in its specific pick, it reports the broader
nano-family color instead of guessing. This is opt-in for your own custom
models too — see predict_color()'s uses_fallback/parent_map/
confidence_threshold arguments.
What's NOT here
Object detection / separating a photo into individual objects (that's YOLO's job, a completely different kind of model) and the web page from an earlier version of this project. Both were deliberately left out — this package is the color AI only.
Sharing it
Hand someone the .whl file directly — no GitHub, no PyPI account
needed. They run the one pip install command above.
Metadata
Release files for color-ai-core 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| color_ai_core-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for color_ai_core-0.2.0-py3-none-any.whl |
Release files / color_ai_core-0.2.0-py3-none-any.whl
| Download URL | color_ai_core-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1ba21ddf86754fb5e91d11adf4303c347a0df93e4c5f4d06c49cfe93b8f26492
|
|
BLAKE2b-256 checksum How to use checksums |
2505a7dcb73a088b4c0cc689e7e3574110ba16d260d7cded52920811227c0c1b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for color-ai-core 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.