uhc-voice-core-ts

Reusable voice i18n core utilities for UHC/UNID services.

Features

• Load locale JSON files from ESM modules.
• Resolve locale by language prefix with fallback.
• Render {{variable}} templates.
• Resolve localized language names with fallback to Intl APIs.
• Share provider-neutral batch/streaming transcription contracts.
• Share allowlisted intent proposal, resolution and provider-attempt contracts.
• Share JSON Schema 2020-12 forms and person/animal applicability for subject, appointment, medication, immunization, allergy, condition, procedure and observation intents. Deterministic rules run before any model; FunctionGemma or a larger remote model can only propose a catalog entry and field values.
• Keep companion conversation and consent-gated social fact proposals separate from operational intents.

Install

npm install uhc-voice-core-ts

API

• loadJsonFile(relativePath, importMetaUrl)
• loadVoiceRuntimePanelCatalog() loads the canonical runtime YAML from the installed npm package; consumers do not need a sibling source checkout.
• resolveLocaleByPrefix(value, supportedLocales, fallbackLocale)
• renderTemplate(template, vars)
• getLocalizedLanguageName(targetLocale, uiLocale, localeNames, supportedLocales, fallbackLocale?)
• AssistantAudioTranscriptionProvider for short push-to-talk audio.
• AssistantStreamingTranscriptionProvider for later partial transcripts.
• AssistantIntentProvider and AssistantIntentResolution for proposal-only deterministic/local/remote routing.
• AssistantCompanionProvider for disclosed conversation whose extracted facts still require consent and confirmation.
• resolveAssistantCompanionActivation for a controller-configurable wake phrase (default conversai) and speaker-scoped companion context.
• Reviewable social, family, wellbeing and vital-sign proposals. Repeated measurements remain proposals until a clinical application groups and saves them through its canonical FHIR/Communication path.

Providers defined here have no SDK or GW dependency. Model output cannot invoke application functions; a channel validates, previews and confirms through its normal builders and authorization path.

Canonical Voice Flow

The current UHC/UNID phone-assistance flow is specified in:

• flow-personal-phone-assistance.md

Supporting demo-specific voice materials now live in:

• docs/101-VOICE_FLOW_V1_2_DEMO.md
• docs/101-VOICE_FLOW_V1_2_DEMO.runtime.yaml
• docs/101-VOICE_FLOW_V1_2_DEMO.panels.yaml

That file is consumed by uhc-unid-chat-node and is the canonical source for:

• onboarding gate fields
• individual data capture menus
• appointment and medication voice menus
• permission-management prompts
• the shared permission-set order used by telephone, web, chat and WhatsApp: choose permit or deny, choose data scopes, resolve a country or verified contact, choose jurisdiction-allowed roles, review the complete authorization and confirm once with key 9; country input is spoken rather than a numbered country list
• minimum subject identity context accompanies clinical or emergency-contact access and is stated in the review: usual/display name, birth date or year, and administrative sex when recorded. It is not a hidden extra choice
• human clinical permission selection for all IPS sections or an explicit governed IPS section list; administrative roles are organization-only and billing-only, and paramedics are exposed only where jurisdiction policy enables them
• CALL_INDIVIDUAL_TYPE person/animal activation conditions
• direct routing to the configured subject type without asking the caller to choose between person and animal
• the animal name, birth-date and exact NCBI species menu, retained as catalogued_disabled while UHC is configured for people; breed is not part of telephone onboarding
• the channel-neutral animal species fallback catalog: exact speech/search first, then three numbered choices per page, 9 next, 7 previous and 8 to retain a private cardless draft instead of hanging up
• the currently disabled person-only procedures/donations questionnaire for prior donation, blood group, country, recency, donation type, approximate date and current country of residence

The donation and animal-only panels are catalogued as catalogued_disabled: this release does not change the UHC person handlers or activate those branches.

The docs/101-VOICE_FLOW_V1_2_DEMO* files are supplementary demo documents. They belong with voice ownership, not with gdc-sdk-core-ts.