Capture the Narrative Codebase

This is the codebase for the Capture The Narrative social media bot competition 2025. It was built to deploy viral bots in a mock social media environment to sway a mock political election. Placed in the top 30% of competitors.

Setup Instructions

Initial Setup - Create Virtual Environment and Install Dependencies

# Create virtual environment
python3 -m venv venv

# Activate virtual environment (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Export the llm API keys into the environment
export OPENAI_API_KEY='your_openai_api_key_here'

Run Options

Option 1: Run Manually (for testing/iteration)

Run these Python files in the correct order for a single bot iteration:

# 1. First, scrape trending data (usernames and post IDs)
python scrape.py

# 2. Generate new messages using LLM (creates 50 new messages)
python llm.py

# 3. Execute a single bot action (post, like, repost, or follow)
python bot_poster.py

Option 2: Run on Schedule (automated continuous operation)

# Run the scheduler (this will run all scripts continuously)
python bot_schedule.py

Schedule Details:

• scrape.py runs every 4 hours
• llm.py runs every 3 hours
• bot_poster.py runs every 1 minute

Explanation of Files in plain english

Scripts

scrape.py gets the post_IDS in trending and the usernames of others in trending page

Legit_API.py deals with the LEGIT platform posting, liking, reposting, following

bot_poster.py collects all the data from the data directory and randomly makes a post, like, repost, or follow

bot_schedule.py keeps bot_poster, llm.py, and scrap.py running on a continuous loop with delays

llm.py gets system messages from manually created messages in system_messages.json and then iterates through openai LLM to create 50 new message every time the script is run and then puts these messages in messages.json for the bot_poster.py to use.

bot_GUI.py is a visualiser for the logs.json file

Data files

bot_credentials.json stores the our bots credentials (usernames, passwords, tokens)

messages.json stores the messages created by llm.py

system_messages.json stores the system messages that llm.py uses to create new messages

post_ID.json stores the post IDs scraped from scrape.py

usernames_to_follow.json stores the usernames scraped from scrape.py

config.json is for the twooter sdk api from the comp

logs.json stores everything that happens when bot is run.