LLM Analysis¶

For ambiguous cases where algorithmic scoring isn't decisive, phonemenal can hand off to an LLM for deep phonetic analysis.

Note

LLM analysis requires the llm extra: pip install phonemenal[llm]

Quick Start¶

from phonemenal import llm

# Via Anthropic Claude
result = llm.analyze("numpy", provider="anthropic")

# Via OpenAI
result = llm.analyze("numpy", provider="openai")

Providers¶

Anthropic (Default)¶

export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"  # optional

result = llm.analyze("numpy", provider="anthropic")

OpenAI¶

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o"  # optional

result = llm.analyze("numpy", provider="openai")

OpenAI-Compatible Gateway¶

For self-hosted models or proxies that expose an OpenAI-compatible API:

result = llm.analyze(
    "numpy",
    gateway_url="https://your-gateway.example.com/v1/chat/completions",
    model="your-model-name",
)

Local Agents¶

Run analysis through a local CLI agent:

# Claude Code CLI
result = llm.analyze("numpy", agent="claude")

# Codex CLI
result = llm.analyze("numpy", agent="codex")

# Custom executable
result = llm.analyze("numpy", agent="/path/to/my-agent")

The prompt is piped to the agent's stdin.

The Analysis Prompt¶

phonemenal ships a carefully crafted prompt template that instructs the LLM to:

Break the word into syllables and IPA pronunciation
Generate phonetic, orthographic, and compound-split variants
Score each variant on a 4-factor model:
- Onset/consonant skeleton (0.25 weight)
- Stressed vowel/main vowel contour (0.30 weight)
- Ending sound/coda (0.25 weight)
- Syllable count + stress/rhythm (0.20 weight)
Classify matches by score bands (exact, near, moderate, weak)

Viewing the Prompt¶

prompt = llm.get_prompt("numpy")
print(prompt)

# CLI — useful for piping to your own LLM
phonemenal prompt numpy | pbcopy

CLI Usage¶

# Anthropic (default)
phonemenal analyze numpy

# OpenAI
phonemenal analyze numpy --provider openai

# Specific model
phonemenal analyze numpy --model claude-opus-4-20250514

# Local agent
phonemenal analyze numpy --agent claude

# Gateway
phonemenal analyze numpy --gateway https://my-gateway.example.com/v1/chat/completions

When to Use LLM Analysis¶

Situation	Recommendation
Batch scanning thousands of names	Use `scanning.scan()` — algorithmic scoring is fast and deterministic
Triaging flagged matches	Use LLM analysis to get a detailed breakdown
Investigating a specific suspicious name	LLM analysis provides reasoning you can include in reports
Out-of-dictionary names with ambiguous scoring	LLM can reason about pronunciation from spelling