🧠 RecoBase: Neural Recommendation Engine & AI Assistant

A universal AI-powered recommendation engine delivered as a Chrome Extension. RecoBase understands any webpage you're browsing and provides intelligent, context-aware recommendations in real time.

📋 Overview

RecoBase is a full-stack AI recommendation system that works as a Chrome Extension. Unlike traditional recommendation engines that require pre-built product catalogs, RecoBase builds a real-time semantic understanding of your browsing session using transformer embeddings and FAISS vector search, augmented by Google Gemini's generative AI for comprehensive recommendations.

This is a standalone portfolio implementation demonstrating full-stack engineering across browser extensions, backend APIs, vector databases, and large language model integration. It captures context intelligently without intruding on the browsing experience.

🎯 Problem

Existing recommendation systems are fundamentally constrained by domain walls. They are:

• Platform-locked: Amazon recommends products on Amazon; Netflix recommends movies on Netflix.
• Data-hungry: They rely heavily on collaborative filtering which requires massive historical user data matrices.
• Siloed: Unable to synthesize intent across disparate browsing sessions or cross-domain content.
• Inaccessible: Not available to users as a proactive, browser-level assistant that travels with them.

💡 Solution

RecoBase provides a universal recommendation layer that transcends domain boundaries. It:

• Works Universally: Operates on ANY webpage — products, articles, videos, recipes, news.
• Intelligently Extracts: Employs a robust 4-layer DOM extraction engine to capture semantics regardless of site structure.
• Builds Ephemeral Memory: Creates per-session semantic memory dynamically using FAISS and sentence-transformers.
• Leverages LLMs: Synthesizes retrieved context with Gemini RAG for intelligent, natural-language recommendations.
• Integrates Smoothly: Delivers insights through a polished, non-intrusive React-based browser panel using Shadow DOM.

🏗️ Architecture

graph TD
    subgraph Browser["Client (Chrome Extension)"]
        CS[Content Script]
        UI[React Shadow DOM Panel]
        BG[Background Service Worker]
    end

    subgraph Backend["FastAPI Backend (Docker)"]
        API[REST API Layer]
        EXT[Extraction Engine]
        RAG[Gemini RAG Pipeline]
        VEC[Embedding Service]
    end

    subgraph Data["Storage Layer"]
        REDIS[(Redis)]
        FAISS[(FAISS Index)]
    end

    CS -->|1. Extract DOM Context| BG
    BG -->|2. POST /track| API
    API --> EXT
    EXT -->|Structured Data| REDIS
    EXT --> VEC
    VEC --> FAISS

    UI -->|3. GET /recommend| BG
    BG --> API
    API --> FAISS
    FAISS -->|Similar Context| RAG
    RAG -->|LLM Completion| API
    API --> UI

Loading

The system follows a scalable layered architecture designed for separation of concerns and high performance:

1. Presentation Layer: A React-based Chrome Extension injecting a floating panel. It uses Shadow DOM to prevent CSS conflicts with host pages.
2. Extraction Layer: A 4-stage heuristic engine processing structured (JSON-LD, Open Graph) and unstructured HTML data into standardized schemas.
3. API Layer: Fast, async FastAPI REST endpoints validating payloads with Pydantic v2.
4. Storage Layer: Redis handles fast session tracking, rate limiting, and state, while FAISS maintains dense vector indexes.
5. Intelligence Layer: Uses sentence-transformers/all-MiniLM-L6-v2 for localized embeddings, feeding into a Gemini-powered Retrieval-Augmented Generation (RAG) system.

✨ Features

• 🌐 Universal Context Extraction: Gracefully degrades through JSON-LD, Open Graph, meta tags, and raw DOM heuristics.
• 🧠 Dynamic Semantic Memory: FAISS indices built on-the-fly per session. No pre-training needed.
• 🤖 Generative RAG: Google Gemini API integration to synthesize contextual recommendations.
• 🎨 Robust UI: React 18 frontend with Shadow DOM isolation, skeleton loaders, and error boundaries.
• ⚡ Resilience: Automatic retry logic and graceful degradation if APIs are rate-limited.
• 🔒 Secure Design: Environment variable configuration. No API keys shipped in extension code.
• 🐳 Containerized Deployment: Docker Compose for deterministic, one-command local setup.
• 📊 Progressive Enrichment: Recommendations adapt in real-time as you browse more pages.

🛠️ Tech Stack

Layer	Technology
Extension	React 18, Vite, CRXJS, Chrome Manifest V3, Shadow DOM CSS
Backend	Python 3.11, FastAPI, Uvicorn, Pydantic v2
AI/ML	sentence-transformers/all-MiniLM-L6-v2, FAISS, Google Gemini
Storage	Redis 7
Infrastructure	Docker, Docker Compose

🔄 How It Works

1. Browsing: The user navigates to a webpage. The extension's content script quietly observes.
2. Extraction: A multi-layered parsing script scans the page for metadata (JSON-LD, Open Graph, DOM heuristics) to build a semantic profile of the content.
3. Tracking: The extracted profile is sent to the backend /track endpoint via the Background Service Worker.
4. Embedding: The backend vectorizes the text using sentence-transformers and updates the active session's FAISS index.
5. Recommendation Request: When the user opens the RecoBase panel, a /recommend request is dispatched.
6. RAG Pipeline: The backend retrieves top-k similar contexts from FAISS for the session, crafts a tailored prompt, and queries Google Gemini.
7. Delivery: The synthesized recommendations are streamed back and beautifully rendered in the React UI.

🧩 Chrome Extension

The extension is built on Manifest V3, adhering to modern security standards. It consists of:

• Content Script: Injected into every page to perform DOM extraction without affecting page performance.
• Background Service Worker: Manages state, handles communication with the backend API, and routes messages.
• Shadow DOM UI: The React interface is mounted inside a Shadow DOM root. This guarantees that host page styles (like Wikipedia or Amazon) do not leak into the RecoBase UI, and vice versa.

🔍 DOM Context Extraction

Relying on a single source of truth is brittle. RecoBase employs a cascading 4-layer extraction strategy:

1. JSON-LD: High precision, standardized schema data often found on modern e-commerce and media sites.
2. Open Graph: Social sharing metadata (og:title, og:description), reliable for news and blogs.
3. Meta Tags: Fallback standard HTML tags (<title>, <meta name="description">).
4. DOM Heuristics: Custom logic extracting <article>, <h1>, and main body paragraphs if structured data is absent.

🤖 Recommendation Engine

RecoBase utilizes a dual-path architecture to ensure relevance and quality without needing a static database.

FAISS Semantic Retrieval

Instead of collaborative filtering across millions of users, RecoBase builds a personal semantic space per session. As you browse, FAISS creates dense vectors of page content. This allows the system to instantly recall structurally similar or semantically related pages you've visited recently to form context.

Gemini RAG Pipeline

The raw vectors lack human intuition. We take the top results from FAISS and inject them into a structured prompt for Google Gemini. Gemini acts as the reasoning engine, understanding the explicit relationships (e.g., "The user is looking at hiking boots and previously viewed waterproof jackets") to generate actionable, cross-domain recommendations.

🗄️ Redis Context Management

Redis acts as the high-speed caching and state management tier. It stores:

• Session IDs: Correlating requests to specific user sessions.
• Browsing History: A fast-access list of recently visited URLs and their basic metadata.
• Rate Limits: Preventing abuse of the AI endpoints.
• TTL: Sessions automatically expire, ensuring privacy and keeping memory footprint low.

📡 API Endpoints

Method	Endpoint	Description
GET	/health	Health check with Redis and model status
POST	/api/v1/extension/track	Track current page context and update session vectors
GET	/api/v1/extension/recommend	Get contextual recommendations based on session memory

(See docs/api.md for full request/response schemas)

📁 Project Structure

reco-base/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   └── routes/       # FastAPI route handlers
│   │   ├── schemas/          # Pydantic request/response models
│   │   ├── services/         # Redis, FAISS, Gemini, Embedding, Recommendation
│   │   ├── utils/            # Input sanitization
│   │   ├── config.py         # pydantic-settings configuration
│   │   └── main.py           # App entry point, lifespan, CORS
│   ├── tests/                # pytest test suite
│   ├── Dockerfile
│   └── requirements.txt
├── extension/
│   ├── src/
│   │   ├── background/       # Service worker (message routing)
│   │   ├── content/          # React app mounted in Shadow DOM
│   │   │   ├── components/   # RecoPanel, RecoCard, LoadingSkeleton, etc.
│   │   │   └── styles/       # Scoped panel CSS
│   │   ├── extractors/       # 4-layer DOM extraction engine
│   │   ├── popup/            # Extension popup UI (React)
│   │   └── services/         # API client, session management
│   ├── manifest.json
│   ├── package.json
│   └── vite.config.js
├── docker/                   # Redis config
├── docs/                     # API, architecture, extraction docs
├── data/                     # Generated data (gitignored)
├── .env.example
├── docker-compose.yml
└── README.md

🚀 Installation

Prerequisites

• Python 3.11+
• Node.js 18+
• Docker & Docker Compose
• Google Gemini API key

Quick Start

1. Clone the repository

   git clone https://github.com/yourusername/reco-base.git
   cd reco-base

2. Setup environment variables

   cp .env.example .env
   # Edit .env and add your GEMINI_API_KEY

3. Start the backend services

   docker-compose up -d

4. Build the extension

   cd extension
   npm install
   npm run build

5. Load in Chrome:
   • Navigate to chrome://extensions
   • Enable Developer Mode
   • Click Load Unpacked
   • Select the extension/dist folder
6. Navigate to any webpage and click the RecoBase icon!

🔐 Environment Variables

Variable	Description	Default
GEMINI_API_KEY	Required. API key for Google Gemini	—
GEMINI_MODEL	Gemini model to use	gemini-2.0-flash
REDIS_HOST	Redis server hostname	localhost
REDIS_PORT	Redis server port	6379
REDIS_DB	Redis database number	0
REDIS_TTL_SECONDS	Session TTL in seconds	1800
BACKEND_HOST	FastAPI bind host	0.0.0.0
BACKEND_PORT	FastAPI bind port	8000
BACKEND_CORS_ORIGINS	Allowed CORS origins (comma-separated)	chrome-extension://*
EMBEDDING_MODEL	Sentence Transformer model name	sentence-transformers/all-MiniLM-L6-v2
MAX_HISTORY_LENGTH	Max pages tracked per session	50

🧪 Testing

Backend Tests

The backend features a comprehensive test suite using pytest.

cd backend
pip install -r requirements.txt
pytest -v

End-to-End Verification

1. Open a clean Chrome profile.
2. Load the extension.
3. Browse 3 distinct e-commerce products.
4. Verify backend logs for successful /track calls.
5. Open the RecoBase panel; verify recommendations synthesize the 3 products.

📸 Screenshots

Screenshots will be added after the extension UI is finalized.

⚡ Performance

Actual measurements to be recorded during load testing.

Metric	Target
DOM extraction	< 100ms
Backend response (cached)	< 500ms
Gemini recommendation	1-3s (depends on API)
Panel render	< 50ms

⚠️ Limitations

• Extraction accuracy heavily depends on the target site adhering to web standards. Single Page Applications (SPAs) without SSR may yield sparse data.
• FAISS vectors are kept purely in memory/Redis per session and are volatile by design; long-term user profiling is intentionally out of scope for this version.
• LLM generation latency is bound by Google Gemini's API response times.

🔮 Future Improvements

• Streaming RAG responses via WebSockets or Server-Sent Events (SSE) to reduce perceived latency.
• Expanding vector dimensions for more granular semantic capture.
• Adding site-specific extraction adapters for complex sites (e.g., YouTube video transcripts).
• Persisting anonymized semantic clusters for global trending recommendations.

👤 Author

Aditya Bansode

This is a standalone personal portfolio implementation of the RecoBase concept. I am the sole developer of every component — Chrome Extension, DOM extraction, FastAPI backend, Redis integration, FAISS session memory, Gemini RAG pipeline, testing, Docker configuration, and documentation.

📄 License

MIT License — see LICENSE