Getting Started

This guide will get you set up and ready to use the Vertesia CLI and SDK.

Vertesia Studio

In order to create and manage your interaction you need to login to Vertesia Studio. This is a web application in which you can create and manage your interactions.

In order to access and use your interactions from outside the Studio application, you can use the Vertesia CLI. If you want to integrate your interactions in your own application you can use the Vertesia SDK.

There is a second and more efficient way to integrate the interactions in your own application by using code generation. Code generation will generate high level classes along with TypeScript interfaces to easily access your interactions. We will talk about code generation at the end of this guide.

We will cover the basics of the CLI and of the SDK in the following sections. For full documentation see the projects themselves. Let's start with a quick look at the installation and basic usage of these tools.

Vertesia CLI

This is a command line application that can be used to access your Vertesia projects. It was designed to fulfill the following main use cases:

• List and switch between your Vertesia projects
• List the existing interactions and execution environments
• Run interactions once or multiple times over a set of different data inputs
• Generate data inputs to run the interactions against
• Search through the history of runs to inspect detailed results

Requirements

A TTY terminal and, as for the SDK, Node version 18 or higher is required.

Installation

npm -g install @vertesia/cli

Basic Usage

Let's list all the projects in the organization owning the API KEY:

vertesia -k {YOUR_API_KEY} projects

To access a project you must pass the project ID too. Let's list the interactions inside a project:

vertesia -k {YOUR_API_KEY} -p {PROJECT_ID} interactions

To simplify using the CLI command options which can get quite long, you can create profiles to store common arguments like the API key, the target project or the target server.

To create a profile run:

vertesia config add

and follow the interactive prompts.

Once you have created a profile you can use it to run commands without having to pass the arguments every time. The last created profile will be automatically selected as the defualt profile. To switch to another profile use the vertesia config user {PROFILE_NAME} command.

Now the following command:

vertesia interactions

will list the interactions using the current profile api key and target project.

Let's run an interaction. We will use the run command.

vertesia run {INTERACTION_ID}

This command has plenty of options. It is not the scope of this guide to explain them all.

To summarize we can run an interaction once or multiple times on a set of data inputs (specfified from a file using --input or inline using --data) we can run a interaction by giving some.

When running a single interaction the response will be, by default, streamed on the console.

You can also tag runs to be able to easily search for them later using vertesia runs.

Example:

vertesia run --tags testing {INTERACTION_1_ID}
vertesia run --tags testing {INTERACTION_2_ID}
# then, later retrieve the run results having the testing_session tag
vertesia runs --tags testing

Vertesia SDK

This is a JavaScript SDK that can be used in both Node.js and in the browser.

Requirements

Node version 18 or higher is required (the fetch API is required). It will also work with node version 17.5 by using the --experimental-fetch flag

Installation

npm install @vertesia/client

Basic Usage

Listing the projects in an organization:

import {VertesiaClient} from "@vertesia/client"

const client = new VertesiaClient({
    apikey: "YOUR_API_KEY_HERE"
})

const projects = await client.projects.list();

for (const project of projects) {
  console.log(project.name+': '+project.id);
}

You can see in the previous example how we initialize the VertesiaClient with the API key. The API key will authenticate us on the server and will select the organization to which the key belongs.

Let's list now the interactions in a project

import { VertesiaClient } from "@vertesia/client"

const client = new VertesiaClient({
    apikey: "YOUR_API_KEY_HERE",
})

const interactions = await client.interactions.list();

for (const interaction of interactions) {
    console.log(interaction.name + ': ' + interaction.id);
}

In the example above, you see we added a projectId option when instantiating the client. This is the ID of the project we want to access.

Both the API key and the project ID are set when initializing the client and will be used for all the requests made with that client.

You can change the project ID at any time by setting it directly on the client:

client.project = "New Project ID"

Let's suppose we created an interaction named "Which Color" which is sending to the LLM an object name to get in response one of its possible colors.

Suppose interactionId is the ID of the interaction. We can run it as follows:

import { VertesiaClient } from "@vertesia/client"

const client = new VertesiaClient({
    apikey: "YOUR_API_KEY_HERE",
})

// Note that the interactionId argument must be a valid interaction ID which belongs to the project you are connected to.
const run = await client.interactions.execute(interactionId, {
    data: { object: "sky" }
});

console.log(run.result);

The response of the LLM will be:

{
    "color": "blue"
}

What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further:

• Go deeper into each endpoint of the API
• Go deeper into using the CLI