AI Services Follow

With AI services, your AuraPlayer projects can connect to Google Gemini, in order to run tasks, retrieve or process data.
We'll introduce AI services by going through 2 examples.

Gemini account Configuration

To use AI services, you'll need to create a Google Gemini account and aquire an API Key.
With those in hand, fill in the following in your ServiceManager->Admin->System Properties:

Environment Variables

AI_KEY = <your Gemini API Key>
AI_MODEL = gemini-2.5-flash    (or any other model)

System Properties

AI_URL = https://generativelanguage.googleapis.com/v1beta/models/${env.AI_MODEL}:generateContent?key=${env.AI_KEY}

You may also add AI_KEY to PROTECTED_FIELDS, if you wish to mask your Gemini Key (like a password).

Creating an AI service - Big Cities example

From your ServiceManager, create an AI service by going to Services -> + -> AI Service.
Fill in the following fields:

• AI Prompt:  Instructions what the AI should do.
• Input Parameters: Add any inputs, that shall be passed to Gemini.
• AI Output Instructions: describe the general role of the outputs (may be empty for simple use cases).
• Output Parameters: Add any outputs, and fill in additional description about each output or how to locate/calculate it (may be empty for simple use cases).

Save and run the service.

This example service is attached at the bottom of this document.

Response of AI service

The response appears in a standard AuraPlayer response format:

The StatusBarMessages will indicate the amount of tokens used (which affects your Gemini quota/billing) - you may monitor the token usage as you try different inputs.

Advanced feature: Optional Prompt

For added flexibilly, AI services can include/exclude parts of the prompt based on the input.

In the above example, the AI Prompt includes an instruction enclosed via {{#northOf}} ... {{/northOf}}:
This instruction will be included in the prompt sent to Gemini only if the northOf input parameter ISN'T empty.
The value of the parameter can be referenced via ${northOf}, like any other parameter.

Try running the service above with an empty northOf input, and see how the response changes.

Advanced feature: Fine turning AI's response

In the ServiceEditor, under the Advanced Details section, you will find the LLM's AI Generation parameters:

These settings allow you to balance creativity (higher T/P/K) with determinism (lower T/P/K) for different use cases, from creative writing to technical tasks.

They control the randomness and diversity of generated text by adjusting how tokens (words/subwords) are selected, with Temperature scaling probabilities (higher = more creative), Top-K limiting to the 'K' most likely words, and Top-P selecting a dynamic set of words whose cumulative probability exceeds 'P':

By hovering above the ? next to each parameter, you will see a short reminder of their role:

• Temperature controls randomness/creativity.
  Lower temperatures -> less risky, more conservative answers.
• TopK is the safety net: it chooses K most probable results.
  Lower TopK ->  filter out more incoherent tokens.
• TopP is the confidence threshold. 
  Results are added until their redistributed cumulative probability exceeds p.

Advanced feature: File Input Parameters

The AI service may pass a file to the AI engine for processing, exatracting information, or as a suplemental knowledge. 

In the following example we send a Purchase Order (PO) pdf file to Gemini, to extract various fields.
In this usecase, AI's advantage over standard OCR is the ability to use reasoning, and identify fields in (sometimes very) different PO formats, in which fields don't appear in the same place nor under the same name. 

To use a file input, add a new input parameter with a name by your choice, mark the "Is File" checkbox.

The file can be provided in one of two formats: base64 or as a path.
When providing a path, it must be a readable path on the ServiceManager server's file system - it is the caller's/application's repsonsibility to upload the file to the server.

For the full PO2SO implementation, please contact AuraPlayer.

Attachments