PE-Runner

A Discord bot for hosting competitive programming contests using Project Euler problems.

PE-Runner turns Project Euler into a community-based contest platform. Participants register their Project Euler accounts once, join contests through Discord, and submit solved problems through the bot. The bot verifies submissions against each participant's actual Project Euler progress rather than relying on self-reported answers.

Features

• Contest Management

  • Create contests with configurable difficulty tiers and time limits
  • Allow participants to opt in through Discord buttons
  • Automatically select problems that no participant has solved yet

• Automatic AC Verification

  • Verify whether a participant has actually solved a submitted problem
  • Retrieve Project Euler progress information to determine solved/unsolved status
  • Use problem difficulty as the base score
  • Use the final AC time as a tiebreaker

• Leaderboard

  • Display each participant's AC status for every contest problem
  • Automatically update standings after submissions

• Community Rating

  • AtCoder-inspired rating system
  • Rating changes only when participating in rated contests
  • Apply time-based decay to inactive ratings

• Problem Recommendations

  • Vote for problems through Discord
  • Recommend popular problems that the requesting user has not solved

• Persistence

  • SQLite for local development
  • Turso/libSQL for persistent production storage

• Read-only HTTP API

  • Expose rating summaries through a lightweight HTTP endpoint

Architecture

Discord
   |
   v
PE-Runner
   |
   +-- Discord Bot
   |     +-- Contest management
   |     +-- Submission handling
   |     +-- Leaderboard
   |     +-- Rating
   |     +-- Recommendations
   |
   +-- Project Euler Client
   |     +-- Authentication
   |     +-- Progress retrieval
   |     +-- AC verification
   |
   +-- Database
   |     +-- SQLite
   |     └-- Turso / libSQL
   |
   └-- HTTP Health / Rating API

How AC Verification Works

Project Euler does not provide a public API for determining which problems a user has solved.

PE-Runner therefore retrieves the participant's Project Euler progress page and parses the solved/unsolved status from the page. This allows the bot to verify an AC without requiring participants to manually report their results.

The system also uses the verified progress information when selecting contest problems, ensuring that selected problems are unsolved by all participants at the time of selection.

Technology

Component	Technology
Language	Python 3.12
Discord	discord.py 2.x
Web scraping	requests, BeautifulSoup4, lxml
Database	SQLite / Turso (libSQL)
Configuration	python-dotenv
Hosting	Render / Oracle Cloud / self-hosted
HTTP	Python standard-library http.server

Commands

Command	Description
/register	Register a Project Euler account
/create_contest	Create a contest
/submit	Submit a solved problem
/leaderboard	Display the current leaderboard
/recommend	Recommend a problem
/recommendations	Display recommended problems
/rating	Display community rating
/tweet	Generate a contest result post

Setup

1. Install dependencies

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure environment variables

Copy the example configuration:

cp .env.example .env

Configure the required Discord and Project Euler credentials in .env.

3. Verify Project Euler authentication

python tools/check_pe.py

4. Start the bot

python bot.py

For persistent production storage, configure Turso/libSQL through DB_URL and DB_TOKEN_RW.

Deployment

The repository includes deployment configuration for Render and self-hosted environments.

For Render, render.yaml can be used to configure the service automatically. A lightweight HTTP health endpoint is included so that the deployment can be monitored or kept alive by an external scheduler.

Design Considerations

A major design constraint of this project is that Project Euler does not expose the information required for contest management through a public API. Instead of treating participant submissions as trusted input, PE-Runner obtains the relevant state from Project Euler and uses it as the source of truth.

This also affects problem selection: the bot selects problems based on the verified state of all registered participants rather than maintaining an independent assumption about which problems they have solved.