Getting Started¶

Prerequisites¶

Before running the pipeline you need:

Python ≥ 3.10 — managed automatically by uv
uv — Python package and project manager
Typst v0.14.2 — PDF typesetting engine (must be on PATH or configured via typst.bin in parameters.yaml)

Installation¶

git clone https://github.com/WDGPH/ImmuKnow.git
cd ImmuKnow
uv sync

To also install development tools (pre-commit, pytest, etc.):

uv sync --group dev
uv run pre-commit install

Preparing input data¶

Input files must be .xlsx format with a single worksheet, extracted from Panorama PEAR.

Place input files in the input/ subdirectory (not tracked by Git):

ImmuKnow/
└── input/
    └── students.xlsx

Running the pipeline¶

uv run viper <input_file> <language> [options]

Required arguments:

Argument	Description
`<input_file>`	Name of the Excel file in `input/` (e.g., `students.xlsx`)
`<language>`	Language code: `en` (English) or `fr` (French)

Common options:

Option	Default	Description
`--input PATH`	`../input`	Input directory
`--output PATH`	`../output`	Output directory
`--config PATH`	`../config`	Configuration directory
`--template NAME`	Built-in `templates/`	PHU template name within `phu_templates/`

Examples:

# Basic English run
uv run viper students.xlsx en

# French run with custom output directory
uv run viper students.xlsx fr --output /tmp/output

# Use a PHU-specific template
uv run viper students.xlsx en --template wdgph

Output¶

All outputs are written to output/ (or the path given by --output):

output/
├── pdf_individual/      # One PDF per client
├── pdf_combined/        # Bundled PDFs (if bundling is enabled)
├── artifacts/           # Intermediate files (QR codes, Typst sources)
├── metadata/            # Validation reports and run metadata
└── logs/                # Per-run log files

Next steps¶

Configuration Reference — feature flags, QR codes, encryption, validation rules
PHU Templates — creating organization-specific layouts
Architecture — how the pipeline steps fit together