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

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.