> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback: POST https://docs.omni.co/feedback ```json { "path": "/modeling/develop/ai-optimization", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # Optimize models for Omni AI > Use context to curate your models and improve the accuracy & relevance of Omni's AI. ## Requirements To follow this guide, you'll need: * An understanding of Omni modeling concepts * Familiarity with Omni's model IDE * Familiarity with basic AI terminology such as tokens, agents, etc. ## Common questions Context is information such as: * Descriptions of topics and fields * Possible field values * How a field might be used In Omni, this is provided to the AI using a **context window**. A context window is the amount of text an AI can read and consider at one time when answering a question or completing a task. Using context windows allows AI models to understand and incorporate relevant information. Specifically, providing context to the LLM makes it more effective, enabling it to interpret your request accurately and generate meaningful responses. Omni uses the following for context, in priority order: * `fully_qualified_name` (`view_name.field_name`) - For example, `order_items.total_sale_price` * `name` - For example, `total_sale_price` * `aliases` * `ai_context` * `all_values` - Used to specify the possible values for the field These properties will be pruned in the following order, but note that fields may be truncated entirely if required. 1. `description` 2. `group_label` - The categorization of the field 3. `label` - If defined, the value will be used. If not provided, a title-cased field name with underscores removed will be used. For example, `Total Sale Price` 4. `semantic_type` - The dimension or aggregate type, such as `dimension`, `sum`, `count`, etc. This value is evaluated based on the field definition and can't be directly modified. 5. `data_type` - The field's data type, such as `number`, `string`, etc. 6. `sample_values` - Example values for the field 7. `synonyms` - Other terms used to refer to the field Context applies to: * Omni Agent / [Embedded chat instances](/embed/customization/ai-chat) * [Workbook Agent](/ai/queries) in the workbook * AI summary visualizations * AI filter generator Omni's model can handle **\~200K** characters of context: * **\~15-25K** is reserved for Omni app context, which is used to ensure queries are generated properly * The remaining **\~175K characters** are allocated for context from the semantic layer before truncation, starting with field metadata To prevent field truncation, we recommend limiting the number of fields included in the context window to **550**. Let's look at example to explain to demonstrate why. You have a topic that you want to use for AI querying. Including the topic's `description`, `name`, `base_view`, `ai_context`, and the included fields' prioritized properties (ex: `name`), let's say the total characters used is around **10,000**. ``` 175,000 characters // total allocated for semantic layer context - 10,000 characters // topic metadata & prioritized field properties ------------------ 165,000 characters // total remaining for additional context ``` In the topic, the included fields generally look like this: ```yaml theme={null} active_camp_active_campaign_id_c: sql: '"ACTIVE_CAMP_ACTIVE_CAMPAIGN_ID_C"' label: Active Campaign Active Campaign ID group_label: Active Campaign ``` The total characters used for this field's basic metadata equals **160 characters**. You'll likely want to add [field-level context](#curate-views-and-fields), such as `description`, `sample_values`, and `ai_context`. Let's add **140 characters** to account for the AI-specific metadata, which brings the total characters per field to **300 characters**: ``` 160 characters // basic field metadata + 140 characters // field-level context for AI -------------- 300 characters // total field metadata ``` To get the total number of fields, divide the remaining characters available (**165,000**) by the total metadata characters per field: ``` 165,000 characters // total remaining for additional context / 300 characters // total field metadata ------------------- 550(ish) fields // total fields for inclusion ``` This gives you roughly **550** fields to include in the context window before Omni begins truncating fields. Context provided to Omni's AI is shared with AWS Bedrock. Refer to the [AI data security guide](/ai/security) for more information. ## Context and agent behavior As the previous section explained, Omni assembles `ai_context` from multiple levels — model, topic, view, and field — and passes it to the Omni Agent as part of the query generation prompt. The LLM that powers the Omni Agent makes its own decisions about which context to follow, how to weight it, and how to resolve apparent contradictions. This means: * **Model-level `ai_context` is not guaranteed to override topic-level `ai_context`.** All context is passed together; the LLM decides what to prioritize. * **Context is guidance, not strict instruction.** The LLM may partially follow, fully follow, or in some cases not follow a given instruction, especially when instructions are complex or contradictory. * **Behavior can be non-deterministic.** Running the same query twice may result in different context being applied, particularly when context is large or contains conflicting signals. Use the [workbook inspector](/analyze-explore/workbook-inspector#ai-messages) to view and debug the context for a given AI session. ## Curate AI outputs across the model You can use the model parameter [`ai_context`](/modeling/models/ai-context) to pass context shared across topics. This parameter may also be useful for topic selection in the Omni Agent. ### Personalize context with user attributes The `ai_context` parameter at the model, topic, and view levels supports [user attributes](/administration/users/attributes) through `${omni_attributes.}` syntax. At query time, Omni substitutes each placeholder with the current user's attribute value, allowing you to tailor AI behavior per user or group. ```yaml title="Topic ai_context using user attributes" theme={null} ai_context: | You are a sales analyst. When someone asks about their team or pipeline, always filter by account.segment = ${omni_attributes.segment} and account.region = ${omni_attributes.region}. ``` User attribute references are supported in `ai_context` at the model, topic, and view levels only. Dimension and measure `ai_context` does not support this syntax — the value is used as-is. Field references and filter conditions are also not supported and will produce a validation warning. ### Implement chain-of-thought reasoning for AI chat If you want the Omni Agent to give a more thorough explanation of what is being generated (topic selection, field selection, etc.), you can include the following context within the model's [`ai_context`](/modeling/models/ai-context). This can be altered and tweaked if desired, but the reference to `GenerateQuery` is required for proper behavior. ```yaml theme={null} ai_context: | Before calling the 'GenerateQuery' tool, please do the following steps: 1. Explain your reasoning of how you picked the fields in detail (9-10 sentences), under the header "Reasoning for field selection" 2. Another 3-4 sentences on alternative queries or fields you could have chosen under the header "Alternative approaches considered" 3. Finally add 4 markdown links as follow up questions under the header "Follow-up questions" ``` ### Output summaries in multiple languages If you'd like the Omni Agent to summarize outputs in multiple languages, you can include the following context: ```yaml theme={null} ai_context: | When generating a summary, always output the summary in both English and Spanish. ``` ## Curate topics [Topics](/modeling/topics) have an [`ai_context`](/modeling/topics/parameters/ai-context) parameter, which is useful for providing behavioral prompts and guidance for handling certain questions specific to the topic. For example: ```yaml title="ai_context for e-commerce orders topic" theme={null} ai_context: |- This topic is focuses on e-commerce orders. The main concepts are orders at the line item level in the order items table, users in our user table, inventory in our inventory items table, and products in the products table. Only respond with accurate answers based on the data that you're aware of. Don't pivot unless there is more than one dimension included in the query. Typical questions will be focused on order performance over time, breakdowns across users, and more. - if asked about sales or performance, always use the order_items.total_sale_price field - if asked about which users or who, use the users.full_name and users.email fields. Never return an ID unless explicitly asked. - if asked about top n without a specific metric or dimension, assume it involves the order_items.total_sale_price and products.name fields ``` You can use the [`ai_chat_topics`](/modeling/models/ai-chat-topics) model parameter to curate the list of topics that the Omni Agent or [embedded chat instances](/embed/customization/ai-chat) have access to. ### Limit fields included in the context window The Omni Agent only uses fields within the context of a topic. Fields with `hidden: true` are excluded from the context window. To control which fields are included, use the [`ai_fields`](/modeling/topics/parameters/ai-fields) parameter in a topic. For included fields, you can also provide additional [context at the field level](#curate-views-and-fields). We recommend periodically checking the **Analytics > AI usage** dashboard to see what questions your users are asking. This helps you identify opportunities to promote commonly used calculations and aggregations to the shared model, improving the self-serve experience over time. ### Reuse logic and limit the context window with topic extensions Topics that you're already leveraging in Omni can be extended to further curate them for AI. Using the [`extends`](/modeling/topics/parameters/extends) parameter, you can reuse the definition of an existing topic without needing to repeat the code. Consider the following `Order Transactions` topic, which you want to extend to create a curated version dedicated to AI usage: ```yaml title="Order Transactions topic" theme={null} label: Order Transactions default_filters: order_items.status: not: [ Returned, Cancelled ] joins: users: {} user_order_facts: {} inventory_items: products: distribution_centers: {} ``` In a new topic, use `extends: [ order_items ]` to extend the `Order Transactions` topic. You can then specify what to include in the AI-specific topic, such as limiting fields, filtering the data for specific use cases, adding more AI context, and so on: ```yaml title="Orders for AI querying topic, extended from Order Transactions" theme={null} extends: [ order_items ] base_view_label: Order Items label: Orders for AI Querying # limit fields included in the context window ai_fields: [ tag:use_for_ai ] ``` ### Add example queries as context Along with providing context about the topic itself, you can use the topic's [`sample_queries`](/modeling/topics/parameters/sample-queries) to provide example questions. This approach is useful if you anticipate specific, recurring questions or you find that the Omni Agent struggles with date filters. To do this, you'll want to: 1. Create a query in a workbook that contains the correct answer to the question. 2. In the workbook, click **Model > Save as sample query to topic**. 3. When prompted, fill in the following: * **Label** - A user-friendly name for the query * **Description** - An optional description * **Display on topic overview** - If checked, the query will display as a sample query when the topic is selected in a new query tab * **Include in AI context** - If checked, the query will be included in the AI context for the topic * **Prompt** - An optional example prompt that could be used to generate this query * **AI context** - Optional, additional context for the AI 4. When finished, click **Save**. You can also use the [model-level `sample_queries` parameter](/modeling/models/sample-queries) to define example queries that could be performed using the topics contained in the model. ## Curate views and fields [Views](/modeling/views) also have an [`ai_context`](/modeling/views/parameters/ai-context) parameter which can be useful for passing context to AI that is specific to the view. Keeping fields organized and labeled can not only help you create a top-notch self-service experience, it can also make Omni's AI more efficient. The following parameters can be used to add metadata to fields for the purposes of AI: * `ai_context` - Adds context useful for AI responses * `all_values` - All possible values for the field * **Note**: when the [dbt integration](/integrations/dbt/setup) is enabled, `accepted_values` tests will be ingested as `all_values` * `sample_values` - Example values for the field * `synonyms` - Other terms used to refer to the field You can use the workbook or the IDE to add the parameters. 1. In the field browser, click the (three dots icon) next to the field. 2. Click **Modeling > Edit** to open the **Edit field** side panel. Workbook AI parameters panel In the IDE, navigate to the view containing the field to add the parameters. For example: ```yaml title="products.view" theme={null} dimensions: brand: sql: '"BRAND"' description: Brand name of product sample_values: [ Calvin Klein, Carhartt, Hanes, Volcom, Levi's, Diesel, Lucky Brand, Quicksilver, Nautica, American Apparel, Columbia, Hurley, Dockers, Arc'teryx, C-IN2, DKNY, HOBO, NOM, ANS ] synonyms: [ logo ] ai_context: To filter this field, use contains with the brand name. ```