scanverion 0.1.0__tar.gz

scanverion-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: scanverion
+Version: 0.1.0
+Summary: Python client for the Scanverion OCR API.
+Author: Scanverion
+License: Apache-2.0
+Classifier: License :: OSI Approved :: Apache Software License
+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.0
+```
+
+It requires Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from pathlib import Path
+from scanverion import Scanverion
+
+client = Scanverion(
+    api_key="skv_...",
+    base_url="http://localhost:5009",
+)
+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="skv_...") 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.
+
+## Local validation
+
+From the `scanverion` directory:
+
+```powershell
+python -m unittest discover -s packages/sdk-python/tests -v
+python -m compileall packages/sdk-python/src
+```

scanverion-0.1.0/README.md

@@ -0,0 +1,54 @@
+# 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.0
+```
+
+It requires Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from pathlib import Path
+from scanverion import Scanverion
+
+client = Scanverion(
+    api_key="skv_...",
+    base_url="http://localhost:5009",
+)
+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="skv_...") 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.
+
+## Local validation
+
+From the `scanverion` directory:
+
+```powershell
+python -m unittest discover -s packages/sdk-python/tests -v
+python -m compileall packages/sdk-python/src
+```

scanverion-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scanverion"
+version = "0.1.0"
+description = "Python client for the Scanverion OCR API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Scanverion" }]
+classifiers = [
+	"License :: OSI Approved :: Apache Software License",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3.10",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"Programming Language :: Python :: 3.14",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scanverion = ["py.typed"]

scanverion-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scanverion-0.1.0/src/scanverion/__init__.py

@@ -0,0 +1,23 @@
+"""Small, dependency-free Scanverion API client."""
+
+from .client import (
+    AnalysisClient,
+    AsyncScanverion,
+    Scanverion,
+    ScanverionApiError,
+    UsageClient,
+)
+from .models import (
+    Capability,
+    CapabilityCatalogResponse,
+    CapabilityUsageDetail,
+    CapabilityUsageResponse,
+    DailyUsageResponse,
+    RealtimeAnalysisBatchResponse,
+    RealtimeAnalysisResponse,
+    UsagePricePreview,
+    UsageSummary,
+)
+
+__all__ = ["AnalysisClient", "AsyncScanverion", "Capability", "CapabilityCatalogResponse", "CapabilityUsageDetail", "CapabilityUsageResponse", "DailyUsageResponse", "RealtimeAnalysisBatchResponse", "RealtimeAnalysisResponse", "Scanverion", "ScanverionApiError", "UsageClient", "UsagePricePreview", "UsageSummary"]
+__version__ = "0.1.0"

scanverion-0.1.0/src/scanverion/client.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import mimetypes
+import secrets
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, BinaryIO, Callable, Mapping, Protocol, Sequence
+from urllib.parse import quote, urlencode
+from .models import Capability, CapabilityCatalogResponse, CapabilityUsageDetail, CapabilityUsageResponse, DailyUsageResponse, RealtimeAnalysisBatchResponse, RealtimeAnalysisResponse, UsagePricePreview, UsageSummary
+
+JsonObject = dict[str, Any]
+FileInput = bytes | bytearray | memoryview | str | Path | BinaryIO
+
+
+@dataclass(frozen=True)
+class TransportResponse:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+class Transport(Protocol):
+    def __call__(self, method: str, url: str, headers: Mapping[str, str], body: bytes | None, timeout: float) -> TransportResponse: ...
+
+
+class AsyncTransport(Protocol):
+    async def __call__(self, method: str, url: str, headers: Mapping[str, str], body: bytes | None, timeout: float) -> TransportResponse: ...
+
+
+class ScanverionApiError(RuntimeError):
+    def __init__(self, message: str, status: int, problem: JsonObject | None = None, request_id: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.problem = problem
+        self.request_id = request_id
+        self.retryable = bool(problem.get("retryable")) if problem and "retryable" in problem else status in (408, 429) or status >= 500
+
+
+class AnalysisClient:
+    def __init__(self, client: Scanverion, vehicle: bool = False):
+        self._client = client
+        self._vehicle = vehicle
+
+    def process(self, file: FileInput, *, file_name: str | None = None, content_type: str | None = None, operations: Sequence[str] | None = None, disable_object_segmentation: bool | None = None, scanner_fields: Sequence[str] | None = None, checkbox_definitions: str | None = None, idempotency_key: str | None = None) -> RealtimeAnalysisResponse:
+        route = "/api/v1/ai/vehicle-processing" if self._vehicle else "/api/v1/ai/document-processing"
+        fields = {"File": [(file, file_name, content_type)]}
+        return self._client._post_multipart(route, fields, operations=operations, disable_object_segmentation=disable_object_segmentation, scanner_fields=scanner_fields, checkbox_definitions=checkbox_definitions, idempotency_key=idempotency_key)
+
+    def process_batch(self, files: Sequence[FileInput], *, file_names: Sequence[str | None] | None = None, content_types: Sequence[str | None] | None = None, operations: Sequence[str] | None = None, disable_object_segmentation: bool | None = None, scanner_fields: Sequence[str] | None = None, checkbox_definitions: str | None = None, idempotency_key: str | None = None) -> RealtimeAnalysisBatchResponse:
+        if not files:
+            raise ValueError("Scanverion requires at least one file.")
+        route = "/api/v1/ai/vehicle-processing/batches" if self._vehicle else "/api/v1/ai/document-processing/batches"
+        entries = [(file, file_names[index] if file_names and index < len(file_names) else None, content_types[index] if content_types and index < len(content_types) else None) for index, file in enumerate(files)]
+        return self._client._post_multipart(route, {"Files": entries}, operations=operations, disable_object_segmentation=disable_object_segmentation, scanner_fields=scanner_fields, checkbox_definitions=checkbox_definitions, idempotency_key=idempotency_key)
+
+
+class UsageClient:
+    def __init__(self, client: Scanverion):
+        self._client = client
+
+    def summary(self, *, from_date: str | None = None, to_date: str | None = None) -> UsageSummary:
+        return self._client._get("/api/v1/usage/summary", from_date, to_date)
+
+    def daily(self, *, from_date: str | None = None, to_date: str | None = None) -> DailyUsageResponse:
+        return self._client._get("/api/v1/usage/daily", from_date, to_date)
+
+    def by_capability(self, *, from_date: str | None = None, to_date: str | None = None) -> CapabilityUsageResponse:
+        return self._client._get("/api/v1/usage/by-capability", from_date, to_date)
+
+    def price_preview(self, *, from_date: str | None = None, to_date: str | None = None) -> UsagePricePreview:
+        return self._client._get("/api/v1/usage/price-preview", from_date, to_date)
+
+
+class Scanverion:
+    def __init__(self, api_key: str, *, base_url: str = "http://localhost:5009", timeout: float = 60.0, max_retries: int = 2, transport: Transport | None = None, user_agent: str | None = None):
+        if not api_key.strip():
+            raise ValueError("Scanverion requires a non-empty api_key.")
+        if timeout <= 0 or max_retries < 0:
+            raise ValueError("timeout must be positive and max_retries must not be negative.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.user_agent = user_agent
+        self._transport = transport or default_transport
+        self.documents = AnalysisClient(self)
+        self.vehicles = AnalysisClient(self, vehicle=True)
+        self.usage = UsageClient(self)
+
+    def capabilities(self) -> list[Capability]:
+        return self._get("/api/v1/ai/capabilities")
+
+    def catalog_capabilities(self) -> CapabilityCatalogResponse:
+        return self._get("/api/v1/catalog/capabilities")
+
+    def capability_usage(self, capability_key: str, *, from_date: str | None = None, to_date: str | None = None) -> CapabilityUsageDetail:
+        return self._get(f"/api/v1/catalog/capabilities/{quote(capability_key, safe='')}/usage", from_date, to_date)
+
+    def _get(self, path: str, from_date: str | None = None, to_date: str | None = None) -> Any:
+        query = {key: value for key, value in (("from", from_date), ("to", to_date)) if value is not None}
+        return self._request("GET", f"{path}?{urlencode(query)}" if query else path, None, None, retryable=True)
+
+    def _post_multipart(self, path: str, fields: Mapping[str, Sequence[tuple[FileInput, str | None, str | None]]], *, operations: Sequence[str] | None, disable_object_segmentation: bool | None, scanner_fields: Sequence[str] | None, checkbox_definitions: str | None, idempotency_key: str | None) -> JsonObject:
+        parts: list[tuple[str, bytes, str | None, str | None]] = []
+        for field_name, files in fields.items():
+            for file, file_name, content_type in files:
+                payload, resolved_name, resolved_type = read_file_input(file, file_name, content_type)
+                parts.append((field_name, payload, resolved_name, resolved_type))
+        text_fields: list[tuple[str, str]] = [("Operations", operation) for operation in (operations or ["Detection"])]
+        if disable_object_segmentation is not None:
+            text_fields.append(("DisableObjectSegmentation", str(disable_object_segmentation).lower()))
+        text_fields.extend(("ScannerFields", field) for field in (scanner_fields or []))
+        if checkbox_definitions is not None:
+            text_fields.append(("CheckboxDefinitions", checkbox_definitions))
+        body, content_type = encode_multipart(parts, text_fields)
+        headers = {"Accept": "application/json", "Content-Type": content_type, "Authorization": f"Bearer {self.api_key}"}
+        if self.user_agent:
+            headers["User-Agent"] = self.user_agent
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return self._request("POST", path, body, headers, retryable=bool(idempotency_key))
+
+    def _request(self, method: str, path: str, body: bytes | None, headers: Mapping[str, str] | None, *, retryable: bool) -> Any:
+        request_headers = dict(headers or {"Accept": "application/json", "Authorization": f"Bearer {self.api_key}"})
+        attempts = self.max_retries + 1 if retryable else 1
+        for attempt in range(attempts):
+            try:
+                response = self._transport(method, f"{self.base_url}{path}", request_headers, body, self.timeout)
+            except Exception:
+                if not retryable or attempt == attempts - 1:
+                    raise
+                time.sleep(min(2**attempt, 10))
+                continue
+            if 200 <= response.status < 300:
+                return json.loads(response.body.decode("utf-8")) if response.body else None
+            problem = json.loads(response.body.decode("utf-8")) if response.body else None
+            request_id = response.headers.get("X-Request-Id") or (problem or {}).get("requestId")
+            error = ScanverionApiError((problem or {}).get("detail") or (problem or {}).get("title") or "Scanverion request failed.", response.status, problem, request_id)
+            if not error.retryable or not retryable or attempt == attempts - 1:
+                raise error
+            retry_after = response.headers.get("Retry-After")
+            time.sleep(min(float(retry_after) if retry_after else 2**attempt, 10))
+        raise RuntimeError("Scanverion request retry loop ended unexpectedly.")
+
+
+class AsyncScanverion:
+    def __init__(self, api_key: str, *, base_url: str = "http://localhost:5009", timeout: float = 60.0, max_retries: int = 2, transport: AsyncTransport | None = None, user_agent: str | None = None):
+        self._client = Scanverion(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries, user_agent=user_agent)
+        self._transport = transport
+        self.documents = AsyncAnalysisClient(self, vehicle=False)
+        self.vehicles = AsyncAnalysisClient(self, vehicle=True)
+        self.usage = AsyncUsageClient(self)
+
+    async def __aenter__(self) -> AsyncScanverion:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        return None
+
+    async def capabilities(self) -> list[Capability]:
+        return await self._get("/api/v1/ai/capabilities")
+
+    async def catalog_capabilities(self) -> CapabilityCatalogResponse:
+        return await self._get("/api/v1/catalog/capabilities")
+
+    async def _get(self, path: str, from_date: str | None = None, to_date: str | None = None) -> Any:
+        query = {key: value for key, value in (("from", from_date), ("to", to_date)) if value is not None}
+        return await self._request("GET", f"{path}?{urlencode(query)}" if query else path, None, retryable=True)
+
+    async def _post_multipart(self, path: str, fields: Mapping[str, Sequence[tuple[FileInput, str | None, str | None]]], **kwargs: Any) -> JsonObject:
+        body, content_type = build_multipart_request(fields, kwargs)
+        return await self._request("POST", path, body, retryable=bool(kwargs.get("idempotency_key")), content_type=content_type, idempotency_key=kwargs.get("idempotency_key"))
+
+    async def _request(self, method: str, path: str, body: bytes | None, *, retryable: bool, content_type: str | None = None, idempotency_key: str | None = None) -> Any:
+        headers = {"Accept": "application/json", "Authorization": f"Bearer {self._client.api_key}"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        if self._client.user_agent:
+            headers["User-Agent"] = self._client.user_agent
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        if self._transport:
+            return await async_request(self._transport, self._client, method, path, body, headers, retryable)
+        return await asyncio.to_thread(self._client._request, method, path, body, headers, retryable=retryable)
+
+
+class AsyncAnalysisClient:
+    def __init__(self, client: AsyncScanverion, vehicle: bool):
+        self._client = client
+        self._vehicle = vehicle
+
+    async def process(self, file: FileInput, **kwargs: Any) -> RealtimeAnalysisResponse:
+        route = "/api/v1/ai/vehicle-processing" if self._vehicle else "/api/v1/ai/document-processing"
+        return await self._client._post_multipart(route, {"File": [(file, kwargs.pop("file_name", None), kwargs.pop("content_type", None))]}, **kwargs)
+
+    async def process_batch(self, files: Sequence[FileInput], **kwargs: Any) -> RealtimeAnalysisBatchResponse:
+        if not files:
+            raise ValueError("Scanverion requires at least one file.")
+        names = kwargs.pop("file_names", None)
+        types = kwargs.pop("content_types", None)
+        entries = [(file, names[index] if names and index < len(names) else None, types[index] if types and index < len(types) else None) for index, file in enumerate(files)]
+        route = "/api/v1/ai/vehicle-processing/batches" if self._vehicle else "/api/v1/ai/document-processing/batches"
+        return await self._client._post_multipart(route, {"Files": entries}, **kwargs)
+
+
+class AsyncUsageClient:
+    def __init__(self, client: AsyncScanverion):
+        self._client = client
+
+    async def summary(self, **kwargs: str | None) -> UsageSummary:
+        return await self._client._get("/api/v1/usage/summary", kwargs.get("from_date"), kwargs.get("to_date"))
+
+    async def daily(self, **kwargs: str | None) -> DailyUsageResponse:
+        return await self._client._get("/api/v1/usage/daily", kwargs.get("from_date"), kwargs.get("to_date"))
+
+    async def by_capability(self, **kwargs: str | None) -> CapabilityUsageResponse:
+        return await self._client._get("/api/v1/usage/by-capability", kwargs.get("from_date"), kwargs.get("to_date"))
+
+    async def price_preview(self, **kwargs: str | None) -> UsagePricePreview:
+        return await self._client._get("/api/v1/usage/price-preview", kwargs.get("from_date"), kwargs.get("to_date"))
+
+
+def read_file_input(file: FileInput, file_name: str | None, content_type: str | None) -> tuple[bytes, str, str]:
+    if isinstance(file, (str, Path)):
+        path = Path(file)
+        return path.read_bytes(), file_name or path.name, content_type or mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+    if isinstance(file, bytes):
+        return file, file_name or "file.bin", content_type or "application/octet-stream"
+    if isinstance(file, (bytearray, memoryview)):
+        return bytes(file), file_name or "file.bin", content_type or "application/octet-stream"
+    return file.read(), file_name or "file.bin", content_type or "application/octet-stream"
+
+
+def encode_multipart(files: Sequence[tuple[str, bytes, str, str]], text_fields: Sequence[tuple[str, str]]) -> tuple[bytes, str]:
+    boundary = "scanverion-" + secrets.token_hex(12)
+    chunks: list[bytes] = []
+    for name, value in text_fields:
+        chunks.extend([f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"\r\n\r\n{value}\r\n".encode(), b""])
+    for name, payload, file_name, content_type in files:
+        chunks.extend([f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"; filename=\"{file_name}\"\r\nContent-Type: {content_type}\r\n\r\n".encode(), payload, b"\r\n"])
+    chunks.append(f"--{boundary}--\r\n".encode())
+    return b"".join(chunks), f"multipart/form-data; boundary={boundary}"
+
+
+def build_multipart_request(fields: Mapping[str, Sequence[tuple[FileInput, str | None, str | None]]], options: Mapping[str, Any]) -> tuple[bytes, str]:
+    files: list[tuple[str, bytes, str, str]] = []
+    for name, entries in fields.items():
+        for file, file_name, content_type in entries:
+            files.append((name, *read_file_input(file, file_name, content_type)))
+    text_fields = [("Operations", operation) for operation in options.get("operations") or ["Detection"]]
+    if options.get("disable_object_segmentation") is not None:
+        text_fields.append(("DisableObjectSegmentation", str(options["disable_object_segmentation"]).lower()))
+    text_fields.extend(("ScannerFields", field) for field in options.get("scanner_fields") or [])
+    if options.get("checkbox_definitions") is not None:
+        text_fields.append(("CheckboxDefinitions", options["checkbox_definitions"]))
+    return encode_multipart(files, text_fields)
+
+
+def default_transport(method: str, url: str, headers: Mapping[str, str], body: bytes | None, timeout: float) -> TransportResponse:
+    request = urllib.request.Request(url, data=body, headers=dict(headers), method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return TransportResponse(response.status, dict(response.headers.items()), response.read())
+    except urllib.error.HTTPError as error:
+        return TransportResponse(error.code, dict(error.headers.items()), error.read())
+
+
+async def async_request(transport: AsyncTransport, client: Scanverion, method: str, path: str, body: bytes | None, headers: Mapping[str, str], retryable: bool) -> Any:
+    attempts = client.max_retries + 1 if retryable else 1
+    for attempt in range(attempts):
+        response = await transport(method, f"{client.base_url}{path}", headers, body, client.timeout)
+        if 200 <= response.status < 300:
+            return json.loads(response.body.decode("utf-8")) if response.body else None
+        problem = json.loads(response.body.decode("utf-8")) if response.body else None
+        error = ScanverionApiError((problem or {}).get("detail") or (problem or {}).get("title") or "Scanverion request failed.", response.status, problem, response.headers.get("X-Request-Id") or (problem or {}).get("requestId"))
+        if not error.retryable or not retryable or attempt == attempts - 1:
+            raise error
+        await asyncio.sleep(min(float(response.headers.get("Retry-After", 2**attempt)), 10))
+    raise RuntimeError("Scanverion request retry loop ended unexpectedly.")

scanverion-0.1.0/src/scanverion/models.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class BoundingBox(TypedDict):
+    left: float
+    top: float
+    right: float
+    bottom: float
+
+
+class ScannerResult(TypedDict):
+    fields: dict[str, str | None]
+    issuingCountry: dict[str, Any] | None
+    detectedLanguages: list[dict[str, Any]] | None
+
+
+class ObjectProcessingResults(TypedDict):
+    scanner: ScannerResult | None
+    rotation: dict[str, float] | None
+    blur: dict[str, bool] | None
+    faces: list[Any] | None
+    barcodes: list[Any] | None
+    checkboxes: list[Any] | None
+    signature: dict[str, Any] | None
+    lostOrStolenCard: dict[str, Any] | None
+
+
+class DetectedObject(TypedDict):
+    objectId: str
+    category: str
+    confidence: float
+    bounds: BoundingBox
+    results: ObjectProcessingResults
+    pageNumber: int
+
+
+class OperationSummary(TypedDict):
+    operation: str
+    status: str
+    message: str | None
+
+
+class UsageCharge(TypedDict):
+    units: int
+    unitsByOperation: dict[str, int]
+
+
+class RealtimeAnalysisResponse(TypedDict):
+    requestId: str
+    model: str
+    processingTimeMs: int
+    objects: list[DetectedObject]
+    operations: list[OperationSummary]
+    usage: UsageCharge
+
+
+class RealtimeAnalysisBatchResponse(TypedDict):
+    results: list[RealtimeAnalysisResponse]
+    usage: UsageCharge
+
+
+UsageSummary = TypedDict("UsageSummary", {"from": str, "to": str, "totalCalls": int, "estimatedCostEur": float, "includedCredits": int, "usedCredits": int})
+
+
+class DailyUsagePoint(TypedDict):
+    date: str
+    calls: int
+
+
+class DailyUsageResponse(TypedDict):
+    points: list[DailyUsagePoint]
+
+
+class CapabilityUsageItem(TypedDict):
+    capabilityKey: str
+    label: str
+    calls: int
+    units: float
+    estimatedCostEur: float
+
+
+class CapabilityUsageResponse(TypedDict):
+    items: list[CapabilityUsageItem]
+
+
+class UsagePricePreview(TypedDict):
+    includedCostEur: float
+    overageCostEur: float
+    totalEstimatedCostEur: float
+    currency: str
+
+
+class Capability(TypedDict):
+    key: str
+    name: str
+    model: str
+    supportedOperations: list[str]
+    supportedInputMimeTypes: list[str]
+    maximumFileSizeBytes: int
+
+
+class CapabilityCatalogItem(TypedDict):
+    key: str
+    name: str
+    description: str
+    route: str
+    method: str
+    isEnabled: bool
+
+
+class CapabilityCatalogResponse(TypedDict):
+    capabilities: list[CapabilityCatalogItem]
+
+
+CapabilityUsageDetail = TypedDict("CapabilityUsageDetail", {"capabilityKey": str, "from": str, "to": str, "calls": int, "credits": float})

scanverion-0.1.0/src/scanverion.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: scanverion
+Version: 0.1.0
+Summary: Python client for the Scanverion OCR API.
+Author: Scanverion
+License: Apache-2.0
+Classifier: License :: OSI Approved :: Apache Software License
+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.0
+```
+
+It requires Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from pathlib import Path
+from scanverion import Scanverion
+
+client = Scanverion(
+    api_key="skv_...",
+    base_url="http://localhost:5009",
+)
+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="skv_...") 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.
+
+## Local validation
+
+From the `scanverion` directory:
+
+```powershell
+python -m unittest discover -s packages/sdk-python/tests -v
+python -m compileall packages/sdk-python/src
+```

scanverion-0.1.0/src/scanverion.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/scanverion/__init__.py
+src/scanverion/client.py
+src/scanverion/models.py
+src/scanverion/py.typed
+src/scanverion.egg-info/PKG-INFO
+src/scanverion.egg-info/SOURCES.txt
+src/scanverion.egg-info/dependency_links.txt
+src/scanverion.egg-info/top_level.txt
+tests/test_client.py

scanverion-0.1.0/src/scanverion.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scanverion-0.1.0/src/scanverion.egg-info/top_level.txt

@@ -0,0 +1 @@
+scanverion

scanverion-0.1.0/tests/test_client.py

@@ -0,0 +1,104 @@
+import asyncio
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parents[1] / "src"))
+
+from scanverion import AsyncScanverion, Scanverion, ScanverionApiError
+from scanverion.client import TransportResponse
+
+CONTRACT_FIXTURE = json.loads((Path(__file__).parents[3] / "fixtures" / "client-contract-cases.json").read_text(encoding="utf-8"))
+
+
+class FakeTransport:
+    def __init__(self, responses):
+        self.responses = iter(responses)
+        self.calls = []
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.calls.append((method, url, headers, body, timeout))
+        return next(self.responses)
+
+
+def response(payload, status=200, headers=None):
+    return TransportResponse(status, headers or {}, json.dumps(payload).encode())
+
+
+class ScanverionClientTests(unittest.TestCase):
+    def test_tracks_shared_v1_contract_cases(self):
+        self.assertEqual("v1", CONTRACT_FIXTURE["version"])
+        self.assertEqual(
+            {
+                "document-multipart",
+                "document-batch-multipart",
+                "vehicle-operations",
+                "usage-period",
+                "structured-problem",
+            },
+            {case["id"] for case in CONTRACT_FIXTURE["cases"]},
+        )
+
+    def test_processes_multipart_path_input_and_idempotency(self):
+        transport = FakeTransport([response({"requestId": "req_1", "model": "Document"})])
+        client = Scanverion("skv_test", transport=transport)
+
+        result = client.documents.process(b"image", file_name="sample.jpg", content_type="image/jpeg", operations=["Detection", "Scanner"], idempotency_key="sample-1")
+
+        self.assertEqual("req_1", result["requestId"])
+        method, url, headers, body, _ = transport.calls[0]
+        self.assertEqual("POST", method)
+        self.assertEqual("http://localhost:5009/api/v1/ai/document-processing", url)
+        self.assertEqual("Bearer skv_test", headers["Authorization"])
+        self.assertEqual("sample-1", headers["Idempotency-Key"])
+        self.assertIn(b'name="Operations"', body)
+        self.assertIn(b"Scanner", body)
+        self.assertIn(b'filename="sample.jpg"', body)
+
+    def test_usage_dates_are_encoded_and_transient_post_retries_only_with_key(self):
+        transport = FakeTransport([
+            response({"from": "2026-07-01", "to": "2026-07-31"}),
+            response({"title": "Busy", "retryable": True}, 503, {"Retry-After": "0"}),
+            response({"requestId": "req_2"}),
+        ])
+        client = Scanverion("skv_test", transport=transport, max_retries=1)
+
+        client.usage.summary(from_date="2026-07-01", to_date="2026-07-31")
+        self.assertEqual("http://localhost:5009/api/v1/usage/summary?from=2026-07-01&to=2026-07-31", transport.calls[0][1])
+        self.assertEqual("req_2", client.documents.process(b"x", idempotency_key="retry-1")["requestId"])
+        self.assertEqual(3, len(transport.calls))
+
+    def test_structured_error_preserves_request_id(self):
+        transport = FakeTransport([response({"title": "Invalid", "detail": "Fix input", "code": "invalid_request", "retryable": False, "requestId": "req_3"}, 422, {"X-Request-Id": "req_3"})])
+        with self.assertRaises(ScanverionApiError) as context:
+            Scanverion("skv_test", transport=transport).documents.process(b"x")
+        self.assertEqual(422, context.exception.status)
+        self.assertEqual("req_3", context.exception.request_id)
+        self.assertFalse(context.exception.retryable)
+
+    def test_transient_processing_error_is_not_retried_without_idempotency_key(self):
+        transport = FakeTransport([response({"title": "Busy", "retryable": True}, 503)])
+        with self.assertRaises(ScanverionApiError):
+            Scanverion("skv_test", transport=transport, max_retries=2).documents.process(b"x")
+        self.assertEqual(1, len(transport.calls))
+
+    def test_async_client_uses_injected_transport(self):
+        calls = []
+
+        async def transport(method, url, headers, body, timeout):
+            calls.append((method, url, body))
+            return response({"points": []})
+
+        async def run():
+            async with AsyncScanverion("skv_test", transport=transport) as client:
+                return await client.usage.daily(from_date="2026-07-01")
+
+        result = asyncio.run(run())
+        self.assertEqual([], result["points"])
+        self.assertEqual("GET", calls[0][0])
+        self.assertIn("from=2026-07-01", calls[0][1])
+
+
+if __name__ == "__main__":
+    unittest.main()