Vals AI CLI and SDK Tool

Install

pip install valsai

Overview

This Python package contains two items - a CLI tool to use Vals from the command line, and an SDK to use Vals from Python code.

All code is contained within vals/, separated by CLI and SDK. Note that many of the CLI functions are just thin wrappers around the SDK.

Examples

We've provided a set of examples in examples/. They are organized as follows:

suites/ - These are example JSON files, of the sort that you may use for vals suite create <example.json>.
scripts/ - These are example Python scripts that leverage the sdk.

Authentication

Make an account at platform.vals.ai and confirm your email.

Then, go to platform.vals.ai/project/default-project/settings/api-keys and create an API key. If using a different project, navigate to that project's settings instead.

If you are using the command line, you should set the following:

export VALS_API_KEY=<YOUR API KEY>

If you're using the EU instance of vals, you should also set export VALS_REGION=europe. Include these in your .zshrc / .bashrc to make them permanent.

See the documentation for passing in your API key directly via Python code for SDK usage.

CLI Usage

The CLI is run as follows:

$ vals

Use the --help flag at the top and subcommand level for guidance.

Commands must be run from the pip environment the cli was installed in. Commands are split up into subcommands. Currently there are three main subcommands:

vals suite --help: relating to creating / updating tests and suites
vals run --help: relating to creating and querying runs and run results
vals project --help: relating to listing and managing projects

Full documentation of the CLI usage can be found in our documentation at docs.vals.ai/cli/cli

SDK Usage

All of the functionality that is in the CLI can also be accessed via Python functions, as well as features only available in the SDK.

See usage documentation in our docs: docs.vals.ai/sdk

Development

The SDK uses uv for dependency management. A Makefile is provided for common tasks. See the root README for full environment setup instructions.

Local Installation

make install

To install the SDK in editable mode in another project (apply local changes without reinstalling):

uv pip install -e /path/to/platform/sdk

Makefile Commands

make install        Install dependencies for development
make test           Run tests
make style          Lint & format (ruff)
make typecheck      Run basedpyright
make codegen        Generate GraphQL client

Running Codegen

Add additional .graphql files to vals/graphql, then run the following command:

make codegen

ariadne-codegen --config codegen-config.toml

NOTE: This will overwrite anything in the vals/graphql_client directory.

Metadata

Release files for valsai 0.3.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for valsai 0.3.11
File	Size	Uploaded
valsai-0.3.11.tar.gz	385.9 kB	May 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for valsai 0.3.11
File	Interpreter	ABI	Platform	Reset
valsai-0.3.11-py3-none-any.whl 110.3 kB May 8, 2026	Python 3	none	any	Details

Total release size: 496.2 kB

Release files / valsai-0.3.11.tar.gz

Download URL	valsai-0.3.11.tar.gz
Size	385.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`ccae7877025cebceb79aefab601fb20a86ab834eb6f1d7ee1e71fc069eff4306`
BLAKE2b-256 checksum How to use checksums	`d1bcc041c042e902255bc1072669bb369e25e3f82e75d11552ca86c942055ca7`
Upload date	May 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vals-ai/platform
Publishing commit: github.com/vals-ai/platform/tree/733fdb5fb1ad12e8ee5a8ec2fdde6eb8937ae370

Workflow

Publishing configuration: github.com/vals-ai/platform/blob/733fdb5fb1ad12e8ee5a8ec2fdde6eb8937ae370/.github/workflows/sdk-publish.yml
Publishing logs: github.com/vals-ai/platform/actions/runs/25583866184/attempts/1

Artifact

Subject: valsai-0.3.11.tar.gz
SHA-256 checksum: ccae7877025cebceb79aefab601fb20a86ab834eb6f1d7ee1e71fc069eff4306 Verifying attestations

Release files / valsai-0.3.11-py3-none-any.whl

Download URL	valsai-0.3.11-py3-none-any.whl
Size	110.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`10fbd6e4c9e28cfef67d65e7f133ed860fdee525c03875e9a01b2ee8914d4fa6`
BLAKE2b-256 checksum How to use checksums	`10b45f14a7900c129509cf7a0e5a32bbf6d85286625c50b4aeaaea23c4dc6347`
Upload date	May 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vals-ai/platform
Publishing commit: github.com/vals-ai/platform/tree/733fdb5fb1ad12e8ee5a8ec2fdde6eb8937ae370

Workflow

Publishing configuration: github.com/vals-ai/platform/blob/733fdb5fb1ad12e8ee5a8ec2fdde6eb8937ae370/.github/workflows/sdk-publish.yml
Publishing logs: github.com/vals-ai/platform/actions/runs/25583866184/attempts/1

Artifact

Subject: valsai-0.3.11-py3-none-any.whl
SHA-256 checksum: 10fbd6e4c9e28cfef67d65e7f133ed860fdee525c03875e9a01b2ee8914d4fa6 Verifying attestations