# How to Configure AI Enhancement Settings in FluidVoice: A Complete Guide

> Configure FluidVoice AI enhancement settings easily. Learn to select providers, secure API keys, and customize models for optimal audio performance. Master your sound today.

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

---

**Configure FluidVoice's AI enhancement by selecting a provider in `AISettingsView`, securing your API key in the macOS Keychain via `AIEnhancementSettingsViewModel`, and customizing models and reasoning parameters—all persisted automatically through `SettingsStore`.**

FluidVoice is an open-source macOS dictation application that leverages large language models to enhance transcription quality. To customize this behavior, you configure AI enhancement settings through a SwiftUI interface backed by secure storage and modular view models. This guide walks through the exact implementation found in the altic-dev/FluidVoice repository, covering provider selection, credential management, and advanced reasoning configuration.

## Core Components of the AI Enhancement System

### AISettingsView (The UI Layer)

Located in [`Sources/Fluid/UI/AISettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/AISettingsView.swift), this SwiftUI view hosts the configuration interface. It initializes two critical view models that drive the entire configuration flow:

```swift
@StateObject private var voiceViewModel = VoiceEngineSettingsViewModel(...)
@StateObject private var enhancementViewModel = AIEnhancementSettingsViewModel(...)

```

### AIEnhancementSettingsViewModel (State Management)

Defined in [`Sources/Fluid/UI/AISettings/AIEnhancementSettingsViewModel.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/AISettings/AIEnhancementSettingsViewModel.swift), this `ObservableObject` manages all runtime state. It handles provider selection, API key references, model availability, reasoning configurations, and connection testing through published properties that automatically update the UI.

### SettingsStore (Persistence Layer)

Found in [`Sources/Fluid/Persistence/SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Persistence/SettingsStore.swift), this class handles UserDefaults for general settings and the macOS Keychain for secure API key storage. All mutations in the view model ultimately propagate here, ensuring configurations survive app restarts.

## Configuring AI Enhancement Settings Step by Step

### 1. Select or Create an AI Provider

The `selectedProviderID` property binds directly to the provider picker. Built-in providers (OpenAI, Groq, Apple Intelligence) automatically populate their base URLs via `ModelRepository.defaultBaseURL(for:)`, while custom providers use a `custom:` prefix.

To create a custom provider programmatically:

```swift
if let newID = enhancementViewModel.createDraftProvider(named: "MyAI") {
    enhancementViewModel.selectProvider(newID)
}

```

Changing the provider triggers `updateCurrentProvider()`, which refreshes `openAIBaseURL` and `availableModels` for the new selection.

### 2. Secure API Key Configuration

API keys are never stored in plain text. Instead, `AIEnhancementSettingsViewModel` uses `providerAPIKeys` to interface with the macOS Keychain. Before displaying the key editor, the system verifies Keychain permissions through `ensureKeychainAccessForAPIKeyEdit()`.

Update or add keys using:

```swift
enhancementViewModel.handleAPIKeyButtonTapped()
enhancementViewModel.updateProviderAPIKey("sk-mykey123", 
                                           for: enhancementViewModel.selectedProviderID)

```

### 3. Manage Available Models

The `availableModelsByProvider` dictionary maintains provider-specific model lists. Users can extend beyond default offerings using `addNewModel()` or remove entries via `deleteSelectedModel()`. The UI reflects current options through the `availableModels` computed property, which updates dynamically when switching providers.

### 4. Configure Reasoning Parameters

For models supporting chain-of-thought reasoning, enable the feature by toggling `editingReasoningEnabled` and configuring `ModelReasoningConfig`:

```swift
enhancementViewModel.editingReasoningEnabled = true
enhancementViewModel.editingReasoningParamName = "reasoning_effort"
enhancementViewModel.editingReasoningParamValue = "high"

```

When `testAPIConnection()` executes with `usesResponsesAPI` enabled, these values inject into the request payload to control reasoning depth.

### 5. Test the Connection

Before saving, validate the configuration by calling `testAPIConnection()`. This method constructs a POST request using the current provider's base URL, validates the API key from Keychain, and checks model availability. It updates `connectionStatus` and `connectionErrorMessage` to provide immediate visual feedback in the UI.

## Prompt Profile Customization

Dictation enhancement prompts are stored in `SettingsStore.dictationPromptProfiles`. The system combines user-editable prompt bodies with hidden base prompts using `SettingsStore.combineBasePrompt(for:with:)`. This architecture allows customization of transcription behavior without exposing or modifying system-level instructions.

## Summary

- **[`AISettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AISettingsView.swift)** renders the configuration interface and injects the view models that drive the UI.
- **[`AIEnhancementSettingsViewModel.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AIEnhancementSettingsViewModel.swift)** manages provider selection through `selectedProviderID`, handles secure API keys via `providerAPIKeys`, and controls model lists with `availableModelsByProvider`.
- **[`SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/SettingsStore.swift)** persists settings to UserDefaults and stores API keys securely in the macOS Keychain.
- Create custom providers beyond built-in options using `createDraftProvider(named:)` when you need to connect to private endpoints.
- Enable advanced reasoning through `ModelReasoningConfig` properties (`editingReasoningParamName`, `editingReasoningParamValue`) for supported models.
- Always validate setups using `testAPIConnection()` before beginning dictation sessions.

## Frequently Asked Questions

### Where are my API keys stored in FluidVoice?

API keys are stored in the macOS Keychain, accessed through the `providerAPIKeys` property in `AIEnhancementSettingsViewModel`. The app requests Keychain access permissions via `ensureKeychainAccessForAPIKeyEdit()` before allowing any key editing operations, ensuring credentials remain encrypted and sandbox-compliant.

### Can I use custom AI providers not listed by default?

Yes. Call `createDraftProvider(named:)` on the view model to generate a custom provider with a `custom:` prefix identifier. You must manually specify the base URL, and the provider will immediately appear in the `selectedProviderID` picker alongside built-in options like OpenAI and Groq.

### How do I add a model that isn't in the default list?

Use the `addNewModel()` method in `AIEnhancementSettingsViewModel` to append models to `availableModelsByProvider`. Conversely, use `deleteSelectedModel()` to remove unused entries. These modifications persist automatically through `SettingsStore` and reflect immediately in the model selection picker.

### What does the reasoning configuration do?

When `editingReasoningEnabled` is true, FluidVoice injects reasoning parameters into API requests to enable chain-of-thought processing. Configure the exact parameter name via `editingReasoningParamName` (e.g., `reasoning_effort`) and the intensity via `editingReasoningParamValue` (e.g., `low`, `medium`, `high`) to control the model's analytical depth during transcription enhancement.