AI - Communication with Artificial Intelligence

Basic AI concepts

Now implemented communication and API for OpenAI ChatGPT.
There are two ways to use FastGrid AI, by purchasing AI credits from TreeGrid (COQsoft) or by purchasing OpenAI API key directly from OpenAI.
Both the ways have the same prices per token, except you have some enterprise level in OpenAI.

AI credits from TreeGrid (COQsoft)

By default, FastGrid uses AI bridge at https://www.treegrid.net/AI set to AI tag Url attribute.
There are a few free AI credits available for FastGrid AI evaluation that will be used by default without purchased credit.

To continue larger evaluation or to develop your application(s) with FastGrid AI, you need to purchase AI credits in our e-shop at https://www.treegrid.com/Purchase?ai=100.
Purchased credits can be passed to FastGrid in AI tag Credit or entered directly to FastGrid in AI settings menu.
If the credit is entered to FastGrid in AI settings, it is stored in browser local storage for actual server, so after clearing the storage or using different browser or server, the credit must be entered again.

The purchased credits can be used in any FastGrid location (localhost, treegrid.com, any your server, any your customer server, ...) and in any web browser, and all its usage is shared and spends the credit.
The actual budget, spent credits and prompt price are shown in AI output for every prompt, when set Cfg attribute AIOutputPrice&1 or set the option Show prompt price in AI settings menu.

The prompt cost can vary per model and prompt complexity.
Nano model costs from 0.2 cent for simple grid control to 10 cents for complex generating sheet from web search. Nano model is ideal for the most grid controls and also for many complex tasks. It is also the fastest model.
Mini model costs from 0.5 cent for simple grid control to 20 cents for complex generating sheet from web search.
Codex model costs from 2 cents for simple grid control to 50 cents for complex generating sheet from web search. This model can be also prioritized to speed up, but for double price.
Standard model costs from 8 cents for simple grid control to 80 cents for complex generating sheet from web search. This model can be also prioritized to speed up, but for double price.
Pro model costs from 1 USD for simple grid control to 5 USD for complex generating sheet from web search. Using Pro model has sense only for really complex tasks if other models fail. It is also the slowest model.

Using CQOsoft credits is good for development or small production projects; for larger production projects purchase your own OpenAI API key, see next paragraph.

OpenAI API key

To use OpenAI with FastGrid in larger production, you should have your own API account on OpenAI (https://platform.openai.com/docs/quickstart).

Create your API key and set it to FastGrid AI communication settings:
For development you can set it directly to OpenAI Responses API as AI: { Url: "https://api.openai.com/v1/responses", Header: { Authorization: "Bearer ..." } }.
For production you should create your server side url to be used as a bridge between FastGrid and OpenAI and pass its url to AI: { Url:"..." }. This server side code will read the request from FastGrid and pass it to https://api.openai.com/v1/responses with added HTTP header with the API key. And read the OpenAI responses and pass them back to FastGrid. To not reveal your secret API key to your visitors.

If AI is permitted to search Internet by WebSearch, set or clear the AI UrlDownload as URL for downloading files without CORS.
Otherwise all the downloads will go through our server url https://www.treegrid.net/AIGet.

AI toolbar

Add AI toolbar to the grid, usually to grid Bottom by Bottom:["AI"].
In Sheet the AI toolbar is shown (on top) by default, if you want to not use AI, hide it by Bottom:[{id:"AI",Hidden:1}].

AI descriptions

Next you should precisely describe your grid to AI, its structure, data, sense and behavior, in AI: { StaticInstructions:"..." } or dynamically in API event OnAIGetStaticInstructions.
For start and base testing you can use built-in instructions and set only grid Description.

Next you should precisely describe your grid actual state and settings to AI in AI: { DynamicInstructions:"..." } or dynamically in API event OnAIGetDynamicInstructions.
For start and base testing you can use built-in instructions.

In Sheet the specific descriptions are usually not required, if the sheets content can vary.

Basic AI settings

All AI definitions, internal settings, tools and instructions. The AI settings changeable by users are in Cfg tag in attributes starting by by "AI". AI identification to control all the other features. Now it can be only to "OpenAI" for OpenAI ChatGPT. URL to communicate with AI. It uses standard OpenAI Responses API communication.
Default URL is "https://www.treegrid.net/AI" and it can be used only with purchased credits.
For testing or development with OpenAI key it can be set directly to OpenAI Responses AI Url: "https://api.openai.com/v1/responses".
In this case must be set also Header with OpenAI API credentials as Header:{ Authorization: "Bearer ...." }.
HTTP Headers added to every communication with Url. Credit purchased from TreeGrid (COQsoft) to use AI with default AI bridge on https://www.treegrid.net/AI set to Url.
The credit can be purchased in e-shop at https://www.treegrid.com/Purchase?ai=100.
This attribute should be used only for testing and development, because it can be read by users.
See purchasing AI credits.

For production use server side bridge between client and treegrid.net and pass this credit value to HTTP header "Fast-Grid" with comma after Fast-Grid header came from client side.
For example if incoming Fast-Grid HTTP header is "123456,abcd", pass the HTTP Fast-Grid header with credit as "123456,abcd,credit". Or as ",,credit", if no Fast-Grid header was present.
This credit is not needed and cannot be used if you use your own OpenAI API key. Available AI models that can be used for communication with AI. Actually chosen model is in Cfg AIModel.
The model definition is JSON object with AI API settings that set the model and related parameters. It is included to communication with AI API as is. The model definition can have also special Tools attribute that is not send to AI directly, but updates available tools like AI Tools attribute.
Actual AI model that will be used in communication with AI. One id from AI Models. JSON object with specific OpenAI API settings, included in every communication with AI API as is. It is automatically set during communication with AI to identify response thread. It can be saved to cookies to preserve the thread through reload.
If set, clears the AIResponseId on reload, when it was loaded from storage.

Instructions for AI

Full comprehensive description of actual grid, its data meaning, available features, restrictions and other related information for AI.
It can be in any language, but English is preferred.
It can contain only plain text. In the text use "\n\n" to separate paragraphs, "## Caption... \n" for major headings, "### Caption... \n" for minor headings, **major highlighted text**, or *minor highlighted text*.
This information is sent to AI API in every communication to let AI understand the grid.
If not set, there are used universal built-in instructions for any grid.
Setting it to "" uses the empty string and not the built-in instructions.
This information should not be changed during time or due changes in grid. Otherwise it breaks down AI caching and the AI usage could cost up to 10 times more.
Called to generate AI StaticInstructions by script.
instructions are actual instructions that will be used if the handler returns null.
The returned string should not be changed during time or due changes in grid. Otherwise it breaks down AI caching and the AI usage could cost up to 10 times more.
Universal description of FastGrid, its usage, exceptions and hints for AI.
It can be in any language, but English is preferred.
It can contain only plain text. In the text use "\n\n" to separate paragraphs, "## Caption... \n" for major headings, "### Caption... \n" for minor headings, **major highlighted text**, or *minor highlighted text*.
This information is sent with (after) StaticInstructions to AI API in every communication to let AI understand the grid.
It is usually not needed to set it, and use predefined built-in general FastGrid instructions.
Setting it to "" uses the empty string and not the built-in instructions.
This information should not be changed during time or due changes in grid. Otherwise it breaks down AI caching and the AI usage could cost up to 10 times more.
Called to generate AI GeneralInstructions by script.
instructions are actual instructions that will be used if the handler returns null.
The returned string should not be changed during time or due changes in grid. Otherwise it breaks down AI caching and the AI usage could cost up to 10 times more.
Description of grid actual state, its setting and data, actually available features, restrictions and other related information for AI.
It can be in any language, but English is preferred.
It can contain only plain text. In the text use "\n\n" to separate paragraphs, "## Caption... \n" for major headings, "### Caption... \n" for minor headings, **major highlighted text**, or *minor highlighted text*.
This information is sent to AI API in every communication after all other instructions to let AI understand the grid.
If not set, there are used universal built-in instructions for any grid.
Setting it to "" uses the empty string and not the built-in instructions.
This information should be as short as possible, because it is not cached by AI and its tokens cost 10 times more than in the other instructions.
Called to generate AI DynamicInstructions by script.
instructions are actual instructions that will be used if the handler returns null.
The returned string should be as short as possible, because it is not cached by AI and its tokens cost 10 times more than in the other instructions.
Grid description for AI. It should be in English language. It should describe the data meaning and the grid purpose.
It is used only if not set StaticInstructions.
Kind of the row or column for AI. Describe the assigned kinds in AI StaticInstructions and AI will distinguish the kinds in communication with user.
If it is not set and row has set Kind, it is used instead.
By default it is null for all rows and columns, only for Group rows it is set to "Group".

Built-in AI tools

Tools provided directly by AI vendor (OpenAI).
Now FastGrid uses only web search and image generation from built-in AI tools.
JSON objects with specific OpenAI API tools settings, included in every communication with AI API in tools array as they are.
Here are defined OpenAI specific tools like web search, image generation or mcp servers.
By default there are defined two tools, Web for web search and Image for image generation.
To disable particular already defined tool globally, redefine it as 0, e.g. Tools: { Web:0 } disables the web search for all models.
It is possible to define or disable the tools also per model by model Tools attribute that has the same format as this AI Tools attribute.
If AI is permitted to search information on Internet. 1 - yes, 0 - no, -1 no and cannot be enabled in menu.
If on, AI can use Internet search for its reasoning and also can download files from Internet to client.
Specific web search settings for OpenAI are defined in Tools in Web tag. URL bridge to download files on server side to avoid CORS problems.
If not set, files are loaded directly, but some can be refused due CORS (Cross-Origin Resource Sharing).
Files can be downloaded when AI is performing Internet search (WebSearch) or when a user explicitly requests AI to use some URL.
To this URL are sent only GET requests with query string as "?max,url", where max is maximal requested size of the downloaded data (MaxDownloadSize) and url is full URI to download the data from.
The URL should return text data from requested url and use standard HTTP status codes for errors.
Default URL is "https://www.treegrid.net/AIGet" and it can be used only for FastGrid evaluation, for all other purposes including development provide your own URL or empty string.
Timeout in millisecond for start downloading data or text files from Internet on AI requests.
If downloading takes longer time, it is stopped and to AI is passed error.
Timeout in millisecond for downloading all data or text files from Internet on AI requests.
Maximal time for downloading whole file. If downloading takes longer time, it is stopped and to AI is passed truncated data.
Maximal size in bytes of downloaded data or text file from Internet on AI requests.
Longer files are truncated and passed to AI.
This value is sent also to the UrlDownload.
Maximal count of files that can be downloaded for one prompt. Soft limit, just asks AI to not download more files. If AI is permitted to generate images. 1 - yes, 0 - no, -1 no and cannot be enabled in menu.
Specific image generation settings for OpenAI are defined in Tools in Image tag. Quality of generated images by AIImageGeneration.
0 - auto, 1 - low, 2 - medium, 3 - high.
If set negative, it is used as positive and cannot be changed by users in AI options.

FastGrid AI tools

FastGrid API functions that are called by AI to control the grid.
The FastGrid AI API functions are designed to use only for AI.
Calling the FastGrid AI API tool functions in static JavaScript code is strongly not recommended, because these AI API functions can be changed or even removed in future FastGrid versions or even builds.
List of available FastGrid functions for AI by the function name.
Actually there are only three functions defined:
Do - tool function to control grid; it is not available in sheet.
Run - tool function to control sheet; it is not available in grid.
Download - tool function to download data from given url in sheet; it is not available in grid. It is an usually faster but more expensive alternative to API function download usable in Run code.
Text used to fully describe the tool function, its parameters and usage to AI. It can be in any language, but English is preferred. List of function parameter descriptions by the function name.
The JavaScript function is called with one parameter as object containing all these listed properties.
If the parameter is required, its name should have "$R" suffix. With "C" use "$RC" suffix.
If the parameter can contain JavaScript code calling some APIFunctions, its name should have "$C" suffix. With "R" use "$RC" suffix.
The description is text to fully describe the parameter and its usage to AI. It can be in any language, but English is preferred.
The parameter type is string by default. To specify other type, define the parameter as object instead of string with properties { Type:"type", Desc:"description", Required:0/1 }.
The parameter type can be "array", "object", "boolean", "integer", "number" and empty string "" as any type.
Optional JavaScript function name if differs from the function name for AI.
Which ToolFunctions will be used. Empty means all. If passed function name prefixed by "-", it is excluded, e.g. "-Do" - use all except Do.
List of JavaScript functions available if some of the ToolFunctions parameter can contain JavaScript code and its name ends by "$C".
Example definition:
ToolFunctions:{ TestRows: {
Desc:"Iterates all rows and for every row calls function Test(row)",
Param:{ Test$RC:"inner code of JavaScript function with parameter 'row' called for every row in grid" },
},
APIFunctions:{ Color: { Desc:"Colors the 'row' in given background 'color'", Param:"row,color", Use:"TestRows", Ignore:"Grid.IsLocked('EditAll')" } } String with comma separated list of parameter names the function accepts in this order.
The parameters names need not be the same as the real parameter names the JavaScript function defines, they should be just referred and explained in Desc.
Text used to fully describe the API function, its parameters and usage to AI. It can be in any language, but English is preferred. String with comma separated list of the ToolFunctions names, inside their parameter code the function can be called.
Optional string with JavaScript code that returns true if the function should not be available in actual request. The code can use Grid object as actual grid. Or Ignore can be set to 1 to ignore the function without condition.
Returns active filters in grid in string for AI. part can be set to particular row or column part, where to get the filter. If not set, it returns first filter in grid.
Fills to array cols the column attributes: name (visible name), type (Type), width (actual width), hidden (true or false), kind (AIKind or Kind), part (ColPart id), treelevel (L) from columns in grid.
If not set cols, creates it from all columns in grid, in the order they are displayed.
Returns the new or updated array cols.
Example: var S = "The grid columns are defined in JSON object as: "+JSON.stringify(this.AIAddColsAttrs())+". ";

Custom functions for AI tools

There are two ways of defining custom JavaScript functions usable by AI:

Custom API functions for tool function Do and / or Run

The most of tasks done by AI are done by main function Do in FastGrid and by main function Run in FastSheet, defined in AI.js.
The Do / Run function runs JavaScript code passed by AI to its parameter "code".
The JavaScript code can call defined API functions.

1) Define the custom JavaScript API function in Script or in FGrid tag in data. The custom API function must have the first parameter the grid object. For example:
Script: { customgrouprows: function(G,cols){ if(typeof(cols)=="object") cols = cols.join(","); G.SetGroup(cols); } },

2) Add the custom API function to ToolFunctions for Do and / or Run function. For example:
AI: { APIFunctions: { customgrouprows: { Param:"cols", Desc:"groups rows according to columns set in array 'cols'", Use:"Do" } } },

3) AI will call the custom API function in such way: Do({"code":"customgrouprows('A,C,F'); return 'ok';"})

Custom tool functions

The tool functions are directly called by AI.

1) Define the custom JavaScript function in Script or in FGrid tag in data.
The custom tool function must have two parameters, the first is the grid object and the second parameter is object with properties as defined in Param. For example:
Script:{ CustomGroupRows: function(G,P){ if(typeof(P.cols)=="object") P.cols = P.cols.join(","); G.SetGroup(P.cols); } },

2) Add the custom main function to AI. For example:
AI: { ToolFunctions: { CustomGroupRows: { Desc:"Groups rows according to columns set in parameter 'cols'", Param: { cols:"Array of columns to group the rows by them" } } } },

3) AI will call the custom tool function in such way: CustomGroupRows({"cols":"A,C,F"})

AI UI settings

When the input request will be sent to AI.
1. bit &1 - by Send button. If not set, the button is hidden.
2. bit &2 - by pressing Enter during editing prompt input. If not set, Enter puts CRLF to the text.
3. bit &4 - by pressing Ctrl + Enter during editing prompt input. If not set, Ctrl+Enter puts CRLF to the text. CRLF to text can be always put by Shift+Enter.
4. bit &8 - by chosen prompt in history list. If not set, choosing prompt in history list will start editing it.
5. bit &16 - by clicking outside the prompt input. If not set, clicking outside just finishes editing.
First character separated list of permanent items added above prompts history in AIInput cell.
If it contains item "*", the InputHistory is included to this place, otherwise it is added to the end.
By default it is "|*|-|$AICopyResponse|$AIClearResponse|$AIClearHistory" with options to copy to clipboard or clear the AI response in AIOutput and to clear the prompts history.
First character separated list or array of initial items in prompts history. Maximal count of items in prompts history in InputHistory. If set to 0, history is not used.
Minimal length of the prompt text to be added to history. To avoid adding communication like 'yes' or 'always'.
Maximal JSON input length (in characters) sent to AI API, for case the AI reads too many data by tool function.
When the limit is reached, to AI API is sent error to let it to try another approach.
Maximal time in milliseconds the AI API code can run in grid.
When the code runs longer, it is stopped and exception is sent to AI to try another approach. All changes done in this unsuccessful approach are undone. Text colors and other settings for individual response text types shown in AIOutput. It must be opening <div> tag with style and optionally followed by text.
Array of available heights in pixels of the AI toolbar height, for list in AI settings. Default value is [50,100,150,250,325,400]. If and how prints API functions called by AI to AIOutput, 0 - nothing, 1 - call content, 2 - return content, 3 - call and return content, 4 - only static text, 5 only static text during progress.
The FastGrid API for AI should be used only for AI and not for any API calls from JavaScript code - this API is undocumented and can be changed in any future FastGrid version or build. 1. bit &1 - Prints to output also price for the prompt and spent and rest budget. Works only if used default AI bridge on treegrid.net in Url
2. bit &2 - Prints to output also tokens used by the prompt.
If permits read only editing the AI response text, to select text part and copy it to clipboard. How the grid behaves during communication with AI.
0 - grid is accessible, but locked. Progress is shown in AI output response. The lock level is chosen according to AIPermissions and is set by AI LockUIx.
1 - grid is disabled and shows static messages. No progress is shown. It can be used mainly for simple server communication without chunked data.
2 - grid is disabled and shows one progress bar. The progress counts communication events all together, so the progress bar never reset. But the progress can stop short or be longer time nearly full.
3 - grid is disabled and shows progress bar for every communication part. The progress counts arrived data and resets the progress bar on every communication request, API call, file download, etc. It resets progress bar also during communication when the count reaches the MaxProgress.
If progress is shown by 0, 2 or 3, it always sets stream:true for the AI to receive progress events. If used custom server AI bride in Url, the server must send and receive the data chunked with content-type: text/event-stream.
The virtual length of progress bar for AIDisableGrid values 2 and 3.
Permissions level for AI. Controls which LockAIx will be set for AI and which LockUIx will be set to users during AI communication.
By default the permission modes are:
0 - full mode, with no lock and all features enabled.
1 - control mode, with disabled changing grid data, but permitting sort, filter, group, select, focus, etc.
2 - read only mode, with disabled changing grid and controls, with permitting only reading data and highlight, select and focus.
Comma separated list of locks applied for AI and set AIPermissions = 0.
AI cannot use the locked features and if required, AI will ask user to temporary enable the feature by changing the AIPermissions.
By default the AIPermissions = 0 is used as full mode, with no lock and all features enabled. Comma separated list of locks applied for AI and set AIPermissions = 1.
AI cannot use the locked features and if required, AI will ask user to temporary enable the feature by changing the AIPermissions.
By default the AIPermissions = 1 is used as control mode, with disabled changing grid data, but permitting sort, filter, group, select, focus, etc. Comma separated list of locks applied for AI and set AIPermissions = 2.
AI cannot use the locked features and if required, AI will ask user to temporary enable the feature by changing the AIPermissions.
By default the AIPermissions = 2 is used as read only mode, with disabled changing grid and controls, with permitting only reading data and highlight, select and focus. Comma separated list of locks applied when grid is locked during communication with AI and DisableGrid = 0 and AIPermissions = 0.
Comma separated list of locks applied when grid is locked during communication with AI and DisableGrid = 0 and AIPermissions = 1.
Comma separated list of locks applied when grid is locked during communication with AI and DisableGrid = 0 and AIPermissions = 2.
Comma separated string or array of items shown in AI configuration menu. Set it to "" to not show the menu. It can contain "-" item as separator. Case sensitive. It can contain these keywords:
Model - sets AIModel from Models,
Permissions - sets AIPermissions,
WebSearch - sets AIWebSearch,
ImageGeneration - sets AIImageGeneration,
ImageQuality - sets AIImageQuality,
Accept - sets AIAccept,
DisableGrid - sets AIDisableGrid,
OutputSelect - sets AIOutputSelect,
OutputHeight - sets AI toolbar MaxHeight,
OutputFunction - sets AIOutputFunction,
OutputPrice - sets AIOutputPrice, 1. bit.
OutputTokens - sets AIOutputPrice, 2. bit.

API functions to control AI

Main function to communicate with AI. Sends the text to AI and calls func periodically with AI responses.
Calls func(Grid,Text,Result) during communication,
Text is html with AI response or html with error, according to the Result.
Result is
1 - Finished ok, Text is AI final response,
0 - Communication in progress, next AI response(s) will follow, Text contains AI reasoning texts or AI tool calls,
-1 - AI error, Text contains error message from AI,
-2 - Unexpected server response, it does not contain correct response from OpenAI, Text contains the full server text response,
-3 - Server error, Text contains the server error message,
-4 - Communication error, Text contains standard FastGrid error message $AIAjaxError,
-5 - Abort, the running communication was aborted, the user canceled the communication or started new communication or AISend was called, Text contains standard FastGrid error message $AIAbort.
func can be JavaScript function or string with JavaScript code for the function.
row, col can be FastGrid Html cell where the response texts will be added and displayed.
Returns true if the communication started and false for any error.
Interrupts and cancels actual AI communication and undoes all changes done during the canceled AI communication.
Returns null if no AI communication was running. Returns false if the communication was not canceled. Returns true if the communication was canceled.
Returns how long the AI is running, in milliseconds. Returns null if AI is not running.
Returns AI input history.
Adds given item to AI input history.
Sets value and EmptyString to AIInput cell in all sheets.
Returns actual AI credit in format that will be sent to server url https://www.treegrid.net/AI.
The returned value is not the same as credit set by AISetCredit or in Credit
Sets actual prepaid credit to use with AI communication.
Shows prompt message to enter the AI credit by user and save and use the entered credit.