WARNING:
The FraudScanner is being developed and improved constantly.
Thus, the SDK is not always up to date with the current version and may break.
If you plan on using the SDK in a production environment, or encounter any issues, please contact us.

Vaarhaft FraudScanner SDK

A modern, async-friendly Python SDK for interacting with the Vaarhaft FraudScanner API.

Pre-requisites

In order to use the Vaarhaft FraudScanner API, you need to have an API key. You can obtain one by requesting it here.

Installation

pip install vaarhaft-fraudscanner

Examples

Basic Usage

"""
Basic usage example for the Vaarhaft FraudScanner SDK.

This example demonstrates how to use the FraudScannerClient to send a request to the FraudScanner API (v2)
and access some of the relevant response contents. It also shows how to use the batch functionality
to process multiple files.
"""

import asyncio
import os

from vaarhaft.fraudscanner import FraudScannerClient, ItemIdTuple, ResultItem


async def example_usage():
    """Run a basic example of using the FraudScanner SDK."""
    # Create an output directory for attachments
    output_dir = os.path.join(os.path.dirname(__file__), "..", "attachments")

    async with FraudScannerClient(api_key="your_api_key_here", attachments_output_dir=output_dir) as client:
        # Send a request to the FraudScanner API
        response = await client.send(
            file_path="/path/to/your/file.zip",
            case_number="My Case Number 123",
            issue_date="2023-10-01",  # Optional
            language="de",  # Optional, defaults to English
        )

        # Access metainformation about the request
        print(f"Status code: {response.status_code}")
        print(f"Request duration: {response.duration:.2f} seconds")

        # Access the raw JSON response
        print(f"Raw JSON response: {response.raw_json}")

        # Access textual information about received attachments
        print(f"Attachments: {response.attachments}")

        # Access response level fields regarding the overall response, such as the session ID
        print(f"Session ID: {response.sessionId}")
        # Access the number of FraudScanner API tokens consumed by the request
        print(f"Number of consumed tokens: {response.tokensConsumed}")

        # Access the processed 'Files' results
        files_mapping: dict[str, ResultItem] = response.Files
        for filename, file in files_mapping.items():
            print(f"File {filename} has a total suspicion level of '{file.suspicion_level}'")

        # Access all items in the response
        items_mapping: dict[ItemIdTuple, ResultItem] = response.get_all_items()
        for id_tuple, item in items_mapping.items():
            print(
                f"Item in file {id_tuple.file_name} with id {id_tuple.item_uuid} and type '{item.item_type}' has suspicion level '{item.suspicion_level}'."
            )


async def example_batched():
    """Run an example of using the batch functionality to process multiple files."""
    # Set the output directory path for attachments
    output_dir = os.path.join(os.path.dirname(__file__), "..", "attachments")

    async with FraudScannerClient(api_key="your_api_key_here", attachments_output_dir=output_dir) as client:
        # Process an entire directory (containing image or document files, not zips) in batches
        await client.batched(
            input_dir="/path/to/your/input/directory",
            output_file="/path/to/your/output/file.csv",  # CSV file containing an overview of the results
            case_number_base="TestBatch",  # Use max. 10 characters
            language="de",  # Optional, defaults to English
        )


if __name__ == "__main__":
    asyncio.run(example_usage())
    asyncio.run(example_batched())

API Reference

FraudScannerClient

The main client for interacting with the FraudScanner API. Can be used as a context manager (async with; see example above).

client = FraudScannerClient(api_key="your_api_key", attachments_output_dir="attachments")

Parameters

• api_key (str): The API key for authenticating with the FraudScanner API.
• attachments_output_dir (str): Directory to save attachments to.

Methods

• send(case_number, file_path, issue_date=None, contact_email=None, language="en"): Send a request to the FraudScanner API. Returns a FraudScannerResponse object.
• batched(case_number_base, input_dir, output_file, issue_date=None, contact_email=None, language="en"): Send all image and document files in a directory to the FraudScanner API. The results summarized in the specified output CSV file. Useful for getting a large amount of old cases/files into the system in bulk and without much setup.

FraudScannerResponse

The response from the FraudScanner API.

Properties

• Files: A dictionary of filename-to-file result pairs. Contains the main results of the analyses. Refer to the API documentation for details on the structure of the results.
• raw_json: The raw JSON data from the response.
• attachments: A dictionary mapping filenames to their paths on disk.
• status_code: The HTTP status code of the response.
• duration: The duration of the request in seconds.
• suspicion_level: The overall suspicion level of the request.
• caseNumber: The case number for the analysis.
• sessionId: The session ID for the request.
• modelVersions: The versions of the models used for analysis.
• tokensConsumed: The number of tokens that were consumed by the request.

Methods

• get_all_items(type=None): Get all items from the response, optionally filtered by type (image/document).

License

This project is licensed under the MIT License.