Chart generation

When you need to visualize data in a graphical format, you can instruct Alan AI to generate charts from JSON data. This can be helpful, in particular, when dealing with data that requires a graphical display for better comprehension:

• Performance metrics

• Resource usage statistics

• Time-series data and so on

Parameters

To generate charts, you can leverage the dynamic corpus, transforms and createUI() function:

Dialog script

corpus({
    title: `VM statistics`,
    description: `Corpus to answer questions about VM stats and visualize VM stats as chart`,
    query: transforms.vm_questions,
    output: api.createUI({transform: transforms.vm_charts}),
});

Name	Type	Required/Optional	Description
title	string	Optional	Corpus title.
description	string	Optional	Corpus description.
query	function	Required	Transforms function used to process user queries and generate code to retrieve necessary data.
output	function	Optional	createUI() function and the transforms function to process data and render the required UI element.

Example of use

To generate charts from JSON data, perform the following steps:

1. Retrieve VM data: add a function that retrieves data from the data source.

2. Add a query transform: instruct the AI agent on how to generate code that will get the necessary data to answer user queries.

3. Add a UI generation transform: instruct the AI agent on how to process and render the JSON data.

4. Add a dynamic corpus: define a dynamic corpus.

Step 1. Retrieve data

To retrieve JSON data from the data source, you will typically make an API call to the data provider. To keep things simple, we will add a JSON object defining VMs statistics directly to the dialog script.

In the dialog script, create the project.vmStats variable:

Dialog script

project.vmStats = [
    {
        "vm_id": "vm-001",
        "name": "WebServer",
        "stats": [
            { "day": "2024-10-15", "uptime_hours": 19, "downtime_hours": 5 },
            { "day": "2024-10-16", "uptime_hours": 22.5, "downtime_hours": 1.5 },
            { "day": "2024-10-17", "uptime_hours": 23.8, "downtime_hours": 0.2 },
            { "day": "2024-10-18", "uptime_hours": 20.5, "downtime_hours": 3.5 },
            { "day": "2024-10-19", "uptime_hours": 21, "downtime_hours": 3 },
            { "day": "2024-10-20", "uptime_hours": 23.6, "downtime_hours": 0.4 },
            { "day": "2024-10-21", "uptime_hours": 19.8, "downtime_hours": 4.2 }
        ]
    },
    {
        "vm_id": "vm-002",
        "name": "DatabaseServer",
        "stats": [
            { "day": "2024-10-15", "uptime_hours": 21, "downtime_hours": 3 },
            { "day": "2024-10-16", "uptime_hours": 19.2, "downtime_hours": 4.8 },
            { "day": "2024-10-17", "uptime_hours": 22.7, "downtime_hours": 1.3 },
            { "day": "2024-10-18", "uptime_hours": 23.5, "downtime_hours": 0.5 },
            { "day": "2024-10-19", "uptime_hours": 18.8, "downtime_hours": 5.2 },
            { "day": "2024-10-20", "uptime_hours": 20.2, "downtime_hours": 3.8 },
            { "day": "2024-10-21", "uptime_hours": 22.9, "downtime_hours": 1.1 }
        ]
    },
    {
        "vm_id": "vm-003",
        "name": "AppServer",
        "stats": [
            { "day": "2024-10-15", "uptime_hours": 19.6, "downtime_hours": 4.4 },
            { "day": "2024-10-16", "uptime_hours": 23.9, "downtime_hours": 0.1 },
            { "day": "2024-10-17", "uptime_hours": 21.2, "downtime_hours": 2.8 },
            { "day": "2024-10-18", "uptime_hours": 20.3, "downtime_hours": 3.7 },
            { "day": "2024-10-19", "uptime_hours": 22.5, "downtime_hours": 1.5 },
            { "day": "2024-10-20", "uptime_hours": 23.1, "downtime_hours": 0.9 },
            { "day": "2024-10-21", "uptime_hours": 19.9, "downtime_hours": 4.1 }
        ]
    }
];

Step 2. Add a query transform

With a query transform, you can instruct the AI agent on how to process the input data and generate code that returns the information needed to answer user queries.

In this example, we will instruct the AI agent using functions added to transforms.

Note

Each function used in transforms must have an explanation formatted as a JSDoc comment preceding the function code.

1. To the dialog script, add the getVmStats() function with the function description:

   Dialog script

    /**
     * Retrieves VM uptime statistics for a week.
     * @returns {Object[]} Array of VMs with their daily uptime statistics.
     * @property {string} vm_id - Unique identifier for the virtual machine.
     * @property {string} name - Name of the virtual machine.
     * @property {Object[]} stats - Array of uptime statistics per day.
     * @property {string} stats[].day - The day of the uptime data (YYYY-MM-DD format).
     * @property {number} stats[].uptime_hours - Hours the VM was up on that day.
     * @property {number} stats[].downtime_hours - Hours the VM was down on that day.
    */
    async function getVmStats() {
        let data = await project.vmStats;
        console.log(data);
        return data;
    }
   

2. In the AI agent project, under Transforms, create the vms_queries transform with the following data:

   1. In the Instruction field, import getVmStats() function and provide general instructions on how to process VMs statistics. Then save the transform.

      Transform instruction

      #import getVmStats
      
      If a question relates to VM stats data, write an async function getRequestedData() that takes no parameters. The function must call provided functions to construct a JSON that will have all the necessary information to answer the question.
      

   2. In the Examples section, add an example to handle the Show VM uptime statistics query. At the bottom of the view, click Add Row and create a transform example:

      Note

      To open an example in preview mode, in the top left corner of any cell, click the magnifying glass icon.

      • At the top of the Input field, select the data format: json.

      • At the top of the Query field, select the data format: text. In the field below, enter the user query: Show VM uptime statistics.

      • At the top of the Result field, select the data format: javascript. In the field below, add steps in natural language to retrieve all VMs data wrapped with <thinking></thinking> tags:

        Transform example

        <thinking>
        To return the VM statistics:
        1. Use getVmStats() to get all VMs stats.
        2. Construct a JSON object with the following data for each VM: date, uptime_hours, downtime_hours.
        3. Return the result.
        </thinking>
        

      • At the top of the Result field, click the Generate result button to automatically generate code for the instructions specified in the <thinking></thinking> block:

        

      • To test if the generated function works correctly, in the top right corner of the Result field, click the Run script button:

        

Step 3. Add a UI generation transform

With the output transform, you can define the rules for chart generation and rendering.

1. In the AI agent project, under Transforms, create the vms_charts transform.

2. In the Instruction field, provide general instructions on how to generate a chart from the VM statistics. Then save the transform.

   Instruction

    #extend act_visualization
   
    Use this url for d3 script: https://cdnjs.cloudflare.com/ajax/libs/d3/7.9.0/d3.min.js
   
    When you have a chart, make sure that logic for rendering y-axis and x-axis is outside of the loops.
   
    For each element or point in the chart, generate a tooltip to be displayed over the element on hover.
    Below the chart, show a table with data displayed in the chart.
    Show dates in the chart in the format: Oct 15.
   

   Note

   The act_visualization transform is a built-in transform with a basic set of rules and instructions for generating charts. You can customize it by adding your own data processing and rendering instructions, as demonstrated above.

   

Step 4. Add a dynamic corpus

To define a dynamic corpus, add the corpus() function with the following parameters to the dialog script:

Dialog script

corpus({
    title: `VM statistics`,
    description: `Corpus to answer questions about VM stats and visualize VM stats as chart`,
    query: transforms.vms_queries,
    output: api.createUI({transform: transforms.vms_charts}),
    priority: 1
});

Now, you can ask the AI agent questions like:

• Show uptime and downtime stats for DatabaseServer

  

• Show the uptime and downtime hours stats in percent for all VMs

  

• Show the average uptime versus downtime for AppServer as a pie chart