> ## 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. # 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: These properties are never removed from the context window, even when space runs out: * `name` - The field's fully qualified name (`view_name.field_name`). For example, `order_items.total_sale_price` * `ai_context` - Context you write for the AI. When Omni assembles context for a specific topic, `ai_context` is never pruned, whether it's defined on the model, topic, view, or field. The exception is when the AI is choosing a topic; see [What limitations does context have?](#context-limits) If a topic's metadata exceeds the space Omni allots for it (see [What limitations does context have?](#context-limits)), Omni prunes the following properties, starting with the lowest priority. Each property is removed from every field before the next is considered: 1. `all_values` - The field's possible values. Pruned first because the AI can retrieve a field's values on demand when it needs them. 2. `sql` - The field's SQL definition, when included 3. `sample_values` - Example values for the field 4. `description` 5. `group_label` - The categorization of the field 6. `label` - The field's display name. If not defined, Omni generates one by title-casing the field name and removing underscores. For example, `Total Sale Price` 7. `aggregate_type` - A measure's aggregation type, such as `sum`, `count`, etc. This value is evaluated based on the field definition and can't be directly modified. 8. `data_type` - The field's data type, such as `number`, `string`, etc. To save space, this property is automatically omitted when the type can be inferred, such as for string fields. 9. `synonyms` - Other terms used to refer to the field. Pruned last because synonyms help the AI match the language in a user's question to the right field. If removing all of these properties still isn't enough, Omni may exclude entire views from the results the Omni Agent sees when it searches the model. If the remaining context still exceeds what the AI model can accept (for example, because a topic carries a large amount of `ai_context`, which Omni never trims), the request fails with an error. Context applies to: * Omni Agent and [embedded chat instances](/embed/customization/ai-chat), including topic selection and model search * [Workbook Agent](/ai/queries), including query and SQL generation * [Chat with Content](/ai/dashboard-assistant) summaries * AI visualization generation and summary visualizations * AI filter generation * [Modeling Agent](/ai/model-assistant) and modeling workflows, such as topic metadata generation and learn-from-conversation The AI model's context window is shared by everything in a request, including: * Omni's built-in instructions, which ensure queries are generated properly * Context from your semantic model, such as topic and field metadata, `ai_context`, and sample queries * The conversation history and query results To keep requests fast and leave room for the rest of the conversation, Omni caps how much of the window your model's metadata can use. These caps - not the full context window - are what determine when pruning begins: * **A topic's field definitions are capped at roughly 75K characters.** When a topic's metadata exceeds the cap, Omni prunes field properties in the order described in [What does Omni AI use for context?](#context-priority). * **When choosing a topic, the AI reads a summary of every topic, capped at roughly 100K characters.** If the summary exceeds the cap, Omni trims view metadata (including view-level `ai_context`), then sample queries, and trims topic metadata only as a last resort. The AI recovers trimmed details when it selects a specific topic. * **Searches outside of a topic return up to 100 fields.** When [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/query-all-views-and-fields) is enabled, the AI finds fields for views that aren't in a topic by searching the model. Instead of pruning properties, each search returns at most 100 fields and the AI runs narrower searches to find the rest. How many fields fit under the cap varies widely with how much metadata each field carries: a lightly annotated field uses around 100 characters, while a field with a rich description, sample values, and `ai_context` can use several times that. Instead of targeting a field count, use the [workbook inspector](/analyze-explore/workbook-inspector#ai-messages) to see the context the AI actually received, and curate with [`ai_fields`](/modeling/topics/parameters/ai-fields) to focus each topic on the fields users actually ask about. A smaller, well-described set of fields gives the AI fewer chances to pick the wrong one. Conversation history is managed separately - refer to the [`conversation_prune_length` reference](/modeling/models/parameters/ai-settings/conversation-prune-length) for more information. 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" wrap 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.

Optimize context for different AI models

The `ai_context` parameter at the model, topic, and view levels supports model-specific customization through the `omni_llm` namespace. This ensures optimal performance across AI model options by allowing you to tailor AI instructions to the capabilities of different AI model tiers: * `smartest` - Most capable models suited for complex reasoning * `standard` - Balanced models for typical queries * `fastest` - Optimized for speed and simple requests For example, you can provide different chain-of-thought instructions based on model tier. In the following example, the first block (`{{# omni_llm.smartest }}`) would apply when the model tier is `smartest`, and the second (`{{^ omni_llm.smartest }}`) would apply when the model tier is `standard` or `fastest`: ```yaml title="Model-level ai_context with omni_llm" wrap theme={null} ai_context: | {{# omni_llm.smartest }} Before calling 'GenerateQuery', explain your reasoning for field selection in detail (9-10 sentences) under "Reasoning for field selection", then provide 3-4 sentences on alternative approaches under "Alternative approaches considered". {{/ omni_llm.smartest }} {{^ omni_llm.smartest }} Proceed directly to generating the query without intermediate explanation steps. {{/ omni_llm.smartest }} ``` You can also adjust analysis depth based on model capabilities: ```yaml title="Topic-level ai_context with omni_llm" wrap theme={null} ai_context: | This topic focuses on financial transactions. {{# omni_llm.smartest }} For complex multi-table queries, consider indirect relationships and provide rationale for join path selection. {{/ omni_llm.smartest }} {{# omni_llm.standard }} Use straightforward joins between related tables. {{/ omni_llm.standard }} {{# omni_llm.fastest }} Prefer single-table queries when possible. {{/ omni_llm.fastest }} ``` See the `ai_context` references for [models](/modeling/models/ai-context), [topics](/modeling/topics/parameters/ai-context), and [views](/modeling/views/parameters/ai-context) for more information and examples.

Optimize context for different AI agents

The `ai_context` parameter at the model, topic, and view levels also supports agent-specific customization through the `omni_agent` namespace. This lets you scope portions of your context to the AI agent that will read it, preventing bulky agent-specific content from inflating context windows for other agents. The three agent types correspond to existing AI settings configuration categories: * `analyze` - Used for search-model tool and query generation * `build` - Used for topic metadata generation and learn-from-conversation * `simple_summarize` - Used for tile/visualization summaries and query metadata For example, you might want to provide detailed modeling conventions to the build agent while keeping the analyze agent's context concise: ```yaml title="Model-level ai_context with omni_agent" wrap theme={null} ai_context: | {{# omni_agent.build }} Modeling conventions: Always define primary keys. Use snake_case for field names. Prefer measures over dimensions for aggregations. {{/ omni_agent.build }} {{^ omni_agent.build }} Keep queries focused and efficient. {{/ omni_agent.build }} This context is read by the {{ omni_agent.name }} agent. ``` You can also provide agent-specific query optimization tips at the topic level: ```yaml title="Topic-level ai_context with omni_agent" wrap theme={null} ai_context: | This topic focuses on user activity data. {{# omni_agent.analyze }} For performance, prefer filtering by date ranges before joining to user details. {{/ omni_agent.analyze }} {{# omni_agent.build }} When generating field relationships, consider that user_id is the primary key linking activity to users. {{/ omni_agent.build }} ``` See the `ai_context` references for [models](/modeling/models/ai-context), [topics](/modeling/topics/parameters/ai-context), and [views](/modeling/views/parameters/ai-context) for more information and examples. ### Use constants for reusable AI context You can define reusable AI instruction blocks as [`constants`](/modeling/models/constants) and reference them across multiple `ai_context` fields using `@{constant_name}` syntax. This approach helps you maintain shared context (tone, privacy guidance, domain context) in a single location instead of duplicating it across models, topics, views, and sample queries. ```yaml title="Model file with reusable AI context constants" theme={null} constants: tone: value: "Keep responses concise and professional." privacy_high: value: "Never show individual customer names or emails." domain_finance: value: "This is a financial analytics model. Use monetary values with precision." ai_context: | @{tone} @{privacy_high} @{domain_finance} ``` You can then reference these same constants in topic-level, view-level, and sample query `ai_context` fields, ensuring consistent instruction blocks across your model while keeping maintenance centralized. See the [`constants` reference](/modeling/models/constants#reusable-ai-context) for more details and examples. ### Implement chain-of-thought reasoning 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 needed, but the reference to `GenerateQuery` is required for proper behavior. ```yaml wrap 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" ``` If you don't want to implement chain-of-thought reasoning for all model tiers, you can provide [model tier-specific](#model-specific-context) instructions instead. ### 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 wrap 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" wrap expandable theme={null} ai_context: |- This topic 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 When querying within a topic, the AI uses only that topic's fields. When querying outside of a topic, it can use fields from any view in the model. 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" wrap 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. ```