Metadata-Version: 2.4
Name: coldet
Version: 1.0.0
Summary: Colour detection inference — Python client and CLI.
Project-URL: Homepage, https://coldet.io
Project-URL: Documentation, https://coldet.io/docs
Project-URL: Repository, https://github.com/Coldet/coldet-python
Project-URL: Bug Tracker, https://github.com/Coldet/coldet-python/issues
License: MIT
Keywords: cli,color,colour,detection,image,inference
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: gradio-client>=1.1.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pyfiglet>=1.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: video
Requires-Dist: opencv-python>=4.8.0; extra == 'video'
Description-Content-Type: text/markdown

# coldet

**Colour detection inference — Python client and terminal CLI.**

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

```python
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

```bash
pip install coldet
```

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

```bash
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`.

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

Or set the environment variable instead:

```bash
export COLDET_API_TOKEN="your-api-key"
```

### 2. Run inference

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

### 3. Read the result

```python
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`

```python
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.

```python
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:

```bash
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.

```python
# 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
