ChatGJU

AI-powered chatbot for German Jordanian University (GJU). Uses RAG (Retrieval-Augmented Generation) to answer questions about the university.

Architecture

┌─────────────────────────────────────────────────────────┐
│              Python FastAPI Backend                     │
│                  (apps/retriever)                       │
│                                                         │
│  GET  /health       - Health check                      │
│  POST /retrieve     - Vector search only                │
│  POST /chat         - Full RAG (retrieval + LLM)        │
└─────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
   ┌─────────┐      ┌──────────┐      ┌──────────┐
   │   Web   │      │ WhatsApp │      │  Mobile  │
   │ Next.js │      │   Bot    │      │   App    │
   └─────────┘      └──────────┘      └──────────┘

Project Structure

ChatGJU/
├── apps/
│   ├── web/           # Next.js frontend
│   └── retriever/     # FastAPI backend (Python)
├── data/
│   ├── urls/          # URLs to scrape
│   ├── website/       # Scraped content (CSV)
│   └── glc/           # Curated Q&A (Markdown)
├── tools/
│   ├── scraper/       # Website scraper
│   ├── ingest/        # Data ingestion scripts
│   ├── delete/        # Data deletion utilities
│   └── evaluate/      # RAG evaluation tool
└── docs/              # Documentation

Quick Start

1. Configure Environment

# Copy the example environment file (in monorepo root)
cp .env.example .env

# Edit .env with your credentials:
# - COHERE_API_KEY (required)
# - ZILLIZ_URI (required)
# - ZILLIZ_TOKEN (required)

2. Start the Backend API

cd apps/retriever

# Setup (first time only)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn app.main:app --reload

API available at http://localhost:8000

3. Start the Web Frontend

cd apps/web

# Setup (first time only)
npm install

# Run
npm run dev

Frontend available at http://localhost:3000

---

API Usage

The backend provides a unified API for all chat interfaces.

Chat Endpoint

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What are the admission requirements?"}
    ]
  }'

Response:

{
  "text": "To apply for admission, you need...",
  "chunks": [
    {
      "text": "Source content...",
      "score": 0.85,
      "metadata": {
        "title": "Admission Requirements",
        "source_url": "https://gju.edu.jo/..."
      }
    }
  ]
}

Multi-turn Conversations

Include conversation history for context-aware responses:

{
  "messages": [
    {"role": "user", "content": "What are the admission requirements?"},
    {"role": "assistant", "content": "The requirements include..."},
    {"role": "user", "content": "What about for engineering?"}
  ]
}

See apps/retriever/README.md for full API documentation.

---

Integration Examples

Python (WhatsApp Bot)

import requests

response = requests.post(
    "http://localhost:8000/chat",
    json={"messages": [{"role": "user", "content": "What is GJU?"}]}
)
print(response.json()["text"])

JavaScript (Mobile/Web)

const response = await fetch('http://localhost:8000/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'What is GJU?' }]
  })
});
const data = await response.json();
console.log(data.text);

---

Data Pipeline

Scraping

source .venv/bin/activate

# Test mode (5 URLs)
python3 tools/scraper/scrape_gju.py --test

# Full scrape
python3 tools/scraper/scrape_gju.py

Ingestion

# Ingest curated Q&A
python3 tools/ingest/ingest_qna.py

# Ingest scraped website data
python3 tools/ingest/ingest_csv.py

Evaluation

python3 tools/evaluate/run_evaluation.py

See individual README files in tools/ for details.

---

Environment Variables

All environment variables are configured in a single .env file at the monorepo root.

cp .env.example .env

Variable	Required	Description
COHERE_API_KEY	Yes	Cohere API key
COHERE_MODEL	No	LLM model (default: c4ai-aya-vision-8b)
COHERE_EMBED_MODEL	No	Embedding model (default: embed-v4.0)
ZILLIZ_URI	Yes	Zilliz Cloud endpoint
ZILLIZ_TOKEN	Yes	Zilliz authentication token
ZILLIZ_COLLECTION	No	Collection name (default: ChatGJU_Database)
RETRIEVER_URL	No	Backend API URL (default: http://localhost:8000)

---

Git Workflow

1. Create a branch: git checkout -b your-branch-name
2. Make changes and commit: git add . && git commit -m "message"
3. Push: git push -u origin your-branch-name
4. Create a Pull Request on GitHub to merge into main