🥑 Avocado - TikTok Fact Checker

Fight misinformation on TikTok with AI-powered analysis.

Avocado is an open-source tool that helps users verify the credibility of TikTok videos in real-time. It combines a Chrome Extension for seamless UI integration with a robust FastAPI backend that leverages Google Gemini for content analysis.

✨ Features

• Real-time Analysis: Instantly analyzes video transcripts and metadata.
• AI-Powered Fact Checking: Uses Google Gemini (via OpenRouter) to cross-reference claims with trusted sources.
• Seamless Integration: Injects a non-intrusive "Fact Check" button directly into the TikTok interface.
• Detailed Reports: Provides a credibility score, summary of claims, and specific concerns (e.g., lack of sources, sensationalism).
• Robust Backend: Built with FastAPI, featuring caching, rate limiting, and parallel data fetching.

🏗️ Architecture

The project consists of two main components:

1. Backend (/backend)

A Python FastAPI service that acts as the brain of the operation.

• Scraper: Fetches video metadata and transcripts using the Supadata API.
• Analyzer: Processes content using LLMs (default: Gemini Flash 1.5) via OpenRouter.
• API: Exposes REST endpoints (/api/v1/check) for the extension to consume.

2. Extension (/extension)

A Manifest V3 Chrome extension that provides the user interface.

• Content Script: Detects TikTok videos and injects the "Avocado" button.
• Side Panel: Displays the analysis results in a slide-out drawer.
• Note: The extension is currently configured to use mock data for demonstration purposes.

🚀 Getting Started

Prerequisites

• Python 3.10 or higher
• Google Chrome (or Chromium-based browser)
• API Keys (see instructions below):
  • Supadata — for TikTok video scraping
  • Google AI Studio — for Gemini AI analysis

---

🔑 Getting Your API Keys

1. Supadata API Key (TikTok scraping)

1. Go to supadata.ai and sign up for a free account.
2. After logging in, navigate to the Dashboard → API Keys.
3. Click Create New Key and copy your API key.
4. The free tier includes 500 requests/month, which is enough for testing.

2. Google Gemini API Key (AI analysis)

1. Go to Google AI Studio.
2. Sign in with your Google account.
3. Click Create API key and select a project (or create a new one).
4. Copy your API key.
5. The free tier includes 15 requests/minute and 1,500 requests/day — plenty for personal use!

Note: Gemini API is free with generous rate limits. No credit card required!

Where to put your keys? Create a file called .env in the backend/ folder and add your keys there. See step 4 below for the exact format.

---

1️⃣ Backend Setup

1. Navigate to the backend directory:

   cd backend

2. Set up a virtual environment:

   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # macOS/Linux
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure Environment Variables: Create a .env file in the backend directory:

   # backend/.env
   SUPADATA_API_KEY=your_supadata_api_key_here
   GEMINI_API_KEY=your_gemini_api_key_here
   
   # Optional settings
   DEBUG=True

5. Run the Server:

   uvicorn app.main:app --reload

   The API will be live at http://localhost:8000. You can view the docs at http://localhost:8000/docs.

2️⃣ Extension Setup

1. Open Chrome and navigate to chrome://extensions/.
2. Enable Developer mode in the top-right corner.
3. Click Load unpacked.
4. Select the extension folder from this repository.
5. Go to TikTok.com, and you should see the Avocado button on video pages!

🔌 API Endpoints

Method	Endpoint	Description
POST	/api/v1/check	Full analysis: scrapes data and performs fact-check.
POST	/api/v1/fact-check	Performs fact-check on already scraped data.
POST	/api/v1/scrape-metadata	Scrapes metadata/transcript only.
GET	/health	Service health check.

🛠️ Development

• Testing: Run the test suite with pytest.

  cd backend
  pytest tests/

• Linting: use black and flake8 to maintain code quality.