Installation Guide - CheckThat AI

Overview

This guide provides comprehensive installation instructions for CheckThat AI. You can choose between automated setup using scripts or manual installation for more control.

For a faster setup, see the Quickstart Guide which uses automated scripts.

Prerequisites

Before installing CheckThat AI, ensure your system meets these requirements:

System requirements

Operating System: Linux, macOS, or Windows (with WSL recommended)
Node.js: Version 18 or higher
Python: Version 3.8 or higher
Git: For cloning the repository
npm: Comes with Node.js
pip: Python package installer (comes with Python)

Verify installations

Check that you have the required tools installed:

# Check Node.js version
node --version  # Should be v18 or higher

# Check npm version
npm --version

# Check Python version
python --version  # Should be 3.8 or higher
# On some systems, use python3
python3 --version

# Check pip version
pip --version
# On some systems, use pip3
pip3 --version

# Check git
git --version

API keys

Obtain API keys for the AI providers you plan to use:

OpenAI API Key

Visit OpenAI Platform
Sign up or log in to your account
Navigate to API Keys
Click “Create new secret key”
Copy and save your key securely

Supported models: GPT-5, GPT-5 nano, o3, o4-mini

Anthropic API Key

Visit Anthropic Console
Sign up or log in
Navigate to API Keys section
Generate a new API key
Save your key securely

Supported models: Claude Sonnet 4, Claude Opus 4.1

Google AI API Key

Visit Google AI Studio
Sign in with your Google account
Click “Get API Key”
Create a new API key or use an existing one
Save your key securely

Supported models: Gemini 2.5 Pro, Gemini 2.5 Flash

xAI API Key

Visit xAI Console
Sign up or log in
Navigate to API section
Generate your API key
Save your key securely

Supported models: Grok 3, Grok 4, Grok 3 Mini

Together AI (Free Models)

Together AI offers free models that don’t require an API key for local development:

Llama 3.3 70B (free, no key required)
DeepSeek R1 Distill Llama 70B (free, no key required)

These are great options for testing and development without API costs.

Never commit API keys to version control. Always use environment variables or secure configuration files.

Installation methods

Option 1: Automated setup (recommended)

The automated setup is the fastest way to get started:

Clone repository

git clone https://github.com/nikhil-kadapala/clef2025-checkthat-lab-task2.git
cd clef2025-checkthat-lab-task2

Make scripts executable

Linux/macOS:

chmod +x setup-project.sh run-project.sh

Windows: Use Git Bash or WSL to run the scripts:

bash setup-project.sh
bash run-project.sh

Set environment variables

Linux/macOS:

export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GEMINI_API_KEY="your-gemini-key"
export GROK_API_KEY="your-grok-key"

Windows (PowerShell):

$env:OPENAI_API_KEY="your-openai-key"
$env:ANTHROPIC_API_KEY="your-anthropic-key"
$env:GEMINI_API_KEY="your-gemini-key"
$env:GROK_API_KEY="your-grok-key"

Run setup script

./setup-project.sh

The script automatically:

Detects your OS (Linux/macOS/Windows)
Terminates conflicting processes on port 5173
Installs frontend dependencies (Node.js packages)
Fixes npm vulnerabilities
Creates Python virtual environment
Installs backend dependencies with uv (falls back to pip)
Handles cross-platform compatibility

Start the application

./run-project.sh

This starts:

Frontend on http://localhost:5173
Backend on http://localhost:8000

Option 2: Manual setup

For more control over the installation process:

Backend installation

Clone repository

git clone https://github.com/nikhil-kadapala/clef2025-checkthat-lab-task2.git
cd clef2025-checkthat-lab-task2

Create virtual environment

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Linux/macOS:
source .venv/bin/activate

# Windows:
.venv\Scripts\activate

You should see (.venv) in your terminal prompt indicating the virtual environment is active.

Install Python dependencies

pip install -r requirements.txt

This installs:

fastapi[standard] - Web framework
uvicorn[standard] - ASGI server
AI provider SDKs: openai, anthropic, together, google-genai, xai-sdk
Data processing: pandas, numpy, nltk, scipy, scikit-learn
Evaluation: deepeval for G-Eval metrics
Utilities: pydantic, pydantic-settings, httpx, requests

Download NLTK data (for METEOR scoring)

python -c "import nltk; nltk.download('punkt'); nltk.download('wordnet')"

Set environment variables

Create a .env file in the project root:

# .env
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GEMINI_API_KEY=your-gemini-key
GROK_API_KEY=your-grok-key

# Optional configuration
ENV_TYPE=dev
LOG_LEVEL=INFO
CORS_ORIGINS=*

Start backend server

cd src/api
python main.py

Or use FastAPI’s development server:

cd src/api
fastapi dev main.py --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000.

Frontend installation

Navigate to app directory

Open a new terminal window and navigate to the frontend directory:

cd src/app

Install Node.js dependencies

npm install

This installs:

Framework: React 19, React Router v7
Build tool: Vite 7
Styling: Tailwind CSS 4
UI components: Radix UI primitives, Lucide icons
Utilities: TypeScript, class-variance-authority, clsx

Fix vulnerabilities (optional)

npm audit fix

For breaking changes:

npm audit fix --force

Start development server

npm run dev

The frontend will be available at http://localhost:5173.

Configuration

Environment variables

CheckThat AI uses environment variables for configuration. Here’s the complete reference:

API keys

# AI Provider API Keys
OPENAI_API_KEY=sk-...           # OpenAI GPT models
ANTHROPIC_API_KEY=sk-ant-...    # Anthropic Claude models
GEMINI_API_KEY=...              # Google Gemini models
GROK_API_KEY=...                # xAI Grok models

Backend configuration

# Environment type: dev, prod, or test
ENV_TYPE=dev

# Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=INFO

# CORS configuration
# Use "*" for public API or comma-separated origins
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

# Server configuration
HOST=0.0.0.0
PORT=8000

Frontend configuration

The frontend automatically connects to the backend at http://localhost:8000 in development. For production, update the API URL in src/app/client/src/lib/config.ts:

// src/app/client/src/lib/config.ts
export const API_BASE_URL = import.meta.env.PROD 
  ? 'https://your-api-domain.com'
  : 'http://localhost:8000';

Persistent environment variables

To make environment variables persistent across terminal sessions:

Linux/macOS

Add to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

# Add to ~/.bashrc or ~/.zshrc
export OPENAI_API_KEY="your-key"
export ANTHROPIC_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROK_API_KEY="your-key"

Then reload:

source ~/.bashrc  # or source ~/.zshrc

Windows

PowerShell Profile:

Open PowerShell and run:
```
notepad $PROFILE
```

Add your environment variables:

$env:OPENAI_API_KEY="your-key"
$env:ANTHROPIC_API_KEY="your-key"
$env:GEMINI_API_KEY="your-key"
$env:GROK_API_KEY="your-key"

Save and reload:
```
. $PROFILE
```

System Environment Variables:

Open System Properties → Environment Variables
Add new user or system variables
Restart your terminal

Production deployment

Building for production

Backend

The FastAPI backend is production-ready by default. For deployment:

# Install production dependencies
pip install -r requirements.txt

# Run with production ASGI server
uvicorn api.main:app --host 0.0.0.0 --port 8000 --workers 4

Frontend

Build the frontend for production:

cd src/app
npm run build

This creates optimized static files in src/app/dist/ ready for deployment to:

GitHub Pages
Netlify
Vercel
AWS S3 + CloudFront
Any static hosting service

Deployment options

GitHub Pages (frontend)

The project includes a deploy script:

cd src/app
npm run deploy

This builds and deploys to the /docs folder for GitHub Pages.

Cloud hosting (backend)

Render:

Create a new Web Service on Render
Connect your repository
Configure:
- Build Command: pip install -r requirements.txt
- Start Command: uvicorn api.main:app --host 0.0.0.0 --port $PORT
Add environment variables in Render dashboard

Railway:

Create new project from GitHub repo
Railway auto-detects Python and installs dependencies
Add environment variables
Deploy automatically on push

AWS/GCP/Azure: Deploy as a containerized application using Docker:

# Dockerfile
FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and deploy:

docker build -t checkthat-ai .
docker run -p 8000:8000 --env-file .env checkthat-ai

Troubleshooting

Common issues

Port already in use

Problem: Error “Port 5173 already in use” or “Port 8000 already in use” Solution:

# Find and kill process on port 5173 (frontend)
# Linux/macOS:
lsof -ti:5173 | xargs kill -9

# Windows:
netstat -ano | findstr :5173
taskkill /PID <PID> /F

# Find and kill process on port 8000 (backend)
# Linux/macOS:
lsof -ti:8000 | xargs kill -9

# Windows:
netstat -ano | findstr :8000
taskkill /PID <PID> /F

Permission denied on scripts

Problem: ./setup-project.sh: Permission denied Solution:

chmod +x setup-project.sh run-project.sh
./setup-project.sh

Windows script execution

Problem: Scripts don’t run on Windows Solution: Use Git Bash or WSL:

bash setup-project.sh
bash run-project.sh

Or install WSL:

wsl --install

npm install fails

Problem: npm install fails with errors Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

# If still failing, update npm
npm install -g npm@latest

Python module not found

Problem: ModuleNotFoundError: No module named 'fastapi' Solution:

# Ensure virtual environment is activated
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Reinstall dependencies
pip install -r requirements.txt

# Verify installation
pip list | grep fastapi

NLTK data missing

Problem: LookupError: Resource punkt not found Solution:

python -c "import nltk; nltk.download('punkt'); nltk.download('wordnet'); nltk.download('omw-1.4')"

API key not working

Problem: “Invalid API key” or “Unauthorized” errors Solution:

Verify API key is correct (no extra spaces)
Check API key has sufficient credits/quota

Ensure environment variable is set:

echo $OPENAI_API_KEY  # Linux/macOS
echo $env:OPENAI_API_KEY  # Windows PowerShell

Restart terminal and reactivate environment
Check provider’s status page for outages

CORS errors in browser

Problem: “CORS policy: No ‘Access-Control-Allow-Origin’ header” Solution:

Verify backend is running on correct port
Check CORS configuration in api/core/config.py

Set CORS_ORIGINS environment variable:

export CORS_ORIGINS="http://localhost:5173"

Restart backend server

Frontend build fails

Problem: npm run build fails with TypeScript errors Solution:

# Check Node.js version (requires v18+)
node --version

# Update dependencies
npm update

# Clear TypeScript cache
rm -rf node_modules/.cache

# Rebuild
npm run build

Getting help

If you’re still experiencing issues:

Check logs: Look for error messages in terminal output
Search issues: Check GitHub Issues
Create issue: Report bugs with:
- Operating system and version
- Node.js and Python versions
- Complete error messages
- Steps to reproduce
Community support: Join discussions on the repository

Next steps

Now that you have CheckThat AI installed:

Quickstart Guide

Learn how to make your first API call

API Reference

Explore all available endpoints

Evaluation Methods

Understand normalization strategies

Model Comparison

Compare AI models and choose the best fit

Get Started

Core Concepts

Web Application

Guides

Deployment

​Overview

​Prerequisites

​System requirements

​Verify installations

​API keys

​Installation methods

​Option 1: Automated setup (recommended)

​Option 2: Manual setup

​Backend installation

​Frontend installation

​Configuration

​Environment variables

​API keys

​Backend configuration

​Frontend configuration

​Persistent environment variables

​Linux/macOS

​Windows

​Production deployment

​Building for production

​Backend

​Frontend

​Deployment options

​GitHub Pages (frontend)

​Cloud hosting (backend)

​Troubleshooting

​Common issues

​Port already in use

​Permission denied on scripts

​Windows script execution

​npm install fails

​Python module not found

​NLTK data missing

​API key not working

​CORS errors in browser

​Frontend build fails

​Getting help

​Next steps

Quickstart Guide

API Reference

Evaluation Methods

Model Comparison

Build docs developers (and LLMs) love

Overview

Prerequisites

System requirements

Verify installations

API keys

Installation methods

Option 1: Automated setup (recommended)

Option 2: Manual setup

Backend installation

Frontend installation

Configuration

Environment variables

API keys

Backend configuration

Frontend configuration

Persistent environment variables

Linux/macOS

Windows

Production deployment

Building for production

Backend

Frontend

Deployment options

GitHub Pages (frontend)

Cloud hosting (backend)

Troubleshooting

Common issues

Port already in use

Permission denied on scripts

Windows script execution

npm install fails

Python module not found

NLTK data missing

API key not working

CORS errors in browser

Frontend build fails

Getting help

Next steps