aems-pdf-annotator

Schema-driven PDF annotation engine for AEMS — the Assisted Exam Marking System.

What this is

A small, focused library that takes a structured annotation payload (LLM output, rubric verdicts, page-anchored highlights) and draws it onto a PDF using PyMuPDF. It powers the annotated marker PDFs that AEMS returns to instructors.

Key surfaces:

• PDFAnnotation, BBox, AnnotationBatch — typed models for the annotation payload (Pydantic v2).
• payload_to_annotations(), feedback_items_to_annotations() — convert AEMS LLM output (the "annotation contract") into typed annotation objects.
• PDFAnnotator, apply_annotations(), apply_annotation_batch() — open a PDF, draw the annotations, save.
• Validator + schemas — invariants on coordinates, colours, icons, verdicts.

Installation

pip install aems-pdf-annotator

Or from source:

pip install git+https://github.com/aems-app/aems-pdf-annotator

Requires Python 3.10+.

Minimal example

from aems_pdf_annotator import (
    PDFAnnotation, BBox, AnnotationColor, AnnotationType,
    apply_annotations,
)

annotations = [
    PDFAnnotation(
        page=1,
        bbox=BBox(x=0.10, y=0.20, width=0.40, height=0.04),
        annotation_type=AnnotationType.HIGHLIGHT,
        color=AnnotationColor.GREEN,
        content="Correct identification of the boundary condition.",
        is_verdict=False,
    ),
    PDFAnnotation(
        page=1,
        bbox=BBox(x=0.80, y=0.20, width=0.03, height=0.03),
        annotation_type=AnnotationType.STAR,
        color=AnnotationColor.GREEN,
        content="PASS",
        is_verdict=True,
    ),
]

apply_annotations(
    input_pdf_path="input.pdf",
    output_pdf_path="annotated.pdf",
    annotations=annotations,
)

Coordinates are normalised (0.0–1.0) with (0, 0) at the top-left of the page; the renderer converts to PDF bottom-left internally.

Contract version

The LLM-output payload format follows a versioned contract. Current values are exported as CURRENT_CONTRACT_VERSION and CURRENT_COORDINATE_SPACE. payload_to_annotations() validates the incoming payload's contract version against SUPPORTED_CONTRACT_VERSIONS and raises ContractValidationError on a mismatch.

License

AGPL-3.0-or-later. See LICENSE.

This package wraps PyMuPDF, which is itself licensed under AGPL-3.0. Any program that imports aems_pdf_annotator in-process inherits the AGPL combined-work obligations. If that does not fit your distribution model, commercial PyMuPDF licensing is available from Artifex.

Links

• Homepage: https://aems.app
• Source: https://github.com/aems-app/aems-pdf-annotator
• Issues: https://github.com/aems-app/aems-pdf-annotator/issues