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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.