PROJECT.md

🔭 AstroBot — RAG-Powered educational AI System

AstroBot is a modular Retrieval-Augmented Generation (RAG) architecture designed for domain-specific educational Q&A. It demonstrates: End-to-end PDF ingestion → structured Parquet datasets Semantic indexing with FAISS Context-grounded LLM responses via Groq (LLaMA-3) Modular architecture enabling easy LLM or vector DB swapping Public deployment on Hugging Face Spaces (CI/CD via git push)

---

Table of Contents

1. Project Overview
2. Tech Stack
3. Architecture
4. File Structure
5. Module Responsibilities
6. Data Pipeline
7. Setup & Deployment
8. Environment Variables
9. How to Add New Course Materials
10. Limitations & Guardrails
11. Troubleshooting

---

Project Overview

AstroBot is a Retrieval-Augmented Generation (RAG) chatbot deployed on Hugging Face Spaces.
It is designed as an educational companion for astrology students, allowing them to ask natural-language questions about astrological concepts and receive accurate, grounded answers drawn exclusively from course textbooks and materials.

Tech Stack

Layer	Technology	Why
LLM	Groq + LLaMA-3.1-8b-instant	Fastest open-model inference; free tier generous
Vector DB	FAISS (CPU)	No external service needed; runs inside the Space
Embeddings	sentence-transformers/all-MiniLM-L6-v2	Lightweight, accurate, runs locally
Dataset	HF Datasets (Parquet)	Native HF Hub format; handles large PDFs well
Framework	LangChain	Chunking utilities and Document schema
UI	Gradio 4	Native to HF Spaces; quick to build, mobile-friendly
Hosting	Hugging Face Spaces	Free GPU/CPU hosting; CI/CD via git push

What it does

• Answers questions about planets, houses, signs, aspects, transits, chart elements, and astrological theory.
• Grounds every answer in actual course material (no hallucination of unsupported facts).
• Clearly declines to make personal predictions or interpret individual birth charts.

What it does NOT do

• Make predictions of any kind.
• Interpret a specific person's chart.
• Answer questions unrelated to astrology concepts.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        OFFLINE (once)                           │
│                                                                 │
│  Astrology PDFs ──► convert_pdfs.py ──► HF Dataset (Parquet)   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    HF SPACE (at startup)                        │
│                                                                 │
│  data_loader.py                                                 │
│    └── load_dataset() from HF Hub ──► list[Document]           │
│                                                                 │
│  vector_store.py                                                │
│    ├── RecursiveCharacterTextSplitter ──► Chunks                │
│    ├── HuggingFaceEmbeddings (MiniLM-L6) ──► Vectors           │
│    └── FAISS.from_documents() ──► Index                        │
│                                                                 │
│  llm.py                                                         │
│    └── Groq(api_key) ──► Groq Client                           │
│                                                                 │
│  rag_pipeline.py                                                │
│    └── RAGPipeline(index, groq_client) ──► Ready               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    HF SPACE (per query)                         │
│                                                                 │
│  Student Question                                               │
│       │                                                         │
│       ▼                                                         │
│  rag_pipeline.query()                                           │
│       ├── vector_store.retrieve()  ──► Top-K Chunks            │
│       └── llm.generate_answer()   ──► Grounded Answer          │
│                                                                 │
│  app.py  ──►  Gradio UI  ──►  Student sees answer              │
└─────────────────────────────────────────────────────────────────┘

---

File Structure

astrobot/
│
├── app.py              # Gradio UI — entry point for HF Spaces
├── config.py           # All configuration (env vars, hyperparameters)
├── data_loader.py      # HF dataset fetching + Document creation
├── vector_store.py     # Chunking, embedding, FAISS index
├── llm.py              # Groq client + prompt engineering
├── rag_pipeline.py     # Orchestrates retrieval → generation
│
├── convert_pdfs.py     # Offline helper: PDFs → HF Parquet dataset
├── requirements.txt    # Python dependencies
└── PROJECT.md          # This file

---

Module Responsibilities

Module	Single Responsibility
config.py	Central source of truth for all settings. Change a parameter once here.
data_loader.py	Fetch data from HF Hub; detect text column; return list[Document].
vector_store.py	Chunk text; embed with sentence-transformers; build & query FAISS index.
llm.py	Validate Groq key; build system prompt; call Groq API; return answer string.
rag_pipeline.py	Glue layer: validate query → retrieve → generate → return RAGResponse.
app.py	UI only: Gradio layout, event wiring, error display. No business logic.
convert_pdfs.py	One-time offline script: extract PDF pages → push Parquet to HF Hub.

This separation means:

• You can swap FAISS → Pinecone by editing only vector_store.py.
• You can swap Groq → OpenAI by editing only llm.py.
• You can change the system prompt (persona, guardrails) in only llm.py.
• You can replace the UI without touching any backend logic.

---

Data Pipeline

Step 1 — Prepare your PDFs (run locally)

Place your astrology textbook PDFs in a folder and run:

pip install pypdf datasets huggingface-hub
python convert_pdfs.py \
    --pdf_dir  ./astrology_books \
    --repo_id  YOUR_USERNAME/astrology-course-materials \
    --private          # optional

This will:

1. Extract text from each PDF page-by-page.
2. Build a datasets.Dataset with columns: source, page, text.
3. Push it to HF Hub as a Parquet-backed dataset.

Step 2 — Connect to the Space

Set HF_DATASET=YOUR_USERNAME/astrology-course-materials in Space secrets (see below).

Step 3 — What happens at startup

load_dataset()                   # ~30s for large datasets
RecursiveCharacterTextSplitter   # chunk_size=512, overlap=64
HuggingFaceEmbeddings            # ~60s to encode all chunks
FAISS.from_documents()           # <5s

The index is built once per Space restart and held in memory.

---

Setup & Deployment

1. Create a Hugging Face Space

• Go to huggingface.co/new-space
• SDK: Gradio
• Hardware: CPU Basic (free)

2. Upload files

Upload these files to the Space repository:

app.py
config.py
data_loader.py
vector_store.py
llm.py
rag_pipeline.py
requirements.txt

3. Set secrets

Go to Space → Settings → Repository secrets → New secret

Secret Name	Value
GROQ_API_KEY	From console.groq.com → API Keys
HF_DATASET	your-username/your-dataset-name
HF_TOKEN	Your HF token (only needed for private datasets)

4. Done

The Space will auto-rebuild. Startup takes ~3–5 minutes (embedding model download + indexing).

---

Environment Variables

All variables are read in config.py. You can also set them locally for development:

export GROQ_API_KEY="gsk_..."
export HF_DATASET="yourname/astrology-course-materials"
export HF_TOKEN=""          # leave blank for public datasets

python app.py

---

How to Add New Course Materials

1. Add the new PDF(s) to your ./astrology_books/ folder.
2. Re-run convert_pdfs.py (it will overwrite the existing dataset).
3. Restart the HF Space — it will re-index on next startup.

No code changes required.

---

Limitations & Guardrails

Limitation	Detail
No predictions	The system prompt explicitly forbids AstroBot from making personal predictions. This is enforced at the prompt level.
Grounded answers only	If the answer isn't in the course materials, AstroBot says so rather than hallucinating.
No chart interpretation	Questions about specific birth charts are declined.
Index is in-memory	The FAISS index is rebuilt on every Space restart (~3–5 min cold start).
Context window	Top-5 chunks are retrieved per query. Adjust TOP_K in config.py.
Language	Optimised for English. Other languages may work but are untested.

---

Troubleshooting

Space fails to start

• Check Logs tab in the Space for Python errors.
• Verify all 3 secrets are set (GROQ_API_KEY, HF_DATASET).

"GROQ_API_KEY is not set"

• Add the secret in Space → Settings → Repository secrets.

"No usable text column found"

• Your Parquet dataset doesn't have a column named text, content, etc.
• Either rename the column in your dataset, or add your column name to text_column_candidates in config.py.

Answers seem unrelated to the question

• Increase TOP_K in config.py (try 7–10).
• Decrease CHUNK_SIZE (try 256) for finer granularity.
• Check that your PDFs are text-extractable (not scanned images). Use OCR first if needed.

Groq rate limit errors

• Free Groq tier: 14,400 tokens/minute. For a class of many students, consider upgrading or rate-limiting the UI.

---