Spaces:

kina006097
/

kids-playground-ai-api

Sleeping

App Files Files Community

kids-playground-ai-api / docs /ai_api_development_guide.md

kina006097

docker環境の作成

3bf36b5 4 months ago

preview code

raw

history blame

63.9 kB

AI API 開発ガイド

このドキュメントは、Hugging Face SpacesとGradioを利用したAI APIの開発環境構築と、その後の開発プロセスに関する要点をまとめたものです。

1. 概要

1.1. 目的と機能概要

本プロジェクトの目的は、「親子で遊ぼうナビ」にAIを活用した口コミの自動要約機能を実装することです。

目的: ユーザーが多数の口コミを全て読んでも、施設の全体的な評判を素早く、かつ客観的に把握できるようにする。
ユーザー体験:
1. ユーザーは施設の詳細ページで「口コミをAI要約」ボタンをクリックします。
2. AIがその施設の全口コミを分析し、「ポジティブな点」と「注意が必要な点」などをまとめた中立的な要約文を生成します。
3. 生成された要約がモーダルウィンドウ等で表示され、ユーザーは短時間で施設の長所と短所を理解できます。

1.2. アーキテクチャ概要

この機能は、Djangoアプリケーションと、Hugging Face Spaces上で動作するGradio APIとの連携によって実現します。

開発環境: Dockerコンテナ内で開発・テストを行う。
バージョン管理: Gitでコードを管理する。
CI/CD: GitHub Actionsでテストとデプロイを自動化する。
本番環境: Hugging Face Spacesにデプロイし、APIを公開する。

1.3. 技術選定理由

Hugging Face Spaces:
- 選定理由: 無料枠が利用可能で、迅速なプロトタイピングに適しています。また、GitHubリポジトリと連携した自動デプロイ機能（CI/CD）が標準で提供されており、開発体験が非常にスムーズです。
- 代替案との比較: AWS LambdaやGoogle Cloud Functionsのようなサーバーレス環境も考えられますが、これらはコンテナイメージのサイズ制限が厳しく、大規模なAIモデルのデプロイには追加の工夫が必要です。Hugging Face Inference APIは最も手軽ですが、カスタムロジックの追加やUIの提供ができないため、今回はGradioと組み合わせられるSpacesを選択しました。
Gradio:
- 選定理由: 数行のコードでAIモデルのデモUIとAPIエンドポイントを同時に作成できるため、開発速度を大幅に向上させます。特に、動作確認用のUIが自動で生成される点は、開発初期段階での実験やデバッグにおいて大きな利点となります。

1.4. アーキテクチャ図

graph TD
    subgraph "ユーザー環境"
        Browser[ユーザーのブラウザ]
    end

    subgraph "Webサーバー (Django)"
        A[Django View] -- DBから口コミ取得 --> DB[(PostgreSQL)]
        A -- 要約リクエスト --> B{API Client}
        B -- HTTP POST --> C[AI API Gateway]
    end

    subgraph "AI推論環境 (Hugging Face Spaces)"
        C -- 認証・ルーティング --> D[Gradio App]
        D -- 推論実行 --> E[Summarization Model]
    end

    Browser -- "1. 要約ボタンクリック" --> A
    C -- "3. 要約結果 (JSON)" --> B
    A -- "4. 要約結果 (JSON)" --> Browser

    style DB fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#ccf,stroke:#333,stroke-width:2px

2. プロジェクト構造と開発環境

保守性・拡張性を高めるため、役割ごとにファイルを分割したディレクトリ構造を採用し、Dockerで開発環境を構築します。

2.1. 推奨ディレクトリ構造

kids-playground-ai-api/
│
├── .github/
│   └── workflows/
│       └── ci.yml
│
├── .gitignore
├── Dockerfile
├── pyproject.toml
├── requirements.txt
├── README.md
│
├── docs/
│   └── ai_api_development_guide.md # ★この開発ガイド
│
├── src/
│   └── ai_api/
│       ├── __init__.py
│       ├── main.py         # APIエントリーポイント (Gradio UI)
│       ├── core/
│       │   ├── __init__.py
│       │   └── inference.py  # AI推論ロジック
│       └── config.py       # 設定ファイル
│
└── tests/
    └── core/
        └── test_inference.py

2.2. 品質管理ツールの設定

pyproject.toml: プロジェクトルートに作成し、Ruff (フォーマッター/リンター), Mypy (型チェッカー), Pytest (テストフレームワーク) の設定を記述します。
.pre-commit-config.yaml: pre-commitを導入し、Gitコミット時に自動でコードチェックが走るように設定します。

2.3. 開発環境 (Docker)

requirements.txt: 必要なライブラリを記述します。
Dockerfile: ローカル開発環境の統一と効率化のために使用します。
- 注記: このDockerfileは、あくまでローカル開発用です。デプロイ先のHugging Face Spacesでは、Dockerfileは直接使われず、requirements.txtに基づいて環境が自動構築されます。
docker-compose.yml: DjangoサーバーとAI APIサーバーなど、複数のサービスを定義し、一括で起動・管理するために使用します。
Docker Desktopの活用: WindowsやMacのユーザーは、Docker Desktopを利用することで、コンテナの状態をGUIで視覚的に確認したり、起動・停止を容易に行うことができます。Linuxユーザーも利用可能です。コマンドライン操作に慣れていない開発者には、Docker Desktopの利用を推奨します。

2.3.1. ローカル環境の起動とアクセス

開発を開始するには、プロジェクトのルートディレクトリで以下のコマンドを実行します。Docker Desktopを利用している場合は、GUI上から docker-compose.yml を指定して起動することも可能です。


# -d フラグでバックグラウンドで起動
docker-compose up --build -d

これにより、各サービスがコンテナとして起動します。

Djangoアプリケーション: http://localhost:8000
AI API (Gradio): http://localhost:7860

2.4. デバッグ方法

コンテナ内で問題が発生した場合、以下のコマンドでコンテナの内部に入り、デバッグ作業を行うことができます。


# <service_name> は docker-compose.yml で定義したサービス名 (例: web, api)
docker-compose exec <service_name> bash

コンテナ内では、ログファイルの確認、Pythonのインタラクティブシェルを起動してのコード実行などが可能です。

3. モデル管理

モデル選定: まずは速度とリソースのバランスが良い軽量なモデル（例: llm-jp/t5-small-japanese-finetuned-sum）で開発を開始し、必要に応じて、より高品質なモデル（例: izumi-lab/t5-base-japanese-summary）への差し替えを検討します。
情報記録: config.pyには、モデル名だけでなく、モデルサイズ、ライセンス、推論速度の目安などの情報もコメントとして記録し、管理します。

4. 実装の役割分担

src/ai_api/config.py (設定担当): モデルやパラメータの情報を管理します。
src/ai_api/core/inference.py (AI推論担当): AIモデルのロードと推論のコアロジックを実装します。
src/ai_api/main.py (API受付担当): GradioのUIを定義し、サーバーを起動します。Dockerコンテナ内で外部にAPIを公開するため、iface.launch(server_name="0.0.0.0")のように起動オプションを指定します。

AI新機能開発におけるコーディング規約

AI新機能の開発においては、以下のコーディング規約と開発原則を遵守し、高品質で保守性の高いコードベースを目指します。

1. Pythonコーディング規約

PEP 8準拠: PythonコードはPEP 8スタイルガイドに厳密に準拠します。flake8 および black による自動フォーマットとリントを徹底し、コードの一貫性を保ちます。
型ヒントの活用: mypy を用いた型チェックを徹底し、コードの堅牢性、可読性、およびIDEによる補完の恩恵を最大化します。
Djangoとの連携: AI機能がDjangoアプリケーションと連携する場合、Djangoのモデル、ビュー、フォーム、URLパターンなどの既存の命名規則と構造に準拠し、シームレスな統合を図ります。
AI/MLコードの構造:
- データ処理（前処理、特徴量エンジニアリング）、モデル定義、学習ロジック、推論ロジックは明確に分離し、それぞれが単一の責務を持つモジュールとして設計します。
- 設定値やハイパーパラメータはコードから分離し、Djangoのsettings.py、または専用のYAML/JSONファイルなどで一元的に管理します。
ドキュメンテーション: 関数、クラス、複雑なアルゴリズム、およびAIモデルの設計意図には、適切なDocstringを記述し、コードの意図と振る舞いを明確にします。
エラーハンドリング: 予期せぬエラーや例外処理は、Djangoの標準的なエラーハンドリングやPythonの例外処理メカニズムに従い、適切にログを出力し、システムの安定性を確保します。
保守性と可読性: コードは常に保守性と可読性を最優先に設計・実装します。複雑なロジックは小さな関数に分割し、変数名や関数名は意図が明確に伝わるように命名します。
単一責務の原則 (SRP): クラスや関数は、変更の理由が一つであるように設計します。これにより、コードの凝集度を高め、テスト容易性と再利用性を向上させます。

2. テスト駆動開発 (TDD) とテストの考え方

t_wada氏のTDDスタイル: 開発は「Red → Green → Refactor」のTDDサイクルを厳守して進めます。
- Red: 最初に失敗するテストを記述し、必要な機能の振る舞いを定義します。
- Green: テストが成功する最小限のコードを実装します。
- Refactor: コードの品質を向上させ、重複を排除し、設計を改善します。
「動く仕様書」としてのテスト: テストコードは、単なる品質保証の手段ではなく、機能の振る舞いを明確に記述した「動く仕様書」として機能するように設計します。
- テストケース名（pytestのテスト関数名など）は、日本語で「〜という状況で、〜という振る舞いをすべき」というように、具体的なシナリオと期待される結果を記述します。
- テストは実装の詳細ではなく、機能の振る舞い（Behavior）に焦点を当てます。

5. テスト戦略

ユニットテスト: pytestを使い、inference.py内の純粋な関数（AIのコアロジック）をテストします。
インテグレーションテスト: ローカルで起動したGradioサーバーに対し、requestsライブラリで実際にAPIリクエストを送り、HTTPステータスコードやレスポンスの形式が期待通りであることを確認するテストも追加します。これにより、APIとしての正常性を保証します。

6. CI/CDとデプロイ戦略

6.1. 推奨ワークフロー

CI (GitHub Actions): プルリクエスト作成時やmainブランチへのプッシュ時に、GitHub Actionsを起動し、pytestによる自動テスト（ユニットテストとインテグレーションテスト）を実行します。
CD (Hugging Face Hub連携): テストが成功したコードがmainブランチにマージされたら、Hugging Face HubのGitHub連携機能がそれを検知し、自動的にSpacesにデプロイします。この方法が、Actionsから手動でgit pushするよりシンプルで確実なため推奨されます。

6.2. 設定

GitHub Actions: .github/workflows/ci.ymlにテストのワークフローを定義します。
Hugging Face Hub: Spacesの設定ページで、対象のGitHubリポジトリとブランチを指定して連携を有効化します。

7. セキュリティと利用制限

7.1. API認証

課題: Hugging Face Spacesで公開されるAPIは、デフォルトでは誰でもアクセス可能な状態になります。意図しない利用や攻撃を防ぐため、Djangoアプリケーションからのみリクエストを受け付けるように制御する必要があります。

対策: APIキーによる認証を導入します。

APIキーの生成: UUIDなどで推測困難な文字列をAPIキーとして生成します。
Secretsへの登録: 生成したキーを、DjangoとGradio APIの両方の環境変数（Hugging Face SpacesのSecrets）として登録します。
- AI_API_KEY: Gradio側でリクエストを検証するためのキー
- DJANGO_AI_API_KEY: Djangoがリクエスト時に送信するキー
認証の実装:
- Django側: APIを呼び出す際、HTTPヘッダー（例: Authorization: Bearer <APIキー>）にAPIキーを含めて送信します。
- Gradio側: FastAPIの依存性注入（Depends）などを利用して、リクエストヘッダーをチェックする認証関数を定義します。APIキーが一致しない場合は、HTTP 401または403エラーを返却します。

7.2. その他の対策

Abuse対策: 公開APIが悪用されるのを防ぐため、Gradioのqueue()メソッドを利用してリクエストを待ち行列に入れ、同時アクセス数を制限することを検討します。
免責事項: README.mdに、APIの利用は自己責任であること、生成される内容の正確性を保証しないこと、商用利用に関する制限などを明記しておきます。

8. 今後の開発プロセス

このドキュメントは、今後の調査や開発の進捗に応じて、継続的に更新・メンテナンスされます。

9. 設計

このセクションでは、機能実装の前に定義するべき、より詳細な設計について記録します。

9.1. APIインターフェース設計 (口コミ要約機能 v1)

DjangoとGradio APIがやり取りするデータ形式とルールを以下のように定めます。

9.1.1. 基本方針

通信プロトコル: HTTP/HTTPS
データ形式: JSON
基本構造: Gradioの標準API形式に準拠します。

9.1.2. リクエスト仕様 (Django → Gradio API)

エンドポイント: (SpaceのURL)/api/predict/
HTTPメソッド: POST

ボディ (JSON):

{
  "data": [
    "口コミ全文を結合した文字列..."
  ]
}

9.1.3. レスポンス仕様 (Gradio API → Django)

成功時 (HTTP 200 OK):

ボディ (JSON):

{
  "data": [
    "AIによって生成された要約文..."
  ],
  "duration": 3.5
}

失敗時 (HTTP 500 Internal Server Error):

ボディ (JSON):

{
  "error": "Gradio側で設定したエラーメッセージ"
}

9.2. UI/UX設計 (口コミ要約機能 v1)

ユーザーが機能を直感的に利用でき、システムの応答を快適に待てるように、以下の通りUI/UXを設計します。

9.2.1. 操作フロー

トリガー: ユーザーが施設詳細ページの「口コミをAI要約」ボタンをクリックします。
ローディング: ボタンが無効化され、「生成中です...」というテキストとスピナー（回転するアイコン）が表示されます。これにより、処理中であることがユーザーに明確に伝わります。
結果表示: 要約が完了すると、Bootstrapのモーダルウィンドウが画面中央に表示され、その中に生成された要約文が提示されます。
完了: ユーザーはモーダルを閉じて、元のページ閲覧を続けます。ローディング表示は元のボタン表示に戻ります。

9.2.2. エッジケースの対応

口コミが少ない場合:
- 条件: Django側で、対象施設の口コミが3件未満の場合。
- 処理: AIのAPIは呼び出さず、即座に「口コミが3件未満のため、要約できません。」というアラートメッセージを表示します。これにより、不要なAPIコールを防ぎ、ユーザーに状況を的確に伝えます。
APIエラー発生時:
- 条件: APIのタイムアウトやサーバーエラーが発生した場合。
- 処理: 「AIサーバーで問題が発生しました。時間をおいて再度お試しください。」といった内容をアラートまたはモーダルで表示します。

9.3. データ処理・ビジネスロジック設計 (v1)

AIの性能を最大限に引き出し、安定した運用を行うための内部ルールを以下のように設計します。

9.3.1. 入力データの前処理 (Django側)

口コミの結合: 複数の口コミは、それぞれを独立した段落としてAIに認識させるため、2つの改行文字 (\n\n) で区切って1つのテキストに結合します。
ノイズ除去: 絵文字やURLなど、要約のノイズとなりうる不要な文字列は、正規表現を用いて事前に除去します。

9.3.2. 要約実行の判断ロジック (Django側)

以下の条件を満たさない場合は、APIを呼び出さずにエラーとして処理します。

最小口コミ件数: 3件以上
最小総文字数: 全体の文字数が300文字以上

9.3.3. AIモデルの推論パラメータ (Gradio API側)

生成される要約文の品質を制御するため、以下の初期パラメータを設定します。これらの値は config.py で管理し、調整可能にします。

要約文の最小長 (min_length): 50
要約文の最大長 (max_length): 250
長さペナルティ (length_penalty): 2.0 (冗長な表現を抑制)

9.3.4. 大量データへの対応方針

初期実装: まずは全ての口コミを結合してAPIに送信します。モデルの最大入力長を超える場合は、truncation=True オプションにより自動的に末尾が切り捨てられます。
将来的な改善: 性能やコストに問題が見られた場合、「直近1年間の口コミのみを対象とする」などの制限を後から追加することを検討します。

9.4. エラーハンドリング設計 (v1)

予期せぬ事態が発生した場合でもシステムが安定して動作し、ユーザーに適切なフィードバックを返せるよう、以下の通りエラーハンドリングを設計します。

9.4.1. エラー発生源と対応方針

9.4.2. 実装のポイント

Django (司令塔) の役割:
- Djangoのビューは、Gradio APIとの通信部分を必ずtry...exceptブロックで囲み、タイムアウト（例: 30秒）を設定します。
- APIから返されたHTTPステータスコードを常にチェックし、200番台以外はエラーとして処理します。
- 発生したエラーは、必ずサーバーログに記録し、原因調査に役立てます。
- ユーザーには、技術的なエラー詳細（スタックトレース等）を直接見せず、「AIサーバーで問題が発生しました」のような抽象的で分かりやすいメッセージを返します。
Gradio API (専門家) の役割:
- AIの推論処理など、失敗する可能性のあるコードはtry...exceptブロックで囲みます。
- エラー発生時は、raise gr.Error("具体的なエラー原因")を呼び出し、APIの契約通りにエラー情報を返却します。

9.5. 詳細設計: AI推論コア (`core/inference.py`) (v1)

AI推論のコアロジックは、保守性とテスト容易性を高めるために、いくつかの設計原則とデザインパターンを適用して構造化します。

9.5.1. クラス設計と責務

Summarizer クラスの導入: AIの推論に関連する全てのロジックを、単一のSummarizerクラスに集約します。このクラスは「AIモデルを管理し、テキスト要約を実行する」という明確な責務を持ちます。

9.5.2. 適用するデザインパターン

ファサード (Facade) パターン: Summarizerクラスは、transformersライブラリの複雑な内部処理（モデルのロード、トークナイズ、推論、デコード等）をカプセル化（隠蔽）します。そして、summarize(text)という非常にシンプルなメソッドのみを外部に公開します。これにより、利用側（main.py）はAIの複雑な詳細を意識することなく、簡単かつ安全に要約機能を利用できます。
依存性の注入 (Dependency Injection) によるインスタンス管理: AIモデルのようなリソースを大量に消費するオブジェクトは、リクエストごとに生成するべきではありません。代わりに、アプリケーションの起動時に一度だけSummarizerのインスタンスを生成し、それを必要とする各コンポーネント（APIのエンドポイント関数など）に注入（引数として渡す）します。
- なぜシングルトンを避けるか: ご指摘の通り、グローバルな単一インスタンス（シングルトン）に依存する設計は、コンポーネント間の結合を強め、テストを困難にするためアンチパターンと見なされます。このアプローチは避けるべきです。
- 具体的な実現方法: アプリケーションのエントリーポイント（main.py）でSummarizerインスタンスを生成し、functools.partialなどを用いて、APIを処理する関数にそのインスタンスをあらかじめ渡しておくことで、グローバルな状態を持つことなくインスタンスの共有を実現します。これにより、テスト容易性と設計の柔軟性が大幅に向上します。
- 設定値の注入: このDIパターンは、Summarizerクラスが使用するモデル名や要約の長さといった設定値をコンストラクタを通じて外部のconfigモジュールから受け取るという、元々の依存性注入の考え方とも一致しています。

9.5.3. エラーハンドリング方針

Summarizerクラス内で発生したエラー（モデルのロード失敗、推論失敗など）は、クラス内部で適切に捕捉され、呼び出し元がハンドリングしやすいように、専用の例外（例: InferenceError）として再送出する設計とします。

9.6. 詳細設計: 設定管理 (`config.py`) (v1)

設定値をコードから分離し、安全かつ構造的に管理するため、以下の通り設計します。

9.6.1. 設計方針

データクラスの活用: Python標準のdataclassesを用い、関連する設定項目をグループ化した設定クラス（例: ModelConfig）を定義します。これにより、型安全性が保証され、コード補完も効くため開発効率が向上します。
不変性の確保: 作成したデータクラスは @dataclass(frozen=True) を指定し、イミュータブル（変更不可能）にします。これにより、アプリケーション実行中に意図せず設定が変更されてしまう危険な状態を防ぎます。
環境変数による設定の上書き: 将来的な拡張性（例: APIキーの管理）を見据え、設定値は環境変数から取得することを基本とします。開発環境では.envファイルを利用し、本番環境では実行環境（Hugging Face Spacesなど）のSecrets機能で設定を注入する運用を想定します。
- .env.example の提供: 開発者が環境変数を容易に設定できるよう、リポジトリには .env.example ファイルを含めます。実際の開発では、このファイルをコピーして .env を作成し、値を設定します。
```
# AI APIのモデル名を指定
AI_MODEL_NAME="llm-jp/t5-small-japanese-finetuned-sum"
```
- docker-compose.yml での読み込み: docker-compose.yml ファイルで env_file を指定することで、コンテナ起動時に .env ファイルの内容が環境変数として読み込まれます。
```
services:
  api:
    build: .
    env_file:
      - .env
```

9.6.2. 構造案

ModelConfig クラス:
- 責務: 使用するAIモデルに関する情報を一元管理します。
- 属性案: NAME (モデル名), REVISION (バージョン)
InferenceConfig クラス:
- 責務: AIの推論（要約生成）時のパラメータを一元管理します。
- 属性案: MIN_LENGTH, MAX_LENGTH, LENGTH_PENALTY, NUM_BEAMS

9.7. 詳細設計: Django側ビュー (`summary_views.py`) (v1)

Django側でAI APIを呼び出すビューは、責務を明確に分離し、堅牢なエラーハンドリングとロギングを組み込んだクラスとして設計します。

9.7.1. 設計方針

クラスベースビュー (CBV) の採用: Django標準のdjango.views.Viewを継承したクラスとして実装します。これにより、将来的な機能拡張（例: POSTメソッドの追加）にも柔軟に対応できます。
責務の分離: 1つのメソッドに全てのロジックを記述するのではなく、「口コミの取得」「バリデーション」「API呼び出し」といった関心事ごとにプライベートメソッド（例: _call_api）へ処理を分割し、メインのgetメソッドの見通しを良くします。
集中的なエラーハンドリング: メインのgetメソッドにtry...exceptブロックを設け、各処理で発生しうる例外（DB関連、通信関連など）を集中的に捕捉し、適切なJsonResponseを返すようにします。
詳細なロギング: Pythonのloggingモジュールを活用し、API呼び出しの成否、発生したエラー、ビジネスロジックの判断などをログに出力します。特にエラー発生時には、スタックトレースを含めて記録することで、迅速な原因究明を可能にします。

9.7.2. クラス・メソッド構成案

SummarizeReviewsView(View)
- get(self, request, playground_id):
  - HTTP GETリクエストを処理するメインメソッド。
  - 以下の処理フローを制御する。
    1. _get_reviewsを呼び出し、口コミデータを取得。
    2. _validate_reviewsを呼び出し、ビジネスルール（件数、文字数）を検証。
    3. 口コミテキストを前処理（結合、ノイズ除去）。
    4. _call_summary_apiを呼び出し、外部APIと通信。
    5. 成功レスポンスまたはエラーレスポンスをJsonResponseとして返す。
- _get_reviews(self, playground_id):
  - playground_idに対応する口コミをデータベースから取得する責務を持つ。
- _validate_reviews(self, reviews):
  - 取得した口コミが要約実行の条件を満たすか検証する責務を持つ。
- _call_summary_api(self, text):
  - requestsライブラリを使い、Gradio APIとの通信を行う責務を持つ。タイムアウト設定もここで行う。

9.7.3. 設定値の管理

Gradio APIのエンドポイントURLやタイムアウト秒数といった設定値は、settings.pyに記述し、ビューからはdjango.conf.settingsを通じて参照します。これにより、設定の一元管理を実現します。

9.8. 詳細設計: テスト戦略の具体化 (v1)

アプリケーションの品質と信頼性を保証するため、以下の通り多層的なテスト戦略を設計します。

9.8.1. テストの種類と目的

ユニットテスト (Unit Tests):
- 目的: 個々の部品（クラス、メソッド）が単体で正しく動作することを検証します。高速に実行できるため、開発中の頻繁な確認に適しています。
- 対象: core/inference.py の Summarizer クラスなど、ビジネスロジックの中核を担う部分。
インテグレーションテスト (Integration Tests):
- 目的: Gradio APIのエンドポイントが、APIの契約通りに正しくリクエストを処理し、レスポンスを返すことを検証します。コンポーネント間の連携を確認します。
- 対象: ローカルで起動したGradioアプリケーションの /api/predict/ エンドポイント。

9.8.2. テストケースの計画

ユニットテスト (tests/core/test_inference.py):
- 正常系: 通常のテキストが入力された場合に、期待される形式（文字列）の要約が返ることを確認する。
- 異常系: 空文字列や不正なデータ型が入力された場合に、設計通りValueError等の例外が発生することを確認する。
インテグレーションテスト (tests/test_api.py):
- 正常系: APIに有効なリクエストを送信し、HTTPステータスコード200と、設計通りのJSONレスポンスが返ることを確認する。
- 異常系: 不正なリクエストを送信した場合に、適切なHTTPエラーステータスコード（例: 4xx）が返ることを確認する。

9.8.3. テストの効率化

フィクスチャの活用 (@pytest.fixture): AIモデルのロードは時間がかかるため、Summarizerクラスのインスタンス生成をフィクスチャとして定義します。scope="session"を指定することで、全テスト実行中にモデルのロードが一度だけで済み、テスト時間を大幅に短縮します。
パラメータ化の活用 (@pytest.mark.parametrize): 複数の異なる入力値と期待される結果の組み合わせを、一つのテスト関数で効率的に検証するために使用します。

9.9. 詳細設計: Django-AI連携 (v1)

DjangoアプリケーションとAIアプリケーション（Gradio）がどのように連携して機能を実現するかの具体的な設計を以下に示します。

9.9.1. 連携シーケンス

正常系のシーケンス

全体の処理の流れは以下の通りです。

sequenceDiagram
    participant Browser as ユーザー(ブラウザ)
    participant Django as Djangoサーバー
    participant Gradio as AI API (Gradio)

    Browser->>+Django: GET /summarize/playground/{id}/
    Django->>Django: 1. 口コミ取得・検証
    alt 口コミが3件未満など条件を満たさない
        Django-->>-Browser: JSON (エラー)
    end
    Django->>+Gradio: POST /api/predict/ (口コミテキスト)
    Gradio->>Gradio: 2. AIモデルで要約実行
    Gradio-->>-Django: JSON (要約結果)
    Django-->>-Browser: JSON (要約結果)

異常系（AI APIエラー）のシーケンス

AI API側でエラーが発生した場合の処理の流れです。

sequenceDiagram
    participant Browser as ユーザー(ブラウザ)
    participant Django as Djangoサーバー
    participant Gradio as AI API (Gradio)

    Browser->>+Django: GET /summarize/playground/{id}/
    Django->>+Gradio: POST /api/predict/ (口コミテキスト)
    Gradio->>Gradio: AIモデルの処理でエラー発生
    Gradio-->>-Django: HTTP 500 (エラー情報)
    Django->>Django: エラーをログに記録
    Django-->>-Browser: JSON (ユーザー向けエラーメッセージ)

9.9.2. 各コンポーネントの責務と実装

1. Django側 (myapp/views/summary_views.py)

クラス: SummarizeReviewsView(View)
メソッド: get(self, request, playground_id)
- 責務: リクエストを受け付け、AI APIとの通信を制御する司令塔。
- 処理フロー:
  1. DBから口コミを取得し、件数や文字数を検証する。
  2. _call_summary_api メソッドを呼び出し、AI APIにリクエストを送信する。
  3. 返ってきた結果（成功またはエラー）を整形し、JsonResponseとしてフロントエンドに返す。
メソッド: _call_summary_api(self, text)
- 責務: requestsライブラリを用いて、AI APIとのHTTP通信を実際に担当する。
- 実装詳細:
  - settings.AI_SUMMARY_API_URL からAPIのエンドポイントURLを取得する。
  - requests.post() を使い、タイムアウトを設定してPOSTリクエストを送信する。
  - 通信エラーや、APIが返すエラーステータスコードをtry...exceptで捕捉し、適切に処理する。
  - 成功時はレスポンスのJSONをパースし、要約テキストを返す。

2. AIアプリケーション側 (src/ai_api/)

ファイル: main.py (エントリーポイント)
- 責務: Gradioアプリケーションを起動し、HTTPリクエストを受け付ける窓口。
- 実装詳細:
  1. 起動時に一度だけ、core.inference.Summarizer クラスのインスタンスを生成する。
  2. functools.partial を使い、API処理関数に Summarizer のインスタンスを注入（バインド）する。
  3. gradio.Interface を定義し、リクエストを処理する関数として上記でバインドした関数を渡す。これにより、Gradioは /api/predict/ というエンドポイントを自動的に作成する。
ファイル: core/inference.py
- クラス: Summarizer
- メソッド: summarize(self, text)
  - 責務: AIモデルの管理と、実際の要約処理というコアロジックに責任を持つ。
  - 実装詳細: transformersライブラリを使い、テキストのトークナイズ、モデルによる推論、結果のデコードを行う。

9.9.3. 疎結合の担保（独立した開発・テスト）

この設計が、いかにして疎結合（Loose Coupling）を担保しているかを以下に示します。

通信の抽象化:
- DjangoとAIアプリは、HTTPとJSONという標準化された技術でのみ通信します。
- DjangoはAIアプリがGradioで実装されていることを知る必要はなく、逆もまた然りです。知っているのは「どのURLに、どんなJSONを送れば、どんなJSONが返ってくるか」というAPI契約だけです。
独立した実行とテスト:
- AIアプリケーション:
  - src/ai_api/ ディレクトリは、それ自体が完結したPythonプロジェクトです。
  - python src/ai_api/main.py を実行すれば、Djangoとは無関係に単体で起動できます。
  - 起動したAIアプリに対し、ブラウザでUIを操作したり、curlコマンドでAPIを直接叩いたりすることで、単体での動作テストが可能です。
- Djangoアプリケーション:
  - SummarizeReviewsView のテストを書く際、unittest.mock.patch を使って _call_summary_api メソッドをモック（偽のオブジェクトに差し替え）します。
  - これにより、AI APIへ実際にネットワーク通信を発生させることなく、「APIが成功を返した場合」「タイムアウトした場合」「エラーを返した場合」など、あらゆる状況を想定したビューのロジックを高速にテストできます。

この設計により、両アプリケーションは互いに依存することなく、独立して開発,テスト,デプロイを進めることが可能になります。

9.10. pyproject.toml の詳細設計

ここでのゴールは、プロジェクトで利用する品質管理ツール（Ruff, Mypy, Pytest）の具体的な動作ルールをpyproject.tomlファイルに定義し、誰が開発しても、またCI/CDで実行されても、常に一貫した基準でコードの品質がチェックされるようにすることです。

1. Ruff (リンター & フォーマッター)

高速なリンター兼フォーマッターであるRuffの設定を定義します。

設計方針

Pythonの標準的なフォーマッターであるblackの規約に準拠させます。
必須のルールに加え、潜在的なバグを発見するルールや、コードをよりモダンな記法に自動修正するルールを積極的に有効化し、コード品質を高く保ちます。

設定案 (`[tool.ruff]`セクション)

line-length = 88: 1行の最大長をblackに合わせて88文字に設定。
select = ["E", "W", "F", "I", "B", "UP"]:
- E, W, F: pycodestyleとPyflakesの基本的なエラー・警告（必須）。
- I: isort互換のimport文の自動ソート（必須）。
- B: flake8-bugbearの、バグの温床となりやすいコードパターンを検出するルール。
- UP: pyupgradeの、古いPython記法を新しい記法へ自動的にアップグレードするルール。
target-version = "py312": Python 3.12の文法を正しく解釈するように指定。

設定案 (`[tool.ruff.format]`セクション)

quote-style = "double": コード内での引用符をダブルクォート（"）に統一。

2. Mypy (静的型チェッカー)

型ヒントの正しさを保証するMypyの設定を、厳格かつ実用的に定義します。

設計方針

型ヒントの記述をプロジェクト内で徹底させ、型の安全性を高めます。
一方で、型情報を持たない外部ライブラリに起因するエラーは無視し、実用性を損なわないようにします。

設定案 (`[tool.mypy]`セクション)

python_version = "3.12": 型チェックの対象となるPythonバージョンを指定。
ignore_missing_imports = true: 型情報（スタブ）が提供されていないライブラリをインポートした際のエラーを無視します。これは多くのプロジェクトで必須の設定です。
disallow_untyped_defs = true: 型ヒントが書かれていない関数定義をエラーとします。これにより、プロジェクト全体で型ヒントの記述を強制し、コードの可読性と信頼性を飛躍的に向上させます。
warn_return_any = true: 関数の返り値の型が、曖昧なAny型になっている場合に警告を出します。より具体的な型定義を促し、バグを未然に防ぎます。

3. Pytest (テストフレームワーク)

テストの実行方法に関する設定を定義します。

設計方針

テストの実行に関する基本的なルールを定め、誰が実行しても同じ結果が得られるようにします。

設定案 (`[tool.pytest.ini_options]`セクション)

testpaths = ["tests"]: テストファイルが格納されているディレクトリをtestsに限定します。
addopts = "-ra --strict-markers": テスト実行時に、詳細なサマリーを表示し(-ra)、未定義のテストマーカーの使用を禁止する(--strict-markers)ことで、テストの管理を厳格にします。
minversion = "7.0": プロジェクトが要求するPytestの最低バージョンを7.0と定め、古いバージョンでの意図しない動作を防ぎます。

10. さらなる検討事項 (Further Considerations)

このセクションでは、v1開発のスコープ外としつつも、本機能の品質と価値を継続的に向上させるために、将来的に調査・実装すべき項目を計画としてまとめる。

10.1. AIモデルの評価と改善サイクル (MLOps)

目的: 感覚的な判断を排し、データに基づいてAIの品質を客観的に評価・改善する仕組みを構築する。

10.2. 堅牢性とスケーラビリティの向上

目的: 大量アクセスや予期せぬ入力に対しても、安定して高速なレスポンスを返し、コストを最適化する。

| 項目 | 調査計画 | 成果物 | | : | : | : | | 1. 高度な入力分割戦略 | - 長大な口コミ群に対応するため、テキストを意味のある単位（チャンク）で分割し、それぞれを要約してから最終的に統合する「Map-Reduce」的なアプローチを調査・実装する。
- LangChainなどのライブラリが提供する要約チェーンの活用を検討する。 | - チャンク要約の実装PoC。
- 長文入力に対するエラー率や品質の改善レポート。 | | 2. 非同期API呼び出し | - DjangoからAI APIを呼び出す処理を非同期化し、Webサーバーのワーカースレッドを長時間ブロックするのを防ぐ。
- CeleryやDramatiqといった非同期タスクキューを導入し、要約処理をバックグラウンドジョブとして実行するアーキテクチャを設計する。
- フロントエンド側は、ポーリングやWebSocketを利用して、ジョブの完了を検知し結果を表示する方式に変更する。 | - 非同期処理アーキテクチャの設計図。
- Celery導入のPoCと、応答性能の改善効果測定レポート。 | | 3. キャッシュ戦略の導入 | - Djangoのキャッシュフレームワーク（Redis, Memcachedなど）の利用方法を調査する。
- 「施設ID」をキーとして要約結果をキャッシュするアーキテクチャを設計する。
- キャッシュの有効期間（TTL）をどの程度に設定すべきか、方針を決定する。 | - キャッシュシステムのアーキテクチャ図。
- settings.pyへの設定例と、ビューでの利用コード例。 | | 4. コスト・パフォーマンス試算 | - Hugging Face Spacesの無料枠・有料プラン（ハードウェア性能）と料金体系を調査する。
- 1リクエストあたりの平均処理時間とメモリ使用量を計測し、無料枠の範囲内で何リクエストまで処理可能か試算する。
- 想定されるアクセス数に基づき、月間の運用コストと、スケールアップが必要になる条件を定義する。 | - コストとパフォーマンスの試算レポート。
- スケールアップ計画。 |

10.3. 運用と監視

目的: 本番環境におけるAPIの稼働状況を可視化し、問題発生時に迅速な検知と対応を可能にする。

| 項目 | 調査計画 | 成果物 | | : | : | : | | 1. ログの統合管理 | - DjangoとGradio APIの両方で、リクエストIDを共有する仕組みを導入する。
- 構造化ログ（JSON形式）にリクエストIDを含めることで、Datadogなどの外部サービスで、ユーザーリクエストからAI API呼び出しまでの一連のログを横断的に追跡できるようにする。 | - ログフォーマットの統一仕様。
- 構造化ロギングの実装例。 | | 2. パフォーマンス監視とエラーレポート | - Hugging Face Spacesが標準で提供する分析機能（Analytics）で取得できるメトリクスを確認する。
- Sentryなどのエラーレポートツールを導入し、アプリケーション例外を自動で収集・通知する仕組みを構築する。
- 特に監視すべき重要指標（KPI）を定義する（例: エラー率、95パーセンタイル応答時間、要約品質スコア）。 | - 監視ツールの選定と比較。
- 監視KPIリストとその閾値の定義。
- Sentry導入手順書。 |

10.4. ユーザー体験の強化

目的: AIの機能をよりユーザーフレンドリーで、多くの人が利用しやすい形で提供する。

11. 実装タスクリスト（詳細版）

このセクションでは、TDD（テスト駆動開発）のサイクルに基づき、実装の詳細な手順を階層的に定義します。

担当: AI - このアイコンが付いているタスクは、AI（Gemini）がコード生成やファイル作成を直接実行できます。
担当: 人間 - このアイコンが付いているタスクは、開発者による手動での実行、判断、または承認が必要です。

フェーズ0: プロジェクトの初期化

目的: 新しいプロジェクトの作業を開始するための準備を行う。

中タスク0.1: プロジェクトルートディレクトリの作成
- 担当: 人間
- 内容: 作業を開始するディレクトリに、プロジェクトのルートとなる kids-playground-ai-api ディレクトリを作成し、その中に移動してください。
- 指示: 以下のコマンドを実行してください。
```
mkdir kids-playground-ai-api
cd kids-playground-ai-api
```


- [x] **中タスク0.2: Git管理の開始と初期コミット**
    - **担当:** 人間
    - **内容:** プロジェクトのGit管理を開始し、`.gitignore`を設定して不要なファイルを管理対象から除外し、初期コミットを行います。
    - **指示:** プロジェクトルートディレクトリで以下のコマンドを実行してください。
    ```bash
git init
# .gitignore ファイルを作成または編集し、適切な内容を記述
# 例:
# echo "__pycache__\nvenv/\.env" > .gitignore
git add .
git commit -m "Initial commit"

中タスク0.3: GitHubリポジトリの作成と連携
- 担当: 人間
- 内容: GitHub上に新しいリポジトリを作成し、ローカルリポジトリと連携させます。
- 指示:
  1. GitHubにログインし、新しいリポジトリを作成します（リポジトリ名は kids-playground-ai-api など）。READMEや.gitignore、ライセンスの追加はスキップしてください。
  2. 作成されたリポジトリページに表示される指示に従い、ローカルリポジトリをリモートにプッシュします。

git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPOSITORY_NAME.git git branch -M main git push -u origin main


- [x] **中タスク0.4: Hugging Faceアカウントの登録とSpacesの準備**
    - **担当:** 人間
    - **内容:** Hugging Faceアカウントを登録し、AIモデルをデプロイするためのHugging Face Spaceを準備します。
    - **指示:**
        1. Hugging Faceのウェブサイト (huggingface.co) にアクセスし、アカウントを登録します。
        2. ログイン後、「Spaces」セクションに移動し、「Create new Space」をクリックします。
        3. Space名、ライセンス、SDK（Gradioを選択）、公開/非公開設定などを適切に設定し、Spaceを作成します。
        4. 作成後、Spaceの設定ページで「Link to a Git repository」オプションを探し、先ほど作成したGitHubリポジトリと連携させます。これにより、GitHubへのプッシュで自動デプロイが可能になります。


### フェーズ1: 開発環境のセットアップ

**目的:** コーディングを開始する前に、品質を担保し、開発を効率化するための基盤を構築する。

- [x] **中タスク1.0: ドキュメントの配置**
    - **担当:** AI
    - **内容:** この開発ガイド (`ai_api_development_guide.md`) を `docs/` ディレクトリに配置します。
    - **指示:** 以下のコマンドを実行してください。
    ```bash
cp /path/to/current/ai_api_development_guide.md docs/ai_api_development_guide.md

*   *注: `/path/to/current/ai_api_development_guide.md` は、このドキュメントが現在置かれている絶対パスに置き換える必要があります。*

中タスク1.1: プロジェクト構造の初期セットアップ
- 担当: AI
- 内容: 以下のディレクトリとファイルをプロジェクトルートに作成します。
  - ディレクトリ: src/ai_api/core, tests/core, docs, .github/workflows
  - ファイル: .gitignore, Dockerfile, pyproject.toml, requirements.txt, README.md, .github/workflows/ci.yml (空ファイルとして)
- 指示: 以下のコマンドを実行して、プロジェクトの初期ディレクトリとファイルを準備してください。
```
mkdir -p src/ai_api/core tests/core docs .github/workflows
touch .gitignore Dockerfile pyproject.toml requirements.txt README.md .github/workflows/ci.yml
```


- [x] **中タスク1.2: 品質管理ツールの設定**
    - [x] **小タスク1.2.1: `pyproject.toml` の設定**
        - **担当:** AI
        - **内容:** セクション `9.10` の設計に基づき、Ruff, Mypy, Pytestの設定を記述した `pyproject.toml` ファイルを更新します。
        - **指示:** `/home/jam/kidsPlayGround/pyproject.toml` を更新してください。

- [x] **中タスク1.3: 依存関係の管理**
    - [x] **小タスク1.3.1: `requirements.txt` の設定**
        - **担当:** AI
        - **内容:** ライブラリを記述した `requirements.txt` を更新します。
        - **指示:**  `/home/jam/kidsPlayGround/requirements.txt` を更新してください。
        ```
# AI App
gradio
transformers
torch

# Testing
pytest
requests

# Linting & Formatting
ruff
mypy
          ```
    - [x] **小タスク1.3.2: Docker開発環境の構築と起動**
        - **担当:** 人間
        - **内容:** Docker Desktopを利用して、プロジェクトのDocker開発環境を構築し、起動します。これにより、必要な依存関係がコンテナ内に自動的にインストールされます。
        - **指示:**
            1. Docker Desktopがインストールされ、起動していることを確認してください。
            2. プロジェクトのルートディレクトリで、以下のコマンドを実行してDockerコンテナをビルドし、バックグラウンドで起動します。
            ```bash
docker-compose up --build -d
            ```
            3. コンテナが正常に起動したら、Djangoアプリケーションは `http://localhost:8000`、AI API (Gradio) は `http://localhost:7860` でアクセス可能になります。

### フェーズ2: AIアプリケーションのTDD (コアロジック → API)

**目的:** クリーンアーキテクチャの原則に従い、内側のビジネスロジックから外側のAPIへと実装を進める。

- [ ] **中タスク2.1: AIコアロジック `Summarizer` の実装**
    - [ ] **小タスク2.1.1 (RED):** `Summarizer`クラスのテスト作成
        - **担当:** AI
        - **内容:** `tests/core/test_inference.py` を作成し、「`from src.ai_api.core.inference import Summarizer` が成功すること」をテストします。このテストは、ファイルやクラスが存在しないため失敗します。
    - [ ] **小タスク2.1.2 (GREEN):** `Summarizer`クラスの骨格作成
        - **担当:** AI
        - **内容:** `src/ai_api/core/inference.py` と、空の`Summarizer`クラスを作成し、テストをパスさせます。
    - [ ] **小タスク2.1.3 (REFACTOR):** リファクタリング
        - **担当:** AI
        - **内容:** この時点では特になし。コミットの区切りとします。

- [ ] **中タスク2.2: AI設定クラス `Config` の実装と注入**
    - [ ] **小タスク2.2.1 (RED):** `Summarizer`が設定オブジェクトを受け取るテスト作成
        - **担当:** AI
        - **内容:** `tests/core/test_inference.py`に追記します。
        - **内容:** `Summarizer`がコンストラクタで設定オブジェクト（モデル名など）を受け取ることを期待するテストを`tests/core/test_inference.py`に追記します。
    - [ ] **小タスク2.2.2 (GREEN):** 設定クラスの作成とコンストラクタ修正
        - **担当:** AI
        - **内容:** `src/ai_api/config.py`に設計通りの設定クラス（`ModelConfig`など）を作成します。`Summarizer`の`__init__`を修正し、設定オブジェクトを受け取るようにします。
    - [ ] **小タスク2.2.3 (REFACTOR):** リファクタリング
        - **担当:** AI
        - **内容:** コードの可読性を向上させます。 **この時点で、AIモデルを切り替えるための基本的な仕組み（設定値を外部から与える）が完成します。**

- [ ] **中タスク2.3: 要約機能 `summarize` メソッドの実装**
    - [ ] **小タスク2.3.1 (RED):** `summarize`メソッドのユニットテスト作成
        - **担当:** AI
        - **内容:** `unittest.mock.patch`を使い、`transformers.pipeline`をモック（偽物に差し替え）します。「`summarize`メソッドを呼ぶと、内部で`pipeline`が特定の引数で呼ばれ、モックの返り値がそのまま返されること」をテストします。これにより、重いモデルをロードせずにロジックだけを高速にテストできます。
    - [ ] **小タスク2.3.2 (GREEN):** `summarize`メソッドの実装
        - **担当:** AI
        - **内容:** `Summarizer`クラスに`summarize`メソッドを実装し、内部で`transformers.pipeline`を呼び出して要約を実行するようにします。
    - [ ] **小タスク2.3.3 (REFACTOR):** リファクタリング
        - **担当:** AI
        - **内容:** エラーハンドリングなどを追加し、コードを整理します。

- [ ] **中タスク2.4: APIエントリーポイント `main.py` の実装**
    - [ ] **小タスク2.4.1 (RED):** APIのインテグレーションテスト作成
        - **担当:** AI
        - **内容:** `tests/test_api.py`を作成します。テスト内でGradioアプリを別スレッドで起動し、`requests.post`で`/api/predict/`にリクエストを送信して、期待した応答が得られない（サーバーがないため）ことを確認します。
    - [ ] **小タスク2.4.2 (GREEN):** `main.py`の実装
        - **担当:** AI
        - **内容:** `src/ai_api/main.py`を作成します。`Summarizer`と設定クラスをインスタンス化し、DI（依存性の注入）してGradioの`Interface`を定義・起動します。
    - [ ] **小タスク2.4.3 (REFACTOR):** リファクタリング
        - **担当:** AI
        - **内容:** コードを整理します。
    - [ ] **小タスク2.4.4: 手動での動作確認**
        - **担当:** 人間
        - **内容:** `python src/ai_api/main.py` を実行し、ブラウザで表示されるGradioのUIにテキストを入力して、要約機能が単体で正しく動作することを確認します。

### フェーズ3: Djangoへの組み込み

**目的:** 独立して動作するAIアプリケーションを、DjangoからAPI経由で安全に呼び出す。

- [ ] **中タスク3.1: Django側のAPIクライアント実装**
    - [ ] **小タスク3.1.1 (RED):** APIクライアントのテスト作成
        - **担当:** AI
        - **内容:** `myapp/tests/test_clients.py`を作成します。`requests.post`がモック化されている状態でAPIクライアント関数を呼び出し、成功時・タイムアウト時・サーバーエラー時の挙動をテストします。
    - [ ] **小タスク3.1.2 (GREEN):** APIクライアントの実装
        - **担当:** AI
        - **内容:** `myapp/clients/ai_summary_client.py`を作成し、`requests`を使って外部APIを呼び出す関数を実装します。
    - [ ] **小タスク3.1.3 (REFACTOR):** リファクタリング
        - **担当:** AI
        - **内容:** 設定を`settings.py`から読み込むようにするなど、コードを整理します。

- [ ] **中タスク3.2: Django Viewの実装**
    - [ ] **小タスク3.2.1 (RED):** ViewのURLテスト作成
        - **担当:** AI
        - **内容:** `myapp/tests/test_views.py`に、`/summarize/playground/{id}/`へのGETリクエストが404を返すテストを書きます。
    - [ ] **小タスク3.2.2 (GREEN):** URLとViewの骨格作成
        - **担当:** AI
        - **内容:** `myapp/urls.py`と`myapp/views/summary_views.py`を作成・編集し、テストをパスさせます。
    - [ ] **小タスク3.2.3 (RED):** Viewとクライアントの連携テスト作成
        - **担当:** AI
        - **内容:** `unittest.mock.patch`でAPIクライアントをモック化し、「Viewを呼び出すと、内部でAPIクライアントが特定の引数で呼ばれること」をテストします。
    - [ ] **小タスク3.2.4 (GREEN):** Viewロジックの実装
        - **担当:** AI
        - **内容:** View内で口コミの取得・検証ロジック、およびAPIクライアントの呼び出しを実装します。
    - [ ] **小タスク3.2.5 (REFACTOR):** リファクタリング
        - **担当:** AI
        - **内容:** コードを整理します。

- [ ] **中タスク3.3: 統合テスト**
    - [ ] **小タスク3.3.1: 手動での最終確認**
        - **担当:** 人間
        - **内容:** DjangoサーバーとAIアプリ（Gradio）を両方ローカルで起動し、ブラウザから最初の要約ボタンをクリックして、全体の流れが正しく動作するかを確認します。

AI API 開発ガイド

1. 概要

1.1. 目的と機能概要

1.2. アーキテクチャ概要

1.3. 技術選定理由

1.4. アーキテクチャ図

2. プロジェクト構造と開発環境

2.1. 推奨ディレクトリ構造

2.2. 品質管理ツールの設定

2.3. 開発環境 (Docker)

2.3.1. ローカル環境の起動とアクセス

2.4. デバッグ方法

3. モデル管理

4. 実装の役割分担

AI新機能開発におけるコーディング規約

1. Pythonコーディング規約

2. テスト駆動開発 (TDD) とテストの考え方

5. テスト戦略

6. CI/CDとデプロイ戦略

6.1. 推奨ワークフロー

6.2. 設定

7. セキュリティと利用制限

7.1. API認証

7.2. その他の対策

8. 今後の開発プロセス

9. 設計

9.1. APIインターフェース設計 (口コミ要約機能 v1)

9.1.1. 基本方針

9.1.2. リクエスト仕様 (Django → Gradio API)

9.1.3. レスポンス仕様 (Gradio API → Django)

9.2. UI/UX設計 (口コミ要約機能 v1)

9.2.1. 操作フロー

9.2.2. エッジケースの対応

9.3. データ処理・ビジネスロジック設計 (v1)

9.3.1. 入力データの前処理 (Django側)

9.3.2. 要約実行の判断ロジック (Django側)

9.3.3. AIモデルの推論パラメータ (Gradio API側)

9.3.4. 大量データへの対応方針

9.4. エラーハンドリング設計 (v1)

9.4.1. エラー発生源と対応方針

9.4.2. 実装のポイント

9.5. 詳細設計: AI推論コア (core/inference.py) (v1)

9.5.1. クラス設計と責務

9.5.2. 適用するデザインパターン

9.5.3. エラーハンドリング方針

9.6. 詳細設計: 設定管理 (config.py) (v1)

9.6.1. 設計方針

9.6.2. 構造案

9.7. 詳細設計: Django側ビュー (summary_views.py) (v1)

9.7.1. 設計方針

9.7.2. クラス・メソッド構成案

9.7.3. 設定値の管理

9.8. 詳細設計: テスト戦略の具体化 (v1)

9.8.1. テストの種類と目的

9.8.2. テストケースの計画

9.8.3. テストの効率化

9.9. 詳細設計: Django-AI連携 (v1)

9.9.1. 連携シーケンス

正常系のシーケンス

異常系（AI APIエラー）のシーケンス

9.9.2. 各コンポーネントの責務と実装

9.9.3. 疎結合の担保（独立した開発・テスト）

9.10. pyproject.toml の詳細設計

1. Ruff (リンター & フォーマッター)

設計方針

設定案 ([tool.ruff]セクション)

設定案 ([tool.ruff.format]セクション)

2. Mypy (静的型チェッカー)

設計方針

設定案 ([tool.mypy]セクション)

3. Pytest (テストフレームワーク)

設計方針

設定案 ([tool.pytest.ini_options]セクション)

10. さらなる検討事項 (Further Considerations)

10.1. AIモデルの評価と改善サイクル (MLOps)

10.2. 堅牢性とスケーラビリティの向上

10.3. 運用と監視

10.4. ユーザー体験の強化

11. 実装タスクリスト（詳細版）

フェーズ0: プロジェクトの初期化

9.5. 詳細設計: AI推論コア (`core/inference.py`) (v1)

9.6. 詳細設計: 設定管理 (`config.py`) (v1)

9.7. 詳細設計: Django側ビュー (`summary_views.py`) (v1)

設定案 (`[tool.ruff]`セクション)

設定案 (`[tool.ruff.format]`セクション)

設定案 (`[tool.mypy]`セクション)

設定案 (`[tool.pytest.ini_options]`セクション)