籤詩 吉凶禍福 平安

Bless You — RAG + Knowledge Graph + LLM Chatbot for Fortune Stick Interpretation

中文版 README

Try the Live Demo | Traditional Chinese fortune stick culture meets modern AI

---

About

籤詩文化是華人社會深厚的傳統，透過神諭指引人們面對人生的困惑。本專案將古老的籤詩文化與現代科技結合，利用人工智慧技術，提供更便捷、更深入的解籤體驗。

Fortune stick culture, deeply rooted in Chinese-speaking societies, offers divine guidance to navigate life's uncertainties. This project integrates this ancient tradition with modern technology — combining RAG, Knowledge Graph, LLM, and BERT embeddings — to create an intelligent interpretation platform for 100 poems from Longshan Temple (龍山寺).

Note: AI interpretations are for reference only. Fortune stick culture is a cherished tradition — please approach with respect.

---

Quick Start

Option 1: Docker (Recommended)

# Clone the repo
git clone https://github.com/osisdie/fortune-poem-ai.git
cd fortune-poem-ai

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Launch app + Neo4j
docker compose up -d

Visit http://localhost:7860 for the Gradio app and http://localhost:7474 for the Neo4j dashboard.

Option 2: Manual Setup

# Install Python dependencies
pip install -r requirements.txt

# Start Neo4j separately (or use Docker: docker compose up neo4j -d)

# Run the preprocessing notebooks (see Preprocessing section below)
# Then launch the Gradio app notebook:
jupyter notebook bless_u-chatbot-100.ipynb

Option 3: Web Demo (No setup required)

Visit the Next.js showcase site to browse all 100 poems and try the interactive fortune-drawing demo — no API keys or database required.

---

Architecture

Technology Stack

Technology	Purpose
RAG	Retrieval-Augmented Generation for grounding LLM responses
Neo4j	Knowledge Graph database storing poem relationships
BERT (ckiplab/bert-base-chinese)	Chinese-specific embeddings for similarity search
LLM (GPT-4o / Claude 3.5)	AI-powered poem interpretation via aisuite
Gradio	Interactive web interface
Next.js	Static showcase site deployed on Vercel
BeautifulSoup	Web scraping for poem data collection
NetworkX	Knowledge graph visualization

LLM Integration

The system calls GPT-4o and Claude 3.5 Sonnet in parallel via aisuite, with a Neo4j-based caching layer that skips API calls when a similar question has been asked before (cosine similarity > 0.75).

User Question → Neo4j Similarity Search → Hit? → Return cached response
                                        → Miss? → GPT-4o + Claude 3.5 → Store in Neo4j

See docs/llm_architecture.md for full details on the Temple class hierarchy, prompt construction, and caching strategy.

Graph+RAG: Dynamic Graph Updates

When users ask questions, the graph dynamically updates in real time. New UserPrompt nodes are linked to poems via HAS_PROMPT relationships, with purpose_embedding and answer_embedding for similarity-based search using gds.similarity.cosine.

---

Preprocessing

1. Web Crawler

Collect data on 100 poems including text and images.

Implementation: step1-bless_u-crawler

Output: all_chances.json + knowledge graph visualizations:

Good Poems (30)	Normal Poems (50)	Bad Poems (20)

2. LLM Poem Interpretation Expansion

Generate additional UserPrompt data using LLMs.

Implementation: step2-bless_u-LLM-poem-answers-gen

3. Word Embedding Model

Using ckiplab/bert-base-chinese for cosine similarity in Neo4j.

Implementation: step3-bless_u-model-fine-tuning | BERT.md

Training Loss	Validation Loss

4. Neo4j Graph Database

Export poems and relationships into Neo4j for similarity search.

Implementation: step4-bless_u-neo4j

---

Web UI

Execute bless_u-chatbot-100.ipynb to launch the Gradio app:

Initial Interface	Interaction Example

---

Project Structure

.
├── bless_u-chatbot-100.ipynb   # Main Gradio app
├── data/
│   ├── all_chances.json        # 100 poems with full metadata
│   ├── all_contexts.json       # Pre-formatted RAG contexts
│   ├── all_divine.json         # 15 divine categories + sample questions
│   ├── chatgpt_response.json   # Cached GPT-4o responses
│   └── claude_response.json    # Cached Claude responses
├── images/                     # Screenshots and graph visualizations
├── pre-process/                # Data collection & preprocessing notebooks
├── web/                        # Next.js showcase site (Vercel deployment)
├── Dockerfile                  # Python/Gradio container
├── docker-compose.yml          # App + Neo4j orchestration
└── requirements.txt            # Python dependencies

---

Contributing

See CONTRIBUTING.md for guidelines on setting up the development environment, code style, and how to add poems or modify the graph schema.

---

License

This project is licensed under the MIT License.

---

Enjoy the platform, and we look forward to getting your feedback!