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

# Determinism and evidence

> What makes an answer repeatable, and the evidence that shows how it was reached.

## Two steps

Each turn has two steps. Your agent parses the user's words into a
request. Kviria then grounds the request in the area (the kind of place,
the name, the streets) and finds the answer in its map data.

Both of Kviria's steps follow fixed rules over the map data, the state and
the position. A given request, in a given area, always gets the same
answer. Places are ordered by facts, such as their distance or their
position along the street, never by opinion.

How the user's words became the request is your agent's step. The evidence
shows how Kviria read the request it received, so you can always check it.

## The evidence

Every response carries an `evidence` array. Each entry is one check:

| Field | What it holds |
| - | - |
| `test` | The check, such as `entry_path`, `name_match` or `confirm_gate` |
| `result` | `pass`, `warn` or `reject` |
| `reasonCode` | A stable code for the outcome |
| `detail` | Facts for the check, when it has any |

The first entries show how the request was read: how its kind of place, its
name and its streets matched the area (a `test` such as `kind`), and the
entry path, `entry_path` with `structured_intent`. The checks of the answer
follow.

The held answer in the [Quickstart](https://docs.kviria.com/quickstart.md) shows a trail:

```json theme={null}
{
  "decision": "one_unconfirmed",
  "target": {
    "gers": "cf88d374-1b13-4128-aaef-fbaea1aa704e",
    "name": "Rite Spot Cafe",
    "category": "cafe",
    "confidence": 0.9749269485473633,
    "distanceM": 59
  },
  "evidence": [
    {"test": "entry_path", "result": "pass", "reasonCode": "structured_intent"},
    {"test": "name_match", "result": "warn", "reasonCode": "partial_name"},
    {"test": "confirm_gate", "result": "warn", "reasonCode": "awaiting_user_verification"},
    {"test": "resolve", "result": "pass", "reasonCode": "single_survivor_pending"}
  ],
  "state": "AQVAQuGygPEsKMBempKjBVMmAQDPiNN0GxNBKKrv-66hqnBOAIiaeXwWMnnaSOhjfr2Viy0"
}
```

Use the evidence to debug a surprising answer, and keep it in your logs.
Never show it to the user. Your agent says the outcome in its own words.

## Left and right

Kviria does not know which way the user is facing, so it never decides
their left or right. When the user says left or right, the answer gives
the places on both sides, and an entry with the `test` value `side` and
the `reasonCode` value `side_not_used` says so. Ask the user which one they
mean.

When the answer lists the doors beside a place, the entry's `detail` also
names, for each door, the cross street at the end of the block it lies
toward, when that crossing is in range. It says too when only one side
has a neighbour:

```json theme={null}
{
  "test": "side",
  "result": "warn",
  "reasonCode": "side_not_used",
  "detail": {
    "side": "left",
    "toward": [
      { "name": "Starbucks", "toward": "Noe Street" },
      { "name": "The Lotus Method", "toward": null }
    ],
    "oneSideOnly": false
  }
}
```

## When nothing matches

When Kviria looks and finds nothing, the answer is `none`, with the kind of
place that was asked for in `category` when that is the useful fact.
Kviria does not make up a place to fill the gap.

A general kind, such as "a restaurant", also finds its narrower kinds in
the area, such as a pizza restaurant.

When the user asks for a kind of place that does not match any kind of
place in the area, the answer is `unclear`. Kviria does not claim that
nothing is there. Ask the user what they are looking for.

A position outside coverage also gets `none`, with an `out_of_coverage`
evidence entry. See [Coverage](https://docs.kviria.com/concepts/coverage.md).


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