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

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# What a result holds

> What a suite reports of each scenario of an offline run, and the environment the SDKs read.

What a suite reports of each scenario of an offline run, and the environment the SDKs read.

| Field | What it holds |
| - | - |
| `passed` | the suite's own verdict. Left out, the run reads by its scores alone |
| `rewards` | each check's score from 0 (fails) to 1 (passes), with a weight from 0 to 1000 (1) |
| `metrics` | anything else measured (turns, latency): any number |
| `reasons` | why each reward or metric got its value, by its name; at most 16,384 characters each |
| `task` | the scenario's prompt and what it expects, as verifiers' `TaskData`; at most 256 KiB |
| `judgeCalls` (`judge_calls`) | each judge exchange behind the scores, at most 64 |
| `errors` | what failed while the scenario ran |

* **A reward is from 0 to 1.** One outside it is refused before it is sent. A suite that scores out of 10 divides by
  10; a figure with no bound (a count, a cost) is a metric, not a reward.
* **Give a reason with every reward.** A reason is what `ambral runs verdicts` prints beside a failure, and what reading
  the failures for their failure modes starts from. A score without one says only that something went wrong.
* **Send `passed` when the suite has a verdict of its own.** Where it doesn't, the run's results stand mean scores in
  for pass counts, and `ambral runs verdicts --failed` is refused: use `--below 1`.
* **Send the task.** It is what `runs trace` shows of a scenario, and what tells a changed case from the same one: a
  changed task is a new revision, which `tasksets results` marks. Without it, every run of a scenario reads as the same
  revision, whatever changed. In Vitest, `scenario.task(data)`; under the pytest `conftest.py`, `scenario.task = …`; in
  a script, the result's `task`. verifiers reports the episode's task, and Harbor the task's checksum, by themselves.
  Each process sends it once per scenario, then its id alone.

## The SDK's settings

The SDK reads its settings from the environment:

| Variable | What it says |
| - | - |
| `AMBRAL_API_KEY` | the org's API key. Required |
| `AMBRAL_URL` | where Ambral is served, `https://app.ambral.ai` unless it is served elsewhere |
| `AMBRAL_EVAL_MODEL` | the model the run is served, when the code names none: the workload's primary if unset |
| `AMBRAL_EVAL_KEY` | the key the suite's processes share one run by |
| `AMBRAL_EVAL_SOURCE` | `ci` or `local`, where the code names none |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.