Package: papermage
papermageSetupcondacreate-npapermagepython=3.11condaactivatepapermageIf you're installing from source:pip install -e '.[dev,predictors,visualizers]'If you're installing from PyPi:pip install 'papermage.[dev,predictors,visualizers]'(you may need to add/remove quotes depending on your command line shell).If you're on MacOSX, you'll also want to run:conda install popplerUnit testingpython-mpytestfor latest failed testpython-mpytest--lf--no-cov-n0for specific test name of class namepython-mpytest-k'TestPDFPlumberParser'--no-cov-n0Quick start1. Create a Document for the first time from a PDFfrom papermage.recipes import CoreRecipe

recipe = CoreRecipe()
doc = recipe.run("tests/fixtures/papermage.pdf")2. Understanding the output: theDocumentclassWhat is aDocument? At minimum, it is some text, saved under the.symbolslayer, which is just a<str>.  For example:>doc.symbols"PaperMage: A Unified Toolkit for Processing, Representing, and\nManipulating Visually-..."But this library is really useful when you have multiple different ways of segmenting.symbols. For example, segmenting the paper into Pages, and then each page into Rows:forpageindoc.pages:print(f'\n=== PAGE:{page.id}===\n\n')forrowinpage.rows:print(row.text)...===PAGE:5===4Vignette:BuildinganAttributedQASystemforScientificPapersHowcouldresearchersleveragepapermagefortheirresearch?Here,wewalkthroughausersce-narioinwhicharesearcher(Lucy)isprototypinganattributedQAsystemforscience.SystemDesign.DrawinginspirationfromKo...This shows two nice aspects of this library:Documentprovides iterables for different segmentations ofsymbols.  Options include things likepages, tokens, rows, sentences, sections, ....  Not every Parser will provide every segmentation, though.Each one of these segments (in our library, we call themEntityobjects) is aware of (and can access) other segment types. For example, you can callpage.rowsto get all Rows that intersect a particular Page. Or you can callsent.tokensto get all Tokens that intersect a particular Sentence. Or you can callsent.rowsto get the Row(s) that intersect a particular Sentence. These indexes are builtdynamicallywhen theDocumentis created and each time a newEntitytype is added. In the extreme, as long as those layers are available in the Document, you can write:forpageindoc.pages:forsentinpage.sentences:forrowinsent.rows:...You can check which layers are available in a Document via:>doc.layers['tokens','rows','pages','words','sentences','blocks','vila_entities','titles','authors','abstracts','keywords','sections','lists','bibliographies','equations','algorithms','figures','tables','captions','headers','footers','footnotes','symbols','images','metadata','entities','relations']3. Understanding intersection of EntitiesNote thatEntitys don't necessarily perfectly nest each other. For example, what happens if you run:forsentindoc.sentences:forrowinsent.rows:print([token.textfortokeninrow.tokens])Tokens that areoutsideeach sentence can still be printed. This is because when we jump from a sentence to its rows, we are looking forallrows that haveanyoverlap with the sentence. Rows can extend beyond sentence boundaries, and as such, can contain tokens outside that sentence.A key aspect of using this library is understanding how these different layers are defined & anticipating how they might interact with each other. We try to make decisions that are intuitive, but we do ask users to experiment with layers to build up familiarity.4. What's in anEntity?EachEntityobject stores information about its contents and position:.spans: List[Span], ASpanis a pointer intoDocument.symbols(that is,Span(start=0, end=5)corresponds tosymbols[0:5]). By default, when you iterate over anEntity, you iterate over its.spans..boxes: List[Box], ABoxrepresents a rectangular region on the page. Each span is associated a Box..metadata: Metadata, A free form dictionary-like object to store extra metadata about thatEntity. These are usually empty.5. How can I manually create my ownDocument?ADocumentis created by stitching together 3 types of tools:Parsers,RasterizersandPredictors.Parserstake a PDF as input and return aDocumentcompared of.symbolsand other layers. The example one we use is a wrapper aroundPDFPlumber- MIT License utility.Rasterizerstake a PDF as input and return anImageper page that is added toDocument.images. The example one we use isPDF2Image- MIT License.Predictorstake aDocumentand apply some operation to compute a new set ofEntityobjects that we can insert into ourDocument. These are all built in-house and can be either simple heuristics or full machine-learning models.6. How can I save myDocument?importjsonwithopen('filename.json','w')asf_out:json.dump(doc.to_json(),f_out,indent=4)will produce something akin to:{"symbols":"PaperMage: A Unified Toolkit for Processing, Representing, an...","entities":{"rows":[...],"tokens":[...],"words":[...],"blocks":[...],"sentences":[...]},"metadata":{...}}7. How can I load myDocument?These can be used to reconstruct aDocumentagain via:withopen('filename.json')asf_in:doc_dict=json.load(f_in)doc=Document.from_json(doc_dict)Note: A common pattern for adding layers to a document is to load in a previously saved document, run some additionalPredictorson it, and save the result.Seepapermage/predictors/README.mdfor more information about training custom predictors on your own data.Seepapermage/examples/quick_start_demo.ipynbfor a notebook walking through some more usage patterns.