Determinism and evidence

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 shows a trail:

{
  "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:

{
  "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.

Get started

Guides

Concepts

Reference

Determinism and evidence

Two steps

The evidence

Left and right

When nothing matches

​Two steps

​The evidence

​Left and right

​When nothing matches

Two steps

The evidence

Left and right

When nothing matches