Spaces:
Sleeping
Sleeping
| title: Proofly API | |
| emoji: 🛡️ | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: docker | |
| pinned: false | |
| app_port: 7860 | |
| # Proofly | |
| An AI-powered claim verification system that gathers evidence from 7 live sources, builds a semantic vector index, and uses Natural Language Inference (NLI) to produce a **True / False / Mixture/Uncertain** verdict — with full user authentication, history tracking, and a premium responsive UI. | |
| --- | |
| ## Features | |
| - **JWT Authentication** — Register, login, logout with bcrypt-peppered passwords and HttpOnly cookie tokens | |
| - **Per-User History** — Every fact-check is saved to MongoDB Atlas; view, delete, or clear your history | |
| - **7 Evidence Sources** | |
| - Static Knowledge Base (local, instant — no network needed) | |
| - Wikidata (free entity facts, no API key) | |
| - 12 RSS Feeds (BBC, CNN, Al Jazeera, NYT, The Hindu, NDTV, …) | |
| - GDELT Project (global news events, no API key) | |
| - NewsAPI (quality English headlines, requires free API key) | |
| - Wikipedia REST API (encyclopedic summaries) | |
| - DuckDuckGo HTML scrape (automatic fallback) | |
| - **AI Pipeline** — `all-MiniLM-L6-v2` for semantic embeddings + FAISS vector search + `facebook/bart-large-mnli` for NLI | |
| - **KB Short-Circuit** — Skips slow live fetches when the knowledge base already has a strong match (≥ 0.65 similarity) | |
| - **Image OCR** — Upload an image → EasyOCR extracts text → auto-fills the claim field | |
| - **Security** — Flask-Talisman security headers, Flask-Limiter rate limiting, JWT blocklist on logout | |
| - **Responsive UI** — Premium dark/light theme, permanent sidebar on all screen sizes | |
| --- | |
| ## Setup | |
| ### Prerequisites | |
| - Python 3.8+ | |
| - MongoDB Atlas account (free tier works) | |
| - (Optional) NewsAPI key — https://newsapi.org | |
| ### 1. Clone | |
| ```bash | |
| git clone https://github.com/yourusername/proofly.git | |
| cd proofly | |
| ``` | |
| ### 2. Install dependencies | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| > PyTorch + Transformers models (~1–2 GB) download automatically on first run. | |
| ### 3. Configure `.env` | |
| Copy `.env.example` to `.env` and fill in: | |
| ```env | |
| # MongoDB Atlas | |
| MONGO_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/?appName=<app> | |
| MONGO_DB_NAME=factcheck | |
| # FAISS index file path | |
| FAISS_FILE=faiss.index | |
| # NewsAPI (free key at newsapi.org) | |
| NEWS_API_KEY=your_key_here | |
| # Flask | |
| FLASK_SECRET_KEY=your_long_random_secret_key | |
| # JWT | |
| JWT_SECRET_KEY=your_jwt_secret | |
| JWT_ACCESS_TOKEN_MINS=15 | |
| JWT_REFRESH_TOKEN_DAYS=7 | |
| # Password pepper — keep secret, never commit | |
| BCRYPT_PEPPER=your_pepper_string | |
| # Bot identity header | |
| USER_AGENT=ProoflyBot/1.0 | |
| ``` | |
| ### 4. Initialise MongoDB collections & indexes | |
| ```bash | |
| python setup_db.py | |
| ``` | |
| Creates all 4 collections (`users`, `history`, `evidence`, `revoked_tokens`) with validators and indexes on Atlas. | |
| ### 5. Pre-populate evidence index *(recommended before first use)* | |
| ```bash | |
| python update_data.py | |
| ``` | |
| Fetches from all sources across 24 broad topics and builds the FAISS index. Re-run weekly to keep evidence fresh. | |
| ### 6. Run | |
| ```bash | |
| python app.py | |
| ``` | |
| Open `http://localhost:5000` — register an account and start fact-checking. | |
| --- | |
| ## Project Structure | |
| ``` | |
| newsXX/ | |
| ├── app.py # Flask app — routes, JWT config, security middleware | |
| ├── auth.py # Auth Blueprint — register / login / logout / refresh | |
| ├── api_wrapper.py # Per-request pipeline: evidence → FAISS → NLI → verdict | |
| ├── model.py # AI models + 7 evidence fetchers | |
| ├── update_data.py # Offline bulk evidence updater + FAISS index builder | |
| ├── knowledge_base.py # ~80 curated static facts (no network required) | |
| ├── setup_db.py # One-time MongoDB Atlas collection + index setup | |
| ├── project/ | |
| │ ├── config.py # All settings from .env (single source of truth) | |
| │ └── database.py # MongoDB helpers (Borg singleton, CRUD, TTL) | |
| ├── templates/ | |
| │ ├── index.html # Dashboard / claim submission | |
| │ ├── results.html # Verdict + evidence + NLI breakdown | |
| │ ├── history.html # User claim history | |
| │ ├── login.html # Login page | |
| │ └── register.html # Register page | |
| ├── static/ | |
| │ └── style.css # Full design system (dark/light theme, responsive) | |
| ├── .env # Local secrets (never commit) | |
| ├── .env.example # Template | |
| ├── requirements.txt # Python dependencies | |
| └── faiss.index # Vector index (built by update_data.py) | |
| ``` | |
| --- | |
| ## How the Verdict Works | |
| ``` | |
| Claim → Embed (MiniLM) → Knowledge Base check | |
| ↓ if score ≥ 0.65 → skip live fetches | |
| Wikidata + RSS + GDELT + NewsAPI + Wikipedia | |
| ↓ if < 3 items → DuckDuckGo fallback | |
| Build FAISS index | |
| ↓ | |
| Top-5 most similar evidence items | |
| ↓ | |
| NLI (BART-MNLI) on each piece | |
| ↓ | |
| Majority vote → True / False / Mixture/Uncertain | |
| ``` | |
| | Condition | Verdict | | |
| |---|---| | |
| | More entailment results than contradiction | ✅ **True** | | |
| | More contradiction results than entailment | ❌ **False** | | |
| | Tied or average scores below 0.4 | ⚠️ **Mixture/Uncertain** | | |
| --- | |
| ## MongoDB Collections | |
| | Collection | Purpose | Auto-cleanup | | |
| |---|---|---| | |
| | `users` | Accounts with hashed passwords | — | | |
| | `history` | Per-user fact-check records | — | | |
| | `evidence` | Scraped text for FAISS | TTL 30 days | | |
| | `revoked_tokens` | JWT logout blocklist | TTL at token expiry | | |
| --- | |
| ## Dependencies | |
| | Package | Purpose | | |
| |---|---| | |
| | `flask` | Web framework | | |
| | `flask-jwt-extended` | JWT access + refresh tokens via cookies | | |
| | `flask-bcrypt` | Password hashing | | |
| | `flask-limiter` | Rate limiting on auth endpoints | | |
| | `flask-talisman` | HTTP security headers | | |
| | `pymongo` | MongoDB Atlas driver | | |
| | `python-dotenv` | `.env` loading | | |
| | `sentence-transformers` | MiniLM-L6 embeddings | | |
| | `transformers` | BART-MNLI NLI pipeline | | |
| | `faiss-cpu` | Vector similarity search | | |
| | `requests` | HTTP calls to APIs | | |
| | `beautifulsoup4` | DuckDuckGo HTML scraping | | |
| | `feedparser` | RSS feed parsing | | |
| | `numpy` | Numerical operations | | |
| | `torch` | Deep learning backend | | |
| | `easyocr` | Image OCR | | |
| | `Pillow` | Image processing | | |
| --- | |
| ## Security Notes | |
| - Passwords are hashed with **bcrypt** + a server-side **pepper** — a leaked database alone cannot crack them | |
| - JWT tokens stored in **HttpOnly** cookies — inaccessible to JavaScript (XSS-safe) | |
| - `SameSite=Strict` cookie policy prevents CSRF | |
| - Rate limiting: 5 login attempts / minute, 3 register attempts / minute per IP | |
| - All security headers enforced by Flask-Talisman | |
| --- | |
| ## Contributing | |
| Pull requests welcome. Please open an issue first for major changes. | |
| --- | |
| ## License | |
| Open-source. See repository for license details. | |