Skip to content

Latest commit

 

History

History
91 lines (68 loc) · 4.17 KB

CLAUDE.md

File metadata and controls

91 lines (68 loc) · 4.17 KB

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