> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the SDK via .valiqorrc files, environment variables, or programmatic calls.

## Overview

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

1. **Programmatic** — Parameters passed to `ValiqorClient(...)` or `get_config(**overrides)`
2. **Environment variables** — `VALIQOR_API_KEY`, `VALIQOR_PROJECT_NAME`, etc.
3. **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.

```json theme={"system"}
{
  "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"]
}
```

<Warning>
  Never commit API keys to version control. Use environment variables for production deployments.
</Warning>

***

## 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.

```python theme={"system"}
from valiqor.common.config import get_config

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

With overrides:

```python theme={"system"}
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.

```python theme={"system"}
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.

```python theme={"system"}
from valiqor.common.config import load_config_file

config_data = load_config_file()  # auto-discovers
```

***

### `save_config()`

Write configuration to a `.valiqorrc` file.

```python theme={"system"}
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.

```python theme={"system"}
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.

```python theme={"system"}
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:

```python theme={"system"}
import valiqor

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

***

## Example: Production Setup

```bash theme={"system"}
# .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
```

```python theme={"system"}
# 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)
```

***

## Related

* [ValiqorClient](/sdk/valiqor-client) — Main client (accepts config params)
* [Exceptions](/sdk/exceptions) — `ConfigurationError` for config issues
* [CLI Configuration](/cli/configuration) — `valiqor configure` command