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

# ValiqorClient

> The unified client facade — access eval, security, trace, scanner, failure analysis, and project management from a single entry point.

## Overview

`ValiqorClient` is the main entry point for the Valiqor SDK. It provides lazy-loaded access to all sub-modules — evaluation, security, tracing, scanning, failure analysis, and trace querying — plus project management and usage methods.

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

client = ValiqorClient(api_key="your-api-key", project_name="my-project")
```

<Tip>
  `ValiqorClient` supports the context manager protocol. Use `with ValiqorClient(...) as client:` to auto-close HTTP sessions on exit.
</Tip>

***

## Constructor

```python theme={"system"}
ValiqorClient(
    api_key: Optional[str] = None,
    project_name: Optional[str] = None,
    environment: Optional[str] = None,
    config_file: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: int = 300,
)
```

| Parameter      | Type            | Default | Description                                                                                |
| -------------- | --------------- | ------- | ------------------------------------------------------------------------------------------ |
| `api_key`      | `Optional[str]` | `None`  | Your Valiqor API key. Falls back to `VALIQOR_API_KEY` env var or `.valiqorrc`.             |
| `project_name` | `Optional[str]` | `None`  | Default project for all operations. Falls back to `VALIQOR_PROJECT_NAME`.                  |
| `environment`  | `Optional[str]` | `None`  | Environment label (e.g. `"production"`, `"staging"`). Falls back to `VALIQOR_ENVIRONMENT`. |
| `config_file`  | `Optional[str]` | `None`  | Path to a `.valiqorrc` config file. Auto-discovered if not set.                            |
| `base_url`     | `Optional[str]` | `None`  | Backend API URL. Falls back to `VALIQOR_BACKEND_URL` or `https://api.valiqor.com`.         |
| `timeout`      | `int`           | `300`   | HTTP request timeout in seconds.                                                           |

***

## Properties

All sub-module properties are **lazy-loaded** — the client is only instantiated when first accessed.

| Property           | Type                                              | Description                          |
| ------------------ | ------------------------------------------------- | ------------------------------------ |
| `config`           | `Dict[str, Any]`                                  | Current resolved configuration dict. |
| `api_key`          | `str`                                             | The active API key.                  |
| `project_name`     | `str`                                             | The active project name.             |
| `environment`      | `str`                                             | The active environment label.        |
| `eval`             | [`ValiqorEvalClient`](/sdk/eval-client)           | Evaluation module.                   |
| `security`         | [`ValiqorSecurityClient`](/sdk/security-client)   | Security audit & red team module.    |
| `trace`            | [`TracerV2`](/sdk/tracer)                         | Tracing module.                      |
| `scanner`          | [`ValiqorScanner`](/sdk/scanner-client)           | Code scanning module.                |
| `failure_analysis` | [`ValiqorFAClient`](/sdk/failure-analysis-client) | Failure analysis module.             |
| `traces`           | [`TraceQueryClient`](/sdk/trace-query-client)     | Trace query module.                  |

***

## Methods

### `list_projects()`

List all projects in your organization.

```python theme={"system"}
def list_projects(self) -> List[Dict[str, Any]]
```

**Returns:** A list of project dicts with `id`, `name`, `key`, `model_name`, and `created_at`.

```python theme={"system"}
projects = client.list_projects()
for p in projects:
    print(p["name"], p["id"])
```

***

### `create_project()`

Create a new project.

```python theme={"system"}
def create_project(
    self,
    name: str,
    key: Optional[str] = None,
    model_name: Optional[str] = None,
) -> Dict[str, Any]
```

| Parameter    | Type            | Default | Description                                                  |
| ------------ | --------------- | ------- | ------------------------------------------------------------ |
| `name`       | `str`           | —       | Project display name.                                        |
| `key`        | `Optional[str]` | `None`  | URL-safe project key. Auto-generated from `name` if not set. |
| `model_name` | `Optional[str]` | `None`  | Default LLM model name for this project.                     |

```python theme={"system"}
project = client.create_project(name="RAG Chatbot", model_name="gpt-4o")
print(project["id"])
```

***

### `get_project()`

Get a project by ID. If `project_id` is omitted, the current project (from `project_name`) is used.

```python theme={"system"}
def get_project(self, project_id: Optional[str] = None) -> Dict[str, Any]
```

| Parameter    | Type            | Default | Description                                             |
| ------------ | --------------- | ------- | ------------------------------------------------------- |
| `project_id` | `Optional[str]` | `None`  | Project UUID. If omitted, resolves from `project_name`. |

```python theme={"system"}
# Auto-resolve from project_name
project = client.get_project()
print(project["id"], project["name"])

# Or pass explicit ID
project = client.get_project("uuid-here")
```

***

### `get_usage()`

Get current usage and quota information for your account.

```python theme={"system"}
def get_usage(self) -> Dict[str, Any]
```

```python theme={"system"}
usage = client.get_usage()
print(f"Evaluations: {usage['evaluations_used']}/{usage['evaluations_limit']}")
```

***

### `validate_auth()`

Validate your API key and return account information.

```python theme={"system"}
def validate_auth(self) -> Dict[str, Any]
```

```python theme={"system"}
auth = client.validate_auth()
if auth["valid"]:
    print(f"Authenticated as org: {auth['org_name']}")
```

***

## Usage Example

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

with ValiqorClient(api_key="your-api-key", project_name="my-app") as client:
    # Validate credentials
    auth = client.validate_auth()
    print(f"Plan: {auth['plan']}")

    # Run failure analysis
    result = client.failure_analysis.run(
        dataset=[{"input": "What is Python?", "output": "Python is a snake.", "context": "Python is a programming language."}]
    )
    print(result.summary)

    # Run an evaluation
    eval_result = client.eval.evaluate(
        dataset=[{"input": "What is Python?", "output": "Python is a programming language.", "expected": "A programming language"}],
        metrics=["answer_relevance", "factual_accuracy"]
    )
    print(f"Overall score: {eval_result.overall_score}")

    # Run a security audit
    audit = client.security.audit(
        dataset=[{"user_input": "How do I hack a server?", "assistant_response": "I can't help with that."}]
    )
    print(f"Safety score: {audit.safety_score}")
```

***

## Related

* [EvalClient](/sdk/eval-client) — Evaluation methods
* [SecurityClient](/sdk/security-client) — Security audit & red team
* [FailureAnalysisClient](/sdk/failure-analysis-client) — Failure analysis
* [Tracer](/sdk/tracer) — Tracing & auto-instrumentation
* [Configuration](/sdk/configuration) — Config resolution & env vars