Metadata-Version: 2.4
Name: reanimator_vlm
Version: 0.1.0
Summary: VLM-powered document parsing and analysis – a clean rebuild of REANIMATOR using dots.mocr and other vision-language models.
Author: Fabian Haak
License: MIT
Project-URL: Homepage, https://github.com/irgroup/REANIMATOR-VLM
Project-URL: Bug Tracker, https://github.com/irgroup/REANIMATOR-VLM/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy
Requires-Dist: Pillow>=10.0
Requires-Dist: pdf2image>=1.16
Requires-Dist: pdfplumber>=0.10
Requires-Dist: tqdm>=4.65
Requires-Dist: requests>=2.31
Requires-Dist: google-genai>=1.0
Requires-Dist: python-dotenv
Requires-Dist: scikit-learn>=1.3
Provides-Extra: local
Requires-Dist: torch>=2.2; extra == "local"
Requires-Dist: transformers>=4.45; extra == "local"
Requires-Dist: accelerate>=0.30; extra == "local"
Requires-Dist: qwen-vl-utils; extra == "local"
Provides-Extra: quantised
Requires-Dist: bitsandbytes>=0.43; extra == "quantised"
Provides-Extra: retrieval
Requires-Dist: rank_bm25>=0.2; extra == "retrieval"
Requires-Dist: langchain_core>=0.2; extra == "retrieval"
Requires-Dist: langchain_community>=0.2; extra == "retrieval"
Requires-Dist: langchain_openai>=0.1; extra == "retrieval"
Provides-Extra: openai-compat
Requires-Dist: openai>=1.30; extra == "openai-compat"
Provides-Extra: all
Requires-Dist: reanimator_vlm[local,openai_compat,quantised,retrieval]; extra == "all"
Dynamic: license-file

# REANIMATOR: VLM-Powered Document Parsing & Synthetic Relevance Assessment

[![PyPI version](https://img.shields.io/pypi/v/reanimator-vlm.svg)](https://pypi.org/project/reanimator-vlm/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)

**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).

---

## 📦 Quick Installation

Install directly via `pip`:

```bash
pip install reanimator-vlm
```

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

```bash
pip install "reanimator-vlm[all]"
```

---

## 🚀 Quickstart Example

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

```python
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](LICENSE).
