feat: TF-IDFバブルスコアAPI仕様を追加

[yudai-kdix]

概要

会話バブルUIで使うために、発話ごとのTF-IDFスコアを算出し、表示サイズに変換するAPIを追加しました。
1発話 = 1バブル を前提に、raw_score -> 正規化 -> bubble_size(px) を返します。

追加したもの

• 新規API: POST /analysis/tfidf/bubble-scores
• サービスロジック:
  • raw_score = 上位top_k語のTF-IDF合計
  • p10/p90 によるロバスト正規化
  • min_bubble_size ~ max_bubble_size への線形マッピング
• スキーマ:
  • Request/Responseモデル追加
  • バリデーション追加（空配列、空白発話、max_bubble_size <= min_bubble_size を422）
• テスト:
  • サービステスト追加
  • エンドポイントテスト追加
• ドキュメント:
  • Backend README更新
  • フロント向けAPI仕様更新（リクエスト/レスポンス/TS型）

API仕様（要点）

Request

• utterances: string[]（必須）
• top_k?: number（default: 3）
• window_size?: number（default: 30）
• min_bubble_size?: number（default: 28）
• max_bubble_size?: number（default: 72）

Response

• meta: algorithm, top_k, window_size, p10, p90, utterance_count など
• items[]:
  • index, text
  • raw_score
  • normalized_score（0..1）
  • bubble_size（px）
  • top_terms[]

アルゴリズム意図

• 突発的な高スコア語に引きずられすぎないよう、min-maxではなくp10/p90で正規化
• フロントは bubble_size をそのまま使えるため、描画実装がシンプル

テスト結果

• uv run pytest -q tests/test_text_analysis_service.py tests/test_analysis_endpoint.py
• 21 passed

互換性

• 既存APIへの破壊的変更なし（新規エンドポイント追加のみ）

レビュー観点

• p10/p90 正規化の妥当性（会話長やドメインでの安定性）
• top_k/window_size/min-max デフォルト値の妥当性
• フロントでのバブルサイズ運用（そのまま採用 or 追加平滑化）

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.