Refactor configuration loading with dotenv and pydantic-settings

.env.template

@@ -0,0 +1,38 @@
+# -- Google Cloud Platform --
+GCLOUD_PROJECT="your-gcloud-project-id"
+GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
+
+# -- Speech Recognition --
+# Google Cloud STT
+STACKCHAN_USE_GOOGLE_CLOUD_STT=1
+STACKCHAN_GOOGLE_CLOUD_STT_LANGUAGE_CODE="ja-JP"
+
+# Whisper CLI
+# STACKCHAN_USE_WHISPER_CLI=1
+# STACKCHAN_WHISPER_CLI_MODEL_PATH="/path/to/whisper.cpp/ggml-small.bin"
+# STACKCHAN_WHISPER_CLI_VAD_MODEL_PATH="/path/to/whisper.cpp/ggml-silero-v5.1.2.bin"
+
+# Whisper Server
+# STACKCHAN_USE_USE_WHISPER_SERVER=1
+# STACKCHAN_WHISPER_SERVER_PORT=8431
+
+# -- Speech Syntheis --
+# Google Cloud TTS
+STACKCHAN_USE_GOOGLE_CLOUD_TTS=1
+STACKCHAN_GOOGLE_CLOUD_TTS_MODEL="gemini-2.5-flash-tts"
+STACKCHAN_GOOGLE_CLOUD_TTS_LANGUAGE_CODE="ja-JP"
+STACKCHAN_GOOGLE_CLOUD_TTS_VOICE_NAME="Despina"
+
+# VOICEVOX
+# STACKCHAN_USE_VOICEVOX=1
+STACKCHAN_VOICEVOX_URL="http://localhost:50021"
+STACKCHAN_VOICEVOX_SPEAKER=1
+
+# -- Claude Agent SDK --
+# using Google Cloud Vertex AI
+CLAUDE_CODE_USE_VERTEX=1
+CLOUD_ML_REGION="global"
+ANTHROPIC_VERTEX_PROJECT_ID="your-gcloud-project-id"
+
+# using Anthoropic API Key
+# ANTHROPIC_API_KEY="your-anthropic-api-key"

docs/run_sample_app_ja.md

@@ -0,0 +1,94 @@
+# サンプルアプリケーションの実行
+
+複数のサンプルアプリケーションが実装されています。
+
+- [example_apps/echo_with_move.py](../example_apps/echo_with_move.py): 音声認識した内容をそのまま音声合成して返す。ボディも動かして聞くポーズをします。
+- [example_apps/gemini.py](../example_app/gemini.py): Gemini応答
+- [example_apps/claude_agent.py](../example_app/claude_agent.py): Claude Agent SDKを利用したエージェント
+
+## おうむ返しサンプル
+
+uv で必要なライブラリをインストールします。
+
+```
+uv sync
+```
+
+その後、以下のコマンドでPythonサーバを起動します。
+
+```
+uv run uvicorn app.echo_with_move:app.fastapi --host 0.0.0.0 --port 8000
+```
+
+スタックチャンを起動して、「Disconnected」から「Idle」のステータス表示になれば接続されています。
+
+試しに「ハイ！スタックチャン！」と話しかけて、聞くポーズになることを確認して、話しかけてみてください。
+
+## Gemini応答サンプル
+
+uv で必要なライブラリをインストールします。
+追加でgeminiのクライアントが必要です。
+
+```
+uv sync --group example-gemini
+```
+
+その後、以下のコマンドでPythonサーバを起動します。
+
+```
+uv run uvicorn app.gemini:app.fastapi --host 0.0.0.0 --port 8000
+```
+
+スタックチャンを起動して、「Disconnected」から「Idle」のステータス表示になれば接続されています。
+
+試しに「ハイ！スタックチャン！」と話しかけて、聞くポーズになることを確認して、話しかけてみてください。
+
+## Claude Agent SDKサンプル
+
+Claude Agent SDKのエージェントはファイルシステムの変更権限を持ちます。
+意図しないファイル編集するような指示を与えないように注意してください。
+
+TODO: サンプルアプリはファイル編集、読取権限を剥奪する
+
+### NodeJSのインストール
+
+NodeJSのインストールも必要です。
+以下からインストールを進めてください。
+
+> https://nodejs.org/ja/download
+
+### Pythonライブラリのインストール
+
+uv で必要なライブラリをインストールします。
+追加でclaude agent sdkのクライアントが必要です。
+
+```
+uv sync --group example-claude-agent-sdk
+```
+
+### Claude Agent SDKの環境変数設定
+
+Claude Agent SDKを利用するには、VertexAIを利用する場合、以下の.envもしくは環境変数の設定が必要です。
+
+#### VertexAIを利用する場合
+
+- `CLAUDE_CODE_USE_VERTEX`: `1`
+- `CLOUD_ML_REGION`: リージョン設定 "global"
+- `ANTHROPIC_VERTEX_PROJECT_ID`: Google CloudのプロジェクトID（`GCLOUD_PROJECT`と同じ値）
+- `GOOGLE_APPLICATION_CREDENTIALS`: Google Cloudのサービスアカウントの秘密鍵のJSONファイルのパス
+
+#### Claude APIを利用する場合
+
+- `ANTHROPIC_API_KEY`: Claude APIのAPIキー
+
+### サーバの起動
+
+その後、以下のコマンドでPythonサーバを起動します。
+
+```
+uv run uvicorn app.claude_agent_sdk:app.fastapi --host 0.0.0.0 --port 8000
+```
+
+スタックチャンを起動して、「Disconnected」から「Idle」のステータス表示になれば接続されています。
+
+試しに「ハイ！スタックチャン！」と話しかけて、聞くポーズになることを確認して、話しかけてみてください。

docs/server_ja.md

@@ -0,0 +1,137 @@
+# サーバの設定
+
+## .envファイルの作成
+
+サーバの基本設定は`.env`ファイル、もしくは環境変数に全て記述します。
+リポジトリのルートディレクトリに、`.env`という名前のファイルを作成してください。
+
+次から、`.env`ファイルに記述する環境変数を説明します。
+
+## Google Cloudの設定
+
+[./google_cloud_ja.md](./google_cloud_ja.md) にて、Google Cloudのプロジェクトを作成し、サービスアカウントの秘密鍵のJSONファイルダウンロードしました。
+
+この値を記述します。
+
+- `GCLOUD_PROJECT`: プロジェクト名
+- `GOOGLE_APPLICATION_CREDENTIALS`: ダウンロードしたサービスアカウントの秘密鍵のJSONファイルのパス
+
+プロジェクト名は、秘密鍵のJSONファイル中に記載されている、`project_id`の値と同じものを指定してください。
+
+```
+GCLOUD_PROJECT="your-gcloud-project-id"
+GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
+```
+
+この設定は、Google Cloud Speech-to-Text(STT)、Google Cloud Text-to-Speech(TTS)の両方で使用されます。
+
+## 音声認識の設定
+
+音声認識エンジンとして、以下に対応しています。
+
+- Google Cloud Speech-to-Text
+- Whisper.cppのwhisper-server
+- Whisper.cppのwhisper-cli
+
+### Google Cloud Speech-to-Textの設定
+
+以下の値を設定します。
+
+- `STACKCHAN_USE_GOOGLE_CLOUD_STT`: `1`
+- `STACKCHAN_GOOGLE_CLOUD_STT_LANGUAGE_CODE`: BCP-47 言語コード
+
+BCP-47 言語コードは以下のページを参照してください。
+
+https://docs.cloud.google.com/speech-to-text/docs/speech-to-text-supported-languages
+
+```
+STACKCHAN_USE_GOOGLE_CLOUD_STT=1
+STACKCHAN_GOOGLE_CLOUD_STT_LANGUAGE_CODE="ja-JP"
+```
+
+### Whisper.cppのwhisper-cliの設定
+
+(WIP)
+
+```
+STACKCHAN_USE_WHISPER_CLI=1
+STACKCHAN_WHISPER_CLI_MODEL_PATH="/path/to/whisper.cpp/ggml-small.bin"
+STACKCHAN_WHISPER_CLI_VAD_MODEL_PATH="/path/to/whisper.cpp/ggml-silero-v5.1.2.bin"
+```
+
+### Whisper.cppのwhisper-serverの設定
+
+(WIP)
+
+```
+STACKCHAN_USE_USE_WHISPER_SERVER=1
+STACKCHAN_WHISPER_SERVER_PORT=8431
+```
+
+## 音声合成の設定
+
+音声合成エンジンとして、以下に対応しています。
+
+- Google Cloud Text-to-Speech
+- VOICEVOX
+
+### Google Cloud Text-to-Speechの設定
+
+以下の値を設定します。
+
+- `STACKCHAN_USE_GOOGLE_CLOUD_TTS`: `1`
+- `STACKCHAN_GOOGLE_CLOUD_TTS_MODEL`: モデル
+- `STACKCHAN_GOOGLE_CLOUD_TTS_LANGUAGE_CODE`: BCP-47 言語コード
+- `STACKCHAN_GOOGLE_CLOUD_TTS_VOICE_NAME`: 音声の名前
+
+モデルは以下から選択できます。
+
+https://docs.cloud.google.com/text-to-speech/docs/gemini-tts#available_models
+
+対応言語は以下から確認してください。
+
+https://docs.cloud.google.com/text-to-speech/docs/gemini-tts#available_languages
+
+ボイス名は以下から確認してください。（サンプル音声は英語ですが、日本語に対応しているようです）
+
+https://docs.cloud.google.com/text-to-speech/docs/gemini-tts#voice_options
+
+```
+STACKCHAN_USE_GOOGLE_CLOUD_TTS=1
+STACKCHAN_GOOGLE_CLOUD_TTS_MODEL="gemini-2.5-flash-tts"
+STACKCHAN_GOOGLE_CLOUD_TTS_LANGUAGE_CODE="ja-JP"
+STACKCHAN_GOOGLE_CLOUD_TTS_VOICE_NAME="Despina"
+```
+
+### VOICEVOXの設定
+
+VOICEVOXを利用する際には、VOICEVOXの利用規約の参照をお願いします。
+
+https://voicevox.hiroshiba.jp/
+
+[./setup_ja.md](./setup_ja.md) の手順で立ち上げた場合、http://localhost:50021/ でVOICEVOXのAPIが利用できるようになっています。
+
+以下の値を設定します。
+
+- `STACKCHAN_USE_VOICEVOX`: `1`
+- `STACKCHAN_VOICEVOX_URL`: VOICEVOXのAPIのURL
+- `STACKCHAN_VOICEVOX_SPEAKER`: 使用するキャラクターのスピーカーID
+
+キャラクターの一覧は下記のページにあります。
+キャラクターによって利用規約が異なります。
+
+https://voicevox.hiroshiba.jp/#characters
+
+キャラクターからスピーカーIDの確認が必要です。
+
+VOICEVOXが立ち上がっている場合、/speakers にアクセスすると、スピーカーIDとキャラクターの対応表がJSON形式で表示されます。
+キャラクター毎の構造があり、その中にキャラクターのstyleがあります。
+styleの id がスピーカーIDになります。
+
+> http://localhost:50021/speakers
+
+```
+STACKCHAN_USE_VOICEVOX=1
+STACKCHAN_VOICEVOX_URL="http://localhost:50021"
+STACKCHAN_VOICEVOX_SPEAKER=1
+```

docs/setup_ja.md

@@ -51,6 +51,9 @@ M5Stack Basic、M5Stack Core2は対応していません。
 
 - Tower Pro SG90
     - [秋月電子通商](https://akizukidenshi.com/catalog/g/g108761/)
+- FEETECH SCS0009
+    - [秋月電子通商](https://akizukidenshi.com/catalog/g/g131664/)
+    - [スイッチサイエンス](https://www.switch-science.com/products/8042)
 
 ### 対応確認済み外装ケースと接続ボード
 
@@ -79,23 +82,48 @@ M5Stack Basic、M5Stack Core2は対応していません。
 
 [./firmware_ja.md](./firmware_ja.md)
 
-## VOICEVOXのDockerコンテナの実行
+## （オプション）VOICEVOXのDockerコンテナの実行
+
+標準ではGoogle Cloud Text-to-Speechを利用して音声合成を行います。
+無料で利用できる中品質の音声合成エンジンのVOICEVOXも利用できます。
+キャラクターボイスが多くてかわいいので、VOICEVOXもぜひ試してみてください。
+
+VOICEVOXを利用する際には、VOICEVOXの利用規約の参照をお願いします。
+
+https://voicevox.hiroshiba.jp/
 
-標準では、音声合成にVOICEVOXを利用します。
 VOICEVOXはDockerイメージが提供されているため、Docker環境を構築して実行します。
 
-Dockerがインストールされていない場合は以下のページヲ参照して、Dockerをインストールしてください。
+Dockerがインストールされていない場合は以下のページを参照して、Dockerをインストールしてください。
 
 > 今すぐ始める | Docker
 >
 > https://www.docker.com/ja-jp/get-started/
 
-VOICEVOXのDockerコンテナの実行方法は、以下のページを参照してください。
+Dockerがインストールできたら、リポジトリのディレクトリで以下のコマンドを実行してください。
 
 ```
 docker compose run --rm --service-ports voicevox
 ```
 
+以下のサイトにアクセスし、「VOICEVOX Engine」と表示されていれば成功です。
+
+> http://localhost:50021/
+
+## （オプション）Whisper.cppのwhisper-cliのインストール
+
+標準ではGoogle Cloud Speech-to-Textを利用して音声認識を行います。
+無料で利用できるWhisper.cppのwhisper-cliも利用できます。
+
+TODO
+
+## （オプション）Whisper.cppのwhisper-serverのインストールと実行
+
+標準ではGoogle Cloud Speech-to-Textを利用して音声認識を行います。
+無料で利用できるWhisper.cppのwhisper-serverも利用できます。
+
+TODO
+
 ## Python開発環境の構築
 
 このリポジトリでは、WebソケットサーバをPythonで実装しています。
@@ -105,23 +133,32 @@ Pythonの環境構築の方法は、パッケージマネージャuvのページ
 >
 > https://docs.astral.sh/uv/getting-started/installation/
 
+## サーバの設定
+
+以下のページを参照して、サーバの設定を行ってください。
+
+[./server_ja.md](./server_ja.md)
+
 ## サンプルアプリケーションの実行
 
-uv でPythonサーバを起動します。
+まずは、サンプルアプリケーションを実行してみましょう。
 
-```bash
-uv sync
-uv run uvicorn app.gemini:app.fastapi --host 0.0.0.0 --port 8000
-```
+以下のページを参照して、サンプルアプリケーションの実行方法を確認してください。
 
-## アプリケーションの設定
+[./run_sample_app_ja.md](./run_sample_app_ja.md)
 
-TODO
+## アプリケーションを作る
+
+(WIP)
+
+[example_apps/gemini.py](../example_apps/gemini.py) をベースに改変を行い、アプリケーションを作ってみましょう。
 
 ## Claude Agent SDKによるエージェントの構築と実行
 
-TODO
+(WIP)
+
+[example_apps/claude_agent_sdk/claude_agent_sdk.py](../example_apps/claude_agent_sdk/claude_agent_sdk.py) をベースに改変を行い、Claude Agent SDKを利用したエージェントを作ってみましょう。
 
-## Docker環境で実行する
+## Claude Agent SDKをDocker環境で実行する
 
 TODO