CLI Reference

emb-diversity provides a command-line interface for measuring diversity from text files.

Installation

The CLI is installed automatically with the package:

pip install emb-diversity

Commands

emb-diversity measure

Measure diversity from a text file, CSV, or TSV.

emb-diversity measure INPUT_FILE [OPTIONS]

Arguments:

Argument	Description
INPUT_FILE	Path to .txt, .csv, or .tsv file

Options:

Option	Default	Description
-m, --measure	graph_entropy, vendi_score, mean_pw_dist	Measure(s) to run. Repeat for multiple. Named sets: variety, balance, disparity; all for every measure
-a, --axis	semantic	Diversity axis
--model	(none)	Explicit embedding model (overrides --axis)
-c, --column	text	Column name for CSV/TSV files
-f, --format	table	Output format: table, json, csv
--chunking	off	Chunk long texts instead of truncating them to the model’s max length
--chunks	10	Max windows per text when --chunking is set
--pooling	mean	How to combine chunk vectors when --chunking is set: mean or max

Examples:

# Default measure on a text file (one text per line)
emb-diversity measure texts.txt

# A named measure set (variety, balance, or disparity)
emb-diversity measure texts.txt -m variety

# All measures
emb-diversity measure texts.txt -m all

# Specific measures
emb-diversity measure texts.txt -m mean_pw_dist -m diameter -m vendi_score

# Style diversity
emb-diversity measure texts.txt --axis style

# Custom embedding model
emb-diversity measure texts.txt --model all-MiniLM-L6-v2

# Chunk long texts instead of truncating (5 windows per text, mean-pooled)
emb-diversity measure texts.txt -m mean_pw_dist --chunking --chunks 5 --pooling mean

# CSV with custom column
emb-diversity measure reviews.csv --column review_text

# TSV file
emb-diversity measure data.tsv --column sentence

# JSON output (for piping)
emb-diversity measure texts.txt -m variety --format json

Output formats:

• table (default) and csv show one score (the measure’s value) per measure.

• json emits the full result per measure, including the parameters used and the package version that computed it:

  {
    "mean_pw_dist": {
      "value": 0.71,
      "parameters": {"metric": "cosine", "embedding_model": "..."},
      "version": "0.0.10"
    }
  }
  

Input formats:

• .txt: one text per line

• .csv: comma-separated, reads the text column by default

• .tsv: tab-separated, reads the text column by default

emb-diversity list-measures

List all available diversity measures.

emb-diversity list-measures

Measures tagged [default] run when no -m flag is given. Measures tagged [variety], [balance] or [disparity] belong to that named set and can be selected with -m <name>.

emb-diversity list-axes

List registered diversity axes and their models.

emb-diversity list-axes