# com.innovaphone.assistant

This API is used for communication with a large language model (LLM) and text translation (HTML payload is also supported) against an externally hosted service.

## Messages

Question
Translate
GetTargetLanguages
DetectLanguage

### Question

Transfers the specified question to the LLM in order to receive a response.

    {
        mt:   "Question",
        messages: [{ role: "user", content: "The actual question comes here..." }]
    }

#### Parameters

string mt | message type [mandatory]
array of objects messages | an array of messages to be transfered [mandatory]
number temperature | a number between 0 and 1 which determines the creativity of the response (defaults to 0) [optional]
number max_tokens | limits the length of the response by specifying the maximum number of tokens (words and punctuation) to generate [optional]
number top_p | controls the probability threshold for generating tokens, ensuring that the generated tokens have a cumulative probability of at least the specified value [optional]
number n | specifies the number of chat completion choices to generate for each input message [optional]
string or array of strings stop | a string or array of strings that, if present, stops the generation process when the model outputs this token [optional]
number presence_penalty | penalizes the model for generating tokens that are already present in the conversation history, encouraging new content [optional]
number frequency_penalty | penalizes the model for generating repetitive tokens, thus reducing repetition in the responses [optional]
array of objects tools | provides function specifications to enable models to generate function arguments and invoke functions as part of the response [optional]
string tool_choice | forces the model to use a specific function or not use any function at all [optional]
number seed | sets the random seed for reproducibility, ensuring consistent outputs for the same input parameters [optional]

##### Note:

Not all parameters may be supported by your LLM provider! Adding them might throw a HTTP error.

#### Response

    {
        mt:        "QuestionResult",
        message:   { role: "assistant", content: "The answer to your question is....!" }
    }

#### Parameters

string mt | message type (is "QuestionResult")
object message | the response object of the LLM

#### Error Response

If you run into an error you will receive the following response.

    {
        mt:    "QuestionResult",
       message:   { content: "The actual error message" },
        error: true
    }

#### Parameters

string mt | message type (is "TranslateResult")
string object | English error message which can be shown to the User
bool error | labelling whether error was send. Only sent if true [optional]

### Translate

Translate a specific payload to requested language.

    {
        mt:   "Translate",
        html: "Payload we want translated",
        langDst: "de"
    }

#### Parameters

string mt | message type [mandatory]
string html | payload to be translated [mandatory]
string langSrc | 2 letter source language. If not set, the language will be detected. [optional]
string langDst | 2 letter target language. If not set, the current myApps language will be used. [optional]

If you want to exclude some content from translation, you can wrap them in an HTML tag with the parameter `translate="no"`. (Example: "`Bananas are <span translate="no">yellow</span> fruits.`)

#### Response

    {
        mt:        "TranslateResult",
        html:      "Nutzdaten, die übersetzt werden sollen",
        langSrc:   "en"
        langDst:   "de"
        unchanged: false
    }

#### Parameters

string mt | message type (is "TranslateResult")
string html | translated payload
string langSrc | 2 letter source language
string langDst | 2 letter target language
bool unchanged | labelling if the payload in html have been changed

#### Error Response

If you run into an error you will receive the following response.

    {
        mt:    "TranslateResult",
        html:  "Error: [English error message which can be shown to the User]",
        error: true
    }

#### Parameters

string mt | message type (is "TranslateResult")
string html | English error message which can be shown to the User
bool error | labelling whether error was send. Only sent if true [optional]

### GetTargetLanguages

Get all possible target languages.

    {
        mt:   "GetTargetLanguages"
    }

#### Parameters

string mt | message type (is "GetTargetLanguages")

#### Response

    {
        mt:        "GetTargetLanguagesResult",
        languages: [
            { language: "bg", name: "Bulgarian" },
            { language: "cs", name: "Czech" },
            { language: "da", name: "Danish" },
            { language: "de", name: "German" },
            { language: "el", name: "Greek" },
            ...
        ]
    }

#### Parameters

string mt | message type (is "GetTargetLanguagesResult")
array languages | array of all supported target languages

### DetectLanguage

Detect langiage from given string.

    {
        mt:   "DetectLanguage",
        html: "Payload that should be detected"
    }

#### Parameters

string mt | message type (is "DetectLanguage")
string html | payload

#### Response

    {
        mt:   "DetectLanguageResult",
        lang: "en"
    }

#### Parameters

string mt | message type (is "DetectLanguageResult")
array lang | 2-letter detected language, empty if no match
bool error | labelling whether error was send. Only sent if true [optional]

## Example

You can consume the API com.innovaphone.assistant and send request to it. Inside the callback you can access the response text via recv.msg.message.content

        var assistantApi = start.consumeApi("com.innovaphone.assistant");
        let messages = [];
        messages.push({ role: "system", content: "Answer in the language of the input!" });
        messages.push({ role: "user", content: "What do you know about innovaphone?" });

        assistantApi.sendSrc({ mt: "Question", messages: messages }, assistantApi.providers[0], (recv) => {
            if (recv.msg?.message?.content) {
                console.log('response text: ' + recv.msg.message.content);
            }
        });