CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Running the Application

python app.py

The application will start a Gradio web interface at http://127.0.0.1:7860

Environment Setup

# Using uv (recommended)
uv venv -p 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

# Using pip
pip install -r requirements.txt

Environment Variables

Create a .env file with:

OPENAI_API_KEY=your_api_key_here

Architecture Overview

This is an AI Course Assessment Generator that creates learning objectives and multiple-choice questions from course materials. The system uses OpenAI's language models with structured output generation via the instructor library.

Core Workflow

1. Content Processing: Upload course materials (.vtt, .srt, .ipynb) → Extract and tag content with XML source references
2. Learning Objective Generation: Generate base objectives → Group and rank → Enhance with incorrect answer suggestions
3. Question Generation: Create multiple-choice questions from objectives → Quality assessment → Ranking and grouping
4. Assessment Export: Save final assessment to JSON format

Key Architecture Patterns

Modular Prompt System: The prompts/ directory contains reusable prompt components that are imported and combined in generation modules. This allows for consistent quality standards across different generation tasks.

Orchestrator Pattern: Both LearningObjectiveGenerator and QuizGenerator act as orchestrators that coordinate calls to specialized generation functions rather than implementing generation logic directly.

Structured Output: All LLM interactions use Pydantic models with the instructor library to ensure consistent, validated output formats.

Source Tracking: Content is wrapped in XML tags (e.g., <source file="example.ipynb">content</source>) throughout the pipeline to maintain traceability from source files to generated questions.

Key Components

Main Generators

• LearningObjectiveGenerator (learning_objective_generator/generator.py): Orchestrates learning objective generation, grouping, and enhancement
• QuizGenerator (quiz_generator/generator.py): Orchestrates question generation, quality assessment, and ranking

Data Models (models/)

• Learning objectives progress from BaseLearningObjective → LearningObjective (with incorrect answers) → GroupedLearningObjective
• Questions progress from MultipleChoiceQuestion → RankedMultipleChoiceQuestion → GroupedMultipleChoiceQuestion
• Final output is an Assessment containing both objectives and questions

Generation Pipeline

1. Base Generation: Create initial learning objectives from content
2. Grouping & Ranking: Group similar objectives and select best in each group
3. Enhancement: Add incorrect answer suggestions to selected objectives
4. Question Generation: Create multiple-choice questions with feedback
5. Quality Assessment: Use LLM judge to evaluate question quality
6. Final Ranking: Rank and group questions for output

UI Structure (ui/)

• app.py: Gradio interface with tabs for objectives, questions, and export
• Handler modules process user interactions and coordinate with generators
• State management tracks data between UI components

Development Notes

Model Configuration

• Default model: gpt-5 with temperature 1.0
• Separate model selection for incorrect answer generation (typically o1)
• Quality assessment often uses gpt-5-mini for cost efficiency

Content Processing

• Supports .vtt/.srt subtitle files and .ipynb Jupyter notebooks
• All content is tagged with XML source references for traceability
• Content processor handles multiple file formats uniformly

Quality Standards

The system enforces educational quality through modular prompt components:

• General quality standards apply to all generated content
• Specific standards for questions, correct answers, and incorrect answers
• Bloom's taxonomy integration for appropriate learning levels
• Example-based prompting for consistency