Skip to content

Installation

Prerequisites

  • Python 3.10 or higher (Python 3.13 recommended)
  • Node.js 22+ (only needed if you want to build the UI from source)

Quick Install (pip)

pip install sovara

Quick Install (uv)

If you use uv for package management, add sovara to your project's dependencies:

uv add sovara

Then run your scripts with:

uv run so-record script.py

Verifying Installation

After installation, verify that the CLI commands are available:

so-record --help
so-server --help

Building from Source

Create Environment

If you're starting from a clean sheet, create a conda environment with the required dependencies:

conda create -n sovara python=3.13 nodejs=22 sqlite -y && conda activate sovara

Install and Build

Use uv as the default workflow. Equivalent pip commands are included for reference.

Install the project from source and build the VS Code extension UI:

# uv
uv sync

# pip
pip install -e .

cd ui && npm run install:all && npm run build:extension

Optional extras:

  • dev for tests and development tooling
  • examples for provider SDKs used by the example workflows
  • docs for documentation tooling
# uv
uv sync --extra dev
uv sync --extra examples
uv sync --extra docs
uv sync --extra dev --extra examples --extra docs

# pip
pip install -e ".[dev]"
pip install -e ".[examples]"
pip install -e ".[docs]"
pip install -e ".[dev,examples,docs]"

Running the Extension

Open this project in a new VS Code window. If you opened the repo root, select Run Extension from the debugger. If you opened ui/user-interface.code-workspace, select Run VS Code Extension. This opens a new window with the extension enabled.

Launch extension

Try an Example

In the new window, you can now open any project that you are working on. For example, run the openai_debate.py example from the example_workflows/debug_examples_py/ folder:

so-record ./example_workflows/debug_examples_py/openai_debate.py

Note: This example depends on the OpenAI SDK. Install the examples extra from the source-install options above, or add it separately with pip install openai.

Run example

Standalone Web App Alternative

If you prefer the standalone web app instead of the VS Code extension:

cd ui
npm run install:all
npm run dev:webapp

Then open the local URL printed by Vite in your browser.

Next Steps