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

# How Valiqor Works

> Architecture overview: SDK, backend, LLM judges, async jobs, and data flow.

Now that you've [seen a failure](/start-here/see-a-failure) and [learned to fix it](/start-here/fix-the-failure), let's understand how the system works under the hood.

***

## Architecture

```
┌──────────────┐        HTTPS        ┌──────────────────┐       ┌────────────┐
│              │  ───────────────►   │                  │  ───► │ LLM Judges │
│  Your Code   │                     │  Valiqor Backend │       │ (GPT-4, etc)│
│  + SDK       │  ◄───────────────   │                  │  ◄─── │            │
│              │    JSON results     │  FastAPI + Async │       └────────────┘
└──────────────┘                     │  Workers         │
                                     └──────────────────┘
                                              │
                                     ┌────────┴────────┐
                                     │   PostgreSQL    │
                                     │   (Results DB)  │
                                     └─────────────────┘
```

1. **Your code** calls the SDK (e.g., `client.failure_analysis.run(...)`)
2. The **SDK** sends an HTTPS request to the Valiqor backend
3. The **backend** dispatches the work to LLM judges (GPT-4o by default)
4. The judges classify each item against the failure taxonomy
5. **Results** are returned to the SDK as structured Python objects

***

## Two analysis modes

<Tabs>
  <Tab title="Dataset mode (ad-hoc)">
    Pass your existing AI inputs and outputs directly. No tracing or instrumentation required.

    ```python theme={"system"}
    result = client.failure_analysis.run(
        dataset=[
            {
                "input": "What is 2+2?",
                "output": "5",
                "context": ["Basic arithmetic: 2+2=4"],
            }
        ]
    )
    ```

    **Best for:** Quick checks, debugging, CI testing, evaluating prompt changes.
  </Tab>

  <Tab title="Trace mode (continuous)">
    Instrument your LLM calls with auto-tracing, then run analysis on captured traces.

    ```python theme={"system"}
    import valiqor.auto  # Auto-instruments OpenAI, Anthropic, etc.

    # ... your normal LLM calls happen and are traced ...

    result = client.failure_analysis.run(trace_id="tr_abc123")
    ```

    **Best for:** Production monitoring, capturing full execution context, multi-step chains.
  </Tab>
</Tabs>

***

## Configuration

The SDK resolves configuration from multiple sources, in priority order:

<Steps>
  <Step title="Programmatic (highest priority)">
    Values passed directly to the constructor:

    ```python theme={"system"}
    client = ValiqorClient(
        api_key="vq_...",
        project_name="my-app",
        base_url="https://custom.valiqor.com",
    )
    ```
  </Step>

  <Step title="Environment variables">
    ```bash theme={"system"}
    export VALIQOR_API_KEY="vq_..."
    export VALIQOR_PROJECT_NAME="my-app"
    export VALIQOR_BACKEND_URL="https://api.valiqor.com"
    export VALIQOR_OPENAI_API_KEY="sk_..."  # For LLM judges
    ```
  </Step>

  <Step title=".valiqorrc file">
    A JSON config file in your project root or home directory:

    ```json theme={"system"}
    {
      "api_key": "vq_...",
      "project_name": "my-app",
      "backend_url": "https://api.valiqor.com"
    }
    ```
  </Step>

  <Step title="Defaults (lowest priority)">
    The SDK uses sensible defaults: `backend_url` defaults to `https://api.valiqor.com`, `timeout` defaults to 300 seconds.
  </Step>
</Steps>

***

## Async behaviour

For large datasets or complex analyses, the backend may process requests asynchronously:

```
SDK sends request → Backend returns 202 Accepted
                   → SDK auto-polls for completion (transparent to you)
                   → Result returned when ready
```

This is **fully transparent** — your code looks synchronous:

```python theme={"system"}
# This may take 30+ seconds for large datasets,
# but the SDK handles polling automatically
result = client.failure_analysis.run(dataset=large_dataset)
```

If you want explicit async control, use `run_async()`:

```python theme={"system"}
handle = client.failure_analysis.run_async(dataset=large_dataset)

# Check status
print(handle.status())       # "running", "completed", etc.
print(handle.is_running())   # True/False

# Wait with progress callback
result = handle.wait(
    on_progress=lambda status: print(f"Status: {status}")
)
```

***

## Authentication

Valiqor uses **API key authentication**:

* Every request includes your API key in the `X-API-Key` header (handled by the SDK)
* API keys are scoped to your organization
* Each organization has its own quotas and project isolation
* Keys can be created and revoked from the [Dashboard](https://app.valiqor.com)

***

## What to learn next

<CardGroup cols={2}>
  <Card title="Failure Analysis" icon="magnifying-glass-chart" href="/workflows/failure-analysis">
    Custom buckets, subcategories, batch analysis, and advanced options.
  </Card>

  <Card title="Evaluations" icon="chart-bar" href="/workflows/evaluations">
    Run metric-based evaluations: hallucination, relevance, coherence, and more.
  </Card>

  <Card title="Security Audits" icon="shield-halved" href="/workflows/security">
    Red-team your AI for prompt injection, data leakage, and jailbreaks.
  </Card>

  <Card title="Tracing" icon="radar" href="/workflows/tracing">
    Auto-instrument OpenAI, Anthropic, and LangChain calls for production monitoring.
  </Card>
</CardGroup>