misinformation_detection_backend/README.md

# Fake News Detection (GDELT + Gemini)

This app takes a user query, builds robust GDELT queries via Gemini, fetches articles, analyzes outlet bias, ranks articles with local embeddings, and returns a concise, multi‑perspective summary. The UI renders exactly what the backend returns (no extra formatting or hardcoded values).

## Key Features
- Query expansion: 10 GDELT query variations, language-preserving, AND-only operators.
- Sensitive-query guard: pornography/religion and similar sensitive topics short‑circuit with “I cannot respond to this query.”
- GDELT ingestion and normalization.
- Gemini-driven bias analysis with categories; one category is strictly named “unbiased”.
- Per-category ranking using a cached local embedding model (SentenceTransformers), shared across requests.
- Multi‑perspective summarization:
  - Sends top URLs from all categories (including unbiased) to Gemini.
  - Summary lists sources grouped by category with up to 5 URLs per category.
  - Appends the “reasoning” string (from bias analysis) after the sources.
- Optional domain whitelisting (toggle in .env).
- Terminal and UI show the exact same summary string.

## Requirements
- Python 3.11+
- Conda/venv recommended
- Packages: flask, flask-cors, python-dotenv, requests, sentence-transformers, torch, google-generativeai

## Setup
1. Create and activate environment (example with conda):
   - conda create -n fake_news_detection python=3.11 -y
   - conda activate fake_news_detection
2. Install deps:
   - pip install -r requirements.txt  (if present) or install the packages listed above.
3. Copy .env.example to .env and set values:
   - GEMINI_API_KEY, GEMINI_MODEL (e.g., gemini-1.5-pro or gemini-2.5-pro)
   - MAX_ARTICLES_PER_QUERY, TOP_N_PER_CATEGORY, MIN_SIMILARITY_THRESHOLD
   - SIMILARITY_MODEL (e.g., intfloat/multilingual-e5-base)
   - SHOW_SIMILARITY_SCORES, SHOW_PUBLISH_DATE, SHOW_URL
   - USE_WHITELIST_ONLY (true/false)
   - PORT, DEBUG

## Run
- Linux:
  - chmod +x ./main.py
  - ./main.py
- Visit http://127.0.0.1:5000

## API
POST /api/detect
- Body: {"query": "your question"}
- Returns (simplified):
```
{
  "query": "...",
  "summary": "MULTI-PERSPECTIVE FACTUAL SUMMARY...\n\n...SOURCES BY CATEGORY...\n\n...REASONING: ...",
  "status": "ok" | "no_results" | "blocked"
}
```
Notes:
- If the query is sensitive, status=blocked and summary contains: “I cannot respond to this query.”
- Only the summary string is printed to terminal and sent to UI, and the UI renders it verbatim.

## Behavior Details
- Local embedding model is loaded once and cached for reuse across requests.
- Gemini runs in the cloud (no caching).
- Bias categories come from Gemini; one is enforced/normalized to exactly “unbiased”.
- Summarization uses top URLs from all categories and instructs Gemini to:
  - Group sources by category,
  - List up to 5 URLs per category (numbering restarts at 1 inside each category),
  - Then append the bias-analysis “reasoning” section.

## Whitelist Filtering
- USE_WHITELIST_ONLY=true limits articles to whitelisted domains.
- When false, all domains are considered.

## Frontend
- Primary UI: Flutter app in `misinformationui/`.
- Optional debug client: `static/` minimal JS page (useful for quick backend checks only).

### Run the Flutter UI
1) Start the backend (see Run section below) so it listens on http://localhost:5000

2) In a separate terminal, run the Flutter app:
   - cd misinformationui
   - flutter pub get
   - Choose a target:
     - Web (Chrome): flutter run -d chrome
     - Linux desktop: flutter run -d linux (ensure Linux desktop is enabled in Flutter)
     - Android emulator: flutter run -d emulator
       - Update the API URL in `misinformationui/lib/chat_screen.dart` from `http://localhost:5000` to `http://10.0.2.2:5000` for Android emulators, or use your machine's LAN IP for real devices.
     - iOS simulator: `http://localhost:5000` should work; real devices need your machine's LAN IP.

Note: The legacy `static/` page is kept for quick smoke tests; the production UX is the Flutter app.