docs/GEMINI_API_CONFIG.md

# Gemini API リクエスト設定

> 超天才クイズ v3 における Gemini API 呼び出しの詳細設定

---

## 1. 基本設定

| 項目 | 値 |
|------|-----|
| **モデル** | `gemini-2.5-flash` |
| **API キー** | 環境変数 `GEMINI_API_KEY` |
| **SDK** | `google-generativeai` (Python) |

```python
import google.generativeai as genai
genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
self.model = genai.GenerativeModel("gemini-2.5-flash")
```

---

## 2. 用途別パラメータ設定

### 2.1 問題生成 (`generate_questions`)

| パラメータ | 値 | 説明 |
|-----------|-----|------|
| `temperature` | **0.7** | 創造性高め（多様な問題生成） |
| `max_output_tokens` | **16384** | 5問分の出力を保証 |
| `response_mime_type` | `application/json` | JSON形式で直接取得 |

```python
generation_config=genai.GenerationConfig(
    temperature=0.7,
    max_output_tokens=16384,
    response_mime_type="application/json"
)
```

### 2.2 教科別評価生成 (`generate_evaluation`)

| パラメータ | 値 | 説明 |
|-----------|-----|------|
| `temperature` | **0.5** | 一貫性重視（安定した評価） |
| `max_output_tokens` | **2048** | 1教科分の評価に十分 |
| `response_mime_type` | `application/json` | JSON形式で直接取得 |

```python
generation_config=genai.GenerationConfig(
    temperature=0.5,
    max_output_tokens=2048,
    response_mime_type="application/json"
)
```

### 2.3 全体評価生成 (`_generate_overall_evaluation`)

| パラメータ | 値 | 説明 |
|-----------|-----|------|
| `temperature` | **0.5** | 一貫性重視 |
| `max_output_tokens` | **1024** | 全体サマリーに十分 |
| `response_mime_type` | `application/json` | JSON形式で直接取得 |

---

## 3. システムインストラクション（プロンプト）

### 3.1 問題生成プロンプト

**ロール定義**:
```
あなたは中学受験対策の{教科名}問題作成の専門家です。
```

**主要指示**:
- Knowledge Base（教材）に基づいた問題を生成
- 指定されたジャンルID（JP01, MA01等）を使用
- 難易度を「基本」「標準」「応用」でバランス
- 5問生成

**出力形式**:
```json
[
  {
    "category": "ジャンルID",
    "difficulty": "標準",
    "question": "問題文",
    "choices": ["選択肢1", "選択肢2", "選択肢3", "選択肢4"],
    "correct_answer": 0,
    "explanation": "解説文"
  }
]
```

**オプション追加情報**:
- ユーザー統計（正答率60%未満は基本中心、60%以上は標準・応用）
- 直近20問の履歴（重複回避用）

### 3.2 評価生成プロンプト

**ロール定義**:
```
あなたは中学受験の{教科名}指導の専門家です。
```

**入力データ**:
- 今回の結果（問題数、正解数、正答率）
- カテゴリ別結果
- 解答詳細（最大10問）
- 累積統計（オプション）

**出力形式**:
```json
{
  "advice": "総合的なアドバイス（2-3文）",
  "strengths": ["強み・得意分野1", "強み・得意分野2"],
  "weaknesses": ["改善点・苦手分野1", "改善点・苦手分野2"],
  "recommended_topics": ["おすすめの学習トピック1", "おすすめの学習トピック2"]
}
```

**注意事項**:
- 具体的で建設的なアドバイス
- 小学生に分かりやすい表現
- 励ましの言葉を含める

### 3.3 全体評価プロンプト

**入力**: 教科別評価のJSON

**出力形式**:
```json
{
  "overall_advice": "全体的なアドバイス（2-3文）",
  "strengths": ["強み1", "強み2"],
  "weaknesses": ["改善点1", "改善点2"],
  "next_steps": ["次のステップ1", "次のステップ2"]
}
```

---

## 4. ジャンルID一覧

### 国語 (jp)
| ID | 名称 |
|----|------|
| JP01 | 漢字・語彙 |
| JP02 | 文法・言葉のきまり |
| JP03 | 物語文読解 |
| JP04 | 説明文・論説文読解 |
| JP05 | 随筆文読解 |
| JP06 | 詩・韻文 |
| JP07 | 記述問題 |
| JP08 | 知識・文学史 |

### 算数 (math)
| ID | 名称 |
|----|------|
| MA01 | 計算 |
| MA02 | 数の性質 |
| MA03 | 割合・比 |
| MA04 | 速さ |
| MA05 | 文章題（その他） |
| MA06 | 平面図形 |
| MA07 | 立体図形 |
| MA08 | 場合の数・確率 |
| MA09 | グラフ・表 |
| MA10 | 特殊算 |

### 理科 (sci)
| ID | 名称 |
|----|------|
| SC01 | 力・運動 |
| SC02 | 電気 |
| SC03 | 光・音・熱 |
| SC04 | 物質の性質 |
| SC05 | 水溶液 |
| SC06 | 燃焼・化学変化 |
| SC07 | 植物 |
| SC08 | 動物 |
| SC09 | 人体 |
| SC10 | 天体 |
| SC11 | 気象 |
| SC12 | 地学 |

### 社会 (soc)
| ID | 名称 |
|----|------|
| SO01 | 日本地理（国土・自然） |
| SO02 | 日本地理（産業） |
| SO03 | 世界地理 |
| SO04 | 歴史（古代〜平安） |
| SO05 | 歴史（鎌倉〜室町） |
| SO06 | 歴史（安土桃山〜江戸） |
| SO07 | 歴史（明治〜現代） |
| SO08 | 公民（政治・憲法） |
| SO09 | 公民（経済・国際） |
| SO10 | 時事問題 |

---

## 5. 関連ファイル

| ファイル | 説明 |
|---------|------|
| `src/services/gemini_service.py` | Gemini API呼び出しメインロジック |
| `src/prompts/question_prompts.py` | 問題生成プロンプト定義 |
| `src/prompts/evaluation_prompts.py` | 評価生成プロンプト定義 |
| `src/knowledge/*.md` | 教科別Knowledge Base |

---

## 6. 設定変更時の注意

- **temperature**: 上げると多様性増加、下げると一貫性増加
- **max_output_tokens**: 出力が途切れる場合は増やす
- **モデル変更**: `gemini-2.5-flash` は高速・低コスト。精度重視なら `gemini-2.0-pro` 検討

---

**最終更新**: 2025-12-12