feat(reactive_voice): リアルタイムチャットボット — 席ごとの NPC 音声 + 構造化された arbiter

.env.master.example

@@ -0,0 +1,141 @@
+# ── Master bot (.env.master) ───────────────────────────
+# Used by `uv run wolfbot`. Loaded from `.env.master` via
+# wolfbot.config.MasterSettings.
+
+# Discord Developer Portal で発行した bot トークン (Master 用)
+DISCORD_TOKEN=
+# bot を動かす Discord サーバー(guild)の数値 ID
+DISCORD_GUILD_ID=
+# 議論用メイン text チャンネルの数値 ID
+MAIN_TEXT_CHANNEL_ID=
+# プレイヤーが会話するメイン VC の数値 ID
+MAIN_VOICE_CHANNEL_ID=
+# SQLite データベースの保存先パス
+WOLFBOT_DB_PATH=./wolfbot.db
+# ログ出力レベル (DEBUG / INFO / WARNING / ERROR)
+LOG_LEVEL=INFO
+
+# ── 議論モード ─────────────────────────────────────────
+# rounds         : Master が全 LLM 席のターン制議論文も生成する
+# reactive_voice : 議論文は NPC bot プロセスが VC で発話する
+#                  (Master は投票・夜行動の判断のみ生成)
+LLM_DISCUSSION_MODE=reactive_voice
+
+# ── Master ↔ NPC bot / voice-ingest WebSocket ────────
+# Master ↔ NPC bot 間 WebSocket の listen アドレス
+MASTER_WS_LISTEN=127.0.0.1:8800
+# NPC bot の WebSocket 認証用 Pre-Shared Key (NPC 側 .env.npc.* と同値)
+MASTER_NPC_PSK=
+
+# ── Gameplay LLM (Master が"判断する"側) ───────────────
+# Master が LLM 席の挙動を決めるときに使う LLM。担当範囲:
+#   • 投票判断 (誰を処刑するか) ────────────── 全モード
+#   • 夜行動 (人狼の襲撃先 / 占い / 護衛) ──── 全モード
+#   • 議論ターンの発言文生成 ──────────────── rounds モードのみ
+# (reactive_voice モードでは議論文は NPC bot 側に移譲され、Master は
+#  この LLM で投票と夜行動だけを生成する)
+#
+# Backend は 4 種類から選べる:
+#   xai      ─ xAI Grok など OpenAI Chat Completions 互換 endpoint
+#              (OpenAI / Groq / Together / vLLM / Ollama も同じ枠で可)
+#   deepseek ─ DeepSeek (json_object モード + thinking + reasoning_effort)
+#   gemini   ─ Vertex AI Gemini (ADC/IAM 認証、API key 認証は非対応)
+#   mock     ─ オフライン統合テスト用。API コールせず決定論的な
+#              LLMAction を返す (投票/夜行動は target_name=None で
+#              LLMAdapter 側の random fallback に委譲、議論発言は
+#              定型句のラウンドロビン)。API キー不要。
+# NPC bot 側 NPC_LLM_PROVIDER と独立に選べる (片方を Vertex Gemini、
+# 片方を xAI Grok にする、といった片寄せも可能)。
+GAMEPLAY_LLM_PROVIDER=xai
+
+# xAI / DeepSeek / OpenAI 互換 endpoint で使う API キー (gemini なら不要)
+GAMEPLAY_LLM_API_KEY=
+GAMEPLAY_LLM_MODEL=grok-4-1-fast
+# 自前 endpoint や別プロバイダを叩く場合のみ上書き。空のままなら provider
+# 既定値 (xai: https://api.x.ai/v1, deepseek: https://api.deepseek.com)
+GAMEPLAY_LLM_BASE_URL=
+
+# DeepSeek 専用 (provider=deepseek 以外では無視される)
+GAMEPLAY_LLM_THINKING=enabled
+GAMEPLAY_LLM_REASONING_EFFORT=max
+
+# Vertex AI Gemini 専用 (provider=gemini 以外では無視される)
+# 認証は ADC のみ: ローカルは `gcloud auth application-default login`、
+# 本番は Vertex AI 権限を持つ service account を attach する。
+GAMEPLAY_LLM_VERTEX_PROJECT=
+GAMEPLAY_LLM_VERTEX_LOCATION=global
+GAMEPLAY_LLM_THINKING_LEVEL=high
+
+# ── フェーズ duration (検証・モック用の早送り) ────────
+# 全フェーズの長さに掛ける倍率。0.1 = 10倍速、1.0 = デフォルト。
+# 1秒未満になる場合は 1秒にクランプ。空のままならデフォルト維持。
+# 個別フェーズのみ短くしたいときは下の WOLFBOT_*_DURATION で絶対秒指定
+# (倍率と個別指定は両方適用、個別指定が後勝ち)。
+# 将来的には Master bot の slash command で動的変更できるようになるため、
+# このシングルトンが書き換え地点 (wolfbot.domain.durations.set_phase_durations)。
+WOLFBOT_PHASE_DURATION_FACTOR=
+
+# 個別フェーズ秒数の絶対指定 (空ならデフォルト or 倍率適用後の値を維持)
+WOLFBOT_VOTE_DURATION=
+WOLFBOT_RUNOFF_DURATION=
+WOLFBOT_NIGHT_DURATION=
+WOLFBOT_DAY_DISCUSSION_GRACE=
+WOLFBOT_RUNOFF_SPEECH_GRACE=
+WOLFBOT_DISCUSSION_DAY1=
+WOLFBOT_DISCUSSION_DAY2=
+WOLFBOT_DISCUSSION_DAY3PLUS=
+
+# ── 音声 / テキスト ingest パイプラインの形状 ──────────────
+# 人間の発言 (音声 / テキスト) を構造化 SpeechEvent
+# (addressed_seat_no / co_declaration / role_callout) に変換する経路
+# を 2 つの直交スイッチで明示する。各経路に必要なコンポーネントの
+# クレデンシャルは下のブロックで個別に設定する。
+#
+# VOICE_PIPELINE: 人間の音声をどう取り込むか
+#   audio_analyzer            : 1 コールの multimodal (audio → 構造化 JSON)
+#                               現状は AUDIO_ANALYZER_PROVIDER=gemini のみ対応
+#   stt_then_text_analyzer    : 2 段 (Stt で文字起こし → TextAnalyzer で構造化)
+#                               TextAnalyzer はテキスト経路と同じインスタンスを共有
+#   disabled                  : Master は VC に参加しない (rounds モードのデフォルト)
+VOICE_PIPELINE=disabled
+#
+# TEXT_PIPELINE: テキスト発言をどう取り込むか
+#   text_analyzer  : 各テキスト発言ごとに TextAnalyzer を 1 コール
+#   passthrough    : 構造解析なし (SpeakArbiter は LRU 一本でルーティング)
+TEXT_PIPELINE=passthrough
+
+# ── AudioAnalyzer (audio → transcript + 構造化) ─────────────
+# VOICE_PIPELINE=audio_analyzer のときのみ必須。
+# 1 API コールで書き起こし + CO 検出 + 投票先 + addressed_name を返す
+# multimodal LLM。現状 Gemini Flash 系のみ (xAI / Groq は audio-in 非対応)。
+AUDIO_ANALYZER_PROVIDER=gemini
+AUDIO_ANALYZER_API_KEY=
+AUDIO_ANALYZER_MODEL=gemini-2.0-flash-lite
+
+# ── Stt (audio → transcript) ────────────────────────────
+# VOICE_PIPELINE=stt_then_text_analyzer のときのみ必須。
+# Whisper-large-v3-turbo が Groq 上で最安かつ日本語実用品質。
+# whisper-large-v3 に切り替えると精度↑コスト約3倍。
+STT_PROVIDER=groq
+STT_API_KEY=
+STT_MODEL=whisper-large-v3-turbo
+STT_BASE_URL=https://api.groq.com/openai/v1
+
+# ── TextAnalyzer (text → 構造化) ────────────────────────
+# TEXT_PIPELINE=text_analyzer のとき (発言ごと)、または
+# VOICE_PIPELINE=stt_then_text_analyzer のとき (Stt 後段) に使用。
+# 両経路で同じインスタンスを共有 → クレデンシャルプールも一本化。
+# GAMEPLAY_LLM_* とは意図的に分離 (Gameplay は重い思考モデル、
+# 構造解析は安い高 RPM モデル、の組み合わせを許す)。
+#
+# プロバイダ:
+#   xai / deepseek / openai : OpenAI Chat Completions 互換
+#                             (API_KEY 必須、BASE_URL は任意)
+#   gemini                  : AI Studio REST (AIza... 形式の API_KEY 必須)
+#                             ※ VOICE_PIPELINE=stt_then_text_analyzer の
+#                                 後段としては未対応 (audio_analyzer に寄せる)
+TEXT_ANALYZER_PROVIDER=xai
+TEXT_ANALYZER_API_KEY=
+TEXT_ANALYZER_MODEL=grok-4-1-fast
+# 自前 endpoint (vLLM / Ollama 等) のときのみ上書き
+TEXT_ANALYZER_BASE_URL=

.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python (lint + type + tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      # discord.py loads libopus via ctypes for VC tests. The ubuntu
+      # runner image doesn't ship it by default, so OpusError(...)
+      # crashes inside `_lib.opus_strerror` and breaks test collection
+      # in tests/test_voice_recv_resilience.py.
+      - name: Install libopus (for voice tests)
+        run: sudo apt-get update && sudo apt-get install -y libopus0
+
+      - name: Sync deps
+        run: uv sync --all-extras --dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest tests
+
+  viewer:
+    name: Viewer (typecheck + contract tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The viewer's contract test spawns the real Python exporter
+      # (`scripts/export-game.py`) against a seeded fixture DB, so this
+      # job needs both Node and uv.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Sync Python deps (for live exporter spawn)
+        run: uv sync --all-extras --dev
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: viewer/pnpm-lock.yaml
+
+      - name: Install viewer deps
+        working-directory: viewer
+        run: pnpm install --frozen-lockfile
+
+      - name: Type check
+        working-directory: viewer
+        run: pnpm typecheck
+
+      - name: Contract tests (vitest + live Python exporter)
+        working-directory: viewer
+        run: pnpm test

.gitignore

@@ -8,11 +8,31 @@ __pycache__/
 dist/
 build/
 .env
+.env.master
+# NPC bot env files live under envs/npc/. The committed `.env.npc.example`
+# template is the only one tracked; the per-persona `.env.<persona>` files
+# (generated by scripts/generate_npc_envs.py) stay out of git.
+envs/npc/.env.*
+!envs/npc/.env.npc.example
+envs/voicetest/.env.*
+!envs/voicetest/.env.voicetest.example
+# Local secrets used by the generator
+tokens.txt
 *.db
 *.db-journal
 *.db-wal
 *.db-shm
 .DS_Store
 
+# scripts/run-bots.sh writes per-bot logs here.
+logs/
+
 # for git push
-.claude/
+.claude/
+
+# Specflow local env
+.specflow/config.env
+.specflow/runs/
+.specflow/worktrees/
+.codex
+openspec

AGENTS.md

@@ -1,10 +1,10 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-Runtime code lives in `src/wolfbot`. Keep pure game logic in `domain/`, orchestration in `services/`, SQLite access in `persistence/`, LLM personas and prompts in `llm/`, and Discord UI views in `ui/`. Tests live in `tests/`, with shared fixtures in `tests/conftest.py` and fakes in `tests/fakes.py`. Use `.env.example` for local settings, and read `prompts/IMPLEMENTATION_PROMPT.md` before changing roles, phases, or event ordering.
+Runtime code lives in `src/wolfbot`. Keep pure game logic in `domain/`, orchestration in `services/`, SQLite access in `persistence/`, shared persona types in `llm/persona_base.py` (player personas in `npc/personas.py`, GM personas in `master/personas.py`), and Discord UI views in `ui/`. The Master-only reactive-voice pipeline lives in `master/`; the per-process NPC bot worker lives in `npc/` with its own `NpcSettings`. Each NPC bot process is bound to one persona at startup (`NPC_PERSONA_KEY`); Master's `/wolf start` fills LLM seats from the online NPC registry in reactive_voice mode. Tests live in `tests/`, with shared fixtures in `tests/conftest.py` and fakes in `tests/fakes.py`. Use `.env.master.example` at the repo root for the Master env, and the per-persona templates in `envs/npc/.env.<persona>.example` (see [envs/npc/README.md](envs/npc/README.md)) for each NPC process. Read `prompts/IMPLEMENTATION_PROMPT.md` before changing roles, phases, or event ordering.
 
 ## Build, Test, and Development Commands
-Use `uv` for all local work. `uv sync` installs runtime and dev dependencies. `uv run wolfbot` starts the bot with values from `.env`. `uv run pytest tests` runs the full suite; `uv run pytest tests/test_rules_votes.py` runs one module. `uv run ruff check src tests` runs lint and import checks, `uv run ruff format src tests` formats code, and `uv run mypy` runs strict type checking.
+Use `uv` for all local work. `uv sync` installs runtime and dev dependencies. `uv run wolfbot` starts the Master bot with values from `.env.master`. NPC workers are launched per persona: `WOLFBOT_NPC_ENV=envs/npc/.env.<persona> uv run wolfbot-npc`. `uv run pytest tests` runs the full suite; `uv run pytest tests/test_rules_votes.py` runs one module. `uv run ruff check src tests` runs lint and import checks, `uv run ruff format src tests` formats code, and `uv run mypy` runs strict type checking.
 
 ## Coding Style & Naming Conventions
 Target Python 3.11 and keep 4-space indentation. Follow Ruff defaults with a 100-character line length; let `ruff format` handle wrapping instead of manual alignment. New code should be fully type-annotated because `mypy` runs in strict mode. Use `snake_case` for modules, functions, and test files such as `test_recovery.py`; use `PascalCase` for classes and Pydantic models.