Skip to main content

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.

Metadata

Release files for aems-pdf-annotator 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aems-pdf-annotator 0.3.0
File Size Uploaded Provenance Actions
aems_pdf_annotator-0.3.0.tar.gz 304.7 kB Without provenance Details for aems_pdf_annotator-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aems-pdf-annotator 0.3.0
File Interpreter ABI Platform Actions
aems_pdf_annotator-0.3.0-py3-none-any.whl Python 3 none any Details for aems_pdf_annotator-0.3.0-py3-none-any.whl

Total release size: 354.9 kB

Release files / aems_pdf_annotator-0.3.0.tar.gz

Download URL aems_pdf_annotator-0.3.0.tar.gz
Size 304.7 kB
Tags Source
SHA-256 checksum
How to use checksums
435bdf01de3b2885b467faee77650db0b483e269358155b24c0e2649897e5137
BLAKE2b-256 checksum
How to use checksums
541a666cf7a95ba5fac3f72e0cc48b1488b571560a8fb326177bc6889915b848
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Release files / aems_pdf_annotator-0.3.0-py3-none-any.whl

Download URL aems_pdf_annotator-0.3.0-py3-none-any.whl
Size 50.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8c2f55d185f52022437e73ab66ceefabb4d3273e149eed2d76c18455da2de49f
BLAKE2b-256 checksum
How to use checksums
c719e7a37cd05cb0fe8d5dde5a82c308ce49fee5e6cba04b6b73081210d9e38f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Security for aems-pdf-annotator 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page