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

# How It Works

> The lifecycle of an eval run — from dataset rows to recorded, baseline-compared results.

One run, end to end:

```text The lifecycle of a run theme={null}
dataset ──► rows ──► × samples ──► agent invoked ──► deterministic assertions
                                                        │
                                        gate failed? ──► judges SKIPPED (no tokens)
                                                        │ gates passed
                                                        ▼
                                                   LLM judges run
                                                        │
                                                        ▼
                              everything persisted (response, tool calls, usage,
                              cost, per-assertion results, judge reasoning)
                                                        │
                                                        ▼
                          aggregate: row pass rates + score mean/stddev ──► run summary
                                                        │
                                                        ▼
                                    compare vs baseline ──► gate ──► pass / fail
```

## The pieces

**Rows.** A dataset yields rows: an `input` (the prompt), optional prior `messages` for [multi-turn](/evals/multi-turn), optional `expected` reference data, and free-form meta. Every row gets a **content hash** (input + messages + expected) so the same logical row is tracked across runs even when your file is reordered.

**Samples.** Agents are nondeterministic, so each row runs `samples` times. A row's result is a pass rate and a score distribution (mean ± stddev) — never a single boolean.

**Assertions first, judges last.** Deterministic checks (substrings, tool calls, cost…) cost nothing and run first. An assertion marked `->gate()` that fails hard-fails the sample — and skips its LLM judges entirely, so broken samples never spend judge tokens. Judges then score the surviving samples with persisted reasoning.

**Persistence.** Every sample writes its full context to your database: response text, structured output, tool calls, token usage, finish reason, duration, cost, and each assertion's expected/actual/score — plus the judge's reasoning. This is what powers the [dashboard](/evals/dashboard) and everything below.

**Baselines.** In Pest, the first run that passes its gate becomes the suite's baseline automatically. From the CLI it is explicit — pass `--baseline` (or promote a run later with `evals:baseline` or the dashboard). Later runs are joined to the baseline row-by-row (by content hash) and classified: regressed, improved, newly failing. See [Baselines & Regressions](/evals/baselines-and-regressions).

**The gate.** Pass/fail is a run-level policy — minimum score, minimum pass rate, maximum regressions — applied after aggregation. In Pest, a failed gate fails the test with row-level detail; in the [CLI](/evals/cli), it sets the exit code.

## Where things run

| Surface                                | What it's for                                                                      |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| `expect(...)->toPassEval(...)` in Pest | The main authoring surface — evals in your test suite, `--evals` to execute        |
| `php artisan evals:run`                | The same engine without Pest — class-based suites, `--dry-run`, JSON output for CI |
| Dashboard "Run" button                 | Queued execution of class-based suites from the browser                            |

All three land in the same tables and the same dashboard.

<Tip>
  Deep-dive the two halves of the model: [Scoring](/evals/scoring) for how numbers are computed, and [Baselines & Regressions](/evals/baselines-and-regressions) for how runs are compared.
</Tip>