langchain-fastocr 0.1.0__py3-none-any.whl

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/_version.py

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

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+langchain_fastocr/__init__.py,sha256=T2EE59oU-yfxXBxxanzHrfN2MnDum88kkIu2fEkN4tA,179
+langchain_fastocr/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+langchain_fastocr/loader.py,sha256=_iUMkk-CQUmjvLi0jR30fHnNoSLOZCr5_sUVX_QObs0,3801
+langchain_fastocr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_fastocr-0.1.0.dist-info/METADATA,sha256=lH_f3FkbKUgT2St0eusvK6BiAisBtd2fePihm4d6W0w,7355
+langchain_fastocr-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+langchain_fastocr-0.1.0.dist-info/licenses/LICENSE,sha256=iAEJvhOAbbRmyZP6iiDxfCJrifPj_5COWm4eVHmbOQ8,1064
+langchain_fastocr-0.1.0.dist-info/RECORD,,

langchain_fastocr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_fastocr-0.1.0.dist-info/licenses/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.