From 5779408bfee1df7c64a9d1371f0fbeb03f505b85 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 22:00:10 +0530 Subject: [PATCH 01/20] Update README.md --- README.md | 62 +++++++++++++++++++++++++++---------------------------- 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 90ac0e13..f17b44f3 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,42 @@ # Perspective-AI ![Perspective banner](frontend/public/perspective_banner.jpg) -### Table of Contents -- [Perspective-AI](#perspective-ai) - - [Table of Contents](#table-of-contents) - - [System Overview](#system-overview) - - [High-Level Concept](#high-level-concept) - - [Architecture Components](#architecture-components) - - [1. Frontend Layer](#1-frontend-layer) - - [3. Core Backend](#3-core-backend) - - [4. AI \& NLP Integration](#4-ai--nlp-integration) - - [5. Data Storage](#5-data-storage) - - [Technical Stack](#technical-stack) - - [Frontend Technologies](#frontend-technologies) - - [Backend Technologies](#backend-technologies) - - [I Integration](#i-integration) - - [Core Features](#core-features) - - [1. Counter-Perspective Generation](#1-counter-perspective-generation) - - [2. Reasoned Thinking](#2-reasoned-thinking) - - [3. Updated Facts](#3-updated-facts) - - [4. Seamless Integration](#4-seamless-integration) - - [5. Real-Time Analysis](#5-real-time-analysis) - - [Data Flow \& Security](#data-flow--security) - - [Setup \& Deployment](#setup--deployment) - - [Frontend Setup](#frontend-setup) - - [Backend Setup](#backend-setup) - - [Architecture Diagram](#architecture-diagram) - - [Expected Outcomes](#expected-outcomes) - - [Required Skills](#required-skills) - ---- - ## System Overview -Perspective-AI is designed to combat the echo chambers created by personalized content algorithms. It actively curates counterarguments and alternative narratives from credible sources alongside the content you usually see. Whether it’s a news article, blog post, or social media update, Perspective-AI analyzes the existing narrative and presents a balanced, in-depth counter-perspective. This approach not only challenges your current viewpoints but also helps broaden your understanding of complex issues—all in real time. +Perspective-AI is an AI-powered web app that analyzes online articles and generates fact-based counter-perspectives to reduce bias and echo chambers. Using NLP, RAG, and LLMs, it extracts key points, verifies information, and presents balanced alternative viewpoints in real time. -### High-Level Concept Imagine having a smart, opinionated friend who isn’t afraid to challenge your beliefs with well-articulated counterpoints—that’s Perspective-AI in a nutshell! --- +## Setup & Deployment + +### Prerequisites + +- Node.js 18+ +- Python 3.10+ +- uv package manager → https://docs.astral.sh/uv/ +- API keys: + - Groq/OpenAI API key + - Pinecone API key + - Google Custom Search API key + - (Optional) HuggingFace access token + +### Frontend Setup + +```bash +cd frontend +cp .env.example .env +npm install +npm run dev +``` +### Backend Setup + +```bash +cd backend +cp .env.example .env +uv sync +uv run main.py +``` ## Architecture Components From cd4dbdb76d27903a4619376862656b1f956939e0 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 22:02:31 +0530 Subject: [PATCH 02/20] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f17b44f3..b1657d04 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Perspective-AI is an AI-powered web app that analyzes online articles and genera Imagine having a smart, opinionated friend who isn’t afraid to challenge your beliefs with well-articulated counterpoints—that’s Perspective-AI in a nutshell! --- + ## Setup & Deployment ### Prerequisites @@ -37,6 +38,7 @@ cp .env.example .env uv sync uv run main.py ``` +--- ## Architecture Components From 7de762b4f8dd4147226ef5612bab2e066d4a5a93 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 22:13:00 +0530 Subject: [PATCH 03/20] Update README.md --- README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 55 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index b1657d04..2337be70 100644 --- a/README.md +++ b/README.md @@ -40,23 +40,66 @@ uv run main.py ``` --- -## Architecture Components -### 1. Frontend Layer -- **Next.js UI**: A sleek, responsive interface that displays content alongside counter perspectives. +## Architecture Diagram + -### 3. Core Backend -- **FastAPI Server**: A high-performance API server handling requests, content analysis, and response delivery. -- **Content Analyzer**: Processes incoming articles or posts to identify the dominant narrative. -- **Counter-Narrative Engine**: Uses advanced AI and NLP techniques to generate alternative perspectives and reasoned analyses. +```mermaid +graph TB + %% Define Subgraphs with Colors and Text Styles + subgraph Client Side + style UI fill:#FFDDC1,stroke:#FF6600,stroke-width:2px,color:#000,font-weight:bold + UI[Next.js UI] + end -### 4. AI & NLP Integration -- **LLM Service**: Leverages large language models (e.g., OpenAI, custom models) to generate detailed counterarguments. -- **LangChain & Langgraph**: Frameworks to manage chains of reasoning and workflow orchestration for coherent narrative generation. + subgraph Server Side + style API fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + style Analyzer fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + style CNEngine fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + style Context fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + API[FastAPI Server] + Analyzer[Content Analyzer] + CNEngine[Counter-Narrative Engine] + Context[Context Manager] -### 5. Data Storage -- **VectorDB**: A vector database for storing semantic embeddings to efficiently retrieve and compare content. + end + subgraph AI & NLP Layer + style LLM fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold + style LangChain fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold + style Langgraph fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold + LLM[LLM Service] + LangChain[LangChain] + Langgraph[Langgraph] + end + + subgraph Data Storage + style VectorDB fill:#FFDDEE,stroke:#CC3366,stroke-width:2px,color:#000,font-weight:bold + VectorDB[(Vector Database)] + end + + %% Define Connections with Labels + style Browser fill:#FFFF99,stroke:#FFAA00,stroke-width:2px,color:#000,font-weight:bold + Browser -->|User Interaction| UI + UI -->|Requests| API + API -->|Process| Analyzer + Analyzer -->|Analysis| CNEngine + CNEngine -->|Generates| LLM + LLM -->|Uses| LangChain + LLM -->|Uses| Langgraph + API -->|Manages| Context + CNEngine -->|Stores| VectorDB + API -->|Responses| UI + +``` +### Components + +- **1. Frontend (Next.js)** – User interface for submitting articles and viewing generated perspectives +- **2. FastAPI Backend** – Handles requests, orchestration, and API responses +- **3. Content Analyzer** – Extracts key points and identifies narrative bias +- **4. Counter-Narrative Engine** – Generates alternative viewpoints using AI +- **5. LLM Service (LangChain/LangGraph)** – Runs reasoning workflows and text generation +- **6. Vector Database** – Stores embeddings for semantic retrieval --- ## Technical Stack From de1dbf68cf8daec6c5a692c3a4617c0f230da71b Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 22:44:34 +0530 Subject: [PATCH 04/20] Update README.md --- README.md | 264 ++++++++++++++++++++++++------------------------------ 1 file changed, 115 insertions(+), 149 deletions(-) diff --git a/README.md b/README.md index 2337be70..6d8e5bae 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,24 @@ -# Perspective-AI +
+ +# Perspective +Fact-checked counter-perspectives powered by LLMs + +
+ ![Perspective banner](frontend/public/perspective_banner.jpg) +--- + ## System Overview -Perspective-AI is an AI-powered web app that analyzes online articles and generates fact-based counter-perspectives to reduce bias and echo chambers. Using NLP, RAG, and LLMs, it extracts key points, verifies information, and presents balanced alternative viewpoints in real time. +Perspective-AI is designed to combat the echo chambers created by personalized content algorithms. It actively curates counterarguments and alternative narratives from credible sources alongside the content you usually see. Whether it’s a news article, blog post, or social media update, Perspective-AI analyzes the existing narrative and presents a balanced, in-depth counter-perspective. This approach not only challenges your current viewpoints but also helps broaden your understanding of complex issues—all in real time. +## High-Level Concept Imagine having a smart, opinionated friend who isn’t afraid to challenge your beliefs with well-articulated counterpoints—that’s Perspective-AI in a nutshell! --- -## Setup & Deployment +## Quick Setup ### Prerequisites @@ -40,6 +49,109 @@ uv run main.py ``` --- +## Tech Stack + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FrontendBackendAI & NLPDatabase
+
+ Next.js +		 +
+ FastAPI +		 +
+ OpenAI / LLM APIs +		 +
+ Vector DB +
+
+ TailwindCSS +		 +
+ Python +		 +
+ LangChain / LangGraph +		 + Embeddings Storage +
+ Responsive UI + + REST APIs + + Prompt Engineering + + Semantic Search +
+ +--- + +## Core Features + +### 1. Counter-Perspective Generation +- **What It Does**: Instantly displays counterarguments to the main narrative. +- **How It Works**: Analyzes content to identify biases and generates alternative viewpoints. + + +### 2. Reasoned Thinking +- **What It Does**: Breaks down narratives into logical, connected arguments. +- **How It Works**: Uses chain-of-thought prompting and connected fact analysis. + +### 3. Updated Facts +- **What It Does**: Provides real-time updates and the latest facts along with counter-narratives. +- **How It Works**: Continuously pulls data from trusted sources and updates the insights. + +### 4. Seamless Integration +- **What It Does**: Integrates effortlessly with existing news, blogs, and social media platforms. +- **How It Works**: Uses custom integration modules and API endpoints. + +### 5. Real-Time Analysis +- **What It Does**: Generates insights instantly as you browse. +- **How It Works**: Employs real-time processing powered by advanced AI. + +--- + + + ## Architecture Diagram @@ -102,52 +214,8 @@ graph TB - **6. Vector Database** – Stores embeddings for semantic retrieval --- -## Technical Stack - -### Frontend Technologies - - **framework**: Next.js -- **styling**: TailwindCSS - -### Backend Technologies - - **framework**: FastAPI - - **language**: Python - - **AI & NLP**: LangChain, Langgraph, Prompt Engineering - - **database**: Any VectorDB - - -### I Integration - - - **LLM**: OpenAI, Other NLP Models - - **processing**:Context-Aware - - ---- - -## Core Features - -### 1. Counter-Perspective Generation -- **What It Does**: Instantly displays counterarguments to the main narrative. -- **How It Works**: Analyzes content to identify biases and generates alternative viewpoints. -### 2. Reasoned Thinking -- **What It Does**: Breaks down narratives into logical, connected arguments. -- **How It Works**: Uses chain-of-thought prompting and connected fact analysis. - -### 3. Updated Facts -- **What It Does**: Provides real-time updates and the latest facts along with counter-narratives. -- **How It Works**: Continuously pulls data from trusted sources and updates the insights. - -### 4. Seamless Integration -- **What It Does**: Integrates effortlessly with existing news, blogs, and social media platforms. -- **How It Works**: Uses custom integration modules and API endpoints. - -### 5. Real-Time Analysis -- **What It Does**: Generates insights instantly as you browse. -- **How It Works**: Employs real-time processing powered by advanced AI. - ---- - ## Data Flow & Security ```mermaid @@ -174,108 +242,6 @@ sequenceDiagram ``` --- -## Setup & Deployment - -### Frontend Setup - -Setup environment variables:* - - add .env file in `/frontend`directory. - - add following environment variable in your .env file. -``` -NEXT_PUBLIC_API_URL = http://localhost:8000 - -``` - -```bash -cd frontend -npm install -npm run dev -``` - -### Backend Setup - -*Get HuggingFace Access Token:* -- Go to HuggingFace website and create new access token. -- copy that token - -*Install uv:* -- install **uv** from [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/) - - -*Setup environment variables:* - - add .env file in `/backend`directory. - - add following environment variable in your .env file. - ``` -GROQ_API_KEY= -PINECONE_API_KEY = -PORT = 8000 -SEARCH_KEY = - ``` - -*Run backend:* -```bash -cd backend -uv sync # Creating virtual environment at: .venv -uv run main.py #Runs the backend server -``` - ---- - - -## Architecture Diagram - - -```mermaid -graph TB - %% Define Subgraphs with Colors and Text Styles - subgraph Client Side - style UI fill:#FFDDC1,stroke:#FF6600,stroke-width:2px,color:#000,font-weight:bold - UI[Next.js UI] - end - - subgraph Server Side - style API fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - style Analyzer fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - style CNEngine fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - style Context fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - API[FastAPI Server] - Analyzer[Content Analyzer] - CNEngine[Counter-Narrative Engine] - Context[Context Manager] - - end - - subgraph AI & NLP Layer - style LLM fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold - style LangChain fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold - style Langgraph fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold - LLM[LLM Service] - LangChain[LangChain] - Langgraph[Langgraph] - end - - subgraph Data Storage - style VectorDB fill:#FFDDEE,stroke:#CC3366,stroke-width:2px,color:#000,font-weight:bold - VectorDB[(Vector Database)] - end - - %% Define Connections with Labels - style Browser fill:#FFFF99,stroke:#FFAA00,stroke-width:2px,color:#000,font-weight:bold - Browser -->|User Interaction| UI - UI -->|Requests| API - API -->|Process| Analyzer - Analyzer -->|Analysis| CNEngine - CNEngine -->|Generates| LLM - LLM -->|Uses| LangChain - LLM -->|Uses| Langgraph - API -->|Manages| Context - CNEngine -->|Stores| VectorDB - API -->|Responses| UI - -``` - ---- - ## Expected Outcomes - **Less Bias in Narratives**: Break out of echo chambers and question prevailing narratives. From 90a462c247e3435f817cbe4c71b955453333c6a2 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:10:13 +0530 Subject: [PATCH 05/20] Update README.md --- README.md | 300 +++++++++++++++--------------------------------------- 1 file changed, 80 insertions(+), 220 deletions(-) diff --git a/README.md b/README.md index 6d8e5bae..f25858e9 100644 --- a/README.md +++ b/README.md @@ -1,261 +1,121 @@ -
- # Perspective -Fact-checked counter-perspectives powered by LLMs - -
-![Perspective banner](frontend/public/perspective_banner.jpg) +Perspective-AI is an AI-powered web platform that analyzes articles and generates fact-checked counter-perspectives using LLMs to reduce bias and promote balanced understanding. ---- +# Want to Contribute? 😄 -## System Overview +    -Perspective-AI is designed to combat the echo chambers created by personalized content algorithms. It actively curates counterarguments and alternative narratives from credible sources alongside the content you usually see. Whether it’s a news article, blog post, or social media update, Perspective-AI analyzes the existing narrative and presents a balanced, in-depth counter-perspective. This approach not only challenges your current viewpoints but also helps broaden your understanding of complex issues—all in real time. +1. First, join the **[Discord Server](https://discord.gg/hjUhu33uAn) (Go to Projects->Perspective)** to chat with everyone. +2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [CONTRIBUTING.md](./CONTRIBUTING.md) file. -## High-Level Concept -Imagine having a smart, opinionated friend who isn’t afraid to challenge your beliefs with well-articulated counterpoints—that’s Perspective-AI in a nutshell! +## Architecture ---- +### Frontend +- Next.js: Web UI framework for building the responsive client interface +- TailwindCSS: Styling and layout system -## Quick Setup +### Backend (Python) +- FastAPI: API server handling requests and routing +- Content Analyzer: Extracts and processes article text +- Counter-Narrative Engine: Generates alternative perspectives using AI +- Context Manager: Manages request flow and reasoning state -### Prerequisites +### AI & NLP +- LLMs (OpenAI/Groq/others): Generate counterarguments and summaries +- LangChain: Prompt chaining and reasoning workflows +- LangGraph: Graph-based orchestration of AI pipelines +- Fact Checking: Web search + source verification -- Node.js 18+ -- Python 3.10+ -- uv package manager → https://docs.astral.sh/uv/ -- API keys: - - Groq/OpenAI API key - - Pinecone API key - - Google Custom Search API key - - (Optional) HuggingFace access token +### Data & Storage +- Vector Database (Pinecone/others): Stores embeddings for semantic search +- Embeddings: Enables similarity matching and fast retrieval -### Frontend Setup -```bash -cd frontend -cp .env.example .env -npm install -npm run dev -``` -### Backend Setup + +## Features -```bash -cd backend -cp .env.example .env -uv sync -uv run main.py -``` ---- +- AI-generated counter-perspectives for articles and online content +- Bias detection and balanced narrative analysis +- Fact-checking with trusted sources and real-time updates +- Structured reasoning using LLM chains and workflows +- FastAPI + Next.js powered real-time processing +- Vector search for semantic retrieval and exploration +- Clean, responsive web interface for seamless reading -## Tech Stack +## 🧩 Technical Stack - - - - + + - + + + - + + + + - + + + + - + + + + + + + - + + + - + + + + - + + + + - + + + - + + + - + + + + - + + + + - + + +
FrontendBackendAI & NLPDatabaseComponentTechnology
-
- Next.js -		Frontend FrameworkNext.js
-
- FastAPI -
StylingTailwindCSS
-
- OpenAI / LLM APIs -
Backend APIFastAPI
-
- Vector DB -
Programming LanguagePython
LLM ProviderOpenAI / Groq
-
- TailwindCSS -		AI OrchestrationLangChain
-
- Python -
Workflow EngineLangGraph
-
- LangChain / LangGraph -
Vector DatabasePinecone (or any VectorDB)
- Embeddings Storage -
Fact CheckingGoogle Custom Search API
- Responsive UI -Package Manager (Frontend)npm
- REST APIs -
Package Manager (Backend)uv
- Prompt Engineering -
DeploymentVercel
- Semantic Search -
ContainerizationDocker (optional)
---- - -## Core Features - -### 1. Counter-Perspective Generation -- **What It Does**: Instantly displays counterarguments to the main narrative. -- **How It Works**: Analyzes content to identify biases and generates alternative viewpoints. - - -### 2. Reasoned Thinking -- **What It Does**: Breaks down narratives into logical, connected arguments. -- **How It Works**: Uses chain-of-thought prompting and connected fact analysis. - -### 3. Updated Facts -- **What It Does**: Provides real-time updates and the latest facts along with counter-narratives. -- **How It Works**: Continuously pulls data from trusted sources and updates the insights. - -### 4. Seamless Integration -- **What It Does**: Integrates effortlessly with existing news, blogs, and social media platforms. -- **How It Works**: Uses custom integration modules and API endpoints. - -### 5. Real-Time Analysis -- **What It Does**: Generates insights instantly as you browse. -- **How It Works**: Employs real-time processing powered by advanced AI. - ---- - - - - -## Architecture Diagram - - -```mermaid -graph TB - %% Define Subgraphs with Colors and Text Styles - subgraph Client Side - style UI fill:#FFDDC1,stroke:#FF6600,stroke-width:2px,color:#000,font-weight:bold - UI[Next.js UI] - end - - subgraph Server Side - style API fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - style Analyzer fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - style CNEngine fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - style Context fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold - API[FastAPI Server] - Analyzer[Content Analyzer] - CNEngine[Counter-Narrative Engine] - Context[Context Manager] - - end - - subgraph AI & NLP Layer - style LLM fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold - style LangChain fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold - style Langgraph fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold - LLM[LLM Service] - LangChain[LangChain] - Langgraph[Langgraph] - end - - subgraph Data Storage - style VectorDB fill:#FFDDEE,stroke:#CC3366,stroke-width:2px,color:#000,font-weight:bold - VectorDB[(Vector Database)] - end - - %% Define Connections with Labels - style Browser fill:#FFFF99,stroke:#FFAA00,stroke-width:2px,color:#000,font-weight:bold - Browser -->|User Interaction| UI - UI -->|Requests| API - API -->|Process| Analyzer - Analyzer -->|Analysis| CNEngine - CNEngine -->|Generates| LLM - LLM -->|Uses| LangChain - LLM -->|Uses| Langgraph - API -->|Manages| Context - CNEngine -->|Stores| VectorDB - API -->|Responses| UI - -``` -### Components - -- **1. Frontend (Next.js)** – User interface for submitting articles and viewing generated perspectives -- **2. FastAPI Backend** – Handles requests, orchestration, and API responses -- **3. Content Analyzer** – Extracts key points and identifies narrative bias -- **4. Counter-Narrative Engine** – Generates alternative viewpoints using AI -- **5. LLM Service (LangChain/LangGraph)** – Runs reasoning workflows and text generation -- **6. Vector Database** – Stores embeddings for semantic retrieval ---- - - - -## Data Flow & Security - -```mermaid -sequenceDiagram - %% Define Participants - participant U as User - participant F as Frontend - participant B as Backend - participant AI as AI Service - participant D as Data Storage - - %% Interaction Flow - U->>F: Request/View Content - F->>B: Forward Request - B->>AI: Analyze Content & Generate Counter Perspective - AI->>B: Return Counter Analysis - B->>F: Deliver Results - F->>U: Display Balanced Insights - - %% Notes for Clarity - Note over AI: AI generates counter analysis - Note over B: Backend processes logic - Note over F: Frontend updates UI -``` ---- - -## Expected Outcomes - -- **Less Bias in Narratives**: Break out of echo chambers and question prevailing narratives. -- **Wider Perspectives**: Broaden your understanding of complex issues. -- **Better Discourse**: Enable balanced, informed discussions. -- **Sharper Analysis**: Improve critical thinking by comparing connected facts and counter-facts. - ---- - -## Required Skills - -- **Frontend Development**: Experience with Next.js and modern UI frameworks. -- **Backend Development**: Proficiency in Python and FastAPI. -- **AI & NLP**: Familiarity with LangChain, Langgraph, and prompt engineering techniques. -- **Database Management**: Knowledge of vector databases system. ---- From 59783b987cb5273c172c2a10954455dd628a2328 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:14:16 +0530 Subject: [PATCH 06/20] Update README.md --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f25858e9..7c521246 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Perspective-AI is an AI-powered web platform that analyzes articles and generate     1. First, join the **[Discord Server](https://discord.gg/hjUhu33uAn) (Go to Projects->Perspective)** to chat with everyone. -2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [CONTRIBUTING.md](./CONTRIBUTING.md) file. +2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [ARCHITECTURE.md](./CONTRIBUTING.md) file. ## Architecture @@ -43,7 +43,7 @@ Perspective-AI is an AI-powered web platform that analyzes articles and generate - Vector search for semantic retrieval and exploration - Clean, responsive web interface for seamless reading -## 🧩 Technical Stack +## Technical Stack @@ -118,4 +118,8 @@ Perspective-AI is an AI-powered web platform that analyzes articles and generate
+--- + +Our Code of Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) + From 619496fdc1f1dbc73f7c6696a393da62fb963425 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:20:58 +0530 Subject: [PATCH 07/20] Create CONTRIBUTING.md --- CONTRIBUTING.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..227c357c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# 🌟 Contributing to Perspective + +Hi there! 👋 +Thank you for considering contributing to **Perspective** — we’re excited to collaborate with you. + +Whether you're: +- fixing bugs +- improving documentation +- adding features +- or suggesting ideas + +You're welcome here! + +--- + +## ⚠️ Before You Start + +- Please check existing issues first +- Comment on the issue before working on it +- Wait for maintainer approval/assignment +- Avoid duplicate PRs + +--- + +# 🛠 Setting Up the Project + +Follow these steps to run Perspective locally. + +--- + +## Prerequisites + +Install: + +- Node.js 18+ +- Python 3.10+ +- uv package manager → https://docs.astral.sh/uv/ +- API keys: + - OpenAI/Groq + - Pinecone (or other Vector DB) + - Google Custom Search + +--- + +## Frontend Setup + +```bash +cd frontend +cp .env.example .env +npm install +npm run dev +``` +Frontend runs at: +http://localhost:3000 + +Backend Setup +```bash +cd backend +uv sync +cp .env.example .env +uv run main.py +``` +Backend runs at: +http://localhost:8000 + +🧪 Testing +Frontend +cd frontend +npm test +Backend +cd backend +pytest +Make sure all tests pass before submitting a PR. + +📂 Project Structure +frontend/ → Next.js UI +backend/ → FastAPI + AI logic +docs/ → architecture & documentation +🚀 Contribution Workflow +1. Fork the repo +Click Fork on GitHub + +2. Clone +git clone https://github.com//Perspective.git +3. Create a branch +git checkout -b feat/your-feature-name +4. Make changes +Follow existing code style and structure. + +5. Commit clearly +Use prefixes: + +feat: + +fix: + +docs: + +refactor: + +test: + +Example: + +feat: add caching for article analysis +6. Push & open PR +git push origin feat/your-feature-name +Open a Pull Request on GitHub. + From f55ab6e43a7b2b504b88e693824fecfbebcd86e1 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:34:13 +0530 Subject: [PATCH 08/20] Update CONTRIBUTING.md --- CONTRIBUTING.md | 97 ++++++++++--------------------------------------- 1 file changed, 19 insertions(+), 78 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 227c357c..ae511f53 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,35 +1,14 @@ # 🌟 Contributing to Perspective -Hi there! 👋 -Thank you for considering contributing to **Perspective** — we’re excited to collaborate with you. +Hi there! Thank you for considering contributing to PictoPy – we’re excited to collaborate with you. Whether you're fixing a bug, improving documentation, or suggesting a new feature — you're welcome here! -Whether you're: -- fixing bugs -- improving documentation -- adding features -- or suggesting ideas +NOTE: Please do not open a PR for the issue which is not yet reviewed and labelled by the maintainer. Wait for the maintainer to give a green light. -You're welcome here! - ---- - -## ⚠️ Before You Start - -- Please check existing issues first -- Comment on the issue before working on it -- Wait for maintainer approval/assignment -- Avoid duplicate PRs - ---- # 🛠 Setting Up the Project Follow these steps to run Perspective locally. ---- - -## Prerequisites - Install: - Node.js 18+ @@ -40,70 +19,32 @@ Install: - Pinecone (or other Vector DB) - Google Custom Search ---- - -## Frontend Setup +## Clone Repository ```bash +git clone https://github.com/AOSSIE-Org/Perspective.git +cd Perspective +``` + +## Frontend (Next.js) + +1. Install dependencies +```bash cd frontend -cp .env.example .env npm install -npm run dev ``` -Frontend runs at: -http://localhost:3000 -Backend Setup +2. Configure environment ```bash -cd backend -uv sync cp .env.example .env -uv run main.py ``` -Backend runs at: -http://localhost:8000 +Edit the .env file -🧪 Testing -Frontend -cd frontend -npm test -Backend -cd backend -pytest -Make sure all tests pass before submitting a PR. - -📂 Project Structure -frontend/ → Next.js UI -backend/ → FastAPI + AI logic -docs/ → architecture & documentation -🚀 Contribution Workflow -1. Fork the repo -Click Fork on GitHub - -2. Clone -git clone https://github.com//Perspective.git -3. Create a branch -git checkout -b feat/your-feature-name -4. Make changes -Follow existing code style and structure. - -5. Commit clearly -Use prefixes: - -feat: - -fix: - -docs: - -refactor: - -test: - -Example: +3. Start development server +```bash +npm run dev +``` -feat: add caching for article analysis -6. Push & open PR -git push origin feat/your-feature-name -Open a Pull Request on GitHub. +Frontend runs at: +http://localhost:3000 From 9f6f6189231ed83dda876a304cfd42db775a71a4 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:46:41 +0530 Subject: [PATCH 09/20] Update CONTRIBUTING.md --- CONTRIBUTING.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae511f53..0c1a4e3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,6 @@ npm install ```bash cp .env.example .env ``` -Edit the .env file 3. Start development server ```bash @@ -48,3 +47,51 @@ npm run dev Frontend runs at: http://localhost:3000 + +## Backend (FastAPI + uv) + +The backend uses uv for dependency management. + +1. Install uv: https://docs.astral.sh/uv/ + +2. Install dependencies: +```bash +cd backend +uv sync +``` + +3. Configure environment +```bash +cp .env.example .env +``` + +4. Fill required keys: +```bash +OPENAI_API_KEY= +GROQ_API_KEY= +PINECONE_API_KEY= +SEARCH_KEY= +PORT=8000 +``` + +5. Run server +```bash +uv run main.py +``` + +Backend runs at: +http://localhost:8000 + + + +# 🚀 How to Contribute + +1. Pick an issue and get it assigned +2. Fork the repository +3. Create a new branch +4. Make your changes and test locally +5. Push your branch and open a Pull Request + +Please keep PRs small, focused, and follow the existing code style. + + From 90ad41f4384d9ccab4265eb3c3f8d56bd830c580 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:47:32 +0530 Subject: [PATCH 10/20] Add architecture and data flow documentation This document outlines the architecture and data flow of the Perspective application, detailing the client-server model, AI services, and data storage components. --- ARCHITECTURE.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 00000000..402b3e69 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,90 @@ + +## Architecture Diagram + + +This document explains the internal design and workflow of Perspective. + +Perspective follows a simple client–server architecture where: +- The frontend handles user interaction +- The backend processes content +- AI services generate counter-perspectives +- A vector database enables semantic retrieval + +```mermaid +graph TB + %% Define Subgraphs with Colors and Text Styles + subgraph Client Side + style UI fill:#FFDDC1,stroke:#FF6600,stroke-width:2px,color:#000,font-weight:bold + UI[Next.js UI] + end + + subgraph Server Side + style API fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + style Analyzer fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + style CNEngine fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + style Context fill:#D1E8FF,stroke:#005BBB,stroke-width:2px,color:#000,font-weight:bold + API[FastAPI Server] + Analyzer[Content Analyzer] + CNEngine[Counter-Narrative Engine] + Context[Context Manager] + + end + + subgraph AI & NLP Layer + style LLM fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold + style LangChain fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold + style Langgraph fill:#E6FFCC,stroke:#66BB66,stroke-width:2px,color:#000,font-weight:bold + LLM[LLM Service] + LangChain[LangChain] + Langgraph[Langgraph] + end + + subgraph Data Storage + style VectorDB fill:#FFDDEE,stroke:#CC3366,stroke-width:2px,color:#000,font-weight:bold + VectorDB[(Vector Database)] + end + + %% Define Connections with Labels + style Browser fill:#FFFF99,stroke:#FFAA00,stroke-width:2px,color:#000,font-weight:bold + Browser -->|User Interaction| UI + UI -->|Requests| API + API -->|Process| Analyzer + Analyzer -->|Analysis| CNEngine + CNEngine -->|Generates| LLM + LLM -->|Uses| LangChain + LLM -->|Uses| Langgraph + API -->|Manages| Context + CNEngine -->|Stores| VectorDB + API -->|Responses| UI + +``` + +--- + + +## Data Flow & Security + +```mermaid +sequenceDiagram + %% Define Participants + participant U as User + participant F as Frontend + participant B as Backend + participant AI as AI Service + participant D as Data Storage + + %% Interaction Flow + U->>F: Request/View Content + F->>B: Forward Request + B->>AI: Analyze Content & Generate Counter Perspective + AI->>B: Return Counter Analysis + B->>F: Deliver Results + F->>U: Display Balanced Insights + + %% Notes for Clarity + Note over AI: AI generates counter analysis + Note over B: Backend processes logic + Note over F: Frontend updates UI +``` + + From c04a0d2a996e4efb0f0e879a1c70925d3d448c05 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:48:01 +0530 Subject: [PATCH 11/20] Add Contributor Covenant Code of Conduct This document outlines the Contributor Covenant Code of Conduct, detailing the community's pledge, standards, enforcement responsibilities, and consequences for violations. --- CODE_OF_CONDUCT.md | 128 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..ffac1680 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +aossie.oss@gmail.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. From 0e8d04ea043ec29fe38430e9f89a023591237f91 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:51:50 +0530 Subject: [PATCH 12/20] Create .env.example --- frontend/.env.example | 1 + 1 file changed, 1 insertion(+) create mode 100644 frontend/.env.example diff --git a/frontend/.env.example b/frontend/.env.example new file mode 100644 index 00000000..600de8df --- /dev/null +++ b/frontend/.env.example @@ -0,0 +1 @@ +NEXT_PUBLIC_API_URL=http://localhost:8000 From 140f42b4de65b1f68912983b3ac89ff09bd4f8e1 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Mon, 2 Feb 2026 23:57:03 +0530 Subject: [PATCH 13/20] Add example environment configuration file --- backend/.example.env | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 backend/.example.env diff --git a/backend/.example.env b/backend/.example.env new file mode 100644 index 00000000..3f6d739f --- /dev/null +++ b/backend/.example.env @@ -0,0 +1,4 @@ +GROQ_API_KEY= +PINECONE_API_KEY= +PORT=8000 +SEARCH_KEY= From 8f859f922d847896c39fd4d0a4154034ee21705a Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Tue, 3 Feb 2026 08:27:42 +0530 Subject: [PATCH 14/20] Update example environment variables with comments --- backend/.example.env | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/backend/.example.env b/backend/.example.env index 3f6d739f..ccee6b93 100644 --- a/backend/.example.env +++ b/backend/.example.env @@ -1,4 +1,11 @@ -GROQ_API_KEY= -PINECONE_API_KEY= +# Groq API key for LLM inference +GROQ_API_KEY= + +# Pinecone vector database API key +PINECONE_API_KEY= + +# Backend server port PORT=8000 -SEARCH_KEY= + +# Google Custom Search API key for fact-checking +SEARCH_KEY= From 5dfc0d800c5b5aa0e9cc4d1ea674b8d83ff1ae17 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Tue, 3 Feb 2026 08:30:14 +0530 Subject: [PATCH 15/20] Update CONTRIBUTING.md --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c1a4e3a..5e6af0d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ npm install 2. Configure environment ```bash -cp .env.example .env +cp .example.env .env ``` 3. Start development server @@ -62,12 +62,11 @@ uv sync 3. Configure environment ```bash -cp .env.example .env +cp .example.env .env ``` 4. Fill required keys: ```bash -OPENAI_API_KEY= GROQ_API_KEY= PINECONE_API_KEY= SEARCH_KEY= From 1eaf1f71f68f51599c56deaa2c388d2819bb2611 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Tue, 3 Feb 2026 08:30:59 +0530 Subject: [PATCH 16/20] Add comment for NEXT_PUBLIC_API_URL in .env.example --- frontend/.env.example | 1 + 1 file changed, 1 insertion(+) diff --git a/frontend/.env.example b/frontend/.env.example index 600de8df..1c4a042b 100644 --- a/frontend/.env.example +++ b/frontend/.env.example @@ -1 +1,2 @@ +# Backend API base URL NEXT_PUBLIC_API_URL=http://localhost:8000 From 85a9222b326e6ec37988b87b587cb0c6d846b5cd Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Tue, 3 Feb 2026 08:33:43 +0530 Subject: [PATCH 17/20] Fix link to CONTRIBUTING.md and add ARCHITECTURE note Corrected link reference for CONTRIBUTING.md and added note about ARCHITECTURE.md. --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7c521246..08c4ce02 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,12 @@ Perspective-AI is an AI-powered web platform that analyzes articles and generate     1. First, join the **[Discord Server](https://discord.gg/hjUhu33uAn) (Go to Projects->Perspective)** to chat with everyone. -2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [ARCHITECTURE.md](./CONTRIBUTING.md) file. +2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [CONTRIBUTING.md](./CONTRIBUTING.md) file. ## Architecture +For detailed Architecture, please check out our [ARCHITECTURE.md](.ARCHITECTURE/.md) + ### Frontend - Next.js: Web UI framework for building the responsive client interface - TailwindCSS: Styling and layout system From ab5a7ec38772edf1cc9de351f064c8e179f51bc6 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Tue, 3 Feb 2026 08:34:09 +0530 Subject: [PATCH 18/20] Fix link to ARCHITECTURE.md in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 08c4ce02..993dd69a 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Perspective-AI is an AI-powered web platform that analyzes articles and generate ## Architecture -For detailed Architecture, please check out our [ARCHITECTURE.md](.ARCHITECTURE/.md) +For detailed Architecture, please check out our [ARCHITECTURE.md](./ARCHITECTURE.md) ### Frontend - Next.js: Web UI framework for building the responsive client interface From 641e2e88e01b31ff22cb8867ab1b88423bc77c21 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Tue, 3 Feb 2026 08:36:58 +0530 Subject: [PATCH 19/20] Enhance Discord invite link in README Updated Discord server invite link with alt text for accessibility. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 993dd69a..e7c31487 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Perspective-AI is an AI-powered web platform that analyzes articles and generate # Want to Contribute? 😄 -    +   Discord server invite 1. First, join the **[Discord Server](https://discord.gg/hjUhu33uAn) (Go to Projects->Perspective)** to chat with everyone. 2. For detailed setup instructions, coding guidelines, and the contribution process, please check out our [CONTRIBUTING.md](./CONTRIBUTING.md) file. From b13e64ea150210b1b3e4db0ae36ab69daef941a6 Mon Sep 17 00:00:00 2001 From: Sarthak Kad Date: Tue, 3 Feb 2026 09:45:37 +0530 Subject: [PATCH 20/20] Rename .env.example to .example.env --- frontend/{.env.example => .example.env} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename frontend/{.env.example => .example.env} (100%) diff --git a/frontend/.env.example b/frontend/.example.env similarity index 100% rename from frontend/.env.example rename to frontend/.example.env