# AionUi Multi-Model Architecture: How It Switches Between Gemini, Claude, and Ollama

> Explore AionUi's innovative multi-model architecture. Seamlessly switch between Gemini, Claude, and Ollama with a unified interface abstracting LLM provider differences.

- Repository: [OfficeAI/AionUi](https://github.com/iofficeai/aionui)
- Tags: architecture
- Published: 2026-02-16

---

**AionUi abstracts every LLM provider behind a unified three-layer architecture that normalizes protocol differences between Gemini, Claude, and Ollama into a single consistent interface.**

AionUi, developed by iOfficeAI, implements a sophisticated multi-model architecture that enables seamless switching between cloud providers like Google Gemini and Anthropic Claude, alongside local inference engines such as Ollama. This architecture eliminates the friction of managing different API formats by unifying them under a single provider configuration system.

## The Three-Layer Architecture of AionUi Multi-Model Support

The AionUi multi-model architecture consists of three tightly-coupled layers that handle provider declaration, protocol normalization, and UI integration.

### Configuration Layer: Defining Providers in [`modelPlatforms.ts`](https://github.com/iOfficeAI/AionUi/blob/main/modelPlatforms.ts)

All LLM providers are declared in [`src/renderer/config/modelPlatforms.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/config/modelPlatforms.ts) using the **`PlatformConfig`** interface. This central registry supports official cloud providers, local models, and custom endpoints through a unified schema.

```typescript
export interface PlatformConfig {
  name: string;            // UI label (e.g., "Gemini", "Ollama")
  value: string;           // Identifier used in settings
  logo: string | null;     // Optional SVG/PNG asset
  platform: PlatformType;  // 'gemini', 'anthropic', 'custom', etc.
  baseUrl?: string;        // Fixed endpoint for cloud; empty for local
}

```

The **`MODEL_PLATFORMS`** array instantiates this interface for each supported provider. Local inference engines like **Ollama** or **LM Studio** register with `platform: 'custom'`, allowing users to supply a local `baseUrl` such as `http://127.0.0.1:11434`. The UI treats these custom providers identically to cloud services.

### Bridge Layer: Protocol Detection in [`modelBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/modelBridge.ts)

The bridge layer in [`src/process/bridge/modelBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/bridge/modelBridge.ts) handles the complexity of communicating with disparate APIs. When the UI requests available models via `ipcBridge.mode.fetchModelList`, the bridge executes a protocol detection and normalization sequence.

The bridge first guesses the protocol using **`guessProtocolFromUrl`** and **`guessProtocolFromKey`**, then routes to the appropriate test routine:

- **`testGeminiProtocol`** for Google Gemini endpoints
- **`testOpenAIProtocol`** for OpenAI-compatible APIs (including Ollama)
- **`testAnthropicProtocol`** for Claude/Anthropic endpoints

Each routine returns a normalized payload that the bridge transforms into a unified structure:

```typescript
{
  success: true,
  data: { mode: string[] }   // Array of model IDs for UI display
}

```

This normalization ensures that the renderer receives identical data structures regardless of whether the source is Gemini's native API, Anthropic's Claude API, or a local Ollama instance.

### Renderer Layer: UI Integration with [`useModelProviderList.ts`](https://github.com/iOfficeAI/AionUi/blob/main/useModelProviderList.ts)

The renderer consumes normalized provider data through the **`useModelProviderList`** hook in [`src/renderer/hooks/useModelProviderList.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/hooks/useModelProviderList.ts). This hook orchestrates the UI-facing logic for provider selection.

The hook performs several key functions:

- Fetches stored configurations via `ipcBridge.mode.getModelConfig`
- Injects the **Gemini Google Auth** virtual provider when users authenticate with Google
- Filters providers using `getAvailableModels` to exclude entries with no usable models
- Builds lookup maps like `geminiModeLookup` for provider-specific UI optimizations

The hook returns a structured object that powers the model selector dropdown:

```typescript
{
  providers: IProvider[];               // All usable providers (Gemini, Claude, Ollama, etc.)
  geminiModeLookup: Map<string, GeminiModeOption>;
  getAvailableModels: (p: IProvider) => string[];
  formatModelLabel: (provider, model) => string;
}

```

Switching the active LLM requires a single IPC call:

```typescript
await ipcBridge.mode.saveModelConfig([selectedProvider]);

```

The bridge persists this selection, and subsequent inference requests automatically route to the new provider.

## How AionUi Normalizes Different LLM Protocols

The multi-model architecture relies on protocol detection utilities located in [`src/common/utils/protocolDetector.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/common/utils/protocolDetector.ts). When a user configures a new endpoint, the system analyzes the URL structure and API key format to determine whether to apply Gemini, Anthropic, or OpenAI-compatible parsing logic.

For local providers like Ollama that expose OpenAI-compatible endpoints at `/v1/models`, the `testOpenAIProtocol` function handles authentication and response parsing without requiring provider-specific modifications to the renderer code.

## Switching Between Providers: Code Examples

### Programmatically Selecting Ollama

You can switch to a local Ollama instance by constructing a provider object and persisting it through the IPC bridge:

```typescript
import { ipcBridge } from '@/common';

async function switchToOllama() {
  const ollamaProvider = {
    id: 'ollama-1',
    name: 'Ollama',
    platform: 'custom',
    baseUrl: 'http://127.0.0.1:11434',
    apiKey: '',                 // No key needed for local Ollama
    model: ['llama3:8b', 'phi3:instruct'],
    capabilities: [{ type: 'text' }],
  };

  await ipcBridge.mode.saveModelConfig([ollamaProvider]);
}

```

### Adding a Custom Provider to `MODEL_PLATFORMS`

To register a new provider in the configuration layer, extend the array in [`src/renderer/config/modelPlatforms.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/config/modelPlatforms.ts):

```typescript
{
  name: 'Ollama',
  value: 'ollama',
  logo: OllamaLogo,
  platform: 'custom',
  // baseUrl is left empty for user configuration in Settings
},

```

## MCP Agents for Cloud Provider Integration

For **Claude** and **Gemini**, AionUi implements dedicated **Model Context Protocol (MCP) agents** that manage the official CLI tools in child processes. These agents reside in [`src/agent/gemini/index.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/agent/gemini/index.ts) and [`src/agent/acp/index.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/agent/acp/index.ts).

When the active provider's `platform` field equals `'gemini'` or `'anthropic'`, the bridge invokes the corresponding MCP agent instead of direct HTTP calls. These agents share the same prefix-based command format used by the generic `agentUtils` module, allowing the UI to issue prompts without distinguishing between local LLMs (Ollama) and remote MCP-based services.

## Summary

- AionUi implements a **three-layer architecture** (Configuration, Bridge, Renderer) to abstract LLM provider differences.
- The **`PlatformConfig`** interface in [`modelPlatforms.ts`](https://github.com/iOfficeAI/AionUi/blob/main/modelPlatforms.ts) unifies cloud and local providers under a single schema.
- **[`modelBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/modelBridge.ts)** handles protocol detection (`guessProtocolFromUrl`, `guessProtocolFromKey`) and normalizes responses into a common format.
- The **`useModelProviderList`** hook consumes normalized data to power the UI model selector.
- **MCP agents** manage Claude and Gemini through their official CLI tools.
- Adding new providers requires only updating `MODEL_PLATFORMS` and ensuring OpenAI-compatible endpoints.

## Frequently Asked Questions

### How does AionUi detect which protocol to use for a custom provider?

AionUi uses the **`guessProtocolFromUrl`** and **`guessProtocolFromKey`** utilities in [`src/process/bridge/modelBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/bridge/modelBridge.ts) to analyze the endpoint URL and API key format. For example, URLs containing `generativelanguage.googleapis.com` trigger Gemini protocol detection, while Anthropic API keys trigger Claude protocol detection. For local providers like Ollama, the system defaults to OpenAI-compatible protocol detection based on the `/v1/models` endpoint structure.

### Can I use AionUi with local LLMs that don't follow the OpenAI API format?

Yes, but you may need to extend the bridge layer. While AionUi natively supports OpenAI-compatible endpoints (covering Ollama, LM Studio, and most local inference servers), bespoke protocols require implementing a new test routine in [`src/process/bridge/modelBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/bridge/modelBridge.ts). Add a `testCustomProtocol` function following the pattern of `testGeminiProtocol` or `testAnthropicProtocol`, then include the corresponding case in the protocol detection switch statement.

### What is the difference between the Bridge layer and the MCP agents in AionUi?

The **Bridge layer** ([`src/process/bridge/modelBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/bridge/modelBridge.ts)) handles HTTP-based API communication and model list fetching for all providers, normalizing REST responses into a common format. **MCP agents** ([`src/agent/gemini/index.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/agent/gemini/index.ts) and [`src/agent/acp/index.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/agent/acp/index.ts)) are specialized child processes that manage the official CLI tools for Gemini and Claude respectively. While the bridge handles direct REST API calls, MCP agents handle streaming context protocol interactions required by Google's and Anthropic's official SDKs when the selected platform is `'gemini'` or `'anthropic'`.

### How do I add a new cloud provider like Groq or Together AI to AionUi?

Add the provider to the **`MODEL_PLATFORMS`** array in [`src/renderer/config/modelPlatforms.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/config/modelPlatforms.ts) using the `PlatformConfig` interface. Set `platform: 'custom'` and provide the appropriate `baseUrl` for the service's OpenAI-compatible endpoint. Since most modern inference providers (including Groq and Together AI) implement the OpenAI `/v1/models` and `/v1/chat/completions` endpoints, the existing `testOpenAIProtocol` function in [`modelBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/modelBridge.ts) will automatically detect and normalize the model list without requiring additional code changes. The new provider will immediately appear in the model selector UI.