adsfolio.pdf.annotation_matching

Find annotation locations locally for explicit review.

Text similarity does not establish the same scientific meaning. This module reads PDF text and coordinates without accessing credentials or a network.

class adsfolio.pdf.annotation_matching.TextIndex(path)

Bases: adsfolio.pdf.annotation_merge.WordIndex

Index PDF words and normalized character-to-word coordinates.

Parameters:

path (Path)

class adsfolio.pdf.annotation_matching.TextMatch(placement, text, method, edits=None, source_words=None, context='', matched_words=None, source_text='', operations=())

Bases: object

An unaccepted placement with its text evidence and alignment edits.

Parameters:

• placement (adsfolio.pdf.annotation_merge.Placement)

• text (str)

• method (str)

• edits (int | None)

• source_words (int | None)

• context (str)

• matched_words (int | None)

• source_text (str)

• operations (tuple[tuple[str, str, str], ...])

context: str = ''

edits: int | None = None

matched_words: int | None = None

method: str

operations: tuple[tuple[str, str, str], ...] = ()

placement: adsfolio.pdf.annotation_merge.Placement

source_text: str = ''

source_words: int | None = None

text: str

adsfolio.pdf.annotation_matching.source_evidence(item, index)

Read the source text anchor and its original PDF word coordinates.

Notes and shapes use the nearest block, measured by Euclidean rectangle gap. Markup follows the stored quad order, as does its displayed text.

Parameters:

• item (adsfolio.pdf.annotation_merge.AnnotationItem)

• index (adsfolio.pdf.annotation_matching.TextIndex)

Return type:

dict[str, Any]

adsfolio.pdf.annotation_matching.text_matches(item, index, query=None, offset=(0.0, 0.0), source_words=None)

Find all whole-word occurrences, allowing typography differences.

Repeated occurrences remain separate candidates. Symbol changes are labelled explicitly. Every occurrence still requires visual review.

Parameters:

• item (adsfolio.pdf.annotation_merge.AnnotationItem)

• index (adsfolio.pdf.annotation_matching.TextIndex)

• query (str | None)

• offset (tuple[float, float])

• source_words (list[tuple[Any, ...]] | None)

Return type:

list[adsfolio.pdf.annotation_matching.TextMatch]

adsfolio.pdf.annotation_matching.wording_matches(items, source, target, cancelled=<function <lambda>>)

Find each page’s closest wording locally for human review.

Sort by fewest word edits, then most matched words. Keep tied minimal spans on every page. No confidence threshold accepts a placement. If no words match, leave the annotation unresolved. Meaning can still differ.

Parameters:

• items (list[adsfolio.pdf.annotation_merge.AnnotationItem])

• source (adsfolio.pdf.annotation_matching.TextIndex)

• target (adsfolio.pdf.annotation_matching.TextIndex)

• cancelled (collections.abc.Callable[[], bool])

Return type:

dict[str, list[adsfolio.pdf.annotation_matching.TextMatch]]