Upload README.md

README.md

@@ -0,0 +1,85 @@
+---
+license: mit
+library_name: scikit-learn
+tags:
+  - color-classification
+  - random-forest
+  - tabular-classification
+  - scikit-learn
+---
+
+# Color AI — chroma classifiers
+
+Three trained color-naming classifiers: given a color, they name it —
+"red", "navy", "charcoal", etc. Each is a `scikit-learn`
+`RandomForestClassifier`, trained entirely on synthetic labeled data (no
+photos, no dataset needed to build them) — see
+[color-ai-core](https://pypi.org/project/color-ai-core/) on PyPI for the
+code that trained these and the functions to use them correctly.
+
+## Files
+
+| File | Code name | Colors | Trees | Samples/class | Validation accuracy |
+|---|---|---|---|---|---|
+| `color_classifier_nano.joblib` | `chromav1n-clf` | 12 | 60 | 400 | 92.4% |
+| `color_classifier_micro.joblib` | `chromav1u-clf` | 24 | 80 | 500 | 82.7% |
+| `color_classifier_microsuper.joblib` | `chromav1us-clf` | 24 | 80 | 800 | 84.4% |
+
+**Nano** covers the basics: red, orange, yellow, green, teal, blue,
+purple, pink, brown, black, gray, white.
+
+**Micro** and **Micro Super** add 12 more: maroon, navy, olive, lime,
+cyan, magenta, indigo, coral, mint, lavender, beige, charcoal. Micro
+Super is the same 24 classes as Micro, just trained on more samples per
+class (800 vs 500), which measurably improves accuracy — same anchors,
+same architecture, purely more training evidence.
+
+Micro and Micro Super also support a **two-stage fallback**: when the
+model isn't confident (below 50%) in its specific pick, it's meant to
+report the broader Nano-family color instead of guessing between two
+close options (e.g. "brown" instead of a shaky call between beige and
+charcoal). This logic lives in the `color-ai-core` package, not baked
+into the `.joblib` file itself — see Usage below.
+
+## Usage
+
+⚠️ These models do **not** take raw RGB as input. They were trained on a
+4-value feature vector — `[sin(hue), cos(hue), saturation, value]` — not
+`[R, G, B]` directly. Feeding raw RGB straight to `.predict()` will run
+without error but give meaningless results. Use the matching feature
+function from `color-ai-core` rather than hand-rolling it:
+
+```bash
+pip install color-ai-core huggingface_hub
+```
+
+```python
+from huggingface_hub import hf_hub_download
+from color_ai_core import load_model, predict_color
+
+path = hf_hub_download(repo_id="YOUR_USERNAME/YOUR_REPO_NAME",
+                        filename="color_classifier_micro.joblib")
+clf = load_model(path)
+
+name, confidence, used_fallback = predict_color(clf, [220, 40, 30], tier="micro")
+print(name)  # "red"
+```
+
+`predict_color()` handles the RGB → feature conversion and the two-stage
+fallback correctly — that's why it's the supported way to use these
+files rather than calling `clf.predict()` directly.
+
+## Training
+
+All three were trained on jittered synthetic data generated around fixed
+HSV anchor points per color (e.g. red ≈ hue 0°, high saturation, high
+value) — noise is added to hue, saturation, value, and the final RGB to
+simulate lighting and camera variation, so each model learns a color's
+*range* rather than one exact shade. No photos were used to train these
+specific files. `color-ai-core` also includes `train_from_images()` for
+training a classifier on your own labeled photos instead, if you'd
+rather have that.
+
+## License
+
+MIT