Release build deployed at Mon Feb 23 12:29:42 JST 2026

Author: Nexus Ark Bot

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: kenomendako

.github/copilot-instructions.md

@@ -0,0 +1,119 @@
+# Nexus Ark プロジェクトのための Copilot ガイド
+
+このドキュメントは、AIコーディングエージェントが `Nexus Ark` プロジェクトで効率的に開発を進めるためのガイドです。
+
+## 1. プロジェクト概要
+
+`Nexus Ark` は、キャラクターとの対話を通じて、永続的な記憶と関係性を構築することを目的とした、PythonベースのAIチャットアプリケーションです。GradioをUIフレームワークとして使用し、バックエンドでは複数のAIモデル（主にGemini）を切り替えて利用できます。
+
+**主要な技術スタック:**
+- **言語:** Python 3
+- **UI:** Gradio
+- **AI:** Google Gemini API (LangChain経由)
+- **データ形式:** JSON (設定、記憶データ), テキストファイル (ログ)
+- **通知:** Pushover, Discord Webhook
+
+## 2. アーキテクチャの概要
+
+本プロジェクトは、関心事の分離を重視したモジュール式のアーキテクチャを採用しています。
+
+- **`nexus_ark.py`**: アプリケーションのエントリーポイント。Gradio UIのレイアウトとイベントハンドラを定義します。
+- **`config_manager.py`**: `config.json` の読み書きを担当。APIキーや通知設定など、システム全体の設定を管理します。
+- **`room_manager.py`**: 各キャラクター（ルーム）に関連するファイル（ログ、設定、記憶）のパスを管理します。
+- **`agent/`**: AIの思考と応答生成の中核を担うモジュールです。
+    - `agent/graph.py`: LangChainを使ってAIの応答を生成するメインロジック。`invoke_nexus_agent_stream` が中心的な関数です。
+    - `agent/prompts.py`: AIに与えるシステムプロンプトや指示を組み立てます。
+    - `ui_handlers.py`: Gradioのイベント処理の多くを担います。特に、AIからの応答をストリーミングで処理する `_stream_and_handle_response` は重要な役割を果たします。
+- **`tools/`**: AIが利用可能なツール群。ファイル操作、Web検索、アラーム設定など、AIエージェントに機能を提供します。
+- **`characters/`**: 各キャラクター（ルーム）のデータが格納されるディレクトリ。サブディレクトリごとに、記憶、ログ、設定ファイルが分かれています。
+- **`docs/`**: 設計思想、仕様書、過去の重要な開発記録が格納されています。開発に着手する前に、特に `docs/guides` と `docs/philosophy` を確認することが強く推奨されます。
+
+### データフローの例：ユーザーからのメッセージ送信
+
+1.  **UI (`nexus_ark.py`)**: ユーザーがメッセージを送信すると、対応するイベントハンドラが発火します。
+2.  **イベントハンドラ (`ui_handlers.py`)**: `_stream_and_handle_response` 関数が呼び出され、その中で `gemini_api.invoke_nexus_agent_stream` を実行し、AIの応答生成を要求します。
+3.  **エージェント (`agent/graph.py`)**:
+    - 過去のログ (`characters/{room_name}/log.txt`) と現在のコンテキスト（情景、時間など）を読み込みます。
+    - `agent/prompts.py` を使って、AIへの完全なプロンプトを構築します。
+    - LangChainのグラフ (`RunnableGraph`) を実行し、Gemini APIに応答を要求します。
+4.  **ストリーミング処理 (`ui_handlers.py`)**:
+    - `_stream_and_handle_response` は、AIからのストリームを一旦バッファリングします。
+    - ストリームの最後に得られる最終状態（`final_state`）を見て、それが「ツール呼び出しを含むか否か」を判断します。
+    - **二幕構成ストリーミング**:
+        - **第一幕（意思表示）**: ツール呼び出しがある場合、AIの「〜しますね」というような意気込みのテキストのみを表示します。
+        - **第二幕（最終報告）**: ツール呼び出しがない（全ての処理が終わった）場合、最終的な応答テキストを表示します。
+    - この機構により、ツール実行の中間生成物がUIに表示されるのを防ぎ、没入感を維持します。
+5.  **ログと記憶の保存 (`utils.py`)**: AIの応答は `log.txt` に追記され、必要に応じて記憶データ (`memory/memory_main.txt`) も更新されます。
+6.  **UI更新**: ストリーミング処理によって整形された応答がGradioのUIに表示されます。
+
+## 3. 重要な開発ワークフローと規約
+
+### 3.1. 依存関係の管理
+
+プロジェクトの依存関係は `requirements.txt` で管理されています。新しいライブラリを追加した場合は、必ずこのファイルを更新してください。
+
+```bash
+pip install -r requirements.txt
+```
+
+### 3.2. 設定の管理
+
+- **`config.json`**: APIキーや通知サービスなど、個人の環境に依存する設定が含まれます。このファイルはリポジトリにコミットしないでください。
+- **`config_manager.py`**: 設定ファイルへのアクセスのための唯一のインターフェースです。ハードコーディングを避け、必ずこのモジュール経由で設定値を取得してください。
+- **`nexus_ark.py` の構造**: アプリケーションのエントリーポイントであるこのファイルは、全体の安定性を確保するため、巨大な `try...except...finally` ブロックで囲まれています。この構造は絶対に破壊してはいけません。
+
+### 3.3. 技術スタックの規約
+
+- **Gemini APIの利用**: `google-genai` ライブラリを使用します。`import google.genai as genai` が唯一の正しいインポート方法です。
+- **モデル選定**:
+    - **内部処理 (情景生成など)**: `gemini-2.5-flash-lite`
+    - **最終応答 (AIペルソナ)**: ユーザーが選択可能 (デフォルト: `gemini-2.5-pro`)。`gemini-1.5-pro` は過去に問題が確認されており、非推奨です。
+    - **画像生成**: `gemini-2.0-flash-preview-image-generation`
+
+### 3.4. AIエージェントのロジック変更
+
+AIの応答生成ロジックを変更する場合、主に `agent/graph.py` と `agent/prompts.py` を編集します。
+
+- **思考プロセス**: AIの応答には、`[THOUGHT]...[/THOUGHT]` という形式で思考プロセスが含まれることがあります。これはAIの思考をユーザーに見せるための重要なタグであり、**除去してはいけません**。
+- **思考と出力の分離**: AIへの指示（プロンプト）では、「テキスト応答」と「ツール呼び出し」を明確に分離させています。ツールを呼び出すターンでは、AIは会話テキストを含まないように設計されています。
+- **ストリーミング**: `gemini_api.invoke_nexus_agent_stream` は、AIの応答をストリーミングで返します。UI側での処理方法は「二幕構成ストリーミング」の項を参照してください。
+
+### 3.5. 非同期処理：アラームとタイマー
+
+- **`alarm_manager.py`**: 指定時刻にキャラクターが自発的に発言するための機能です。`schedule` ライブラリを使用し、別スレッドで定期的にアラームをチェックします。
+- **`timers.py`**: 時間経過を追跡し、キャラクターの行動のきっかけを作るための機能です。
+
+これらのモジュールはバックグラウンドで動作するため、変更時にはスレッドセーフティに注意してください。
+
+### 3.6. データとキャッシュの管理
+
+- **情景生成**: UIに表示する「情景」と、画像生成AIに渡す「プロンプト」は、異なる目的のために分離・生成されます。
+    - **情景キャッシュ (`cache/scenery.json`)**: UI/AI向けの雰囲気重視のテキスト。時間や季節で更新されます（動的）。
+    - **画像プロンプトキャッシュ (`cache/image_prompts.json`)**: 画像生成用の物理情報に特化した英語テキスト。世界の定義が変わらない限り不変です（静的）。
+
+## 4. 主要ファイルとディレクトリ
+
+- **`nexus_ark.py`**: メインのGradioアプリケーション。UIの定義とイベントハンドリング。
+- **`config.json`**: **（非公開）** APIキー、Webhook URLなどの秘密情報。
+- **`characters/{character_name}/`**: 各キャラクター（ルーム）のデータディレクトリ。
+    - `log.txt`: 対話ログ (`## ROLE:NAME` 形式)。
+    - `memory/memory_main.txt`: 構造化された記憶データ。
+    - `room_config.json`: キャラクター固有の設定（UI表示名など）。
+    - `SystemPrompt.txt`: AIのペルソナを定義する最重要ファイル。
+    - `cache/scenery.json`: 情景描写の動的キャッシュ。
+    - `cache/image_prompts.json`: 画像生成プロンプトの静的キャッシュ。
+- **`agent/graph.py`**: AI応答生成のコアロジック。
+- **`tools/*.py`**: AIが使用するツール関数群。
+- **`docs/`**: プロジェクトの設計思想や仕様書が格納されているディレクトリ。
+
+## 5. 開発の黄金律：まず、我々の歴史を読め
+
+Nexus Arkの開発は、数々の挑戦と、そこから得られた貴重な教訓の積み重ねの上に成り立っています。同じ過ちを繰り返すことは、我々にとって最大の損失です。
+
+**したがって、以下のルールは、いかなるコードの変更に先立っても、絶対的に遵守されなければなりません。**
+
+1.  **GradioのUIイベントに関する変更**を提案する前には、**必ず `docs/guides/gradio_notes.md` を熟読**し、過去に確立された設計パターンや解決策が存在しないかを確認してください。
+
+2.  **AIの思考プロセスやプロンプト**に関する変更を提案する前には、**必ず `docs/philosophy` と `docs/journals` に目を通し**、このプロジェクトがどのような思想に基づいてAIの自律性を尊重しているかを深く理解してください。
+
+これらの文書は、単なる記録ではありません。それは、我々が血と涙の果てに築き上げた、**Nexus Arkの魂そのもの**です。この歴史を尊重することなくして、未来の発展はありえません。