REANIMATOR: VLM-Powered Document Parsing & Synthetic Relevance Assessment

REANIMATOR is a Python toolkit for document collection processing, structured multi-modal element parsing (tables, figures, formulas, text), and domain-independent synthetic relevance assessment using Vision-Language Models (VLMs) and LLMs (UMBRELA framework).

📖 HTML & Technical Documentation: Full API reference and guide hosted in docs/ and compiled PyData HTML docs in docs/_build/html/index.html.

📦 Quick Installation

Install directly via pip:

pip install reanimator-vlm

Or install all optional dependencies (local VLM inference, retrieval models):

pip install "reanimator-vlm[all]"

🚀 Quickstart Example

You can import directly using either from reanimator import * or from reanimator_vlm import *:

from reanimator import (
    ReanimatorVLM,
    ProjectCollection,
    OpenAIVisionBackend,
    CachedBackend,
    RelevanceEvaluator,
)

# 1. Initialize VLM Backend & Processing Pipeline
api_backend = OpenAIVisionBackend(
    model="rednote-hilab/dots.mocr",
    base_url="http://localhost:6543/v1",
    api_key="not-needed",
    use_structured_layout=True,
)
backend = CachedBackend(api_backend, cache_dir="./.md_cache")
pipeline = ReanimatorVLM(backend=backend)

# 2. Define Disk-Backed Project Workspace Collection
project = ProjectCollection(
    project_dir="./my_project_data",
    name="COVID-19 Research Collection",
    arxiv_ids=["2504.07584"],
    dois=["10.18653/v1/2024.findings-acl.712"],
    topics=[
        {
            "topic_id": "101",
            "title": "Table parsing performance",
            "description": "Evaluation of table parsing quality in scientific literature."
        }
    ]
)

# 3. Batch Process Documents (Streams & Saves Directly to Disk)
processed_ids = project.process(pipeline, verbose=True)

# 4. Lazy Document Inspection (No RAM Bloat)
for doc in project.iter_documents():
    print(f"Doc: {doc.doc_id} | Tables: {len(doc.tables)} | Figures: {len(doc.figures)}")

# 5. Domain-Independent Synthetic Relevance Assessment (UMBRELA Framework)
evaluator = RelevanceEvaluator(
    backend=backend,
    model_name="synthetic-dots.mocr",
    domain_instruction="general information retrieval and document intelligence",
)

# Evaluate target modality ('tables', 'figures', 'formulas', 'text_only', 'full_document', 'chunks')
judgements = project.run_relevance_assessment(evaluator, modality="tables", verbose=True)

# Export standard TREC qrels format
# Saved to ./my_project_data/relevance/qrels_tables.txt

📑 Core Features

• Multi-Modal Document Parsing: High-accuracy table extraction, figure grounding, formula recognition, and bounding box normalization using dots.mocr or Gemini.
• ProjectCollection Workspace: Disk-backed document workspace managing PDFs, parsed JSONs, VLM cache, figure crops, and relevance judgments without keeping large collections in RAM.
• Synthetic Relevance Engine (reanimator.relevance): Generates 4-level UMBRELA relevance judgments across flexible modalities (full_document, text_only, tables, figures, formulas, chunks).
• Standard TREC Qrels Export: Output relevance judgments directly into standard TREC qrels file format for IR evaluation.

📄 License

Distributed under the MIT License.