Metadata-Version: 2.5
Name: llama-index-readers-fastocr
Version: 0.1.0
Summary: LlamaIndex reader for the FastOCR Document OCR API: load scanned PDFs and images as text, in 100+ languages.
Project-URL: Homepage, https://fastocr.org
Project-URL: Documentation, https://fastocr.org/docs
Project-URL: Repository, https://github.com/fastocr-org/llama-index-readers-fastocr
Project-URL: Changelog, https://github.com/fastocr-org/llama-index-readers-fastocr/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/fastocr-org/llama-index-readers-fastocr/issues
Author-email: FastOCR <support@fastocr.org>
License-Expression: MIT
License-File: LICENSE
Keywords: fastocr,llama-index,llamahub,ocr,pdf,rag,reader,scanned-pdf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastocr-sdk<0.3,>=0.2.0
Requires-Dist: llama-index-core<0.15,>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<a href="https://fastocr.org">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fastocr-org/llama-index-readers-fastocr/main/docs/images/logo-dark.png">
    <img src="https://raw.githubusercontent.com/fastocr-org/llama-index-readers-fastocr/main/docs/images/logo-light.png" alt="FastOCR" width="200">
  </picture>
</a>

<h3>A LlamaIndex reader that reads scanned PDFs and images with FastOCR and returns their text.</h3>

<p>
<a href="https://github.com/fastocr-org/llama-index-readers-fastocr/actions/workflows/ci.yml"><img src="https://github.com/fastocr-org/llama-index-readers-fastocr/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://pypi.org/project/llama-index-readers-fastocr/"><img src="https://img.shields.io/pypi/v/llama-index-readers-fastocr.svg?label=pypi" alt="PyPI"></a>
<a href="https://pypi.org/project/llama-index-readers-fastocr/"><img src="https://img.shields.io/pypi/pyversions/llama-index-readers-fastocr.svg" alt="Python"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
</p>

<p>
<a href="https://fastocr.org">Website</a> ·
<a href="https://fastocr.org/docs">Docs</a> ·
<a href="https://fastocr.org/developers/keys">Get an API key</a>
</p>

<img src="https://raw.githubusercontent.com/fastocr-org/llama-index-readers-fastocr/main/docs/images/readme-hero.gif" alt="FastOCR reads a scanned page in English, Arabic and Hindi and returns its text" width="800">

</div>

## Quickstart

```bash
pip install llama-index-readers-fastocr
export FASTOCR_API_KEY="your_api_key"
```

```python
from llama_index.readers.fastocr import FastOCRReader

documents = FastOCRReader().load_data("scanned_contract.pdf")
print(documents[0].text)
```

Python 3.10 or newer. The distribution is `llama-index-readers-fastocr` and the import is `llama_index.readers.fastocr`.

## What you get back

`FastOCRReader.load_data` returns one `Document` per file.

| You get | Where |
|---|---|
| The text of the whole file | `text` |
| The file's path and name | `metadata["source"]`, `metadata["file_name"]` |
| The FastOCR document id | `metadata["fastocr_document_id"]` |
| Pages billed | `metadata["pages_billed"]` |
| `completed` or `partial` | `metadata["status"]` |
| A searchable PDF, with `output="pdf"` | saved as `<name>.searchable.pdf` beside the input; its path is in `metadata["searchable_pdf_path"]` |

The FastOCR keys (`fastocr_document_id`, `pages_billed`, `status`, `searchable_pdf_path`) are left out of the text that embedding models and LLMs see. Pass `extra_info={...}` to `load_data` to add your own metadata.

If the account runs out of API pages partway through a file, you still get the text of the pages that were processed, with `status` set to `partial` and a warning in the log. A document that fails raises the error from [`fastocr-sdk`](https://pypi.org/project/fastocr-sdk/) with its message and code.

## Languages and files

- 100+ languages, detected automatically. No language setting is needed.
- PDF files up to 1 GiB, and PNG, JPG, JPEG, GIF, WebP and BMP images up to 20 MiB. An image counts as one page.

## Get an API key and pages

Any signed-in FastOCR account can create an API key and start right away.

1. Sign in and create an API key in the [developer console](https://fastocr.org/developers/keys). You accept the [API terms](https://fastocr.org/api-terms) with your first key.
2. Set the key as `FASTOCR_API_KEY`, or pass `api_key=` to the reader.
3. When you need more than the free pages, buy a prepaid API page pack by card in the [developer console](https://fastocr.org/developers/keys#buy-api-pages).

Each account gets 50 free document pages per month.

## Examples

### RAG over scanned PDFs

```python
from llama_index.core import VectorStoreIndex
from llama_index.readers.fastocr import FastOCRReader

documents = FastOCRReader().load_data("scanned_contract.pdf")
index = VectorStoreIndex.from_documents(documents)
print(index.as_query_engine().query("When can the contract be terminated?"))
```

This example uses LlamaIndex's default OpenAI models, so it needs `OPENAI_API_KEY`. Set another embedding model and LLM in `Settings` to use a different provider.

### A folder of scans

```python
from pathlib import Path

from llama_index.readers.fastocr import FastOCRReader

scans = sorted(p for p in Path("scans").iterdir() if p.suffix.lower() in {".pdf", ".png", ".jpg", ".jpeg"})
for document in FastOCRReader().load_data(scans):
    print(document.metadata["file_name"], document.metadata["pages_billed"])
```

The reader runs one file at a time and returns when all files are done.

### Use it with SimpleDirectoryReader

```python
from llama_index.core import SimpleDirectoryReader
from llama_index.readers.fastocr import FastOCRReader

documents = SimpleDirectoryReader(
    "scans",
    file_extractor={".pdf": FastOCRReader(), ".png": FastOCRReader(), ".jpg": FastOCRReader()},
).load_data()
```

### Searchable PDFs for an archive

```python
from llama_index.readers.fastocr import FastOCRReader

documents = FastOCRReader(output="pdf").load_data(["invoice-001.pdf", "invoice-002.pdf"])
for document in documents:
    print(document.metadata["searchable_pdf_path"])
```

Each searchable PDF is saved beside its input, as `invoice-001.searchable.pdf`. An existing file with that name is replaced. Index the text and keep the PDF.

## Options

| Argument | Default | Meaning |
|---|---|---|
| `api_key` | `FASTOCR_API_KEY` | Your FastOCR API key |
| `output` | `"text"` | `"pdf"` also saves a searchable PDF beside each input |
| `base_url` | `FASTOCR_BASE_URL`, then `https://api.fastocr.org` | API address |
| `timeout` | `300.0` | Seconds to wait for each document |

`load_data(file_path, extra_info=None)` takes one path or a list of paths.

## Support and license

Questions: support@fastocr.org. Bugs and requests: [GitHub issues](https://github.com/fastocr-org/llama-index-readers-fastocr/issues). MIT license; see [LICENSE](LICENSE).
