QBot - Quiz Bowl Discord Bot

A sophisticated Discord bot for quiz bowl question practice featuring an advanced query language for filtering questions by category. Built with Rust for high performance and reliability.

• 🔍 Smart Question Filtering: Advanced query language with Boolean operations for precise question selection
• 👓 Interactive Question Reading: Real-time question reading with buzzing functionality
• 🧠 AI-Powered Answer Checking: Intelligent answer validation using LLM integration
• 📚 Comprehensive Categories: Support for all major quiz bowl categories and subcategories
• ⚡ Real-time Feedback: Instant validation and prompting for incorrect answers

Install the bot now here: https://discord.com/oauth2/authorize?client_id=1404873488312828066

• Rust (latest stable version)
• Discord bot token
• (Optional) Gemini or host locally with Ollama for AI answer checking

Simply just clone the repository:

git clone https://github.com/ThatXliner/qbot.git
cd qbot

Then run:

docker run -it --rm -e DISCORD_TOKEN=$DISCORD_TOKEN -e GEMINI_API_KEY=$GEMINI_API_KEY ghcr.io/thatxliner/qbot:main

Or, if you want to use Ollama instead:

docker compose pull
docker compose up -d -e DISCORD_TOKEN=$DISCORD_TOKEN

1. Clone the repository:

   git clone https://github.com/ThatXliner/qbot.git
   cd qbot

2. Build the project:

   cargo build --release

3. Set up environment variables:

   export DISCORD_TOKEN="your_discord_bot_token"
   export GEMINI_API_KEY="your_gemini_api_key"  # Optional, for Gemini
   export OLLAMA_URL="http://127.0.0.1:11434"  # Optional, for Ollama. Default is http://127.0.0.1:11434
   export ENABLE_LEVENSHTEIN_DISTANCE="true"  # True by default
   export ENABLE_EMBEDDING_DISTANCE="false"  # Requires Ollama, false by default
   export ENABLE_LLM_CHECKS="true"  # Requires Gemini, true by default
   # If you enable LLM checks but you didn't provide a Gemini API key and Ollama isn't running, then the program will fail.

4. Run the bot:

   cargo run --release

• /tossup [query] [number] - Get quiz bowl questions

  • query (optional): Filter using query language, otherwise pick from a random category
  • Buzzing: Message buzz during question reading to buzz in
  • Answer Checking: Type answers for AI-powered validation

• /categories [category] - Browse available categories

  • Without parameters: Shows all main categories
  • With category name: Shows subcategories

• /query <expression> - Test query language expressions

• /help [topic] - Get help about commands or topics

/tossup query:Biology                    # Biology questions
/tossup query:Science + History          # Science OR History questions
/tossup query:Biology & Chemistry        # Questions tagged as both
/tossup query:Science - Math             # Science excluding Math
/tossup query:(Biology + Chemistry) - Math number:3  # 3 questions, Biology or Chemistry but no Math

# Run all tests (excluding integration tests that need external services)
cargo test -- --skip judge_tests

# Run specific test modules
cargo test utils_tests
cargo test qb_tests
cargo test query_tests

# Run with coverage
cargo tarpaulin --verbose --workspace --timeout 120 --skip-clean

# Format code
cargo fmt

# Run linter
cargo clippy

The project uses:

• Discord Integration: poise and serenity for Discord bot functionality
• HTTP Client: reqwest for QBReader API communication
• Query Processing: Custom recursive descent parser
• AI Integration: llm crate; Google Gemini or host locally with Ollama
• Async Runtime: tokio for async/await support

src/
├── main.rs           # Bot setup and Discord commands
├── query.rs          # Query language parser and processor
├── qb.rs            # QBReader API client and data structures
├── read.rs          # Interactive question reading logic
├── check.rs         # AI-powered answer validation
├── utils.rs         # Utility functions for text processing
└── *_tests.rs       # Comprehensive unit tests

When a question is being read:

1. Question Progression: Questions are read word-by-word in chunks
2. Buzzing: Type buzz to buzz in and attempt an answer
3. Answer Submission: Type your answer after buzzing
4. AI Validation: Answers are checked against the correct answer using LLM
5. Feedback: Get immediate feedback on correctness with explanations

• Literature (American, British, European, World)
• History (American, Ancient, European, World)
• Science (Biology, Chemistry, Physics, Math, Computer Science)
• Fine Arts (Visual, Auditory, Architecture, Film)
• Religion, Mythology, Philosophy
• Social Science, Current Events, Geography
• Other Academic, Pop Culture

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

• Fork the repository
• Create a feature branch
• Add tests for new functionality
• Ensure all tests pass
• Follow Rust formatting conventions
• Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

• QBReader for providing the quiz bowl question database
• The Rust community for excellent crates and tooling
• Quiz bowl community for feedback and feature requests

• QBReader API Documentation
• Query Language Documentation
• Discord Developer Portal
• Get a Google Gemini API Key
• Ollama Installation Guide

Made with ❤️ for the quiz bowl community