Quickstart

When you open the Sovara app for the first time, you will see a tutorial using a pre-recorded example project. Complete this tutorial before continuing with this section. In this quickstart, we will record our first own run!

Create a sample project

Let’s create a minimal sample project with a script that calls an LLM. Open the terminal and create a new folder for that project:

mkdir sovara-quickstart
cd sovara-quickstart

Select which language you want to use below.

Python
TypeScript

Create the Python project file

Create a pyproject.toml in the sovara-quickstart folder. uv run quickstart.py uses this file to install the OpenAI client and the Sovara SDK into the project’s environment.

cat > pyproject.toml <<'EOF'
[project]
name = "sovara-quickstart"
version = "0.1.0"
description = "Sovara quickstart example."
requires-python = ">=3.10"
dependencies = [
    "openai",
    "sovara",
]
EOF

Create an example script

Create quickstart.py in the project folder. You can use the following script which simply calls OpenAI’s GPT 5.4 mini. It assumes that you have set OPENAI_API_KEY as environment variable. If this is not the case, you need to modify the script accordingy.

from openai import OpenAI
from sovara import SovaraClient  

openai_client = OpenAI()
sovara_client = SovaraClient(project_name="quickstart")  

with sovara_client.run("quickstart run"):  
    response = openai_client.responses.create(
        model="gpt-5.4-mini",
        input="In one sentence, describe what a good quickstart should do.",
    )
print(response.output_text)

Create the TypeScript project file

Create a package.json in the sovara-quickstart folder. npm install uses this file to install the OpenAI client, the Sovara runner, and tsx.

cat > package.json <<'EOF'
{
  "name": "sovara-quickstart",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "@sovara/runner": "latest",
    "openai": "latest",
    "tsx": "latest"
  }
}
EOF

npm install

Create an example script

Create quickstart.ts in the project folder. You can use the following script which simply calls OpenAI’s GPT 5.4 mini. It assumes that you have set OPENAI_API_KEY as environment variable. If this is not the case, you need to modify the script accordingly.

import OpenAI from "openai";
import { SovaraClient } from "@sovara/runner"; 

const openai_client = new OpenAI();
const sovara_client = new SovaraClient({ projectName: "quickstart" }); 

await sovara_client.run("quickstart run", async () => { 
  const response = await openai_client.responses.create({
    model: "gpt-5.4-mini",
    input: "In one sentence, describe what a good quickstart should do.",
  });
  console.log(response.output_text);
}); 

Record the run

Run the command from the sovara-quickstart folder. The Sovara desktop app should stay open while the command runs.

Python
TypeScript

uv run quickstart.py

npx tsx quickstart.ts

Inspect the run

Go to the Sovara desktop app. A new project quickstart should have been created automatically. You might need to refresh the projects page at the top right corner to see it. When you open the project and go to Runs in the side bar, you should see a run called quickstart run. Open the run to inspect its (single) step. You should be able to find the model’s input and output, and the print statement which is logged in a tab in the right most panel.

Getting started

Sovara

Observability

Annotations

Lessons

Create a sample project

Create the Python project file

Create an example script

Create the TypeScript project file

Create an example script

Record the run

Inspect the run

​Create a sample project

​Create the Python project file

​Create an example script

​Create the TypeScript project file

​Create an example script

​Record the run

​Inspect the run

Create a sample project

Create the Python project file

Create an example script

Create the TypeScript project file

Create an example script

Record the run

Inspect the run