OCR

Extract text and markdown from PDFs and images with OCRAgent

Extract text from PDFs and images with OCRAgent — pass a URL or base64 source and get markdown-ready text back.

from praisonaiagents import Agent, OCRAgent

ocr = OCRAgent()
text = ocr.read("https://arxiv.org/pdf/2201.04234")
agent = Agent(name="Reader", instructions="Summarise documents clearly.")
agent.start(f"Summarise this paper:\n\n{text[:4000]}")

The user supplies a document URL; OCR extracts text and the agent summarises it.

Source must be a URL (https://) or base64-encoded document. Local file paths are not supported. Currently only Mistral (mistral/mistral-ocr-latest) is supported.

Quick Start

1. Extract text from a PDF

   from praisonaiagents import Agent, OCRAgent
   
   ocr = OCRAgent()
   text = ocr.read("https://arxiv.org/pdf/2201.04234")
   
   agent = Agent(name="Reader", instructions="Summarise documents clearly.")
   summary = agent.start(f"Summarise this paper:\n\n{text[:4000]}")
   
2. Configure with OCRConfig

   import os
   from praisonaiagents import OCRAgent, OCRConfig
   
   config = OCRConfig(
       pages=[0, 1],
       timeout=300,
       api_key=os.getenv("MISTRAL_API_KEY"),
   )
   
   ocr = OCRAgent(ocr=config)
   result = ocr.extract("https://arxiv.org/pdf/2201.04234")
   
   for page in result.pages:
       print(f"Page {page.index}: {page.markdown[:100]}")
   
3. Async extraction

   import asyncio
   from praisonaiagents import OCRAgent
   
   async def main():
       ocr = OCRAgent()
       text = await ocr.aread("https://example.com/screenshot.png")
       print(text)
   
   asyncio.run(main())
   

How It Works

Method	Returns	Use when
read / aread	str (markdown)	You only need plain text
extract / aextract	Full result with pages	You need per-page markdown or metadata

Configuration Options

OCRAgent

Agent class reference

OCRConfig

Configuration dataclass

Option	Type	Default	Description
include_image_base64	bool	False	Include base64-encoded image bytes in the result
pages	Optional[List[int]]	None	Specific page indexes to extract (0-indexed)
image_limit	Optional[int]	None	Max images to process
timeout	int	600	Request timeout in seconds
api_base	Optional[str]	None	Override provider base URL
api_key	Optional[str]	None	Override provider API key

Common Patterns

Specific pages

from praisonaiagents import OCRAgent

ocr = OCRAgent()
result = ocr.extract("https://example.com/large.pdf", pages=[0, 1, 2])
print(result.pages[0].markdown)

Image URL

from praisonaiagents import OCRAgent

ocr = OCRAgent()
text = ocr.read("https://example.com/screenshot.png")
print(text)

Batch loop

from praisonaiagents import OCRAgent

ocr = OCRAgent()
urls = [
    "https://example.com/doc1.pdf",
    "https://example.com/doc2.pdf",
]

for url in urls:
    print(ocr.read(url)[:500])

Async concurrency

import asyncio
from praisonaiagents import OCRAgent

async def extract_all(urls):
    ocr = OCRAgent()
    tasks = [ocr.aread(url) for url in urls]
    return await asyncio.gather(*tasks)

texts = asyncio.run(extract_all(["https://example.com/a.pdf", "https://example.com/b.pdf"]))

Providers

Mistral OCR

Provider setup and model options

Best Practices

Use HTTPS URLs or base64

Local file paths are not supported — upload to a reachable URL or encode as base64 before calling OCRAgent.

Extract pages selectively for large PDFs

Use pages=[0, 1, 2] via OCRConfig or method kwargs to limit cost and latency on multi-hundred-page documents.

Tune timeout for slow documents

Default timeout is 600 seconds. Lower it for quick image OCR; raise it for large scanned PDFs.

API key precedence

Pass api_key on OCRConfig, on OCRAgent(...), or set MISTRAL_API_KEY in the environment — instance config wins over env vars.

Related

Knowledge

Index extracted text for retrieval

Toolsets

Bundle document-processing tools for agents