feat(stage-ui): refactor speech/transcription providers to unified defineProvider pattern

Refactor OpenAI and OpenAI-compatible speech/transcription providers to use
the unified `defineProvider()` pattern (matching PR #968 n1n provider pattern)
instead of separate registries. This unifies all providers under a single
consistent API.

Changes:
- Refactor OpenAI speech/transcription providers to use `defineProvider()` with
  `tasks` and `extraMethods` instead of `defineSpeechProvider`/`defineTranscriptionProvider`
- Refactor OpenAI-compatible speech/transcription providers similarly
- Add `convertProviderDefinitionToMetadata()` converter function to bridge unified
  pattern with existing store's `ProviderMetadata` format
- Update store to use new converter function instead of old separate converters
- Mark old base interfaces and registry exports as deprecated for backward compatibility
- Fix settings index page to filter out routes with empty titles (preventing empty
  menu items from rendering)

BREAKING CHANGE: Speech and transcription providers now use the unified
`defineProvider()` pattern. Old `defineSpeechProvider` and `defineTranscriptionProvider`
functions are deprecated but still available for backward compatibility.

Refs: PR #961, PR #968

Author: zsleavitt

packages/stage-pages/src/pages/settings/index.vue

@@ -37,6 +37,7 @@ const settings = computed(() => {
       icon: route.meta?.icon as string | undefined,
       to: route.path,
     }))
+    .filter(setting => setting.title)
 })
 </script>
 

packages/stage-ui/src/libs/providers/base-speech.ts

@@ -23,6 +23,9 @@ export interface BaseSpeechProviderConfig {
 /**
  * Base interface that all speech provider implementations should follow.
  *
+ * @deprecated Use the unified `defineProvider()` pattern instead (see `providers/registry.ts`).
+ * This interface is kept for backward compatibility with existing converters.
+ *
  * This provides a consistent contract for speech/TTS providers beyond
  * what's defined in the external @xsai-ext/providers/utils library.
  *

packages/stage-ui/src/libs/providers/base-transcription.ts

@@ -28,6 +28,9 @@ export interface BaseTranscriptionProviderConfig {
 /**
  * Base interface that all transcription provider implementations should follow.
  *
+ * @deprecated Use the unified `defineProvider()` pattern instead (see `providers/registry.ts`).
+ * This interface is kept for backward compatibility with existing converters.
+ *
  * This provides a consistent contract for transcription providers beyond
  * what's defined in the external @xsai-ext/providers/utils library.
  *

packages/stage-ui/src/libs/providers/providers/index.ts

@@ -30,6 +30,8 @@ export {
   listProviders,
 } from './registry'
 
+// Legacy exports for backward compatibility (deprecated - use unified defineProvider pattern)
+// These will be removed in a future version
 export {
   defineSpeechProvider,
   getDefinedSpeechProvider,

packages/stage-ui/src/libs/providers/providers/openai-compatible/speech.ts

@@ -4,77 +4,82 @@ import type {
 } from '@xsai-ext/providers/utils'
 
 import type { ModelInfo, VoiceInfo } from '../../../../stores/providers'
-import type {
-  BaseSpeechProviderConfig,
-} from '../../base-speech'
-import type { ProviderValidationResult } from '../../base-types'
 
 import { createSpeechProvider } from '@xsai-ext/providers/utils'
+import { z } from 'zod'
 
 import { normalizeBaseUrl } from '../../utils'
-import { defineSpeechProvider } from '../registry-speech'
+import { createOpenAICompatibleValidators } from '../../validators/openai-compatible'
+import { defineProvider } from '../registry'
+
+const openAICompatibleSpeechConfigSchema = z.object({
+  apiKey: z.string('API Key'),
+  baseUrl: z.string('Base URL'),
+})
+
+type OpenAICompatibleSpeechConfig = z.input<typeof openAICompatibleSpeechConfigSchema>
 
 /**
  * OpenAI Compatible Speech/TTS Provider Implementation
  *
- * Implements BaseSpeechProviderDefinition for any API that follows the OpenAI specification.
+ * Uses the unified defineProvider pattern for any API that follows the OpenAI specification.
  * This is a generic implementation that works with OpenAI-compatible endpoints.
  */
-export const openaiCompatibleSpeechProvider = defineSpeechProvider({
+export const providerOpenAICompatibleSpeech = defineProvider<OpenAICompatibleSpeechConfig>({
   id: 'openai-compatible-audio-speech',
-  defaultModel: 'tts-1',
-  defaultVoice: 'alloy',
-
-  async validateConfig(config: BaseSpeechProviderConfig): Promise<ProviderValidationResult> {
-    const errors: Error[] = []
-
-    if (!config.apiKey) {
-      errors.push(new Error('API Key is required'))
-    }
+  order: 3,
+  name: 'OpenAI Compatible',
+  nameLocalize: ({ t }) => t('settings.pages.providers.provider.openai-compatible.title'),
+  description: 'OpenAI-compatible text-to-speech API',
+  descriptionLocalize: ({ t }) => t('settings.pages.providers.provider.openai-compatible.description'),
+  tasks: ['text-to-speech', 'speech'],
+  icon: 'i-lobe-icons:openai',
 
-    if (!config.baseUrl) {
-      errors.push(new Error('Base URL is required'))
-    }
+  createProviderConfig: ({ t }) => openAICompatibleSpeechConfigSchema.extend({
+    apiKey: openAICompatibleSpeechConfigSchema.shape.apiKey.meta({
+      labelLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.api-key.label'),
+      descriptionLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.api-key.description'),
+      placeholderLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.api-key.placeholder'),
+      type: 'password',
+    }),
+    baseUrl: openAICompatibleSpeechConfigSchema.shape.baseUrl.meta({
+      labelLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.base-url.label'),
+      descriptionLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.base-url.description'),
+      placeholderLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.base-url.placeholder'),
+    }),
+  }),
 
-    if (errors.length > 0) {
-      return {
-        errors,
-        reason: errors.map(e => e.message).join(', '),
-        valid: false,
-      }
-    }
-
-    return {
-      errors: [],
-      reason: '',
-      valid: true,
-    }
-  },
-
-  async createProvider(config: BaseSpeechProviderConfig) {
+  createProvider(config) {
     const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : ''
     const baseUrl = normalizeBaseUrl(config.baseUrl)
 
     return createSpeechProvider({ apiKey, baseURL: baseUrl }) as SpeechProvider | SpeechProviderWithExtraOptions<string, any>
   },
 
-  async listModels(_config: BaseSpeechProviderConfig): Promise<ModelInfo[]> {
-    // OpenAI Compatible providers don't have hardcoded models
-    // Models are typically discovered via the API
-    return []
+  validationRequiredWhen(config) {
+    return !!config.apiKey?.trim()
   },
 
-  async listVoices(_config: BaseSpeechProviderConfig): Promise<VoiceInfo[]> {
-    // OpenAI Compatible providers don't have hardcoded voices
-    // Voices are typically discovered via the API or user-configured
-    return []
+  validators: {
+    ...createOpenAICompatibleValidators<OpenAICompatibleSpeechConfig>({
+      checks: ['connectivity'],
+    }),
   },
 
-  getDefaultConfig(): Partial<BaseSpeechProviderConfig> {
-    return {}
-  },
+  extraMethods: {
+    async listModels(_config): Promise<ModelInfo[]> {
+      // OpenAI Compatible providers don't have hardcoded models
+      // Models are typically discovered via the API
+      return []
+    },
 
-  supportsSSML(): boolean {
-    return false
+    async listVoices(_config): Promise<VoiceInfo[]> {
+      // OpenAI Compatible providers don't have hardcoded voices
+      // Voices are typically discovered via the API or user-configured
+      return []
+    },
   },
 })
+
+// Keep export for backward compatibility during migration
+export const openaiCompatibleSpeechProvider = providerOpenAICompatibleSpeech

packages/stage-ui/src/libs/providers/providers/openai-compatible/transcription.ts

@@ -4,71 +4,85 @@ import type {
 } from '@xsai-ext/providers/utils'
 
 import type { ModelInfo } from '../../../../stores/providers'
-import type {
-  BaseTranscriptionProviderConfig,
-} from '../../base-transcription'
-import type { ProviderValidationResult } from '../../base-types'
 
 import { createTranscriptionProvider } from '@xsai-ext/providers/utils'
+import { z } from 'zod'
 
 import { normalizeBaseUrl } from '../../utils'
-import { defineTranscriptionProvider } from '../registry-transcription'
+import { createOpenAICompatibleValidators } from '../../validators/openai-compatible'
+import { defineProvider } from '../registry'
+
+const openAICompatibleTranscriptionConfigSchema = z.object({
+  apiKey: z.string('API Key'),
+  baseUrl: z.string('Base URL'),
+})
+
+type OpenAICompatibleTranscriptionConfig = z.input<typeof openAICompatibleTranscriptionConfigSchema>
 
 /**
  * OpenAI Compatible Transcription/STT Provider Implementation
  *
- * Implements BaseTranscriptionProviderDefinition for any API that follows the OpenAI specification.
+ * Uses the unified defineProvider pattern for any API that follows the OpenAI specification.
  * This is a generic implementation that works with OpenAI-compatible endpoints.
  */
-export const openaiCompatibleTranscriptionProvider = defineTranscriptionProvider({
+export const providerOpenAICompatibleTranscription = defineProvider<OpenAICompatibleTranscriptionConfig>({
   id: 'openai-compatible-audio-transcription',
-  defaultModel: 'whisper-1',
-  transcriptionFeatures: {
-    supportsGenerate: true,
-    supportsStreamOutput: false,
-    supportsStreamInput: false,
-  },
-
-  async validateConfig(config: BaseTranscriptionProviderConfig): Promise<ProviderValidationResult> {
-    const errors: Error[] = []
-
-    if (!config.apiKey) {
-      errors.push(new Error('API Key is required'))
-    }
-
-    if (!config.baseUrl) {
-      errors.push(new Error('Base URL is required'))
-    }
+  order: 3,
+  name: 'OpenAI Compatible',
+  nameLocalize: ({ t }) => t('settings.pages.providers.provider.openai-compatible.title'),
+  description: 'OpenAI-compatible transcription API',
+  descriptionLocalize: ({ t }) => t('settings.pages.providers.provider.openai-compatible.description'),
+  tasks: ['speech-to-text', 'automatic-speech-recognition', 'asr', 'stt'],
+  icon: 'i-lobe-icons:openai',
 
-    if (errors.length > 0) {
-      return {
-        errors,
-        reason: errors.map(e => e.message).join(', '),
-        valid: false,
-      }
-    }
+  createProviderConfig: ({ t }) => openAICompatibleTranscriptionConfigSchema.extend({
+    apiKey: openAICompatibleTranscriptionConfigSchema.shape.apiKey.meta({
+      labelLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.api-key.label'),
+      descriptionLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.api-key.description'),
+      placeholderLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.api-key.placeholder'),
+      type: 'password',
+    }),
+    baseUrl: openAICompatibleTranscriptionConfigSchema.shape.baseUrl.meta({
+      labelLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.base-url.label'),
+      descriptionLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.base-url.description'),
+      placeholderLocalized: t('settings.pages.providers.catalog.edit.config.common.fields.field.base-url.placeholder'),
+    }),
+  }),
 
-    return {
-      errors: [],
-      reason: '',
-      valid: true,
-    }
-  },
-
-  async createProvider(config: BaseTranscriptionProviderConfig) {
+  createProvider(config) {
     const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : ''
     const baseUrl = normalizeBaseUrl(config.baseUrl)
 
     return createTranscriptionProvider({ apiKey, baseURL: baseUrl }) as TranscriptionProvider | TranscriptionProviderWithExtraOptions<string, any>
   },
 
-  async listModels(_config: BaseTranscriptionProviderConfig): Promise<ModelInfo[]> {
-    // OpenAI Compatible providers don't have hardcoded models
-    // Models are typically discovered via the API
-    return []
+  validationRequiredWhen(config) {
+    return !!config.apiKey?.trim()
+  },
+
+  validators: {
+    ...createOpenAICompatibleValidators<OpenAICompatibleTranscriptionConfig>({
+      checks: ['connectivity'],
+    }),
   },
 
-  getDefaultConfig(): Partial<BaseTranscriptionProviderConfig> {
-    return {}
+  capabilities: {
+    transcription: {
+      protocol: 'http',
+      generateOutput: true,
+      streamOutput: false,
+      streamInput: false,
+    },
+  },
+
+  extraMethods: {
+    async listModels(_config): Promise<ModelInfo[]> {
+      // OpenAI Compatible providers don't have hardcoded models
+      // Models are typically discovered via the API
+      return []
+    },
   },
 })
+
+// Keep export for backward compatibility during migration
+export const openaiCompatibleTranscriptionProvider = providerOpenAICompatibleTranscription