🎓 IntelliSelect — Chrome Extension

AI-powered study companion that explains, answers, and illustrates any text you select — right inside your browser.

---

📋 Table of Contents

1. Overview
2. Features
3. Architecture
4. File Structure
5. API & Backend
6. Installation & Setup
7. Usage Guide
8. Configuration Reference
9. Troubleshooting
10. Testing

---

🌟 Overview

IntelliSelect is a Chrome Extension (Manifest V3) that supercharges your learning sessions. Highlight any text on any webpage and instantly receive either a concise answer or a rich, in-depth explanation — complete with educational diagrams and illustrations.

The extension is powered by a local Node.js + Express backend that intelligently routes requests across multiple AI providers using a racing strategy — always returning the fastest available response.

---

🚀 Features

🌓 Dual Operating Modes

Feature	Answer Mode	Learning Mode
UI	Floating Toast Popup	Persistent Right Sidebar
Best For	MCQs, True/False, Quick facts	Concepts, Theories, Definitions
AI Provider	Groq (ultra-fast)	OpenRouter / Gemini (detailed)
Images	❌ No	✅ Yes — Educational Visuals
Activation	Toggle → A	Toggle → L

---

🖼️ Educational Image Search (Learning Mode only)

When you highlight text in Learning Mode, the extension:

1. Generates AI-driven queries — The AI creates 3 specific search terms (e.g., "DNA replication flowchart", "Helicase enzyme illustration") instead of using raw text.
2. Fetches educational visuals via SerpAPI (Google Images) targeting diagrams, flowcharts, and scientific illustrations.
3. Displays a responsive gallery in the sidebar below the explanation — click any image to open a full-screen Lightbox Modal.

---

⚡ Performance & Reliability

• AI Racing Strategy: All available providers (Groq, Gemini, OpenRouter) are queried simultaneously. The first successful response wins. This eliminates single-provider latency and adds automatic failover.
• Asynchronous Image Loading: Text explanations appear instantly. Images load in the background and "pop in" once ready — a loading spinner keeps the user informed.
• In-Memory Caching: The backend caches results for 1 hour. Repeated queries are served in milliseconds with zero API cost.
• Cross-Frame Support: Selections inside embedded iframes (e.g., quiz platforms) are correctly routed to the top-level sidebar.

---

🎨 Premium User Experience

• Green Text Selection Highlight: When you release a selection, it turns green to confirm the API has received your query.
• Live Status Bar: A floating pill at the top of the screen shows Selecting... → Sent as the request progresses.
• Markdown Rendering: AI responses with **bold** text are properly rendered as bold in both the sidebar and toast. Newlines are also preserved.
• Glassmorphism UI: Dark, frosted-glass design with smooth cubic-bezier animations on all panels and modals.

---

🏗️ Architecture

User selects text
      │
      ▼
[content.js] ──────────────────────────────────────────────────────┐
  Detects mouseup/keyup                                             │
  Sets green selection highlight                                    │
  Shows "Selecting..." status bar                                   │
      │                                                             │
      ▼                                                             │
[background.js] (MV3 Service Worker)                               │
  Routes AI_REQUEST to backend /api/ai                             │
  Routes IMAGE_REQUEST to backend /api/images                      │
  BROADCAST_UI handler relays events across frames                 │
      │                              │                             │
      ▼                              ▼                             │
[/api/ai]                    [/api/images]                         │
  Race: Groq vs Gemini          AI generates 3 search queries      │
  vs OpenRouter                 SerpAPI fetches top 5 images       │
  Returns: { result }           Returns: { images: [...urls] }     │
      │                              │                             │
      └──────────────┬───────────────┘                             │
                     ▼                                             │
              [content.js] ◄─────────────────────────────────────┘
                Renders text immediately
                Images pop in asynchronously
                     │
            ┌────────┴────────┐
            ▼                 ▼
       [sidebar.js]      [toast.js]
       (Learning Mode)   (Answer Mode)

---

📁 File Structure

Extension/
│
├── manifest.json          # Chrome Extension manifest (MV3)
├── content.js             # Injected into every page; handles text selection,
│                          #   status bar, green highlight, and sidebar orchestration
├── background.js          # Service worker; routes messages between content
│                          #   scripts and backend; handles cross-frame broadcast
├── api.js                 # Content-side helper; wraps chrome.runtime.sendMessage
│                          #   into clean async functions (requestAi, requestImages)
├── sidebar.js             # Builds & manages the Learning Mode right sidebar,
│                          #   image grid, lightbox modal, and Markdown parser
├── toast.js               # Builds & manages the Answer Mode floating toast
│                          #   notification with copy button and auto-dismiss
├── styles.css             # All injected styles: sidebar, toast, image grid,
│                          #   lightbox modal, status bar, loading spinner
├── popup.html             # Extension toolbar popup (settings UI)
├── popup.js               # Popup logic: saves backend URL and mode preference
├── popup.css              # Popup styles
│
└── backend/
    ├── server.js          # Express server: /api/ai, /api/images, /health
    │                      #   AI racing logic, image query gen, SerpAPI, caching
    ├── package.json
    ├── .env               # Your actual API keys (git-ignored)
    ├── .env.example       # Template for required environment variables
    └── test_serpapi.js    # One-shot SerpAPI connectivity test script

---

🔌 API & Backend

The backend exposes three endpoints:

GET /health

Returns the server status and which AI providers are currently configured.

{ "ok": true, "providersConfigured": ["groq", "gemini", "openrouter"] }

---

POST /api/ai

Generates an AI explanation or answer for selected text.

Request Body:

{
  "mode": "learn" | "answer",
  "text": "The selected text from the webpage"
}

Response:

{
  "result": "The AI-generated explanation..."
}

Logic:

• answer mode: Short, direct. Best for MCQs. Format: Option [X]: [One-line explanation].
• learn mode: Friendly teacher format with headings, bullets, analogies, and summary.
• Uses Promise.any() to race all configured providers simultaneously.
• Results are cached for 1 hour per unique mode:text key.

---

POST /api/images

Generates educational image search queries and fetches visuals via SerpAPI.

Request Body:

{
  "text": "The selected text to find visuals for"
}

Response:

{
  "images": [
    "https://example.com/dna-diagram.jpg",
    "https://example.com/replication-flowchart.png"
  ]
}

Logic:

1. Races all AI providers to generate 3 optimized search queries.
2. Falls back to the raw selected text if AI query generation fails.
3. Calls SerpAPI's google_images engine with the first query.
4. Returns up to 5 unique, medium-sized image URLs.

---

🛠️ Installation & Setup

Prerequisites

• Node.js v18 or higher
• Google Chrome browser
• At least one AI provider API key (see below)

Step 1: Clone the Repository

git clone https://github.com/zainabraza06/AI_study_assistant.git
cd AI_study_assistant

Step 2: Backend Setup

cd backend
npm install

Create a .env file in the backend/ directory:

# Server
PORT=3000

# AI Providers (set at least one; more = faster racing fallback)
GROQ_API_KEY=gsk_...          # https://console.groq.com/
GEMINI_API_KEY=AIza...        # https://aistudio.google.com/
OPENROUTER_API_KEY=sk-or-...  # https://openrouter.ai/

# Optional model overrides
GROQ_MODEL=llama-3.1-70b-versatile
GEMINI_MODEL=gemini-1.5-flash
OPENROUTER_MODEL=meta-llama/llama-3.1-70b-instruct

# Image Search — Required for Educational Visuals
SERPAPI_API_KEY=...            # https://serpapi.com/

Start the backend:

npm start
# → IntelliSelect backend listening on https://intelliselect.onrender.com

Step 3: Load the Extension

1. Open Chrome and navigate to chrome://extensions/
2. Enable Developer Mode (top-right toggle)
3. Click Load unpacked
4. Select the root of this project (the folder containing manifest.json)

Step 4: Configure the Extension

1. Click the extension icon in the Chrome toolbar
2. Set Backend URL to https://intelliselect.onrender.com
3. Save settings

---

📖 Usage Guide

Activating the Assistant

Click the circular badge at the bottom-left of any webpage:

• Badge shows A = Answer Mode is active
• Badge shows L = Learning Mode is active
• Badge is grey = Disabled

Clicking the badge when disabled opens a Mode Selection popup where you choose your mode and activate.

Answer Mode

1. Enable the assistant (badge = A)
2. Select any text on the page
3. A floating toast appears with:
   • A concise answer or Option [X]: reason for MCQs
   • A Copy button to copy the answer
   • Auto-dismisses after 8 seconds

Learning Mode

1. Enable the assistant (badge = L)
2. Select any text — the sidebar slides in from the right
3. Phase 1 (Instant): AI explanation appears with full Markdown formatting
4. Phase 2 (Background): A loading spinner appears, then educational images pop in below
5. Click any image to expand it in a full-screen Lightbox Modal

Visual Feedback During a Request

Indicator	Meaning
Text turns green	Selection received, sending to AI
"Selecting..." pill at top	Request is being processed
"Sent" pill (fades out)	Request successfully delivered
Sidebar loading spinner	AI images being fetched

---

⚙️ Configuration Reference

Variable	Required	Description
PORT	No	Backend port (default: 3000)
GROQ_API_KEY	Recommended	Best for Answer Mode (fastest)
GEMINI_API_KEY	Optional	Good for Learning Mode explanations
OPENROUTER_API_KEY	Optional	Fallback provider
GROQ_MODEL	No	Override Groq model name
GEMINI_MODEL	No	Override Gemini model name
OPENROUTER_MODEL	No	Override OpenRouter model name
SERPAPI_API_KEY	For Images	Required to show educational visuals

Tip: Configure all three AI providers for the best racing performance and highest reliability.

---

🔧 Troubleshooting

"Extension API not ready"

The content scripts haven't loaded yet. Try refreshing the page.

"Error: data not defined"

Reload the extension from chrome://extensions/ and refresh the tab. This occurs after extension updates.

Images not appearing

1. Check your SERPAPI_API_KEY is set correctly in .env
2. Restart the backend: npm start
3. Run node test_serpapi.js in the backend/ folder to verify the key works

AI response is slow

• Ensure at least Groq is configured (it's the fastest provider)
• Check that the backend is running: visit https://intelliselect.onrender.com/health
• The first query after starting the server may be slower (cold start)

Extension not detecting text selection

• Some sites with heavy CSP policies may block injected scripts
• Try reloading the page after enabling the extension

---

🧪 Testing

Verify Backend Health

curl https://intelliselect.onrender.com/health

Expected: {"ok":true,"providersConfigured":["groq","gemini","openrouter"]}

Test SerpAPI Image Search

cd backend
node test_serpapi.js

Expected:

Testing SerpAPI with key: Present
Successfully fetched 100 images.
First image URL: https://...
TEST PASSED ✅

Test AI Endpoint Directly

curl -X POST https://intelliselect.onrender.com/api/ai \
  -H "Content-Type: application/json" \
  -d '{"mode":"learn","text":"What is photosynthesis?"}'

---

Built with ❤️ for students who want to learn smarter, not harder.