# AI Runtime Refactor

เอกสารนี้สรุปผล grilling session สำหรับการ refactor AI runtime หลังอัปเกรด GPU จาก RTX 2060 SUPER 8GB เป็น ASUS DUAL RTX 5060 Ti 16GB

เอกสารอ้างอิง:
- [ADR-033](../specs/06-Decision-Records/ADR-033-active-model-and-ocr-management.md)
- [ADR-034](../specs/06-Decision-Records/ADR-034-AI-model-change.md)
- [ADR ใหม่: AI Runtime Policy Refactor](./adr/0001-ai-runtime-policy-refactor.md)
- [CONTEXT.md](../CONTEXT.md)

## เป้าหมาย

- เปลี่ยนชื่อโมเดลหลักและ OCR ไปเป็น canonical identities ใหม่
- ย้ายสัญญา API จาก caller-driven model selection ไปเป็น policy-driven `executionProfile`
- รวมการจัดการ VRAM ของ main model, OCR, embedding, และ reranking ไว้ใน policy เดียว
- ใช้ big bang rollout แบบมีกติกา cutover และ verification ที่รันซ้ำได้

## Decision Summary

### 1. Canonical naming

- ใช้ `np-dms-ai` เป็น canonical model identity เดียวทุกชั้นที่ผู้ใช้และนักพัฒนาเห็น
- ใช้ `np-dms-ocr` เป็น canonical OCR identity เดียวทุกชั้น
- ชื่อ runtime/base model จริงเป็น implementation detail ใน Modelfile, deploy script, หรือ ops internals เท่านั้น

### 2. API contract

- caller ส่งได้เพียง `executionProfile`
- caller ห้ามส่ง `model.key`
- caller ห้าม override `temperature`, `top_p`, `maxTokens`, หรือ runtime parameters อื่นโดยตรง
- backend policy เป็นผู้ map `executionProfile` ไปยัง canonical model, runtime parameters, และ keep_alive policy

### 3. Canonical profile set

โปรไฟล์ระดับ contract มีแค่:

- `fast`
- `balanced`
- `thai-accurate`
- `large-context`

กฎเพิ่ม:

- `large-context` จำกัดเฉพาะ admin/special workflows
- งานที่มีผลต่อข้อมูล เช่น `migrate-document`, `auto-fill-document`, OCR extraction ใช้ backend override profile เอง

### 4. Runtime resource policy

- `np-dms-ai` เป็น workload หลักของ generation path
- `np-dms-ocr` ใช้ adaptive residency แทน fixed `keep_alive`
- retrieval acceleration (`BGE-M3`, `BGE-Reranker-Large`) อยู่ใน policy เดียวกับ main/OCR
- GPU ownership ใช้หลัก LLM-first
- ถ้า VRAM headroom ไม่พอ retrieval ต้อง fallback CPU ทันที

### 5. Queue policy

- คงโครง `ai-realtime` / `ai-batch` และ pause/resume coordination เดิมเป็นแกน
- อนุญาต `ai-realtime = 2` ได้เฉพาะ lightweight realtime jobs
- `rag-query` ไม่ใช่ lightweight realtime job
- `rag-query` เป็น generation-centric job: retrieval เป็นขั้นเตรียม context และ fallback CPU ได้

### 6. Rollout policy

- rollout ใช้ `Big Bang`
- cutover จะถือว่าสำเร็จต่อเมื่อผ่านครบทั้ง:
  - policy contract
  - model switching
  - adaptive OCR residency
  - RAG fallback

## Canonical Models

| Canonical Name | บทบาท | Residency policy | หมายเหตุ |
|---|---|---|---|
| `np-dms-ai` | main generation model | resident by default | backend policy คุม runtime parameters |
| `np-dms-ocr` | OCR model | adaptive | ใช้ policy ตาม VRAM headroom และ active workload |

หมายเหตุ:
- เอกสารนี้ไม่บังคับว่าฐานจริงต้องเป็น model family ใดเสมอไป
- การเปลี่ยน base runtime model ในอนาคตไม่ควรเปลี่ยน canonical API/UI name ถ้า semantics เดิมยังอยู่

## Execution Profile Contract

### Request DTO

```typescript
interface CreateAiJobRequest {
  type: 'auto-fill-document' | 'migrate-document' | 'rag-query';
  documentId?: string;
  attachmentId?: string;
  executionProfile?: 'fast' | 'balanced' | 'thai-accurate' | 'large-context';
}
```

### Policy rules

- `migrate-document`: backend override เป็น profile ที่ deterministic สูงเสมอ
- `auto-fill-document`: backend override ได้ตาม data-affecting policy
- `rag-query`: ปกติใช้ `balanced` หรือ policy ที่ backend กำหนด
- `large-context`: ใช้ได้เฉพาะ admin/special workflows ที่ backend whitelist

### Forbidden contract

สิ่งต่อไปนี้ต้องไม่มีใน public contract:

```typescript
model: {
  key: string;
  parameters: {
    temperature?: number;
    topP?: number;
    maxTokens?: number;
  };
}
```

เหตุผล:
- caller bypass governance ได้
- verification matrix โตเกินจำเป็น
- profile abstraction หมดความหมายทันที

## Adaptive OCR Residency

หลักการ:

- `np-dms-ocr` ไม่ใช้ fixed `keep_alive: 0` หรือ fixed `keep_alive: 300` ตายตัว
- backend policy คำนวณ residency จาก VRAM headroom และ active model/workload ปัจจุบัน
- ถ้า active workload กิน VRAM สูง หรือ profile ปัจจุบันเสี่ยงชน headroom ให้ fallback เป็น `keep_alive: 0`
- ถ้า headroom เหลือและไม่มี contention สำคัญ อนุญาต residency window ชั่วคราวได้

ตัวอย่าง policy:

```text
if active_profile == 'large-context' => OCR keep_alive = 0
if active_main_model_pressure == high => OCR keep_alive = 0
if headroom >= policy threshold => OCR keep_alive = short residency window
```

## LLM-First GPU Ownership

ลำดับสิทธิ์ VRAM:

1. `np-dms-ai`
2. `np-dms-ocr`
3. `BGE-M3`
4. `BGE-Reranker-Large`

ผลเชิงพฤติกรรม:

- retrieval path ใช้ GPU ได้เฉพาะเมื่อ policy ระบุว่ามี headroom จริง
- retrieval path ไม่มีสิทธิ์บังคับรอ GPU เพื่อแย่ง resource จาก main/OCR path
- หาก headroom ไม่พอ `embed` และ `rerank` ต้อง fallback CPU ทันที

## Retrieval Acceleration

### Scope

เอกสารนี้ถือว่า retrieval acceleration เป็นส่วนหนึ่งของ runtime resource policy เดียวกัน ไม่ใช่ tuning แยก

### Sidecar policy

ปัจจุบัน:

```text
POST /embed   -> CPU
POST /rerank  -> CPU
```

เป้าหมาย:

```text
POST /embed   -> GPU เมื่อ headroom ผ่าน policy, ไม่เช่นนั้นใช้ CPU
POST /rerank  -> GPU เมื่อ headroom ผ่าน policy, ไม่เช่นนั้นใช้ CPU
POST /ocr-upload -> OCR path ตาม adaptive OCR residency
POST /normalize  -> CPU
```

### Retrieval fallback rule

- ห้าม queue รอ GPU เพื่อให้ retrieval ได้ acceleration
- ห้าม fail hard เพียงเพราะ GPU ไม่พอ
- ให้ degrade ไป CPU แล้วตอบงานต่อ

## Queue and Scheduling

### Baseline

- `ai-batch` ยังสามารถถูก pause/resume โดย realtime path ตาม coordination model เดิม
- `ai-realtime = 1` ยังคงเป็น baseline สำหรับงาน generation-heavy

### Selective realtime uplift

อนุญาต `ai-realtime = 2` เฉพาะกลุ่มงานที่เป็น lightweight realtime jobs เช่น:

- intent classification ที่ไม่เรียก OCR
- tool-only suggestion path ที่ไม่บังคับ model switching
- metadata-free chat steps ที่ไม่ใช้ GPU-heavy generation

ไม่รวม:

- `rag-query`
- OCR-triggering jobs
- งานที่บังคับ model switching
- generation-heavy jobs

## Big Bang Rollout

### Decision

refactor รอบนี้ใช้ big bang rollout เพราะระบบยังไม่เปิด production

### Consequence

ห้ามใช้เกณฑ์ partial success แบบ "บางแกนผ่านก็ถือว่าปล่อยได้"

### Cutover gate

ต้องผ่านครบทุกแกน:

1. policy contract ใหม่ทำงานจริง
2. canonical naming ใหม่ทำงานจริง
3. model switching และ OCR residency ตรง policy ใหม่
4. retrieval GPU/CPU fallback ทำงานจริง

## Verification

ใช้แนวทาง executable-first แต่ทุกแกนต้องมี manual validation path ประกบ

### 1. Policy contract

Executable:

- unit/integration tests สำหรับ DTO และ policy mapping
- tests ว่า caller ส่ง `model.key` หรือ parameter overrides ไม่ได้
- tests ว่า data-affecting jobs ถูก backend override profile จริง

Manual:

- ยิง request จาก admin/sandbox แล้วตรวจว่า UI/API ไม่ expose free-form model selection

### 2. Canonical naming

Executable:

- search-based checks ว่า public-facing contract ใช้ `np-dms-ai` / `np-dms-ocr`
- tests สำหรับ settings/service/controller ที่คืนชื่อ canonical

Manual:

- เปิด AI Admin Console และ OCR sandbox ตรวจ label/option/log surface ที่ผู้ใช้เห็น

### 3. Adaptive OCR residency

Executable:

- tests ว่า residency policy ให้ `keep_alive` ต่างกันตาม headroom scenario
- logs/trace ว่า OCR requests ใช้ residency decision ตาม policy

Manual:

- รัน OCR ซ้ำหลายงานในเงื่อนไข headroom ต่างกันและตรวจ behavior จริง

### 4. Retrieval fallback

Executable:

- tests ว่า `/embed` และ `/rerank` fallback CPU เมื่อ GPU threshold ไม่ผ่าน
- trace/log ว่า `rag-query` ยังตอบได้เมื่อ GPU retrieval path ถูกปิด

Manual:

- ทดลอง RAG query ภายใต้ภาระ GPU สูงและยืนยันว่าคำตอบยังออกได้แม้ช้าลง

## Implementation Workstreams

### Workstream A: Contract and naming

- เปลี่ยน public contract ให้ใช้ `executionProfile`
- ลบ `model.key` และ parameter override จาก API docs/DTO ที่เกี่ยวข้อง
- เปลี่ยน public-facing names เป็น `np-dms-ai` และ `np-dms-ocr`

### Workstream B: Runtime policy

- สร้าง policy mapping profile -> runtime configuration
- เพิ่ม adaptive OCR residency logic
- แยก policy ของ data-affecting jobs ออกจาก caller input

### Workstream C: Retrieval acceleration

- เพิ่ม GPU eligibility check สำหรับ `embed` และ `rerank`
- เพิ่ม CPU fallback path ที่ explicit
- บันทึก telemetry/log สำหรับ fallback decisions

### Workstream D: Queue policy

- คง pause/resume coordination เดิม
- แยก lightweight realtime jobs ออกจาก generation-heavy jobs
- ใช้ selective concurrency uplift เฉพาะ job ที่ allowed

### Workstream E: Verification

- เพิ่ม automated tests ตาม cutover gate
- เพิ่ม manual validation checklist สำหรับ admin console, OCR sandbox, และ RAG path

## Non-Goals

- ไม่เปิดให้ caller เลือก runtime parameters เอง
- ไม่เปลี่ยน `rag-query` ให้เป็น retrieval-first job
- ไม่ยกเลิก pause/resume coordination เดิมทั้งหมด
- ไม่แยก retrieval acceleration ออกเป็น policy คนละชุดกับ main/OCR
- ไม่ใช้ phased rollout ในเอกสารฉบับนี้

## Migration Note for Current Repo

repo ปัจจุบันยังมีจุดที่อิงชื่อและ policy เดิม เช่น `typhoon2.5-np-dms:latest`, `typhoon-np-dms-ocr:latest`, และ `keep_alive: 0` ในหลาย service/spec. เอกสารนี้จึงเป็น target architecture/policy ใหม่ และต้องมีการอัปเดตโค้ด, tests, cross-spec docs, และ admin UI ให้สอดคล้องก่อนจะถือว่า cutover สำเร็จ.