README.md

---
title: Tipitaka
emoji: 📖
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false
---

# 📖 พระไตรปิฎก ฉบับมหาจุฬาลงกรณราชวิทยาลัย

**Tipitaka Web App** — เว็บอ่านพระไตรปิฎก ฉบับ มจร. แบบจิตวิเวก พร้อม AI ผู้ช่วยอัจฉริยะ

> **Stack:** React + Vite | FastAPI + Python | SQLite FTS5 | Turbovec In-Process (Primary) / Qdrant (Secondary) | ONNX Reranker | DeepSeek API

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| **📖 Reader** | 45+ เล่มพระไตรปิฎก — หน้า-ต่อ-หน้า, ปรับขนาดตัวอักษร, 3 themes (dark/light/classic) |
| **🔍 Hybrid Search** | FTS5 + Vector (Turbovec / Qdrant) + ONNX Reranker — ถูกต้องทั้ง keyword และความหมาย |
| **🤖 AI Assistant** | Floating chat พร้อม RAG context, รองรับ DeepSeek-chat / DeepSeek-reasoner |
| **🔗 Cross-Volume RAG** | ค้นข้ามเล่มจาก Turbovec index / Qdrant + jina-embeddings-v5, rerank ด้วย jina-reranker-v2 |
| **📱 Responsive** | Desktop + Mobile, swipe gesture, keyboard nav |
| **🎨 Markdown Rendering** | AI ตอบเป็น markdown พร้อม prose-invert สำหรับ dark mode |
| **↔️ Resizable Panel** | ลากขอบขวาเพื่อปรับขนาด AI chat — persist ขนาดไว้ |
| **🏷️ Pali Autocorrect** | แก้คำบาลีผิดเอง ก่อนส่งค้นหา — PyThaiNLP + custom dict |

---

## 🏗️ Architecture (Turbovec Edition)

```
┌──────────────────────────────────────────────────────────────────┐
│                      Frontend (Vite + React)                     │
│  AppShell → NavDrawer | ReaderPanel | RightToolbar | AIPopup    │
│  Zustand (5 stores) · Framer Motion · Tailwind CSS v4           │
│  react-markdown + remark-gfm · Lucide React                     │
└────────────────────────────────┬─────────────────────────────────┘
                                 │ HTTP / SSE
┌────────────────────────────────┴─────────────────────────────────┐
│                   Backend (FastAPI Python 3.13)                   │
│                                                                   │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌───────────┐ │
│  │ Page       │  │ Search     │  │ RAG        │  │ LLM       │ │
│  │ Service    │  │ Service    │  │ Service    │  │ Service   │ │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └─────┬─────┘ │
│        │               │               │               │        │
│   ┌────▼────┐    ┌─────▼─────┐    ┌────▼────┐    ┌────▼─────┐ │
│   │ SQLite  │    │ SQLite    │    │ Turbovec│    │ DeepSeek │ │
│   │ FTS5    │    │ LIKE      │    │ Index / │    │ API      │ │
│   │ (memory)│    │ fallback  │    │ Qdrant  │    │ Streaming│ │
│   └─────────┘    └───────────┘    └─────────┘    └──────────┘ │
│                                                                 │
│  Services: page_service · search_service · pali_utils           │
│            rag_service · onnx_reranker · llm_service            │
└─────────────────────────────────────────────────────────────────┘
```

### 🔄 Hybrid Search Pipeline

```
คำถาม → Pali Autocorrect → FTS5 (SQLite, 30 results)
                        ─→ Turbovec Index (jina-embeddings-v5, 30 results)
                        → SQLite Content Enrichment
                        → Merge & Deduplicate
                        → ONNX Rerank (jina-reranker-v2)
                        → Top N → AI context
```

---

## 🗂️ Project Structure

```
RAG/
├── webapp/
│   ├── tipitaka-api/          # FastAPI backend
│   │   ├── app/
│   │   │   ├── main.py        # FastAPI entry + lifespan
│   │   │   ├── config.py      # pydantic-settings
│   │   │   ├── schemas.py     # Pydantic models
│   │   │   ├── routers/       # pages, search, ai, health
│   │   │   ├── services/      # 6 service modules
│   │   │   └── database/      # sqlite_db.py
│   │   ├── tests/             # 35 tests
│   │   ├── models/            # ONNX reranker
│   │   └── startup.sh         # HF Spaces entry
│   │
│   └── tipitaka-web/          # React frontend
│       └── src/
│           ├── components/    # layout, reader, toolbar, ai
│           ├── stores/        # Zustand (5 stores)
│           ├── hooks/         # swipe, keyboard
│           └── lib/           # api.ts
│
├── qdrant_storage/            # Local Qdrant data (optional fallback)
├── snapshots/                 # Qdrant snapshot files (optional fallback)
├── Dockerfile                 # Multi-stage build
├── TIPITAKA_WEB_ARCHITECTURE_TURBOVEC.md   # Main architecture doc (Turbovec)
└── SEARCH_ARCHITECTURE_TURBOVEC.md         # Search specification (Turbovec)
```

---

## 🚀 Quick Start

### Prerequisites
- Python 3.13+
- Node.js 20+
- Ollama (for embedding — **jina-embeddings-v5-small-retrieval**)
- DeepSeek API key

### 1. Setup Backend
```bash
cd webapp/tipitaka-api
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -r requirements.txt

# Copy .env.example → .env and fill DEEPSEEK_API_KEY
python -m app.main        # starts on :8000
```

### 2. Setup Frontend
```bash
cd webapp/tipitaka-web
npm install
npm run dev               # starts on :5173
```

### 3. Setup Embedding
```bash
# Download jina-embeddings-v5 GGUF
ollama pull hf.co/second-state/jina-embeddings-v5-text-small-retrieval-GGUF:v5-small-retrieval-Q6_K.gguf
```

### 4. Run Tests
```bash
cd webapp/tipitaka-api
python -m pytest tests/ -v    # 35 tests, all passing
```

---

## 📡 API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/pages/volumes` | รายการเล่มพระไตรปิฎก |
| `GET` | `/api/pages/volumes/{id}/toc` | สารบัญ (dedup + noise filter) |
| `GET` | `/api/pages/{vol}/{page}` | เนื้อหาหน้า |
| `GET` | `/api/search?q=&limit=&offset=` | ค้นหา FTS5 + LIKE + highlight |
| `GET` | `/api/search/suggestions?q=` | Autocomplete |
| `POST` | `/api/ask/stream` | AI ถาม-ตอบ (SSE streaming) |
| `POST` | `/api/ask` | AI ถาม-ตอบ (non-stream — Discord) |
| `GET` | `/api/ask/rag-status` | สถานะ Turbovec/Qdrant |
| `GET` | `/health` | Health check |

---

## 🧪 Test Suite

```
tests/
├── test_pali_utils.py     # 90 assertions — autocorrect, digits, similarity
├── test_search_service.py # FTS5 + LIKE merge, suggestions
└── test_rag_service.py    # Embedding LRU cache

Total: 35 tests ✅
```

---

## 🧰 Tech Stack Detail

| Layer | Technology |
|-------|-----------|
| **Frontend** | React 18, TypeScript 5, Vite 6, Tailwind CSS v4 |
| **State** | Zustand (5 stores) |
| **Animation** | Framer Motion |
| **Icons** | Lucide React |
| **Markdown** | react-markdown + remark-gfm |
| **Backend** | FastAPI, Python 3.11 |
| **Database** | SQLite (FTS5, loaded to `:memory:` at startup) |
| **Vector Store** | Turbovec (Primary in-process index), Qdrant (Secondary fallback) |
| **Embedding** | jina-embeddings-v5-small-retrieval (GGUF via Ollama / sentence-transformers) |
| **Reranker** | jina-reranker-v2-base-multilingual (ONNX, CPU) |
| **AI** | DeepSeek API (OpenAI-compatible, SSE streaming) |
| **CI/CD** | HF Spaces (Docker multi-stage, auto-build) |

---

## 📚 Documents

| File | Description |
|------|-------------|
| `DESIGN.md` | Design system — colors, typography, components, themes |
| `PRODUCT.md` | Product vision, users, principles |
| `TIPITAKA_WEB_ARCHITECTURE_TURBOVEC.md` | Main architecture document (Turbovec Edition) |
| `SEARCH_ARCHITECTURE_TURBOVEC.md` | Search Architecture Specification (Turbovec Edition) |
| `Tipitaka-Web-Application-Tech-Stack-TURBOVEC-HF.md` | Tech Stack & HF Spaces Deployment (Turbovec Edition) |
| `TIPITAKA_WEB_ARCHITECTURE_V2.md` | Full architecture V2 document (Legacy Qdrant version) |

---

## 🙏 Acknowledgements

- **มหาจุฬาลงกรณราชวิทยาลัย (MCU)** — เนื้อหาพระไตรปิฎก
- **Turbovec** — In-process vector database
- **Qdrant** — Vector database (Legacy/Alternative)
- **jina.ai** — Embedding + Reranker models
- **Ollama** — Local model serving
- **Hugging Face Spaces** — Deployment platform

---

*"อุปมาเหมือนแสงเทียนในห้องมืด คือปัญญาทำลายอวิชชา"*