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

```javascript
// 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

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

### Step 2: Replace/Add Files

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

```bash
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

```bash
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:

```javascript
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