Getting Started with the Servoy AI Runtime Plugin

Servoy AI Runtime Plugin tutorial series hero image

This is a Servoy Tutorial on getting started with the Servoy AI Runtime Plugin, which ships with Servoy 2025.12 and later. If you have been watching the AI space from the sidelines, waiting for a native Servoy way to build AI features without wiring up REST calls by hand, your wait is over. The plugins.ai plugin is built on Langchain4j, it is MIT licensed, and it gives you a clean, builder-pattern API for chat completions, embeddings, vector stores, and tool calling right out of the box.

I am going to walk you through your first chat completion, streaming responses, conversation memory, vector embeddings, and a realistic scenario where semantic search replaces a LIKE query that nobody loved anyway. By the end of this tutorial, you will have working code you can adapt to your own projects.

What Is the AI Runtime Plugin and Why Should You Care?#

The AI Runtime Plugin gives you a clean builder-pattern API for chat completions, embeddings, vector stores, and tool calling. It supports OpenAI and Google Gemini out of the box, and the two providers have identical API surfaces, so switching between them is a one-line change. The plugin operates on a Bring-Your-Own-Key model, so you provision your own API keys from OpenAI or Google and manage them yourself.

Bottom-line, if you are building AI features in Servoy, start with plugins.ai. You can always drop down to the HTTP plugin if you need a provider it does not cover yet (Claude support is on the roadmap), but for OpenAI and Gemini, this is the path of least resistance.

Before we write any code, there is one thing you need to do: put your API key in servoy.properties. Never hardcode API keys. The official recommendation from Servoy’s AI guide is:

1
    /**@type {String}*/
2
const sApiKey = application.getServoyProperty('openai_api_key');

Add a line like openai_api_key=sk-your-key-here to your servoy.properties file and you are ready. For Gemini, use gemini_api_key. Every code example in this article uses this pattern. If you see application.getServoyProperty() and wonder what it is, now you know.

A Quick Note on Promises#

The AI Runtime Plugin’s chat() method returns a JavaScript Promise. If you have not worked with Promises in Servoy before, the short version is that client.chat(prompt) does not block. It immediately returns a Promise object, and you attach handlers with .then() for success and .catch() for errors. The runtime fires the handlers when the response comes back from the model.

Okay, let’s get started.

Your First Chat Completion#

Let’s build the simplest possible thing: a function that sends a prompt to GPT-4o and logs the response. Here is the complete function:

1
/**
2
 * Sends a prompt to OpenAI and logs the response.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 *
7
 * @param {String} sPrompt the prompt to send
8
 */
9
function sendFirstPrompt(sPrompt) {
10
    try {
11
            /**@type {String}*/
12
        const sApiKey = application.getServoyProperty('openai_api_key');
13

14
            /**@type {plugins.ai.ChatClient}*/
15
        const oClient = plugins.ai.createOpenAiChatBuilder()
16
            .apiKey(sApiKey)
17
            .modelName('gpt-4o')
18
            .addSystemMessage('You are a helpful assistant for our ERP system.')
19
            .build();
20

21
        oClient.chat(sPrompt).then(function(oResponse) {
22
                /**@type {String}*/
23
            const sAnswer = oResponse.getResponse();
24
                /**@type {Number}*/
25
            const iTokens = oResponse.getTokenUsage().totalTokenCount();
26
            application.output('AI response: ' + sAnswer);
27
            application.output('Tokens used: ' + iTokens);
28
        }).catch(function(oError) {
29
            application.output('AI call failed: ' + oError.message, LOGGINGLEVEL.ERROR);
30
        });
31
    } catch (e) {
32
        application.output('Error in sendFirstPrompt: ' + e.message, LOGGINGLEVEL.ERROR);
33
        plugins.dialogs.showErrorDialog('Error', 'AI call failed: ' + e.message, 'OK');
34
    }
35
}

Let’s walk through what is happening here:

API key from servoy.properties: application.getServoyProperty('openai_api_key') reads from your servoy.properties file, which keeps the key out of your source code and out of version control.
createOpenAiChatBuilder(): This is the entry point. The builder pattern lets you chain configuration calls and then .build() to get your client. Note the casing: createOpenAiChatBuilder has a lowercase i. The plugin also has a createOpenAIClient shortcut (capital AI) for one-off prompts where you do not need the builder, but the builder is what you will use in practice.
modelName(‘gpt-4o’): You are telling the plugin which model to use. gpt-4o is a good general-purpose choice. For cheaper calls on simpler tasks, gpt-3.5-turbo works well. For tasks that need deep reasoning, the o1 or o3-mini models are available and you can access their reasoning output via oResponse.getThinking().
addSystemMessage: The system message sets the role, tone, and boundaries for the model. Think of it like a scope-level set of defaults that configure how the model behaves for every message in the session.
build(): Returns the chat client, ready to send prompts.
client.chat(prompt): Returns a Promise that resolves to a ChatResponse object.
getResponse(): Pulls out the response text.
getTokenUsage().totalTokenCount(): Returns the total token count for the call. This is important because you are paying per token. Get into the habit of logging this. You cannot optimize what you are not measuring.

The .catch() handler catches any errors from the model call itself, such as network failures or authentication problems. The outer try/catch handles synchronous failures during the client setup.

Expected Output (calling sendFirstPrompt("In two sentences, what is a foundset in Servoy?")):

1
AI response: In Servoy, a foundset is a collection of records from a database table that
2
you can work with in your application, similar to a record set or data set. It allows you
3
to display, navigate, and manipulate data within forms, and you can apply searches and
4
sorts to tailor the set of records you're working with.
5
Tokens used: 121

Make sense? You just called GPT-4o from Servoy in about twenty lines of code.

Switching to Gemini#

The Gemini builder has the exact same API surface. Every method name, every parameter, every return type is identical. Switching providers is literally swapping the builder:

1
    /**@type {plugins.ai.ChatClient}*/
2
const oClient = plugins.ai.createGeminiChatBuilder()
3
    .apiKey(application.getServoyProperty('gemini_api_key'))
4
    .modelName('gemini-3-pro')
5
    .addSystemMessage('You are a helpful assistant for our ERP system.')
6
    .build();

Everything else stays the same. Same .chat() call, same .then() handler, same ChatResponse methods. This is pretty sweet if you are evaluating providers or if your organization wants to avoid vendor lock-in.

Streaming Responses#

The Promise form of chat() waits until the entire response is ready and delivers it in one shot. That works, but if the model is generating a long answer, your user is staring at a loading spinner for five to ten seconds wondering if something broke. Streaming fixes this by delivering partial text chunks as the model generates them, so the user sees words appearing in real time.

The streaming form uses three callbacks instead of a Promise:

1
/**
2
 * Sends a prompt with streaming output.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-17
5
 * @public
6
 *
7
 * @param {String} sPrompt the prompt to send
8
 */
9
function sendStreamingPrompt(sPrompt) {
10
    try {
11
            /**@type {String}*/
12
        const sApiKey = application.getServoyProperty('openai_api_key');
13

14
            /**@type {plugins.ai.ChatClient}*/
15
        const oClient = plugins.ai.createOpenAiChatBuilder()
16
            .apiKey(sApiKey)
17
            .modelName('gpt-4o')
18
            .addSystemMessage('You are a helpful assistant.')
19
            .build();
20

21
            /**@type {Number}*/
22
        const iStartTime = new Date().getTime();
23

24
        oClient.chat(sPrompt,
25
            // partial response callback: fired for each text chunk
26
            function(sPartial) {
27
                elements.chat_output.text += sPartial;
28
            },
29
            // completion callback: fired once when the full response is done
30
            function(oResponse) {
31
                    /**@type {Number}*/
32
                const iElapsed = new Date().getTime() - iStartTime;
33
                    /**@type {Number}*/
34
                const iTokens = oResponse.getTokenUsage().totalTokenCount();
35
                application.output('Done in ' + iElapsed + 'ms, ' + iTokens + ' tokens');
36
            },
37
            // error callback
38
            function(oError) {
39
                application.output('Streaming error: ' + oError.message, LOGGINGLEVEL.ERROR);
40
            }
41
        );
42
    } catch (e) {
43
        application.output('Error in sendStreamingPrompt: ' + e.message, LOGGINGLEVEL.ERROR);
44
    }
45
}

A few things to notice:

The streaming form does not return a Promise. It is void. You do not chain .then() on it. All the work happens inside the three callbacks.
The partial callback receives raw string chunks. Each chunk is a fragment of the response as the model generates it. You append them to a UI element so the user sees the text building up character by character.
The completion callback receives the full ChatResponse. At this point, oResponse.getResponse() has the complete text, and getTokenUsage() has the final token count. This is where you log, save, or do any post-processing.
The error callback works like .catch(). If the model call fails, this fires instead of the completion callback.

For any feature where the user sees the AI response directly (chat interfaces, document summarization, help assistants), use streaming. The difference in perceived responsiveness is dramatic. For background tasks where no user is waiting, the Promise form is cleaner.

Adding Conversation Memory#

One prompt in isolation is not very useful. Real conversations need context. Chat models do not actually preserve any state between calls; the illusion of a continuous conversation is created by sending the chat history with every call. The plugin handles this for you when you enable memory on the builder.

1
/**
2
 * Cached chat client with conversation memory.
3
 * @type {plugins.ai.ChatClient}
4
 */
5
var _oChatClient = null;
6

7
/**
8
 * Gets or creates the chat client, preserving memory across calls.
9
 * @author Gary Dotzlaw
10
 * @since 2026-04-17
11
 * @private
12
 *
13
 * @return {plugins.ai.ChatClient} the cached chat client
14
 */
15
function _getChatClient() {
16
    if (_oChatClient) {
17
        return _oChatClient;
18
    }
19

20
        /**@type {String}*/
21
    const sApiKey = application.getServoyProperty('openai_api_key');
22

23
    _oChatClient = plugins.ai.createOpenAiChatBuilder()
24
        .apiKey(sApiKey)
25
        .modelName('gpt-4o')
26
        .maxMemoryTokens(5000)
27
        .addSystemMessage('You are a sales assistant. Help users find information about customers and orders.')
28
        .build();
29

30
    return _oChatClient;
31
}
32

33
/**
34
 * Clears the conversation memory by resetting the client.
35
 * @author Gary Dotzlaw
36
 * @since 2026-04-17
37
 * @public
38
 */
39
function clearConversation() {
40
    _oChatClient = null;
41
}

With maxMemoryTokens(5000), the client will remember up to 5000 tokens of prior conversation. Think of tokens like characters in a SQL query limit: roughly a word or word fragment each. 5000 tokens is enough for a back-and-forth conversation with maybe 20-25 exchanges before older context starts getting dropped.

The critical pattern here is caching the client in a form variable. If you build a new client on every call, you get a new empty memory every time, which defeats the point entirely. Build it once, reuse it, and null it out when you want to start a fresh conversation. This is the exact pattern the official Example Solution uses, and it is the correct one.

Keep in mind your costs per token and your feature requirements when setting the maxMemoryTokens value. More memory means richer conversation context but also more tokens sent with every call, which means higher cost per interaction.

Multimodal Input: Images, Audio, and Documents#

Before moving on to embeddings, it is worth knowing that the chat client can accept more than just text. The addFile() and addBytes() methods let you attach images, audio, video, PDFs, and text files to a chat prompt. Here is a full working example that attaches a PDF from the file system and asks a question about it:

1
/**
2
 * Multimodal input: attach a file and ask a question about it.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-17
5
 * @public
6
 */
7
function askAboutFile() {
8
    try {
9
            /**@type {String}*/
10
        const sApiKey = application.getServoyProperty('openai_api_key');
11

12
            /**@type {plugins.ai.ChatClient}*/
13
        const oClient = plugins.ai.createOpenAiChatBuilder()
14
            .apiKey(sApiKey)
15
            .modelName('gpt-4o')
16
            .addSystemMessage('You are a document assistant.')
17
            .build();
18

19
        // Option A: from media
20
        //    var aBytes = solutionModel.getMedia('test_doc.pdf').bytes;
21
        //    oClient.addBytes(aBytes, 'application/pdf');
22

23
        // Option B: from file system
24
            /**@type {plugins.file.JSFile}*/
25
        const oFile = plugins.file.convertToJSFile('/path/to/a/small/test.pdf');
26

27
        oClient.addFile(oFile).chat('What is this document about?').then(function(oResponse) {
28
            application.output('addFile response: ' + oResponse.getResponse().substring(0, 100));
29
        }).catch(function(oError) {
30
            application.output('addFile failed: ' + oError.message, LOGGINGLEVEL.ERROR);
31
        });
32
    } catch (e) {
33
        application.output('Error in askAboutFile: ' + e.message, LOGGINGLEVEL.ERROR);
34
    }
35
}

Expected Output:

1
addFile response: This document serves as a quick reference guide for a team using "Copilot Agent Workflows" within a...

The addFile() method accepts a JSFile or a String path on the server, auto-detects the content type, and chains back to the client so you can call .chat() right after. If you need to specify the content type explicitly, use addFile(oFile, 'application/pdf'). The addBytes() variant accepts raw byte arrays for content that is already in memory.

Supported content types include image/*, video/*, audio/*, application/pdf, and text/*. This opens up use cases like extracting structured data from scanned invoices, transcribing audio notes, or asking questions about uploaded documents.

Your First Vector Embedding#

Chat completions are fun, but embeddings are where things get really interesting for Servoy developers. An embedding is a numeric representation of meaning. Two pieces of text that mean similar things produce similar embeddings, even if they share no words in common. Think of it like an index on a column, but instead of indexing exact values, it indexes meaning.

Here is the simplest possible embedding example:

1
/**
2
 * Embeds a few strings and searches them by meaning.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-12
5
 * @public
6
 */
7
function firstEmbeddingTest() {
8
        /**@type {String}*/
9
    const sApiKey = application.getServoyProperty('openai_api_key');
10

11
        /**@type {plugins.ai.EmbeddingModel}*/
12
    const oEmbeddingModel = plugins.ai.createOpenAiEmbeddingModelBuilder()
13
        .apiKey(sApiKey)
14
        .modelName('text-embedding-3-small')
15
        .build();
16

17
        /**@type {plugins.ai.EmbeddingStore}*/
18
    const oStore = oEmbeddingModel.createInMemoryStore();
19

20
        /**@type {Array<String>}*/
21
    const aTexts = [
22
        "Customer called about a late shipment, very upset",
23
        "Product returned due to defective packaging",
24
        "Annual review went well, customer is happy with service",
25
        "Urgent complaint about billing errors on the last invoice"
26
    ];
27

28
    oStore.embed(aTexts, []).then(function() {
29
            /**@type {Array<plugins.ai.SearchResult>}*/
30
        const aResults = oStore.search('unhappy customers', 3);
31
        application.output('Found ' + aResults.length + ' similar notes');
32
        aResults.forEach(function(oResult) {
33
            application.output('  Score ' + oResult.getScore().toFixed(3) + ': ' + oResult.getText());
34
        });
35
    }).catch(function(oError) {
36
        application.output('Embedding failed: ' + oError.message, LOGGINGLEVEL.ERROR);
37
    });
38
}

Let’s walk through this:

createOpenAiEmbeddingModelBuilder(): Similar to the chat builder. You configure it with an API key and a model name. text-embedding-3-small is cheap and fast, which is what you want for most embedding work. If you need the vector dimension for database column sizing, call oEmbeddingModel.getDimension() after building. For text-embedding-3-small, that is 1536.
createInMemoryStore(): The vector store is created from the embedding model itself, not from plugins.ai. This is a common source of confusion. Call oEmbeddingModel.createInMemoryStore(). The store lives in memory, which is perfect for development and testing. For production, you will want PgVector, which I cover in Article 3.
store.embed(texts, metadata): Takes an array of strings and a parallel array of metadata objects. Both arguments are required. If you do not have per-text metadata, pass an empty array [] as the second argument. Omitting it causes a runtime error because the Java signature requires both parameters. This returns a Promise, so you do not run the search until the embeddings are actually in the store.
store.search(query, maxResults): Runs a similarity search and returns results synchronously. Always pass maxResults explicitly; the default is only 3. Each result has .getText(), .getScore(), and .getMetadata() methods.

Notice that the search query is “unhappy customers” but none of the stored notes contain those exact words. The search still returns the ones about the upset customer, the billing complaint, and the defective product, because those notes are semantically similar to “unhappy customers.”

Expected Output:

1
Found 3 similar notes
2
  Score 0.739: Customer called about a late shipment, very upset
3
  Score 0.703: Annual review went well, customer is happy with service
4
  Score 0.686: Urgent complaint about billing errors on the last invoice

A LIKE query would never find these results. A full-text index would need the exact words or aggressive stemming. Semantic search does not care about word overlap. It cares about meaning.

A Realistic Scenario: Searching Products by Meaning#

Let’s take this to a real scenario. The example_data server that ships with Servoy has a products table with 77 rows, each with a productname and a product_desc column. Imagine a user wants to find all products related to “spicy hot condiments.” The word “spicy” may not appear in every product’s name or description, and a LIKE query against “spicy” will miss Louisiana Hot Sauce, Cajun seasoning, pepper sauces, and anything else that is clearly spicy but uses different words.

Here is how you solve this with plugins.ai:

1
/**
2
 * Indexes product names and descriptions into an in-memory embedding store.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-17
5
 * @public
6
 *
7
 * @return {Promise<plugins.ai.EmbeddingStore>} resolves with the populated store
8
 */
9
function buildProductIndex() {
10
        /**@type {String}*/
11
    const sApiKey = application.getServoyProperty('openai_api_key');
12

13
        /**@type {plugins.ai.EmbeddingModel}*/
14
    const oEmbeddingModel = plugins.ai.createOpenAiEmbeddingModelBuilder()
15
        .apiKey(sApiKey)
16
        .modelName('text-embedding-3-small')
17
        .build();
18

19
        /**@type {plugins.ai.EmbeddingStore}*/
20
    const oStore = oEmbeddingModel.createInMemoryStore();
21

22
        /**@type {QBSelect}*/
23
    const query = datasources.db.example_data.products.createSelect();
24
    query.result.add(query.columns.productname);
25
    query.result.add(query.columns.product_desc);
26
        /**@type {JSDataSet}*/
27
    const dsProducts = databaseManager.getDataSetByQuery(query, 5000);
28

29
        /**@type {Array<String>}*/
30
    const aTexts = [];
31
    for (let i = 1; i <= dsProducts.getMaxRowIndex(); i++) {
32
            /**@type {String}*/
33
        const sName = dsProducts.getValue(i, 1) || '';
34
            /**@type {String}*/
35
        const sDesc = dsProducts.getValue(i, 2) || '';
36
        aTexts.push(sName + ' ' + sDesc);
37
    }
38

39
    return oStore.embed(aTexts, []).then(function() {
40
        application.output('Indexed ' + aTexts.length + ' products');
41
        return oStore;
42
    });
43
}
44

45
/**
46
 * Searches products by meaning instead of keywords.
47
 * @author Gary Dotzlaw
48
 * @since 2026-04-17
49
 * @public
50
 *
51
 * @param {plugins.ai.EmbeddingStore} oStore the embedding store
52
 * @param {String} sQuery the natural-language search query
53
 */
54
function searchProducts(oStore, sQuery) {
55
    try {
56
            /**@type {Array<plugins.ai.SearchResult>}*/
57
        const aResults = oStore.search(sQuery, 5);
58
        application.output('Query: ' + sQuery);
59
        application.output('Found ' + aResults.length + ' semantically similar products');
60
        aResults.forEach(function(oResult) {
61
            application.output('  Score ' + oResult.getScore().toFixed(3) + ': ' + oResult.getText());
62
        });
63
    } catch (e) {
64
        application.output('Error in searchProducts: ' + e.message, LOGGINGLEVEL.ERROR);
65
    }
66
}

To use this, call buildProductIndex() once to build the store, then call searchProducts() inside the .then() callback:

1
/**
2
 * Demo: build the index and run a search.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-17
5
 * @public
6
 */
7
function runSearchDemo() {
8
    buildProductIndex().then(function(oStore) {
9
        searchProducts(oStore, 'spicy hot condiments');
10
    }).catch(function(oError) {
11
        application.output('Demo failed: ' + oError.message, LOGGINGLEVEL.ERROR);
12
    });
13
}

Call runSearchDemo() and watch it return products like Louisiana Fiery Hot Pepper Sauce, Cajun Seasoning, and Frankfurter grüne Soße. The word “spicy” does not appear in most of those product names. A LIKE query against “spicy” would have missed them all.

Expected Output:

1
Indexed 77 products
2
Query: spicy hot condiments
3
Found 5 semantically similar products
4
  Score 0.792: Louisiana Fiery Hot Pepper Sauce
5
  Score 0.733: Louisiana Hot Spiced Okra
6
  Score 0.680: Chef Anton's Cajun Seasoning
7
  Score 0.673: Original Frankfurter grüne Soße
8
  Score 0.665: Chef Anton's Gumbo Mix

Five results, ranked by semantic similarity. The top match scores 0.79, and even the weakest match at 0.67 is still clearly a spicy or hot product. None of the results contain the word “spicy” in their product name, yet every one of them is exactly what the user meant.

The advantages of this approach are clear:

Users find what they mean, not what they typed. No more teaching users to guess the exact keywords.
No stemming or full-text index maintenance. The embedding model handles linguistic variation.
Works across synonyms and paraphrases. “Angry customer” matches “furious client” matches “irate buyer.”
Ranked by relevance. Results come back with similarity scores so you can show the best matches first.

Keep in mind that the in-memory store is fine for development and small datasets. The embeddings live only for the lifetime of the current runtime, so if the server restarts you re-embed everything. For production, use the persistent PgVector-backed store so your embeddings survive across sessions and you are not paying OpenAI every time your server restarts. I cover PgVector in Article 3 of this series.

Advanced: Chat With Your Data#

Still with me? Okay, let’s kick it up a notch. This next pattern is one of the more creative uses of the chat API, and it does not involve embeddings at all. The idea is simple: send your database schema to the LLM and let it write SQL for you based on a natural-language question. Then execute the SQL, and optionally send the results back through a second LLM call for a human-readable summary.

This is the pattern demonstrated in the Example Solution’s chatWithYourData form, and I can tell you it makes an impression the first time you see it work.

The first function gets the database schema and sends it to the model:

1
/**
2
 * Generates a SQL query from a natural-language question.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-17
5
 * @public
6
 *
7
 * @param {String} sQuestion the user's natural-language question
8
 * @param {String} sServerName the Servoy server name to query against
9
 * @return {Promise<String>} resolves with the generated SQL
10
 */
11
function generateSQLFromQuestion(sQuestion, sServerName) {
12
        /**@type {String}*/
13
    const sApiKey = application.getServoyProperty('openai_api_key');
14

15
        /**@type {String}*/
16
    const sSystemMessage = 'You are a SQL expert. You will be given a database schema in JSON ' +
17
        'format and a user question. Respond with a valid SQL query that answers the question. ' +
18
        'Only provide the SQL query as the response, nothing else.';
19

20
        /**@type {plugins.ai.ChatClient}*/
21
    const oClient = plugins.ai.createOpenAiChatBuilder()
22
        .apiKey(sApiKey)
23
        .modelName('gpt-4o')
24
        .addSystemMessage(sSystemMessage)
25
        .build();
26

27
        /**@type {Object}*/
28
    const oSchema = _getSchema(sServerName);
29

30
        /**@type {String}*/
31
    const sPrompt = 'Database Schema:\n' + JSON.stringify(oSchema) +
32
        '\n\nUser Question:\n' + sQuestion;
33

34
    return oClient.chat(sPrompt).then(function(oResponse) {
35
        return oResponse.getResponse();
36
    });
37
}

The _getSchema helper function introspects the database and returns it as JSON:

1
/**
2
 * Tables exposed to the chat-with-your-data model. Trimming the schema to just
3
 * the tables the question can touch keeps the prompt small and the call fast.
4
 * @type {Array<String>}
5
 */
6
const ALLOWED_TABLES = ['products', 'orders', 'order_details', 'customers'];
7

8
/**
9
 * Fetches the database schema for a Servoy server in JSON format.
10
 * Only includes tables listed in ALLOWED_TABLES.
11
 * @author Gary Dotzlaw
12
 * @since 2026-04-17
13
 * @private
14
 *
15
 * @param {String} sServerName the Servoy server name
16
 * @return {Object} the schema as a JSON-friendly object
17
 */
18
function _getSchema(sServerName) {
19
        /**@type {Object}*/
20
    const oSchema = {
21
        databaseType: databaseManager.getDatabaseProductName(sServerName),
22
        tables: []
23
    };
24

25
        /**@type {Array<String>}*/
26
    const aTableNames = databaseManager.getTableNames(sServerName);
27
    for (let i = 0; i < aTableNames.length; i++) {
28
            /**@type {String}*/
29
        const sTableName = aTableNames[i];
30
        if (ALLOWED_TABLES.indexOf(sTableName) === -1) {
31
            continue;
32
        }
33
            /**@type {Object}*/
34
        const oTable = databaseManager.getTable(sServerName, sTableName);
35
            /**@type {Array<String>}*/
36
        const aPKColumns = oTable.getRowIdentifierColumnNames();
37
            /**@type {Array<String>}*/
38
        const aColumns = oTable.getColumnNames();
39

40
            /**@type {Object}*/
41
        const oTableInfo = { table: sTableName, columns: [] };
42
        for (let j = 0; j < aColumns.length; j++) {
43
                /**@type {String}*/
44
            const sColName = aColumns[j];
45
                /**@type {Object}*/
46
            const oColumn = oTable.getColumn(sColName);
47
            oTableInfo.columns.push({
48
                name: sColName,
49
                type: oColumn.getTypeAsString(),
50
                length: oColumn.getLength(),
51
                description: oColumn.getDescription(),
52
                title: oColumn.getTitle(),
53
                fkForTableName: oColumn.getForeignType(),
54
                isPK: aPKColumns.indexOf(sColName) !== -1
55
            });
56
        }
57
        oSchema.tables.push(oTableInfo);
58
    }
59
    return oSchema;
60
}

And then you bring it all together, executing the generated SQL and summarizing the results:

1
/**
2
 * Asks a question about your data and gets a natural-language answer.
3
 * @author Gary Dotzlaw
4
 * @since 2026-04-17
5
 * @public
6
 *
7
 * @param {String} sQuestion the user's natural-language question
8
 * @param {String} sServerName the Servoy server name
9
 */
10
function askYourData(sQuestion, sServerName) {
11
    try {
12
        plugins.svyBlockUI.show('Thinking...');
13
        generateSQLFromQuestion(sQuestion, sServerName).then(function(sRawSQL) {
14
            // Strip markdown code fences that the model sometimes adds around the SQL
15
                /**@type {String}*/
16
            const sSQL = sRawSQL.replace(/```sql\s*|```/g, '').trim();
17
            application.output('Generated SQL: ' + sSQL);
18

19
                /**@type {JSDataSet}*/
20
            const dsResult = databaseManager.getDataSetByQuery(sServerName, sSQL, null, 1000);
21
                /**@type {String}*/
22
            const sCSV = dsResult.getAsText(',', '\n', '"', true);
23

24
            // Second LLM call: summarize the results in plain language
25
                /**@type {plugins.ai.ChatClient}*/
26
            const oSummaryClient = plugins.ai.createOpenAiChatBuilder()
27
                .apiKey(application.getServoyProperty('openai_api_key'))
28
                .modelName('gpt-4o')
29
                .addSystemMessage('You are a data expert. Given a user question and a CSV dataset, ' +
30
                    'provide a concise, accurate answer. Include relevant data and observations.')
31
                .build();
32

33
                /**@type {String}*/
34
            const sSummaryPrompt = 'User Question:\n' + sQuestion +
35
                '\n\nDataset in CSV format:\n' + sCSV;
36

37
            return oSummaryClient.chat(sSummaryPrompt);
38
        }).then(function(oResponse) {
39
            application.output('Answer: ' + oResponse.getResponse());
40
        }).catch(function(oError) {
41
            application.output('askYourData failed: ' + oError.message, LOGGINGLEVEL.ERROR);
42
        }).finally(function() {
43
            plugins.svyBlockUI.stop();
44
        });
45
    } catch (e) {
46
        application.output('Error in askYourData: ' + e.message, LOGGINGLEVEL.ERROR);
47
        plugins.svyBlockUI.stop();
48
    }
49
}

Call askYourData("What are the top 5 best selling products?", "example_data") and watch the model write the SQL, execute it against your database, and come back with a plain-language answer drawn from your actual data.

Expected Output:

1
Generated SQL: SELECT p.productname, SUM(od.quantity) AS total_quantity_sold
2
FROM order_details od
3
JOIN products p ON od.productid = p.productid
4
GROUP BY p.productname
5
ORDER BY total_quantity_sold DESC
6
LIMIT 5;
7

8
Answer: Based on the dataset provided, the top 5 best selling products are:
9

10
1. Camembert Pierrot with 1,577 units sold.
11
2. Raclette Courdavault with 1,496 units sold.
12
3. Gorgonzola Telino with 1,397 units sold.
13
4. Gnocchi di nonna Alice with 1,263 units sold.
14
5. Pavlova with 1,158 units sold.
15

16
These products have the highest total quantities sold as per the dataset.

Notice two things. First, the LLM picked the right join — order_details.productid to products.productid — even though the question did not mention tables or columns by name. The model inferred the join path from the schema JSON alone. Second, the answer summarizes the CSV it received in plain English, adding natural-language framing around the raw numbers. One pass generated the SQL, a second pass narrated the result. The user asked a question, the agent answered it.

A couple of important caveats. This pattern gives the LLM indirect read access to your database. Make sure you are comfortable with that from a security perspective before exposing it to users. The LLM-generated SQL should be treated as untrusted input; consider running it with a read-only database connection or restricting the tables visible in the schema. And obviously, never let the model generate INSERT, UPDATE, or DELETE statements through this pattern.

The ChatResponse: Everything It Can Tell You#

Before we close, here is the full list of methods on the ChatResponse object. You have already seen getResponse() and getTokenUsage(), but the others are useful for logging, debugging, and working with newer models:

getResponse() returns the full response text.
getPrompt() returns the original user prompt that produced this response. Useful for logging.
getId() returns a unique identifier. Correlate this with your provider’s dashboard when debugging.
getFinishReason() returns why the model stopped. Normal completion, token limit, tool call, etc.
getTokenUsage() returns a TokenUsage object. Call .inputTokenCount(), .outputTokenCount(), and .totalTokenCount() on it. These are method calls, not properties; do not forget the parentheses.
getThinking() returns the reasoning text from models like OpenAI’s o1 series or Gemini 2.5 Pro. Returns null for models that do not support reasoning (like gpt-4o). Useful for debugging agentic workflows where you need to see why the model made a decision.

What Comes Next#

This tutorial covered the foundation: chat completions, streaming, conversation memory, provider switching, embeddings, similarity search, and the chat-with-your-data pattern. The AI Runtime Plugin has several more capabilities that deserve their own articles:

Tool calling lets you register Servoy functions as tools the LLM can invoke during reasoning. The agent decides when to call them. This is how you build agentic workflows where the AI actually does things in your Servoy solution instead of just answering questions. That is Article 2.
FoundSet embedding and PgVector stores let you embed database records directly with primary keys preserved as metadata, and persist those embeddings in PostgreSQL so they survive server restarts. That is Article 3.
QBVectorColumn and hybrid queries let you combine semantic similarity with traditional SQL WHERE clauses in a single query. Products semantically similar to “lightweight laptop for travel” filtered to under $2,000 and in stock, in one database round-trip. That is Article 4.

I will cover each of these in the following tutorials. For now, get comfortable with the basics. Set up an API key, put it in your servoy.properties, try the chat builder, embed a few strings, and run a similarity search. Once the basics click, the advanced features will make a lot more sense.

That concludes this Servoy tutorial on getting started with the AI Runtime Plugin. I hope you enjoyed it, and I look forward to bringing you more Servoy tutorials on AI integration in the future.

The Series#

This is Part 1 of a four-part series on the Servoy AI Runtime Plugin:

Getting Started with the Servoy AI Runtime Plugin (this article). Chat completions, streaming, conversation memory, embeddings, and your first semantic search.
Tool Calling with the AI Runtime Plugin: Agentic Servoy. Register Servoy methods as tools and let the LLM decide when to call them.
Embedding Your Servoy Data for Semantic Search. PgVector production stores, FoundSet embedAll(), and PDF document chunking.
Hybrid Queries with QBVectorColumn: Semantic Meets SQL. Combine semantic similarity with traditional WHERE clauses in a single database round-trip.