# swagath18/personalized-recommender architecture

> Architecture diagram of the GitHub repository swagath18/personalized-recommender, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swagath18/personalized-recommender
- Repository: https://github.com/swagath18/personalized-recommender

## Overview

##### Project type and purpose
- This is a Python-based, full-stack recommender prototype combining Retrieval-Augmented Generation (RAG) with GPT-4, FAISS vector search, hybrid reranking, a Gradio UI, and feedback sentiment analysis (VADER).
- Purpose: accept a user query + context, retrieve semantically relevant products, ask GPT-4 to craft recommendations, display results, collect feedback, analyze sentiment, and log everything.

##### File structure
- Top-level scripts:
- llmpoweredrag.py – main end-to-end application (UI + retrieval + RAG)
- llmragsenti.py – likely includes feedback-sentiment components
- Data/config:
- amazon_electronics_products.csv – product catalog
- .env – API keys
- recommendation_log.txt, feedback_log.txt – audit logs
- Supporting: .gradio folder holds UI session data

##### README for additional insights
- Confirms use of: SentenceTransformers → FAISS → GPT-4 → hybrid reranking → Gradio UI → VADER
- Describes multi-tab UI (Recommend + Feedback)
- Shows expected query/context inputs and output examples
- Mentions logging for auditability

##### Main components & their interactions
a. User Interface (Gradio)
- Input “Query” + optional “Context” fields
- Two tabs: Recommendations, Feedback
b. Retrieval Engine
- SentenceTransformers embeds query/context
- FAISS vector search on product embeddings → top-k items
c. RAG / GPT-4 Service
- Constructs prompt: retrieved items + user context
- Sends to OpenAI GPT-4 API → returns natural-language recommendations
d. Reranking Module
- Computes cosine similarity between user context and each retrieved product
- Reorders items (hybrid reranking)
e. Feedback Sentiment Analyzer
- Captures user free-text feedback
- Runs VADER → sentiment score
f. Logging / Audit Trail
- recommendation_log.txt logs queries, prompts, GPT responses
- feedback_log.txt logs feedback + timestamp + sentiment
g. Data Store
- CSV of products (static)
- In-memory or ephemeral storage for embeddings

##### Proper flow from input to output
1) User enters “Query” + “Context” in Gradio UI → hits Recommend
2) Application loads embeddings of products (precomputed or on-the-fly)
3) Sentence Transformers encodes user input → FAISS returns top N candidates
4) Hybrid Reranking computes context-cosine scores → sorts candidate list
5) Build a RAG prompt with top candidates + context → call GPT-4 API
6) Receive GPT-4 response → parse recommended items + descriptions
7) In Recommendations tab
8) User provides feedback in Feedback tab → app logs feedback text
9) VADER analyzes sentiment → logs sentiment to feedback_log.txt
10) End-to-end logs saved for audit

##### Architectural patterns & design principles
- Modular pipelines (retrieval, reranking, generation, sentiment)
- Separation of concerns: UI, business logic, external services
- RAG pattern: augment LLM with external knowledge store (FAISS)
- Hybrid ranking: mix vector-search relevance + semantic context scoring
- Auditability: append-only logs for compliance

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer"
        UI["Gradio UI"]:::ui
    end

    UI -->|"query+context"| Encoder["SentenceTransformer Encoder"]:::compute
    subgraph "Retrieval Engine"
        FAISS["FAISS Index"]:::compute
    end
    Encoder -->|"embeddings"| FAISS
    FAISS -->|"top-k candidates"| Reranker["Hybrid Reranking Module"]:::compute
    Reranker -->|"ranked products"| Prompt["RAG Prompt Builder"]:::compute
    Prompt -->|"GPT prompt"| GPT4["OpenAI GPT-4 API"]:::external
    Env[".env (API Key)"]:::datastore
    Env --> GPT4
    GPT4 -->|"GPT response"| UI
    GPT4 -->|"response+metadata"| RecLog["Recommendation Audit Log"]:::datastore

    subgraph "Feedback Flow"
        UI -->|"feedback text"| FeedbackUI["Feedback UI"]:::ui
        FeedbackUI -->|"feedback text"| Sentiment["VADER Sentiment Analyzer"]:::compute
        Sentiment -->|"sentiment score"| FeedbackLog["Feedback Audit Log"]:::datastore
    end

    ProductCSV["Product Catalog CSV"]:::datastore
    ProductCSV --> FAISS

    GradioData[".gradio Session Data"]:::datastore
    UI --> GradioData

    classDef compute fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px
    classDef ui fill:#DDA0DD,stroke:#333,stroke-width:1px

    click UI "https://github.com/swagath18/personalized-recommender/blob/main/llmpoweredrag.py"
    click Encoder "https://github.com/swagath18/personalized-recommender/blob/main/llmpoweredrag.py"
    click FAISS "https://github.com/swagath18/personalized-recommender/blob/main/llmpoweredrag.py"
    click Reranker "https://github.com/swagath18/personalized-recommender/blob/main/llmpoweredrag.py"
    click Prompt "https://github.com/swagath18/personalized-recommender/blob/main/llmpoweredrag.py"
    click GPT4 "https://github.com/swagath18/personalized-recommender/blob/main/llmpoweredrag.py"
    click FeedbackUI "https://github.com/swagath18/personalized-recommender/blob/main/llmragsenti.py"
    click Sentiment "https://github.com/swagath18/personalized-recommender/blob/main/llmragsenti.py"
    click ProductCSV "https://github.com/swagath18/personalized-recommender/blob/main/amazon_electronics_products.csv"
    click RecLog "https://github.com/swagath18/personalized-recommender/blob/main/recommendation_log.txt"
    click FeedbackLog "https://github.com/swagath18/personalized-recommender/blob/main/feedback_log.txt"
    click GradioData "https://github.com/swagath18/personalized-recommender/tree/main/.gradio/"
    click Env "https://github.com/swagath18/personalized-recommender/blob/main/.env"
```
