feat(stage-ui): add abstract base interfaces for transcription and sp…

[lockrush-dev]

Refactor All Speech and Transcription Providers to Unified defineProvider() Pattern

Summary

This PR refactors all speech and transcription providers to use the unified defineProvider() pattern (as established in PR #968), improving architectural consistency, reducing code duplication, and enabling consistent provider discovery across all provider types.

Changes

Core Architecture

• Unified Pattern: Refactored all speech and transcription providers to use the unified defineProvider() pattern instead of separate registries
• Converter Function: Added convertProviderDefinitionToMetadata() to bridge the unified defineProvider() pattern with the existing store's ProviderMetadata format
• Task-Based Classification: Providers now declare their capabilities via tasks array (e.g., ['text-to-speech', 'speech'] for speech providers, ['speech-to-text', 'automatic-speech-recognition', 'asr', 'stt'] for transcription providers)
• Extra Methods: Provider-specific methods like listModels and listVoices are now defined in extraMethods within the unified pattern
• Deprecated Interfaces: Marked old BaseSpeechProviderDefinition and BaseTranscriptionProviderDefinition interfaces as deprecated (kept for backward compatibility)
• Shared Utilities: Created normalizeBaseUrl utility function to eliminate code duplication across provider implementations

Provider Implementations

Speech Providers (9 total) - All Migrated ✅

• OpenAI Speech: Refactored to use defineProvider() with tasks: ['text-to-speech', 'speech'] and extraMethods for listModels and listVoices
• OpenAI Compatible Speech: Refactored to use defineProvider() with tasks: ['text-to-speech', 'speech'] and extraMethods for listModels and listVoices
• ElevenLabs: Migrated to unified pattern with voice listing support
• Deepgram TTS: Migrated to unified pattern with voice listing support
• Microsoft Speech: Migrated to unified pattern with region support and voice listing
• Index-TTS vLLM: Migrated to unified pattern with voice listing support
• Alibaba Cloud Model Studio: Migrated to unified pattern with voice listing support
• Volcengine: Migrated to unified pattern with app configuration and voice listing
• Player2 Speech: Migrated to unified pattern with voice listing support

Transcription Providers (4 total) - All Migrated ✅

• OpenAI Transcription: Refactored to use defineProvider() with tasks: ['speech-to-text', 'automatic-speech-recognition', 'asr', 'stt'] and extraMethods for listModels
• OpenAI Compatible Transcription: Refactored to use defineProvider() with tasks: ['speech-to-text', 'automatic-speech-recognition', 'asr', 'stt'] and extraMethods for listModels
• Browser Web Speech API: Migrated to unified pattern with browser availability validation
• Aliyun NLS Transcription: Migrated to unified pattern with streaming transcription support and region configuration

All providers are now automatically registered when imported via the unified registry and can be discovered via listProviders() and getDefinedProvider().

Code Quality Improvements

• Type Safety: Improved type safety by using Zod schemas for configuration validation within the unified pattern
• Code Deduplication: Extracted base URL normalization logic to a shared utility function used across all provider implementations
• Consistent Pattern: Speech and transcription providers now follow the exact same pattern as chat providers, enabling consistent architecture across all provider types
• Type Fixes: Resolved TypeScript errors related to ComposerTranslation types, validator signatures, and provider instance type casting
• Validator Standardization: All validators now use consistent error format with reasonKey support and proper contextOptions parameter handling

Settings UI & Store Improvements

• Empty Menu Items: Fixed settings index page to filter out routes with empty titles, preventing empty menu items from rendering
• Model Compatibility: Added watch handlers in speech and hearing stores to ensure model selections remain valid when switching providers
• Provider-Specific Defaults: Improved default model selection logic to be provider-aware and prevent incompatible model selections

Benefits

• Complete Migration: All speech and transcription providers now use the unified defineProvider() pattern
• Unified Architecture: All provider types (chat, speech, transcription, embed) now use the same defineProvider() pattern
• Consistency: Speech and transcription providers follow the exact same interface contract and registration pattern as chat providers
• Discoverability: Providers can be programmatically discovered and listed via the unified listProviders() and getDefinedProvider() functions
• Reduced Duplication: Validation, configuration logic, and utility functions are centralized
• Easier Extension: Adding new providers is simplified with clear interface requirements and automatic registration
• Type Safety: Improved TypeScript type safety with explicit provider contracts, Zod schemas, and proper type casting
• Future-Ready: Architecture is now consistent across all provider types, making future additions and maintenance easier

Technical Details

Provider Definition Pattern

export const providerOpenAISpeech = defineProvider<Config>({
  id: 'openai-audio-speech',
  tasks: ['text-to-speech', 'speech'],
  createProvider: (config) => { /* ... */ },
  extraMethods: {
    listModels: (config, provider) => { /* ... */ },
    listVoices: (config, provider) => { /* ... */ },
  },
  // ... other fields
})

Store Integration

The convertProviderDefinitionToMetadata() function converts unified provider definitions to the store's ProviderMetadata format, enabling seamless integration with existing provider store logic.

Validator Pattern

All validators follow a consistent pattern with proper error handling:

validators: {
  validateConfig: [
    ({ t }: { t: ComposerTranslation }) => ({
      id: 'provider-id:check-config',
      name: t('validator.name.key'),
      validator: async (config: Config, _contextOptions: { t: ComposerTranslation }): Promise<ProviderValidationResult> => {
        const errors: Array<{ error: unknown, errorKey?: string }> = []
        // ... validation logic
        return {
          errors,
          reason: errors.length > 0 ? errorMessages.join(', ') : '',
          reasonKey: errors.length > 0 ? 'provider-id:check-config:invalid' : '',
          valid: errors.length === 0,
        }
      },
    }),
  ],
}

Testing

• ✅ Type checks pass: pnpm run typecheck
• ✅ Linter checks pass: pnpm lint
• ✅ Build passes: pnpm -F @proj-airi/stage-tamagotchi build
• ✅ Existing functionality preserved: All providers maintain backward compatibility
• ✅ Registry functions work correctly: Providers are automatically registered and can be discovered via unified registry functions
• ✅ Model compatibility: Provider switching correctly handles model selection

Migration Notes

• Old defineSpeechProvider() and defineTranscriptionProvider() functions are deprecated but still exported for backward compatibility
• Old BaseSpeechProviderDefinition and BaseTranscriptionProviderDefinition interfaces are deprecated but still available
• New providers should use the unified defineProvider() pattern
• Existing code using deprecated functions will continue to work but should be migrated

Related

• Addresses nekomeowww's request from PR feat(stage-ui): add n1n provider #968 review to extend the unified defineProvider() pattern to all speech and transcription providers
• Follows the pattern established in PR feat(stage-ui): add n1n provider #968 for the n1n provider
• Closes feat(stage-ui): add abstract base interfaces for transcription and sp… #961

[gemini-code-assist]

Summary of Changes

Hello @lockrush-dev, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the provider architecture within the stage-ui package by introducing abstract base interfaces for transcription and speech services. The primary goal is to standardize how different providers are defined and integrated, leading to a more maintainable, extensible, and type-safe system. This change streamlines the process of adding new providers and ensures a uniform approach to configuration and validation across all speech and transcription functionalities.

Highlights

• New Abstract Base Interfaces: Introduced BaseTranscriptionProviderDefinition and BaseSpeechProviderDefinition to establish a consistent contract for all transcription and speech providers, enhancing architectural consistency.
• Provider Adapters and Converters: Added createTranscriptionProviderAdapter and createSpeechProviderAdapter functions to seamlessly convert existing ProviderMetadata into the new base interface definitions. New converter functions (convertSpeechProviderToMetadata, convertTranscriptionProviderToMetadata) integrate base provider implementations with the existing provider store.
• Refactored Provider Implementations: OpenAI Speech, OpenAI Transcription, OpenAI Compatible Speech, and OpenAI Compatible Transcription providers have been refactored to utilize the new base interfaces, centralizing validation, model/voice listing, and configuration management.
• Architectural Benefits: The changes lead to improved consistency across providers, reduced code duplication by centralizing common logic, simplified extension for adding new providers, and enhanced TypeScript type safety with explicit contracts.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a solid architectural improvement by creating base interfaces for transcription and speech providers. The refactoring of OpenAI and OpenAI-compatible providers to use these new interfaces significantly reduces code duplication in the main providers.ts store and improves consistency. The use of converter functions to bridge the new provider definitions with the existing metadata-based system is a good integration strategy.

My review includes a few suggestions to further enhance maintainability and type safety:

• Removing newly added but unused adapter files.
• Replacing as any type assertions with more specific types in the converter functions to improve type safety.
• Consolidating duplicated URL normalization logic into a shared utility.

[github-actions]

⏳ Approval required for deploying to Cloudflare Workers (Preview) for stage-web.

Name	Link
🔭 Waiting for approval	For maintainers, approve here

Hey, @nekomeowww, @sumimakito, @luoling8192, @LemonNekoGH, kindly take some time to review and approve this deployment when you are available. Thank you! 🙏

[nekomeowww]

Since you've completed so many tasks about speech & transcription API, would you love to try extending and try using this https://github.com/n1n-api/airi/tree/feat/n1n-provider/packages/stage-ui/src/libs/providers/providers pattern to defineProvider(s) for transcription services & speech services?

[lockrush-dev]

Since you've completed so many tasks about speech & transcription API, would you love to try extending and try using this https://github.com/n1n-api/airi/tree/feat/n1n-provider/packages/stage-ui/src/libs/providers/providers pattern to defineProvider(s) for transcription services & speech services?

I can certainly try! I'll try to take care of that as a part of this pull request.

[lockrush-dev]

@gemini-code-assist review

[gemini-code-assist]

Code Review

This pull request is an excellent and significant refactoring that unifies speech and transcription providers under the defineProvider() pattern. This greatly improves architectural consistency, reduces code duplication, and enhances maintainability. The changes are well-structured, and the use of a converter function to bridge the new provider definitions with the existing store is a smart approach for gradual migration.

My review includes a few suggestions for improvement: one for code simplification in a Vue component, and a high-severity comment on a potential fragility in the new provider converter that could affect future development.

[lockrush-dev]

@gemini-code-assist review

[gemini-code-assist]

Code Review

This pull request significantly refactors the speech and transcription providers to align with the unified defineProvider() pattern, enhancing architectural consistency and reducing code duplication. The introduction of convertProviderDefinitionToMetadata() effectively bridges the new pattern with the existing store's ProviderMetadata format. Additionally, the changes correctly address the issue of empty menu items in the settings UI and improve model/voice selection consistency when switching providers. The overall direction of these changes is positive, leading to a more maintainable and extensible provider system.