ag-x/docs/AI_PROVIDER_README.md

Antigravity AI Provider GUI Support

This directory contains the implementation of GUI support for multiple AI providers in the Antigravity IDE.

Files Added/Modified

Backend (Electron Main Process)

1. services/aiProviderService.js (NEW)

   • Core service for AI provider management
   • Handles CRUD operations for providers
   • Manages provider configurations and storage
   • Provides connection testing functionality

2. services/settingsService.js (MODIFIED)

   • Added AI-related setting keys
   • Added default values for AI configuration

3. ipcHandlers.js (MODIFIED)

   • Added AI provider IPC handlers
   • Integrated AIProviderService
   • Exposed 10+ new IPC methods for frontend

Frontend (Renderer Process)

4. aiProviderAPI.ts (NEW)

   • TypeScript wrapper for IPC communication
   • Type-safe API for AI provider operations
   • Helper methods for settings management

5. ai-provider-settings.html (NEW)

   • Complete, production-ready GUI implementation
   • Responsive design with modern UI
   • Full CRUD operations
   • Connection testing
   • Settings management

Documentation

6. AI_PROVIDER_SPECIFICATION.md (NEW)
   • Comprehensive implementation guide
   • API documentation
   • Usage examples
   • Testing checklist
   • Future enhancements

Quick Start

Viewing the GUI

The GUI can be accessed by opening ai-provider-settings.html in a web browser after integrating with the Electron app.

Basic Usage

// Get all providers
const providers = await window.electron.invoke('ai:get-providers');

// Add a new provider
const newProvider = await window.electron.invoke('ai:add-provider', {
  name: 'My Custom Provider',
  type: 'openai',
  endpoint: 'https://api.myprovider.com/v1',
  apiKey: 'my-api-key',
  models: ['model-1', 'model-2'],
  capabilities: ['chat', 'streaming']
});

// Test connection
const result = await window.electron.invoke('ai:test-connection', newProvider.id);
console.log(result.success ? 'Connected!' : 'Failed: ' + result.message);

// Update settings
await window.electron.invoke('storage:update-items', {
  'aiProvider': newProvider.id,
  'aiModel': 'model-1',
  'aiTemperature': '0.7',
  'aiMaxTokens': '4096',
  'aiStreaming': 'true'
});

Architecture

┌─────────────────────────────────────────────────┐
│            Renderer Process (UI)               │
├─────────────────────────────────────────────────┤
│  ai-provider-settings.html                      │
│  ├── Provider Cards (Grid Layout)               │
│  ├── Settings Panel                             │
│  ├── Modals (Add/Edit)                          │
│  └── Toast Notifications                        │
│                                                 │
│  aiProviderAPI.ts                               │
│  └── Type-safe IPC wrapper                     │
└─────────────────────────────────────────────────┘
                    │ IPC
                    ↓
┌─────────────────────────────────────────────────┐
│            Main Process (Backend)               │
├─────────────────────────────────────────────────┤
│  ipcHandlers.js                                 │
│  └── AI Provider IPC handlers (10+ methods)     │
│                                                 │
│  services/                                      │
│  ├── aiProviderService.js                       │
│  │   ├── Provider management (CRUD)             │
│  │   ├── Storage integration                   │
│  │   └── Connection testing                    │
│  └── settingsService.js                         │
│      └── AI setting keys                        │
│                                                 │
│  storage.js                                     │
│  └── Persistent storage                         │
└─────────────────────────────────────────────────┘

Features

Provider Management

• ✅ Add custom providers
• ✅ Edit existing providers
• ✅ Delete providers (except defaults)
• ✅ Set default provider
• ✅ Enable/disable providers
• ✅ View provider capabilities
• ✅ Test provider connections

Model Configuration

• ✅ Select default model per provider
• ✅ View available models
• ✅ Model-specific settings

Global Settings

• ✅ Temperature control (0.0-2.0)
• ✅ Max tokens (100-32000)
• ✅ Streaming toggle
• ✅ Persistent settings

UI/UX

• ✅ Modern, responsive design
• ✅ Real-time feedback
• ✅ Error handling
• ✅ Loading states
• ✅ Toast notifications
• ✅ Modal dialogs
• ✅ Visual status indicators

Integration Guide

Step 1: Extract app.asar

cd Antigravity-x64/resources
npx asar extract app.asar app-extracted

Step 2: Replace/Add Files

Copy the modified files to app-extracted/dist/:

cp aiProviderService.js app-extracted/dist/services/
cp settingsService.js app-extracted/dist/services/
cp ipcHandlers.js app-extracted/dist/
cp aiProviderAPI.ts app-extracted/dist/
cp ai-provider-settings.html app-extracted/dist/
cp AI_PROVIDER_SPECIFICATION.md app-extracted/dist/

Step 3: Repack app.asar

npx asar pack app-extracted app.asar

Step 4: Launch the App

Run the modified Antigravity application.

Step 5: Access the GUI

Open the AI Provider Settings page in the app (typically via Settings menu or by navigating to ai-provider-settings.html).

API Reference

IPC Methods

Method	Parameters	Returns	Description
ai:get-providers	none	AIProvider[]	Get all providers
ai:get-provider	id: string	AIProvider	Get specific provider
ai:get-enabled-providers	none	AIProvider[]	Get enabled providers
ai:get-default-provider	none	AIProvider	Get default provider
ai:add-provider	provider: AIProviderCreate	AIProvider	Add new provider
ai:update-provider	id: string, updates: AIProviderUpdate	AIProvider	Update provider
ai:delete-provider	id: string	void	Delete provider
ai:set-default-provider	id: string	void	Set as default
ai:toggle-provider	id: string, enabled: boolean	void	Enable/disable
ai:test-connection	id: string	AIConnectionTest	Test connection

Storage Keys

Key	Type	Default	Description
aiProvider	string	openai-default	Default provider ID
aiModel	string	gpt-4o	Default model
aiTemperature	string	0.7	Temperature setting
aiMaxTokens	string	4096	Max tokens setting
aiStreaming	string	true	Streaming enabled
aiEmbeddingProvider	string	openai-default	Embedding provider
aiProviders	string	JSON	All provider configs

Supported Providers

Built-in Providers

1. OpenAI (Default)

   • Models: GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-3.5-turbo
   • Capabilities: All features

2. Anthropic

   • Models: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku
   • Capabilities: Chat, Vision, Tool Use, Streaming

3. Ollama (Local)

   • Models: Llama3, CodeLLama, Mistral, Neural Chat
   • Capabilities: Chat, Completion, Streaming

Custom Providers

Add any OpenAI-compatible API endpoint:

await window.electron.invoke('ai:add-provider', {
  name: 'My Local Model',
  type: 'custom',
  endpoint: 'http://localhost:8080/v1',
  apiKey: 'not-required',
  models: ['my-model'],
  capabilities: ['chat', 'streaming']
});

Troubleshooting

Provider not connecting

1. Check API key is correct
2. Verify endpoint URL
3. Test connection with "Test" button
4. Check network/firewall settings
5. For Ollama, ensure service is running

Settings not persisting

1. Check storage permissions
2. Verify storage path exists
3. Check for storage quota issues
4. Review app logs for errors

UI not loading

1. Ensure all files are properly copied
2. Check app.asar is correctly repacked
3. Verify HTML file path
4. Check browser console for errors

Contributing

To extend this implementation:

1. New Provider Types: Add to AIProviderType enum
2. New Capabilities: Add to AIProviderCapability enum
3. New Settings: Add to SettingKey and DEFAULTS
4. New IPC Methods: Add handlers in ipcHandlers.js
5. UI Enhancements: Modify ai-provider-settings.html

License

Same as the Antigravity application.

Support

For issues or questions:

1. Check the specification document (AI_PROVIDER_SPECIFICATION.md)
2. Review the code comments
3. Check browser console for errors
4. Review Electron logs

Changelog

Version 1.0 (Current)

• Initial implementation
• Full CRUD for AI providers
• Connection testing
• Settings management
• Complete GUI implementation
• Documentation