# Robert's Sudoku Solver

A comprehensive web application that uses Google Vision AI to extract Sudoku puzzles from images and features a powerful manual entry mode with support for any grid size.

## Features

- 📷 Take photos or upload screenshots of Sudoku puzzles
- 🤖 AI-powered OCR using Google Vision API
- 🧩 Automatic Sudoku puzzle extraction
- ⚡ Fast solving using backtracking algorithm
- ✏️ Manual entry mode with customizable grid sizes
- 🎯 Visual grid lines for easy puzzle section identification
- 📱 Responsive design for mobile and desktop
- 🎯 Visual feedback and error handling
- 🔢 Support for any grid size (4×4, 6×6, 9×9, 12×12, 16×16, etc.)

## Setup Instructions

### 1. Prerequisites

- PHP 7.4 or higher
- Composer (for Google Cloud PHP libraries)
- Google Cloud account with Vision API enabled
- Web server (Apache/Nginx) or PHP built-in server

### 2. Google Vision API Setup

1. **Get a Google Vision API Key:**
   - Go to [Google Cloud Console](https://console.cloud.google.com/)
   - Create a new project or select an existing one

2. **Enable Vision API:**
   - Navigate to "APIs & Services" > "Library"
   - Search for "Cloud Vision API" and enable it

3. **Create API Key:**
   - Go to "APIs & Services" > "Credentials"
   - Click "Create Credentials" > "API Key"
   - Copy the generated API key

4. **Enable Billing:**
   - Make sure billing is enabled for your project
   - Vision API usage may incur costs

### 3. Configuration

1. **Update API Key:**
   - Copy `config.example.php` to `config.php`
   - Replace the placeholder API key with your actual Google Vision API key:

   ```php
   'api_key' => 'YOUR_ACTUAL_API_KEY_HERE', // Replace with your API key
   ```

2. **Security Note:**
   - Never commit your API key to version control
   - Consider using environment variables for production
   - Rotate your API keys regularly

### 4. Running the Application

#### Option 1: PHP Built-in Server (Development)
```bash
php -S localhost:8000
```
Then open http://localhost:8000/sudoku_solver.html

#### Option 2: Apache/Nginx (Production)
- Place files in your web server's document root
- Ensure PHP is enabled
- Make sure file upload permissions are set correctly

### 5. Testing & Troubleshooting

#### Diagnostic Tools

- **`check_api_key.php`** - Check current API key restrictions and status
- **`test_api_key.php`** - Test your API key without uploading images
- **`diagnose_api.php`** - Comprehensive API diagnostic with detailed error analysis
- **`test_setup.html`** - Web-based testing interface
- **`test_upload.php`** - Test image upload functionality

#### Common API Issues

**"Requests to this API are blocked":**
1. Go to https://console.cloud.google.com/apis/library
2. Search for "Cloud Vision API"
3. Click "ENABLE"
4. Wait 2-3 minutes
5. Try again

**"Requests from referer <empty> are blocked":**
This means your API key has HTTP referrer restrictions.
1. Go to https://console.cloud.google.com/apis/credentials
2. Find your API key
3. Click EDIT
4. Under "Application restrictions":
   - Change to "None" (quick fix)
   - OR add localhost referrers
5. Click SAVE
6. Wait 2-3 minutes

**Run `check_api_key.php` to diagnose your specific issue.**

### 6. Usage

### Primary Interface: Manual Mode

1. **Open the Application:**
   - Visit `http://localhost:8000` or `http://localhost:8000/index.html`
   - Click "Manual Mode" (primary button)

2. **Set Grid Size:**
   - Choose width and height (e.g., 9×9 for standard Sudoku)
   - Click "Create Grid"
   - Supported sizes: 4×4, 6×6, 9×9, 12×12, 16×16, etc.

3. **Enter Numbers:**
   - Click on any cell
   - Type numbers 1-9 (or appropriate range for grid size)
   - Use arrow keys to navigate
   - Press Delete to clear cells

4. **Solve the Puzzle:**
   - Click "Solve Puzzle"
   - View the solved grid below
   - Thick black lines show puzzle sections

### Alternative: AI Photo Mode

1. **Access AI Mode:**
   - Click the small "🤖 Try AI Photo Mode" link at bottom
   - Or visit `http://localhost:8000/ai_mode.html`

2. **Upload an Image:**
   - Click "📁 Upload Image" to select a file
   - Or click "📷 Take Photo" to capture using camera

3. **Image Requirements:**
   - Clear, well-lit image of a Sudoku puzzle
   - Numbers should be clearly visible
   - Avoid blurry or distorted images
   - Supported formats: JPEG, PNG, GIF, WebP

4. **Solve the Puzzle:**
   - Wait for AI to process the image
   - Original numbers appear in gray
   - Click "Solve Puzzle" to see the solution
   - Solved numbers appear in green

## File Structure

```
sudoku-solver/
├── sudoku_solver.html    # Main HTML interface
├── process_image.php     # Google Vision API processing
├── solve_sudoku.php      # Sudoku solver backend
├── vendor/              # Composer dependencies
├── README.md            # This file
└── [service-key.json]   # Your Google service account key (keep secure!)
```

## Troubleshooting

### Common Issues

1. **"No text detected in the image"**
   - Ensure the image is clear and well-lit
   - Make sure numbers are clearly visible
   - Try a different angle or lighting

2. **"Vision API Error" / "Requests to this API are blocked"**
   - **Most Common**: Vision API not enabled for your project
   - Check your API key is correct and active
   - Verify the Vision API is enabled: https://console.cloud.google.com/apis/library
   - Ensure billing is enabled: https://console.cloud.google.com/billing
   - Check your API usage quotas and restrictions
   - Run the diagnostic tool: `diagnose_api.php` or `test_api_key.php`

3. **"Unable to solve this puzzle"**
   - The puzzle might have multiple solutions
   - Check if the OCR correctly identified all numbers
   - Try re-uploading the image

4. **File upload errors**
   - Check PHP upload limits in php.ini
   - Ensure proper file permissions
   - Verify supported image formats

### Debug Mode

To enable debug logging, add this to the top of PHP files:
```php
error_reporting(E_ALL);
ini_set('display_errors', 1);
```

## API Reference

### process_image.php

**Endpoint:** `POST /process_image.php`

**Input:** Form data with `image` file

**Output:**
```json
{
  "success": true,
  "puzzle": [[1,2,3,...],[...],...]
}
```

### solve_sudoku.php

**Endpoint:** `POST /solve_sudoku.php`

**Input:**
```json
{
  "puzzle": [[1,2,3,...],[...],...]
}
```

**Output:**
```json
{
  "success": true,
  "solution": [[1,2,3,...],[...],...]
}
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

This project is open source and available under the MIT License.

## Disclaimer

This application uses Google Cloud Vision API which may incur costs based on usage. Please refer to Google's pricing documentation before deploying to production.