A Python Client for Reviewable Document Processing: Durable State, Server Quotes and Human Review
A document-processing client that uploads a file and waits for a result is fragile. For company records, the more useful design is a small auditable state machine: submit, capture the authoritative quote and job state, observe, download and review. Skavio Agent Tools provides the company-scoped authenticated API primitives; the Python client should preserve the evidence around them.
Treat the server quote as a durable record
Agent Tools is asynchronous and uses a shared prepaid credit wallet. The quote returned at submission is authoritative, so the Python client should not recalculate cost locally or treat an estimate as a settled job. A successful job settles once, and a permanent failure releases the reservation. That makes the quote and job state accounting-adjacent records, but credit consumption is still distinct from a cash receipt. A quote is not a job, and a job ID is not a completed result.
- Persist the request identifier and idempotency key before submission; store the authoritative quote snapshot, job ID and submission time when they are returned.
- Keep the captured quote data separate from later job-state updates so a changed provider state cannot silently rewrite the client’s record.
- Take request fields, authentication format and response schemas from the current Agent Tools documentation rather than guessing them.
Build the Python client as a state machine, not a script
A useful client has at least four responsibilities: transport, durable persistence, workflow orchestration, and a webhook verifier. The transport layer sends HTTPS requests with a company-scoped key. The persistence layer stores records outside process memory so a restart does not lose the idempotency key or job ID. The workflow layer advances a document from submission and quote capture to observation and artifact download. The verifier checks completion events before they are allowed to change business state. Keep scoped API keys server-side; they do not belong in browser code, logs or shared configuration files.
- Use a local record with fields such as request ID, idempotency key, quote snapshot, job ID, last observed state and artifact metadata.
- Treat an accepted or queued job as incomplete; use the documented status values from the current API contract.
- Separate the client’s internal state names from the API’s published states so a schema change is visible rather than hidden.
Retry uncertain requests by resolving state first
Network timeouts are normal, but blind resubmission is not. A stable idempotency key should identify the logical document request, not each retry. If the client loses the HTTP response after submission, it should first resolve the persisted record and reuse the same idempotency key with documented recovery behavior before treating the request as new. For completion, signed webhooks are preferable to constant polling, but the signature must be verified with the documented method before the event is trusted. Polling remains a controlled fallback, not a way to infer that a queued job has completed.
- Keep one idempotency key per logical request and reuse it only for safe retries of that request.
- Reject unsigned or invalid completion events and alert an operator instead of marking a document complete.
- Design polling with bounded intervals and respect the published limit of 120 requests per minute.
Download with company scope, then stop at human review
Results are retrieved through authenticated, company-scoped downloads. The client should place them in controlled storage and record artifact metadata alongside the quote, job ID and source reference. For extraction jobs, documented outputs include XLSX document and line-item worksheets, CSV, JSON, source evidence and review warnings. The Python client can assemble a review packet, but it should not write automatically into accounting or an ERP. Review dates, totals and line items before accepting results; source evidence and warnings are review aids, not replacements for a human check.
- Scope downloaded artifacts to the requesting company and avoid exposing result URLs or keys in client-side logs.
- Preserve source evidence, review warnings and the original request trail so a reviewer can trace a questionable value.
- Require an explicit human approval before any downstream financial write or external handoff.
Plan the first deployment around published limits
Agent Tools has operational limits that should shape the Python client’s batching and retention design: 100 upload files and 500 MB total upload per request, 2 GB of company source storage, 100 queued company jobs, four active company jobs, seven-day retention and 120 requests per minute. These are planning constraints, not performance claims. Start with a controlled sample set, check the live documentation and quote before processing a real batch, and make artifact retrieval part of the workflow rather than a manual afterthought.
- Submit files in batches that stay comfortably within the upload file-count and total-size limits.
- Treat four active company jobs as a scheduling constraint; queue awareness belongs in the client.
- Download and archive reviewed artifacts within the retention window, then apply your own retention and access policy.