check point

API.md

@@ -0,0 +1,186 @@
+# Game Generator API
+
+## Game Types
+
+| type_id | game_type | Mô tả |
+|---------|-----------|-------|
+| 1 | quiz | Multiple choice questions |
+| 2 | sequence_sentence | Sắp xếp câu |
+| 3 | sequence_word | Sắp xếp từ |
+
+---
+
+## 1. POST /generate
+
+Analyze + Generate nhiều games.
+
+**Request:**
+```json
+{
+    "text": "Mặt Trời là ngôi sao...",
+    "enabled_game_ids": [1, 2],      // optional, default: all
+    "max_items": 3,                   // optional, default: 3
+    "min_score": 30,                  // optional, default: 30
+    "run_validator": true             // optional, default: true
+}
+```
+
+**Response:**
+```json
+{
+    "success": true,
+    "games": [1, 2],
+    "game_scores": [
+        {"type_id": 1, "score": 85, "reason": "..."}
+    ],
+    "results": {
+        "1": [{"question": "...", "answers": "...", ...}],
+        "2": [{"sentence": "...", ...}]
+    },
+    "token_usage": {"prompt_tokens": 100, "completion_tokens": 50},
+    "llm": "gemini/gemini-2.0-flash-lite"
+}
+```
+
+---
+
+## 2. POST /generate/single
+
+1 API call = Analyze + Generate 1 game tốt nhất.
+
+**Request:**
+```json
+{
+    "text": "Python là ngôn ngữ...",
+    "enabled_game_ids": [1, 2, 3],   // optional
+    "max_items": 3                    // optional
+}
+```
+
+**Response:**
+```json
+{
+    "success": true,
+    "type_id": 1,
+    "reason": "Text has clear facts",
+    "items": [{"question": "...", ...}],
+    "token_usage": {...},
+    "llm": "..."
+}
+```
+
+---
+
+## 3. POST /generate/{type_id}
+
+Generate trực tiếp 1 game (không analyze).
+
+### Quiz (type_id = 1)
+
+**Input format:**
+```
+Question: Thủ đô Việt Nam?
+A. Hà Nội
+B. TP HCM
+C. Đà Nẵng
+D. Huế
+Correct: A
+```
+
+**Request:**
+```json
+{
+    "text": "Question: ...\\nA. ...\\nB. ...\\nCorrect: A",
+    "max_items": 5
+}
+```
+
+### Sequence Sentence (type_id = 2)
+
+**Input format:**
+```
+sentence1; sentence2; sentence3
+```
+
+**Request:**
+```json
+{
+    "text": "Mặt trời mọc; Chim hót; Người thức dậy",
+    "max_items": 10
+}
+```
+
+### Sequence Word (type_id = 3)
+
+**Input format:**
+```
+word1; word2; word3
+```
+
+**Request:**
+```json
+{
+    "text": "Apple; Banana; Orange; Grape",
+    "max_items": 10
+}
+```
+
+**Response (all direct):**
+```json
+{
+    "success": true,
+    "type_id": 1,
+    "items": [...],
+    "token_usage": {...},
+    "llm": "..."
+}
+```
+
+---
+
+## 4. GET /games
+
+**Response:**
+```json
+{
+    "total": 3,
+    "active_count": 3,
+    "games": [
+        {"type_id": 1, "game_type": "quiz", "display_name": "Quiz", "active": true},
+        {"type_id": 2, "game_type": "sequence_sentence", ...},
+        {"type_id": 3, "game_type": "sequence_word", ...}
+    ]
+}
+```
+
+---
+
+## 5. POST /llm
+
+**Request:**
+```json
+{
+    "provider": "gemini",
+    "model_name": "gemini-2.0-flash-lite",
+    "temperature": 0.1
+}
+```
+
+Ollama:
+```json
+{
+    "provider": "ollama",
+    "model_name": "qwen2.5:14b",
+    "base_url": "http://localhost:11434"
+}
+```
+
+---
+
+## 6. Other Endpoints
+
+- `GET /llm` - Xem LLM config hiện tại
+- `POST /reload` - Reload game definitions
+- `GET /health` - Health check
+- `POST /games/{game_type}/activate` - Bật game
+- `POST /games/{game_type}/deactivate` - Tắt game