# AI Self-Loop 骨架

能自我驅動的 AI 處理系統：接收輸入 → 呼叫 LLM 處理 → 評估品質 → 不達標自動修正再跑，
直到達標（`done`）或送人工審核（`review`）。

起步領域：以 `https://www.pluspay.com.tw/` 為起點，自動爬出站內地圖並做逐頁健檢。

## 快速開始

```bash
pip install -r requirements.txt
# 需要本機 Ollama 在 http://localhost:11434，且有 environments.yaml 指定的模型

python -m src.pipeline          # 預設：seed 一筆任務 + 處理（驗收用）
python -m src.pipeline --seed   # 只放任務進佇列
python -m src.pipeline --run    # 只處理 pending 任務
```

產出：
- `output/sitemap.json` —— 站內頁面地圖
- `output/health_report.json` —— 每頁健檢報告
- `review_queue/task_<id>.json` —— 送審任務（若有）

## 架構：兩個分層

| 層 | 介面 | 職責 | 起步實作 |
|----|------|------|----------|
| **Driver**（怎麼做） | `BaseDriver.connect/execute` | 連線與操作目標，無領域判斷 | `drivers/api_client.py`（HTTP） |
| **Agent**（做什麼） | `BaseAgent.run` | 領域 AI 判斷，呼叫 Driver + Loop 引擎 | `agents/site_health.py` |

要加 web(Playwright)/mobile driver 時，agent 不用動。

## Loop 引擎（五元件，`src/core/`）

1. **Context Assembler** — 決定哪些資訊送進 LLM（寧可少不要雜）
2. **Prompt Builder** — 從 `prompts/*.yaml` 用 Jinja2 渲染；重試時注入上一輪 feedback
3. **Output Judge** — 統一輸出 `passed/score/issues/suggestions`（先 rule-based）
4. **Feedback Builder** — 把 Judge 結果轉成下一輪的具體修正指令
5. **Loop Controller** — 重試上限（預設 3）+ 每次嘗試完整記錄 + Circuit Breaker

## LLM 後端（`src/llm/`）

- `LLMBackend`：`call(prompt, system)` / `is_available()`
- `OllamaBackend`：**每次 call 強制帶 `num_ctx`（預設 32768）**，不吃 Ollama 預設的 4K
- `LLMRouter`：多 backend 依序用第一個可用的

## Task Queue（`src/db/`，SQLite）

`tasks`（狀態）/ `attempts`（每次嘗試的完整記錄）/ `results`（定版輸出）。
取任務用原子 compare-and-swap 防重複。

## 設定外部化（`config/`）

- `environments.yaml` —— 各環境 URL/端點/Loop 參數（明文，先不加密）
- `credentials.example.yaml` —— 憑證佔位；複製成 `credentials.yaml` 填真值
  （已 gitignore）。讀取優先序：環境變數 > credentials.yaml > 預設。

## 驗收

放一筆任務 → 跑 `pipeline.py` → 任務 `pending → done/review` → `output/` 出現結果。
已通過：3 頁限縮實跑得到 `done`，sitemap 與 health_report 落地。

## 尚未做（刻意保留為下一步）

- **LLM-as-Judge**（build order #9）：目前 Judge 是 rule-based；可加一層讓 LLM
  評估 issue 的「對人類審核者是否真的有用」。掛點在 `core/judge.py`。