ドキュメントの更新

README.md

@@ -9,35 +9,37 @@ app_file: app.py
 pinned: false
 ---
 
-# kids-playground-ai-api
+# 口コミ要約AI API
 
 ## 概要
 
-本プロジェクトは、「親子で遊ぼうナビ」アプリケーションにAIを活用した**口コミの自動要約機能**を提供するAI APIです。Hugging Face SpacesとGradioを基盤として構築されており、ユーザーが施設の評判を素早く把握できるよう支援します。
+本プロジェクトは、「親子で遊ぼうナビ」アプリケーションにAIを活用した**口コミの自動要約機能**を提供するAPIです。Hugging Face SpacesとGradioを基盤として構築されており、ユーザーが施設の評判を素早く把握できるよう支援します。
 
-## 機能概要
+## 主な機能
 
-*   **口コミの自動要約:** 施設の口コミをAIが分析し、「ポジティブな点」と「注意が必要な点」などをまとめた中立的な要約文を生成します。
-*   **API提供:** Djangoアプリケーションから利用可能なAPIエンドポイントとして機能します。
-*   **Gradio UI:** 開発・デバッグ用に、ブラウザから直接操作できるGradioのデモUIを提供します。
+- **口コミの自動要約:** 施設の口コミテキストを受け取り、AIが分析して中立的な要約文を生成します。
+- **パスワード認証:** 環境変数で設定されたパスワードにより、APIへのアクセスを保護します。
+- **Gradio UI:** 開発・デバッグ用に、ブラウザから直接操作できるGradioのデモUIを提供します。
 
 ## 技術スタック
 
-*   **AIフレームワーク:** Hugging Face Transformers
-*   **APIフレームワーク:** Gradio
-*   **言語:** Python 3.12
-*   **開発環境:** Docker, Docker Compose
-*   **品質管理:** Ruff (Linter/Formatter), Mypy (Type Checker), pre-commit (Git Hooks)
+- **AIフレームワーク:** Hugging Face Transformers
+- **APIフレームワーク:** Gradio
+- **言語:** Python 3.12
+- **開発環境:** Docker, Docker Compose
+- **品質管理:** Ruff (Linter/Formatter), Mypy (Type Checker), pre-commit (Git Hooks)
 
-## 開発環境のセットアップ
+---
+
+## ローカル開発環境のセットアップ
 
-本プロジェクトはDockerベースで構築されており、以下の手順で開発環境をセットアップできます。
+本プロジェクトはDockerを用いて、OSに依存しない開発環境を構築します。
 
 ### 前提条件
 
-*   Docker Desktopがインストールされ、起動していること。
+- [Docker](https://www.docker.com/) および [Docker Compose](https://docs.docker.com/compose/) がインストールされ、起動していること。
 
-### 手順
+### セットアップ手順
 
 1.  **リポジトリのクローン:**
     ```bash
@@ -46,44 +48,69 @@ pinned: false
     ```
 
 2.  **環境変数の設定:**
-    `.env.example`を参考に、`.env`ファイルを作成し、必要な環境変数を設定します。
+    `.env.example`ファイルをコピーして`.env`ファイルを作成し、後述の「環境変数」セクションを参考に内容を編集します。
     ```bash
     cp .env.example .env
-    # 必要に応じて .env ファイルを編集
     ```
 
-3.  **Docker環境の構築と起動:**
+3.  **Dockerコンテナのビルドと起動:**
     ```bash
     docker-compose up --build -d
     ```
-    これにより、必要な依存関係がインストールされ、Gradioアプリケーションがコンテナ内で起動します。
+    これにより、必要なライブラリがインストールされ、Gradioアプリケーションがコンテナ内で起動します。
 
 4.  **`pre-commit`フックのインストール:**
-    Gitコミット時にコード品質チェックが自動で実行されるように、`pre-commit`フックをインストールします。
+    Gitコミット時にコード品質チェックを自動実行するため、`pre-commit`フックをインストールします。
     ```bash
-    docker-compose exec api bash
-    pre-commit install
-    exit
+    docker-compose exec api pre-commit install
     ```
 
-## アプリケーションへのアクセス
+---
+
+## 環境変数
+
+本アプリケーションは、`.env`ファイルまたは実行環境の環境変数から以下の設定を読み込みます。
+
+| 変数名              | 説明                                                                                                                            | デフォルト値・例                               |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `GRADIO_PASSWORD`   | APIとGradioデモUIを保護するためのパスワード。設定しない場合、認証は無効になります。                                               | `your_strong_password_here`                    |
+| `AI_MODEL_NAME`     | （オプション）要約に使用するHugging Faceモデルの名前。指定しない場合、コード内で定義されたデフォルトモデルが使用されます。         | `llm-jp/t5-small-japanese-finetuned-sum` |
+
+---
+
+## アプリケーションの実行とアクセス
 
-開発環境が起動したら、ブラウザから以下のURLでGradioのデモUIにアクセスできます。
+`docker-compose up`を実行すると、APIサーバーが起動します。
 
-*   **Gradio UI:** `http://localhost:7860`
+- **GradioデモUI:** `http://localhost:7860`
+  - ブラウザでアクセスすると、パスワード認証が求められます。`.env`で設定した`GRADIO_PASSWORD`を入力してください。
+
+### APIの認証と利用
+
+APIはパスワードで保護されています。クライアントからAPIを呼び出す際は、以下の情報が必要です。
+
+- **エンドポイントURL:** `http://localhost:7860` （またはデプロイ先のURL）
+- **ユーザー名:** `gemini` （固定）
+- **パスワード:** `GRADIO_PASSWORD`で設定した値
+
+クライアント（例: `gradio_client`）では、このユーザー名とパスワードを使って認証を行います。
+
+---
 
 ## テストの実行
 
-*(このセクションは、テストが実装された後に追記します。)*
+`pytest`を使用してテストを実行します。以下のコマンドで、コンテナ内のすべてのテストを実行できます。
 
-## 貢献
+```bash
+docker-compose exec api pytest
+```
 
-貢献を歓迎します！コントリビューションガイドラインについては、別途ドキュメントを参照してください。
+## デプロイ
 
-## ライセンス
+このアプリケーションは、Hugging Face Spacesへのデプロイを想定して構成されています。リポジトリをHugging Faceにプッシュすると、自動的にビルドとデプロイが実行されます。
 
-*(このセクションは、ライセンスが決定された後に追記します。)*
+本番環境では、Hugging Faceの**Repository secrets**に`GRADIO_PASSWORD`を設定して、APIを保護してください。
 
-## 連絡先
+## ライセンス
 
-ご質問やご提案がありましたら、GitHub Issuesをご利用ください。
+本プロジェクトは **MIT License** の下で公開されています。詳細は[LICENSE](LICENSE)ファイルをご覧ください。

docs/ai_api_development_guide.md

@@ -205,16 +205,17 @@ AI新機能の開発においては、以下のコーディング規約と開発
 
 ### 7.1. API認証
 
-**課題:** Hugging Face Spacesで公開されるAPIは、デフォルトでは誰でもアクセス可能な状態になります。意図しない利用や攻撃を防ぐため、Djangoアプリケーションからのみリクエストを受け付けるように制御する必要があります。
-
-**対策:** APIキーによる認証を導入します。
-1.  **APIキーの生成:** UUIDなどで推測困難な文字列をAPIキーとして生成します。
-2.  **Secretsへの登録:** 生成したキーを、DjangoとGradio APIの両方の環境変数（Hugging Face SpacesのSecrets）として登録します。
-    - `AI_API_KEY`: Gradio側でリクエストを検証するためのキー
-    - `DJANGO_AI_API_KEY`: Djangoがリクエスト時に送信するキー
+**課題:** Hugging Face Spacesで公開されるAPIは、デフォルトでは誰でもアクセス可能な状態になります。意図しない利用や攻撃を防ぐため、認証を導入する必要があります。
+
+**対策:** Gradioが標準で提供するパスワード認証機能を利用します。
+1.  **認証情報の設定:**
+    - `GRADIO_PASSWORD`: APIを保護するためのパスワードを環境変数で設定します。
+2.  **Secretsへの登録:**
+    - **APIサーバー側 (Hugging Face):** `GRADIO_PASSWORD`の値を、Hugging Face SpacesのSecretsに登録します。
+    - **クライアント側 (Renderなど):** 同じパスワードを、クライアントアプリケーションの環境変数 `AI_SUMMARY_API_KEY` として登録します。
 3.  **認証の実装:**
-    - **Django側:** APIを呼び出す際、HTTPヘッダー（例: `Authorization: Bearer <APIキー>`）にAPIキーを含めて送信します。
-    - **Gradio側:** FastAPIの依存性注入（`Depends`）などを利用して、リクエストヘッダーをチェックする認証関数を定義します。APIキーが一致しない場合は、HTTP 401または403エラーを返却します。
+    - **Gradio側:** `iface.launch(auth=(username, password))` の形式で認証を有効にします。ユーザー名は現在 `gemini` で固定されており、パスワードは環境変数から読み込まれます。
+    - **クライアント側:** `gradio_client`を利用する際、`auth=("gemini", api_key)` のように認証情報を渡してAPIを呼び出します。
 
 ### 7.2. その他の対策
 

docs/github_actions_hf_spaces_integration.md

@@ -31,6 +31,18 @@ GitHub ActionsからHugging Face Spacesにアクセスするために、アク
 *   「New repository secret」をクリックし、**Name**を `HF_TOKEN`、**Secret**にコピーしたトークンを貼り付けて登録します。
     *   **`genemicli`との連携:** `genemicli`は、この`HF_TOKEN`の登録方法を丁寧に案内してくれました。
 
+### 4.5. アプリケーション用Secretsの登録 (Hugging Face Spaces側)
+
+`HF_TOKEN`はGitHub Actionsがデプロイを行うために必要なトークンですが、デプロイされた**アプリケーション自体**が実行時に必要とする機密情報（APIキーやパスワードなど）は、Hugging Face Spaces側で設定する必要があります。
+
+今回のプロジェクトでは、APIを保護するための`GRADIO_PASSWORD`が必要です。
+
+*   Hugging Face Spaceの「Settings」ページに移動します。
+*   「Variables and Secrets」セクションで、「New secret」をクリックします。
+*   **Name**を `GRADIO_PASSWORD`、**Value**に設定したいパスワードを入力して登録します。
+
+これにより、アプリケーションは安全にパスワードを読み込んで認証を有効にすることができます。
+
 ### 5. GitHub Actionsワークフローの作成
 
 GitHubリポジトリのルートに `.github/workflows/sync-to-space.yml` というファイルを作成し、以下の内容を記述します。このワークフローは、GitHubの`main`ブランチへのプッシュをトリガーにして、Spaceのコンテンツを自動で更新します。