Citation Extractor and Classifier

The Citation Extractor and Classifier is a software that performs the automatic annotation of in-text citations in academic papers provided in PDF.

It is developed within the GraspOS EU project.

It works by applying two steps, described as follows:

• PDF Parsing. The software analyses the PDF paper provided as input and extracts its basic bibliographic metadata, all the bibliographic references with all its metadata marked up, the citation sentences that contain in-text reference pointers, and other structural information, such as sections, when possible.
• Citation Function Classification. The software uses the output of the previous step to classify the semantics emerging from each citation sentence that will be used for characterising the function of the citation defined by the authors of the citing paper (i.e., the input PDF) by means of the related in-text reference pointer.

Please find more details in the README files of each module: extractor and classifier.

Docker Compose

Ready-to-use Docker setup. No expertise required.

Create docker-compose.yaml:

services:
grobid:
image: opencitations/oc_cec_grobid:1.2.0container_name: grobidinit: trueports:
- "8070:8070"environment:
- CROSSREF_MAILTO=your.email@example.org
- GROBID_CONCURRENCY=1deploy:
resources:
limits:
memory: 16Gcpus: '4'reservations:
memory: 8Gcpus: '2'extractor:
image: opencitations/oc_cec_extractor:1.1.0container_name: cec_extractorinit: trueports:
- "5001:5001"deploy:
resources:
limits:
memory: 16Greservations:
memory: 2Genvironment:
- GROBID_URL=http://grobid:8070depends_on:
- grobidcic-classifier:
image: opencitations/oc_cec_classifier:V2_fullcontainer_name: cic-classifierports:
- "5000:5000"deploy:
resources:
limits:
memory: 16Greservations:
memory: 4G

Adjust CPU and RAM based on your hardware.

Commands

docker compose up -d # Run the docker-compose.yaml
docker compose down # Stop all the containers
docker compose restart # Restart all

Services

• Classifier: http://localhost:5000/cic
• Extractor: http://localhost:5001/cex

Bulk extraction

scripts/bulk_extract.py runs the extractor API over a folder of PDFs and unpacks each result under cec_output/<pdf_stem>/. It uses the Python standard library only and assumes the Docker Compose stack is running on localhost:5001.

python scripts/bulk_extract.py path/to/pdfs # batch a directory
python scripts/bulk_extract.py paper.pdf # single file
python scripts/bulk_extract.py path/to/pdfs -o out # custom output dir
python scripts/bulk_extract.py path/to/pdfs --consolidate # enable CrossRef enrichment

By default the script does not query CrossRef: references are parsed straight from the PDF and returned as they appear. Consolidation is opt-in because GROBID fires CrossRef requests in parallel within every single PDF, and those bursts still hit HTTP 429 even on the polite pool (the parallelism is hardcoded in GROBID's Java source). If you pass --consolidate, replace your.email@example.org in CROSSREF_MAILTO with a real address first, so the requests land in the polite pool.