coldet 1.0.0

Colour detection inference — Python client and CLI.

coldet

Colour detection inference — Python client and terminal CLI.

Point it at an image. Get a colour back. That's the core of it.

import coldet

coldet.token("your-api-key")                        # save once
result = coldet.request("product-photo.jpg", "coldet-v1-mini")

print(result["predicted"])    # → "beige"
print(result["confidence"])   # → 0.2778

---

Installation

pip install coldet

Add [video] to enable MP4 frame-by-frame analysis:

pip install "coldet[video]"

Requires Python ≥ 3.9.

---

Quick start

1. Save your API token

You only need to do this once. The token is written to ~/.config/coldet/token.

import coldet
coldet.token("your-api-key")

Or set the environment variable instead:

export COLDET_API_TOKEN="your-api-key"

2. Run inference

result = coldet.request("shirt.jpg", "coldet-v1-mini")

3. Read the result

print(result["predicted"])          # top colour name
print(result["confidence"])         # float 0–1
print(result["probabilities"])      # dict of all classes → probabilities
print(result["credits_left"])       # remaining API credits

---

API reference

coldet.token(value=None)

Get or set the saved API token.

Parameter	Type	Description
value	str | None	When given, writes the token to disk and returns it. When omitted, returns the saved token (or None).

Returns str | None

coldet.token("sk-abc123")   # save
tok = coldet.token()         # read back → "sk-abc123"

---

coldet.request(image_path, model, *, api_token=None)

Run colour-detection inference on a local image.

Parameter	Type	Default	Description
image_path	str	required	Local file path or public URL.
model	str	"coldet-v1-mini"	Model name — no extension needed.
api_token	str | None	None	Override the saved token for this call only.

Returns dict with the following keys:

Key	Type	Description
predicted	str	Top predicted colour name.
confidence	float	Probability of the top prediction (0–1).
probabilities	dict[str, float]	Full distribution over all colour classes.
credits_left	int	API credits remaining on your account.
user	str	Username associated with the token.
model	str	Model that produced the result.

Raises coldet.ColdetError if the token is missing, the file cannot be read, or the API returns an error.

---

coldet.ColdetError

Exception raised by coldet.request() on any API or configuration failure.

try:
    result = coldet.request("photo.jpg")
except coldet.ColdetError as e:
    print(f"something went wrong: {e}")

---

Available models

Model	Description
coldet-v1-mini	Fast, lightweight model. 58 colour classes. Recommended for most use cases.

More models will be added as they are released.

---

CLI

Installing the package registers a coldet command:

coldet

The terminal interface is interactive:

• Drop in an image path (Tab-completion available) to run inference and see the full colour distribution.
• Type // to open the command menu:
  • /model — switch the active model
  • /token — save or rotate your API token
  • /whoami — inspect your current token and model
  • /quit — exit

MP4 files are processed frame-by-frame when opencv-python is installed.

---

Configuration

Method	Details
coldet.token("key")	Saves to ~/.config/coldet/token
COLDET_API_TOKEN env var	Read at runtime if no file is present
COLDET_CONFIG_DIR env var	Override the config directory

---

Importing as a package

coldet is a regular importable package — the CLI is just one entry point.

# Batch-process a folder
from pathlib import Path
import coldet

coldet.token("your-api-key")

images = Path("product-photos").glob("*.jpg")
for img in images:
    result = coldet.request(str(img))
    print(img.name, "→", result["predicted"], f"({result['confidence']:.1%})")

---

License

MIT