# GLOBAL Hybrid — Stability First

這一版不是「多幾個 Agent」而已，而是把你最在意的問題做成可執行架構：**少除錯、少試錯、舊規則不亂復活、做不到不偷偷換方法、錯了能定位是哪一層。**

## 已完成的完整流程

```text
你這次要什麼
  -> CURRENT TASK CONTRACT（本次唯一有效任務）
  -> deterministic contract check
  -> 必要時 Fact Specialist
  -> 圖像任務先 Ground CURRENT source identity
  -> capability / route gate
  -> bounded Executor
  -> independent Visual Judge
  -> deterministic acceptance
  -> GLOBAL 最後整合
```

研究則走另一條路：

```text
舊圖片 / 舊輸出 / 成功失敗案例 / feedback
  -> Evidence Layer
  -> Evidence Researcher
  -> CANDIDATE finding
  -> countercheck / matching-scope validation
  -> adoption eligibility
  -> 明確 ADOPT 後才成為 reusable authority
```

**舊資料可以一直拿來學，但不會因為曾經存在就自動變成新任務限制。**

## 現在跟最早 MVP 最大的差異

- GLOBAL Manager 不再自己臨場呼叫 Fact 亂繞流程；專業步驟由 orchestrator 明確安排。
- Fact / Sales / Visual / Executor 各自有邊界。
- Image Executor 不自己判成功；Visual Judge 才做 acceptance。
- `strict source-preserving` 只在本次明確要求時啟用。
- fresh generation 帶 source image 時仍是「reference-based generation」，不假裝 pixel-preserving edit。
- Persistent SQLite store 會保存 evidence、研究 finding、被採用的 authority、每次 run trace。
- scheduled research 可以反覆研究已存 evidence；沒有新上傳不代表完全停止學習。圖片 evidence 會以實際影像輸入 Researcher，不只看檔名。
- finding 預設只進 `CANDIDATE`，不會自動污染 production authority。
- 每次 run 可追到 TASK_CONTRACT / FACT / SOURCE_IDENTITY / ROUTE / EXECUTION / VISUAL_JUDGE / GLOBAL 哪一層失敗。

## 安裝

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export OPENAI_API_KEY=sk-...
export GLOBAL_MODEL=gpt-5.6-sol
```

OpenAI Agents SDK 支援 manager/specialist、hosted image generation、guardrails 與 tracing；本專案另外保留一份 local SQLite trace，避免只靠遠端 trace 才能除錯。

## 出圖

```bash
python main.py run \
  --request "把這台車做成更有賣相的真實銷售圖；可以重畫，但必須保持同一台實車身份" \
  --source-image front.jpg \
  --source-image rear.jpg \
  --authority-file data/authority/current.md \
  --evidence-dir data/evidence \
  --feedback-file data/feedback/current_feedback.md \
  --store state/global_hybrid.sqlite3 \
  --json-report output/latest_run.json \
  --output output/latest.png \
  --live-image-exec
```

如果本次寫的是：

```text
原車不可重畫，只換背景
```

contract 才會啟動 strict source-preserving。因為本專案目前沒有接 deterministic/pixel-preserving compositor，這種任務會 **BLOCK**，不會偷偷改用 whole-image regeneration。

## 銷售 / Fact

Contract Builder 會判斷 task 是 `sales`、`fact`、`image`、`analysis` 或 `mixed`。

- 銷售文案 / 真人回覆：Sales Specialist 自然處理，但 hard facts 不能自己猜。
- 年份 / 市場 / trim / 配備 / 價格 / 法規等：先走 Fact Specialist，需要時才查證。
- Sales 不會因過去某篇文案成功就固定 CTA / 段落 / 客戶類型。

## 用舊資料自動研究

```bash
python main.py research \
  --authority-file data/authority/current.md \
  --evidence-dir data/evidence \
  --feedback-file data/feedback/current_feedback.md \
  --store state/global_hybrid.sqlite3 \
  --evidence-manifest state/latest_evidence_manifest.json
```

排程可直接跑 `scripts/hourly_research.sh`。

研究會把 finding 保存在 SQLite，但**不會直接改 production 規則**。只有通過 adoption eligibility，並被明確採用後，才會進 reusable authority。

## 看它到底哪裡出錯

```bash
python main.py status --store state/global_hybrid.sqlite3
python main.py findings --store state/global_hybrid.sqlite3
python main.py trace RUN_ID --store state/global_hybrid.sqlite3
```

這就是減少你反覆用人話幫系統除錯的核心：結果不對時先看 trace，不需要把整套規則重新討論一次。

## Tests

```bash
PYTHONPATH=. pytest -q
```

目前 deterministic core：**20 tests**，涵蓋：

- 舊 strict rule 不得自己復活。
- 本次 explicit strict 才能啟用。
- strict 不得 silent fallback 到 fresh regeneration。
- rerender 任務可使用 fresh generation。
- current source identity 與 style 分離。
- generic old evidence 永遠不會自己變 authority。
- 單一案例 finding 不具 adoption eligibility。
- supported、多證據、有 countercheck 的 finding 才可進 adoption gate。
- adopted finding 可被 reject 並立即退出 authority。
- Visual Judge FAIL 時，即使圖片成功生成也不能 accepted。
- 每個 run stage 都可寫入 local trace。

## 已知硬邊界

目前真正剩下的不是架構缺口，而是執行環境邊界：

1. **這個 Python runtime 無法直接接管你正在開著的 ChatGPT 對話內部 `image_gen`。** 它要透過 OpenAI API / Agents SDK 自己執行。
2. **pixel-preserving / deterministic composite executor 尚未提供。** 所以 strict source-preserving 任務故意 fail-close。
3. 這個工作容器目前沒有外網 package installation，也沒有你的 API key，因此這裡能完整驗證 deterministic core，但不能在容器內替你跑一次 Agents SDK live API execution。

其餘架構、資料層、learning lifecycle、route gate、specialists、acceptance、local trace、scheduled research 都已接好。

詳細結構見 `ARCHITECTURE.md`，部署見 `DEPLOY.md`。

## MCP / ChatGPT App 版本

repo root 現在也包含 `server.py` 與 `render.yaml`：

```text
ChatGPT App
  -> https://<service>.onrender.com/mcp
  -> GLOBAL current-task contract
  -> bounded specialists / capability gate
  -> executor
  -> independent Visual Judge
  -> trace + result
```

Render 部署細節見 `DEPLOY_RENDER.md`。第一次部署預設關閉 live image execution，先驗證 MCP 連線；確認後再開啟 `GLOBAL_ALLOW_LIVE_EXEC=true`。