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"])
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. |
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. |
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)
