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
• 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

Marker	Description
[t]	Question start marker (required)
[s]	Single choice question
[m]	Multiple choice question
[g]	Gap-fill question
_	Correct answer (for MC questions)
-	Incorrect answer (for MC questions)
[gap]...[/gap]	Gap to fill
@N	Points for the question (e.g., @2)
# TITLE:	Pool title metadata
# DESCRIPTION:	Pool description metadata

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

Python API

from iliasqc import txt_to_zip

# Convert to ILIAS zip archive
output_path = txt_to_zip("questions.txt")
print(f"Created: {output_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/

Manual Testing

Create a local Python 3.12+ environment, install the package, and generate sample zip files for manual ILIAS import testing:

conda create -n iliasqc python=3.12 -y
conda activate iliasqc
pip install -e .
python manual_test.py

This generates all sample question pools as .zip files in manual_test_output/, ready to upload to ILIAS. It covers all commands: convert, --title/--description overrides, --points filtering, and combine with different target point totals.

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.