ua-exam

ua-exam is a Python CLI tool designed to automate the creation of physical paper exams from Moodle question banks (GIFT format). It allows instructors to define complex exam structures via a JSON configuration, randomly select questions from hierarchical categories, generate professional LaTeX-ready documents, and support multiple randomized exam copies.

Detailed documentation is available on the GitHub Pages.

Key Features

• Advanced GIFT Parsing:
  • Support for .gift and .txt files.
  • Handles Multiple Choice, True/False, and Open Answer (Essay).
  • Support for Multiple Response (partial credits) with multi-answer solution keys.
  • Robust handling of questions containing internal blank lines and complex formatting.
• Hierarchical Question Bank:
  • Recursive scanning of questions folders.
  • Automatic indexing by the GIFT $CATEGORY directive.
  • Flexible category matching using a global category_prefix.
• Smart Randomization & Deduplication:
  • Option Shuffling: Choices are randomized for every question to ensure variety.
  • Global Deduplication: Prevents the same question from appearing twice in the same exam.
  • Reproducibility: Use the seed flag to generate the exact same exam order.
• Multiple Exam Versions (Copies):
  • Automatically generate multiple randomized copies of the same exam structure (e.g. Version A, Version B) with sequential seeds.
• Professional LaTeX Layout:
  • Native support for LaTeX Math ($...$) and Code Blocks (code).
  • Automated university branding (Logo and Header).
  • Pre-configured identifying fields (Name, Number, Classification).
  • Solutions generated as a CSV file, perfectly mapped to the shuffled choices.
• Modular Question Conversion:
  • Extensible converter registry to transform GIFT files into other Moodle or LMS formats.

Project Structure

.
├── src/
│   └── ua_exam/
│       ├── __init__.py         # Package initialization
│       ├── cli.py              # CLI entry point
│       ├── exam_generator.py   # Exam generation engine
│       ├── gift_parser.py      # GIFT parsing module
│       ├── gift_escaper.py     # GIFT escaping/markdown translation module
│       ├── pdf_renderer.py     # PDF compilation module
│       ├── converters/         # Modular question format converters
│       └── assets/
│           └── logo_ua_cropped.pdf  # Packaged default university logo
├── test/                       # Test suite
├── examples/                   # Configuration examples
└── assets/
    └── logo.svg                # Project logo

Installation

Install directly from source or via PyPI using pip or uv:

pip install .

Usage

The ua-exam command-line tool provides three primary subcommands: generate, escape, and convert.

1. Generating Exams (generate)

Generates randomized exam copies from a JSON configuration file.

ua-exam generate -c config.json -s 42 -o out/exam.md --pdf

• -c, --config: Path to the JSON configuration file (required).
• -s, --seed: Base random seed (default: 42).
• -o, --output: Base output file path (default: exam.md).
• --pdf: Automatically compile the generated Markdown file into a PDF.

Configuration (config.json)

The config file controls the exam generation logic.

Example Configurations

Example 1: Single Question Folder

{
  "class": "Laboratórios de Sistemas e Serviços",
  "lang": "pt",
  "exam": "Teste 01",
  "copies": 3,
  "category_prefix": "lss/test01/exam",
  "questions_folder": "gift/test01",
  "parts": [
    {
      "part": "Escolha Múltipla",
      "classification": 10,
      "questions": [
        { "topic": "01-terminal", "quantity": 3 },
        { "topic": "02-virtualizacao", "quantity": 4 }
      ]
    },
    {
      "part": "Resposta Aberta",
      "classification": 10,
      "questions": [
        { "topic": "open-questions", "quantity": 4 }
      ]
    }
  ]
}

Example 2: Multiple Question Folders (with prefixes)

{
  "class": "Laboratórios de Sistemas e Serviços",
  "lang": "en",
  "exam": "Exam",
  "copies": 2,
  "questions_folders": [
    {"path": "gift/test01/en", "category_prefix": "lss/test01/exam"},
    {"path": "gift/test02/en", "category_prefix": "lss/test02/exam"}
  ],
  "parts": [
    {
      "part": "Multiple Choice",
      "classification": 10,
      "questions": [
        { "topic": "01-terminal", "quantity": 2 },
        { "topic": "02-virtualizacao", "quantity": 2 }
      ]
    }
  ]
}

2. Escaping and Converting MD to GIFT (escape)

Converts a formatted Markdown file into a Moodle-compatible GIFT file, handling necessary special character escaping.

ua-exam escape -i input.md -o output.gift

3. Modular Question Format Conversion (convert)

Converts GIFT question banks to other question formats (e.g. Moodle XML).

ua-exam convert -i input.gift -f xml -o output.xml

Authors

• Mário Antunes - mariolpantunes

License

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