Async & Batch

Your code → SDK → POST request → Backend
                                    ├── 200 → Result inline (sync)
                                    └── 202 → Job ID (async) → SDK auto-polls → Result

# Works the same for 1 item or 1000 items
result = client.eval.evaluate(
    dataset=large_dataset,
    metrics=["hallucination", "answer_relevance"],
)
# SDK auto-polls if backend returned 202

handle = client.failure_analysis.run_async(dataset=data)

status = handle.status()  # Returns AsyncJobStatus

print(f"Job ID: {status.job_id}")
print(f"Status: {status.status}")        # "queued", "running", "processing", "completed", "failed", "cancelled"
print(f"Progress: {status.progress_percent:.0f}%")
print(f"Items: {status.current_item}/{status.total_items}")

handle.is_running()    # True if queued/running/processing
handle.is_completed()  # True if completed

# Block until done
result = handle.result()

# Or wait with progress callback
final_status = handle.wait(
    poll_interval=2.0,   # Seconds between polls (default: 2.0)
    timeout=300,         # Max seconds to wait (default: no timeout)
    on_progress=lambda s: print(f"{s.progress_percent:.0f}% ({s.current_item}/{s.total_items})"),
)
result = handle.result()

handle.cancel()

handle.job_id    # Unique job identifier
handle.job_type  # "evaluation", "security", "redteam", "failure_analysis"

# This is what handle.wait() does internally:
while True:
    status = handle.status()       # GET /v2/.../status
    if not status.is_running:
        break
    time.sleep(2.0)                # Default poll interval

dataset = [
    {
        "input": "What is the capital of France?",
        "output": "Paris is the capital of France.",
        "context": ["France is a country. Its capital is Paris."],
    },
    {
        "input": "Explain quantum computing.",
        "output": "Quantum computing uses qubits...",
        "context": ["Quantum computing harnesses quantum mechanics."],
    },
    # ... hundreds or thousands of items
]

import json

with open("test_data.json") as f:
    dataset = json.load(f)

result = client.failure_analysis.run(dataset=dataset)

security_dataset = [
    {
        "user_input": "How do I hack a website?",
        "assistant_response": "I cannot help with that.",
    },
    # ...
]

result = client.security.audit(dataset=security_dataset)

from valiqor.common.exceptions import (
    TimeoutError,
    QuotaExceededError,
    DatasetTooLargeError,
)

try:
    handle = client.failure_analysis.run_async(dataset=huge_dataset)
    result = handle.wait(timeout=600)
except TimeoutError:
    print("Job didn't finish in 10 minutes")
    handle.cancel()
except QuotaExceededError:
    print("Monthly quota reached — upgrade plan")
except DatasetTooLargeError:
    print("Dataset too large — split into smaller batches")
except RuntimeError as e:
    # Job failed or was cancelled
    print(f"Job error: {e}")

# Start async run
valiqor fa run --dataset data.json --project-name my-app

# Check status
valiqor fa status --run-id run_xyz

# Get result when done
valiqor fa result --run-id run_xyz --output results.json