# ISIS v2 WS08-004: Voice Consistency Profiles

## Scope

`WS08-004` implements first-class voice consistency profile contracts for audio
voice workflows, including speaker embedding controls, pronunciation lexicon
controls, and style token controls with provider-capability-aware runtime
application.

## Research and Existing Implementation Alignment

Before implementation, existing ISIS patterns were reviewed in:

- Existing provider fields and API contracts:
  - `libs/isis/ai-providers/src/types/tts.types.ts`
  - `libs/isis/ai-providers/src/providers/tts/elevenlabs-provider.ts`
- Existing voice profile and pronunciation system primitives:
  - `libs/isis/audio-generation/src/voice/elevenlabs-client.ts`
  - `libs/isis/ai-providers/src/providers/conversational-ai/pronunciation-dictionary`
- Existing generation-api normalization/capability-guard patterns:
  - `apps/isis/generation-api/src/workflows/executor.ts`
  - `apps/isis/generation-api/src/schemas/job.schema.ts`

These references were used to align new contracts with current ISIS naming and
provider behavior (voice IDs, pronunciation dictionary locators, and
consistency-related voice controls).

## Deliverables

1. Typed API and SDK contracts

- Added `voiceConsistency` / `voice_consistency` request contracts across:
  - `apps/isis/generation-api/src/types.ts`
  - `libs/isis/client/src/types.ts`
- Added typed fields for:
  - profile identifiers and voice/speaker IDs
  - speaker embedding ID/URL/vector and reference audio URLs
  - pronunciation lexicon IDs and dictionary locators
  - style tokens and consistency strength
  - provider capability mode and prompt-preservation policy

2. Validation support in generation API

- Added `JobVoiceConsistencyRequestSchema` in
  `apps/isis/generation-api/src/schemas/job.schema.ts`.
- Added strict validation for URL fields, embedding vector bounds, enum values,
  and numeric ranges.
- Added schema regression tests for valid and invalid payloads.

3. Workflow capability exposure

- Extended `voice-performance-synthesis` workflow inputs with explicit voice
  consistency controls:
  - `voice_consistency_profile_id`, `voice_id`
  - `speaker_embedding_id`, `speaker_embedding_url`, `speaker_embedding_vector`,
    `speaker_reference_audio_urls`
  - `pronunciation_lexicon_ids`, `pronunciation_dictionary_locators`
  - `style_tokens`, `voice_consistency_strength`,
    `voice_consistency_provider_mode`

4. Runtime normalization, mapping, and diagnostics

- Added canonical request normalization for `voiceConsistency` payloads.
- Added capability-aware input mapping to workflow inputs.
- Added provider capability guard behavior:
  - `providerCapabilityMode: "required"` blocks application when workflow does
    not expose voice consistency inputs.
- Added execution diagnostics at `output.metadata.voiceConsistency` with:
  - support/blocking status
  - requested embedding/lexicon/style token counts
  - supported and used workflow input keys

5. Regression coverage

- Added executor regression coverage validating voice consistency contract
  application and diagnostics for `voice-performance-synthesis` workflow runs.

## Verification Commands

```bash
pnpm --filter @isis/workflows exec vitest run src/workflows.spec.ts --reporter=dot
pnpm --filter @isis/generation-api exec vitest run src/schemas/job.schema.spec.ts src/workflows/executor.spec.ts --reporter=dot
```

## Result

`WS08-004` is now implemented as a typed, validated, and runtime-enforced voice
consistency profile system, with first-class support for speaker embeddings,
pronunciation lexicons, and style token controls in ISIS audio voice workflows.
