Add project README with architecture, tech stack, and setup guide

README.md

@@ -1,207 +1,135 @@
----
-base_model: TinyLlama/TinyLlama-1.1B-Chat-v1.0
-library_name: peft
-pipeline_tag: text-generation
-tags:
-- base_model:adapter:TinyLlama/TinyLlama-1.1B-Chat-v1.0
-- lora
-- transformers
----
-
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
-
-
-
-## Model Details
-
-### Model Description
-
-<!-- Provide a longer summary of what this model is. -->
-
-
-
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
-
-### Model Sources [optional]
-
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
-
-## Uses
-
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
-### Direct Use
-
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+# 🧙 CodeSage
 
-#### Preprocessing [optional]
+**A comparative study of three LLM strategies for domain-specific question answering.**
 
-[More Information Needed]
+CodeSage puts a Baseline LLM, a RAG pipeline, and a Fine-Tuned model side-by-side so you can ask the same programming question and immediately see how each approach differs in accuracy, grounding, and speed.
 
+---
 
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
+## Why This Project?
 
-[More Information Needed]
+When building an AI assistant for a specific domain (here: programming / DSA / web dev), you have three realistic options:
 
-#### Software
+| Approach | Core idea | Trade-off |
+|---|---|---|
+| **Baseline LLM** | Prompt a large general-purpose model | Fast, zero setup — but may hallucinate or give vague answers |
+| **RAG** | Retrieve relevant docs first, then generate | Grounded answers, updatable knowledge — retrieval adds latency |
+| **Fine-Tuning** | Train a smaller model on domain data | Potentially fastest, very focused — expensive to update |
 
-[More Information Needed]
+There is no universal winner. The goal of CodeSage is to **make that trade-off visible** with real side-by-side outputs and user-rated metrics.
 
-## Citation [optional]
+---
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+## What It Does
 
-**BibTeX:**
+1. You type (or click) a programming question.
+2. All three systems answer it simultaneously.
+3. You see each answer, the RAG system's retrieved context, and response times.
+4. You rate each answer (correctness, completeness, hallucination).
+5. A live metrics table aggregates your ratings across all questions.
 
-[More Information Needed]
+---
 
-**APA:**
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Streamlit UI                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
+│  │  System 1    │  │  System 2    │  │ System 3  │  │
+│  │  Baseline    │  │    RAG       │  │ Fine-Tuned│  │
+│  └──────┬───────┘  └──────┬───────┘  └─────┬─────┘  │
+└─────────┼─────────────────┼────────────────┼─────────┘
+          │                 │                │
+          ▼                 ▼                ▼
+   Groq API           FAISS index      TinyLlama 1.1B
+   Llama 3.1 8B    +  HuggingFace   (LoRA adapter loaded
+   (prompt only)      embeddings     locally via PEFT)
+                          │
+                      Groq API
+                      Llama 3.1 8B
+                      (with context)
+```
+
+### System 1 — Baseline LLM
+Sends the question directly to **Llama 3.1 8B** (via Groq) with a short system prompt. No extra knowledge. Represents what an off-the-shelf LLM can do.
+
+### System 2 — RAG (Retrieval-Augmented Generation)
+1. The question is embedded with `all-MiniLM-L6-v2` (HuggingFace Sentence Transformers).
+2. Top-3 most similar chunks are retrieved from a **FAISS** vector store built from 17 hand-written `.txt` documents covering DSA topics and web dev concepts.
+3. Those chunks are injected as context into the prompt sent to **Llama 3.1 8B** via Groq.
+
+### System 3 — Fine-Tuned Model
+**TinyLlama 1.1B** fine-tuned with **LoRA (Low-Rank Adaptation)** on ~20 curated programming Q&A pairs. Training is done on Google Colab (free GPU). The resulting adapter is loaded locally via the `peft` library for inference.
 
-[More Information Needed]
+---
 
-## Glossary [optional]
+## Tech Stack
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+| Layer | Technology |
+|---|---|
+| UI | Streamlit |
+| LLM inference | Groq API — `llama-3.1-8b-instant` |
+| Embeddings | `sentence-transformers/all-MiniLM-L6-v2` |
+| Vector store | FAISS (CPU) via LangChain |
+| Fine-tuning | HuggingFace Transformers + PEFT (LoRA) |
+| Base model | TinyLlama/TinyLlama-1.1B-Chat-v1.0 |
+| Training platform | Google Colab |
+| Background animation | HTML5 Canvas (3D particle network via `components.html`) |
 
-[More Information Needed]
+---
 
-## More Information [optional]
+## How to Run
+
+### 1. Clone & install
+```bash
+git clone https://github.com/Adityax-07/LLM-vs-RAG-vs-Fine-Tuning-.git
+cd LLM-vs-RAG-vs-Fine-Tuning-
+pip install -r requirements.txt
+```
+
+### 2. Set your Groq API key
+Create a `.env` file:
+```
+GROQ_API_KEY=your_key_here
+```
+Get a free key at [console.groq.com](https://console.groq.com).
+
+### 3. Run the app
+```bash
+streamlit run demo.py
+```
+The FAISS index is built automatically on first launch.
+
+### 4. (Optional) Load the fine-tuned model
+1. Open `system3_finetune_colab.ipynb` in Google Colab.
+2. Run all cells — training takes ~10 min on a free T4 GPU.
+3. Download `finetuned_model.zip` and unzip it in the project root.
+4. Restart the Streamlit app — System 3 will now return real answers.
 
-[More Information Needed]
+---
 
-## Model Card Authors [optional]
+## Knowledge Base
 
-[More Information Needed]
+The RAG system retrieves from 17 topic documents in `data/docs/`:
 
-## Model Card Contact
+`binary_search` · `sorting_algorithms` · `dynamic_programming` · `graph_algorithms` · `trees` · `linked_list` · `stack_queue` · `recursion` · `backtracking` · `greedy_algorithms` · `hashing` · `string_algorithms` · `two_pointers` · `react_hooks` · `rest_api` · `javascript_promises` · `css_flexbox`
 
-[More Information Needed]
-### Framework versions
+---
 
-- PEFT 0.18.1
+## Project Structure
+
+```
+├── demo.py                       # Streamlit app
+├── system1_baseline.py           # Baseline LLM (Groq)
+├── system2_rag.py                # RAG pipeline (FAISS + Groq)
+├── system3_inference.py          # Fine-tuned model inference
+├── system3_finetune_colab.ipynb  # LoRA training notebook
+├── data/
+│   ├── docs/                     # 17 knowledge base documents
+│   ├── faiss_index/              # FAISS vector store (auto-built)
+│   ├── finetune_data.jsonl       # Training data for fine-tuning
+│   └── questions.csv             # Evaluation question set
+├── finetuned_model/              # LoRA adapter (after training)
+└── requirements.txt
+```