#!/usr/bin/env python3 """DOCSAID first-call example. Python 3.12; install examples/requirements.txt. new prepares a local job; send submits it once; retry explicitly reuses it; inspect draws returned coordinates or prints MRZ lines. No automatic retries, redirects, credential files or server-side recovery of recognition output. """ import argparse import getpass import hashlib import io import json import math import os import re import sys import uuid from datetime import UTC, datetime from pathlib import Path import requests from PIL import Image, ImageDraw, ImageOps VERSIONS = { "docaligner": "docaligner-1.1.1-fastvit-sa24-7f9f5a89", "mrzscanner": "mrzscanner-1.0.7-det20250222-rec20250221", } ORIGINS = ("https://docsaid.org", "https://beta.docsaid.org") MAX_BYTES = 768 * 1024 Image.MAX_IMAGE_PIXELS = 40_000_000 def write_new(path: Path, data: bytes) -> None: """Never replace an existing input, operation or result.""" descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) with os.fdopen(descriptor, "wb") as output: output.write(data) def json_bytes(value: object) -> bytes: return (json.dumps(value, ensure_ascii=False, indent=2) + "\n").encode("utf-8") def prepare_image(content: bytes, already_prepared: bool = False) -> tuple[bytes, int, int]: if not content or len(content) > 10 * 1024 * 1024: raise ValueError("Choose a JPEG, PNG or WebP file up to 10 MiB.") with Image.open(io.BytesIO(content)) as source: if source.format not in ("JPEG", "PNG", "WEBP") or getattr(source, "n_frames", 1) != 1: raise ValueError("Use one still JPEG, PNG or WebP image.") if source.width * source.height > 40_000_000: raise ValueError("The original image must have at most 40 million pixels.") if already_prepared: if source.format != "JPEG" or len(content) > MAX_BYTES or source.width * source.height > 4_000_000 or max(source.size) > 4096: raise ValueError("--prepared requires a JPEG within the API limits, such as the Demo input download.") if source.getexif().get(274, 1) != 1: raise ValueError("The JPEG still has orientation metadata. Omit --prepared to normalize it first.") source.load() return content, source.width, source.height oriented = ImageOps.exif_transpose(source).convert("RGBA") flattened = Image.new("RGBA", oriented.size, "white") flattened.alpha_composite(oriented) image = flattened.convert("RGB") scale = min(1, 1600 / max(image.size)) size = tuple(max(1, math.floor(side * scale + .5)) for side in image.size) if size != image.size: image = image.resize(size, Image.Resampling.LANCZOS) for quality in (92, 80, 65, 45, 25): output = io.BytesIO() image.save(output, "JPEG", quality=quality, optimize=False, subsampling=2) if output.tell() <= MAX_BYTES: return output.getvalue(), image.width, image.height raise ValueError("Compression did not reach 768 KiB. Choose a smaller or simpler image.") def fingerprint(job: dict) -> str: fields = {key: job[key] for key in ("model", "version", "origin", "operation_id", "image_sha256", "options")} return hashlib.sha256(json.dumps(fields, sort_keys=True).encode()).hexdigest() def new_job(args: argparse.Namespace) -> None: if args.image.stat().st_size > 10 * 1024 * 1024: raise ValueError("Choose an image up to 10 MiB.") content = args.image.read_bytes() image, width, height = prepare_image(content, args.prepared) options = {"do_center_crop": args.center_crop} if args.model == "mrzscanner": options.update(do_doc_align=args.doc_align, do_postprocess=not args.raw_mrz) elif args.doc_align or args.raw_mrz: raise ValueError("--doc-align and --raw-mrz apply to MRZScanner only.") job = { "format": 1, "model": args.model, "version": VERSIONS[args.model], "origin": args.origin, "operation_id": str(uuid.uuid4()), "options": options, "image_sha256": hashlib.sha256(image).hexdigest(), "width": width, "height": height, } job["request_fingerprint"] = fingerprint(job) args.job.mkdir(mode=0o700) # An existing folder is never reused for a new job. write_new(args.job / "input.jpg", image) write_new(args.job / "job.json", json_bytes(job)) print(f"Prepared {args.job / 'input.jpg'}: {width} x {height}, {len(image)} bytes.") print(f"Operation ID: {job['operation_id']}") print("Review the prepared image, then use send. Keep this folder to inspect or recover this job.") def load_job(directory: Path) -> tuple[dict, bytes]: path = directory / "job.json" if path.stat().st_size > 16384: raise ValueError("Invalid job manifest.") job = json.loads(path.read_text(encoding="utf-8")) if not isinstance(job, dict) or job.get("format") != 1 or job.get("model") not in VERSIONS or job.get("origin") not in ORIGINS: raise ValueError("Invalid job manifest or unsupported origin.") if not isinstance(job.get("operation_id"), str) or not re.fullmatch(r"[0-9a-f-]{36}", job["operation_id"]): raise ValueError("Invalid operation ID.") expected = {"do_center_crop"} | ({"do_doc_align", "do_postprocess"} if job["model"] == "mrzscanner" else set()) if not isinstance(job.get("options"), dict) or set(job["options"]) != expected or any(type(value) is not bool for value in job["options"].values()): raise ValueError("Invalid prediction options.") if not isinstance(job.get("version"), str) or not re.fullmatch(r"[a-z0-9.-]{1,100}", job["version"]): raise ValueError("Invalid version.") if job.get("request_fingerprint") != fingerprint(job): raise ValueError("The job changed. Prepare a new job for different inputs or options.") image_path = directory / "input.jpg" if image_path.stat().st_size > MAX_BYTES: raise ValueError("The prepared input changed or exceeds the API limit.") image = image_path.read_bytes() if hashlib.sha256(image).hexdigest() != job.get("image_sha256"): raise ValueError("The prepared input changed. Prepare a new job; do not retry this one.") return job, image def send_job(directory: Path, retry: bool = False, session: requests.Session | None = None) -> int: job, image = load_job(directory) lock = directory / "send.lock" try: write_new(lock, json_bytes({"pid": os.getpid(), "started_at": datetime.now(UTC).isoformat()})) except FileExistsError: raise ValueError("A send may still be active. If it was interrupted, confirm it has stopped, check the operation in Console, then remove send.lock before an explicit retry.") from None client = session or requests.Session() try: attempts = directory / "attempts" attempts.mkdir(mode=0o700, exist_ok=True) previous = sorted(attempts.iterdir()) if previous and not retry: raise ValueError("This job was already submitted. Inspect it or explicitly use retry after checking Console.") if retry and not previous: raise ValueError("This is an unsent job. Use send for its first submission.") for path in previous: receipt = path / "receipt.json" if receipt.exists() and json.loads(receipt.read_text()).get("http_status") == 200: if (path / "response.json").exists(): raise ValueError("A successful response is already saved. Use inspect; no further request was sent.") raise ValueError("The server returned 200 but the body was lost. Check the operation in Console; a new job explicitly recalculates the result.") token = os.environ.get("DOCSAID_API_KEY") or getpass.getpass("DOCSAID API key (hidden, not saved): ") if not re.fullmatch(r"ds_beta_[A-Za-z0-9_-]{43}", token): raise ValueError("Enter a DOCSAID product API key. It will not be saved in the job folder.") attempt = attempts / (datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ") + "-" + uuid.uuid4().hex[:8]) attempt.mkdir(mode=0o700) write_new(attempt / "started.json", json_bytes({"operation_id": job["operation_id"], "started_at": datetime.now(UTC).isoformat()})) receipt = {"operation_id": job["operation_id"], "http_status": None, "request_id": None, "error_code": None, "retry_after": None} try: with client.post( f"{job['origin']}/api/v1/models/{job['model']}/predict", headers={"Authorization": f"Bearer {token}", "Idempotency-Key": job["operation_id"]}, data={"model_version": job["version"], **{name: str(value).lower() for name, value in job["options"].items()}}, files={"file": ("input.jpg", image, "image/jpeg")}, timeout=(10, 30), allow_redirects=False, stream=True, ) as response: receipt["http_status"] = response.status_code for field, header, pattern in (("request_id", "X-Request-ID", r"[0-9a-f-]{36}"), ("error_code", "X-Error-Code", r"[a-z][a-z0-9_]{0,63}"), ("retry_after", "Retry-After", r"[0-9]{1,5}")): value = response.headers.get(header, "") if re.fullmatch(pattern, value): receipt[field] = value body = bytearray() for chunk in response.iter_content(16384): body.extend(chunk) if len(body) > 1024 * 1024: raise ValueError("Response exceeds the example client's 1 MiB limit.") write_new(attempt / "response.json", bytes(body)) except (requests.RequestException, ValueError) as error: receipt["transport_error"] = type(error).__name__ write_new(attempt / "receipt.json", json_bytes(receipt)) print("Response incomplete. No automatic retry. Check this operation ID in Console before proceeding.") print(f"Operation ID: {job['operation_id']}\nLocal receipt: {attempt / 'receipt.json'}") return 2 write_new(attempt / "receipt.json", json_bytes(receipt)) print(f"HTTP {receipt['http_status']} | Request ID: {receipt['request_id'] or 'unavailable'} | Reason: {receipt['error_code'] or 'unavailable'}") print(f"Response: {attempt / 'response.json'}\nReceipt: {attempt / 'receipt.json'}") if receipt["retry_after"]: print(f"Retry-After: {receipt['retry_after']} seconds; no automatic retry.") if receipt["http_status"] == 200: print("Use inspect to view the result. Keep the local response; the server does not store recognition output.") return 0 print(f"Check operation {job['operation_id']} in Console. A new job means a new calculation; retry keeps the original input and ID.") return 1 finally: lock.unlink() if session is None: client.close() def inspect_job(directory: Path) -> None: job, image = load_job(directory) attempts = sorted((directory / "attempts").glob("*/receipt.json"), reverse=True) success = next((path for path in attempts if json.loads(path.read_text()).get("http_status") == 200 and (path.parent / "response.json").exists()), None) if not success: raise ValueError(f"No complete successful response saved. Check operation {job['operation_id']} in Console.") result = json.loads((success.parent / "response.json").read_text(encoding="utf-8")) if not isinstance(result, dict) or result.get("model") != job["model"] or result.get("model_version") != job["version"] or result.get("image_width") != job["width"] or result.get("image_height") != job["height"]: raise ValueError("Response does not match this job. Review the saved JSON before using it.") polygon = result.get("polygon" if job["model"] == "docaligner" else "mrz_polygon") if not isinstance(polygon, list) or len(polygon) != 4 or any(not isinstance(point, list) or len(point) != 2 or any(type(value) not in (int, float) or not math.isfinite(value) or abs(value) >= 16384 for value in point) for point in polygon): raise ValueError("The response has no valid four-corner polygon. Review the saved JSON.") with Image.open(io.BytesIO(image)) as source: output = source.convert("RGB") draw = ImageDraw.Draw(output) points = [tuple(point) for point in polygon] draw.line([*points, points[0]], fill="#ff007a", width=max(3, output.width // 300)) for index, point in enumerate(points, 1): draw.text(point, str(index), fill="white", stroke_fill="black", stroke_width=2) buffer = io.BytesIO() output.save(buffer, "PNG") overlay = success.parent / "overlay.png" if not overlay.exists(): write_new(overlay, buffer.getvalue()) print(f"Overlay: {overlay}\nCoordinates refer to input.jpg ({job['width']} x {job['height']} pixels).") if job["model"] == "mrzscanner": lines = result.get("mrz_texts") if not isinstance(lines, list) or not 1 <= len(lines) <= 3 or any(not isinstance(line, str) or not re.fullmatch(r"[A-Z0-9<]{1,64}", line) for line in lines): raise ValueError("Invalid MRZ text shape. Review the saved JSON.") print("MRZ lines (compare every field with the document):\n" + "\n".join(lines)) print(f"Postprocessing: {job['options']['do_postprocess']}. Inspecting format does not verify document authenticity.") else: print("Inspect all four corners before using them for perspective correction. Input and overlay remain local files.") def main() -> int: parser = argparse.ArgumentParser(description=__doc__) commands = parser.add_subparsers(dest="command", required=True) create = commands.add_parser("new", help="Prepare a new image and operation in a new local folder; sends nothing") create.add_argument("image", type=Path) create.add_argument("--job", type=Path, required=True) create.add_argument("--model", choices=VERSIONS, required=True) create.add_argument("--origin", choices=ORIGINS, default=ORIGINS[0]) create.add_argument("--prepared", action="store_true", help="Use the Demo JPEG exactly as downloaded; skip recompression") create.add_argument("--center-crop", action="store_true") create.add_argument("--doc-align", action="store_true") create.add_argument("--raw-mrz", action="store_true", help="Disable MRZ postprocessing") for command, help_text in (("send", "Submit a new job once"), ("retry", "Explicitly resend the identical job after checking its status"), ("inspect", "Inspect a saved response locally")): sub = commands.add_parser(command, help=help_text) sub.add_argument("job", type=Path) args = parser.parse_args() try: if args.command == "new": new_job(args) elif args.command == "inspect": inspect_job(args.job) else: return send_job(args.job, retry=args.command == "retry") except (ValueError, OSError, KeyError, Image.DecompressionBombError) as error: print(f"Stopped: {error}", file=sys.stderr) return 2 return 0 if __name__ == "__main__": raise SystemExit(main())