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

# Installation

> Requirements, package setup, and what gets added to your application.

## Requirements

| Requirement                                 | Version                                |
| ------------------------------------------- | -------------------------------------- |
| PHP                                         | 8.4+                                   |
| Laravel                                     | 12+                                    |
| [laravel/ai](https://github.com/laravel/ai) | ^0.10                                  |
| Pest (for the testing surface)              | ^4.0 on Laravel 12, ^5.0 on Laravel 13 |

The engine also works without Pest via the [CLI](/evals/cli) — Pest is a `suggest`, not a hard dependency.

<Note>
  Pest 5 requires `symfony/process ^8.1`, which Laravel 12 cannot satisfy — so Laravel 12
  tops out at Pest 4 and Laravel 13 gets Pest 5. `toPassEval()` behaves identically on both,
  and nothing in this documentation is Pest-5-only.

  If you want to run [`pestphp/pest-plugin-evals`](/evals/vs-pest-plugin-evals) alongside
  this package, that one needs Pest 5 and pins `laravel/ai` tightly — currently
  `>=0.10.2 <0.11.0` — so you will need Laravel 13 and a recent `laravel/ai`.
</Note>

## Install

```bash Terminal theme={null}
composer require vizra/evals --dev
php artisan migrate
```

<Info>
  Install with `--dev` when evals only run from your test suite and CI. If you trigger runs from the [dashboard](/evals/dashboard) in a deployed environment, require it as a regular dependency instead.
</Info>

Three tables are created (prefix configurable via `evals.table_prefix`):

| Table                    | Holds                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `eval_runs`              | One row per run: suite, git sha/branch, config snapshot, aggregate score/pass rate, cost, baseline flag |
| `eval_row_results`       | One row per sample: response text, tool calls, token usage, finish reason, score, duration, cost        |
| `eval_assertion_results` | One row per assertion per sample: status, score, weight, gate flag, expected/actual, judge reasoning    |

## Configuration (optional)

```bash Terminal theme={null}
php artisan vendor:publish --tag=evals-config
```

See [Configuration](/evals/configuration) for judge defaults, gates, the comparison tolerance, and the price table behind cost tracking.

## The dashboard (optional)

```bash Terminal theme={null}
composer require vizra/evals-ui
```

Adds the `/evals` dashboard — no publishing, no asset build in your app. See [Dashboard](/evals/dashboard).

## Provider credentials

Evals invoke your agents through `laravel/ai`, so whatever providers your agents use must be configured as usual (e.g. `OPENAI_API_KEY`). The [judge](/evals/judge) is an LLM call too and uses the provider configured in `evals.judge`. Nothing needs credentials until you actually run with `--evals` — normal test runs skip evals entirely, and [fakes](/evals/testing-without-tokens) cover everything else.