Configuration

Overview

The Valiqor SDK resolves configuration from three sources, in priority order:

Programmatic — Parameters passed to ValiqorClient(...) or get_config(**overrides)
Environment variables — VALIQOR_API_KEY, VALIQOR_PROJECT_NAME, etc.
Config file — .valiqorrc (JSON file, auto-discovered from cwd upward)

Higher-priority sources override lower-priority ones. For example, passing api_key="..." to the constructor always wins over the environment variable.

`.valiqorrc` File

A JSON configuration file placed in your project root (or any parent directory). The SDK walks up from the current directory to find it.

{
  "project_name": "my-ai-app",
  "api_key": "vq_...",
  "openai_api_key": "sk-...",
  "environment": "development",
  "trace_dir": "valiqor_output/traces",
  "scan_dir": "valiqor_output/scans",
  "valiqor_intelligence": true,
  "backend_url": "https://api.valiqor.com",
  "debug": false,
  "app_version": "1.0.0",
  "auto_providers": ["openai", "langchain", "anthropic"]
}

Never commit API keys to version control. Use environment variables for production deployments.

Environment Variables

Variable	Config Key	Description
`VALIQOR_API_KEY`	`api_key`	Your Valiqor API key.
`VALIQOR_PROJECT_NAME`	`project_name`	Default project name.
`VALIQOR_OPENAI_API_KEY`	`openai_api_key`	OpenAI key for LLM-based metrics.
`VALIQOR_BACKEND_URL`	`backend_url`	Backend API URL.
`VALIQOR_ENVIRONMENT`	`environment`	Environment label (e.g. `production`).
`VALIQOR_TRACE_DIR`	`trace_dir`	Local trace output directory.
`VALIQOR_SCAN_DIR`	`scan_dir`	Local scan output directory.
`VALIQOR_INTELLIGENCE`	`valiqor_intelligence`	Enable cloud uploads (`true`/`false`).
`VALIQOR_DEBUG`	`debug`	Enable debug logging (`true`/`false`).

Configuration Functions

`get_config()`

Resolve the full configuration from all sources.

from valiqor.common.config import get_config

config = get_config()
print(config["api_key"])
print(config["project_name"])

With overrides:

config = get_config(
    config_file="/path/to/.valiqorrc",
    api_key="override-key",
    project_name="override-project"
)

Config Keys & Defaults

Key	Type	Default
`project_name`	`str`	`""`
`api_key`	`str`	`""`
`openai_api_key`	`str`	`""`
`trace_dir`	`str`	`"valiqor_output/traces"`
`scan_dir`	`str`	`"valiqor_output/scans"`
`valiqor_intelligence`	`bool`	`True`
`environment`	`str`	`"development"`
`debug`	`bool`	`False`
`backend_url`	`str`	`"https://api.valiqor.com"`
`enabled`	`bool`	`True`
`app_version`	`str`	`"1.0.0"`
`auto_providers`	`List[str]`	`["openai", "langchain", "anthropic"]`

`find_config_file()`

Find the nearest .valiqorrc file by walking up from the given path.

from valiqor.common.config import find_config_file

path = find_config_file()  # starts from cwd
if path:
    print(f"Found config at: {path}")

Parameter	Type	Default	Description
`start_path`	`Optional[str]`	`None`	Starting directory. Defaults to cwd.

`load_config_file()`

Load and parse a .valiqorrc file.

from valiqor.common.config import load_config_file

config_data = load_config_file()  # auto-discovers

`save_config()`

Write configuration to a .valiqorrc file.

from valiqor.common.config import save_config

# Save specific config
save_config({
    "project_name": "my-app",
    "api_key": "vq_...",
    "environment": "production"
})

# Save current active config
save_config()

Parameter	Type	Default	Description
`config`	`Optional[Dict[str, Any]]`	`None`	Configuration dict to save. If omitted, saves the current active config.
`path`	`Optional[Path]`	`None`	File path. Defaults to `.valiqorrc` in cwd.

Returns: bool — True if saved successfully.

`ensure_output_dirs()`

Create the trace and scan output directories if they don’t exist.

from valiqor.common.config import ensure_output_dirs

# With explicit config
ensure_output_dirs(config)

# Or with current active config
ensure_output_dirs()

Parameter	Type	Default	Description
`config`	`Optional[Dict[str, Any]]`	`None`	Configuration dict. If omitted, uses the current active config.

`should_upload()`

Check if the current config enables cloud uploads.

from valiqor.common.config import should_upload

if should_upload(config):
    print("Uploads enabled")

Constants

Constant	Value	Description
`CONFIG_FILE`	`".valiqorrc"`	Default config filename.
`DEFAULT_BACKEND_URL`	`"https://api.valiqor.com"`	Default backend URL.
`DEFAULT_TRACE_DIR`	`"valiqor_output/traces"`	Default trace output directory.
`DEFAULT_SCAN_DIR`	`"valiqor_output/scans"`	Default scan output directory.

Module-Level `configure()`

The top-level valiqor.configure() function provides a convenient shortcut:

import valiqor

config = valiqor.configure(
    api_key="your-api-key",
    project_name="my-app",
    environment="production"
)

Example: Production Setup

# .env file (loaded by your deploy pipeline)
VALIQOR_API_KEY=vq_prod_abc123
VALIQOR_PROJECT_NAME=chatbot-v2
VALIQOR_ENVIRONMENT=production
VALIQOR_OPENAI_API_KEY=sk-prod_xyz789
VALIQOR_INTELLIGENCE=true

# app.py — no config needed, reads from env
from valiqor import ValiqorClient

client = ValiqorClient()  # All config from env vars
result = client.failure_analysis.run(dataset=my_data)

ValiqorClient — Main client (accepts config params)
Exceptions — ConfigurationError for config issues
CLI Configuration — valiqor configure command

Client

Modules

Utilities

Overview

`.valiqorrc` File

Environment Variables

Configuration Functions

`get_config()`

Config Keys & Defaults

`find_config_file()`

`load_config_file()`

`save_config()`

`ensure_output_dirs()`

`should_upload()`

Constants

Module-Level `configure()`

Example: Production Setup

​Overview

​.valiqorrc File

​Environment Variables

​Configuration Functions

​get_config()

​Config Keys & Defaults

​find_config_file()

​load_config_file()

​save_config()

​ensure_output_dirs()

​should_upload()

​Constants

​Module-Level configure()

​Example: Production Setup

​Related

Overview

`.valiqorrc` File

Environment Variables

Configuration Functions

`get_config()`

Config Keys & Defaults

`find_config_file()`

`load_config_file()`

`save_config()`

`ensure_output_dirs()`

`should_upload()`

Constants

Module-Level `configure()`

Example: Production Setup

Related