Skip to main content

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

or

ariadne-codegen --config codegen-config.toml

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

Metadata

Release files for valsai 0.3.14

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.14
File Size Uploaded Provenance Actions
valsai-0.3.14.tar.gz 377.6 kB With provenance Details for valsai-0.3.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for valsai 0.3.14
File Interpreter ABI Platform Actions
valsai-0.3.14-py3-none-any.whl Python 3 none any Details for valsai-0.3.14-py3-none-any.whl

Total release size: 491.4 kB

Release files / valsai-0.3.14.tar.gz

Download URL valsai-0.3.14.tar.gz
Size 377.6 kB
Tags Source
SHA-256 checksum
How to use checksums
18656cff26f1e8c7a4f0d5eb04751be4f0a12621bdab137ab836697b2e864fe4
BLAKE2b-256 checksum
How to use checksums
9a2a638fb9ffbd2534f6571c9b327fa9d59a30f053dd41792e15d682a221279b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

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

Download URL valsai-0.3.14-py3-none-any.whl
Size 113.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bfc3cf17ee2a8f6825f18b9c318e1ba104c3c4a85c5a8303986ff4c3d1e296d1
BLAKE2b-256 checksum
How to use checksums
f6ac38e7419cebfbc82f0f7b7ac6c21bf65adf5972ee647371c6268fc244375e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for valsai 0.3.14

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for valsai-0.3.14.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.14 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page