# Fluid Intelligence: How the Local On-Device AI Runtime Works in FluidVoice

> Discover Fluid Intelligence locally on macOS. This 3.5GB AI runtime provides smart formatting and context-aware capitalization for FluidVoice dictation without external servers.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: internals
- Published: 2026-07-03

---

**Fluid Intelligence is a self-contained, approximately 3.5GB AI runtime that runs entirely on macOS to provide smart formatting and context-aware capitalization for dictation without sending audio or text to external servers.**

Fluid Intelligence powers the optional, privacy-first AI enhancement layer in the FluidVoice dictation app. According to the altic-dev/FluidVoice source code, this local runtime enables on-device post-processing of transcripts, ensuring that sensitive voice data never leaves the user's machine while delivering intelligent text refinement comparable to cloud-based alternatives.

## What Is Fluid Intelligence?

Fluid Intelligence is an **optional, privately-maintained AI runtime** that provides on-device dictation enhancement. Unlike cloud-based transcription services, this runtime operates as a separate binary that runs entirely within the FluidVoice process on the user's Mac.

The runtime ships as a **~3.5GB model** that the app downloads during onboarding via `PrivateAIProvider`. Once activated, it performs "smart formatting, context-aware capitalization, and post-processing" locally, satisfying a strict zero-data-leaving-device guarantee. No API keys are required, and no network calls occur during inference.

## How the Local AI Runtime Works

The Fluid Intelligence architecture consists of four distinct phases: model acquisition, verification, state management, and inference integration.

### Downloading and Verifying the Model

When a user opts in during onboarding, the app triggers a download workflow managed by `PrivateAIProvider` (see [`Sources/Fluid/Services/PrivateAIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Services/PrivateAIProvider.swift)). The download progress is tracked in real-time by `PrivateAIModelDownloadProgress`, which provides UI updates through `PrivateAIModelDownloadProgressText`.

After the download completes, the provider validates the model's integrity using **SHA-256 hash verification** before moving the artifact into the app's dedicated model directory. This ensures the binary hasn't been corrupted or tampered with during transit.

### The Runtime State Machine

The model's lifecycle is governed by `PrivateAIRuntimeState`, an enum that tracks six distinct states:

- `unavailable` – The runtime cannot be initialized
- `missingModel` – The model file is not present on disk
- `configured` – The model path is set but not loaded
- `loading` – The model is being loaded into memory
- `ready` – The model is active and ready for inference
- `failed` – An error occurred during initialization

These states drive the UI components in [`AISettingsView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/AISettingsView.swift) and [`OnboardingAIEnhancementStepView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/OnboardingAIEnhancementStepView.swift), updating download buttons and status messages automatically as the runtime transitions between phases.

### Integration with the Dictation Pipeline

When transcription completes, `DictationPostProcessingService` checks the active provider configuration stored in `SettingsStore`. If Fluid Intelligence is enabled, the service verifies the runtime state through `PrivateAIIntegrationService` before routing the raw transcript locally.

The integration service loads the verified model into memory and exposes an inference API to the rest of the app. The refined transcript is then displayed in the overlay or written to the target application, all without network latency or external dependencies.

## Code Implementation Examples

### Enabling Fluid Intelligence During Onboarding

The opt-in flow triggers the download and verification sequence through `SettingsStore`:

```swift
// In OnboardingAIEnhancementStepView.swift
Button(action: {
    // Starts the download+verification flow
    SettingsStore.shared.enableFluidIntelligence()
}) {
    Text("Enable Fluid Intelligence")
}

```

### Checking Runtime State Before Inference

The post-processing pipeline validates the local runtime availability before attempting inference:

```swift
// In DictationPostProcessingService.swift
guard SettingsStore.shared.isFluidIntelligenceEnabled,
      let integration = PrivateAIIntegrationService.shared,
      integration.state == .ready else {
    // Fall back to cloud provider or raw transcription
    return rawTranscript
}
let refined = await integration.process(transcript: rawTranscript)

```

### Tracking Download Progress

The UI reflects download status using helper methods that convert progress values into localized strings:

```swift
// PrivateAIProvider.swift – progress UI helper
let title = PrivateAIModelDownloadProgressText.buttonTitle(for: progress)
let status = PrivateAIModelDownloadProgressText.statusText(for: progress)

```

## Summary

- **Fluid Intelligence** is a ~3.5GB local AI runtime that provides private dictation enhancement without cloud dependencies.
- **Model lifecycle** is managed through `PrivateAIProvider` (download/verification) and `PrivateAIIntegrationService` (runtime state).
- **State machine** tracks six states from `missingModel` to `ready`, ensuring the UI accurately reflects availability.
- **Zero-data-leaving-device** architecture ensures all processing occurs locally in `DictationPostProcessingService` with no external API calls.
- **Key files** include [`PrivateAIProvider.swift`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIProvider.swift), [`PrivateAIIntegrationService.swift`](https://github.com/altic-dev/FluidVoice/blob/main/PrivateAIIntegrationService.swift), and [`SettingsStore.swift`](https://github.com/altic-dev/FluidVoice/blob/main/SettingsStore.swift) in the altic-dev/FluidVoice repository.

## Frequently Asked Questions

### What is Fluid Intelligence and how does it work as a local on-device AI runtime?

Fluid Intelligence is a self-contained AI model that runs locally on macOS to enhance dictation transcripts with smart formatting and capitalization. It works by downloading a ~3.5GB binary via `PrivateAIProvider`, verifying its SHA-256 hash, and loading it into memory through `PrivateAIIntegrationService`. Once in the `ready` state, `DictationPostProcessingService` routes transcripts to this local runtime instead of cloud APIs, processing everything within the FluidVoice process.

### How large is the Fluid Intelligence model and where is it stored?

The Fluid Intelligence model requires approximately **3.5GB** of disk space. After download and hash verification via `PrivateAIProvider`, the model is moved to the app's dedicated model directory, with the path persisted in `SettingsStore`. The runtime remains on the user's device indefinitely after initial download, requiring no further network access to function.

### Does Fluid Intelligence require an internet connection to work?

No. After the initial download and verification phase, Fluid Intelligence operates entirely offline. The `PrivateAIIntegrationService` loads the model into local memory and runs inference without network calls, making it suitable for air-gapped environments or users with strict privacy requirements. Internet connectivity is only required for the initial model acquisition via `PrivateAIProvider`.

### How does FluidVoice ensure the model hasn't been tampered with?

The runtime implements cryptographic verification through SHA-256 hash checking. After `PrivateAIProvider` downloads the model, it validates the artifact against a known hash before moving it to the active model directory. This verification step prevents execution of corrupted or malicious binaries, ensuring the integrity of the local AI runtime before `PrivateAIIntegrationService` attempts to load it into memory.