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 +``` + + 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5e6af0d3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,96 @@ +# 🌟 Contributing to Perspective + +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! + +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. + + +# 🛠 Setting Up the Project + +Follow these steps to run Perspective locally. + +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 + +## Clone Repository + +```bash +git clone https://github.com/AOSSIE-Org/Perspective.git +cd Perspective +``` + +## Frontend (Next.js) + +1. Install dependencies +```bash +cd frontend +npm install +``` + +2. Configure environment +```bash +cp .example.env .env +``` + +3. Start development server +```bash +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 .example.env .env +``` + +4. Fill required keys: +```bash +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. + + diff --git a/README.md b/README.md index 90ac0e13..e7c31487 100644 --- a/README.md +++ b/README.md @@ -1,252 +1,127 @@ -# 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) +# Perspective ---- - -## 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 platform that analyzes articles and generates fact-checked counter-perspectives using LLMs to reduce bias and promote balanced understanding. -### 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! +# Want to Contribute? 😄 ---- +   Discord server invite -## Architecture Components +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. -### 1. Frontend Layer -- **Next.js UI**: A sleek, responsive interface that displays content alongside counter perspectives. +## Architecture -### 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. +For detailed Architecture, please check out our [ARCHITECTURE.md](./ARCHITECTURE.md) -### 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. +### Frontend +- Next.js: Web UI framework for building the responsive client interface +- TailwindCSS: Styling and layout system -### 5. Data Storage -- **VectorDB**: A vector database for storing semantic embeddings to efficiently retrieve and compare content. +### 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 ---- +### 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 -## Technical Stack +### Data & Storage +- Vector Database (Pinecone/others): Stores embeddings for semantic search +- Embeddings: Enables similarity matching and fast retrieval -### Frontend Technologies - - **framework**: Next.js -- **styling**: TailwindCSS -### Backend Technologies - - **framework**: FastAPI - - **language**: Python - - **AI & NLP**: LangChain, Langgraph, Prompt Engineering - - **database**: Any VectorDB + +## Features +- 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 -### 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 -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 -``` ---- - -## 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 +## Technical Stack -- **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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentTechnology
Frontend FrameworkNext.js
StylingTailwindCSS
Backend APIFastAPI
Programming LanguagePython
LLM ProviderOpenAI / Groq
AI OrchestrationLangChain
Workflow EngineLangGraph
Vector DatabasePinecone (or any VectorDB)
Fact CheckingGoogle Custom Search API
Package Manager (Frontend)npm
Package Manager (Backend)uv
DeploymentVercel
ContainerizationDocker (optional)
--- -## Required Skills +Our Code of Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) -- **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. ---- diff --git a/backend/.example.env b/backend/.example.env new file mode 100644 index 00000000..ccee6b93 --- /dev/null +++ b/backend/.example.env @@ -0,0 +1,11 @@ +# Groq API key for LLM inference +GROQ_API_KEY= + +# Pinecone vector database API key +PINECONE_API_KEY= + +# Backend server port +PORT=8000 + +# Google Custom Search API key for fact-checking +SEARCH_KEY= diff --git a/frontend/.example.env b/frontend/.example.env new file mode 100644 index 00000000..1c4a042b --- /dev/null +++ b/frontend/.example.env @@ -0,0 +1,2 @@ +# Backend API base URL +NEXT_PUBLIC_API_URL=http://localhost:8000