Metadata-Version: 2.4
Name: rag-pdf-highlighter
Version: 0.1.0
Summary: Highlight text chunks in PDFs – a FastAPI microservice for RAG pipelines
Author-email: Muhammad Salman Ahmad <salman.ahmad@ripeseed.io>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MuhammadSalmanAhmad/rag-pdf-highlighter
Project-URL: Repository, https://github.com/MuhammadSalmanAhmad/rag-pdf-highlighter
Project-URL: Issues, https://github.com/MuhammadSalmanAhmad/rag-pdf-highlighter/issues
Keywords: pdf,highlight,rag,langchain,fastapi,pymupdf
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn[standard]>=0.20
Requires-Dist: httpx>=0.24
Requires-Dist: langchain-core>=0.1
Requires-Dist: pymupdf>=1.23
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# RAG PDF Highlighter

Highlight text chunks inside PDF documents — built for RAG pipelines.

Given a PDF URL and a list of text chunks (with page numbers), this service locates each chunk in the PDF and returns an annotated copy with highlights applied.

## Features

- **3-tier text matching** — exact → sentence → collapsed-whitespace fallback
- **Async PDF download** — non-blocking I/O via `httpx`
- **Stateless** — temp files are cleaned up after every request
- **Docker-ready** — single-command container deployment
- **Library-friendly** — core logic raises plain Python exceptions, no FastAPI dependency required

## Installation

```bash
pip install callisto-pdf-highlighter
```

Or install from source:

```bash
git clone https://github.com/RipeSeed/calli-pdf-highlighter-.git
cd calli-pdf-highlighter-
pip install -e ".[dev]"
```

## Quick Start

### As a microservice

```bash
uvicorn rag_pdf_highlighter.main:app --host 0.0.0.0 --port 8000
```

Then send a POST request:

```bash
curl -X POST http://localhost:8000/highlight \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/report.pdf",
    "documents": [
      {
        "page_content": "Text to highlight in the PDF",
        "metadata": {"page": 0}
      }
    ]
  }' \
  --output highlighted.pdf
```

### With Docker

```bash
docker build -t rag-pdf-highlighter .
docker run -p 8000:8000 rag-pdf-highlighter
```

### As a library

```python
from langchain_core.documents import Document
from rag_pdf_highlighter.utils.pdf_helpers import highlight_chunks_in_pdf

documents = [
    Document(page_content="Text to find", metadata={"page": 0}),
]

output_path = highlight_chunks_in_pdf(
    pdf_path="./report.pdf",
    documents=documents,
)
print(f"Highlighted PDF saved to: {output_path}")
```

## API Reference

### `GET /`

Health check endpoint.

### `POST /highlight`

| Field | Type | Description |
|-------|------|-------------|
| `pdf_url` | `string` | URL of the PDF to highlight |
| `documents` | `array` | List of `{page_content, metadata}` objects |
| `documents[].page_content` | `string` | The text chunk to locate and highlight |
| `documents[].metadata.page` | `int` | Zero-indexed page number |

**Returns:** The highlighted PDF file (`application/pdf`).

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ test/
```

## License

[MIT](LICENSE.txt)
