# Mastering Kaiya conversational AI

Kaiya AI Agents are a fully orchestrated analytics engine, where you can use natural language to automate everything from simple metrics to advanced diagnostics.

With Kaiya AI agents, you can:

* Move from simple metrics to root cause insights in a single flow.
* Leverage AI orchestration to avoid manual report building, SQL writing, or dashboard tweaking.
* Handle complex logic—filters, groupings, comparisons—without needing technical expertise.
* Trust Kaiya to guide you, even when queries aren’t perfect.

{% hint style="success" %}
Under the hood, Kaiya parses questions into roles—**Measure**, **Filters**, **Grouping**, **Time**, **Limit/Sort**—and supports common aggregations (sum, avg, min, max, count/uniqueCount, median, market share) and time grains (yearly, quarterly, monthly, weekly, daily, hourly).
{% endhint %}

## 1. **Live data access vs. Optimized historical queries**

Kaiya dynamically selects data sources based on your query's time context.

* **Live data queries**\
  When you ask for recent periods (*<mark style="color:blue;">"Show me TRx for this month"</mark>*), the Data Prep Agent pulls from live, constantly updated datasets. This ensures you're making decisions on the most current information.
* **Historical queries**\
  If you're analyzing past periods (*<mark style="color:blue;">"Show TRx for 2022"</mark>*), Kaiya automatically optimizes performance by querying cached datasets or archives, reducing load times without compromising accuracy.
* **Smart de-duplication**\
  For domains like pharma sales where duplicate transactions exist, queries like *"<mark style="color:blue;">Show TRx for Ioxalin in April 2024"</mark>* trigger deduplication logic within the Data Prep Agent—no manual cleaning required.

## 2. **Conversational context: Follow-up intelligence**

Unlike static BI tools, Kaiya retains session context across your queries and adapts query structure without requiring you to restate parameters. If you ask, *<mark style="color:blue;">"Show TRx for March 2024"</mark>,* and follow up with *<mark style="color:blue;">"How about last month?"</mark>,* Kaiya understands that <mark style="color:blue;">"</mark>*<mark style="color:blue;">last month</mark>*<mark style="color:blue;">"</mark> refers to **February 2024**, applies previous filters (e.g., product, region), and re-runs the query.

Other follow-up capabilities:

* *<mark style="color:blue;">"What about by product?"</mark>*\
  Kaiya understands that you now want to see the previous metric broken down by product. It automatically restructures the query to group the results by the "Product" dimension.
* *<mark style="color:blue;">"Show it weekly instead"</mark>*\
  Kaiya switches your data view to show weekly trends, keeping your previous selections (like product, region, or date range) intact.

## 3. **Advanced time handling**

Kaiya’s date/time parsing engine allows you to express time filters naturally:

* *<mark style="color:blue;">"Show TRx after November 2023"</mark>*\
  Kaiya understands that you're asking for all TRx (Total Prescriptions) and applies a date filter to include only records starting from December 1, 2023, onward.
* *<mark style="color:blue;">"Monthly TRx for PillABC"</mark>*\
  Kaiya organizes the TRx numbers for PillABC into a month-by-month breakdown, so you can easily see how prescriptions change over time.
* *<mark style="color:blue;">"For 'March 2024'"</mark>*\
  When you use quotes like "March 2024", Kaiya treats it as a specific, fixed time period.

Kaiya also intuitively understands relative timeframes: *"Last quarter"*, *"Past 6 months"*, *"Year-to-date"*&#x20;

## 4. **Dynamic filtering across values, lists, and substrings**

Kaiya automatically applies the right filters based on how you describe them—whether it's a single value, multiple options, or partial matches.

* **Single filters**:\
  \&#xNAN;*<mark style="color:blue;">"Show TRx for Virginia"</mark>* → Applies exact match filters.
* **Multi-value filters**:\
  \&#xNAN;*<mark style="color:blue;">"Show TRx for Virginia and California"</mark>* → Builds compound filters with proper logical operators.
* **Substring matching**:\
  \&#xNAN;*<mark style="color:blue;">"Indication contains OTH"</mark>* → Translates to LIKE/CONTAINS logic in the backend.
* **Logical combinations**:\
  \&#xNAN;*<mark style="color:blue;">"TRx for dermatology in NY OR NJ"</mark>* → Correctly applies AND/OR logic, respecting precedence.

## 5. **Group by and Aggregation**

You can organize and analyze complex datasets by simply describing how you want to break down your data. Kaiya supports SUM, AVG, MIN, MAX, Top N / Bottom N, and nested groupings without explicit instructions.

* *<mark style="color:blue;">"Show TRx by region and product"</mark>*\
  Kaiya automatically applies multi-level grouping, summarizing Total Prescriptions first by region, then by product within each region—exactly like you'd build a nested pivot table, but without manual setup.
* *<mark style="color:blue;">"TRx by all ecosystems"</mark>*\
  Kaiya interprets the word **"all"** intelligently, expanding your request to group data across every relevant dimension (e.g., region, segment, product category), without needing you to list them explicitly.
* *<mark style="color:blue;">"Top 5 HCPs by Units"</mark>*\
  This triggers both an aggregation (summing Units) and a ranking function, returning the highest performers.

## 6. **Comparisons made effortless**

Kaiya handles aligning datasets, managing time frames, visualizing side-by-side comparisons. With simple phrasing, you trigger complex comparative analysis:

* *<mark style="color:blue;">"Compare NRx between Decile 7-8 vs 9-10"</mark>*\
  Kaiya understands you're asking for a side-by-side comparison of two HCP segments (Deciles 7-8 vs. 9-10), and it automatically filters, groups to calculate the differences between these segments
* *<mark style="color:blue;">"TRx in Q1 2024 vs Q1 2023"</mark>*\
  This triggers a period-over-period comparison, where Kaiya calculates both the absolute change and the percentage change in Total Prescriptions between the two quarters.
* *<mark style="color:blue;">"Marketshare of ProductK vs ProductL in CA"</mark>*\
  Here, Kaiya recognizes you're asking for a product vs. product comparison within a specific region. It retrieves the market share data for both products and presents them in a comparative format.

{% hint style="info" %}
When asking about **trends**, explicitly mention the resolution (e.g., monthly, quarterly). For **market share** questions, mention the comparison scope (for example, “Market share of Brand A vs Brand B in California”).
{% endhint %}

## 7. **Growth and trend calculations**

You don’t need to specify formulas for growth. Kaiya can distinguish between point-in-time comparisons, continuous growth trends, event-based deltas (*<mark style="color:blue;">"before and after campaign in Oct 2023"</mark>*).

* *<mark style="color:blue;">"Show TRx growth over 6 months"</mark>*\
  Kaiya understands you're asking for how Total Prescriptions have changed over the past 6 months. and automatically calculates the percentage growth (or decline) month-over-month.
* *<mark style="color:blue;">"NRx growth in West vs East"</mark>*\
  Kaiya detects that you're looking for a regional comparison of growth. It gives side-by-side growth metrics by segment (in this case, West and East regions), highlighting which region is growing faster or declining.
* *<mark style="color:blue;">"Monthly trend of TRx for Product X"</mark>*\
  Recognizing the time-based trend analysis, Kaiya plots Total Prescriptions for Product X across each month, showing how Product X's prescriptions have moved month by month—perfect for spotting peaks, drops, or seasonal patterns.

## **8. Insight-driven questions ("Why" and "Compare")**

When you ask:

* *<mark style="color:blue;">"Why did TRx drop in Q2 2024?"</mark>*
* *<mark style="color:blue;">"Compare TRx between Q1 2023 and Q1 2024"</mark>*

Kaiya triggers the **Insights Agent** to do more than just show numbers. It identifies key drivers, breaks down variances, highlights top contributing factors, and presents both visuals and clear explanations—automating what would normally be manual analysis. You get immediate diagnostic insights without extra effort.

## 9. **Handling complex filtering logic**

Kaiya translates your natural language into precise backend logic, without requiring you to use parentheses or Boolean operators.

* *<mark style="color:blue;">"TRx for Product N in NY where HCP Decile is 9"</mark>*\
  Kaiya applies nested filtering, combining multiple conditions—filtering by product, location, and a specific HCP segment—all in one query.
* *<mark style="color:blue;">"TRx for dermatology in NY OR NJ"</mark>*\
  Kaiya correctly interprets and handles the logical operators (in this case, "OR").

{% hint style="warning" %}
Kaiya handles errors gracefully by providing clear, actionable feedback—whether it's an invalid dimension, unknown filter value, missing metric, or backend issue—so you’re guided to fix the input without confusion or dead ends. It never fails silently, ensuring smooth, transparent interactions.
{% endhint %}

## 10. Single-BV, Auto-BV, and Multi-BV

Kaiya supports three distinct BV-selection modes. They look similar from the chat surface but behave differently underneath.

* **Single-BV (manual).** You pick one BV from the dropdown. Every question in the conversation runs against that BV. Use this when you know exactly which BV holds the data and you don't want Kaiya to second-guess.
* **Auto-BV (dynamic).** Kaiya picks the most relevant BV for each question independently, and the chosen BV can change between turns as the topic shifts. Filters, time windows, and entity context carry forward when Kaiya switches. Each individual question still resolves against a single BV.
* **Multi-BV.** You select up to three BVs at once for the session, and Kaiya joins across them using soft links authored at the BV level. Use this when answering questions that genuinely require combining data from multiple BVs — for example, joining call activity from one BV with prescription volume from another.

Multi-BV and Auto-BV can both be active in the same conversation: a single session can have multiple BVs in play, and the topic can shift between turns.

For the full behavior on multi-BV, check out [Multi-Business Views in Kaiya](/tellius-6.3/kaiya/kaiya-conversational-ai/multi-business-view-conversations.md).

## 11. Chart types Kaiya produces

When you ask Kaiya a Text-to-SQL question, it visualizes the result as a chart or table. You can ask for a specific chart by name, or let Kaiya pick based on the question and the shape of the result.

### Supported chart types

You can ask for any of these by name:

* **Line:** trends over time (days, weeks, months, years). Example: *"Show revenue by month."*
* **Column:** compare categories or discrete periods. Example: *"Sales by product."*
* **Pie:** part-to-whole across a small number of categories. Example: *"Share of sales by region."*
* **Donut:** same as pie, with a center label; good for a small number of slices.
* **Detail table:** exact values in a tabular view; good for many categories or deep inspection.

If you'd rather let Kaiya decide, just say *"show the chart"* or *"visualize this data"* and it picks based on the result shape.

{% hint style="warning" %}
If you ask for any unsupported chart, Kaiya falls back to the closest supported chart or to a detail table.
{% endhint %}

{% hint style="info" %}
This page covers Kaiya's Text-to-SQL chart output only. The full Tellius chart library (used in Vizpads and Search) supports many more chart types. Check out [Know your charts](/tellius-6.3/search/know-your-charts-in-tellius.md).
{% endhint %}

## 12. Ask Kaiya about itself

You can ask Kaiya about its own features and capabilities at any time, in plain language; no special syntax required. This is useful when you want a quick orientation before diving in, or when you're checking whether a specific feature is supported in your deployment.

Examples:

* *"What can you do?"*
* *"What chart types do you support?"*
* *"What workflows are available?"*
* *"How do I use memory?"*
* *"What are your limitations?"*

Kaiya answers in plain language, grounded in the features actually available in your deployment. If something isn't supported, Kaiya says so directly instead of guessing.

{% hint style="warning" %}
Capability questions are about **Kaiya's features**, not your data. To explore your dataset (columns, metrics, values), ask the question directly — *"what columns are in my dataset?"* or *"show me sales by region"* — and Kaiya routes it to the analytics workflow.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.tellius.com/tellius-6.3/kaiya/kaiya-conversational-ai/mastering-kaiya-conversational-ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.