Add AI context page to data modeling (cube-js#10605)

* Add AI context page to data modeling section

Generated-By: mintlify-agent

* fix

---------

Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
Co-authored-by: Artyom Keydunov <artyom.keydunov@gmail.com>

Author: mintlify[bot]

docs-mintlify/docs.json

@@ -85,6 +85,7 @@
                   "docs/data-modeling/concepts/data-blending"
                 ]
               },
+              "docs/data-modeling/ai-context",
               {
                 "group": "Access Control",
                 "pages": [

docs-mintlify/docs/data-modeling/ai-context.mdx

@@ -0,0 +1,290 @@
+---
+title: AI context
+description: Optimize your data model for AI by using descriptions and the meta ai_context property to provide additional context.
+---
+
+When using [Analytics Chat][ref-analytics-chat] or other AI-powered features,
+the AI agent relies on your data model to understand your data. You can
+optimize your data model to help the AI generate more accurate queries and
+provide better insights.
+
+There are two ways to provide additional context to the AI:
+
+- **Descriptions** — visible to both end users and the AI agent.
+- **AI context via `meta`** — only visible to the AI agent, not exposed in the
+  user interface.
+
+## Using descriptions
+
+The [`description`][ref-cube-description] parameter on cubes, views, measures,
+dimensions, and segments provides human-readable context that is displayed in
+the UI and also consumed by the AI agent.
+
+Use descriptions to clarify the meaning of a member for both your team and
+end users:
+
+<CodeGroup>
+
+```yaml title="YAML"
+cubes:
+  - name: orders
+    sql_table: orders
+    description: All orders including pending, shipped, and completed
+
+    measures:
+      - name: total_revenue
+        sql: amount
+        type: sum
+        description: Total revenue from completed orders only
+        filters:
+          - sql: "{CUBE}.status = 'completed'"
+
+    dimensions:
+      - name: status
+        sql: status
+        type: string
+        description: "Current order status: pending, shipped, or completed"
+```
+
+```javascript title="JavaScript"
+cube(`orders`, {
+  sql_table: `orders`,
+  description: `All orders including pending, shipped, and completed`,
+
+  measures: {
+    total_revenue: {
+      sql: `amount`,
+      type: `sum`,
+      description: `Total revenue from completed orders only`,
+      filters: [{ sql: `${CUBE}.status = 'completed'` }]
+    }
+  },
+
+  dimensions: {
+    status: {
+      sql: `status`,
+      type: `string`,
+      description: `Current order status: pending, shipped, or completed`
+    }
+  }
+})
+```
+
+</CodeGroup>
+
+Descriptions are a good starting point because they serve double duty — they
+help end users understand the data and also give the AI agent context for
+query generation.
+
+## Using AI context
+
+If you want to provide context to the AI agent **without exposing it in the
+user interface**, use the `ai_context` key inside the
+[`meta`][ref-cube-meta] parameter. The `meta` parameter accepts custom
+metadata on cubes, views, measures, and dimensions.
+
+<CodeGroup>
+
+```yaml title="YAML"
+cubes:
+  - name: orders
+    sql_table: orders
+    description: All orders
+    meta:
+      ai_context: >
+        This cube contains all e-commerce orders. When users ask about
+        revenue, prefer the total_revenue measure which filters for
+        completed orders only. The amount column includes tax.
+
+    measures:
+      - name: total_revenue
+        sql: amount
+        type: sum
+        filters:
+          - sql: "{CUBE}.status = 'completed'"
+        meta:
+          ai_context: >
+            Use this measure for any revenue-related questions.
+            This excludes pending and cancelled orders.
+
+    dimensions:
+      - name: created_at
+        sql: created_at
+        type: time
+        meta:
+          ai_context: >
+            This is the order creation timestamp in UTC.
+            For fiscal year reporting, use the completed_at
+            dimension instead.
+```
+
+```javascript title="JavaScript"
+cube(`orders`, {
+  sql_table: `orders`,
+  description: `All orders`,
+  meta: {
+    ai_context: `This cube contains all e-commerce orders. When users ask
+      about revenue, prefer the total_revenue measure which filters for
+      completed orders only. The amount column includes tax.`
+  },
+
+  measures: {
+    total_revenue: {
+      sql: `amount`,
+      type: `sum`,
+      filters: [{ sql: `${CUBE}.status = 'completed'` }],
+      meta: {
+        ai_context: `Use this measure for any revenue-related questions.
+          This excludes pending and cancelled orders.`
+      }
+    }
+  },
+
+  dimensions: {
+    created_at: {
+      sql: `created_at`,
+      type: `time`,
+      meta: {
+        ai_context: `This is the order creation timestamp in UTC.
+          For fiscal year reporting, use the completed_at
+          dimension instead.`
+      }
+    }
+  }
+})
+```
+
+</CodeGroup>
+
+You can also use `ai_context` on [views][ref-view-meta]:
+
+<CodeGroup>
+
+```yaml title="YAML"
+views:
+  - name: revenue_overview
+    description: Revenue metrics and breakdowns
+    meta:
+      ai_context: >
+        This is the primary view for revenue analysis. It combines
+        order and product data. Use this view when users ask about
+        sales, revenue, or product performance.
+
+    cubes:
+      - join_path: orders
+        includes:
+          - total_revenue
+          - created_at
+          - status
+```
+
+```javascript title="JavaScript"
+view(`revenue_overview`, {
+  description: `Revenue metrics and breakdowns`,
+  meta: {
+    ai_context: `This is the primary view for revenue analysis. It combines
+      order and product data. Use this view when users ask about
+      sales, revenue, or product performance.`
+  },
+
+  cubes: [
+    {
+      join_path: orders,
+      includes: [
+        `total_revenue`,
+        `created_at`,
+        `status`
+      ]
+    }
+  ]
+})
+```
+
+</CodeGroup>
+
+## Descriptions vs. AI context
+
+| | `description` | `meta.ai_context` |
+| --- | --- | --- |
+| Visible in the UI | Yes | No |
+| Used by the AI agent | Yes | Yes |
+| Supported on | Cubes, views, measures, dimensions, segments | Cubes, views, measures, dimensions |
+
+Use `description` when the context is useful to both end users and the AI
+agent. Use `ai_context` when you want to provide additional instructions or
+context that is only relevant to the AI agent — for example, guidance on
+which measures to prefer, nuances about data quality, or business logic that
+would be confusing in a user-facing description.
+
+You can use both together. The AI agent reads both the `description` and
+`ai_context` when generating queries:
+
+<CodeGroup>
+
+```yaml title="YAML"
+cubes:
+  - name: orders
+    sql_table: orders
+    description: All customer orders
+    meta:
+      ai_context: >
+        When users ask about "sales", they usually mean completed
+        orders only. Prefer total_revenue over raw amount sums.
+
+    measures:
+      - name: total_revenue
+        sql: amount
+        type: sum
+        description: Total revenue from completed orders
+        filters:
+          - sql: "{CUBE}.status = 'completed'"
+        meta:
+          ai_context: >
+            This is the primary revenue metric. Always use this
+            instead of summing the amount dimension directly.
+```
+
+```javascript title="JavaScript"
+cube(`orders`, {
+  sql_table: `orders`,
+  description: `All customer orders`,
+  meta: {
+    ai_context: `When users ask about "sales", they usually mean completed
+      orders only. Prefer total_revenue over raw amount sums.`
+  },
+
+  measures: {
+    total_revenue: {
+      sql: `amount`,
+      type: `sum`,
+      description: `Total revenue from completed orders`,
+      filters: [{ sql: `${CUBE}.status = 'completed'` }],
+      meta: {
+        ai_context: `This is the primary revenue metric. Always use this
+          instead of summing the amount dimension directly.`
+      }
+    }
+  }
+})
+```
+
+</CodeGroup>
+
+## Best practices
+
+- **Add descriptions to all public members.** Descriptions help both end users
+  and the AI agent understand your data model.
+- **Use AI context for agent-specific guidance.** If you need to tell the AI
+  agent which measure to prefer or how to interpret ambiguous terms, use
+  `ai_context`.
+- **Be specific.** Vague context like "important metric" is less helpful than
+  "use this measure when users ask about monthly recurring revenue."
+- **Document relationships.** Use AI context to explain how cubes relate to each
+  other and which views to prefer for common questions.
+- **Keep it up to date.** As your data model evolves, update descriptions and AI
+  context to reflect the current state.
+
+[ref-analytics-chat]: /docs/explore-analyze/analytics-chat
+[ref-cube-description]: /reference/data-modeling/cube#description
+[ref-cube-meta]: /reference/data-modeling/cube#meta
+[ref-view-meta]: /reference/data-modeling/view#meta

docs-mintlify/reference/data-modeling/cube.mdx

@@ -585,6 +585,9 @@ SELECT FLOOR(EXTRACT(EPOCH FROM NOW()) / 5)
 
 Custom metadata. Can be used to pass any information to the frontend.
 
+You can also use the `ai_context` key to provide context to the
+[AI agent][ref-ai-context] without exposing it in the user interface.
+
 <CodeGroup>
 
 ```yaml title="YAML"
@@ -594,6 +597,9 @@ cubes:
     title: Product Orders
     meta:
       any: value
+      ai_context: >
+        This cube contains all e-commerce orders. When users ask
+        about revenue, prefer the total_revenue measure.
 
 ```
 
@@ -602,7 +608,9 @@ cube(`orders`, {
   sql_table: `orders`,
   title: `Product Orders`,
   meta: {
-    any: `value`
+    any: `value`,
+    ai_context: `This cube contains all e-commerce orders. When users ask
+      about revenue, prefer the total_revenue measure.`
   }
 })
 ```
@@ -648,6 +656,7 @@ The `measures` parameter is used to configure [measures][ref-ref-measures].
 The `access_policy` parameter is used to configure [access policies][ref-ref-dap].
 
 
+[ref-ai-context]: /docs/data-modeling/ai-context
 [ref-config-driverfactory]: /reference/configuration/config#driverfactory
 [ref-recipe-control-access-cubes-views]: /docs/data-modeling/access-control/recipes/controlling-access-to-cubes-and-views
 [ref-naming]: /docs/data-modeling/syntax#naming

docs-mintlify/reference/data-modeling/dimensions.mdx

@@ -430,6 +430,9 @@ Using it with other dimension types will result in a validation error.
 
 Custom metadata. Can be used to pass any information to the frontend.
 
+You can also use the `ai_context` key to provide context to the
+[AI agent][ref-ai-context] without exposing it in the user interface.
+
 <CodeGroup>
 
 ```yaml title="YAML"
@@ -443,6 +446,9 @@ cubes:
         type: number
         meta:
           any: value
+          ai_context: >
+            This is a subquery dimension. Use it to get the
+            number of users associated with each product.
 ```
 
 ```javascript title="JavaScript"
@@ -454,7 +460,9 @@ cube(`products`, {
       sql: `${users.count}`,
       type: `number`,
       meta: {
-        any: "value"
+        any: "value",
+        ai_context: `This is a subquery dimension. Use it to get the
+          number of users associated with each product.`
       }
     }
   }
@@ -1187,6 +1195,7 @@ cube(`fiscal_calendar`, {
 </CodeGroup>
 
 
+[ref-ai-context]: /docs/data-modeling/ai-context
 [ref-ref-cubes]: /reference/data-modeling/cube
 [ref-schema-ref-joins]: /reference/data-modeling/joins
 [ref-subquery]: /docs/data-modeling/concepts/calculated-members#subquery-dimensions