-
-
Process Flow Diagram
-
Canonical Demo: Interactive Pronunciation Results
-
PPA Web App: Script Preflight Interface
-
Banner
Inspiration
Modern synthetic voices can sound remarkably natural and still confidently mispronounce the exact words that matter most: medications, scientific terminology, personal names, geographic locations, acronyms, and context-dependent words.
Those mistakes are expensive downstream. They can undermine the credibility of educational and technical content, confuse listeners, create accessibility problems, and force creators to regenerate or manually repair narration after synthesis has already begun.
Most pronunciation workflows are reactive:
generate the narration → hear the error → investigate it → modify the script or synthesis settings → render again.
Pronunciation Preflight Agent (PPA) moves that work upstream.
PPA treats pronunciation as a research and verification problem, not merely a text-substitution problem.
What it does
PPA analyzes an English-language production script before narration or Text-to-Speech generation begins.
It:
- identifies likely pronunciation risks;
- analyzes the surrounding context;
- creates contextual research units;
- plans targeted pronunciation research;
- uses Parallel Search to gather external evidence;
- uses Gemini and Google ADK to synthesize and reason over that evidence;
- applies deterministic validation, provenance checks, pronunciation policy, and bounded repair;
- classifies each result as Verified, Unverified, or Unresolved;
- automatically inserts only Verified pronunciations into generated SSML.
This distinction is important because uncertainty should remain visible rather than being silently converted into confident synthetic speech.
A plausible pronunciation is not automatically treated as a verified pronunciation.
Context matters
PPA researches pronunciation in context, rather than treating every spelling as one universal lookup.
For example:
- record as a noun and record as a verb can become separate research units;
- medications such as quetiapine can require specialized pronunciation evidence;
- scientific and technical terminology can require authoritative research;
- names and places such as Worcester can require pronunciation verification beyond ordinary spelling rules.
PPA V1 is optimized for technical, scientific, medical, geographic, personal-name, and context-sensitive pronunciation risks.
How I built it
The workflow combines agentic reasoning with deterministic safeguards.
Google ADK + Gemini
Google Agent Development Kit (ADK) provides agent orchestration, while Gemini performs structured reasoning, contextual analysis, research planning, evidence synthesis, and semantic evaluation.
The workflow is multi-stage rather than a single LLM prompt.
Parallel Search
Parallel Search provides the external research layer.
During live credentialed runs, PPA calls the Parallel Search API to discover pronunciation evidence and supporting sources for contextual research units.
The retrieved evidence is then structured and evaluated rather than blindly copied into the final output.
Deterministic validation
Model-generated findings pass through a deterministic Python pipeline that performs:
- evidence and provenance checks;
- pronunciation-equivalence handling;
- locale-sensitive policy;
- structured validation;
- semantic validation;
- bounded repair;
- conservative outcome classification;
- verified-only SSML generation.
This separation is deliberate:
agentic reasoning where interpretation and research are valuable; deterministic code where reproducibility and production safety matter.
The high-level workflow is:
Script → Risk Detection → Contextual Research Units → Google ADK + Gemini → Parallel Search → Evidence Synthesis → Deterministic Validation → Verified / Unverified / Unresolved → Verified-Only SSML + Reports
Canonical demonstration
The bundled demonstration produces:
- 6 flagged research units
- 4 Verified
- 1 Unverified
- 1 Unresolved
- 4 Verified-only SSML substitutions
The demonstration intentionally includes uncertainty instead of presenting an artificial perfect-result showcase.
It includes a geographic pronunciation challenge, a personal name, a medication, two context-dependent uses of the same spelling, and a fictional term.
Product experience
PPA includes an interactive web application for exploring completed pronunciation preflights.
Users can inspect flagged terms and their research outcomes, review pronunciation guidance, and download production artifacts including:
- flagged script;
- JSON and Markdown reports;
- audit information;
- pronunciation guidance;
- verified-only SSML;
- a portable saved-preflight ZIP.
A downloaded preflight can later be reopened in the web application without rerunning Gemini or Parallel Search.
The public Cloud Run instance is intentionally credential-free so API credentials are never exposed and judging does not consume live research quota. It provides the complete canonical saved preflight for interactive exploration. The public repository contains the full live-capable implementation and configuration instructions.
Challenges I ran into
The hardest problem was not finding a possible pronunciation. It was determining when PPA had enough evidence to justify automating one.
Pronunciation research can produce:
- conflicting sources;
- locale-specific variants;
- incomplete evidence;
- multiple equivalent phonetic representations;
- ambiguous context;
- structurally valid but semantically weak model outputs.
That required much more than search alone.
PPA developed explicit evidence qualification, provenance reconciliation, pronunciation-equivalence logic, semantic validation, bounded repair, and conservative outcome classification.
Another major challenge was preserving context through the entire workflow. Two identical spellings in one script may require separate research because their intended meanings and pronunciations differ.
That led to PPA's contextual research-unit architecture.
Accomplishments
I am especially proud that PPA became a complete production workflow rather than a single AI demonstration.
The project includes:
- an agentic Google ADK / Gemini research pipeline;
- live Parallel Search integration;
- deterministic safety and validation layers;
- three explicit uncertainty outcomes;
- verified-only SSML;
- detailed audit and reporting outputs;
- portable saved preflights;
- an interactive web interface;
- a public Google Cloud deployment;
- a comprehensive offline regression suite.
The current offline suite contains 550 passing tests covering the application pipeline, evidence handling, contextual grouping, semantic validation, research escalation, repair behavior, pronunciation policy, reporting, web functionality, and agent workflow.
What I learned
The largest lesson was that pronunciation verification is much closer to evidence-based research than to spell-checking.
A useful pronunciation system needs to ask:
- What term is risky?
- What does it mean in this sentence?
- What pronunciation claims exist?
- Which sources support those claims?
- Do those sources apply to this usage and locale?
- Are different phonetic representations actually equivalent?
- Is the evidence strong enough for automation?
- If not, how should uncertainty be communicated?
I also learned that the natural unit of pronunciation research is often not a unique word.
It is a contextual research unit.
Two identical spellings can represent two different pronunciation problems.
What's next
PPA V1 is tuned for real-world technical, scientific, medical, geographic, personal-name, and context-sensitive terminology.
Automatic detection of arbitrary fictional or newly coined terminology remains best-effort. Once such a term is identified, the downstream research and uncertainty-handling pipeline can process it normally.
Future work could expand coined-term detection, pronunciation-source specialization, production-system integrations, collaborative human review, and direct integration with narration and speech-synthesis pipelines.
Why it matters
As synthetic narration becomes increasingly natural, individual pronunciation mistakes become more conspicuous.
One badly pronounced medication, name, city, company, or technical term can damage the credibility of an otherwise excellent production.
PPA provides a quality-control layer upstream of voice generation and narration.
Ordinary spell-check catches writing mistakes. PPA catches pronunciation risks before they become spoken errors.
Log in or sign up for Devpost to join the conversation.