perceptor-client-lib-java

Usage

If you use a locally stored package, add a file source, for example:

repositories {
    mavenCentral()
    flatDir {
    dirs '../packages'
    }
}

Add following dependencies to your java project:

implementation ':perceptor_client_lib:0.1-dev01'
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.1")
implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.8.20")

To access the client, following package must be imported:

import org.tamedai.perceptorclient.*;

To create a client instance

        var waitTimeout = java.time.Duration.ofSeconds(30);
        ClientSettings settings = new ClientSettings("API_KEY",
                "https://perceptor-api.tamed.ai/1/model/",
                waitTimeout);
        PerceptorClient client = PerceptorClientFactory.INSTANCE.createClient(settings);

It is also possible to read the main client settings (api_key and api_url) from environment variables. Following environment variables will be used: TAI_PERCEPTOR_BASE_URL for api url TAI_PERCEPTOR_API_KEY for api key

ClientSettings settings = ClientSettings.Factory.fromEnv();

Should those variables be missing or empty, an exception will be thrown.

Creating request

Use method PerceptorRequest.Factory.withFlavor to create a request object without additional parameters. You have to specify the flavor name and binary flag whether the scores are to be calculated or not. To specify additional parameters use the constructor of PerceptorRequest.

Example code to create a client instance and send an instruction for a text:

import org.tamedai.perceptorclient.*;
import java.util.Arrays;
import java.util.List;


public class Main {
    public static void main(String[] args) {

        var waitTimeout = java.time.Duration.ofSeconds(30);
        ClientSettings settings = new ClientSettings("API_KEY",
                "https://perceptor-api.tamed.ai/1/model/",
                waitTimeout);
        PerceptorClient client = PerceptorClientFactory.INSTANCE.createClient(settings);

        String textToProcess ="Ich melde einen Schaden für meinen Kunden Hans Helmut. Meine Vermittlernumer ist die 090.100.";

        List<String> instructions = Arrays.asList("Vorname und Nachname des Kunden?",
                "Vermittlernumer?");

        var res = client.askText(textToProcess,
                PerceptorRequest.Factory.withFlavor("original", true),
                instructions
        );

        InstructionWithResult firstResp = res.get(0);

        if (firstResp.isSuccess()){
            System.out.println("Got response:");
            System.out.println(firstResp.getResponse().get("text"));
        }else{
            System.out.println("Got error:");
            System.out.println(firstResp.getErrorText());
        }

    }
}

Example code to create a client to send an instruction for an image:

import org.tamedai.perceptorclient.*;
import java.util.Arrays;
import java.util.List;


public class Main {
    public static void main(String[] args) {

        var waitTimeout = java.time.Duration.ofSeconds(30);
        ClientSettings settings = new ClientSettings("API_KEY",
                "https://perceptor-api.tamed.ai/1/model/",
                waitTimeout);
        PerceptorClient client = PerceptorClientFactory.INSTANCE.createClient(settings);

        var responseImage = client.askImage("path_to_image",
                PerceptorRequest.Factory.withFlavor("original"),
                Arrays.asList("What is the invoice number?",
                        "What is the invoice date?"));

        InstructionWithResult firstResp = res.get(0);

        if (firstResp.isSuccess()){
            System.out.println("Got response:");
            System.out.println(firstResp.getResponse().get("text"));
        }else{
            System.out.println("Got error:");
            System.out.println(firstResp.getErrorText());
        }

    }
}

Example code to create a client to send a classify instruction for an image:

import org.tamedai.perceptorclient.*;
import java.util.Arrays;
import java.util.List;


public class Main {
    public static void main(String[] args) {

        var waitTimeout = java.time.Duration.ofSeconds(30);
        ClientSettings settings = new ClientSettings("API_KEY",
                "https://perceptor-api.tamed.ai/1/model/",
                waitTimeout);
        PerceptorClient client = PerceptorClientFactory.INSTANCE.createClient(settings);

        var response = client.classifyImage(_invoiceImagePath,
                PerceptorRequest.Factory.withFlavor("original", true),
                "what kind of document is it?",
                Arrays.asList("invoice", "application", "prescription")
        );

        if (response.isSuccess()) {
            System.out.printf("Instruction: %s, response: %s", response.getInstruction(), response.getResponse());

        } else {
            System.out.printf("Instruction: %s, error: %s", response.getInstruction(), response.getErrorText());
        }

    }
}

Reading responses

Basic class containing the processing result is InstructionWithResult (see here).

It contains following properties:
instruction contains the original instruction text
isSuccess set to True if the query was successful
response is a map/dictionary containing at least "text" element (with actual response text) and may contain additional values (for example scores).
errorText error text (if error occurred)

Following methods return the list of InstructionWithResult instances:
askText
askImage

Following method(s) return single InstructionWithResult instance:
askTableFromImage
classifyText
classifyImage

Following methods query multiple images (document images), hence return the list of DocumentImageResult instances, containing, beside the InstructionWithResult list, also the original page info:
askDocumentImagePaths
askDocumentImageStreams
askDocumentImageBytes

Mapping response

If you use the methods returning the list of DocumentImageResult and need to have the responses grouped by instruction rather than page, you can use the provided utility function (UtilsKt.groupByInstruction) to map the response:

        var mapped = org.tamedai.perceptorclient.UtilsKt.groupByInstruction(res);
        for (InstructionWithPageResult instructionResult : mapped){
            System.out.printf("instruction: %s", instructionResult.getInstruction());
            for (var pageRes : instructionResult.getPageResults()){
                if (pageRes.isSuccess()){
                    System.out.printf("page: %s, response: %s", pageRes.getPageIndex(), pageRes.getResponse());
                }else {
                    System.out.printf("page: %s, error: %s", pageRes.getPageIndex(), pageRes.getErrorText());
                }
            }
        }