> ## Documentation Index
> Fetch the complete documentation index at: https://f4c7a9e2d8b1-docs.tenzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Default Pronunciations

> Manage the org-agnostic pronunciation defaults that apply to every org, and read their usage

<Warning>
  **Restricted Access**: This panel and doc are internal-only. Global defaults change what the AI says on **every org's** calls.
</Warning>

## What this is

Every AI interview call applies a set of built-in **default** pronunciation rules on top of whatever rules an org configures for itself — things like `TX` → "Texas", `401k` → "four oh one K", and `HIPAA` → "hippa". These defaults were previously hardcoded in Python code and have now been seeded into the `global_pronunciations` database table.

The **Internal Tools → Pronunciations** panel makes that set editable at runtime. The database table is the single source of truth for global defaults across the system.

## Where to configure

**Internal Tools → Pronunciations** (support/full-access users only).

The editor works exactly like the per-org pronunciation page: a **Spelled as** term, a **Spoken as** respelling, and a **Match case** toggle. Only the audio changes — transcripts, summaries, and notes keep the original spelling.

## How resolution works

Resolution is fully database-driven:

1. The `global_pronunciations` database table is the source of truth for global defaults.
2. If the table row is absent or a database error occurs, resolution fails soft to an empty list (no default dictionary).
3. An org's own custom rules always win over a default for the same term on conflict.
4. Changes propagate to running backend processes within one cache TTL (60s).

## Never expose the global set to customers

The global rules are org-agnostic and can name other customers' brands and terms, so the list
itself is effectively an unofficial client list. Keep it internal:

* The per-org settings API returns only that org's own rules, and the customer docs and settings
  page deliberately say nothing about a built-in list. Don't add one.
* Customers don't need visibility into it. If a default mispronounces something for them, they add
  their own rule for that term and it **overrides** ours — no support ticket, no disclosure.

## Two important caveats

* **Blast radius.** A bad global rule degrades calls for *every* customer. Keep terms long and distinctive, and prefer **Match case** for short codes (e.g. `TX`) so they never fire inside ordinary words. Some state codes that are also English words (`OR`, `IN`, `ME`, …) are deliberately excluded — adding one is possible but breaks calls that use the word normally.
* **Orgs with their own rules don't update retroactively.** An org that saved its own pronunciations baked the previous defaults into its ElevenLabs dictionary at save time. Editing the globals does **not** rebuild those dictionaries; run the `backfill_pronunciation_defaults` one-time job to refresh them.

## Usage tracking

Below the editor, the **Usage** table shows how many recent calls actually said each global term, from the offline `scan_pronunciation_usage` job.

This measures **opportunity**, not confirmed pronunciation: ElevenLabs gives no per-rule firing feedback, so the job counts calls whose agent speech contained the term (agent speech keeps its original spelling). A term that never appears over a long window is a candidate for removal; a term that appears constantly clearly earns its place. Global rows slightly over-count, because an org that overrides a term still says it.

The scan records usage at **both tiers** in the `pronunciation_usage` table, distinguished by a `level` column:

* `level = 'global'` (org\_id NULL) — a default rule, counted across every org's calls. This is what the panel shows.
* `level = 'org'` (org\_id set) — an org's own custom rule, counted only within that org's calls.

Each scan writes the whole snapshot in one transaction (a full replace), so removed rules are pruned. Org-level usage is recorded and queryable now; it is not yet surfaced on the per-org settings page.

Run the scan from `server/`:

```bash theme={null}
python -m one-time-jobs.scan_pronunciation_usage --days 30
python -m one-time-jobs.scan_pronunciation_usage --days 30 --apply
```