Metadata-Version: 2.4
Name: qomplement
Version: 0.1.0
Summary: Python SDK for the Qomplement StructDatafy API — extract structured data from documents and fill forms with AI.
Author-email: Andres Garza <andres@qomplement.com>
License: MIT
Project-URL: Homepage, https://qomplement.com
Project-URL: Documentation, https://docs.qomplement.com
Project-URL: Repository, https://github.com/Qomplement/qomplement-python
Project-URL: Issues, https://github.com/Qomplement/qomplement-python/issues
Keywords: qomplement,ocr,document,extraction,pdf,excel,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# qomplement

Python SDK for the [Qomplement StructDatafy API](https://docs.qomplement.com) — extract structured data from documents and fill PDF/Excel forms with AI.

## Installation

```bash
pip install qomplement
```

## Quick Start

```python
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

```python
# 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

```python
# 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

```python
# 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:

```python
# 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

```python
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

```python
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

```python
# 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

```python
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
