Metadata-Version: 2.4
Name: vec-cluster
Version: 0.2.0
Summary: Inspect and cluster generic vector features for entities
Author-email: mikewong23571 <mikewong23571@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mikewong23571/vec-cluster
Project-URL: Repository, https://github.com/mikewong23571/vec-cluster
Project-URL: Issues, https://github.com/mikewong23571/vec-cluster/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: pyarrow>=15.0.0

# vec-cluster

Inspect and cluster generic vector features for entities. Lightweight CLI built with Typer + Rich.

- Repo: https://github.com/mikewong23571/vec-cluster
- License: MIT
- Python: 3.10+

## Install

```bash
uv venv
uv sync
```

## Usage

```bash
# Help
uv run vec-cluster -h

# Inspect (recommended first)
uv run vec-cluster inspect features.csv

# One-shot auto cluster
uv run vec-cluster auto features.csv
```

After publishing to PyPI you can run without installing:

```bash
uvx vec-cluster inspect features.csv
```

### Commands quick reference

- `inspect` — data health, distance distribution, HAC threshold suggestions.
- `auto` — HAC with suggested medium threshold, writes clusters + report.
- `hac` — hierarchical clustering (requires `--k` or `--threshold`).
- `kmeans` — k-means (requires `--k`).
- `dbscan` — DBSCAN (`--eps`, `--min-samples`, cluster=-1 => outlier).

## Development

```bash
uv run ruff format
uv run ruff check
uv run mypy src tests
uv run pytest          # full suite with coverage gate
```

Design/contract document: `docs/design.md`.
