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](#project-overview)
2. [Tech Stack](#tech-stack)
3. [Architecture](#architecture)
4. [File Structure](#file-structure)
5. [Module Responsibilities](#module-responsibilities)
6. [Data Pipeline](#data-pipeline)
7. [Setup & Deployment](#setup--deployment)
8. [Environment Variables](#environment-variables)
9. [How to Add New Course Materials](#how-to-add-new-course-materials)
10. [Limitations & Guardrails](#limitations--guardrails)
11. [Troubleshooting](#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:

```bash

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](https://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](https://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:

```bash

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.

---