lcbp3/docs/ai-knowledge-base/playbooks/intent-classification.md

Intent Classification API Playbook

Overview

ระบบ Intent Classification ใช้ Hybrid Strategy: Pattern Matching (keyword/regex) → LLM Fallback (Ollama) → FALLBACK intent

API Endpoints

Classification

Method	Endpoint	Auth	Rate Limit	Description
POST	/ai/intent/classify	JWT	30/min	จำแนก Intent จาก query

Request:

{
  "query": "สรุปเอกสารนี้ให้หน่อย",
  "projectPublicId": "019505a1-...",
  "userPublicId": "019505a1-...",
  "currentDocumentId": "019505a1-..."
}

Response:

{
  "intentCode": "SUMMARIZE_DOCUMENT",
  "confidence": 1.0,
  "method": "pattern",
  "latencyMs": 3
}

Admin — Intent Definitions

Method	Endpoint	Auth	Description
GET	/admin/ai/intent-definitions	JWT + RBAC	รายการ Intent Definitions
GET	/admin/ai/intent-definitions/:intentCode	JWT + RBAC	Intent ตาม code
POST	/admin/ai/intent-definitions	JWT + RBAC	สร้าง Intent ใหม่
PATCH	/admin/ai/intent-definitions/:intentCode	JWT + RBAC	อัปเดต Intent

Query Parameters (GET all):

• category: read | suggest | utility
• isActive: true | false

Admin — Intent Patterns

Method	Endpoint	Auth	Description
GET	/admin/ai/intent-definitions/:code/patterns	JWT + RBAC	Patterns ของ Intent
POST	/admin/ai/intent-definitions/:code/patterns	JWT + RBAC	สร้าง Pattern
GET	/admin/ai/intent-patterns/:publicId	JWT + RBAC	Pattern ตาม UUID
PATCH	/admin/ai/intent-patterns/:publicId	JWT + RBAC	อัปเดต Pattern
DELETE	/admin/ai/intent-patterns/:publicId	JWT + RBAC	Soft delete

---

Classification Methods

Method	Description	Confidence	Latency
pattern	Keyword/regex match	1.0	< 10ms
llm_fallback	Ollama LLM classification	0.4-1.0	< 2000ms
semaphore_overflow	LLM queue full	0	< 10ms
llm_error	LLM unavailable/timeout	0	< 5000ms

---

12 Standard Intents (v1)

Intent Code	Category	Description (TH)
RAG_QUERY	read	ถามคำถามธรรมชาติ ตอบจาก vector + doc context
GET_RFA	read	ดึง RFA ตาม filter
GET_DRAWING	read	ดึง Drawing revision
GET_TRANSMITTAL	read	ดึง Transmittal
GET_CORRESPONDENCE	read	ดึง Correspondence ทั่วไป
GET_CIRCULATION	read	ดึง Circulation
GET_RFA_DRAWINGS	read	ดึง Drawings ที่ผูกกับ RFA
SUMMARIZE_DOCUMENT	read	สรุปเอกสารที่เปิดอยู่
LIST_OVERDUE	read	รายการ cross-entity ที่เกินกำหนด
SUGGEST_METADATA	suggest	แนะนำ metadata สำหรับเอกสาร
SUGGEST_ACTION	suggest	แจ้งเตือนว่าควรทำอะไรต่อ
FALLBACK	utility	ไม่เข้า intent ไหน / ไม่เกี่ยวกับระบบ

---

Cache Strategy

• Key: ai:intent:patterns:active
• TTL: 300 seconds
• Invalidation: Auto on admin CRUD (create/update/delete pattern)
• Fallback: DB query if Redis unavailable

---

Semaphore (LLM Concurrency Control)

• Max concurrent: 3 (configurable via INTENT_LLM_MAX_CONCURRENT)
• Behavior on full: Return FALLBACK with method semaphore_overflow
• Pattern: Promise-based queue with idempotent release

---

Configuration (Environment Variables)

# Ollama
OLLAMA_BASE_URL=http://192.168.10.5:11434
OLLAMA_MODEL=gemma4:e4b

# Intent Classification
INTENT_LLM_MAX_CONCURRENT=3
INTENT_LLM_TIMEOUT_MS=5000
INTENT_CACHE_TTL_SECONDS=300

---

Troubleshooting

Problem	Cause	Solution
All queries return FALLBACK	Redis empty + LLM down	Check Redis + Ollama status
High latency (> 2s)	LLM overloaded	Increase semaphore or add patterns
Pattern not matching	Cache stale	Wait TTL (5min) or restart
429 Too Many Requests	Rate limit exceeded	Wait 60s or reduce frequency

---

Related

• ADR-024: Intent Classification Strategy
• ADR-023A: Unified AI Architecture (Model Revision)
• Feature spec: specs/200-fullstacks/224-intent-classification/spec.md