AI System Architecture & Model Guidelines

🤖 AI_ARCHITECTURE.md - AI System Architecture & Models (ระบบโครงสร้างปัญญาประดิษฐ์และ AI โมเดล)

This document defines the AI pipelines, prompt strategies, OCR engines, safety rules, and model abstractions used in SplitDee.
เอกสารฉบับนี้กำหนดรายละเอียดระบบท่อลำเลียงข้อมูล AI, แผนกลยุทธ์การเขียนคำสั่ง Prompt, กลไกตัวสแกน OCR, กฎความปลอดภัยทางเนื้อหา และเกณฑ์มาตรฐานโมเดลอ้างอิงสำหรับโครงการ SplitDee

---

🇹🇭 ภาษาไทย (สำหรับผู้ใช้งาน)

1. ภาพรวมระบบวิเคราะห์ AI (AI System Overview)

SplitDee นำโมเดลปัญญาประดิษฐ์มาประยุกต์ใช้งานในสองท่อหลัก:

• ระบบตรวจรูปภาพเอกสาร (OCR Pipeline): ใช้แกะรหัส Mini-QR จากสลิปโอนเงินธนาคาร และส่งวิเคราะห์ตัวอักษรรายการอาหารจากสลิปใบเสร็จร้านค้า
• ระบบสร้างมีมทวงเงิน (Reminder & Meme Engine): นำข้อมูลค้างจ่ายมาประกอบพร้อมท์ ส่งให้ LLM แต่งประโยคและสุ่มประทับครอบลงบนภาพพื้นหลังมีม

2. ท่อประมวลผล OCR และการตรวจสอบสลิปแบบอะซิงโครนัส

• Mini-QR Reader (แสกนรหัสสลิป): รูปภาพสลิปจะถูกอ่านหา Mini-QR คีย์ด้วย Python OpenCV/ZBar เพื่อดึงเลขอ้างอิงทำรายการนำไปเช็ก Statement ธนาคารโดยตรง หากสแกนไม่ได้จะปลอบผ่อนคลายไปตรวจตัวเลขธนาคารด้วยเครื่องสแกนตัวอักษรแทน
• LLM Receipt Parser (แสกนเมนูใบเสร็จ): โมเดล AI จะอ่านรูปใบเสร็จร้านค้าและสกัดข้อมูลออกมาเป็นสเปก JSON (ชื่อร้าน, ยอดเงินรวม, ตารางรายการสินค้าและราคา) เพื่อช่วยกรอกบิลตั้งหารอัตโนมัติ

3. ระบบสร้างมีมทวงเงิน

• Prompt Strategy (ระดับการพูดจา): เขียน Prompt คุมอารมณ์น้องโมจิในระดับเสียงที่ต่างกัน ได้แก่ สุภาพ (การแจ้งเตือนทางการ), เป็นกันเอง (ภาษาพูดสลีปเพื่อนร่วมชั้น), หรือแนวมีมตลกๆ (AI แต่งคำพูดล้อเลียนความอ้วนหรือเมนูกินชวนขำ)
• Meme Overlay (การวาดคําทับมีม): ดึงภาพพื้นหลังมีม แต่งแคปชันโดย LLM และพิมพ์คำศัพท์ทับพิกเซลจุด X-Y ของแม่แบบมีมด้วย Pillow บันทึกภาพลง S3 และโพสต์ข้อความลงแชทกลุ่มรูมเมท

4. กฎความปลอดภัยและข้อจำกัด AI (Safety & Constraints)

• การคัดกรองเนื้อหา: บังคับป้อน Safe Rules ในระบบควบคุมทราฟฟิกภาษา ห้าม AI พิมพ์คำหยาบคาย เสียดสีรบกวนสัญชาติญาณ หรือกล่าวหาเรื่องเงินจนผิดใจ
• ระบบสำรองกรณีล้มเหลว: หากคีย์เซิร์ฟเวอร์ AI หน่วงเวลาหรือแครช ให้เปลี่ยนไปยิงทวงเป็นข้อความปกติของโปรแกรมทันที
• จำกัดสิทธิ์แก้ไขเงิน: ห้าม AI มีสิทธิ์กดเปลี่ยนสเตตัสบิลเป็นจ่ายแล้ว ข้อมูลการโอนต้องทำธุรกรรมผ่านระบบและ Statement เท่านั้น

5. การสลับเปลี่ยนโมเดลและการคุมงบ (Model Abstraction & Rate Limits)

• อินเตอร์เฟส LLM Provider: หุ้มระบบ API หลังคลาสโมเดลเพื่อป้องกันปัญหายึดติดค่าย ปัจจุบันใช้ Gemini Pro/Flash และรองรับ GPT-4o-mini สำรอง และเปิดช่องให้รันค่าย LLM ในเครื่องตัวเองได้
• การคุมโควต้าคลาวด์: จำกัดแสกนภาพสลิป/ใบเสร็จคนละ 10 รูป/วัน และสั่งจำลองมีมทวงเงินกลุ่มละไม่เกิน 3 มีม/วัน เพื่อคุมงบประมาณ

---

🇬🇧 English (For AI Agents)

1. AI System Overview

SplitDee incorporates artificial intelligence across three distinct pipelines:

• OCR Pipeline: Evaluates bank slips to extract Mini-QR and processes merchant receipts via LLM text extraction.
• Reminder & Meme Engine: Aggregates group spend context, feeds prompts to the LLM, and overlays generated text captions onto visual templates.

2. Asynchronous OCR & Slip Verification Pipeline

• Mini-QR Reader: OpenCV/ZBar script scans the bank slip for a Mini-QR code. If readable, extracts the transaction reference ID. Fallbacks to Google Cloud Vision API/Tesseract on failure.
• LLM Receipt Parser: Automatically extracts merchant name, itemized pricing, and total bill amount using structured Gemini Flash/GPT prompting returning JSON outputs.

3. AI Reminder & Meme Generator Engine

• Prompt Strategy: Formulates prompt contexts dynamically using parameters {debtor_name}, {amount}, and {bill_title} according to selected tone models (Polite, Casual, Humorous/Meme).
• Meme Overlay Generator: Queries random base MemeTemplate configurations, calls the LLM to generate funny text, renders it onto the image layout using Python Pillow, and saves assets to S3.

4. AI Safety Rules & Constraints

• Content Filtering: Enforces strict system prompt filters against profanity, offensive jokes, and direct financial accusations.
• Deterministic Fallbacks: Fallback instantly to a static text template if LLM connection fails or times out.
• No Direct Financial Alteration: AI models cannot mutate database state. Balance clearance must occur strictly via atomic program logic.

5. Model Abstraction & Portability

• Gateway Interface: Abstract LLMProvider decoupling backend use cases from specific LLM models (OpenAI, Gemini).
• Supported Providers: Gemini Pro/Flash API, OpenAI GPT-4o-mini, and future local AI integrations (Ollama / Llama-3-8B).

6. Rate Limits & Budget Safeguards

• OCR Limit: Max 10 receipt scans and 10 slip scans per user per day.
• Meme Generation Limit: Max 3 custom memes per group per day.