# OpenAI Service Setup Guide

This document explains how to configure and use the OpenAI service for parsing book metadata from images.

## Overview

The Bookshelf app now supports two AI services for book cover analysis:
1. **Google Gemini** (original service)
2. **OpenAI** (new alternate service)

The app will automatically try OpenAI first if configured, and fall back to Gemini if OpenAI fails or is not configured.

## Configuration

### Step 1: Configure API Keys

Edit `lib/config/api_config.dart`:

```dart
class ApiConfig {
  // Gemini API (original service)
  static const String geminiApiKey = 'YOUR_GEMINI_API_KEY_HERE';
  
  // OpenAI API (new service)
  static const String openaiApiKey = 'YOUR_OPENAI_API_KEY_HERE';
  
  // OpenAI API endpoint
  static const String openaiBaseUrl = 'http://localhost:8317';
}
```

### Step 2: Replace API Keys

Replace the placeholder values with your actual API keys:

- **OpenAI API Key**: Get from your OpenAI account or local OpenAI-compatible server
- **Gemini API Key**: Get from [Google AI Studio](https://makersuite.google.com/app/apikey) (fallback)

## OpenAI Service Details

### Endpoint Configuration

The OpenAI service is configured to use:
- **Default endpoint**: `http://localhost:8317/v1/chat/completions`
- **Model**: `glm-4` (vision-capable)
- **Max tokens**: 500
- **Temperature**: 0.3

**Important**: The server must support the `glm-4` model. This is a required model name for this OpenAI-compatible endpoint.

You can customize the endpoint by changing the `openaiBaseUrl` in `api_config.dart`.

### How It Works

1. The app captures an image using the camera
2. The image is converted to base64 format
3. A prompt is sent to the OpenAI API with the image
4. The API analyzes the image and extracts:
   - Book title
   - Author name
   - Genre (fiction/fantasy/science/detective/biography/other)
   - Brief annotation/description
5. The parsed data is returned and pre-filled in the add book form

### Service Priority

The app follows this priority order:
1. **OpenAI** (if API key is configured) - tried first
2. **Gemini** (if OpenAI fails or is not configured) - fallback

This ensures you always have a working service available.

## Testing

To test the OpenAI service:

1. Make sure your OpenAI server is running at `http://localhost:8317`
2. Configure your OpenAI API key in `api_config.dart`
3. Run the app: `flutter run`
4. Navigate to the "Add Book" screen
5. Tap the camera icon to scan a book cover
6. The app will use OpenAI to analyze the image

## Troubleshooting

### "API ключ не настроен (ни OpenAI, ни Gemini)"

This error means neither OpenAI nor Gemini API keys are configured. At least one must be set in `api_config.dart`.

### "Не удалось распознать книгу"

This can occur if:
- The API request failed (check your server logs)
- The image quality is poor
- The API returned invalid JSON
- Network connectivity issues

### OpenAI Service Not Working

If OpenAI fails, the app will automatically fall back to Gemini. Check the console output to see which service is being used:

```
Using OpenAI service for analysis
```
or
```
Using Gemini service for analysis
```

### Network Issues

Make sure:
- Your OpenAI server is accessible from the device/emulator
- For Android emulator: Use `10.0.2.2` instead of `localhost`
- For iOS simulator: `localhost` should work
- For physical device: Use your machine's actual IP address

## Files Modified

1. **lib/services/openai_service.dart** - New OpenAI service implementation
2. **lib/config/api_config.dart** - Added OpenAI configuration
3. **lib/screens/scanner_screen.dart** - Updated to support both services
4. **lib/screens/add_book_screen.dart** - Updated to pass OpenAI configuration
5. **pubspec.yaml** - Added `http` package dependency

## Future Enhancements

Possible improvements:
- Add UI option to manually select which service to use
- Add retry logic with different services
- Implement caching of recognized books
- Add support for multiple OpenAI models
- Add detailed error messages and logging