orves 0.1.0a1

Official Python SDK for Orves Parse — turn PDFs into clean, structured Markdown through the Orves API.

Orves Python SDK

Official Python SDK for Orves Parse — turn PDFs into clean, structured Markdown through the Orves API.

Alpha release. The SDK exposes exactly what the API serves today: Parse (PDF in, Markdown out, with job status and per-page billing metadata). The surface will grow as new capabilities ship — nothing here is a placeholder.

Installation

pip install orves

Quickstart

export ORVES_API_KEY="orves_live_..."   # from the Orves dashboard

from orves import Orves

client = Orves()

document = client.parse("report.pdf")
print(document.markdown)
print(document.page_count, document.credits_used)

Explicit control

job = client.parse.submit("report.pdf")
print(job.id, job.status)          # prs_..., queued

document = job.wait(timeout=600)   # poll until completed/failed

Fetch a job later, from anywhere:

job = client.parses.retrieve("prs_...")
if job.done:
    document = job.result()

Async

from orves import AsyncOrves

client = AsyncOrves()
job = await client.parse.submit("report.pdf")
document = await job.wait()

Errors

All API errors derive from OrvesError and carry code, request_id (citable in support), status_code and retryable:

from orves import Orves, RateLimitError, BillingError, ParseFailedError

try:
    document = client.parse("report.pdf")
except RateLimitError as e:
    print("daily limit reached, retry after", e.retry_after, "seconds")
except BillingError:
    print("workspace has no credits")
except ParseFailedError as e:
    print("parse failed:", e.code, e.request_id)   # failed jobs are never charged

Retries with exponential backoff and Retry-After support are built in for transient failures. Submissions carry an automatic Idempotency-Key, so a retried upload never creates a duplicate job.

Limits (pilot)

• PDF only · max 100 MB per file · max 5000 pages per job
• 100 parses per day per workspace
• Credits are reserved on submit and settled to the actual page count; failed jobs are never charged.

Configuration

Setting	Default	Override
API key	ORVES_API_KEY env var	Orves(api_key=...)
Base URL	https://api.orves.ai	Orves(base_url=...) / ORVES_BASE_URL
Timeout	60 s per request	Orves(timeout=...)
Retries	3	Orves(max_retries=...)

The API contract lives at specs/public/openapi.yaml in the Orves repository and is enforced against the live gateway by automated contract tests.