qomplement

Python SDK for the Qomplement StructDatafy API — extract structured data from documents and fill PDF/Excel forms with AI.

Installation

pip install qomplement

Quick Start

from qomplement import Qomplement

client = Qomplement("sd_your_api_key")

# Extract data from any document
result = client.extract("invoice.pdf")
print(result.fields)
# {'invoice_number': '12345', 'client_name': 'Acme Corp', 'total': '$5,000.00'}
print(result.tables)
print(result.document_type)  # 'invoice'
print(result.confidence)     # 94

Extract

# Basic extraction
result = client.extract("document.pdf")

# With full detail (entities, summary, primary/secondary entities)
result = client.extract("document.pdf", detail=True)
print(result.detail["entities"])
print(result.detail["summary"])

# Guided extraction with schema
schema = [
    {"name": "invoice_number", "type": "string"},
    {"name": "total_amount", "type": "number"},
    {"name": "vendor_name", "type": "string"},
]
result = client.extract("invoice.pdf", schema=schema)

# Extract with text chunking
result = client.extract("long_document.pdf", chunk_size=1000, chunk_overlap=200)
for chunk in result.chunks:
    print(chunk["text"])

# From bytes
with open("document.pdf", "rb") as f:
    result = client.extract(f.read(), filename="document.pdf")

Fill PDF

# Fill using source documents (AI extracts and maps fields)
result = client.fill_pdf(
    "form.pdf",
    source="invoice.pdf",
)
result.save("filled_form.pdf")

# Fill with natural language instructions
result = client.fill_pdf(
    "contract.pdf",
    instructions="Fill client name as 'Acme Corporation' and date as January 15, 2024",
)
result.save("filled_contract.pdf")

# Fill with explicit field mappings
result = client.fill_pdf(
    "form.pdf",
    field_mappings={"client_name": "Acme Corp", "date": "2024-01-15"},
)
result.save("filled_form.pdf")

print(f"Filled {result.fields_filled}/{result.fields_total} fields")

Fill Excel

# Fill Excel template from source documents
result = client.fill_excel(
    "template.xlsx",
    source="invoice.pdf",
)
result.save("filled_template.xlsx")

# Fill with instructions
result = client.fill_excel(
    "template.xlsx",
    instructions="Add company name as Acme Corp in the header",
)
result.save("filled.xlsx")

Async Jobs

Large documents (>5 pages) are processed asynchronously. By default, the SDK polls and waits for completion:

# This automatically waits for completion (default: wait=True)
result = client.extract("large_document.pdf")

# Get a job reference without waiting
job = client.extract("large_document.pdf", wait=False)
print(job.id)      # job ID
print(job.status)  # 'processing'

# Check job status later
job = client.get_job(job.id)
if job.status == "completed":
    print(job.result)

# List your jobs
jobs = client.list_jobs(status="completed", limit=10)

Usage

usage = client.usage()
print(f"Requests: {usage.requests}")
print(f"Pages processed: {usage.pages_processed}")

# Usage for a specific month
usage = client.usage(period="2026-02")

Supported Formats

formats = client.formats()
print(formats["total_formats"])  # 33

# List available models
models = client.models()
for m in models:
    print(f"{m['id']}: {m['description']}")

The API supports 33+ file formats including PDF, DOCX, XLSX, PPTX, CSV, TXT, RTF, images (PNG, JPEG, HEIC, TIFF), and legacy formats (DOC, XLS, PPT).

Configuration

# API key from environment variable
import os
os.environ["QOMPLEMENT_API_KEY"] = "sd_your_api_key"
client = Qomplement()

# Custom base URL
client = Qomplement("sd_your_api_key", base_url="https://developer-api-testing.qomplement.com")

# Custom timeout and max wait
client = Qomplement("sd_your_api_key", timeout=120, max_wait=300)

Error Handling

from qomplement import Qomplement, AuthenticationError, RateLimitError, ValidationError

client = Qomplement("sd_your_api_key")

try:
    result = client.extract("document.pdf")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid request: {e}")

License

MIT