deepxl-python-sdk 1.2.1
Python SDK for DeepXL fraud detection, document parsing, and verification services
Requires Python: >=3.8

# DeepXL Python SDK

Python SDK for DeepXL fraud detection, document parsing, verification, and file retrieval services.

## Installation

```bash
pip install deepxl
```

Or install from source:

```bash
pip install -r requirements.txt
```

## Usage

### Initialize the Client

```python
from deepxl import DeepXLClient, DeepXLClientConfig

config = DeepXLClientConfig(apiKey='your-api-key-here')
client = DeepXLClient(config)
```

## Fraud Detection

### Get Available Models

```python
models = client.get_detection_models()
print(models)
```

### Analyze a File for Fraud Detection

```python
from deepxl import AnalyzeFileOptions

# Read file as bytes
with open('document.jpg', 'rb') as f:
    file_data = f.read()

options = AnalyzeFileOptions(
    model='document',  # or 'object'
    file=file_data,
    fileName='document.jpg',
    tags={
        'customerId': '9999',
        'customerName': 'Acme Corp',
        'documentId': 'DOC-2024-001'
    }
)

result = client.analyze_file(options)
print(result['result'])
```

### Get Detection History

```python
from deepxl import DetectionQueryParams

params = DetectionQueryParams(
    limit=25,
    offset=0,
    sortBy='createdOn',
    direction='desc',
    fraudSeverity='high',
    minLikelihood=70
)

history = client.get_detection_history(params)
print(history['data'])
```

### Get Detection by ID

```python
detection = client.get_detection_by_id(123)
print(detection['result'])
```

## Document Parsing

### Get Available Parsing Models

```python
models = client.get_parsing_models()
print(models)
```

### Parse a Document

```python
from deepxl import ParseDocumentOptions

# Read file as bytes
with open('drivers_license.jpg', 'rb') as f:
    file_data = f.read()

options = ParseDocumentOptions(
    model='light',  # or 'performance'
    file=file_data,
    fileName='drivers_license.jpg',
    tags={
        'customerId': '9999',
        'customerName': 'Acme Corp'
    }
)

result = client.parse_document(options)
print(result['result']['parsedData'])
```

### Get Parse History

```python
from deepxl import ParseQueryParams

params = ParseQueryParams(
    limit=25,
    offset=0,
    sortBy='parseId',
    direction='desc',
    documentType='usa_driver_license'
)

history = client.get_parsing_history(params)
print(history['data'])
```

### Get Parse by ID

```python
parse_result = client.get_parse_by_id(117)
print(parse_result['result'])
```

## Verification

### Verify User with ID and Selfie

```python
from deepxl import VerifyOptions

# Read files as bytes
with open('id.jpg', 'rb') as f:
    id_data = f.read()

with open('selfie.jpg', 'rb') as f:
    selfie_data = f.read()

options = VerifyOptions(
    idFile=id_data,
    idFileName='id.jpg',
    selfieFile=selfie_data,
    selfieFileName='selfie.jpg',
    tags={
        'customerId': '9999',
        'customerName': 'Acme Corp'
    }
)

result = client.verify(options)
print(result['result']['verified'])
print(result['result']['technicalChecks'])
```

### Get Verification History

```python
from deepxl import VerificationQueryParams

params = VerificationQueryParams(
    limit=25,
    offset=0,
    verified=True,
    sortBy='timestamp',
    direction='desc'
)

history = client.get_verification_history(params)
print(history['data'])
```

### Get Verification by ID

```python
verification = client.get_verification_by_id(456)
print(verification['result'])
```

## File Retrieval

### Download a File

```python
file_bytes = client.download_file('fd_123_document.jpg')
with open('downloaded_file.jpg', 'wb') as f:
    f.write(file_bytes)
```

### Get File as Response

```python
response = client.get_file('fd_123_document.jpg')
file_bytes = response.content
with open('downloaded_file.jpg', 'wb') as f:
    f.write(file_bytes)
```

## Type Definitions

All type definitions are available for import:

```python
from deepxl import (
    Tag,
    FileData,
    ModelMetadata,
    FraudDetection,
    DetectionResponse,
    DetectionQueryParams,
    AnalyzeFileOptions,
    APIParse,
    APIParseResponse,
    ParseQueryParams,
    ParseDocumentOptions,
    Verification,
    VerificationResponse,
    VerificationQueryParams,
    VerifyOptions,
)
```

## Error Handling

The SDK raises `ValueError` with descriptive error messages:

```python
try:
    result = client.analyze_file(options)
except ValueError as e:
    print(f'Error: {e}')
    # Error messages match API error responses
```

## Query Parameters

All query parameters are optional and can be used to filter and paginate results:

- `limit`: Number of results (1-100, default: 25)
- `offset`: Number of results to skip (default: 0)
- `sortBy`: Field to sort by
- `direction`: 'asc' or 'desc' (default: 'desc')
- `tagFilter`: Filter by tags in format 'tagName=tagValue'
- Various model-specific filters (see type definitions for details)

## Tags

Tags are optional metadata that can be attached to analyses for organization and filtering:

```python
tags = {
    'customerId': '9999',
    'customerName': 'Acme Corp',
    'documentId': 'DOC-2024-001',
    'companyName': 'DeepXL',
    'companyId': 'COMP-001'
}
```

You can filter results by tags using the `tagFilter` query parameter:

```python
params = DetectionQueryParams(tagFilter='customerId=9999')
history = client.get_detection_history(params)
```

## Using File Objects

You can also pass file-like objects directly:

```python
# Using open file handle
with open('document.jpg', 'rb') as f:
    options = AnalyzeFileOptions(
        model='document',
        file=f,
        fileName='document.jpg'
    )
    result = client.analyze_file(options)
```