langchain-fastocr 0.1.0__tar.gz

langchain_fastocr-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.mypy_cache/
+.ruff_cache/
+.DS_Store

langchain_fastocr-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this package are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[semantic versioning](https://semver.org).
+
+## [0.1.0] - 2026-10-24
+
+First release. `FastOCRLoader`, a LangChain document loader for scanned PDFs and images
+(PDF, PNG, JPG, JPEG, GIF, WebP, BMP). One document per file, with `source`, `file_name`,
+`fastocr_document_id`, `pages_billed` and `status` in the metadata. `output="pdf"` also saves
+a searchable PDF beside the input. Needs `fastocr-sdk` 0.2.0 or later. API requests send the
+User-Agent `langchain-fastocr/<version>` followed by the SDK's own.

langchain_fastocr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FastOCR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_fastocr-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: langchain-fastocr
+Version: 0.1.0
+Summary: LangChain document loader 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/langchain-fastocr
+Project-URL: Changelog, https://github.com/fastocr-org/langchain-fastocr/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/fastocr-org/langchain-fastocr/issues
+Author-email: FastOCR <support@fastocr.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: document-loader,fastocr,langchain,ocr,pdf,rag,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: langchain-core>=0.3.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/langchain-fastocr/main/docs/images/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/fastocr-org/langchain-fastocr/main/docs/images/logo-light.png" alt="FastOCR" width="200">
+  </picture>
+</a>
+
+<h3>A LangChain document loader that reads scanned PDFs and images with FastOCR.</h3>
+
+<p>
+<a href="https://github.com/fastocr-org/langchain-fastocr/actions/workflows/ci.yml"><img src="https://github.com/fastocr-org/langchain-fastocr/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+<a href="https://pypi.org/project/langchain-fastocr/"><img src="https://img.shields.io/pypi/v/langchain-fastocr.svg?label=pypi" alt="PyPI"></a>
+<a href="https://pypi.org/project/langchain-fastocr/"><img src="https://img.shields.io/pypi/pyversions/langchain-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/langchain-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 langchain-fastocr
+export FASTOCR_API_KEY="your_api_key"
+```
+
+```python
+from langchain_fastocr import FastOCRLoader
+
+documents = FastOCRLoader("scanned_contract.pdf").load()
+print(documents[0].page_content)
+```
+
+Python 3.10 or newer. The distribution is `langchain-fastocr` and the import is `langchain_fastocr`.
+
+## What you get back
+
+`FastOCRLoader` returns one `Document` per file.
+
+| You get | Where |
+|---|---|
+| The text of the whole file | `page_content` |
+| 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"]` |
+
+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 loader.
+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 langchain_core.vectorstores import InMemoryVectorStore
+from langchain_fastocr import FastOCRLoader
+from langchain_openai import OpenAIEmbeddings
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+documents = FastOCRLoader("scanned_contract.pdf").load()
+chunks = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=150).split_documents(documents)
+
+store = InMemoryVectorStore.from_documents(chunks, OpenAIEmbeddings())
+for hit in store.as_retriever(search_kwargs={"k": 3}).invoke("When can the contract be terminated?"):
+    print(hit.metadata["file_name"], hit.page_content[:200])
+```
+
+Each chunk keeps its file's metadata, so answers can cite the source file. This example also needs `pip install langchain-openai langchain-text-splitters numpy` and an OpenAI key; any other embeddings class works the same way.
+
+### A folder of scans
+
+```python
+from pathlib import Path
+
+from langchain_fastocr import FastOCRLoader
+
+scans = sorted(p for p in Path("scans").iterdir() if p.suffix.lower() in {".pdf", ".png", ".jpg", ".jpeg"})
+for document in FastOCRLoader(scans).lazy_load():
+    print(document.metadata["file_name"], document.metadata["pages_billed"])
+```
+
+`lazy_load()` yields each document as soon as its file is finished. The loader runs one file at a time.
+
+### Searchable PDFs for an archive
+
+```python
+from langchain_fastocr import FastOCRLoader
+
+documents = FastOCRLoader(["invoice-001.pdf", "invoice-002.pdf"], output="pdf").load()
+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 |
+|---|---|---|
+| `file_path` | required | One path or a list of paths |
+| `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 |
+
+## Support and license
+
+Questions: support@fastocr.org. Bugs and requests: [GitHub issues](https://github.com/fastocr-org/langchain-fastocr/issues). MIT license; see [LICENSE](LICENSE).

langchain_fastocr-0.1.0/README.md

@@ -0,0 +1,133 @@
+<div align="center">
+
+<a href="https://fastocr.org">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fastocr-org/langchain-fastocr/main/docs/images/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/fastocr-org/langchain-fastocr/main/docs/images/logo-light.png" alt="FastOCR" width="200">
+  </picture>
+</a>
+
+<h3>A LangChain document loader that reads scanned PDFs and images with FastOCR.</h3>
+
+<p>
+<a href="https://github.com/fastocr-org/langchain-fastocr/actions/workflows/ci.yml"><img src="https://github.com/fastocr-org/langchain-fastocr/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+<a href="https://pypi.org/project/langchain-fastocr/"><img src="https://img.shields.io/pypi/v/langchain-fastocr.svg?label=pypi" alt="PyPI"></a>
+<a href="https://pypi.org/project/langchain-fastocr/"><img src="https://img.shields.io/pypi/pyversions/langchain-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/langchain-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 langchain-fastocr
+export FASTOCR_API_KEY="your_api_key"
+```
+
+```python
+from langchain_fastocr import FastOCRLoader
+
+documents = FastOCRLoader("scanned_contract.pdf").load()
+print(documents[0].page_content)
+```
+
+Python 3.10 or newer. The distribution is `langchain-fastocr` and the import is `langchain_fastocr`.
+
+## What you get back
+
+`FastOCRLoader` returns one `Document` per file.
+
+| You get | Where |
+|---|---|
+| The text of the whole file | `page_content` |
+| 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"]` |
+
+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 loader.
+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 langchain_core.vectorstores import InMemoryVectorStore
+from langchain_fastocr import FastOCRLoader
+from langchain_openai import OpenAIEmbeddings
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+documents = FastOCRLoader("scanned_contract.pdf").load()
+chunks = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=150).split_documents(documents)
+
+store = InMemoryVectorStore.from_documents(chunks, OpenAIEmbeddings())
+for hit in store.as_retriever(search_kwargs={"k": 3}).invoke("When can the contract be terminated?"):
+    print(hit.metadata["file_name"], hit.page_content[:200])
+```
+
+Each chunk keeps its file's metadata, so answers can cite the source file. This example also needs `pip install langchain-openai langchain-text-splitters numpy` and an OpenAI key; any other embeddings class works the same way.
+
+### A folder of scans
+
+```python
+from pathlib import Path
+
+from langchain_fastocr import FastOCRLoader
+
+scans = sorted(p for p in Path("scans").iterdir() if p.suffix.lower() in {".pdf", ".png", ".jpg", ".jpeg"})
+for document in FastOCRLoader(scans).lazy_load():
+    print(document.metadata["file_name"], document.metadata["pages_billed"])
+```
+
+`lazy_load()` yields each document as soon as its file is finished. The loader runs one file at a time.
+
+### Searchable PDFs for an archive
+
+```python
+from langchain_fastocr import FastOCRLoader
+
+documents = FastOCRLoader(["invoice-001.pdf", "invoice-002.pdf"], output="pdf").load()
+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 |
+|---|---|---|
+| `file_path` | required | One path or a list of paths |
+| `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 |
+
+## Support and license
+
+Questions: support@fastocr.org. Bugs and requests: [GitHub issues](https://github.com/fastocr-org/langchain-fastocr/issues). MIT license; see [LICENSE](LICENSE).

langchain_fastocr-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-fastocr"
+dynamic = ["version"]
+description = "LangChain document loader for the FastOCR Document OCR API: load scanned PDFs and images as text, in 100+ languages."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["langchain", "document-loader", "ocr", "pdf", "scanned-pdf", "rag", "fastocr"]
+authors = [
+    { name = "FastOCR", email = "support@fastocr.org" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastocr-sdk>=0.2.0,<0.3",
+    "langchain-core>=0.3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "respx>=0.21.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://fastocr.org"
+Documentation = "https://fastocr.org/docs"
+Repository = "https://github.com/fastocr-org/langchain-fastocr"
+Changelog = "https://github.com/fastocr-org/langchain-fastocr/blob/main/CHANGELOG.md"
+Issues = "https://github.com/fastocr-org/langchain-fastocr/issues"
+
+[tool.hatch.version]
+path = "src/langchain_fastocr/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_fastocr"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "docs", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

langchain_fastocr-0.1.0/src/langchain_fastocr/__init__.py

@@ -0,0 +1,6 @@
+"""LangChain document loader for the FastOCR Document OCR API."""
+
+from ._version import __version__
+from .loader import FastOCRLoader
+
+__all__ = ["__version__", "FastOCRLoader"]

langchain_fastocr-0.1.0/src/langchain_fastocr/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

langchain_fastocr-0.1.0/src/langchain_fastocr/loader.py

@@ -0,0 +1,90 @@
+"""Document loader that reads scanned PDFs and images with FastOCR."""
+import logging
+from pathlib import Path
+from typing import Any, Dict, Iterator, Literal, Optional, Sequence, Union
+
+from fastocr_sdk import FastOCR
+from langchain_core.document_loaders import BaseLoader
+from langchain_core.documents import Document
+
+from ._version import __version__
+
+logger = logging.getLogger(__name__)
+
+USER_AGENT = f"langchain-fastocr/{__version__}"
+SUPPORTED_SUFFIXES = (".pdf", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp")
+
+PathLike = Union[str, Path]
+
+
+class FastOCRLoader(BaseLoader):
+    """Load scanned PDFs and images as LangChain documents, one document per file.
+
+    Args:
+        file_path: One path or a list of paths (PDF, PNG, JPG, JPEG, GIF, WebP or BMP).
+        api_key: A FastOCR API key. Defaults to the FASTOCR_API_KEY environment variable.
+        output: "text" returns the text. "pdf" also saves a searchable PDF beside each
+            input file as <name>.searchable.pdf and records its path in the metadata.
+        base_url: Overrides the API address. Defaults to FASTOCR_BASE_URL, then https://api.fastocr.org.
+        timeout: Seconds to wait for each document to finish.
+
+    Each document's metadata has source, file_name, fastocr_document_id, pages_billed and
+    status. A "partial" status means the account ran out of API pages partway: the text
+    covers only the processed pages and a warning is logged. A failed document raises the
+    SDK's DocumentFailedError.
+    """
+
+    def __init__(
+        self,
+        file_path: Union[PathLike, Sequence[PathLike]],
+        *,
+        api_key: Optional[str] = None,
+        output: Literal["text", "pdf"] = "text",
+        base_url: Optional[str] = None,
+        timeout: float = 300.0,
+    ) -> None:
+        if output not in ("text", "pdf"):
+            raise ValueError("output must be 'text' or 'pdf'")
+        paths = [file_path] if isinstance(file_path, (str, Path)) else list(file_path)
+        self.paths = [Path(path).expanduser() for path in paths]
+        for path in self.paths:
+            if path.suffix.lower() not in SUPPORTED_SUFFIXES:
+                raise ValueError(f"{path.name}: FastOCR accepts PDF, PNG, JPG, JPEG, GIF, WebP and BMP files")
+        self.api_key = api_key
+        self.output = output
+        self.base_url = base_url
+        self.timeout = timeout
+
+    def lazy_load(self) -> Iterator[Document]:
+        with self._client() as client:
+            for path in self.paths:
+                yield self._load_one(client, path)
+
+    def _client(self) -> FastOCR:
+        client = FastOCR(api_key=self.api_key, base_url=self.base_url)
+        sdk_agent = client._http.headers.get("User-Agent", "")
+        client._http.headers["User-Agent"] = f"{USER_AGENT} {sdk_agent}".strip()
+        return client
+
+    def _load_one(self, client: FastOCR, path: Path) -> Document:
+        job = client.documents.process(path, timeout=self.timeout)
+        if job.is_partial:
+            logger.warning(
+                "%s: only %s of %s pages were processed because the account ran out of API pages",
+                path.name,
+                job.pages_billed,
+                job.pages_total,
+            )
+        metadata: Dict[str, Any] = {
+            "source": str(path),
+            "file_name": path.name,
+            "fastocr_document_id": job.id,
+            "pages_billed": job.pages_billed,
+            "status": job.status,
+        }
+        text = client.documents.get_text(job.id)
+        if self.output == "pdf":
+            destination = path.with_name(f"{path.stem}.searchable.pdf")
+            client.documents.download_searchable_pdf(job.id, destination)
+            metadata["searchable_pdf_path"] = str(destination)
+        return Document(page_content=text, metadata=metadata)

langchain_fastocr-0.1.0/tests/test_loader.py

@@ -0,0 +1,172 @@
+"""The loader end to end, with the FastOCR API mocked at the HTTP layer."""
+import logging
+
+import httpx
+import pytest
+import respx
+from fastocr_sdk import AuthenticationError, DocumentFailedError
+from langchain_core.document_loaders import BaseLoader
+
+from langchain_fastocr import FastOCRLoader, __version__
+
+BASE_URL = "https://api.test"
+UPLOAD_URL = "https://s3.test/uploads/original?X-Amz-Signature=sig"
+TEXT_URL = "https://s3.test/out/ocr-text.txt?X-Amz-Signature=sig"
+PDF_URL = "https://s3.test/out/searchable.pdf?X-Amz-Signature=sig"
+
+
+def job(doc_id, status="completed", pages=2, total=2):
+    return {
+        "id": doc_id,
+        "status": status,
+        "pages_billed": pages,
+        "pages_total": total,
+        "outputs": {"text": {"available": True}, "pdf": {"available": True}},
+    }
+
+
+@pytest.fixture
+def api():
+    with respx.mock(assert_all_called=False) as router:
+        yield router
+
+
+def mock_document(api, doc_id, finished, text):
+    api.put(UPLOAD_URL).respond(200)
+    api.post(f"{BASE_URL}/v1/documents/{doc_id}/start").respond(202, json={"status": "processing"})
+    api.get(f"{BASE_URL}/v1/documents/{doc_id}").respond(200, json=finished)
+    api.get(f"{BASE_URL}/v1/documents/{doc_id}/output", params={"format": "text"}).respond(
+        200, json={"format": "text", "url": TEXT_URL + doc_id, "expires_at": "x"}
+    )
+    api.get(f"{BASE_URL}/v1/documents/{doc_id}/output", params={"format": "pdf"}).respond(
+        200, json={"format": "pdf", "url": PDF_URL, "expires_at": "x"}
+    )
+    api.get(TEXT_URL + doc_id).respond(200, content=text.encode("utf-8"))
+
+
+def mock_creates(api, *doc_ids):
+    responses = [
+        httpx.Response(201, json={"id": doc_id, "status": "awaiting_upload", "upload_url": UPLOAD_URL, "expires_at": "x"})
+        for doc_id in doc_ids
+    ]
+    return api.post(f"{BASE_URL}/v1/documents").mock(side_effect=responses)
+
+
+def loader(paths, **options):
+    return FastOCRLoader(paths, api_key="fok_test", base_url=BASE_URL, **options)
+
+
+def test_is_a_langchain_loader():
+    assert issubclass(FastOCRLoader, BaseLoader)
+
+
+def test_loads_an_image(api, tmp_path):
+    image = tmp_path / "receipt.png"
+    image.write_bytes(b"\x89PNG test")
+    mock_creates(api, "doc_1")
+    mock_document(api, "doc_1", job("doc_1", pages=1, total=1), "مرحبا بالعالم")
+
+    [document] = loader(image).load()
+
+    assert document.page_content == "مرحبا بالعالم"
+    assert document.metadata == {
+        "source": str(image),
+        "file_name": "receipt.png",
+        "fastocr_document_id": "doc_1",
+        "pages_billed": 1,
+        "status": "completed",
+    }
+
+
+def test_loads_a_list_of_files_one_document_each(api, tmp_path):
+    first, second = tmp_path / "a.pdf", tmp_path / "b.PDF"
+    first.write_bytes(b"%PDF-1.4 a")
+    second.write_bytes(b"%PDF-1.4 b")
+    mock_creates(api, "doc_a", "doc_b")
+    mock_document(api, "doc_a", job("doc_a"), "text of a")
+    mock_document(api, "doc_b", job("doc_b"), "text of b")
+
+    documents = loader([str(first), second]).load()
+
+    assert [d.page_content for d in documents] == ["text of a", "text of b"]
+    assert [d.metadata["file_name"] for d in documents] == ["a.pdf", "b.PDF"]
+
+
+def test_pdf_output_saves_the_searchable_pdf_beside_the_input(api, tmp_path):
+    scan = tmp_path / "scan.v2.pdf"
+    scan.write_bytes(b"%PDF-1.4 scan")
+    mock_creates(api, "doc_1")
+    mock_document(api, "doc_1", job("doc_1"), "page text")
+    api.get(PDF_URL).respond(200, content=b"%PDF searchable")
+
+    [document] = loader(scan, output="pdf").load()
+
+    saved = tmp_path / "scan.v2.searchable.pdf"
+    assert saved.read_bytes() == b"%PDF searchable"
+    assert document.metadata["searchable_pdf_path"] == str(saved)
+    assert document.page_content == "page text"
+
+
+def test_partial_result_keeps_the_text_and_logs_a_warning(api, tmp_path, caplog):
+    scan = tmp_path / "big.pdf"
+    scan.write_bytes(b"%PDF-1.4 big")
+    mock_creates(api, "doc_1")
+    mock_document(api, "doc_1", job("doc_1", status="partial", pages=3, total=10), "first three pages")
+
+    with caplog.at_level(logging.WARNING, logger="langchain_fastocr"):
+        [document] = loader(scan).load()
+
+    assert document.page_content == "first three pages"
+    assert document.metadata["status"] == "partial"
+    assert "3 of 10 pages" in caplog.text
+
+
+def test_failed_document_raises_the_sdk_error(api, tmp_path):
+    scan = tmp_path / "bad.pdf"
+    scan.write_bytes(b"%PDF-1.4 bad")
+    mock_creates(api, "doc_1")
+    failed = {"id": "doc_1", "status": "failed", "error": {"type": "x", "code": "buy_pages", "message": "No pages", "retryable": False}}
+    mock_document(api, "doc_1", failed, "")
+
+    with pytest.raises(DocumentFailedError) as raised:
+        loader(scan).load()
+
+    assert raised.value.out_of_pages
+
+
+def test_rejected_key_raises_authentication_error(api, tmp_path):
+    scan = tmp_path / "scan.pdf"
+    scan.write_bytes(b"%PDF-1.4 scan")
+    api.post(f"{BASE_URL}/v1/documents").respond(401, json={"message": "Unauthorized"})
+
+    with pytest.raises(AuthenticationError):
+        loader(scan).load()
+
+
+def test_requests_name_this_package_ahead_of_the_sdk(api, tmp_path):
+    scan = tmp_path / "scan.pdf"
+    scan.write_bytes(b"%PDF-1.4 scan")
+    create = mock_creates(api, "doc_1")
+    mock_document(api, "doc_1", job("doc_1"), "text")
+
+    loader(scan).load()
+
+    agent = create.calls[0].request.headers["User-Agent"]
+    assert agent.startswith(f"langchain-fastocr/{__version__} fastocr-python/")
+
+
+def test_unsupported_file_type_is_rejected_before_any_request(tmp_path):
+    with pytest.raises(ValueError, match="notes.docx"):
+        FastOCRLoader(tmp_path / "notes.docx", api_key="fok_test")
+
+
+def test_api_key_defaults_to_the_environment(api, tmp_path, monkeypatch):
+    scan = tmp_path / "scan.pdf"
+    scan.write_bytes(b"%PDF-1.4 scan")
+    monkeypatch.setenv("FASTOCR_API_KEY", "fok_from_env")
+    create = mock_creates(api, "doc_1")
+    mock_document(api, "doc_1", job("doc_1"), "text")
+
+    FastOCRLoader(scan, base_url=BASE_URL).load()
+
+    assert create.calls[0].request.headers["Authorization"] == "Bearer fok_from_env"