Automate Quizzes with Turnitin's Assessment Agent

1. 1
   Generate a Question Item Bank

   First, provide the Student Assessment Agent with your source content. The agent will parse the text and generate a bank of questions, each pre-calibrated with difficulty and discrimination parameters based on its psychometric models.
2. 2
   Create an Adaptive Quiz

   Using the generated item bank ID, create a new quiz. The Student Assessment Agent will administer this as an adaptive test, selecting subsequent questions based on the student's real-time performance to efficiently gauge their proficiency.
3. 3
   Review Scores and Feedback

   Once students have taken the quiz, retrieve the results. The agent provides a proficiency score based on Item Response Theory (IRT), which is more nuanced than a simple percentage. You also get detailed feedback for each question.
4. 4
   Configure At-Risk Student Alerts

   Set a proficiency threshold to automatically flag students who may be struggling. The Student Assessment Agent will send an alert when a student's score falls below this value, enabling timely instructor intervention.

import requests
import json
import os

# --- Configuration ---
# It's best practice to use environment variables for API keys
API_KEY = os.environ.get("TURNITIN_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://api.turnitin.com/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

COURSE_MATERIAL = """
Photosynthesis is a process used by plants, algae, and certain bacteria to convert light energy into chemical energy, through a process that converts carbon dioxide and water into sugars and oxygen. The primary cellular location for photosynthesis is the chloroplast. Chlorophyll is the molecule in chloroplasts that absorbs the energy in sunlight.
"""

def generate_item_bank(name, text):
    """Sends source text to generate a bank of questions."""
    print(f"\n[1] Generating item bank for '{name}'...")
    payload = {"name": name, "source_text": text}
    try:
        response = requests.post(f"{BASE_URL}/item-banks", headers=HEADERS, json=payload)
        response.raise_for_status() # Raises an HTTPError for bad responses (4xx or 5xx)
        item_bank = response.json()
        print(f"Success! Item Bank ID: {item_bank.get('id')}")
        return item_bank
    except requests.exceptions.RequestException as e:
        print(f"Error generating item bank: {e}")
        return None

def create_adaptive_quiz(name, item_bank_id):
    """Creates an adaptive quiz using an existing item bank."""
    print(f"\n[2] Creating adaptive quiz '{name}'...")
    payload = {
        "name": name,
        "item_bank_id": item_bank_id,
        "settings": {"max_items": 15, "adaptive_mode": True}
    }
    try:
        response = requests.post(f"{BASE_URL}/quizzes", headers=HEADERS, json=payload)
        response.raise_for_status()
        quiz = response.json()
        print(f"Success! Quiz ID: {quiz.get('id')}. Shareable URL: {quiz.get('student_url')}")
        return quiz
    except requests.exceptions.RequestException as e:
        print(f"Error creating quiz: {e}")
        return None

def get_quiz_results(quiz_id):
    """Retrieves the scoring and proficiency results for a quiz."""
    print(f"\n[3] Fetching results for Quiz ID: {quiz_id}...")
    # In a real scenario, you'd wait for students to complete the quiz.
    # This is a mock response for demonstration.
    mock_results = {
        "quiz_id": quiz_id,
        "students": [
            {
                "student_id": "user_123",
                "irt_proficiency_score": 1.2, # Above average
                "at_risk_status": False
            },
            {
                "student_id": "user_456",
                "irt_proficiency_score": -0.8, # Below average
                "at_risk_status": True
            }
        ]
    }
    print("Success! Mock results received:")
    print(json.dumps(mock_results, indent=2))
    return mock_results

if __name__ == "__main__":
    if API_KEY == "YOUR_API_KEY":
        print("Please set your TURNITIN_API_KEY environment variable.")
    else:
        # Step 1: Generate Item Bank
        # NOTE: The API is hypothetical; these calls will not actually work.
        # We will use placeholder IDs for subsequent steps.
        # item_bank = generate_item_bank("Chapter 1: Photosynthesis", COURSE_MATERIAL)
        mock_item_bank_id = "ibank_mock_abc123"
        print(f"\n[1] Using mock Item Bank ID: {mock_item_bank_id}")

        # Step 2: Create Quiz
        # quiz = create_adaptive_quiz("Photosynthesis Basics Quiz", item_bank['id'])
        mock_quiz_id = "quiz_mock_def456"
        print(f"\n[2] Using mock Quiz ID: {mock_quiz_id}")

        # Step 3: Get Results
        if mock_quiz_id:
            get_quiz_results(mock_quiz_id)