gen_game-a0/API.md

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:

{
    "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:

{
    "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:

{
    "text": "Python là ngôn ngữ...",
    "enabled_game_ids": [1, 2, 3],   // optional
    "max_items": 3                    // optional
}

Response:

{
    "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:

{
    "text": "Question: ...\\nA. ...\\nB. ...\\nCorrect: A",
    "max_items": 5
}

Sequence Sentence (type_id = 2)

Input format:

sentence1; sentence2; sentence3

Request:

{
    "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:

{
    "text": "Apple; Banana; Orange; Grape",
    "max_items": 10
}

Response (all direct):

{
    "success": true,
    "type_id": 1,
    "items": [...],
    "token_usage": {...},
    "llm": "..."
}

---

4. GET /games

Response:

{
    "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:

{
    "provider": "gemini",
    "model_name": "gemini-2.0-flash-lite",
    "temperature": 0.1
}

Ollama:

{
    "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