# Providers

Rocky uses a three-layer provider abstraction to support multiple AI backends for both chat and realtime voice interactions.

## Architecture

```
Provider Kind → Provider Instance (Account + Credential) → Model
```

- **Provider Kind** — the backend type (e.g., OpenAI, Anthropic)
- **Provider Instance** — a configured account with API credentials
- **Model** — the specific model to use (e.g., gpt-4o, claude-sonnet-4-20250514)

## Chat Providers

Ten chat provider backends are supported:

| Provider | Key Features |
|----------|-------------|
| **OpenAI** | GPT-4o, GPT-4o-mini, o1, o3 series |
| **Azure OpenAI** | OpenAI models via Azure endpoints |
| **Anthropic** | Claude model family |
| **Gemini** | Google Gemini models |
| **Groq** | Fast inference for open models |
| **xAI** | Grok models |
| **OpenRouter** | Multi-provider routing |
| **DeepSeek** | DeepSeek models |
| **Volcengine (Doubao)** | ByteDance models, Chinese-optimized |
| **AIProxy** | Proxy service for iOS apps |

### Configuration

Each provider instance is stored as JSON in `Application Support/OpenRockyProviders/{id}.json`. The configuration includes:

- Provider kind
- Model ID
- API credential (stored in OS Keychain, not in the JSON file)
- Azure-specific parameters (endpoint, deployment name, API version)
- Proxy settings (if applicable)

### Credential Security

All API keys and secrets are stored in the iOS Keychain via `OpenRockyKeychain`. They are never written to disk files or included in backups.

## Realtime Voice (single-track)

Voice is single-track in current Rocky: there is exactly one realtime backend, and the configuration is a single instance — no list, no "Add provider" flow.

### OpenAI Realtime

- **Models:** `gpt-realtime-mini`, `gpt-realtime`
- **Protocol:** WebSocket realtime API
- **Tool surface:** restricted on the realtime side. Heavier work is delegated to the back-end Chat agent via `delegate-task`.
- **Mic handling:** the bridge suspends the mic during TTS playback to avoid feedback loops.

Earlier builds shipped a second realtime backend (GLM) and a Classic STT + Chat + TTS path. Both have been removed; the realtime client protocol (`OpenRockyRealtimeVoiceClient`) remains so an additional backend can be slotted in without touching the home view or session runtime.

## Provider Stores

- `OpenRockyProviderStore` — manages **Chat** provider instances (multi-instance, with active selection).
- `OpenRockyRealtimeProviderStore` — manages the **Realtime Voice** configuration (single instance).

Both stores handle credential storage in Keychain and backward-compatible migration from older data formats.

## Setting Up Providers

The settings UX consolidates both tiers under a single **Model** group:

1. Open **Settings → Model**
2. Tap **Realtime Voice** to set up your OpenAI Realtime API key and pick a model
3. Tap **Chat** to add one or more Chat provider instances; activate the one you want to drive text chat and the back-end agent
4. Both halves are required for a full experience — Realtime drives the live voice loop; Chat drives `delegate-task` work and the chat detail screen
