iliasqc

Python package to convert structured text files into ILIAS-compatible question pool zip archives. Supports single/multiple choice and gap-fill question types, plus automated quiz combination generation.

This package is based on Kaffeedrache/Tiqi.

Features

• Multiple question types: Single choice, multiple choice, and gap-fill questions
• QTI 1.2 compliant: Generates ILIAS-compatible XML format
• Python API: Use programmatically in your Python code
• CLI tool: Convert files from the command line
• Template generator: Create question file templates with examples
• Quiz combinations: Generate multiple pools and find optimal combinations to reach target point totals

Installation

pip

pip install iliasqc

conda / mamba (conda-forge)

conda install -c conda-forge iliasqc
# or
mamba install -c conda-forge iliasqc

Question File Format

Questions are defined in .txt files with special syntax:

# TITLE: My Question Pool
# DESCRIPTION: A collection of questions

[t][s] Single Choice Question @1
Question text goes here.
_ Correct answer
- Incorrect answer
- Another wrong answer

[t][m] Multiple Choice Question @2
Which options are correct?
- Wrong answer
_ Correct answer 1
_ Correct answer 2
- Wrong again

[t][g] Gap-Fill Question @1
The capital of France is [gap]Paris[/gap].
The capital of Germany is [gap]Berlin[/gap].

Syntax Reference

Usage

Command Line

Convert a question file to ILIAS zip archive:

iliasqc convert questions.txt

Specify custom output path:

iliasqc convert questions.txt -o my_pool.zip

Override title and description:

iliasqc convert questions.txt -t "My Pool" --description "My description"

Filter questions by point value:

iliasqc convert questions.txt -p 2

Quiz Combinations

Generate multiple pools (one per point value) and find combinations to reach a target:

iliasqc combine questions.txt -t 20

This will:

1. Create separate zip files for each point value found in your questions
2. Find all valid combinations that sum to 20 points
3. Display a table showing the combinations ranked by balance
4. Export a CSV file with the combinations

Options:

• -t, --target: Target total points (required)
• -o, --output: Output directory (default: same as input file)
• -c, --combinations: Maximum number of combinations to show (default: 10)
• --csv-only: Only output CSV, skip the table display

Example output:

Quiz Combinations for 20.0 Points
======================================================================

Available Pools:
  - My Pool (5 points): 8 questions
  - My Pool (4 points): 12 questions
  - My Pool (2 points): 15 questions

──────────────────────────────────────────────────────────────────────
Rank  Questions  Balance  Combination
──────────────────────────────────────────────────────────────────────

1     5          ●●●●     2x My Pool (5 points) + 5x My Pool (2 points)
2     4          ●●●○     5x My Pool (4 points)
3     6          ●●●○     3x My Pool (4 points) + 5x My Pool (2 points)
──────────────────────────────────────────────────────────────────────

Tip: Lower balance score = more diverse quiz

Generated 3 pools:
  - My Pool_2pt_pool.zip: 15 questions
  - My Pool_4pt_pool.zip: 12 questions
  - My Pool_5pt_pool.zip: 8 questions

Export as QTI XML (without creating zip archive):

iliasqc qti questions.txt -o output.xml

Generate a question template file:

iliasqc template -o my_template.txt

Generate template without examples:

iliasqc template -o basic_template.txt --no-examples

Python API

from iliasqc import txt_to_zip, txt_to_qti, generate_template

# Convert to ILIAS zip archive
output_path = txt_to_zip("questions.txt")
print(f"Created: {output_path}")

# Convert to QTI XML only
xml_path = txt_to_qti("questions.txt", "output.xml")
print(f"Created: {xml_path}")

# Generate a template
template_path = generate_template("my_template.txt")
print(f"Created template: {template_path}")

Quiz Combination API

from iliasqc import (
    generate_quiz_combinations,
    generate_pools_by_points,
    find_combinations,
    format_combinations_table,
    export_combinations_csv,
)

# Generate pools and find combinations (full pipeline)
pools, combinations = generate_quiz_combinations(
    "questions.txt",
    target_points=20,
    output_dir=".",
)

# Or use individual functions
pools = generate_pools_by_points("questions.txt")
combinations = find_combinations(pools, target_points=20)

# Format as a text table
table = format_combinations_table(combinations, pools, target_points=20)
print(table)

# Export to CSV
csv_path = export_combinations_csv(".", combinations, target_points=20)

Development

git clone https://github.com/famosab/iliasqc.git
cd iliasqc
pip install -e ".[dev]"

Running Tests

Run all tests:

pytest tests/

Run with coverage:

pytest tests/ --cov=iliasqc --cov-report=term-missing

Code Quality

Run linting checks:

ruff check src/ tests/
ruff format --check src/ tests/

Fix linting issues automatically:

ruff check --fix src/ tests/
ruff format src/ tests/

Continuous Integration

The project uses GitHub Actions for automated testing. The CI pipeline runs on every push and pull request, testing against Python 3.12, 3.13, and 3.14.

License

MIT – see LICENSE.