From c5d66260bab8010e30477790d609e5612ba77ea9 Mon Sep 17 00:00:00 2001 From: Jamey ONeill Date: Mon, 6 Jul 2026 23:20:19 -0700 Subject: [PATCH] docs: align README and architecture output examples with v0.2 (0.9.23) Update the embedded output examples to match what extraction actually produces: - publisher and publicationYear shown as null (platform-owned, set at publish) - rightsList removed (stripped from output); publisher dropped from the ROR canonicalisation note and the pipeline-uses list - descriptionType shown as Other (set deterministically; no longer asked of the model) - affiliation identifier casing corrected to schemeURI - formats added (derived from the file extension) - architecture caption examples fixed to the {id, caption} shape Docs only; patch bump to 0.9.23. --- README.md | 28 ++++++++++------------------ docs/architecture.md | 16 ++++++++-------- pyproject.toml | 2 +- 3 files changed, 19 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 2568c26..b89d36b 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,7 @@ The pipeline uses: - **Qwen2-VL-7B** for vision-based OCR of image posters - **pdfplumber** for layout-aware PDF text extraction - **lingua-language-detector** for ISO 639-1 language detection on body text (overrides any value the model emits — body text beats metadata-fragment guessing) -- **ROR** (`https://api.ror.org`) for affiliation and publisher canonicalisation; matched names get a ROR identifier attached -- **SPDX** matching (with integer-exact version handling) for license normalisation in `rightsList` +- **ROR** (`https://api.ror.org`) for affiliation canonicalisation; matched names get a ROR identifier attached ## Quick Start @@ -124,7 +123,7 @@ Output conforms to the [poster-json-schema](https://github.com/fairdataihub/post "name": "Stanford University", "affiliationIdentifier": "https://ror.org/00f54p054", "affiliationIdentifierScheme": "ROR", - "schemeUri": "https://ror.org/" + "schemeURI": "https://ror.org/" } ] } @@ -132,7 +131,7 @@ Output conforms to the [poster-json-schema](https://github.com/fairdataihub/post "titles": [ { "title": "Machine Learning Approaches to Diabetic Retinopathy Detection" } ], - "publicationYear": 2025, + "publicationYear": null, "language": "en", "researchField": "Health Sciences", "subjects": [ @@ -140,18 +139,9 @@ Output conforms to the [poster-json-schema](https://github.com/fairdataihub/post { "subject": "Diabetic Retinopathy" } ], "descriptions": [ - { "description": "We present a deep learning model...", "descriptionType": "Abstract" } - ], - "publisher": { "name": "Zenodo" }, - "rightsList": [ - { - "rights": "Creative Commons Attribution 4.0 International", - "rightsIdentifier": "CC-BY-4.0", - "rightsIdentifierScheme": "SPDX", - "schemeUri": "https://spdx.org/licenses/", - "rightsUri": "https://creativecommons.org/licenses/by/4.0/" - } + { "description": "We present a deep learning model...", "descriptionType": "Other" } ], + "publisher": null, "content": { "sections": [ { "sectionTitle": "Abstract", "sectionContent": "..." }, @@ -160,15 +150,17 @@ Output conforms to the [poster-json-schema](https://github.com/fairdataihub/post ] }, "imageCaptions": [{ "id": "fig1", "caption": "Figure 1. ROC curves showing..." }], - "tableCaptions": [{ "id": "table1", "caption": "Table 1. Performance metrics" }] + "tableCaptions": [{ "id": "table1", "caption": "Table 1. Performance metrics" }], + "formats": ["application/pdf"] } ``` Notes on the auto-populated fields: - `language` is detected from the raw body text (lingua heuristic). Returns null when text is too short (<200 chars / <50 non-ASCII codepoints) or the detector is unsure. - `researchField` must be one of the four OpenAlex top-level domains: `Health Sciences`, `Life Sciences`, `Physical Sciences`, `Social Sciences`. Null when the model can't pick one confidently. -- `affiliation` and `publisher` get ROR enrichment when the matcher returns a high-confidence chosen result. Strings without a confident match pass through unchanged. Set `POSTER2JSON_ROR=0` to disable. -- `rightsList` entries are matched against an SPDX table; the matcher is conservative on version numbers (e.g. `CC-BY-4.0` and `CC-BY-4.1` are never confused). +- `affiliation` gets ROR enrichment when the matcher returns a high-confidence chosen result. Strings without a confident match pass through unchanged. Set `POSTER2JSON_ROR=0` to disable. +- `publisher` and `publicationYear` are always emitted as `null`. They are platform-owned and set when the poster is published, not by extraction. +- `formats` is derived from the input file's extension, not the model. ## System Requirements diff --git a/docs/architecture.md b/docs/architecture.md index 4c6600f..247ee03 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -127,11 +127,11 @@ ORCIDs are extracted from poster text via regex, then matched to the appropriate ### ROR enrichment -Affiliation names are looked up against the [ROR API](https://ror.org). When a match is found, `affiliationIdentifier`, `affiliationIdentifierScheme`, and `schemeUri` are populated. +Affiliation names are looked up against the [ROR API](https://ror.org). When a match is found, `affiliationIdentifier`, `affiliationIdentifierScheme`, and `schemeURI` are populated. -### Publisher enrichment +### Publisher -If a publisher name is extracted, it is also looked up against ROR to populate `publisherIdentifier`, `publisherIdentifierScheme`, and `schemeURI`. +`publisher` is always emitted as `null`. It is platform-owned and assigned when the poster is published (the hosting repository), so extraction does not populate or enrich it. ### Language detection @@ -139,11 +139,11 @@ The `language` field is detected from the raw poster text using the `lingua` lan ### Description type -The LLM prompt instructs the model to classify `descriptionType` based on poster content. It defaults to "Abstract" for poster summaries, but the model can choose from the full set of DataCite description types (Abstract, Methods, SeriesInformation, TableOfContents, TechnicalInfo, Other). +`descriptionType` is not requested from the model; it is set deterministically to `"Other"`, since the description is a machine-generated summary. `"Abstract"` is reserved for an author-provided formal abstract, which the platform attaches downstream. -### Rights normalization +### Rights -License strings from the LLM are canonicalized to SPDX form. This includes alias matching, Creative Commons URL parsing, and fuzzy matching (Levenshtein distance 1). Junk entries like funding acknowledgments or boilerplate text are filtered out. +`rightsList` is stripped from the output. The license is chosen by the user at publish time rather than inferred from the poster. ### Funding normalization @@ -185,10 +185,10 @@ Outputs conform to [poster-json-schema](https://github.com/fairdataihub/poster-j ] }, "imageCaptions": [ - {"caption": "Figure 1. Description"} + {"id": "fig1", "caption": "Figure 1. Description"} ], "tableCaptions": [ - {"captions": ["Table 1.", "Description"]} + {"id": "table1", "caption": "Table 1. Description"} ] } ``` diff --git a/pyproject.toml b/pyproject.toml index ffc6db2..8dee125 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [tool.poetry] name = "poster2json" -version = "0.9.22" +version = "0.9.23" description = "Convert scientific posters (PDF/images) to structured JSON metadata using Large Language Models" packages = [{ include = "poster2json" }]