README.md

metadata

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

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

cd webapp/tipitaka-web
npm install
npm run dev               # starts on :5173

3. Setup Embedding

# 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

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

---

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