> For the complete documentation index, see [llms.txt](https://help.tellius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tellius.com/tellius-6.4/data/kaiya-context-model/context-model-suggestions.md).
# Context model suggestions
How Kaiya learns from conversations and proposes changes to a context model that its owner approves or rejects.
A Kaiya context model gets better the more people use it. In their conversations, people often explain what they mean: what "underperforming" means for a territory, which products count as "the big three", or that "promo ROI" should leave out zero spend. Without suggestions, the next person who asks has to explain it all again. With suggestions turned on, Kaiya collects those explanations, checks them against the data, and proposes them as changes to the model. The model's owner, or someone who can edit the model, decides what goes in. Once approved changes are published to the model, they are used for everyone.
{% hint style="info" %}
Suggestions are turned off by default. A super user turns them on with **Learn from conversations (context model suggestions)** in [Kaiya Configuration](https://help.tellius.com/settings/kaiya-and-ai/kaiya-configuration). Kaiya proposes suggestions only on models whose owner's role has **Full Access** to the **Context Models** module. See [Who can work with a context model](https://help.tellius.com/data/kaiya-context-model#who-can-work-with-a-context-model). While the setting is off, a context model has no **Suggestions** tab, and its **Explore** tab has no **Suggestions** card.
{% endhint %}
### How it works
1. **Kaiya notes assumptions as people work.** Whenever a meaning gets settled in a conversation on a context model, Kaiya records it in the background: a metric definition, a business term, a rule, a default time window and so on. It records whether the person stated it, the person corrected Kaiya, or Kaiya inferred it on its own. Nobody has to do anything extra, and the note never slows down the answer. See [What Kaiya notes and what it leaves out](#what-kaiya-notes-and-what-it-leaves-out).
2. **Until it is approved, an assumption stays in its own conversation.** Kaiya uses it only in the conversation where it was made. In another conversation, people need to say it again, or ask Kaiya to add it to the model.
3. **Kaiya reviews the notes once a day.** Every day at 00:00 UTC, Kaiya looks at what all users assumed on each model since the last review. For each item, it keeps each user's latest view, flags people who changed their mind, and tests every formula and filter on the data to make sure the result is plausible. It drops items that don't hold up, items that were rejected before, and items below the minimum confidence set by your administrator.
4. **Kaiya proposes changes to the model's owner.** What's left becomes suggestions on the model's **Suggestions** tab. Each suggestion is a single change: add, update or delete one item. The owner gets an email when a new suggestion arrives.
5. **The owner decides.** The owner, or someone who can edit the model, approves or rejects each suggestion. Approving only marks a suggestion. Publishing then saves every approved suggestion to the model together, as one new version, and every later answer uses it. A rejected suggestion is recorded at once, and Kaiya won't suggest it again.
### What Kaiya notes and what it leaves out
Kaiya notes a meaning only when it settles a question about what the model means. It notes once per turn, after the analysis is done, for each context model the analysis used. A turn that only chatted, listed models or failed before any result adds nothing. A correction is noted even when it doesn't change any numbers, because the definition itself changed.
Kaiya notes these kinds of meaning:
| Kind | Example |
| --------------------- | ------------------------------------------------------------------------------------------ |
| **Metric** | "Net revenue" is gross sales minus returns, and the model has no metric for it. |
| **Calculated column** | A margin percentage that the person worked out from revenue and cost. |
| **Vocabulary** | "Active customer" means customers with an active status. |
| **Synonym** | "Turnover" means the revenue metric. |
| **Rule** | Refunds are always left out of sales figures. |
| **Relationship** | Orders join returns on the order ID, not the invoice ID. |
| **Default scope** | "Sales" means the last 12 months when no period is named. |
| **Entity mapping** | "EMEA" means the EU, UK and Middle East regions. |
| **Analysis** | How churn is worked out, step by step. |
| **Override** | The person set aside one of the model's rules or metrics for a reason that sounds general. |
Kaiya leaves out:
* **Personal preferences**, such as chart types, formatting, how long the answer is, or a currency ("show me in euros"). These never become suggestions.
* **One-off scoping of a single question**, such as "only for store 42" or "for last week". The exception is a phrase the person defines for good, such as "by last quarter I mean the latest full calendar quarter". Kaiya notes that.
* **Anything the model already says**, such as a metric or a business term used exactly as written, a column used under its own name, or the model's default date column.
* **Guesses Kaiya didn't act on.**
* **Data quality or data values**, as opposed to what the data means.
* **Defaults for things the person didn't mention.** For example, if someone sets a rule for one region only, Kaiya doesn't assume anything about the other regions.
Kaiya doesn't mention this note-taking in the chat, and it doesn't change the answer. If you ask Kaiya how it learns, it explains.
{% hint style="success" %}
**How to teach the model.** State a definition in so many words, for example *"By active prescriber I mean someone who wrote at least one prescription in the last 90 days."* Or correct Kaiya when it gets a meaning wrong. Both count more than a meaning Kaiya had to guess, and a correction counts the most.
{% endhint %}
### Who can review suggestions
The model's owner, an admin, or anyone the model is shared with using **Can Edit** access can approve and reject suggestions. Their role also needs **Full Access** to **Context Models**, and they need access to the model's datasource. People with view access, or whose role has only **Read Access** to **Context Models**, can't approve or reject.
* **Refresh suggestions** is available only to the people who can approve and reject.
* **Approve** works only when the current version of the model is selected, and while nobody is editing the model and Kaiya isn't in the middle of a review.
Suggestions show only counts of the people and conversations behind them, never what other users actually typed.
#### The email to the owner
When Kaiya has new suggestions for a model, the model's owner gets an email. Only the owner gets it, and each suggestion is emailed once. The email lists the suggested changes and points to **Data → Context Models**, then the model, then **Suggestions**. Nothing changes in the model until someone approves the suggestions and publishes them.
### The Suggestions tab
Open the model from **Data → Context Models** and select **Suggestions**. When suggestions are waiting, a count shows beside **Suggestions** on the tab and beside **Pending** inside it. The top of the tab says when Kaiya last reviewed conversations (**Last run**, or **Not run yet** for a new model). Hover over the info icon beside it for a reminder that Kaiya reviews what users assumed on the model once a day.
The model's **Explore** tab shows the same state in a **Suggestions** card at the right, for example **No pending suggestions** and **Last run: Not run yet**, so you can see at a glance whether anything is waiting without opening the tab.
**Refresh suggestions** asks Kaiya to review recent conversations now instead of waiting for the daily run. While it works, the button is unavailable and the tab shows **Kaiya is reviewing recent conversations**.
The tab has two views:
* **Pending:** suggestions waiting for a decision. This view opens by default. Use **All**, **Add**, **Update** and **Delete** to filter the list, and **Previous** and **Next** to move through it, for example **2 of 5**.
* **History:** every suggestion Kaiya made on this model and what became of it, including the ones you approved or rejected.
When nothing is waiting, the tab shows **No pending suggestions**.
{% hint style="success" %}
**When to select Refresh suggestions.** The daily review is enough for most models. Refresh when you have just had several conversations that settled what a term or metric means and want the owner to review them today, or after you edited the model, so that Kaiya checks a suggestion marked **Model changed since suggested** against the current version.
{% endhint %}
#### Reading a suggestion
Each pending suggestion is a card that shows:
* **The change:** **Add**, **Update** or **Delete**, and the item it affects, such as a metric or a vocabulary term.
* **Confidence:** **High confidence** or **Medium confidence**. See [How Kaiya rates confidence](#how-kaiya-rates-confidence).
* **Evidence:** how many users and conversations it came from, and when it was last seen.
* **Proposed change:** the change written out, with **Why** Kaiya proposes it and the **Checks on the data** it ran.
* **The YAML difference:** **In the model now** next to **After approval**, so you can see exactly what would change. Unchanged lines are folded away.
* **Details** or **Sources and checks:** the number of **Users** and **Conversations**, the **Latest** date, and **How it was learned**.
When people disagree, the card lists the **Options offered**, with the one Kaiya suggests marked **Recommended**.
If someone edited the same item in the model after Kaiya made the suggestion, the card shows **Model changed since suggested** and can't be approved as it is. Reject it, or select **Refresh suggestions** so that Kaiya checks it again against the current model.
#### How Kaiya rates confidence
* **High confidence:** the change checked out on the data, nothing conflicts with it, it has stayed stable over time, and either someone corrected Kaiya or several users agree on it.
* **Medium confidence:** the change checked out on the data, but it comes from one user only, people disagree on a minor point, or it hasn't been stable for long.
* **Low confidence** items are never proposed. Kaiya keeps watching them instead.
Some suggestions come from a meaning nobody stated: Kaiya worked it out from the data and the column names, and nobody objected. Kaiya proposes these at **Medium confidence** at most, marks them **Inferred — verify**, and proposes no more than three of them in each review.
{% hint style="warning" %}
**Check an Inferred suggestion before you approve it.** Nobody in a conversation confirmed it, so it's only as good as Kaiya's reading of the column names and values. Compare **In the model now** with **After approval**, look at the **Checks on the data**, and approve it only if it matches how your business defines the item.
{% endhint %}
#### Approving, publishing or rejecting
* **Approve:** marks the suggestion for the model. Nothing changes in the model yet. An approved suggestion shows **Approved**; select **Undo** to take the approval back.
* **Publish:** once you approve at least one suggestion, a bar shows how many are approved, with a **Publish N approved** button, for example **Publish 2 approved**. Publishing saves every approved suggestion to the model together, as one new version. A message confirms the version number, the published suggestions leave the **Pending** view, and the change shows in **Versions**, where you can compare it with the version before. See [Exploring and editing a context model](https://help.tellius.com/data/kaiya-context-model/exploring-and-editing-a-context-model#versions).
* **Reject:** applies at once. The change isn't made, the decision is recorded as **Rejected**, and Kaiya won't suggest it again.
If an approved suggestion no longer matches the current model, or the model wouldn't be valid with all your approvals, nothing is published. Tellius lists the suggestions or problems involved. Suggestions that no longer match are taken back off the approved list, so you can review them again.
If the model changed while you were looking at a suggestion, Tellius reloads the model and asks you to review the suggestion again.
{% hint style="success" %}
**When to approve and when to reject.**
* Approve when the suggestion matches how your business defines the term, and the **Checks on the data** look right. A suggestion with **High confidence** from several users is usually a sign that the model was missing something people keep needing.
* Reject when the meaning was right for one person's question but not for everyone, such as one analyst's own time window, or when it conflicts with an agreed definition.
* If a suggestion is close but not quite right, reject it and make the right change yourself, in the chat or by editing the YAML.
* Approve related suggestions together and publish them once, so they land in the same version and are easy to compare with the version before.
{% endhint %}
#### History
**History** opens on **Approved** each time you visit it. Use the filters to switch between **Approved**, **Rejected**, **Suggested**, **Withdrawn or dropped** and **All**. Entries are grouped by day, newest first, and each one shows the time, what happened, the suggestion, and the date. Open an entry to see its details and the change it proposed. What happened can be **Suggested**, **Updated**, **Withdrawn**, **Dropped**, **Approved** or **Rejected**. An approved entry shows the version it was saved in, and a dropped one shows the reason. Select **Load more** to see older entries. When a filter has no entries, the view shows **Nothing recorded yet**.
### Settings that control suggestions
A super user sets these under **Settings → Intelligence → Kaiya & AI → Kaiya Configuration**, in **Conversation & Capabilities**. Only super users see these settings. **Minimum suggestion confidence** and **Maximum pending suggestions** appear once **Learn from conversations (context model suggestions)** is on.
| Setting | What it does | Default |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Learn from conversations (context model suggestions)** | Turns assumption notes and daily suggestions on or off for every context model. | Off |
| **Minimum suggestion confidence** | The lowest confidence that reaches model owners. The options are **High** and **Medium**. Low confidence is never proposed. | Medium |
| **Maximum pending suggestions** | The most suggestions that can wait for review on one context model at a time, from 1 to 50. | 15 |
{% hint style="info" %}
**High or Medium?** Start with **Medium** while a model is new, so owners see what people need even when only one person has asked so far. Switch to **High** once a model is mature or widely used, so owners see only the changes several people agree on. Lower **Maximum pending suggestions** if owners find the list too long to review.
{% endhint %}
---
# 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://help.tellius.com/tellius-6.4/data/kaiya-context-model/context-model-suggestions.md?ask=&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.
