Library API

pip install kogo is enough for library use — the serve extra (FastAPI, uvicorn) is only needed for the web app.

import kogo

result: kogo.ComparisonResult = kogo.compare_pdfs("old.pdf", "new.pdf", "out/")

kogo.compare_pdfs is the entry point. Everything else on this page is typing support for its return value — the return value itself is a plain dict at runtime (also written to output_dir/result.json), so none of this changes behavior.

kogo.compare_pdfs(old_path, new_path, output_dir, *, old_name=None, new_name=None, dpi=144, sensitivity='standard', max_pages=200, previews=True, artifacts=True, on_progress=None)

Compare two revisions of a PDF document and produce marked outputs.

Text is compared at word precision (character precision for CJK text, including supplementary-plane kanji), after reconstructing a reading order from page layout. Figures, equations, and layout changes are detected visually outside text areas, and existing PDF annotations (highlights, comments, ink) are fingerprinted and diffed. Style-only changes (bold, italic, font size) on unchanged text are reported as well. All markers are baked into the output PDFs.

Parameters:

Name	Type	Description	Default
old_path	Path	PDF of the previous revision.	required
new_path	Path	PDF of the updated revision.	required
output_dir	Path	Directory for results; created if missing.	required
old_name	str | None	Display name of the old file; defaults to its file name.	None
new_name	str | None	Display name of the new file; defaults to its file name.	None
dpi	int	Rendering resolution for the visual diff, 96-180.	144
sensitivity	str	Figure detection sensitivity: "high", "standard", or "low".	'standard'
max_pages	int	Maximum number of pages allowed per file.	200
previews	bool	Whether to generate per-page JPEG previews.	True
artifacts	bool	Whether to bake and save the marked old/new/side-by-side PDFs. Set to False to skip that I/O when only the JSON summary is needed (e.g. a CI step); result["artifacts"] is then None. result.json is still written either way.	True
on_progress	Callable[[str, int, int], None] | None	Optional callback invoked as on_progress(phase, current, total) while the comparison runs, with phase one of "aligned", "comparing" (once per aligned row), "rendering", and "previews". Purely informational; exceptions it raises are not caught.	None

Returns:

Type	Description
ComparisonResult	A ComparisonResult dict (also written to output_dir/result.json) with keys:
ComparisonResult	"files": {"old": {"name", "pages"}, "new": {"name", "pages"}}
ComparisonResult	"settings": {"dpi", "sensitivity", "large_document_fallback"}
ComparisonResult	"summary": word/page/visual-region/annotation/style change counts
ComparisonResult	"legend": human-readable color explanations
ComparisonResult	"artifacts": {"old", "new", "side_by_side"} -> {"name", "label", "size"}, or None when artifacts=False
ComparisonResult	"rows": one entry per aligned page pair with "kind", "old"/"new" page info, and "changes" counts/snippets
ComparisonResult	Files written to output_dir: result.json always; old-highlighted.pdf,
ComparisonResult	new-highlighted.pdf, and side-by-side.pdf when artifacts is True;
ComparisonResult	previews/ when previews is True.

Raises:

Type	Description
ComparisonError	user-facing problems such as encrypted, empty, oversized, unreadable, or non-PDF input.

Example

import kogo

result = kogo.compare_pdfs("old.pdf", "new.pdf", "out/")
print(result["summary"]["changed_pages"])

ComparisonResult and friends

These are TypedDicts, useful for type-checking and editor autocomplete when you store or pass around a result:

def summarize(result: kogo.ComparisonResult) -> str:
    return f"{result['summary']['changed_pages']} pages changed"

kogo.ComparisonResult

Bases: TypedDict

kogo.Files

Bases: TypedDict

kogo.FileInfo

Bases: TypedDict

kogo.Settings

Bases: TypedDict

kogo.Summary

Bases: TypedDict

kogo.Legend

Bases: TypedDict

kogo.Artifacts

Bases: TypedDict

kogo.ArtifactInfo

Bases: TypedDict

kogo.Row

Bases: TypedDict

kogo.RowChanges

Bases: TypedDict

kogo.PageRef

Bases: _PageRefRequired

ComparisonError

kogo.ComparisonError

Bases: ValueError

A user-facing PDF comparison error.