Quickstart - Sovara

In this quickstart, you will create a Sovara project, run a small script, and inspect the recorded run in the desktop app. This guide assumes you completed the installation steps and have OPENAI_API_KEY set in the terminal where you run the example.

Create a Project Folder

Create a folder for the quickstart and open a terminal inside it. Sovara uses the folder location to decide which project a run belongs to.

mkdir sovara-quickstart
cd sovara-quickstart

Add the Project in Sovara

Open the Sovara desktop app and create a project for this folder.

Click New Project.
Name the project quickstart.
Set the description to something short, for example Quickstart demo of Sovara.
Click Browse and select the sovara-quickstart folder.
Click Create Project.

New Project dialog in the Sovara desktop app

Any run from this folder, or one of its subfolders, will now be saved to the quickstart project.

Create the Python Project File

If you are following the Python path, 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 one file in the project folder. The Python example is the fastest path because uv run installs the dependencies from pyproject.toml and the script creates a Sovara run context directly. The TypeScript example uses the same project, but wraps the script with withSovaraRun.

Python
TypeScript

from openai import OpenAI
import sovara

client = OpenAI()

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

if __name__ == "__main__":
    with sovara.run("quickstart"):
        main()

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

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

Save the file as quickstart.py for Python or quickstart.ts for TypeScript.

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 Graph

Go back to the Sovara desktop app and open the quickstart project. You should see a new run named quickstart. Open the run to inspect the graph. The model request, model response, logs, and runtime metadata are captured as structured nodes, so the run is inspectable after the script finishes.

​Create a Project Folder

​Add the Project in Sovara

​Create the Python Project File

​Create an Example Script

​Record the Run

​Inspect the Graph