# FluidVoice AI Enhancement Features: Multi-Provider Speech-to-Text Customization

> Explore FluidVoice AI enhancement features. Customize multi-provider speech-to-text with local models and granular controls for advanced audio processing.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: deep-dive
- Published: 2026-06-30

---

**FluidVoice provides a pluggable AI enhancement architecture that supports multiple cloud providers, custom local models, and granular reasoning controls through a centralized settings management system.**

FluidVoice is an open-source dictation application developed by **altic-dev** that embeds advanced AI capabilities directly into the speech-to-text workflow. The app's AI enhancement features deliver granular control over transcription providers, model selection, and privacy settings, enabling users to balance cloud-based performance with local processing security.

## Multi-Provider AI Architecture

FluidVoice normalizes access to diverse AI providers through a unified abstraction layer implemented in [`AIEnhancementSettingsViewModel.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AIEnhancementSettingsViewModel.swift). The system supports both built-in services and user-defined custom providers, with selection logic handled by `providerKey(for:)` to ensure consistent identifier mapping across the UI and persistence layers.

### Built-in Provider Support

The application ships with native integrations for major AI providers including **OpenAI**, **Groq**, **Apple Intelligence**, **NVIDIA**, and **Cohere**. Provider metadata and default endpoint URLs are centralized in [`ModelRepository.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ModelRepository.swift), which maintains the registry of available services and their configuration defaults.

### Secure API Key Management

Each provider stores credentials securely in the system keychain. The view model exposes `updateProviderAPIKey(_:for:persistEmptyValue:)` to handle key updates, which delegates persistence to `SettingsStore.saveProviderAPIKeys`. This architecture ensures that sensitive tokens never reside in plain-text configuration files.

## Dynamic Model Management

Users can extend provider capabilities beyond default offerings through custom model lists. The `AIEnhancementSettingsViewModel` maintains `availableModelsByProvider` and `selectedModelByProvider` dictionaries that track per-provider model availability.

To add custom models, the view model provides `addNewModel()`, which appends user-specified identifiers to the provider's model list. The UI reflects these changes immediately in the Models picker within [`AIEnhancementSettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AIEnhancementSettingsView.swift), allowing real-time switching between models like `gpt-4o-mini` and organization-specific deployments.

## Advanced Reasoning Configuration

For providers supporting extended reasoning (such as OpenAI's o1 series), FluidVoice exposes granular control over reasoning effort levels. The `AIEnhancementSettingsViewModel` tracks reasoning state through:

- `editingReasoningEnabled`: Toggles reasoning mode activation
- `editingReasoningParamName`: Specifies the API parameter name (e.g., `reasoning_effort`)
- `editingReasoningParamValue`: Sets the effort level (e.g., `high`, `medium`, `low`)
- `reasoningConfigVersion`: Monitors configuration changes for UI synchronization

These parameters are transmitted with transcription requests when the selected model supports chain-of-thought capabilities.

## Private AI and Local Model Integration

When the **Private AI Provider** feature flag is enabled (`PrivateFeatures.privateAIProvider`), FluidVoice can load locally-installed large language models through the [`PrivateAIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIProvider.swift) abstraction. The integration relies on `PrivateAIModelRegistry` to supply valid model identifiers, while `verifyPrivateAIProvider(model:)` performs asynchronous verification of local model availability.

The system represents load states through `PrivateAIModelLoadState`, enabling the UI to display loading indicators or error states when initializing local inference engines. This architecture supports air-gapped deployments and privacy-sensitive workflows that prohibit cloud transmission.

## Connection Testing and Status Monitoring

FluidVoice implements comprehensive connectivity validation through provider-specific verification methods. `verifyAppleIntelligence()` and `verifyPrivateAIProvider(model:)` execute test requests to confirm endpoint availability and authentication validity.

Connection states are cached using `AIConnectionStatus` enums and stored in `cachedVerifiedProviderItems` and `cachedUnverifiedProviderItems`. This caching strategy drives UI filtering in [`AISettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AISettingsView.swift), ensuring users only see functional providers in the selection interface while maintaining `isTestingConnection` flags to prevent duplicate verification attempts.

## Prompt Profiles and Shortcut Integration

Beyond provider configuration, the AI enhancement layer supports workflow customization through `DictationPromptTestCoordinator`. Users can create, edit, and delete **dictation prompt profiles** that bind specific AI instructions to particular applications.

The system listens for shortcut recordings via `newPromptShortcutCancellable`, which observes `.newPromptShortcutRecorded` notifications to attach keyboard triggers to specific prompt configurations. When providers change, `updateCurrentProvider()` automatically synchronizes `selectedModel`, `openAIBaseURL`, and current provider state to maintain consistency across the dictation pipeline.

## Implementation Examples

The following Swift patterns demonstrate common AI enhancement configurations using the `AIEnhancementSettingsViewModel` API:

```swift
// 1️⃣ Select a provider (e.g. OpenAI) and set its API key
viewModel.selectedProviderID = "openai"
viewModel.updateProviderAPIKey("sk‑YOUR‑KEY", for: "openai", persistEmptyValue: true)

// 2️⃣ Add a custom model to the selected provider
viewModel.newModelName = "gpt‑4o-mini"
viewModel.addNewModel()

// 3️⃣ Enable reasoning for the selected model
viewModel.editingReasoningEnabled = true
viewModel.editingReasoningParamName = "reasoning_effort"
viewModel.editingReasoningParamValue = "high"

// 4️⃣ Load a private‑AI model (requires the Private AI feature flag)
if PrivateFeatures.privateAIProvider {
    let model = PrivateAIModelRegistry.model(id: "llama‑2‑7b")
    Task {
        let success = await viewModel.verifyPrivateAIProvider(model: model)
        print("Private AI model loaded:", success)
    }
}

// 5️⃣ Test the connection of the current provider
viewModel.isTestingConnection = true
viewModel.updateConnectionStatus(.testing, for: viewModel.selectedProviderID)
// …perform network call…
viewModel.updateConnectionStatus(.success, for: viewModel.selectedProviderID)

```

## Summary

- **Multi-provider support** includes OpenAI, Groq, Apple Intelligence, NVIDIA, and Cohere, with extensible custom provider definitions managed via `AIEnhancementSettingsViewModel`.
- **Secure credential handling** stores API keys in the system keychain through `SettingsStore.saveProviderAPIKeys` and `updateProviderAPIKey`.
- **Custom model management** allows per-provider model lists using `addNewModel()` and `availableModelsByProvider`.
- **Reasoning controls** enable parameter tuning for supported models through `editingReasoningParamName` and `editingReasoningParamValue`.
- **Private AI integration** supports local LLM loading via `PrivateAIModelRegistry` and `verifyPrivateAIProvider()` when the feature flag is enabled.
- **Connection validation** caches provider status in `cachedVerifiedProviderItems` to optimize UI state and prevent invalid configurations.

## Frequently Asked Questions

### Which AI providers does FluidVoice support by default?

FluidVoice ships with built-in integrations for OpenAI, Groq, Apple Intelligence, NVIDIA, and Cohere. Provider definitions and default endpoints are centralized in [`ModelRepository.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ModelRepository.swift), while the selection logic in `AIEnhancementSettingsViewModel.providerKey(for:)` normalizes provider identifiers across the application.

### How does FluidVoice handle API key security?

API keys are stored in the macOS/iOS system keychain rather than user defaults or configuration files. The `updateProviderAPIKey(_:for:persistEmptyValue:)` method in `AIEnhancementSettingsViewModel` handles all key updates, delegating persistence to `SettingsStore.saveProviderAPIKeys` to ensure credentials remain encrypted and sandbox-compliant.

### Can I use local AI models with FluidVoice?

Yes, when the **Private AI Provider** feature flag is enabled, FluidVoice can load locally-installed models through the [`PrivateAIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIProvider.swift) abstraction. The `PrivateAIModelRegistry` supplies model identifiers, and `verifyPrivateAIProvider(model:)` validates local model availability, enabling completely offline dictation workflows.

### What is the reasoning configuration feature?

Reasoning configuration allows users to enable chain-of-thought processing for supported models (such as OpenAI's reasoning models). The system tracks configuration through `editingReasoningEnabled`, `editingReasoningParamName`, and `editingReasoningParamValue`, with `reasoningConfigVersion` ensuring UI consistency when toggling these advanced parameters.