Metadata-Version: 2.4
Name: scanverion
Version: 0.1.1
Summary: Python client for the Scanverion OCR API.
Author: Scanverion
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# scanverion

Node and Python are the first supported Scanverion client languages. This package provides synchronous and asynchronous standard-library clients for the OCR API.

## Download and install

Install the published package from PyPI:

```powershell
python -m pip install scanverion==0.1.1
```

It requires Python 3.10 or newer.

## Quickstart

### Client-held identity templates

```python
from scanverion import IdentityTemplateImage

template = client.templates.create(
    [IdentityTemplateImage("portrait.png")],
    processing_authorized=True, idempotency_key="template-create-001")
comparison = client.templates.compare(
    reference_template=template["templateToken"],
    candidate_image=IdentityTemplateImage("candidate.png"),
    processing_authorized=True, idempotency_key="template-compare-001")
```

Use the configured `Scanverion` client shown below; `AsyncScanverion` exposes the same methods with `await`. Creation accepts 1-8 JPEG/PNG images (10 MiB each, 40 MiB combined). Compare a reference template or `reference_images` against a candidate template or one `candidate_image`. Both operations cost 2 credits on completion, require explicit processing authorization and a 1-96 character idempotency key, and never automatically retry. Do not print the template dictionary: tokens and search vectors are sensitive biometric data. There is no server gallery. Cosine similarity requires human review; it is not identity probability or liveness.

### Camera liveness

Included in release 0.1.1. Availability depends on the deployment and workspace; a successful public try-out does not activate workspace API access. Check `/api/v1/face-liveness/policy` and workspace capabilities. Synchronous and asynchronous clients expose `liveness.create_session` and `liveness.get_result`:

```python
import os
from uuid import uuid4
from scanverion import Scanverion

client = Scanverion(
    api_key=os.environ["SCANVERION_API_KEY"],
    base_url="https://api.scanverion.com",
)
session = client.liveness.create_session(
    processing_authorized=True, idempotency_key=str(uuid4()))
```

Complete the real camera challenge using Scanverion's [React component](../liveness-react/README.md) and the returned capture metadata, then retrieve the assessment after its completion callback. The backend must authenticate participants, verify processing authorization and bind each session to its owner:

```python
result = client.liveness.get_result(session_id=session["sessionId"], access_token=session["accessToken"])
```

Use `await` for the same methods on `AsyncScanverion`. Neither method automatically retries. Do not print or persist the session dictionary: its access token and short-lived capture ID are sensitive. Valid completed assessments are billable independently of pass/fail; liveness does not prove identity or compare faces. [Camera flow, IAM, expiry and activation](../../docs/aws-face-liveness.md).

### Document processing

```python
import os
from pathlib import Path
from scanverion import Scanverion

client = Scanverion(
    api_key=os.environ["SCANVERION_API_KEY"],
    base_url=os.getenv("SCANVERION_API_URL", "https://api.scanverion.com"),
)
result = client.documents.process(
    Path("invoice.pdf"),
    file_name="invoice.pdf",
    content_type="application/pdf",
    operations=["Detection", "Scanner"],
    scanner_fields=["invoiceNumber", "grossTotal"],
    idempotency_key="invoice-2026-0007",
)
print(result["requestId"], result["objects"])
```

The core methods accept `bytes`, `bytearray`, `memoryview`, `pathlib.Path`, or binary file objects. `AsyncScanverion` exposes the same resource groups and uses an injected async transport or `asyncio.to_thread` with the default transport.

```python
from scanverion import AsyncScanverion

async with AsyncScanverion(
    api_key=os.environ["SCANVERION_API_KEY"],
    base_url=os.getenv("SCANVERION_API_URL", "https://api.scanverion.com"),
) as client:
    summary = await client.usage.summary(from_date="2026-07-01", to_date="2026-07-31")
```

API keys are server-side credentials. Do not put them in browser code, mobile binaries, logs, or public fixtures. Processing POST retries happen only when an idempotency key is supplied; safe GET resources may retry transient failures.

## Face comparison

The current workspace adds `client.faces.compare` and its async equivalent. These additions are not in the published PyPI package yet; install from this repository for local use.

```python
from scanverion import FaceComparisonInput

comparison = client.faces.compare(
    FaceComparisonInput(image=Path("reference.jpg")),
    FaceComparisonInput(artifact_id="workspace-portrait-id"),
    policy="balanced",
    idempotency_key="face-comparison-001",
)
print(comparison["similarity"], comparison["decision"], comparison["reviewRequired"])
```

For an `AsyncScanverion` instance, use `await client.faces.compare(...)`. Supply exactly one JPEG/PNG image or same-workspace portrait artifact per side, with a 10 MB image limit. Byte inputs need an explicit `content_type`. Responses include face bounds and landmarks; similarity is not identity proof or liveness. Successful requests use the configured face credit price. Validation and provider failures are uncharged, and face requests never retry automatically. Investigate uncertain completion before resubmitting.

## Local validation

From the `scanverion` directory:

```powershell
python -m unittest discover -s packages/sdk-python/tests -v
python -m compileall packages/sdk-python/src
```
