ag-x/docs/AI_PROVIDER_SPECIFICATION.md

# AI Provider GUI Support - Implementation Specification

## Overview

This document describes the implementation of GUI support for multiple AI providers in the Antigravity IDE. The implementation adds comprehensive backend infrastructure and a fully functional frontend interface for managing AI provider configurations.

## Architecture

### Backend Components

#### 1. AIProviderService (`services/aiProviderService.js`)

The core service managing AI provider configurations with the following features:

- **Provider Management**: CRUD operations for AI providers
- **Storage Integration**: Persists configurations using the existing StorageManager
- **Event System**: Emits events for provider changes
- **Connection Testing**: Validates provider connectivity

**Supported Provider Types**:
- OpenAI (GPT-4, GPT-3.5)
- Anthropic (Claude)
- Ollama (Local models)
- Groq
- OpenRouter
- Custom providers

**Provider Capabilities**:
- Chat completion
- Text completion
- Embeddings
- Vision (multimodal)
- Tool use
- Streaming

#### 2. Settings Integration

Added new settings to `settingsService.js`:

- `aiProvider`: Default provider ID
- `aiModel`: Default model
- `aiTemperature`: Response creativity (0.0-2.0)
- `aiMaxTokens`: Max response length
- `aiStreaming`: Enable/disable streaming
- `aiEmbeddingProvider`: Embedding provider

#### 3. IPC Handlers

Added comprehensive IPC handlers in `ipcHandlers.js`:

```
ai:get-providers - Get all providers
ai:get-provider - Get specific provider
ai:get-enabled-providers - Get only enabled providers
ai:get-default-provider - Get default provider
ai:add-provider - Create new provider
ai:update-provider - Update provider
ai:delete-provider - Delete provider
ai:set-default-provider - Set as default
ai:toggle-provider - Enable/disable provider
ai:test-connection - Test connectivity
```

### Frontend Components

#### 1. TypeScript API (`aiProviderAPI.ts`)

Type-safe wrapper for IPC communication with the backend:

```typescript
class AIProviderAPI {
  async getProviders(): Promise<AIProvider[]>
  async addProvider(provider: AIProviderCreate): Promise<AIProvider>
  async updateProvider(id: string, updates: AIProviderUpdate): Promise<AIProvider>
  async deleteProvider(id: string): Promise<void>
  async testConnection(id: string): Promise<AIConnectionTest>
  async getSettings(): Promise<AISettings>
  async updateSettings(settings: Partial<AISettings>): Promise<void>
}
```

#### 2. Complete GUI Implementation (`ai-provider-settings.html`)

A fully functional, production-ready GUI with:

**Features**:
- Visual provider cards with status badges
- Add/edit/delete providers
- Connection testing with visual feedback
- Model selection per provider
- Settings panel for default configuration
- Temperature/tokens/streaming controls
- Responsive grid layout
- Toast notifications
- Modal dialogs for forms

**UI Components**:
- Provider cards with capability badges
- Model tags showing available models
- Connection status indicators
- Settings sliders and toggles
- Form inputs with validation
- Loading states
- Error handling

## Data Model

### AIProvider Interface

```typescript
interface AIProvider {
  id: string;                    // Unique identifier
  name: string;                 // Display name
  type: AIProviderType;         // Provider type enum
  endpoint: string;             // API endpoint URL
  apiKey: string;               // API key (stored securely)
  models: string[];             // Available models
  defaultModel: string;          // Default selected model
  capabilities: AIProviderCapability[]; // Feature flags
  isEnabled: boolean;           // Enable/disable flag
  isDefault: boolean;           // Default provider flag
}
```

### Storage Format

Providers are stored in the app's storage as JSON:

```json
{
  "aiProviders": "[{\"id\":\"openai-default\",\"name\":\"OpenAI\",...}]"
}
```

## Default Providers

The system initializes with three default providers:

1. **OpenAI** (Default)
   - Endpoint: `https://api.openai.com/v1`
   - Models: GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-3.5-turbo
   - Capabilities: All features

2. **Anthropic**
   - Endpoint: `https://api.anthropic.com/v1`
   - Models: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku
   - Capabilities: Chat, Vision, Tool Use, Streaming

3. **Ollama (Local)**
   - Endpoint: `http://localhost:11434/v1`
   - Models: Llama3, CodeLLama, Mistral, Neural Chat
   - Capabilities: Chat, Completion, Streaming

## Implementation Details

### Backend Changes

1. **File**: `services/aiProviderService.js`
   - Created new service class
   - Integrated with StorageManager
   - Added event emitter for real-time updates

2. **File**: `services/settingsService.js`
   - Added AI-related setting keys
   - Defined default values

3. **File**: `ipcHandlers.js`
   - Imported AIProviderService
   - Registered IPC handlers
   - Connected to storage manager

### Frontend Changes

1. **File**: `aiProviderAPI.ts`
   - TypeScript interface definitions
   - IPC wrapper methods
   - Type-safe API

2. **File**: `ai-provider-settings.html`
   - Complete HTML/CSS/JS implementation
   - Responsive design
   - State management
   - Error handling

## Usage

### For Users

1. Open the AI Provider Settings panel
2. View all configured providers
3. Add custom providers with API keys
4. Test connections before use
5. Configure default model and parameters
6. Enable/disable providers as needed

### For Developers

**Adding a new provider programmatically**:

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

**Getting current settings**:

```typescript
const settings = await aiProviderAPI.getSettings();
console.log(`Using ${settings.provider} with model ${settings.model}`);
```

**Changing default model**:

```typescript
await aiProviderAPI.updateSettings({
  model: 'gpt-4o-mini',
  temperature: 0.5
});
```

## Security Considerations

1. **API Key Storage**: Keys are stored in the app's secure storage
2. **Validation**: All inputs are validated before storage
3. **Error Handling**: Connection failures are gracefully handled
4. **HTTPS Only**: External API calls use HTTPS (validated in shell:open-external)

## Future Enhancements

1. **Usage Tracking**: Monitor API usage per provider
2. **Cost Estimation**: Calculate costs based on model pricing
3. **Provider Health**: Automatic health checks and fallbacks
4. **Model Comparison**: Side-by-side model comparison tools
5. **Prompt Templates**: Save and manage prompt templates
6. **Conversation History**: Store and manage chat histories
7. **Export/Import**: Backup and restore provider configurations

## Testing

### Manual Testing Checklist

- [ ] Add new provider
- [ ] Edit existing provider
- [ ] Delete provider
- [ ] Set default provider
- [ ] Toggle provider enabled/disabled
- [ ] Test connection with valid credentials
- [ ] Test connection with invalid credentials
- [ ] Change default model
- [ ] Adjust temperature slider
- [ ] Modify max tokens
- [ ] Toggle streaming
- [ ] Save all settings
- [ ] Reload app and verify persistence
- [ ] Test with Ollama (local provider)

### Automated Testing

The implementation includes test hooks through IPC handlers. Test the backend:

```javascript
const providers = await window.electron.invoke('ai:get-providers');
console.assert(providers.length >= 3, 'Should have default providers');
```

## Integration with IDE Features

The AI provider infrastructure enables:

1. **Code Completion**: AI-powered suggestions
2. **Chat Interface**: Interactive AI assistant
3. **Refactoring**: AI-assisted code improvements
4. **Documentation**: Auto-generate docs
5. **Code Review**: AI-powered reviews
6. **Natural Language Search**: Search codebase with questions

## Performance Considerations

1. **Lazy Loading**: Providers loaded on-demand
2. **Connection Pooling**: Reuse HTTP connections
3. **Caching**: Cache provider lists in renderer
4. **Debouncing**: Debounce settings updates
5. **Async Operations**: All I/O operations are non-blocking

## Browser Compatibility

The GUI uses modern web APIs:
- ES6+ JavaScript
- CSS Grid and Flexbox
- CSS Custom Properties
- Fetch API
- CSS Animations

Compatible with:
- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+

## Conclusion

This implementation provides a complete, production-ready AI provider management system for the Antigravity IDE. The modular architecture allows easy extension and customization while maintaining backward compatibility with existing systems.