Aibou AI Web Companion (相棒AI) - Production MVP

完全ローカルで動作するパーソナライズされたAIコンパニオンWebシステムです。 バックエンドにFastAPI、フロントエンドにバニラHTML/JS/CSSを使用し、Ollama経由でローカルのLLM（大規模言語モデル）と対話します。 AIキャラクターの可視化(Live2D)と音声合成(VOICEVOX)を統合したコンパニオンアプリです。

特徴

• ローカル動作: Ollamaを使用し、完全ローカルで動作します。（デフォルトモデル：qwen2.5:7b）
• Web検索連携: Brave Search APIによる実検索（Real）、モック検索（Mock）、無効（Off）を統合。検索クオータを管理し課金事故を防ぎます。
• 100%日本語出力: アシスタントの回答は厳格に日本語のみとなるよう制御。
• キャラクターホットスワップ: 再起動なしでAIのペルソナ（性格・音声設定・感情表現）、およびLive2Dモデルを切り替え可能。
  • 同梱キャラクター: default (アイコ), tsumugi (春日部つむぎ風)
• Live2D & 音声リップシンク: フロントエンド側で WebAudio API の AnalyserNode を用いて、音声 (WAV) のボリュームから自動的にLive2Dの口の開閉 (MouthSync) を行います。
• 音声合成 (TTS): VOICEVOXエンジンと連携。エンジン未起動時は自動的にブラウザ内蔵のWeb Speech API(フォールバック)に切り替わり、クラッシュしません。

必要条件

• Windows環境
• Python 3.11 (グローバル環境で実行可能。仮想環境は任意)
• Ollama インストール済みであること
• VOICEVOX (オプション、高品質音声用)

セットアップと起動手順

1. Ollamaの準備

Ollamaを起動し、デフォルトモデル（qwen2.5:7b）を取得・起動状態にします。

ollama run qwen2.5:7b

※Ollamaがバックグラウンド（http://localhost:11434）で起動している必要があります。

2. VOICEVOXエンジンの起動 (オプション)

VOICEVOX アプリケーションを起動するか、Dockerエンジンを起動し、http://127.0.0.1:50021 でアクセス可能な状態にします。 ※起動していない場合は、ブラウザ標準の音声合成にフォールバックします。

3. バックエンドの起動 (Python 3.11)

必須パッケージをインストールし、サーバーを起動します。

# パッケージのインストール
pip install fastapi uvicorn httpx pydantic

# 環境変数の設定 (実検索を使う場合のみ)
# set BRAVE_API_KEY=your_api_key_here

# FastAPI サーバーの起動 (ポート8000)
# ※スマホなどの別端末(Tailscale等)からアクセスする場合は --host 0.0.0.0 を付与します
uvicorn aibou_ai.web.backend.main:app --reload --host 0.0.0.0 --port 8000

※フロントエンドファイルもFastAPIがまとめて配信します。

4. ブラウザでアクセス

ブラウザを開き、以下のURLにアクセスしてください： http://127.0.0.1:8000/

検索モードと安全性について

トップバーの「検索」設定で以下を選択可能です：

• OFF: 外部検索を行いません。
• ON (モック): 構成済みのモックデータで検索した程で回答します。APIコールは一切発生しません。
• ON (実検索): Brave Search API を呼び出します。
  • フェイルセーフ: BRAVE_API_KEY環境変数が設定されていない場合、自動的に「モック」にフォールバックし、UIとログに切り替わった旨を通知します。アプリはクラッシュしません。
  • クォータ管理: shared/usage.json にて一日のAPIコール回数が厳密に管理されており、上限に達すると自動的にOFFに切り替わり検索をストップします。

永続化ファイル一覧

以下のファイルは状態や記憶をシステムに保存するために利用され、自動生成・更新されます。

• shared/memory.json: ユーザーとの対話から得られた自動記憶、およびマニュアル記憶（Boost Memory）を保存します。
• shared/usage.json: 実検索（REAL検索）の利用回数クオータ（日次・月次）を保存・追跡します。

API エンドポイント

• GET /api/state: 現在のキャラクター、検索モード、利用残回数などを返します。
• POST /api/settings: キャラクター、検索モード、ミュートの切り替えを行います。
• POST /api/chat: メッセージを送信し、応答と感情を受け取ります。
• POST /api/memory/boost: 任意の記憶テキストを優先記憶として追加します。
• POST /api/tts: テキストと話者名からWAV音声を生成します（VOICEVOX連携）。

トラブルシューティング

• 音声が鳴らない: ミュートトグルがOFFになっていること、VOICEVOXが起動しているかを確認してください。VOICEVOXがない場合はUI上に警告が出てブラウザ音声になります。
• Live2Dモデルが表示されない: frontend/assets/live2d 直下にモデルデータ（.model3.json など）が正しく配置されているか確認してください。
• REAL検索が機能しない: ターミナルに [Search] BRAVE_API_KEY missing と出ていないか、あるいは [Search] REAL -> OFF (quota exhausted) と出ていないか確認してください。