Skip to content

About

Generates trivia questions from any article-based website, using Claude through Atomic Agents

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

19 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿง  TriviaToday - Universal Article Trivia Quiz

Test your knowledge with trivia questions generated from any article-based website! TriviaToday supports Wikipedia, news sites, blogs, documentation, and more. Built using the Atomic Agents framework and creates an interactive quiz experience with 5 questions of increasing difficulty.

๐Ÿš€ Features

  • Interactive Quiz Game: Simple A-D answer format with immediate feedback
  • Universal Content Extraction: Works with Wikipedia, news sites, blogs, documentation, forums, and more
  • Smart Content Processing: Uses Trafilatura library for intelligent content extraction
  • Increasing Difficulty: Generates questions from Easy to Master level
  • Rich Console Interface: Beautiful terminal UI with progress indicators
  • Score Tracking: See your performance at the end of each quiz
  • Play Again: Easy restart for multiple rounds
  • Modular Design: Built with atomic agents for extensibility
  • Type Safety: Full type hints and Pydantic validation

๐Ÿ“ฆ Installation

  1. Clone the repository:
git clone <your-repo-url>
cd triviatoday
  1. Install dependencies using uv (recommended) or pip:
# Using uv (recommended)
uv sync

# Or using pip
pip install -e .
  1. Set up your configuration:
# Copy the example configuration file
cp env.example .env

# Edit the .env file with your settings
# At minimum, you need to set your Anthropic API key

Required Configuration:

  • ANTHROPIC_API_KEY: Your Anthropic API key for Claude access

Optional Configuration:

  • MODEL_NAME: AI model to use (default: claude-3-5-sonnet-20240620)
  • MODEL_MAX_TOKENS: Maximum tokens to generate (default: 4000)
  • MODEL_TEMPERATURE: Response temperature 0.0-1.0 (default: 0.7)
  • MODEL_TOP_P: Top-p sampling parameter 0.0-1.0 (default: 0.9)
  • NUM_QUESTIONS: Number of trivia questions to generate (default: 5)

โš™๏ธ Configuration

TriviaToday uses Pydantic Settings for centralized configuration management. This provides:

  • Type-safe configuration with automatic validation
  • Environment variable support with .env file loading (UTF-8 encoded)
  • Default values for all optional settings
  • Centralized configuration instead of scattered os.getenv() calls
  • Case-insensitive environment variable matching
  • Proper error handling for missing required configuration

Configuration Classes

  • ModelConfig: AI model settings (name, tokens, temperature, etc.) with MODEL_ prefix
  • APIConfig: External API keys and credentials (no prefix for API keys)
  • AppConfig: Application-specific settings (content length, question count) with no prefix

Environment Variable Prefixes

  • MODEL_*: Model configuration (e.g., MODEL_NAME, MODEL_MAX_TOKENS)
  • No prefix: API keys and application settings (e.g., ANTHROPIC_API_KEY, MAX_CONTENT_LENGTH, NUM_QUESTIONS)

๐ŸŽฏ Usage

Command Line Interface

Run the interactive quiz game:

python -m triviatoday
# or
uv run python -m src.triviatoday.app

The app will:

  1. Ask for an article URL (Wikipedia, news, blog, documentation, etc.)
  2. Show a loading timer while generating questions
  3. Present questions one by one with A-D answer options
  4. Show your score and ask if you want to play again

API Server

Run the FastAPI server for API access:

# Start the server
uv run triviatoday-server
# or
uv run python -m src.triviatoday.api_server

The server will start on http://localhost:8000 with:

API Example

# Generate trivia from an article
curl -X POST "http://localhost:8000/generate-trivia" \
     -H "Content-Type: application/json" \
     -d '{"article_url": "https://en.wikipedia.org/wiki/Chess"}'

Programmatic Usage

from triviatoday.agent import create_trivia_agent
from triviatoday.schemas import UniversalTriviaInputSchema
import anthropic
import instructor
import os

# Set up the agent (uses universal scraper by default)
client = instructor.from_anthropic(anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY")))
agent = create_trivia_agent(client)

# Alternative: Use Wikipedia-specific agent for Wikipedia-only use cases
# from triviatoday.agent import create_wikipedia_trivia_agent
# agent = create_wikipedia_trivia_agent(client)

# Generate questions from any article
input_data = UniversalTriviaInputSchema(
    article_url="https://en.wikipedia.org/wiki/Artificial_intelligence"
)

result = agent.run(input_data)
print(f"Generated {len(result.questions)} questions about {result.title}")
print(f"Author: {result.author}")
print(f"Date: {result.date}")

๐Ÿ—๏ธ Architecture

TriviaToday is built using the Atomic Agents framework and consists of:

  • UniversalScraper: Tool for extracting content from any article-based website using Trafilatura
  • WikipediaScraper: Specialized tool for Wikipedia content extraction (legacy support)
  • UniversalTriviaAgent: Main agent that orchestrates scraping and question generation
  • Structured Schemas: Pydantic models for type-safe input/output
  • Rich CLI: Beautiful command-line interface

Components

src/triviatoday/
โ”œโ”€โ”€ agent.py              # Main trivia agents
โ”œโ”€โ”€ app.py                # CLI application
โ”œโ”€โ”€ schemas.py            # Input/output schemas
โ””โ”€โ”€ tools/
    โ”œโ”€โ”€ __init__.py
    โ”œโ”€โ”€ base_scraper.py       # Shared schemas and utilities
    โ”œโ”€โ”€ universal_scraper.py  # Universal content extraction
    โ””โ”€โ”€ wikipedia_scraper.py  # Wikipedia-specific extraction

Supported Websites

TriviaToday works with any article-based website, including:

  • Wikipedia (all languages)
  • News sites (BBC, CNN, Reuters, The Guardian, etc.)
  • Blogs (Medium, WordPress, custom blogs)
  • Documentation (MDN Web Docs, GitHub docs, etc.)
  • Educational sites (Khan Academy, university sites)
  • Forums (Reddit, Stack Overflow, etc.)
  • Any site with readable article content

๐ŸŽฎ Example Output

๐Ÿง  TriviaToday - Universal Article Trivia Quiz
Test your knowledge with trivia questions from any article-based website!

Enter an article URL: https://en.wikipedia.org/wiki/Chess

โœ… Successfully generated 5 trivia questions!

๐Ÿ“– Article: Chess
๐Ÿ”— URL: https://en.wikipedia.org/wiki/Chess
๐Ÿ“ Summary: Chess is a strategic board game played between two players...
๐Ÿ‘ค Author: Not available
๐Ÿ“… Date: Not available

๐ŸŽฏ Generated Trivia Questions:

โ”Œโ”€ Difficulty: Easy โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Question 1: How many players participate in a  โ”‚
โ”‚ standard game of chess?                        โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

A. 1
B. 2  โœ“
C. 3
D. 4

โœ“ Correct Answer: 2
Explanation: Chess is played between exactly two players...

๐Ÿ› ๏ธ Development

The project uses modern Python practices:

  • Python 3.13+: Latest Python features
  • Type Hints: Full type safety
  • Pydantic: Data validation
  • Rich: Beautiful console output
  • Atomic Agents: Modular AI agent framework
  • Trafilatura: Universal content extraction

Development Setup

  1. Install development dependencies:
uv sync --dev
  1. Run tests (if available):
uv run pytest
  1. Format code:
uv run ruff format
  1. Lint code:
uv run ruff check

๐Ÿ”ง Troubleshooting

Common Issues

  1. API Key Error: Make sure ANTHROPIC_API_KEY is set in your environment or .env file
  2. Invalid URL: Ensure you're providing a valid article URL (Wikipedia, news sites, blogs, etc.)
  3. Network Issues: Check your internet connection and try again
  4. Rate Limits: If you hit API rate limits, wait a moment before trying again
  5. Content Extraction Issues: Some sites may block automated access or have complex layouts

Error Messages

  • Error fetching article page: The URL might be invalid or the page might not exist
  • No content could be extracted: The page might not contain readable article content
  • Error initializing Anthropic client: Check your API key configuration
  • Input data is required: This shouldn't happen in normal usage

๐Ÿค Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if needed
  5. Submit a pull request

๐Ÿ“„ License

This project is licensed under the GPL-3.0-or-later License.

๐Ÿ™ Acknowledgments

  • Built with Atomic Agents
  • Powered by Anthropic's Claude
  • Content extraction powered by Trafilatura
  • Inspired by the wealth of knowledge available on the web

About

Generates trivia questions from any article-based website, using Claude through Atomic Agents

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages