Installation¶

Requirements¶

Python 3.11 or later

Install from PyPI¶

pip install phonemenal

Or with uv:

uv add phonemenal

Optional Extras¶

LLM Support¶

For deep phonetic analysis powered by Anthropic Claude or OpenAI GPT:

pip install phonemenal[llm]

This adds the anthropic and openai SDKs. You'll need an API key set in your environment:

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."

Tip

If you use a local agent (e.g. phonemenal analyze numpy --agent claude), you don't need the llm extra — agents are invoked as subprocesses and have no Python SDK dependency.

Grapheme-to-Phoneme¶

For G2P-based pronunciation of out-of-dictionary words:

pip install phonemenal[g2p]

All Extras¶

pip install phonemenal[llm,g2p]

NLTK Data¶

phonemenal uses the CMU Pronouncing Dictionary from NLTK. It is downloaded automatically on first use, but you can pre-fetch it:

python -c "import nltk; nltk.download('cmudict', quiet=True)"

Or via the Makefile:

make setup

Development Install¶

git clone https://github.com/brokensound77/phonemenal.git
cd phonemenal
uv sync --all-extras
make setup  # download NLTK data
make test   # run the test suite

Verify Installation¶

phonemenal --version
phonemenal similarity crowd crown