# chromaframe-sdk

Deterministic, privacy-preserving Rust SDK for color measurement, quality/confidence scoring, and goal-specific candidate ranking.

## Features

| Feature | Purpose |
|---|---|
| default | Core deterministic measurement and ranking |
| `vision` | Region extraction abstractions and overlay types |
| `vision-helper` | Local Python/MediaPipe helper adapter |
| `live-gemini` | Gated provider smoke tests only; not used by local vision flows |

## Quickstart

```toml
chromaframe-sdk = "0.1"
```

Use manual region samples when you already have measured RGB samples, or enable `vision-helper` for local automatic region extraction.

## Local vision helper

See [`vision-helper/README.md`](vision-helper/README.md). Run parser setup before analysis:

```bash
uv run python sdk/vision-helper/scripts/setup-face-parser.py
```

Required helper environment:

```bash
CHROMAFRAME_VISION_HELPER_PYTHON=/absolute/path/to/python
CHROMAFRAME_MEDIAPIPE_TASK_PATH=/absolute/path/to/face_landmarker.task
CHROMAFRAME_FACE_PARSING_ONNX_PATH=/absolute/path/to/resnet18.onnx
CHROMAFRAME_VISION_ASSET_MANIFEST=/absolute/path/to/resnet18.manifest.json
```

Product image analysis requires an approved baseline face-parser ONNX asset and manifest. Sparse or absent parser hair remains `not_measured` with `semantic_parser_hair_evidence_low` after the parser runs. Beard/stubble uses a conservative lower-face proxy: `approximate`/`landmark_lower_face_proxy` means enough color/texture evidence exists to use it as low-confidence facial-hair evidence; `low_evidence`/`clean_shaven_or_low_stubble_evidence` means the proxy is skin-like or ambiguous and is not converted into beard samples for scoring. This is not a definitive no-beard classifier, and baseline parsers must not claim beard/moustache/stubble detection.

## Privacy

- `Debug` implementations redact image bytes, pixels, masks, private paths, and provider/helper payloads.
- Image metadata is not retained by default.
- Overlay artifacts are SDK-local opt-in only and must not be committed.
- Reports describe deterministic color fit and uncertainty only.

## Development

From repository root:

```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test -p chromaframe-sdk --all-features
```

## Publishing

SDK releases use `sdk-vX.Y.Z` tags, require the tag version to match `sdk/Cargo.toml`, list package contents, and run a locked dry-run publish before publishing. See [`../docs/releasing.md`](../docs/releasing.md).
