Merge pull request #95 from kc3hack/feature/issue-88-skill-tree-ai-improve

feat: #88 スキルツリーAI生成の最適化と三角形レイアウト改善

Author: Inlet-back

.github/STREAMING_IMPLEMENTATION.md

@@ -0,0 +1,187 @@
+# スキルツリーストリーミング実装ガイド
+
+## 概要
+
+LangChain Expression Language (LCEL) の `astream()` を使用して、スキルツリーをノード単位にプログレッシブ表示します。
+
+## 実装内容
+
+### バックエンド
+
+1. **ストリーミング関数** (`backend/app/core/llm.py`):
+   - `stream_llm()`: LLMからストリーミングでチャンクを受信
+
+2. **JSON Lines形式プロンプト** (`backend/app/core/prompts_streaming.py`):
+   - 1行1ノード形式で生成させる
+   - 例: `{"type":"node","id":"html-css","name":"HTML/CSS基礎",...}`
+
+3. **SSEエンドポイント** (`backend/app/api/endpoints/analyze.py`):
+   - `GET /api/v1/analyze/skill-tree/stream?category=web`
+   - Server-Sent Events (SSE) 形式でリアルタイム送信
+
+### フロントエンド
+
+4. **APIクライアント** (`frontend/src/lib/api/skillTree.ts`):
+   - `streamSkillTree()`: EventSource でSSE受信
+   - コールバック: `onNode`, `onMetadata`, `onComplete`, `onError`
+
+## 使用方法
+
+### DashboardContainer.tsx での実装例
+
+```typescript
+import { streamSkillTree } from "@/lib/api/skillTree";
+import { useState, useEffect } from "react";
+
+export function DashboardContainer() {
+  const [skillTreeNodes, setSkillTreeNodes] = useState<TreeSkillNode[]>([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    if (!category) return;
+
+    setIsStreaming(true);
+    setSkillTreeNodes([]); // リセット
+
+    const eventSource = streamSkillTree(
+      category,
+      // ノード受信時: 段々追加
+      (node) => {
+        setSkillTreeNodes((prev) => [...prev, node]);
+      },
+      // メタデータ受信時: 進捗表示
+      (metadata) => {
+        setProgress(metadata.progress_percentage);
+      },
+      // 完了時
+      () => {
+        setIsStreaming(false);
+        console.log("スキルツリー生成完了!");
+      },
+      // エラー時
+      (error) => {
+        setIsStreaming(false);
+        setError(error.message);
+      }
+    );
+
+    // クリーンアップ: カテゴリ変更時にストリーミング停止
+    return () => {
+      eventSource.close();
+    };
+  }, [category]);
+
+  return (
+    <div>
+      {isStreaming && (
+        <div className="loading">
+          スキルツリー生成中... {progress.toFixed(0)}%
+        </div>
+      )}
+      <SkillTreeCanvas nodes={skillTreeNodes} />
+    </div>
+  );
+}
+```
+
+## テスト方法
+
+### バックエンドのみテスト
+
+```bash
+cd backend
+poetry run uvicorn app.main:app --reload
+```
+
+ブラウザで開く:
+
+```
+http://localhost:8000/api/v1/analyze/skill-tree/stream?category=web
+```
+
+SSE形式でノードが段々表示されます:
+
+```
+data: {"type":"node","id":"html-css","name":"HTML/CSS基礎",...}
+
+data: {"type":"node","id":"javascript","name":"JavaScript基礎",...}
+
+data: {"type":"metadata","total_nodes":15,...}
+
+data: {"type":"done"}
+```
+
+### フルスタックテスト
+
+1. バックエンド起動:
+
+```bash
+cd backend
+poetry run uvicorn app.main:app --reload
+```
+
+2. フロントエンド起動:
+
+```bash
+cd frontend
+npm run dev
+```
+
+3. ブラウザで `http://localhost:3000` にアクセス
+4. ログイン後、カテゴリを選択
+5. スキルツリーが段々できていくのを確認
+
+## パフォーマンス
+
+### 最適化内容
+
+1. **トークン削減**: 60.7% 削減
+   - ベースライン全体 (1,614 tokens) → Few-shot 2例 (282 tokens)
+2. **プロンプト簡潔化**: 要件5つ → 3つ
+3. **モデル変更**: gpt-4o-mini → gpt-3.5-turbo-0125 (2-3倍高速)
+
+4. **ノード数削減**: 20-30個 → 15-20個
+
+### 期待される生成時間
+
+- **従来**: 20-30秒（完全なJSONが返るまで待機）
+- **ストリーミング**: 最初のノードが2-3秒で表示開始
+  - ユーザー体感速度: **大幅改善**
+  - 完了まで: 10-15秒
+
+## 注意事項
+
+### 認証
+
+- GETエンドポイントですが、`Depends(get_current_user)` で認証必須
+- フロントエンド: `credentials: "include"` で Cookie 送信
+
+### エラーハンドリング
+
+- プロンプトが不適切で JSON Lines 形式でない場合はパースエラー
+- フォールバック: 従来の `/skill-tree` エンドポイントを使用
+
+### ブラウザ互換性
+
+- すべてのモダンブラウザで EventSource をサポート
+- IE11 非対応（polyfill 必要）
+
+## まとめ
+
+✅ **完了した実装**:
+
+- バックエンド: LLM ストリーミング + SSE エンドポイント
+- フロントエンド: EventSource クライアント
+
+⚠️ **フロントエンドの実装が必要**:
+
+- `DashboardContainer.tsx` に `streamSkillTree()` を統合
+- プログレッシブレンダリングのUI実装
+- ローディングインジケーター（進捗率表示）
+
+🚀 **次のステップ**:
+
+1. フロントエンド実装
+2. テスト・動作確認
+3. UX改善（アニメーション追加）