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

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

All LLM providers are declared in 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.

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

The bridge layer in 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:

{
  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

The renderer consumes normalized provider data through the useModelProviderList hook in 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:

{
  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:

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. 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:

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:

{
  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 and 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 unifies cloud and local providers under a single schema.
• 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 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. 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) 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 and 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 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 will automatically detect and normalize the model list without requiring additional code changes. The new provider will immediately appear in the model selector UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}