> For the complete documentation index, see [llms.txt](https://docs.rainbird.ai/rainbird/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rainbird.ai/rainbird/evidence/the-evidence-tree-v2.md).

# The Evidence Tree (v2)

### Overview

The Evidence Tree shows how Rainbird reached a result. It starts with the result and works back through every rule, condition and piece of data behind it, so you can see exactly why a decision was made.

Every result Rainbird returns has its own evidence tree. Each fact in the tree records where it came from and how certain Rainbird is of it.

Use the Evidence Tree to:

* **Debug a knowledge map.** Check that a rule fired for the reason you expected.
* **Troubleshoot a result.** Trace an unexpected answer back to the fact or condition that caused it.
* **Audit a decision.** Keep a link to the evidence alongside the result, and return to it whenever the decision is questioned.

### Opening an evidence tree

In Rainbird Studio, select the information icon next to a result. The evidence tree for that result opens in a new browser tab.

You can also open a tree from an evidence link. Rainbird agents can return one with a result, and developers can build one for any result returned by the API. See [Building an Evidence Tree URL](https://docs.rainbird.ai/rainbird/developer-docs/api-guide/building-an-evidence-tree-url).

The tree opens on the result alone: one card, with every condition closed. You choose which parts of the reasoning to open.

{% hint style="info" %}
Rainbird Studio and any previously saved links will continue to open the [v1 Rainbird Evidence Tree](https://docs.rainbird.ai/rainbird/evidence/the-evidence-tree-v1.md) until we have completed the migration to the new application.
{% endhint %}

#### Evidence keys and link sharing

Evidence is protected by default. Each knowledge map has an evidence key, and a tree only loads when the right key is supplied.

* **If the page asks for a key**, paste the evidence key shown in Rainbird Studio for that knowledge map and select **Use key**. The key is kept in that browser tab only. It is never added to the address bar, so a link you copy does not carry it.
* **To let people open evidence links without a key**, turn on link sharing for the knowledge map. In Studio, select **Publish** at the top left and toggle sharing on. Anyone with a link can then view that map's evidence, so only turn it on if you intend to share evidence this way.

### How to read the tree

Read the tree outwards from the result. Each card is one fact, and each line joins a rule's condition to the fact that satisfied it.

The result is the outlined card, and it is repeated in the bar at the top of the page with its source and certainty. By default the result sits on the right and its evidence opens to the left.

<figure><img src="https://2183467111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FehfnPLAHSx4uHugNiyth%2Fuploads%2FzfRKsmhUXk3rsoZ5wIjC%2Fimage.png?alt=media&amp;token=dc20bf0e-a291-4cb5-b638-4f2c5fa5a0ad" alt=""><figcaption></figcaption></figure>

*An evidence tree opened out. The result is the outlined card on the right. Each condition that has been opened links to the card for the fact behind it.*

#### Fact cards

Every card states one fact as a subject, a relationship and an object, for example *Dana Whitfield – has risk band – High*.

| Part of the card | What it tells you                                                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source chip      | Where the fact came from. See the sources below.                                                                                                      |
| Certainty        | How certain Rainbird is of the fact, from 0% to 100%. Rule cards show it as a large number beside a bar. Other cards show a meter in the card header. |
| Fact             | The subject, relationship and object. When the rule has alt text, the card leads with the alt text. The Advanced view shows the fact beneath it.      |
| Conditions       | On rule cards only: one numbered row for each condition, in rule order.                                                                               |
| Close (×)        | Closes the card and everything opened beneath it. The result card has no close control.                                                               |

#### Sources

The chip at the top of each card names the source of the fact. Each source has its own colour and symbol, and the label always appears with them.

| Chip            | The fact was                                                                                          |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| ◆ Rule          | Inferred by a rule. The card lists the rule's conditions.                                             |
| ƒ List function | Calculated by a list function inside an expression. The card lists the facts the function considered. |
| ● Answer        | Given by a user in answer to a question.                                                              |
| ▼ Data source   | Returned by a datasource.                                                                             |
| ▲ Injected      | Injected through the API.                                                                             |
| ■ Stored        | Held in the knowledge map.                                                                            |
| ✕ Not met       | Not found. This is a placeholder for a condition that was not met, and is always 0% certain.          |

A source the Evidence Tree does not recognise is shown under its own name.

#### Rule cards and conditions

A rule card explains an inferred fact. Beneath the fact it shows the rule's certainty, then every condition the rule evaluated.

Each condition row reads left to right: its number in the rule, a marker, a dot in the colour of the source behind it, the condition itself, and how much it contributed to the rule's certainty.

| On the row                  | Meaning                                                                        |
| --------------------------- | ------------------------------------------------------------------------------ |
| Chevron (›)                 | There is evidence behind this condition. Select the row to open it.            |
| ƒ                           | An expression, such as a comparison, with nothing further to open.             |
| Struck through, **Not met** | The condition was not met. It contributed 0%.                                  |
| **Missing**                 | The fact behind the condition is not in the stored evidence.                   |
| **shared**                  | The fact behind this condition also supports another condition.                |
| → %NAME                     | The expression stores its result in this variable. Shown in the Advanced view. |
| Greyed text                 | The condition was met but added nothing to the certainty.                      |

#### Lines

A line runs from a condition row to the card for the fact behind it. Thicker lines mean higher certainty: the thickest join facts that are 100% certain, the thinnest facts below 50%.

#### Expressions

An expression condition is marked ƒ. In the **Basic** view it shows its alt text. In the **Advanced** view it shows the expression beneath the alt text, with each variable as a chip. An expression with no alt text is shown in both views.

A chip carries the variable's name and the value it held when the rule ran. Dates are shown as *12 Mar 2026*.

#### List function cards

When an expression uses a list function, its condition row has a chevron. Select the row to open a list function card for each function in the expression.

In the **Advanced** view, each function also appears in the row as a chip with its result. Selecting the chip opens its card.

The card shows the function, its **Result**, and the **Facts considered**, each with its own certainty. For a minimum or maximum, the fact that supplied the value is tagged **Result**. If the function found nothing, the card says **No facts found**. Select any fact considered to open it in the tree.

<figure><img src="https://2183467111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FehfnPLAHSx4uHugNiyth%2Fuploads%2Fhbg6veK8wWhyIPRwAB5u%2Fimage.png?alt=media&amp;token=fe483240-2ad9-4de0-b0e8-4ada9d3af8d3" alt=""><figcaption></figcaption></figure>

*A list function card, opened from the first condition of the rule on the right. The tree is in the Advanced view, so each condition shows its alt text with the expression beneath.*

List function cards have no certainty of their own. Evidence from sessions created before v4.90 does not have expandable list functions.

#### Conditions that were not met

A rule can still succeed when an optional condition is not met. The row is struck through, flagged **Not met** and contributes 0%. Open it to see a **Not met** card, 0% certain, showing the fact the rule looked for.

### Features

The toolbar at the top of the page controls the whole tree. Cards and condition rows control their own part of it.

| Control                        | What it does                                                            |
| ------------------------------ | ----------------------------------------------------------------------- |
| ← → ↓ ↑                        | Sets the direction the tree flows. Right to left is the default.        |
| **Expand all**                 | Opens every fact in the tree.                                           |
| **Collapse all**               | Closes everything back to the result.                                   |
| **Search**                     | Finds any fact in the tree.                                             |
| **Basic / Advanced**           | Sets how rules and conditions read.                                     |
| **Merge shared facts**         | Shows a fact that supports several rules once, or once under each rule. |
| Theme                          | Switches between light and dark. Your choice is remembered.             |
| Zoom in, Zoom out, Fit to view | At the bottom right of the tree.                                        |
| **?**                          | Opens this documentation.                                               |

#### Open and close evidence

Select a condition row to open the fact behind it. Select the row again, or the × on the card, to close it and everything beneath it.

* The card you are working on stays where it is. The rest of the tree moves around it.
* Facts are fetched as you open them. The counter at the bottom left shows how many facts are loaded and how many are not yet fetched.
* Point at an open row to light up the card it opened and the line to it.
* Point at a card to light up every line into and out of it.

#### Expand all and Collapse all

**Expand all** fetches and opens the whole tree. A progress message shows the facts fetched and those still to go, and the button becomes **Cancel** while it runs. Conditions that were not met stay closed.

Expand all stops at 2,000 facts. If it stops early, the tree says that not everything is shown, and each unfetched card offers **Try again**.

**Collapse all** returns to the result on its own.

#### Focus on one condition

Point at a condition row and select the target icon at its right-hand end. The tree opens everything beneath that condition and dims the rest.

A bar above the tree names the condition in focus. To leave, select the icon again, the × on the bar, or press Esc.

#### Search

Select **Search** or press `/`. Type to search the subject, relationship, object and alt text of every fact. A fact matches when it contains every word you type.

Results are listed with those nearest the result first. Select one to open the path to it and bring it into view.

Facts not yet fetched are searched by their subject, relationship and object only. Select **Fetch the whole tree** to load every fact, without opening any cards, so the search covers everything.

#### See everything about a subject or object

Subjects and objects that are concept instances or text are selectable. They are shown with a dotted underline.

* Point at one to highlight it wherever it appears, and to see its concept, its type and how many facts mention it.
* Select one to open the **Concept instance** panel. It counts the facts, rules and conditions that mention the value, and lists the facts with the most certain first. Select a fact to open it in the tree.
* **Dim the rest** fades every card that does not mention the value. It is on by default.

Numbers, dates and true or false values are not selectable.

#### Trace a value in an expression

In the **Advanced** view, each variable in an expression is a chip. Point at a chip to see its name, value and type. Every chip for the same variable in the rule lights up, and so does the condition that set the value, where the evidence records it.

Select the chip to follow the value. If another expression computed it, that condition is highlighted. If a fact supplied it, the tree opens the path to that fact and highlights it. Clear the trace with the × on the trace bar, or press Esc.

Where the evidence does not record which condition set a value, selecting the chip does nothing.

#### Basic and Advanced views

Alt text is the plain-English description an author gives a rule or condition. The view sets whether you see that description on its own or with the underlying data beneath it.

Select **Basic** or **Advanced** in the toolbar, or press `A` to switch. Your choice is remembered in your browser.

| View                | Cards and conditions show                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Basic** (default) | The alt text only. Point at it to see the underlying fact or expression.                                                      |
| **Advanced**        | The alt text with the underlying fact or expression beneath it. Expressions show their variables and list functions as chips. |

<figure><img src="https://2183467111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FehfnPLAHSx4uHugNiyth%2Fuploads%2FKCTGKfahMPecPMIhsBVo%2Fimage.png?alt=media&amp;token=c15a69d4-9868-46a6-b37c-f8b28c0deb99" alt=""><figcaption></figcaption></figure>

*The same rule card in each view. Advanced adds the fact beneath the rule's alt text, and the expression beneath each condition's alt text.*

Where a rule or condition has no alt text, the fact or expression is shown in both views.

#### Merge shared facts

One fact often supports several rules. With **Merge shared facts** on, the default, the fact appears once with a line to every condition it supports. A chip on the card counts those links.

With it off, the fact is drawn once under each condition, and the chip counts how many times it appears.

#### Move around the tree

* Drag the background to pan.
* Scroll or pinch to zoom. **Fit to view** brings the whole tree back into view.

#### Keyboard

| Key        | Action                                                                 |
| ---------- | ---------------------------------------------------------------------- |
| Arrow keys | Move between cards                                                     |
| Enter      | Open the next closed condition on the current card                     |
| `/`        | Open search                                                            |
| `A`        | Switch between the Basic and Advanced views                            |
| Esc        | Close the side panel, then clear a trace, then clear a condition focus |

#### If something does not load

* A fact that cannot be fetched shows a **Couldn't load** card with **Try again**.
* If the result itself cannot be loaded, a banner at the top of the tree explains why.
* If the knowledge map protects its evidence, the page asks for the evidence key. See Evidence keys and link sharing.

### Certainty

Every fact carries a certainty from 0% to 100%, and every rule card shows how its certainty was built. The bar beside the number has one segment for each condition, as wide as that condition's contribution.

Select the bar to open the **Why N% certain** panel, which ranks every condition by its contribution. For how to read both, see The certainty breakdown.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rainbird.ai/rainbird/evidence/the-evidence-tree-v2.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
