feat(issue-57): ドキュメントからハンズオン演習を自動生成するAI機能の実装

Neon-straySheep · Neon-straySheep · commit c1680e027110 · 2026-02-20T02:38:33.000+09:00
## 概要 ユーザーが学びたい技術のドキュメントを入力すると、 LLMを使用してランクに見合った実践的なハンズオン演習を自動生成する機能を実装。 概念実証を優先し、まずは動くことを重視。 ## 実装内容 ### 1. プロンプトテンプレート拡張 - `app/core/prompts.py`: QUEST_GENERATION_TEMPLATEを詳細化 - ランク別の難易度設定ガイドライン - JSON出力形式の厳密な指定 - ステップ構成の要件定義 ### 2. サービス層実装 - `app/services/quest_service.py`: generate_handson_quest関数 - LLM呼び出し (temperature=0.7で創造性を持たせる) - JSONパース+エラーハンドリング - デフォルト値フォールバック ### 3. スキーマ定義拡張 - `app/schemas/quest.py`: QuestGenerationRequest/Response追加 - QuestStep: 演習ステップの詳細定義 - リクエストバリデーション (document_content: 10KB制限) - Swagger UIのExample付き ### 4. APIエンドポイント実装 - `app/api/endpoints/quest.py`: POST /api/v1/quest/generate - リクエスト受け取り - サービス呼び出し - エラーハンドリング ### 5. ルーター登録 - `app/api/api.py`: questルーターを統合 ### 6. テスト実装 - `tests/test_services/test_quest_service.py`: サービス層テスト - `tests/test_api/test_quest.py`: APIエンドポイントテスト - LLM呼び出しをモック化してCI環境対応 - 正常系・エラー系・バリデーションをカバー ## MVP制限（概念実証優先） - ❌ DB保存なし: 生成された演習はAPIレスポンスのみ - ❌ 進捗管理なし: 演習の完了状態やスコアは後続Issue - ⚠️ 生成品質: プロンプト調整は後続Issue ## セキュリティ考慮 - Request Bodyサイズ制限（document_content: 10KB） - LLMレスポンスのサニタイズ（JSONパースエラー時のフォールバック） - エラーメッセージの安全な返却 ## テスト要件 - モック使用でAPI キー不要（CI環境対応） - 正常系・エラー系・バリデーションを網羅 ## 完了条件（DoD） - [x] POST /api/v1/quest/generate実装完了 - [x] スキーマ定義とバリデーション実装 - [x] テスト5件以上実装（モック使用） - [x] エラーハンドリング実装 ## 依存 - Issue #32（AI基盤セットアップ）✅ - Issue #36（ランク判定AI）✅ ## 次のステップ（後続Issue） - Issue #41: 演習のDB保存機能 - Issue #42: 演習進捗管理機能 - Issue #43: 演習生成品質向上 - Issue #44: 生成コードのセキュリティチェック
diff --git a/backend/app/api/api.py b/backend/app/api/api.py
@@ -1,9 +1,9 @@
 """ルーター集約"""
 
 from fastapi import APIRouter
-from app.api.endpoints import analyze
-
+from app.api.endpoints import analyze, quest
 
 api_router = APIRouter()
 
 api_router.include_router(analyze.router, prefix="/analyze", tags=["analyze"])
+api_router.include_router(quest.router, prefix="/quest", tags=["quest"])
diff --git a/backend/app/api/endpoints/quest.py b/backend/app/api/endpoints/quest.py
@@ -0,0 +1,54 @@
+"""
+ハンズオン演習生成APIエンドポイント
+
+POST /api/v1/quest/generate - ドキュメントからハンズオン演習を生成
+"""
+
+from fastapi import APIRouter, HTTPException
+from app.schemas.quest import QuestGenerationRequest, QuestGenerationResponse
+from app.services.quest_service import generate_handson_quest
+
+router = APIRouter()
+
+
+@router.post("/generate", response_model=QuestGenerationResponse)
+async def generate_quest(request: QuestGenerationRequest) -> QuestGenerationResponse:
+    """
+    ドキュメントからハンズオン演習を生成
+
+    Args:
+        request: ハンズオン生成リクエスト
+
+    Returns:
+        QuestGenerationResponse: 生成された演習
+
+    Raises:
+        HTTPException 500: LLM呼び出し失敗時
+
+    Example:
+        Request:
+            {
+                "document_content": "Reactの基本: コンポーネント、State、Props...",
+                "user_rank": 2,
+                "user_skills": "JavaScript, HTML/CSS"
+            }
+
+        Response:
+            {
+                "title": "Reactでカウンターアプリを作ろう",
+                "difficulty": "beginner",
+                "estimated_time_minutes": 45,
+                "learning_objectives": ["Stateの理解", "イベントハンドリング"],
+                "steps": [...],
+                "resources": ["https://react.dev/"]
+            }
+    """
+    try:
+        result = await generate_handson_quest(
+            document_content=request.document_content,
+            user_rank=request.user_rank,
+            user_skills=request.user_skills,
+        )
+        return QuestGenerationResponse(**result)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Quest generation failed: {str(e)}")
diff --git a/backend/app/core/prompts.py b/backend/app/core/prompts.py
@@ -93,36 +93,47 @@
 
 
 # ============================================================
-# 演習生成用プロンプト（Phase 3で詳細実装）
+# 演習生成用プロンプト
 # ============================================================
 
-QUEST_GENERATION_TEMPLATE = ChatPromptTemplate.from_messages(
-    [
-        ("system", SYSTEM_PROMPT_BASE),
-        (
-            "user",
-            """# ハンズオン演習生成
+QUEST_GENERATION_TEMPLATE = """あなたは優秀な技術教育者です。
+以下のドキュメント内容を元に、ユーザーのランクに適したハンズオン演習を生成してください。
 
-ドキュメント内容:
+## ドキュメント内容
 {document_content}
 
-対象ユーザー:
-- ランク: {user_rank}
+## 対象ユーザー
+- ランク: {user_rank} (0: 種子, 1: 苗木, ..., 9: 世界樹)
 - 得意分野: {user_skills}
 
-このドキュメントの内容を学ぶための、実践的なハンズオン演習を生成してください。
+## 生成要件
+1. ユーザーのランクに適した難易度設定
+   - ランク0-2: 基礎的な手順、丁寧な説明
+   - ランク3-5: 中級者向け、応用要素を含む
+   - ランク6-9: 高度な実装、最適化やアーキテクチャ設計
+2. 段階的な手順（5-10ステップ）
+3. 各ステップは実行可能で具体的
+4. 学習効果が高く、実務に役立つ内容
 
-## 要件
-- ユーザーのランクに適した難易度
-- 段階的な手順（5-10ステップ）
-- 実行可能な具体的なタスク
-- 学習効果の高い内容
+## 出力形式（JSON）
+{{
+  "title": "演習タイトル",
+  "difficulty": "beginner|intermediate|advanced",
+  "estimated_time_minutes": 60,
+  "learning_objectives": ["目標1", "目標2", "目標3"],
+  "steps": [
+    {{
+      "step_number": 1,
+      "title": "ステップタイトル",
+      "description": "具体的な手順の説明",
+      "code_example": "コード例（必要に応じて）",
+      "checkpoints": ["確認ポイント1", "確認ポイント2"]
+    }}
+  ],
+  "resources": ["参考リンク1", "参考リンク2"]
+}}
 
-出力形式: Markdown
-""",
-        ),
-    ]
-)
+JSON以外の形式や追加の説明は含めず、JSONのみを出力してください。"""
 
 
 # ============================================================
diff --git a/backend/app/schemas/quest.py b/backend/app/schemas/quest.py
@@ -2,7 +2,7 @@
 
 from datetime import datetime
 
-from pydantic import BaseModel, ConfigDict, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from app.models.enums import QuestCategory
 
@@ -32,3 +32,71 @@ class Quest(BaseModel):
     created_at: datetime
 
     model_config = ConfigDict(from_attributes=True)
+
+
+# ============================================================
+# ハンズオン演習生成用スキーマ
+# ============================================================
+
+
+class QuestStep(BaseModel):
+    """演習ステップ"""
+
+    step_number: int = Field(..., ge=1, description="ステップ番号")
+    title: str = Field(..., min_length=1, max_length=200, description="ステップタイトル")
+    description: str = Field(..., description="手順の詳細説明")
+    code_example: str = Field(default="", description="コード例")
+    checkpoints: list[str] = Field(default_factory=list, description="確認ポイント")
+
+
+class QuestGenerationRequest(BaseModel):
+    """ハンズオン生成リクエスト"""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "document_content": "Reactの基本: コンポーネント、State、Props...",
+                "user_rank": 2,
+                "user_skills": "JavaScript, HTML/CSS",
+            }
+        }
+    )
+
+    document_content: str = Field(
+        ..., min_length=10, max_length=10000, description="学習対象ドキュメント"
+    )
+    user_rank: int = Field(..., ge=0, le=9, description="ユーザーランク")
+    user_skills: str = Field(default="", max_length=500, description="得意分野（オプション）")
+
+
+class QuestGenerationResponse(BaseModel):
+    """ハンズオン生成レスポンス"""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "title": "Reactでカウンターアプリを作ろう",
+                "difficulty": "beginner",
+                "estimated_time_minutes": 45,
+                "learning_objectives": ["Stateの理解", "イベントハンドリング"],
+                "steps": [
+                    {
+                        "step_number": 1,
+                        "title": "プロジェクトのセットアップ",
+                        "description": "create-react-appで新規プロジェクトを作成",
+                        "code_example": "npx create-react-app counter-app",
+                        "checkpoints": ["プロジェクトが起動した"],
+                    }
+                ],
+                "resources": ["https://react.dev/"],
+            }
+        }
+    )
+
+    title: str = Field(..., description="演習タイトル")
+    difficulty: str = Field(..., description="難易度（beginner/intermediate/advanced）")
+    estimated_time_minutes: int = Field(..., ge=1, description="推定所要時間（分）")
+    learning_objectives: list[str] = Field(..., description="学習目標")
+    steps: list[QuestStep] = Field(..., min_length=1, description="演習ステップ")
+    resources: list[str] = Field(default_factory=list, description="参考リソース")
+
diff --git a/backend/app/services/quest_service.py b/backend/app/services/quest_service.py
@@ -0,0 +1,75 @@
+"""
+ハンズオン演習生成サービス
+
+LLMを使用してドキュメントからハンズオン演習を生成するビジネスロジック
+"""
+
+import json
+from app.core.llm import invoke_llm
+from app.core.prompts import QUEST_GENERATION_TEMPLATE
+
+
+async def generate_handson_quest(
+    document_content: str,
+    user_rank: int,
+    user_skills: str = "",
+) -> dict:
+    """
+    LLMを使用してハンズオン演習を生成
+
+    Args:
+        document_content: 学習対象のドキュメント
+        user_rank: ユーザーのランク（0-9）
+        user_skills: ユーザーの得意分野（オプション）
+
+    Returns:
+        {
+            "title": str,
+            "difficulty": str,
+            "estimated_time_minutes": int,
+            "learning_objectives": list[str],
+            "steps": list[dict],
+            "resources": list[str]
+        }
+
+    Note:
+        - JSONパースエラー時はデフォルト値を返す
+        - 生成品質の向上は後続Issueで対応
+    """
+    # プロンプトテンプレートに入力値を埋め込む
+    prompt = QUEST_GENERATION_TEMPLATE.format(
+        document_content=document_content,
+        user_rank=user_rank,
+        user_skills=user_skills or "未指定",
+    )
+
+    # LLMに非同期で呼び出し (temperature=0.7で創造性を持たせる)
+    response = await invoke_llm(prompt=prompt, temperature=0.7)
+
+    # JSONパース（エラーハンドリング付き）
+    try:
+        result = json.loads(response)
+        # 必須フィールドの存在確認
+        required_fields = ["title", "difficulty", "steps"]
+        if not all(k in result for k in required_fields):
+            raise ValueError("Missing required fields in LLM response")
+        return result
+    except (json.JSONDecodeError, ValueError) as e:
+        # LLMがJSON以外を返した場合のフォールバック
+        print(f"JSON parse error: {e}. Returning fallback response.")
+        return {
+            "title": "演習生成エラー",
+            "difficulty": "beginner",
+            "estimated_time_minutes": 30,
+            "learning_objectives": ["ドキュメントの内容理解"],
+            "steps": [
+                {
+                    "step_number": 1,
+                    "title": "ドキュメントを読む",
+                    "description": "提供されたドキュメントを読んで理解を深めてください。",
+                    "code_example": "",
+                    "checkpoints": ["ドキュメントの概要を理解した"],
+                }
+            ],
+            "resources": [],
+        }
diff --git a/backend/tests/test_api/test_quest.py b/backend/tests/test_api/test_quest.py
@@ -0,0 +1,101 @@
+"""
+ハンズオン演習生成APIエンドポイントのテスト
+
+FastAPIのテストクライアントを使用
+"""
+
+import json
+import pytest
+from unittest.mock import AsyncMock, patch
+from fastapi.testclient import TestClient
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_generate_quest_success():
+    """正常系: POST /api/v1/quest/generate"""
+    mock_response = {
+        "title": "Pythonでウェブスクレイピング",
+        "difficulty": "intermediate",
+        "estimated_time_minutes": 60,
+        "learning_objectives": ["Beautiful Soupの使い方"],
+        "steps": [
+            {
+                "step_number": 1,
+                "title": "ライブラリインストール",
+                "description": "pip install beautifulsoup4",
+                "code_example": "pip install beautifulsoup4 requests",
+                "checkpoints": ["インストール完了"],
+            }
+        ],
+        "resources": [],
+    }
+
+    with patch("app.services.quest_service.invoke_llm", new_callable=AsyncMock) as mock_invoke:
+        mock_invoke.return_value = json.dumps(mock_response)
+
+        response = client.post(
+            "/api/v1/quest/generate",
+            json={
+                "document_content": "Pythonでウェブスクレイピングを学ぶ...",
+                "user_rank": 3,
+                "user_skills": "Python基礎",
+            },
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["title"] == "Pythonでウェブスクレイピング"
+        assert data["difficulty"] == "intermediate"
+
+
+def test_generate_quest_minimal():
+    """最小入力のテスト"""
+    mock_response = {
+        "title": "Docker入門",
+        "difficulty": "beginner",
+        "estimated_time_minutes": 40,
+        "learning_objectives": ["Dockerの基本操作"],
+        "steps": [
+            {
+                "step_number": 1,
+                "title": "Dockerインストール",
+                "description": "Docker Desktopをインストール",
+                "code_example": "",
+                "checkpoints": ["バージョン確認"],
+            }
+        ],
+        "resources": ["https://docs.docker.com/"],
+    }
+
+    with patch("app.services.quest_service.invoke_llm", new_callable=AsyncMock) as mock_invoke:
+        mock_invoke.return_value = json.dumps(mock_response)
+
+        response = client.post(
+            "/api/v1/quest/generate",
+            json={"document_content": "Dockerの基礎を学ぶチュートリアル", "user_rank": 1},
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["title"] == "Docker入門"
+        assert data["difficulty"] == "beginner"
+
+
+def test_generate_quest_invalid_rank():
+    """エラー系: ランクが範囲外は422エラー"""
+    response = client.post(
+        "/api/v1/quest/generate", json={"document_content": "Test", "user_rank": 99}
+    )
+
+    assert response.status_code == 422
+
+
+def test_generate_quest_document_too_short():
+    """エラー系: ドキュメントが短すぎる場合は422エラー"""
+    response = client.post(
+        "/api/v1/quest/generate", json={"document_content": "Short", "user_rank": 2}
+    )
+
+    assert response.status_code == 422
diff --git a/backend/tests/test_services/test_quest_service.py b/backend/tests/test_services/test_quest_service.py
