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.
from valiqor import ValiqorClient
client = ValiqorClient(api_key="your-api-key", project_name="my-project")
ValiqorClient supports the context manager protocol. Use with ValiqorClient(...) as client: to auto-close HTTP sessions on exit.
Constructor
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 | Evaluation module. |
security | ValiqorSecurityClient | Security audit & red team module. |
trace | TracerV2 | Tracing module. |
scanner | ValiqorScanner | Code scanning module. |
failure_analysis | ValiqorFAClient | Failure analysis module. |
traces | TraceQueryClient | Trace query module. |
Methods
list_projects()
List all projects in your organization.
def list_projects(self) -> List[Dict[str, Any]]
id, name, key, model_name, and created_at.
projects = client.list_projects()
for p in projects:
print(p["name"], p["id"])
create_project()
Create a new project.
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. |
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.
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. |
# 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.
def get_usage(self) -> Dict[str, Any]
usage = client.get_usage()
print(f"Evaluations: {usage['evaluations_used']}/{usage['evaluations_limit']}")
validate_auth()
Validate your API key and return account information.
def validate_auth(self) -> Dict[str, Any]
auth = client.validate_auth()
if auth["valid"]:
print(f"Authenticated as org: {auth['org_name']}")
Usage Example
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}")
