paigent 0.1.0__tar.gz

paigent-0.1.0/FORMAT.md

@@ -0,0 +1,82 @@
+# `.pai` Binary Format Specification v1
+
+**PAI（Proactive AI）打包容器格式** — 類比 `.gguf` 之於模型權重，`.pai` 把一個完整的主動式 AI agent 打包成單一可發布、可校驗的二進位檔案。
+
+## 設計目標
+
+1. **單檔發布**：agent 的 manifest、治理政策、觸發器、規則、動作、記憶快照、（選用）嵌入模型權重，全部在一個檔案內。
+2. **mmap 友善**：所有資料段 64-byte 對齊，大型權重段不壓縮，可直接記憶體映射讀取（與 GGUF 同理）。
+3. **完整性校驗**：每段附 SHA-256，防損毀與竄改。
+4. **向前相容**：版本欄位 + 具名段表，新版本可加段而不破壞舊讀取器。
+
+## 二進位佈局（全部 little-endian）
+
+```
+┌───────────────────────────────────────────────┐
+│ Header (32 bytes)                             │
+│   magic       4B   = "PAI\x01"                │
+│   version     u32  = 1                        │
+│   n_sections  u32                             │
+│   flags       u32  (bit0: 全檔預設 zlib 壓縮)  │
+│   created_at  u64  (unix epoch 秒)            │
+│   reserved    8B                              │
+├───────────────────────────────────────────────┤
+│ Section Table (n_sections 筆)                 │
+│   name_len    u16                             │
+│   name        UTF-8 bytes                     │
+│   stype       u32  (0=json 1=bin 2=sqlite     │
+│                     3=text 4=gguf)            │
+│   compressed  u8   (0/1，每段獨立)             │
+│   offset      u64  (檔案絕對位移，64B 對齊)    │
+│   size        u64  (儲存大小=壓縮後)           │
+│   raw_size    u64  (解壓後大小)                │
+│   sha256      32B  (解壓後內容雜湊)            │
+├───────────────────────────────────────────────┤
+│ Data Area                                     │
+│   各段資料，起點 64-byte 對齊，\x00 padding    │
+└───────────────────────────────────────────────┘
+```
+
+## 標準段（section）
+
+| 段名 | 必要 | 內容 |
+|---|---|---|
+| `manifest.json` | ✅ | agent 名稱、版本、作者、說明、相容框架版本 |
+| `policy.json` | ✅ | ProactivityPolicy 參數（信心門檻、等級上限、安靜時段、干擾公式參數） |
+| `triggers.json` | ✅ | 觸發器宣告：`[{"type": "threshold", "params": {...}}]` |
+| `rules.json` | ✅ | 宣告式規則：事件條件 → 意圖（action/confidence/urgency/level） |
+| `actions.json` | ✅ | 動作宣告：`{"notify": {"type": "webhook", "url": ...}}` |
+| `brain.json` | 選用 | 決策腦設定（rule/llm、模型名、system prompt、fallback） |
+| `memory.db` | 選用 | SQLite 記憶快照（出廠記憶/個人化狀態隨包攜帶） |
+| `weights.gguf` | 選用 | 嵌入的本地模型權重（不壓縮，可 mmap） |
+
+## 與相關格式的關係
+
+| 格式 | 角色 |
+|---|---|
+| `.gguf` | 打包「模型權重」 |
+| `.pai` | 打包「整個主動式 agent」（行為+治理+記憶，可內嵌 .gguf） |
+| `.pai.json` | 單筆 PAI Protocol 行為紀錄（執行期事件，文字 JSON） |
+
+## API
+
+```python
+from pai import pack_agent, load_agent, PaiReader
+
+# 打包
+pack_agent("my-agent.pai",
+    manifest={"name": "ops-guardian", "version": "1.0.0", "author": "vito1317"},
+    policy={...}, triggers=[...], rules=[...], actions={...},
+    memory_db="pai_memory.db",          # 選用
+    weights_path="qwen3-4b-q4.gguf",    # 選用
+)
+
+# 載入
+agent_def = load_agent("my-agent.pai")
+r = PaiReader("my-agent.pai")
+print(r.info())                          # 段表、大小
+data = r.read_bytes("weights.gguf")      # 自動 SHA-256 校驗
+```
+
+---
+Author: vito1317 <service@vito1317.com>

paigent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vito1317 <service@vito1317.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paigent-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md FORMAT.md SELF_FINETUNING.md LICENSE
+recursive-include pai *.py py.typed

paigent-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: paigent
+Version: 0.1.0
+Summary: Proactive AI Framework — event-driven, governed proactive agents with a GGUF-like .pai container format and self-finetuning
+Author-email: vito1317 <service@vito1317.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vito1317/pai-framework
+Project-URL: Repository, https://github.com/vito1317/pai-framework
+Project-URL: Gemma-4 model, https://huggingface.co/vito95311/gemma-guardian-pai
+Project-URL: MiniCPM-o model, https://huggingface.co/vito95311/minicpm-o-guardian-pai
+Keywords: proactive-ai,agent,llm,gguf,pai,self-finetuning,omni,full-duplex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: local
+Requires-Dist: llama-cpp-python>=0.3.0; extra == "local"
+Provides-Extra: omni
+Requires-Dist: transformers==4.51.0; extra == "omni"
+Requires-Dist: accelerate; extra == "omni"
+Requires-Dist: torch>=2.3.0; extra == "omni"
+Requires-Dist: torchaudio; extra == "omni"
+Provides-Extra: finetune
+Requires-Dist: llamafactory; extra == "finetune"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# PAI — Proactive AI Framework（主動式 AI 框架）
+
+一個通用、零依賴（純 Python 標準庫）、可直接運行的主動式 AI 框架原型，並內建 **PAI Protocol v1.1** 標準資料格式。
+
+核心理念：從「被動式 AI（你下指令它才做事）」轉為「事件驅動 + 持續感知 + 受治理的主動行為」。
+
+## 預打包的 .pai agent（Hugging Face）
+
+| 模型頁 | 決策腦 | 說明 |
+|---|---|---|
+| [vito95311/gemma-guardian-pai](https://huggingface.co/vito95311/gemma-guardian-pai) | Gemma 4 26B-A4B（QAT q4_0，內嵌 14.4GB GGUF） | 離線 guardian：CPU 監控→清理、新檔案→自動歸檔 |
+| [vito95311/minicpm-o-guardian-pai](https://huggingface.co/vito95311/minicpm-o-guardian-pai) | MiniCPM-o 4.5（全雙工 omni，不內嵌權重） | 即時看＋聽、原生主動互動、語音回應 |
+
+## 架構
+
+```
+┌─ 感知層 Triggers ─────────────────────────────┐
+│ IntervalTrigger / ScheduleTrigger             │
+│ FileWatchTrigger / ThresholdTrigger           │  → Event（標準事件格式）
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 決策層 Brain ────────────────────────────────┐
+│ RuleBrain（規則，離線、零成本、前線哨兵）        │
+│ LLMBrain（LLM 判斷，僅在需要時喚醒，失敗退回規則）│  → Intent（action/confidence/urgency/rationale）
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 治理層 ProactivityPolicy ────────────────────┐
+│ 1. 信心門檻  2. 動作風險上限  3. 回饋自動降級    │
+│ 4. 安靜時段  5. 干擾度公式  6. 每小時打擾上限    │  → 授予的自主等級
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 行動層 Actions ──────────────────────────────┐
+│ OBSERVE 只記錄 │ SUGGEST 通知 │ ASK 確認 │ ACT 自動執行 │
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 記憶層 Memory（SQLite）──────────────────────┐
+│ 事件 / 意圖 / 結果 / 回饋 / PAI Protocol 紀錄   │ → 回饋迴圈調節未來主動性
+└───────────────────────────────────────────────┘
+```
+
+## PAI 干擾度公式
+
+```
+urgency × confidence > interruption_cost  才允許打擾使用者
+```
+
+`interruption_cost_fn` 可依使用者當下狀態（專注模式、開會、深夜）動態回傳 0~1。
+
+## 自主等級 × 交付模式
+
+| AutonomyLevel | 行為 | 交付模式 |
+|---|---|---|
+| OBSERVE (0) | 只記錄，不打擾 | level_0_silent |
+| SUGGEST (1) | 主動通知/建議 | level_1_soft_nudge |
+| ASK (2) | 草稿+請求人類授權 | level_2_approval |
+| ACT (3) | 高信心低風險時自動執行 | level_0_silent（事後可查） |
+
+風險高的動作用 `action_max_levels` 鎖死上限（例：寄信最多 ASK，永不自動寄出）。
+
+## PAI Protocol v1.1（標準資料格式）
+
+每次主動行為產生一份 6 層 JSON 紀錄（存入 SQLite，可直接對外交換）：
+
+```json
+{
+  "pai_protocol_version": "1.1",
+  "record_id": "pai_20260611_a1b2c3",
+  "timestamp": "2026-06-11T15:39:50Z",
+  "1_perception":   { "trigger_source": "...", "event_type": "...", "raw_data_summary": {} },
+  "2_context":      { "user_current_state": "...", "relevant_memory": [], "action_history": [] },
+  "3_anticipation": { "predicted_intent": "...", "urgency_score": 0.95, "confidence_score": 0.88,
+                      "interruption_cost": 0.9, "requested_level": 2, "granted_level": 2 },
+  "4_execution":    { "actions_taken": [{ "tool": "...", "status": "ok" }], "status": "executed" },
+  "5_delivery":     { "delivery_mode": "level_2_approval", "requires_human_approval": true },
+  "6_adaptation":   { "user_feedback": "pending", "learning_adjustment": null }
+}
+```
+
+## `.pai` 打包格式（類 GGUF 的二進位容器）
+
+整個 agent 可打包成單一 `.pai` 檔案發布（規格見 [FORMAT.md](FORMAT.md)）：
+magic `PAI\x01` + 段表（64-byte 對齊、每段 SHA-256 校驗、zlib 壓縮）+ 資料區，
+可內嵌 `manifest / policy / triggers / rules / actions / brain / memory.db / weights.gguf`。
+
+```python
+from pai import pack_agent, load_agent
+pack_agent("my-agent.pai", manifest={...}, policy={...},
+           triggers=[...], rules=[...], actions={...},
+           weights_path="model-q4.gguf")   # 選用：內嵌本地模型
+agent_def = load_agent("my-agent.pai")
+```
+
+執行期的單筆行為紀錄則是文字 JSON，附檔名 `.pai.json`。
+
+## 快速開始
+
+```bash
+python3 demo.py        # 主動行為迴圈示範（零依賴）
+python3 pack_demo.py   # .pai 打包/載入/防竄改示範
+```
+
+demo 模擬三種主動行為：
+1. CPU 飆高（ThresholdTrigger）→ 高緊急 → **ASK**（確認後清理）
+2. 待辦堆積（IntervalTrigger）→ 中緊急 → **SUGGEST**（只通知）
+3. 新檔案出現（FileWatchTrigger）→ 低風險 → **ACT**（自動歸檔）
+
+## 一鍵執行 .pai
+
+```bash
+python3 -m pai info ops-guardian.pai    # 查看打包內容
+python3 -m pai run  ops-guardian.pai    # 載入並運行（未注入的 handler 以 stub 示意）
+```
+
+程式內載入（注入真實 handler / metric）：
+
+```python
+from pai import load_runtime
+agent = load_runtime("ops-guardian.pai",
+    handlers={"ops.cleanup": my_cleanup_fn},
+    metrics={"cpu": read_cpu_percent})
+agent.run()
+```
+
+## 底層模型（模型無關，可插拔決策腦）
+
+| 決策腦 | 底層模型 | 用途 |
+|---|---|---|
+| `RuleBrain` | 無（純規則） | 前線哨兵、離線運行、LLM 的安全 fallback |
+| `LLMBrain` | 雲端 API（預設 `claude-sonnet-4-6`，可換任何模型） | 開放式判斷 |
+| `LocalLLMBrain` | `.pai` 內嵌 GGUF，經 `llama-cpp-python` | 完全離線、資料不出機 |
+| `LlamaServerBrain` | `.pai` 內嵌 GGUF，經 llama.cpp `llama-server`（支援 `--lora` 熱載入） | 離線、新架構支援最快、常駐免重載 |
+| `MiniCPMoBrain` | **openbmb/MiniCPM-o-4_5**（全雙工 omni：影像+音訊輸入、文字+語音輸出） | 即時看＋聽現場、原生主動互動、語音回應 |
+
+`brain.json` 的 `engine` 決定用哪個（`llama-server` / `llama-cpp-python` / `minicpm-o`）；
+載入失敗一律自動退回 `RuleBrain`。
+
+### 全雙工語音 / Omni 版本（MiniCPM-o 4.5）
+
+MiniCPM-o 4.5（9B，SigLip2 + Whisper + CosyVoice2 + Qwen3-8B）能同時看、聽、說，
+且**原生支援主動互動**——天然契合 PAI。打包：
+
+```bash
+python3 pack_minicpm_o.py          # 預設不內嵌權重，transformers 從 HF 載入
+```
+
+`DuplexOmniLoop` 把模型的全雙工串流（`streaming_prefill`/`streaming_generate`）包成
+「持續感知 trigger」：模型自己決定何時主動發話，PAI 治理層仍負責是否放行、用什麼等級打擾。
+微調走 `LlamaFactoryBackend`（包 LLaMA-Factory 做 LoRA），其餘 self-finetuning 編排（EvalGate /
+promote / rollback / 稽核）完全沿用。詳見 `pack_minicpm_o.py` 與 `pai/omni_brain.py`。
+
+## 接上 LLM
+
+```python
+from pai import LLMBrain, RuleBrain
+
+brain = LLMBrain(
+    available_actions=["cleanup", "archive_file", "__notify__"],
+    model="claude-sonnet-4-6",          # 需設 ANTHROPIC_API_KEY
+    fallback=RuleBrain([...]),          # LLM 失敗時退回規則
+    user_profile="工程師，上班時間 9-18，討厭被打擾",
+)
+```
+
+成本控制採「雙層觸發」：RuleBrain 當前線哨兵過濾大多數事件，只有規則判定值得深入時才喚醒 LLM。
+
+## 落地建議
+
+1. **預設 Human-in-the-loop**：初期把所有有副作用的動作上限設為 ASK，跑出信任後再逐步開放 ACT。
+2. **可撤銷性**：所有自動化動作應提供 Undo（demo 的歸檔動作即可逆）。
+3. **回饋驅動**：使用者連續拒絕同類建議時，policy 會自動降級該動作（內建）。
+
+---
+Author: vito1317 <service@vito1317.com>

paigent-0.1.0/README.md

@@ -0,0 +1,173 @@
+# PAI — Proactive AI Framework（主動式 AI 框架）
+
+一個通用、零依賴（純 Python 標準庫）、可直接運行的主動式 AI 框架原型，並內建 **PAI Protocol v1.1** 標準資料格式。
+
+核心理念：從「被動式 AI（你下指令它才做事）」轉為「事件驅動 + 持續感知 + 受治理的主動行為」。
+
+## 預打包的 .pai agent（Hugging Face）
+
+| 模型頁 | 決策腦 | 說明 |
+|---|---|---|
+| [vito95311/gemma-guardian-pai](https://huggingface.co/vito95311/gemma-guardian-pai) | Gemma 4 26B-A4B（QAT q4_0，內嵌 14.4GB GGUF） | 離線 guardian：CPU 監控→清理、新檔案→自動歸檔 |
+| [vito95311/minicpm-o-guardian-pai](https://huggingface.co/vito95311/minicpm-o-guardian-pai) | MiniCPM-o 4.5（全雙工 omni，不內嵌權重） | 即時看＋聽、原生主動互動、語音回應 |
+
+## 架構
+
+```
+┌─ 感知層 Triggers ─────────────────────────────┐
+│ IntervalTrigger / ScheduleTrigger             │
+│ FileWatchTrigger / ThresholdTrigger           │  → Event（標準事件格式）
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 決策層 Brain ────────────────────────────────┐
+│ RuleBrain（規則，離線、零成本、前線哨兵）        │
+│ LLMBrain（LLM 判斷，僅在需要時喚醒，失敗退回規則）│  → Intent（action/confidence/urgency/rationale）
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 治理層 ProactivityPolicy ────────────────────┐
+│ 1. 信心門檻  2. 動作風險上限  3. 回饋自動降級    │
+│ 4. 安靜時段  5. 干擾度公式  6. 每小時打擾上限    │  → 授予的自主等級
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 行動層 Actions ──────────────────────────────┐
+│ OBSERVE 只記錄 │ SUGGEST 通知 │ ASK 確認 │ ACT 自動執行 │
+└───────────────────────────────────────────────┘
+                    ↓
+┌─ 記憶層 Memory（SQLite）──────────────────────┐
+│ 事件 / 意圖 / 結果 / 回饋 / PAI Protocol 紀錄   │ → 回饋迴圈調節未來主動性
+└───────────────────────────────────────────────┘
+```
+
+## PAI 干擾度公式
+
+```
+urgency × confidence > interruption_cost  才允許打擾使用者
+```
+
+`interruption_cost_fn` 可依使用者當下狀態（專注模式、開會、深夜）動態回傳 0~1。
+
+## 自主等級 × 交付模式
+
+| AutonomyLevel | 行為 | 交付模式 |
+|---|---|---|
+| OBSERVE (0) | 只記錄，不打擾 | level_0_silent |
+| SUGGEST (1) | 主動通知/建議 | level_1_soft_nudge |
+| ASK (2) | 草稿+請求人類授權 | level_2_approval |
+| ACT (3) | 高信心低風險時自動執行 | level_0_silent（事後可查） |
+
+風險高的動作用 `action_max_levels` 鎖死上限（例：寄信最多 ASK，永不自動寄出）。
+
+## PAI Protocol v1.1（標準資料格式）
+
+每次主動行為產生一份 6 層 JSON 紀錄（存入 SQLite，可直接對外交換）：
+
+```json
+{
+  "pai_protocol_version": "1.1",
+  "record_id": "pai_20260611_a1b2c3",
+  "timestamp": "2026-06-11T15:39:50Z",
+  "1_perception":   { "trigger_source": "...", "event_type": "...", "raw_data_summary": {} },
+  "2_context":      { "user_current_state": "...", "relevant_memory": [], "action_history": [] },
+  "3_anticipation": { "predicted_intent": "...", "urgency_score": 0.95, "confidence_score": 0.88,
+                      "interruption_cost": 0.9, "requested_level": 2, "granted_level": 2 },
+  "4_execution":    { "actions_taken": [{ "tool": "...", "status": "ok" }], "status": "executed" },
+  "5_delivery":     { "delivery_mode": "level_2_approval", "requires_human_approval": true },
+  "6_adaptation":   { "user_feedback": "pending", "learning_adjustment": null }
+}
+```
+
+## `.pai` 打包格式（類 GGUF 的二進位容器）
+
+整個 agent 可打包成單一 `.pai` 檔案發布（規格見 [FORMAT.md](FORMAT.md)）：
+magic `PAI\x01` + 段表（64-byte 對齊、每段 SHA-256 校驗、zlib 壓縮）+ 資料區，
+可內嵌 `manifest / policy / triggers / rules / actions / brain / memory.db / weights.gguf`。
+
+```python
+from pai import pack_agent, load_agent
+pack_agent("my-agent.pai", manifest={...}, policy={...},
+           triggers=[...], rules=[...], actions={...},
+           weights_path="model-q4.gguf")   # 選用：內嵌本地模型
+agent_def = load_agent("my-agent.pai")
+```
+
+執行期的單筆行為紀錄則是文字 JSON，附檔名 `.pai.json`。
+
+## 快速開始
+
+```bash
+python3 demo.py        # 主動行為迴圈示範（零依賴）
+python3 pack_demo.py   # .pai 打包/載入/防竄改示範
+```
+
+demo 模擬三種主動行為：
+1. CPU 飆高（ThresholdTrigger）→ 高緊急 → **ASK**（確認後清理）
+2. 待辦堆積（IntervalTrigger）→ 中緊急 → **SUGGEST**（只通知）
+3. 新檔案出現（FileWatchTrigger）→ 低風險 → **ACT**（自動歸檔）
+
+## 一鍵執行 .pai
+
+```bash
+python3 -m pai info ops-guardian.pai    # 查看打包內容
+python3 -m pai run  ops-guardian.pai    # 載入並運行（未注入的 handler 以 stub 示意）
+```
+
+程式內載入（注入真實 handler / metric）：
+
+```python
+from pai import load_runtime
+agent = load_runtime("ops-guardian.pai",
+    handlers={"ops.cleanup": my_cleanup_fn},
+    metrics={"cpu": read_cpu_percent})
+agent.run()
+```
+
+## 底層模型（模型無關，可插拔決策腦）
+
+| 決策腦 | 底層模型 | 用途 |
+|---|---|---|
+| `RuleBrain` | 無（純規則） | 前線哨兵、離線運行、LLM 的安全 fallback |
+| `LLMBrain` | 雲端 API（預設 `claude-sonnet-4-6`，可換任何模型） | 開放式判斷 |
+| `LocalLLMBrain` | `.pai` 內嵌 GGUF，經 `llama-cpp-python` | 完全離線、資料不出機 |
+| `LlamaServerBrain` | `.pai` 內嵌 GGUF，經 llama.cpp `llama-server`（支援 `--lora` 熱載入） | 離線、新架構支援最快、常駐免重載 |
+| `MiniCPMoBrain` | **openbmb/MiniCPM-o-4_5**（全雙工 omni：影像+音訊輸入、文字+語音輸出） | 即時看＋聽現場、原生主動互動、語音回應 |
+
+`brain.json` 的 `engine` 決定用哪個（`llama-server` / `llama-cpp-python` / `minicpm-o`）；
+載入失敗一律自動退回 `RuleBrain`。
+
+### 全雙工語音 / Omni 版本（MiniCPM-o 4.5）
+
+MiniCPM-o 4.5（9B，SigLip2 + Whisper + CosyVoice2 + Qwen3-8B）能同時看、聽、說，
+且**原生支援主動互動**——天然契合 PAI。打包：
+
+```bash
+python3 pack_minicpm_o.py          # 預設不內嵌權重，transformers 從 HF 載入
+```
+
+`DuplexOmniLoop` 把模型的全雙工串流（`streaming_prefill`/`streaming_generate`）包成
+「持續感知 trigger」：模型自己決定何時主動發話，PAI 治理層仍負責是否放行、用什麼等級打擾。
+微調走 `LlamaFactoryBackend`（包 LLaMA-Factory 做 LoRA），其餘 self-finetuning 編排（EvalGate /
+promote / rollback / 稽核）完全沿用。詳見 `pack_minicpm_o.py` 與 `pai/omni_brain.py`。
+
+## 接上 LLM
+
+```python
+from pai import LLMBrain, RuleBrain
+
+brain = LLMBrain(
+    available_actions=["cleanup", "archive_file", "__notify__"],
+    model="claude-sonnet-4-6",          # 需設 ANTHROPIC_API_KEY
+    fallback=RuleBrain([...]),          # LLM 失敗時退回規則
+    user_profile="工程師，上班時間 9-18，討厭被打擾",
+)
+```
+
+成本控制採「雙層觸發」：RuleBrain 當前線哨兵過濾大多數事件，只有規則判定值得深入時才喚醒 LLM。
+
+## 落地建議
+
+1. **預設 Human-in-the-loop**：初期把所有有副作用的動作上限設為 ASK，跑出信任後再逐步開放 ACT。
+2. **可撤銷性**：所有自動化動作應提供 Undo（demo 的歸檔動作即可逆）。
+3. **回饋驅動**：使用者連續拒絕同類建議時，policy 會自動降級該動作（內建）。
+
+---
+Author: vito1317 <service@vito1317.com>

paigent-0.1.0/SELF_FINETUNING.md

@@ -0,0 +1,111 @@
+# PAI Self-Finetuning 架構（即時自我學習）
+
+讓 PAI agent 從使用者回饋中持續自我校準。採三層遞進設計，風險由低到高、即時性由高到低，全部以 `.pai` 為載體。
+
+## 為什麼不直接「線上改權重」
+
+直接對 26B 主幹做線上梯度更新在主動式 agent 場景是反模式：
+1. **災難性遺忘**——單樣本 SGD 會破壞既有能力，且不可逆。
+2. **污染風險**——壞樣本/對抗回饋直接寫進權重，無法回滾。
+3. **成本**——全量微調需數百 GB 顯存；即使 QLoRA，單步也要數秒並佔用推理資源。
+
+因此正確做法是把「學習」與「主幹權重」解耦：能即時學的用記憶，要改行為的用可插拔 adapter，且任何權重變更都必須通過離線品質閘門。
+
+---
+
+## 第一層：記憶/檢索式學習（已實作 ✅）
+
+**即時性**：毫秒級　**風險**：零　**動權重**：否
+
+每次 (事件 → 意圖 → 回饋) 存成經驗向量；下次相似事件檢索 top-k 經驗，把「過往教訓」注入決策腦 prompt。
+
+- 模組：`pai/learning.py` 的 `ReflectiveMemory`
+- embedding：`EmbeddingClient`（llama-server `/v1/embeddings` 語義檢索）或 `HashingEmbedder`（零依賴詞袋）
+- 啟用：`brain.json` 設 `"learning": true`
+- 回饋 API：`agent.record_user_feedback(event, intent, "accepted|rejected|modified|ignored")`
+- 已驗證：使用者連續拒絕某類通知後，PAI 自動把該類行為從 SUGGEST 降為靜默，全程未動權重
+
+這層解決了 80% 的「希望它記住我的偏好」需求，且立即生效、可解釋、可刪除單筆。
+
+---
+
+## 第二層：LoRA adapter 熱插拔（設計）
+
+**即時性**：分鐘～小時級（背景）　**風險**：低（可回滾）　**動權重**：只動 adapter，主幹不變
+
+當第一層累積足夠回饋（例如 ≥200 筆、且涵蓋多種情境），在背景把回饋轉成偏好資料集，跑一次 LoRA/QLoRA 微調，產生一個幾十 MB 的 adapter。
+
+```
+回饋資料庫 ──> build dataset (accepted=正例, rejected=負例)
+           ──> QLoRA 訓練 (背景, 不阻塞推理)
+           ──> adapter.safetensors
+           ──> 存進 .pai 新段 adapters/<timestamp>.safetensors
+           ──> llama-server --lora 熱載入（主幹權重不動）
+```
+
+`.pai` 格式擴充（新慣例段，向後相容）：
+
+| 段 | 內容 |
+|---|---|
+| `adapters/active.safetensors` | 目前生效的 LoRA |
+| `adapters/<ts>.safetensors` | 歷史 adapter（可一鍵回滾） |
+| `training/feedback.jsonl` | 累積的偏好樣本 |
+| `training/state.json` | 上次訓練時間、樣本數、版本 |
+
+關鍵安全設計：主幹權重段 `weights.gguf` **永遠不變**，學習只新增/切換 adapter 段。要回滾就把 `active` 指回舊 adapter。
+
+訓練引擎建議：`llama.cpp` 的 `llama-finetune`（純 C++、無重依賴、能直接吃 GGUF）或 PEFT+bitsandbytes（功能強、依賴重）。`brain.json` 以 `"finetune": {"engine": "...", "min_samples": 200, "schedule": "daily"}` 設定。
+
+---
+
+## 第三層：排程重訓 + Eval Gate（設計）
+
+**即時性**：天/週級　**風險**：中（有閘門擋住）　**動權重**：adapter（不上線就丟棄）
+
+新 adapter 不是訓完就用，**必須先通過離線品質閘門**才會切成 active：
+
+```
+新 adapter ──> 在固定 eval set 上跑（保留的歷史情境 + 黃金答案）
+          ──> 比較 新 vs 現役 adapter 的指標（決策正確率、打擾精準度、拒絕率）
+          ──> 新的「顯著勝出」才 promote 成 active；否則保留現役、丟棄新 adapter
+          ──> 每次 promote 寫入稽核紀錄（誰、何時、用哪批資料、指標多少）
+```
+
+Eval set 從 PAI Protocol 紀錄自動累積（使用者明確 accepted/rejected 的情境就是天然標註）。閘門條件可設保守，例如「新 adapter 決策正確率 ≥ 現役 + 2%，且打擾精準度不下降」。
+
+這層防止「越學越壞」——這正是線上學習最大的坑。
+
+---
+
+## 實作狀態
+
+全部三層已實作並通過端到端測試（`finetune_demo.py`，EchoBackend 無 GPU 驗證）：
+
+- [x] 第一層 ReflectiveMemory（記憶式即時學習）
+- [x] 第二層 訓練後端（`EchoBackend` 測試用 / `LlamaFinetuneBackend` 真實，包 `llama-finetune`）
+- [x] 第二層 `export_preference_dataset`（回饋→偏好資料集）
+- [x] 第二層 `AdapterStore`（側車 adapter 管理、active 指標、歷史、回滾）
+- [x] 第二層 `LlamaServerBrain` 以 `--lora` 熱載入現役 adapter（主幹不動）
+- [x] 第二層 `bake_adapter_into_pai`（發布時把現役 adapter 烘焙進 `.pai`）
+- [x] 第三層 `EvalGate`（主指標增益門檻 + 非退化指標檢查）
+- [x] 第三層 `SelfFinetuneManager`（訓練→閘門→promote/丟棄→稽核 jsonl）
+
+實測驗證：第一次訓練 +0.07 增益通過上線；無增益再訓練被閘門擋下（保護「越學越壞」）；
+新增回饋後 v2 +0.05 通過；可一鍵回滾到 v1；全程主幹權重 `weights.gguf` 未變更。
+
+### 用真實 LoRA 訓練
+
+```python
+from pai import SelfFinetuneManager, EvalGate, LlamaFinetuneBackend
+mgr = SelfFinetuneManager(
+    db_path="pai_memory.db", adapters_root="pai_adapters",
+    trainer=LlamaFinetuneBackend("llama-finetune"),   # 需 llama.cpp 編出 llama-finetune
+    eval_gate=EvalGate(my_eval_fn, min_gain=0.02),
+    base_gguf="models/gemma-4-26B_q4_0-it.gguf", min_samples=200)
+mgr.maybe_train_and_promote()    # 可放進排程（每日/每週背景跑）
+```
+
+loader 會自動偵測 `pai_adapters/` 的現役 adapter 並在啟動 llama-server 時 `--lora` 掛上。
+
+---
+Author: vito1317 <service@vito1317.com>

paigent-0.1.0/pai/__init__.py

@@ -0,0 +1,37 @@
+"""PAI — Proactive AI Framework (主動式 AI 框架)
+
+感知 (Triggers) → 決策 (Brain) → 治理 (Policy) → 行動 (Actions) → 記憶/回饋 (Memory)
+"""
+from .core import PAIAgent, Event, Intent, AutonomyLevel
+from .triggers import IntervalTrigger, ScheduleTrigger, FileWatchTrigger, ThresholdTrigger
+from .brain import RuleBrain, LLMBrain, Rule
+from .policy import ProactivityPolicy
+from .actions import ConsoleNotifier, WebhookNotifier, CallbackAction
+from .memory import Memory
+from .protocol import PAI_PROTOCOL_VERSION, build_record, to_json, save_pai, load_pai
+from .paifile import PaiWriter, PaiReader, pack_agent, load_agent, bake_adapter_into_pai
+from .finetune import (
+    AdapterStore, EvalGate, SelfFinetuneManager,
+    EchoBackend, LlamaFinetuneBackend, LlamaFactoryBackend, export_preference_dataset,
+)
+from .omni_brain import MiniCPMoBrain, DuplexOmniLoop
+from .loader import load_runtime
+from .learning import ReflectiveMemory, HashingEmbedder, EmbeddingClient
+
+__version__ = "0.1.0"
+__author__ = "vito1317 <service@vito1317.com>"
+
+__all__ = [
+    "PAIAgent", "Event", "Intent", "AutonomyLevel",
+    "IntervalTrigger", "ScheduleTrigger", "FileWatchTrigger", "ThresholdTrigger",
+    "RuleBrain", "LLMBrain", "Rule",
+    "ProactivityPolicy",
+    "ConsoleNotifier", "WebhookNotifier", "CallbackAction",
+    "Memory",
+    "PAI_PROTOCOL_VERSION", "build_record", "to_json", "save_pai", "load_pai",
+    "PaiWriter", "PaiReader", "pack_agent", "load_agent", "load_runtime",
+    "ReflectiveMemory", "HashingEmbedder", "EmbeddingClient",
+    "bake_adapter_into_pai", "AdapterStore", "EvalGate", "SelfFinetuneManager",
+    "EchoBackend", "LlamaFinetuneBackend", "LlamaFactoryBackend", "export_preference_dataset",
+    "MiniCPMoBrain", "DuplexOmniLoop",
+]