# Sudoku Game

## Game Description

Sudoku is a popular logic puzzle game where players need to fill a 9×9 grid with digits 1 through 9, ensuring that each row, each column, and each 3×3 subgrid contains all digits from 1 to 9 without repetition. Each puzzle starts with some numbers already filled in, and players must use these clues to deduce the numbers that should go in the remaining empty cells.

## Code Logic

### Core Classes and Methods

- **Sudoku**: Inherits from the base `Game` class, responsible for generating and handling Sudoku games.
  - `generate()`: Generates Sudoku puzzle and solution, controls the number of empty cells based on difficulty level, can specify whether a unique solution is required.
  - `extract_answer()`: Extracts the Sudoku solution from the model's response text.
  - `_generate_complete_sudoku()`: Generates a complete valid 9x9 Sudoku solution.
  - `_mask_sudoku_by_difficulty()`: Masks some digits based on difficulty level, with option to ensure unique solution.
  - `_has_unique_solution()`: Checks if the given Sudoku has a unique solution.

- **SudokuVerifier**: Inherits from the base `Verifier` class, verifies whether the model's Sudoku solution is correct.
  - `verify()`: Verifies if the solution follows Sudoku rules and is consistent with the original puzzle.
  - `_is_valid_sudoku()`: Checks if the Sudoku solution follows the rules.
  - `_is_consistent_with_original()`: Checks if the solution is consistent with the original puzzle.

### Data Generation Process

1. Uses backtracking algorithm to generate a complete, valid 9x9 Sudoku solution.
2. Randomly retains some digits based on specified difficulty level (1-4):
   - Difficulty 1 (Easy): Retains 35-45 hint cells
   - Difficulty 2 (Medium): Retains 30-35 hint cells
   - Difficulty 3 (Hard): Retains 25-30 hint cells
   - Difficulty 4 (Expert): Retains 20-25 hint cells
3. If unique solution is required, uses gradual removal method to ensure the generated Sudoku has a unique solution.
4. Generates puzzle description, randomly selecting Chinese or English templates.
5. Saves the generated puzzle, solution, and metadata to a `Data` object.

### Answer Verification Process

1. Extracts the Sudoku solution from the model's response (usually in tuple form within Python code blocks).
2. Verifies if the solution is a valid 9x9 Sudoku (each row, column, and 3x3 subgrid contains 1-9 without repetition).
3. Verifies if the solution is consistent with the numbers already given in the original puzzle.

## Usage Instructions

### Generating Sudoku Game Data

Use the following command to generate Sudoku game data:

```bash
bash games/tasks/sudoku/run.sh --num_of_data 100 --difficulty 3 --unique_solution
```

Parameter explanations:
- `--num_of_data`: Number of puzzles to generate, default is 100.
- `--max_attempts`: Maximum number of attempts per puzzle, default is 1000.
- `--difficulty`: Difficulty level (1-4), default is 3.
- `--unique_solution`: Specifies that generated Sudoku must have a unique solution (default).

Generated data will be saved in `games/tasks/sudoku/data/unique_solution_{unique_solution}/difficulty_{difficulty}/num_of_data_{num_of_data}/data.jsonl` file.

## Features

- Supports different difficulty levels (1-4) for Sudoku generation
- Supports generating Sudoku puzzles with unique or multiple solutions
- Supports random mixed Chinese and English prompt generation
- Strict verification of Sudoku solution correctness
- Performance analysis of model solutions by difficulty level