ocragent

Official Python SDK for OCR Agent — extract structured data from documents using AI.

Installation

pip install ocragent

Quick Start

from ocragent import OcrAgent

client = OcrAgent(api_key="sk_...")

# List your agents
agents = client.agents.list()

# Extract a document
with open("invoice.pdf", "rb") as f:
    result = client.extract(agent_id=agents[0]["id"], file=f)

print(result["data"])
# {"invoice_number": "INV-001", "total_amount": 4250, "due_date": "2025-04-15"}

API

OcrAgent(api_key, ...)

client.agents

client.agents.list()
client.agents.get(agent_id)
client.agents.get_schema(agent_id)
client.agents.update_schema(agent_id, fields=[...])
client.agents.set_status(agent_id, "active" | "paused")
client.agents.delete(agent_id)
client.agents.results(agent_id, period="30d", page=1, limit=20)
client.agents.export_results(agent_id, format="csv")   # returns bytes
client.agents.stats(agent_id)

client.extract

# Single document
client.extract(agent_id, file, file_back=None, callback_url=None)

# Multiple documents
client.extract.batch(agent_id, files=[f1, f2, f3])

# Pre-upload an image
client.extract.upload_image(file)

client.jobs

client.jobs.list(status=None, page=1, limit=20)
client.jobs.get(job_id)
client.jobs.result(job_id)
client.jobs.download(job_id, format="json")  # returns bytes
client.jobs.delete(job_id)

Error Handling

from ocragent.errors import OcrAgentError, AuthError, RateLimitError

try:
    result = client.extract(agent_id="...", file=f)
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except OcrAgentError as e:
    print(e.status, e.code, e.message)

Context manager

with OcrAgent(api_key="sk_...") as client:
    agents = client.agents.list()

License

MIT © NxtwaveAI