The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
On-demand skills system for Metabot (#75249)
Mihael Konjevićec842e146cb5
diff --git a/resources/metabot/prompts/llm_shape.selmer b/resources/metabot/prompts/llm_shape.selmerindex 7b224dd7d48..88efc76a9b0 100644--- a/resources/metabot/prompts/llm_shape.selmer+++ b/resources/metabot/prompts/llm_shape.selmer@@ -15,7 +15,7 @@</segment>{% endif %}{% if is_field %}-<field id="{{field_id}}" name="{{field_name_quoted|safe}}" display_name="{{field_display_name}}" type="{{field_base_type}}" database_type="{{field_database_type}}"{% if field_fk_target_fqn %} fk_target_fully_qualified_name="{{field_fk_target_fqn}}"{% endif %}>{% if field_description %}+<field id="{{field_id}}" name="{{field_name|safe}}" display_name="{{field_display_name}}" type="{{field_base_type}}" database_type="{{field_database_type}}"{% if field_fk_target_fqn %} fk_target_fully_qualified_name="{{field_fk_target_fqn}}"{% endif %}>{% if field_description %}## Description{{field_description}}{% endif %}</field>{% endif %}@@ -312,7 +312,9 @@ They provide a rough idea of the data characteristics but may not reflect the co{% if is_field_metadata %}{% if field_metadata_value_xml %}<field-metadata field_id="{{field_metadata_field_id}}">- {{field_metadata_value_xml|safe}}+{% if field_metadata_source %} Source table: {{field_metadata_source}}+{% endif %}{% if field_metadata_reference %} Reference (copy into a field clause): {{field_metadata_reference|safe}}+{% endif %} {{field_metadata_value_xml|safe}}</field-metadata>{% else %}No metadata available to display. This doesn't mean the column is empty or cannot be queried - there may be various reasons why values aren't shown here.diff --git a/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmer b/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmerindex c347c71e2f2..5b619bba5a7 100644--- a/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmer+++ b/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmer@@ -2,6 +2,16 @@Published metrics are business-validated calculations — same definition every team uses. Models are curated, analysis-ready datasets. Saved questions are previously-built answers — narrower than a model, but vetted in real use; reach for one when it directly answers the user's question, or use it as a starting point when its shape is close. Raw tables are the source. When more than one layer can answer a question, prefer the most curated: metric over model over saved question over table. Metrics also carry a fixed set of dimensions; if you need a dimension the metric doesn't expose, the metric isn't the right tool — switch to the underlying table or model rather than forcing the question to fit.+## A named measure is almost always a defined metric, measure, or segment — find it, don't recompute it++When the user names a business quantity — a **rate or ratio** ("open rate", "bounce rate", "churn rate", "conversion rate", "utilization rate"), an **aggregate with a name** ("average order value", "MRR", "active subscribers"), or a **named cohort/filter** ("hard bounces", "SUBSCRIBED customers", "high-value opportunities") — assume the organization has already defined it and reach for the definition rather than reconstructing it from raw columns:++- **Metrics** — a named aggregation that lives independently. Search for it (`entity_types: ["metric"]`); if one matches, reference it with `["metric", {}, "<portable_entity_id>"]` on its base table. Don't rebuild it as `count` / `count-where` / a hand-rolled ratio.+- **Measures** — a named aggregation attached to a table. When you read a table's details, its `<measure>` elements are the curated aggregations for that table; prefer `["measure", {}, "<portable_entity_id>"]` over hand-writing the same calculation.+- **Segments** — a named, reusable filter attached to a table. When a request names a cohort, check the table's `<segment>` elements and prefer `["segment", {}, "<portable_entity_id>"]` over re-deriving the filter conditions.++Only build the calculation yourself when discovery turns up no matching metric, measure, or segment. (See the construct skills for the exact clause syntax.) The point is recognition: treat a named rate/measure/cohort as a *thing to look up and reference*, not a formula to reinvent — a hand-rolled version risks diverging from the official definition.+## Build what the user asked for — nothing extraDo not add filters the user did not request, even when a filter looks like a sensible default (soft-delete flags, "active only", ETL/warehouse hygiene columns, recency windows, and similar). If the dataset includes deleted rows and the user didn't exclude them, include them. Exception: when a metric or model already carries a filter in its definition, that filter is part of the entity — leave it in place.diff --git a/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer b/resources/metabot/prompts/shared/prompt_snippets/grounding.selmerindex 5c03a554de9..b25a55fafb0 100644--- a/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer+++ b/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer@@ -20,6 +20,14 @@ When a filter value the user asked for isn't in the sample, that's fine — sampFor numeric, date, or free-text fields where the user's intent maps onto the schema directly (e.g. `amount > 1000`, `created_at in 2024`), a sample check isn't required. Verify when you'll compare against a specific literal value whose format you can't predict.+## Attempt an answer before handing back to the user++You're judged on producing the query the user wants, not on caveats. A clarifying question or an empty hand-back is a last resort — used after discovery has genuinely failed, not as the first response to an under-specified or referential request. Push a little further into the problem before giving up.++- **Resolve references yourself.** A follow-up like "narrow that to 2024", "filter it to hard bounces", or "only SUBSCRIBED customers" refers to something already in play. Check what the user is currently viewing and their recently-viewed items, and search for the most likely entity, before concluding you don't know what they mean — "it" / "that" / "those" almost always points at the metric, question, or table in the current context.+- **Commit to a reasonable interpretation.** When a request is under-specified but a sensible default exists, build the query for that default and note the assumption in your reply, rather than asking the user to restate. A query they can correct beats a question they have to answer.+- Reserve clarifying questions for genuine structural forks where guessing wrong yields a fundamentally different result (e.g. "top customers by revenue or by order count?") — not for references you can resolve from context, or details you can discover with the metadata tools.+## Disclose what isn't nailed downWhen you took a judgement call the user should know about — applied a format pattern to a value that wasn't in samples, picked between two equivalent fields, used a relative date when the question was ambiguous — say so briefly in your final message alongside the result. Don't be exhaustive; the goal is to flag the one or two things the user might want to correct.diff --git a/resources/metabot/prompts/shared/skills.selmer b/resources/metabot/prompts/shared/skills.selmernew file mode 100644index 00000000000..c7c10bce25e--- /dev/null+++ b/resources/metabot/prompts/shared/skills.selmer@@ -0,0 +1,13 @@+{% if skill_catalog %}+# Available skills++These skills hold detailed, task-specific instructions. Before doing the related+work, load the skill(s) you need with the `load_skill` tool (you may load several+at once). Load only what's relevant.+{% for s in skill_catalog %}+- **{{ s.id }}** — {{ s.description }}+{% endfor %}+{% endif %}+{% for body in skill_always_on %}+{{ body|safe }}+{% endfor %}diff --git a/resources/metabot/prompts/system/embedding-next.selmer b/resources/metabot/prompts/system/embedding-next.selmerindex e5257c8ec3d..6177a291ee3 100644--- a/resources/metabot/prompts/system/embedding-next.selmer+++ b/resources/metabot/prompts/system/embedding-next.selmer@@ -32,17 +32,7 @@ Your job is to answer analytical questions by producing visualizations. For othe- SQL queries: direct the user to the SQL editor.- Finding existing saved content: direct the user to search/browse.-{% if tool_instructions %}-# Tool reference--<tools>-{% for tool_instruction in tool_instructions %}-<tool name="{{tool_instruction.tool_name}}">-{{tool_instruction.instructions}}-</tool>-{% endfor %}-</tools>-{% endif %}+{% include "metabot/prompts/shared/skills.selmer" %}{% if custom_instructions %}diff --git a/resources/metabot/prompts/system/internal.selmer b/resources/metabot/prompts/system/internal.selmerindex f868d61c316..88209ba4965 100644--- a/resources/metabot/prompts/system/internal.selmer+++ b/resources/metabot/prompts/system/internal.selmer@@ -17,17 +17,7 @@ A single objective: **the query you build should return the data the user asked{% if has_sql_generation %}# Writing SQL-Metabase is read-only: your SQL is always a `SELECT` (CTEs/`WITH` are fine for transforms; never `CREATE`, `INSERT`, `UPDATE`, `DELETE`, `ALTER`, `DROP`, `TRUNCATE`). Deliver SQL through the SQL tools rather than pasting it into chat — the tools place it in the editor for the user. Verify the format of any literal you filter or branch on before writing it (see grounding above). The full SQL contract — model reference syntax, fully-qualified table names, dialect notes — is in the SQL tool reference below.-{% if sql_dialect_instructions %}--## SQL dialect: {{ sql_dialect | upper }}--The target database uses the **{{ sql_dialect }}** dialect. Follow these dialect-specific rules:--<dialect_instructions>-{{ sql_dialect_instructions|safe }}-</dialect_instructions>-{% endif %}+Metabase is read-only: your SQL is always a `SELECT` (CTEs/`WITH` are fine for transforms; never `CREATE`, `INSERT`, `UPDATE`, `DELETE`, `ALTER`, `DROP`, `TRUNCATE`). Deliver SQL through the SQL tools rather than pasting it into chat — the tools place it in the editor for the user. Verify the format of any literal you filter or branch on before writing it (see grounding above). The full SQL contract — model reference syntax, fully-qualified table names — is in the SQL skills (load them via `load_skill`).{% if sql_dialect_loaded %} When the user is in the SQL editor, dialect-specific instructions for **{{ sql_dialect }}** have already been loaded into this conversation — follow them.{% endif %}{% endif %}{% else %}# Discovery only@@ -63,17 +53,7 @@ You can create X-ray auto-generated dashboards from a single table, model, or meYou answer analytical questions and help users find existing content. When a request needs a custom dashboard with specific cards, direct the user to the dashboard builder. For finding saved content, search and present what's there.-{% if tool_instructions %}-# Tool reference--<tools>-{% for tool_instruction in tool_instructions %}-<tool name="{{ tool_instruction.tool_name }}">-{{ tool_instruction.instructions|safe }}-</tool>-{% endfor %}-</tools>-{% endif %}+{% include "metabot/prompts/shared/skills.selmer" %}{% if custom_instructions %}# Custom Instructionsdiff --git a/resources/metabot/prompts/system/natural-language-querying-only.selmer b/resources/metabot/prompts/system/natural-language-querying-only.selmerindex 819e1906a2b..165c5385de8 100644--- a/resources/metabot/prompts/system/natural-language-querying-only.selmer+++ b/resources/metabot/prompts/system/natural-language-querying-only.selmer@@ -32,17 +32,7 @@ Your job is to answer analytical questions by producing visualizations. For othe- SQL queries: direct the user to the SQL editor.- Finding existing saved content: direct the user to search/browse.-{% if tool_instructions %}-# Tool reference--<tools>-{% for tool_instruction in tool_instructions %}-<tool name="{{tool_instruction.tool_name}}">-{{tool_instruction.instructions}}-</tool>-{% endfor %}-</tools>-{% endif %}+{% include "metabot/prompts/shared/skills.selmer" %}{% if custom_instructions %}diff --git a/resources/metabot/prompts/system/slackbot.selmer b/resources/metabot/prompts/system/slackbot.selmerindex f9c04f18417..90b112f08e8 100644--- a/resources/metabot/prompts/system/slackbot.selmer+++ b/resources/metabot/prompts/system/slackbot.selmer@@ -306,19 +306,7 @@ You naturally weave reliability context into your responses:{% include "metabot/prompts/shared/prompt_snippets/personality.selmer" %}-{% if tool_instructions %}-<tool_instructions>-# Tool-Specific Instructions--The following tools have specific behavioral requirements that you must follow:--{% for tool_instruction in tool_instructions %}-<tool name="{{ tool_instruction.tool_name }}">-{{ tool_instruction.instructions }}-</tool>-{% endfor %}-</tool_instructions>-{% endif %}+{% include "metabot/prompts/shared/skills.selmer" %}<environment># Environment Integrationdiff --git a/resources/metabot/prompts/system/sql-querying-only.selmer b/resources/metabot/prompts/system/sql-querying-only.selmerindex 3a68e384864..99aaa027665 100644--- a/resources/metabot/prompts/system/sql-querying-only.selmer+++ b/resources/metabot/prompts/system/sql-querying-only.selmer@@ -331,29 +331,15 @@ If you are fixing SQL errors it is FORBIDDEN to replace referenced models and ta- Use UNION ALL instead of UNION when duplicates don't matter- Consider creating models for frequently-used complex queries-{% if sql_dialect_instructions %}+{% if sql_dialect %}# SQL Dialect: {{sql_dialect|upper}}-The target database uses the **{{sql_dialect}}** SQL dialect. Follow these dialect-specific rules:--<dialect_instructions>-{{sql_dialect_instructions}}-</dialect_instructions>+The target database uses the **{{sql_dialect}}** SQL dialect.{% if sql_dialect_loaded %} When the user is in the SQL editor, its dialect-specific instructions have already been loaded into this conversation — follow them.{% endif %}{% endif %}{% include "metabot/prompts/shared/prompt_snippets/field-references.selmer" %}-{% if tool_instructions %}-# Tool-Specific Instructions--<tools>-{% for tool_instruction in tool_instructions %}-<tool name="{{tool_instruction.tool_name}}">-{{tool_instruction.instructions}}-</tool>-{% endfor %}-</tools>-{% endif %}+{% include "metabot/prompts/shared/skills.selmer" %}# Special Responsesdiff --git a/resources/metabot/prompts/system/transform-codegen.selmer b/resources/metabot/prompts/system/transform-codegen.selmerindex fc3c835fa97..d2725c0b501 100644--- a/resources/metabot/prompts/system/transform-codegen.selmer+++ b/resources/metabot/prompts/system/transform-codegen.selmer@@ -373,19 +373,7 @@ This ensures you have full context about referenced entities before making chang{% include "metabot/prompts/shared/prompt_snippets/field-references.selmer" %}-{% if tool_instructions %}-# Tool-Specific Instructions--The following tools have specific behavioral requirements that you must follow:--<tools>-{% for tool_instruction in tool_instructions %}-<tool name="{{ tool_instruction.tool_name }}">-{{ tool_instruction.instructions }}-</tool>-{% endfor %}-</tools>-{% endif %}+{% include "metabot/prompts/shared/skills.selmer" %}<<<METABOT_CACHE_BREAKPOINT>>>diff --git a/resources/metabot/prompts/tools/search_metabase_documentation.md b/resources/metabot/prompts/tools/search_metabase_documentation.mddeleted file mode 100644index a974d482a91..00000000000--- a/resources/metabot/prompts/tools/search_metabase_documentation.md+++ /dev/null@@ -1,42 +0,0 @@-Search the official Metabase documentation using hybrid semantic + keyword search to retrieve authoritative information about Metabase features, configuration, and usage.--**CRITICAL: Always search docs for Metabase-specific syntax and features rather than guessing based on general knowledge.**--**Important notes:**-- Custom expressions and formulas in Metabase reference fields by their display names, not database column names-- Metabase syntax differs from standard SQL - always verify syntax in documentation before providing examples--**When to use:**-- User asks about Metabase product features, capabilities, or limitations-- Questions about how to configure, set up, or use specific Metabase functionality-- **Before providing syntax examples for custom expressions, filters, or formulas** - verify correct syntax and field referencing-- Clarifying whether something is possible in Metabase before making claims-- User explicitly requests information from documentation-- Follow-up questions after initial doc search (search again with refined query)-- Questions starting with "how do/does", "what is", "can I/you", "is it possible"-- Explaining Metabase concepts, terminology, or best practices-- When you're about to provide specific code/syntax examples for Metabase features--**When NOT to use:**-- Questions about data in the user's database (use query/analysis tools instead)-- SQL or database-specific questions unrelated to Metabase features-- General programming or analytics concepts not specific to Metabase-- Questions already definitively answered in current conversation context--**Best practices:**-- Formulate specific, clear search queries focused on key concepts-- For ambiguous questions, search first to ground your response in documentation-- Reference specific documentation sections in your response when available-- If initial results are insufficient, refine your query and search again--**Examples of good use cases:**-- "How do I use custom expressions in Metabase?" → Search for custom expression syntax and available functions-- "How can I calculate XYZ with a custom expression?" → Search for custom expression syntax, CASE statements, and mathematical operations-- "What filters are available in Metabase dashboards?" → Search for dashboard filtering capabilities-- "Can I schedule email reports?" → Search to verify feature availability and configuration-- "How do I set up SSO?" → Search for authentication and SSO setup instructions-- "What's the difference between questions and models?" → Search for concept explanations--**Limitations:**-- Returns top 10 most relevant documentation chunks-- Search works best with specific feature names or clear concept queriesdiff --git a/resources/metabot/prompts/tools/ask_for_sql_clarification.md b/resources/metabot/skills/ask-for-sql-clarification.mdsimilarity index 75%rename from resources/metabot/prompts/tools/ask_for_sql_clarification.mdrename to resources/metabot/skills/ask-for-sql-clarification.mdindex 69d36600fab..d140fbfdabc 100644--- a/resources/metabot/prompts/tools/ask_for_sql_clarification.md+++ b/resources/metabot/skills/ask-for-sql-clarification.md@@ -1,3 +1,10 @@+---+id: ask-for-sql-clarification+title: Asking for SQL clarification+description: Asking the user a short clarifying question with ask_for_sql_clarification — load to learn when a request is genuinely ambiguous enough to ask vs. when to pick a default and deliver SQL instead.+tools: [ask_for_sql_clarification]+priority: 50+---Ask the user a short clarifying question when their request is genuinely ambiguous. The `question` text is inserted as a SQL comment at the user's cursor — so this is a small-surface input for *short prose only*, not a delivery channel.**Use only for:**diff --git a/resources/metabot/skills/construct-notebook-query-advanced.md b/resources/metabot/skills/construct-notebook-query-advanced.mdnew file mode 100644index 00000000000..4fca8cad7c7--- /dev/null+++ b/resources/metabot/skills/construct-notebook-query-advanced.md@@ -0,0 +1,195 @@+---+id: construct-notebook-query-advanced+title: Construct notebook query — advanced+description: Joins (explicit and implicit), multi-stage queries, querying saved questions/models with source-card, metrics, measures, segments, expressions, and aggregation references in construct_notebook_query — load when a query needs any of these.+tools: [construct_notebook_query]+priority: 50+---+# Construct Query Reference — Advanced++These are the advanced building blocks for `construct_notebook_query`. The base clause shape, field references, and rules live in the **construct-notebook-query-core** skill; the operator/function catalogs live in **construct-notebook-query-operators**.++## Aggregation references++To refer to an aggregation already in the same stage's `aggregation` list — e.g. from `order-by`:+1. **Inline** — repeat the clause itself. The inline form must match an entry in `aggregation` **exactly** (same op, same args). The tool rewrites it to a reference.+2. **By 0-based index** (preferred when reused) — `["aggregation", {}, 0]` means "the first aggregation".++Out-of-range indices surface a clear error listing every available aggregation with its index.++## Expressions++Define custom columns inside a stage using `expressions` and reference by name with `["expression", {}, "<Name>"]`. Object form (preferred); the name becomes the column's display name.++```json+"expressions": {+ "Subtotal": ["+", {},+ ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "TOTAL"]],+ ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "TAX"]]]+},+"aggregation": [["sum", {}, ["expression", {}, "Subtotal"]]]+```++The sequential form `[["expression", {}, "Name", expr], ...]` is also accepted and auto-converted.++## Joins (explicit)++```json+"joins": [{+ "alias": "Products",+ "strategy": "left-join",+ "stages": [{"lib/type": "mbql.stage/mbql",+ "source-table": ["Sample Database", "PUBLIC", "PRODUCTS"]}],+ "conditions": [["=", {},+ ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "PRODUCT_ID"]],+ ["field", {"join-alias": "Products"},+ ["Sample Database", "PUBLIC", "PRODUCTS", "ID"]]]]+}],+"breakout": [["field", {"join-alias": "Products"},+ ["Sample Database", "PUBLIC", "PRODUCTS", "CATEGORY"]]]+```++- `alias` is a free-choice string; use it consistently in conditions, breakout, aggregation, order-by.+- `strategy` is one of `"left-join"`, `"right-join"`, `"inner-join"`, `"full-join"`. Default `"left-join"`.+- **Every** field reference on the joined side must carry `{"join-alias": "<same-alias>"}`.+- Join `conditions` accept only `=`, `!=`, `<`, `<=`, `>`, `>=` — no `between`, `in`, `and`/`or` wrappers.++## Implicit joins++Reference a field on a related table directly — when the source has exactly one FK to that target, the tool auto-fills `source-field` and performs the implicit join:++```json+"source-table": ["Sample Database", "PUBLIC", "ORDERS"],+"aggregation": [["count", {}]],+"breakout": [["field", {}, ["Sample Database", "PUBLIC", "PRODUCTS", "CATEGORY"]]]+```++- **Multiple FKs** to the target → `:ambiguous-fk` lists them. Retry with explicit `{"source-field": ["DB", "SCH", "SRC", "FK_COL"]}` on the field.+- **No FK path** → `:no-fk-path`. Switch to an explicit `joins` entry, or pick a field on the source table.+- Inside an explicit `joins` block, joined-side field refs still need `{"join-alias": ...}` — implicit-join repair does not rewrite those.+- If the FK column lives on a previous stage's output, write `{"source-field-name": "<col>"}` (not auto-filled).+- If multiple explicit joins all expose the target FK, `:ambiguous-fk-via-join` lists them — set `{"source-field-join-alias": "<alias>"}` to pick one.++**Tip:** discover FKs with `entity_details` / `read_resource metabase://table/<id>/fields`. FK columns are tagged `fk_target_fully_qualified_name="schema.table.field"` — always look for one before assuming a column lives on the current table.++## Multi-stage queries++Every stage after the first consumes the previous stage's output. Only the first stage has a `source-table`/`source-card`; later stages omit it.++Post-aggregation filter — count orders per product, keep only those with > 10:++```json+"stages": [+ {"lib/type": "mbql.stage/mbql",+ "source-table": ["Sample Database", "PUBLIC", "ORDERS"],+ "aggregation": [["count", {}]],+ "breakout": [["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "PRODUCT_ID"]]]},+ {"lib/type": "mbql.stage/mbql",+ "filters": [[">", {}, ["field", {}, "count"], 10]]}+]+```++Re-aggregate — average daily total by month:++```json+"stages": [+ {"lib/type": "mbql.stage/mbql",+ "source-table": ["Sample Database", "PUBLIC", "ORDERS"],+ "aggregation": [["sum", {}, ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "TOTAL"]]]],+ "breakout": [["field", {"temporal-unit": "day"},+ ["Sample Database", "PUBLIC", "ORDERS", "CREATED_AT"]]]},+ {"lib/type": "mbql.stage/mbql",+ "aggregation": [["avg", {}, ["field", {}, "sum"]]],+ "breakout": [["field", {"temporal-unit": "month"}, ["field", {}, "CREATED_AT"]]]}+]+```++- Cross-stage refs use a **string name** in slot 3 (e.g. `["field", {}, "count"]`). The name is whatever the previous stage's aggregation/breakout/field produced (`count`, `sum`, or the source field's name).+- Within the **same stage**, refer to your own aggregation with `["aggregation", {}, <idx>]` (see Aggregation references above). In a **later** stage, use the cross-stage string-name form against the previous stage's output.+- Joins, expressions, filters, aggregation, breakout, order-by, limit are all valid in later stages.++## Rates and ratios (numerator ÷ denominator) — always two stages++A rate like **open rate**, **bounce rate**, **conversion rate**, or **% of total** divides one aggregation by another. You **cannot** divide two aggregations inside a single stage's `expressions` — that produces a *non-aggregation expression* error. Compute the numerator and denominator as separate aggregations in **stage 1**, then divide them in **stage 2**.++Worked example — share of small orders per month (`count of orders under $50 ÷ total orders`):++```json+{"lib/type": "mbql/query",+ "stages": [+ {"lib/type": "mbql.stage/mbql",+ "source-table": ["Sample Database", "PUBLIC", "ORDERS"],+ "aggregation": [+ ["count-where", {}, ["<", {}, ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "TOTAL"]], 50]],+ ["count", {}]],+ "breakout": [["field", {"temporal-unit": "month"},+ ["Sample Database", "PUBLIC", "ORDERS", "CREATED_AT"]]]},+ {"lib/type": "mbql.stage/mbql",+ "expressions": {+ "Small Order Rate": ["/", {}, ["field", {}, "count_where"], ["field", {}, "count"]]},+ "fields": [["field", {}, "CREATED_AT"],+ ["expression", {}, "Small Order Rate"]]}]}+```++Stage 2 references each stage-1 aggregation by the **output column name** it produced — `count`, `sum`, `avg`, etc., and `count_where` for `count-where` — and a `breakout`/passthrough column keeps its own name (e.g. `CREATED_AT`). Don't worry about the exact spelling: the tool canonicalises common variants for you (a hyphenated `count-where` or a quoted `"count"` is matched to the real column), so use the natural name. If two aggregations would collide on a name, give one an explicit `{"name": "..."}` to disambiguate. Multiply by 100 for a percentage: `["*", {}, ["/", {}, ["field", {}, "count_where"], ["field", {}, "count"]], 100]`.++## Saved questions and models (`source-card`)++Instead of `source-table`, use `source-card` to query an existing question or model. The value is the card's **portable entity id** — a 21-char opaque string reported by `entity_details` and search tools as `portable_entity_id`.++1. Get the `portable_entity_id` from a tool response. `search` and `read_resource` (`metabase://question/<id>`, `metabase://model/<id>`) include it on the result tag — reuse what's already in context, no extra call needed.+2. Copy it **verbatim** into `source-card`. The id is opaque — never guess, construct, or abbreviate.+3. Reference the card's columns by output **name** (string in slot 3), not portable FK. If you don't know the names, call `read_resource metabase://question/<numeric-id>/fields` (or `.../model/...`).++```json+{"lib/type": "mbql.stage/mbql",+ "source-card": "T4wA_GPFwGb6R4FxIDGTo",+ "filters": [[">", {}, ["field", {}, "total"], 100]],+ "limit": 50}+```++A stage has either `source-table` **or** `source-card`, never both. The card must live in the same database as the rest of the query (no cross-database queries). Falling back to native SQL like `SELECT * FROM {{#<id>-<slug>}}` is **not** acceptable — always use `source-card`.++## Metrics++> Before hand-building any named aggregation (a rate, ratio, or "X rate"/"average X"), check whether a published **metric** or table **measure** already defines it and reference that instead — see "A named measure is almost always a defined metric, measure, or segment" in the data-sources guidance. Only fall back to the two-stage rate recipe above when discovery finds no matching definition.++A metric is a pre-defined aggregation attached to a base table. To use one:++1. Put the metric's **base table** in `source-table`. Read it from the `base_table_fully_qualified_name` attribute on the `<metric>` tag (combine with `database_name` to form the portable FK). Never invent schema/table names.+2. Reference the metric as `["metric", {}, "<portable_entity_id>"]` in `aggregation`.+3. Filters/breakouts on the same stage use portable FKs on the metric's base table.++```json+{"lib/type": "mbql.stage/mbql",+ "source-table": ["Analytics", "brex_enriched", "fct_cards"],+ "filters": [["!=", {}, ["field", {},+ ["Analytics", "brex_enriched", "fct_cards", "card_status"]], "inactive"]],+ "aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]]}+```++Metrics are aggregations, **not sources** — never put a metric in `source-table` or `source-card`. The `metabase://metric/<id>` URIs are for reading metadata via `read_resource`, not for embedding in queries.++## Using measures and segments++A measure or segment can be referenced two ways. **Prefer the opaque-id clause** — it preserves the measure/segment's identity in the rendered notebook (chip with the official name, click-through to the definition, lineage tooling sees the dependency, definition updates propagate).++### Preferred — opaque-id clause++Each `<measure>` and `<segment>` block on a `<table>` carries a `portable_entity_id="…"` attribute (a 21-char NanoID). Copy it verbatim:++```json+"aggregation": [["measure", {}, "<portable_entity_id>"]]+"filters": [["segment", {}, "<portable_entity_id>"]]+```++The stage's `source-table` must be the table the measure/segment belongs to (the same `<table>` block where you saw the `<measure>` / `<segment>` element).++### Fallback — inline the `<definition>` body++When you need to **compose on top of** a measure or segment (add an extra filter the segment doesn't include, breakout an aggregation the measure doesn't have, …), copy the JSON array inside `<definition>` directly into your stage's `aggregation: [...]` (measure) or `filters: [...]` (segment) and add your own clauses alongside. The definition is in the same portable form the tool expects.++### Don't++- Never invent a `portable_entity_id` — only use the value reported in a tool response.+- The matching aggregation-only opaque-id clause is `["metric", {}, "<portable_entity_id>"]` (for metrics, which live independently of a table — see Metrics above).diff --git a/resources/metabot/skills/construct-notebook-query-core.md b/resources/metabot/skills/construct-notebook-query-core.mdnew file mode 100644index 00000000000..a21e040c17c--- /dev/null+++ b/resources/metabot/skills/construct-notebook-query-core.md@@ -0,0 +1,125 @@+---+id: construct-notebook-query-core+title: Construct notebook query — core+description: Building or editing a notebook (MBQL) query with construct_notebook_query — load before your first query so you get the clause shape, field references, and the rules/anti-patterns right.+tools: [construct_notebook_query]+priority: 60+---+# Construct Query Reference — Core++Construct a Metabase MBQL 5 query as a JSON object describing the query shape. Metabase validates, repairs, and resolves it.++> Advanced topics — joins, implicit joins, multi-stage queries, `source-card`, metrics, measures/segments, expressions, and aggregation references — are in the **construct-notebook-query-advanced** skill. The full operator/function catalogs are in **construct-notebook-query-operators**. Load those skills when you need them.++Return:+- `query`: a JSON **object** (never a quoted string). The target database is inferred from the first stage's `source-table` (or `source-card`) — use the **exact** database name reported by `entity_details` / metadata tools.+- `visualization`: optional `{"chart_type": "bar"}` (sibling of `query`, never embedded inside it).++## Minimal example — count of orders by month++```json+{"lib/type": "mbql/query",+ "stages": [{"lib/type": "mbql.stage/mbql",+ "source-table": ["Sample Database", "PUBLIC", "ORDERS"],+ "aggregation": [["count", {}]],+ "breakout": [["field", {"temporal-unit": "month"},+ ["Sample Database", "PUBLIC", "ORDERS", "CREATED_AT"]]]}]}+```++Every clause is `["op", {}, ...args]` with a mandatory `{}` options map at position 1; every field reference uses a 4-segment portable FK in the last slot. These are the two most-violated rules.++## Universal clause shape++Every operation is `["<operator>", {options}, ...args]`. The options map is **always present**, even when empty.++- Good: `["count", {}]`, `["field", {}, ["DB", "SCH", "TBL", "COL"]]`, `["sum", {}, <expr>]`+- Bad: `["count"]`, `["field", ["DB", "SCH", "TBL", "COL"]]`++The pipeline repairs missing `{}` slots, but write them — your output should match what later inspection will show.++## Top-level query and stage shape++Top level:+- `"lib/type": "mbql/query"` — required marker.+- `"stages": [...]` — at least one stage.++Stage (`"lib/type": "mbql.stage/mbql"` — required marker):+- `source-table` **or** `source-card` — exactly one, **first stage only**. Later stages take the previous stage's output implicitly.+- Optional: `filters`, `aggregation`, `breakout`, `expressions`, `fields`, `joins`, `order-by`, `limit`, `page`.++There is no top-level `database:` field in the LLM contract — the database is derived from the source.++## Field references++```json+["field", {}, ["<db-name>", "<schema-or-null>", "<table-name>", "<field-name>"]]+```++The third slot is the **portable field FK** — a 4+ element string array. Schemaless databases (MongoDB, etc.) use `null` in the schema slot: `["Mongo", null, "orders", "created_at"]`. JSON-unfolded fields append extra segments: `["DB", "SCH", "TBL", "PARENT", "CHILD"]`.++Inside later stages, refer to a column produced by the previous stage by **string name** instead of a portable FK: `["field", {}, "count"]`, `["field", {}, "PRODUCT_ID"]`.++Field options (all optional):+- `temporal-unit` — bucket a date/time field, e.g. `"month"`, `"day"`, `"hour"`. Full list in the **construct-notebook-query-operators** skill.+- `join-alias` — required on every field reference that lives inside an explicit join.+- `source-field` — portable FK of the FK column on the source table; only needed when the implicit-join auto-fill is ambiguous.+- `source-field-name` — name of the FK column when it comes from a previous stage's output (rare; not auto-filled).+- `source-field-join-alias` — explicit-join alias the FK column belongs to (usually auto-filled).+- `binning` — bucket a numeric field.++`base-type` is auto-filled on cross-stage refs — don't write it.++## Per-clause examples++Filter (comparison + boolean combination):++```json+"filters": [["and", {},+ [">", {}, ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "TOTAL"]], 100],+ ["=", {}, ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "STATUS"]], "paid"]]]+```++Aggregation (on a field, plus `count`):++```json+"aggregation": [["sum", {}, ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "TOTAL"]]],+ ["count", {}]]+```++Breakout with temporal bucket:++```json+"breakout": [["field", {"temporal-unit": "month"},+ ["Sample Database", "PUBLIC", "ORDERS", "CREATED_AT"]]]+```++Order by — direction wraps a ref; works on field refs or aggregation refs:++```json+"order-by": [["desc", {}, ["field", {}, ["Sample Database", "PUBLIC", "ORDERS", "CREATED_AT"]]],+ ["desc", {}, ["aggregation", {}, 0]]]+```++`"limit": 50` and `"fields": [<field-ref>, ...]` are the obvious scalar / list forms.++## Rules and common mistakes++Shape rules:+- **Always include `{}` options in every clause**, even when empty. `["count"]` is wrong — it must be `["count", {}]`.+- **The query is a JSON object**, not a string. Send it directly as the `"query"` field of the call.+- **Use the exact database name** reported by `entity_details` (e.g. `"Sample Database"`, not `"Sample"`) as the first element of every portable FK. Near-misses surface `Unknown database` instead of silently picking one. Cross-database queries are not supported.+- **Use portable FKs**, not numeric IDs. Schemaless databases use `null` in the schema slot. JSON-unfolded fields append path segments.+- **Clause heads are lowercase, hyphenated**: `"count"`, `"sum-where"`, `"time-interval"`, `"get-day-of-week"`. Not underscores, not camelCase.+- **Never invent a `source-card` entity_id.** It must be a 21-char string copied verbatim from `entity_details` / search — no patterns, no numeric ids, no `card__<id>`.+- **`source-card` columns are referenced by output name** (string in slot 3), not portable FK.++Anti-hallucination:+- **Don't subtract dates** with `-`. Use `["datetime-diff", {}, <left>, <right>, "<unit>"]` for the integer count of units between two temporal values.+- **For multi-value categorical filters, use `in` / `not-in`**, not `=` with a list literal. The tool rewrites the list form, but write canonical: `["in", {}, <field>, "a", "b"]`.+- **Extracted quarter values are numbers `1, 2, 3, 4`**, never strings like `"Q1"`.+- **Don't breakout on the same underlying field twice** in one stage. If you breakout by `{"temporal-unit": "month"}`, do not also breakout by the raw field.+- **`visualization` is a sibling of `query`**, never embedded inside it.+- **Ordering by an inline aggregation must match an `aggregation:` entry exactly** (same op, same args). If unsure, use `["aggregation", {}, <0-based-idx>]`.+- **Never write `metabase://...` URIs as `source-table` or `source-card` values.** Those URIs are for `read_resource`, not for query sources.+- **Never write `[aggregate, ...]`, `[filter, ...]`, `[order-by, ...]`, `[breakout, ...]`, `[limit, ...]` as clause heads** — those are stage *container keys*, not clauses. Place inner clauses directly inside the stage's `aggregation:` / `filters:` / etc. arrays.+- Common typos (`count-if`, `variance`, `stddev-pop`, `count-distinct`, `dayofweek`, `hour-of-day`, `month-of-year`, `quarter-of-year`, `temporal-diff`, `relative-date`) are auto-corrected, but write the canonical name (`count-where`, `var`, `stddev`, `distinct`, `get-day-of-week`, `get-hour`, `get-month`, `get-quarter`, `datetime-diff`, `relative-datetime`) so the tool output matches what later inspection will show.diff --git a/resources/metabot/skills/construct-notebook-query-operators.md b/resources/metabot/skills/construct-notebook-query-operators.mdnew file mode 100644index 00000000000..9baf3e17573--- /dev/null+++ b/resources/metabot/skills/construct-notebook-query-operators.md@@ -0,0 +1,122 @@+---+id: construct-notebook-query-operators+title: Construct notebook query — operator catalogs+description: The full catalog of aggregation, filter, expression, and temporal-unit operators for construct_notebook_query — load when you need the exact name/arity of a specific operator or the list of temporal units.+tools: [construct_notebook_query]+priority: 40+---+# Construct Query Reference — Operator catalogs++> Source of truth: `src/metabase/lib/schema/{aggregation,filter,temporal_bucketing}.cljc` and `src/metabase/lib/schema/expression/*.cljc`. If something seems missing here, attempt it — the schema may have grown.++These catalogs accompany `construct_notebook_query`. The clause shape and field references are in the **construct-notebook-query-core** skill.++## Aggregations++- `["count", {}]` — count all rows. Optional 3rd slot `<expr>` counts non-NULL.+- `["cum-count", {}]` — cumulative count. Optional 3rd slot `<expr>`.+- `["sum", {}, <num-expr>]`+- `["cum-sum", {}, <num-expr>]`+- `["avg", {}, <num-expr>]`+- `["min", {}, <orderable>]`+- `["max", {}, <orderable>]`+- `["median", {}, <num-expr>]`+- `["percentile", {}, <num-expr>, <0..1>]`+- `["distinct", {}, <expr>]` — count of distinct non-NULL values.+- `["distinct-where", {}, <expr>, <bool-pred>]`+- `["count-where", {}, <bool-pred>]`+- `["sum-where", {}, <num-expr>, <bool-pred>]`+- `["share", {}, <bool-pred>]` — fraction of rows where pred is true.+- `["stddev", {}, <num-expr>]`+- `["var", {}, <num-expr>]`+- `["metric", {}, "<portable_entity_id>"]` — reference a defined metric. The metric's base table must be the stage's `source-table`.+- `["measure", {}, "<portable_entity_id>"]` — reference a defined measure (preferred over inlining its definition). The measure's table must be the stage's `source-table`.++## Order-by direction++- `["asc", {}, <ref>]` / `["desc", {}, <ref>]` — wrap any field ref or aggregation ref.++## Filters++Boolean:+- `["and", {}, <pred>, <pred>, ...]` — min 2 args.+- `["or", {}, <pred>, <pred>, ...]` — min 2 args.+- `["not", {}, <pred>]`++Equality (variadic, ≥2 args):+- `["=", {}, <a>, <b>, ...]`+- `["!=", {}, <a>, <b>, ...]`+- `["in", {}, <expr>, <v1>, <v2>, ...]`+- `["not-in", {}, <expr>, <v1>, <v2>, ...]`++Comparison:+- `["<", {}, <a>, <b>]` / `["<=", {}, <a>, <b>]` / `[">", {}, <a>, <b>]` / `[">=", {}, <a>, <b>]`+- `["between", {}, <expr>, <min>, <max>]`+- `["inside", {}, <lat-expr>, <lon-expr>, <lat-max>, <lon-min>, <lat-min>, <lon-max>]` — lat/lon bounding box.++Nullness / emptiness:+- `["is-null", {}, <expr>]` / `["not-null", {}, <expr>]`+- `["is-empty", {}, <expr>]` / `["not-empty", {}, <expr>]` — equivalent to is-null OR `= ""` for strings.++String (accept `{"case-sensitive": false}` in opts):+- `["starts-with", {}, <str>, <prefix>]`+- `["ends-with", {}, <str>, <suffix>]`+- `["contains", {}, <str>, <substring>]`+- `["does-not-contain", {}, <str>, <substring>]`++Temporal:+- `["time-interval", {}, <temporal>, <n-or-:current/:last/:next>, "<unit>"]` — relative window. Opts may set `{"include-current": true}`.+- `["during", {}, <temporal>, "<iso-date-or-datetime>", "<unit>"]` — value falls within the bucket containing the literal.+- `["relative-time-interval", {}, <temporal>, <value>, "<bucket>", <offset-value>, "<offset-bucket>"]` — window offset from now.++Named reference:+- `["segment", {}, "<portable_entity_id>"]` — reference a defined segment (preferred over inlining its definition). The segment's table must be the stage's `source-table`.++## Expressions++Arithmetic:+- `["+", {}, <a>, <b>, ...]` / `["-", {}, <a>, <b>, ...]` / `["*", {}, <a>, <b>, ...]` / `["/", {}, <a>, <b>, ...]`+- `["abs", {}, <num>]` / `["power", {}, <num>, <exp>]` / `["sqrt", {}, <num>]`+- `["exp", {}, <num>]` / `["log", {}, <num>]`+- `["ceil", {}, <num>]` / `["floor", {}, <num>]` / `["round", {}, <num>]`+- `["integer", {}, <num-or-str>]` / `["float", {}, <num-or-str>]`++String:+- `["concat", {}, <a>, <b>, ...]`+- `["substring", {}, <str>, <start>, <length>]` — 1-based start; length is optional.+- `["replace", {}, <str>, <old>, <new>]`+- `["regex-match-first", {}, <str>, <regex>]`+- `["split-part", {}, <str>, <sep>, <n>]`+- `["length", {}, <str>]`+- `["trim", {}, <str>]` / `["ltrim", {}, <str>]` / `["rtrim", {}, <str>]`+- `["upper", {}, <str>]` / `["lower", {}, <str>]`+- `["host", {}, <url>]` / `["domain", {}, <url>]` / `["subdomain", {}, <url>]` / `["path", {}, <url>]`+- `["month-name", {}, <int>]` / `["quarter-name", {}, <int>]` / `["day-name", {}, <int>]`+- `["text", {}, <expr>]` / `["collate", {}, <str>, <collation>]`++Conditional:+- `["case", {}, [[<pred1>, <expr1>], [<pred2>, <expr2>], ...], <default?>]` — alias: `if`.+- `["coalesce", {}, <a>, <b>, ...]`++Temporal:+- `["datetime-add", {}, <temporal>, <n>, "<unit>"]`+- `["datetime-subtract", {}, <temporal>, <n>, "<unit>"]`+- `["datetime-diff", {}, <left>, <right>, "<unit>"]` — `<unit>` is one of `second, minute, hour, day, week, month, quarter, year`.+- `["interval", {}, <n>, "<unit>"]`+- `["get-year", {}, <temporal>]` / `["get-month", {}, <temporal>]` / `["get-day", {}, <temporal>]` / `["get-quarter", {}, <temporal>]`+- `["get-hour", {}, <temporal>]` / `["get-minute", {}, <temporal>]` / `["get-second", {}, <temporal>]`+- `["get-week", {}, <temporal>]` / `["get-day-of-week", {}, <temporal>]` — both accept optional 4th-slot mode `"iso"`, `"us"`, `"instance"`.+- `["temporal-extract", {}, <temporal>, "<unit>"]` — extract one of the date/time extraction units listed below.+- `["convert-timezone", {}, <temporal>, "<target-tz>"]` — optional 4th slot is source tz.+- `["relative-datetime", {}, <n>, "<unit>"]` (or `["relative-datetime", {}, "current"]`)+- `["absolute-datetime", {}, "<iso-string>", "<unit?>"]`+- `["date", {}, <expr>]` / `["datetime", {}, <expr>]` / `["time", {}, <expr>]`+- `["now", {}]` / `["today", {}]`++## Temporal units (for `{"temporal-unit": ...}` on field refs and as `<unit>` args)++- Date truncation: `day`, `week`, `month`, `quarter`, `year`+- Date extraction (integer-returning): `day-of-week`, `day-of-month`, `day-of-year`, `week-of-year`, `month-of-year`, `quarter-of-year`, `year`, `year-of-era`+- Time truncation: `millisecond`, `second`, `minute`, `hour`+- Time extraction (integer-returning): `second-of-minute`, `minute-of-hour`, `hour-of-day`+- Plus `default` — let the system pick based on the field's base type.diff --git a/resources/metabot/prompts/tools/create_sql_query.md b/resources/metabot/skills/create-sql-query.mdsimilarity index 85%rename from resources/metabot/prompts/tools/create_sql_query.mdrename to resources/metabot/skills/create-sql-query.mdindex 0d86f3d6d05..06364de4228 100644--- a/resources/metabot/prompts/tools/create_sql_query.md+++ b/resources/metabot/skills/create-sql-query.md@@ -1,3 +1,10 @@+---+id: create-sql-query+title: Creating SQL queries+description: Creating a new SQL query with create_sql_query — load before writing SQL for the read-only contract, model reference syntax ({{#model_id}}), and identifier quoting.+tools: [create_sql_query]+priority: 50+---**When to use:**- User asks for SQL queries but isn't editing an existing one- You want to create SQL using models ({{#model_id}} syntax) or tables@@ -33,7 +40,7 @@**For transformations**, use CTEs:```sqlWITH step1 AS (- SELECT * FROM {{ '{{' }}#model_id{{ '}}' }} AS name_alias+ SELECT * FROM {{#model_id}} AS name_alias),step2 AS (SELECT ... FROM step1diff --git a/resources/metabot/prompts/tools/edit_chart.md b/resources/metabot/skills/edit-chart.mdsimilarity index 80%rename from resources/metabot/prompts/tools/edit_chart.mdrename to resources/metabot/skills/edit-chart.mdindex 07c84c22ec4..95f7fe76358 100644--- a/resources/metabot/prompts/tools/edit_chart.md+++ b/resources/metabot/skills/edit-chart.md@@ -1,3 +1,10 @@+---+id: edit-chart+title: Editing chart settings+description: Changing the chart type of an existing visualization with edit_chart (e.g. bar to line) — load when the user wants to switch chart type for a chart already in context.+tools: [edit_chart]+priority: 50+---Edit the chart settings of an existing chart.This tool changes the chart type (e.g., bar chart to line chart, table to pie chart) but does not modify the underlying data or SQL query.It will return a new chart with the updated settings.@@ -19,4 +26,4 @@ It will return a new chart with the updated settings.- Only changes the chart type, not detailed display settings- Cannot modify chart titles, colors, axis formatting, or styling- Does not modify data or perform calculations-- Limited to basic chart type conversions\ No newline at end of file+- Limited to basic chart type conversionsdiff --git a/resources/metabot/prompts/tools/edit_sql_query.md b/resources/metabot/skills/edit-sql-query.mdsimilarity index 68%rename from resources/metabot/prompts/tools/edit_sql_query.mdrename to resources/metabot/skills/edit-sql-query.mdindex 1a9c6bb29a7..093dfcd6861 100644--- a/resources/metabot/prompts/tools/edit_sql_query.md+++ b/resources/metabot/skills/edit-sql-query.md@@ -1,3 +1,10 @@+---+id: edit-sql-query+title: Editing SQL queries (targeted)+description: Making small, targeted string-replacement edits to an existing SQL query with edit_sql_query — load when changing a query already in context (use replace-sql-query for major rewrites).+tools: [edit_sql_query]+priority: 50+---Edit an existing SQL query by applying targeted string replacements. This updates the query text shown to the user; it does **not** execute the query.**Safety:**@@ -11,4 +18,4 @@ Edit an existing SQL query by applying targeted string replacements. This update**When to use:** small, targeted changes to a SQL query that is already in the conversation context (use `replace_sql_query` for major rewrites). Never execute SQL or act outside the current query.-SELECT-only — never emit DDL/DML. Quote identifiers containing spaces or reserved words in double quotes (e.g. `"order"`). Use the target database's SQL dialect. See `create_sql_query` for the full SQL contract (read-only rules, model reference syntax, fully-qualified table names).+SELECT-only — never emit DDL/DML. Quote identifiers containing spaces or reserved words in double quotes (e.g. `"order"`). Use the target database's SQL dialect. See the `create-sql-query` skill for the full SQL contract (read-only rules, model reference syntax, fully-qualified table names).diff --git a/resources/metabot/prompts/tools/read_resource.md b/resources/metabot/skills/read-resource.mdsimilarity index 96%rename from resources/metabot/prompts/tools/read_resource.mdrename to resources/metabot/skills/read-resource.mdindex 701421405db..4a471e18469 100644--- a/resources/metabot/prompts/tools/read_resource.md+++ b/resources/metabot/skills/read-resource.md@@ -1,3 +1,10 @@+---+id: read-resource+title: Reading resources by URI+description: Navigating the Metabase instance with read_resource — load to learn the URI patterns (databases, collections, tables, models, questions, metrics, transforms, dashboards) and when to drill vs. search.+tools: [read_resource]+priority: 50+---When using the read_resource tool, you have access to a unified interface for navigating the Metabase instance and retrieving data about its resources via URI patterns.The URI pattern determines what is returned — from top-level lists (databases, collections) to a single entity, to its sub-resources (fields, items, sources, derived items).diff --git a/resources/metabot/prompts/tools/replace_sql_query.md b/resources/metabot/skills/replace-sql-query.mdsimilarity index 55%rename from resources/metabot/prompts/tools/replace_sql_query.mdrename to resources/metabot/skills/replace-sql-query.mdindex 81e11bb0ae5..4145f5eb5e2 100644--- a/resources/metabot/prompts/tools/replace_sql_query.md+++ b/resources/metabot/skills/replace-sql-query.md@@ -1,5 +1,12 @@+---+id: replace-sql-query+title: Replacing SQL queries (full rewrite)+description: Replacing the entire body of an existing SQL query with replace_sql_query — load for major rewrites or structural changes (use edit-sql-query for small targeted edits).+tools: [replace_sql_query]+priority: 50+---Replace the entire content of an existing SQL query with new SQL. Use for major rewrites or structural changes — more token-efficient than many `edit_sql_query` calls. This updates the query text shown to the user; it does **not** execute the query.**When to use:** large changes to a SQL query that is already in the conversation context (use `edit_sql_query` for small targeted edits). Never execute SQL or act outside the current query.-SELECT-only — never emit DDL/DML. Quote identifiers containing spaces or reserved words in double quotes (e.g. `"order"`). Use the target database's SQL dialect. See `create_sql_query` for the full SQL contract (read-only rules, model reference syntax, fully-qualified table names).+SELECT-only — never emit DDL/DML. Quote identifiers containing spaces or reserved words in double quotes (e.g. `"order"`). Use the target database's SQL dialect. See the `create-sql-query` skill for the full SQL contract (read-only rules, model reference syntax, fully-qualified table names).diff --git a/resources/metabot/prompts/tools/write_transform_python.md b/resources/metabot/skills/write-transform-python.mdsimilarity index 91%rename from resources/metabot/prompts/tools/write_transform_python.mdrename to resources/metabot/skills/write-transform-python.mdindex 70ec5c9da01..85bffc8874a 100644--- a/resources/metabot/prompts/tools/write_transform_python.md+++ b/resources/metabot/skills/write-transform-python.md@@ -1,3 +1,10 @@+---+id: write-transform-python+title: Writing Python transforms+description: Creating or editing a Python transform with write_transform_python — load for the edit/replace modes, required source_tables fields when creating, the shared library convention, and safety rules.+tools: [write_transform_python]+priority: 50+---Write new Python code or edit existing code using exact string matching with safety checks for ambiguous edits.It is useful for modifying or fixing Python code based on user requests, e.g. when modifying a Python-based transform.@@ -55,4 +62,4 @@ When creating a new transform, you must provide:**Limitations:*** This tool does not execute Python code, it only modifies the source code text.* Edits must be unambiguous and uniquely identifiable within the code context.-* You can not apply the edits for the user. Never say things like, "Let me know if you'd like me to apply this change".\ No newline at end of file+* You can not apply the edits for the user. Never say things like, "Let me know if you'd like me to apply this change".diff --git a/resources/metabot/prompts/tools/write_transform_sql.md b/resources/metabot/skills/write-transform-sql.mdsimilarity index 90%rename from resources/metabot/prompts/tools/write_transform_sql.mdrename to resources/metabot/skills/write-transform-sql.mdindex f9ac4cabb40..770bb4efb6c 100644--- a/resources/metabot/prompts/tools/write_transform_sql.md+++ b/resources/metabot/skills/write-transform-sql.md@@ -1,3 +1,10 @@+---+id: write-transform-sql+title: Writing SQL transforms+description: Creating or editing a SQL transform with write_transform_sql — load for the edit/replace modes, required fields when creating a transform, and the SQL safety rules.+tools: [write_transform_sql]+priority: 50+---Write new SQL queries or edit existing queries using exact string matching with safety checks for ambiguous edits.It is useful for modifying or fixing SQL queries, adding or changing clauses, or restructuring queries@@ -53,4 +60,4 @@ When creating a new transform, you must provide:* This tool does not execute SQL queries, it only modifies the query text.* Edits must be unambiguous and uniquely identifiable within the query context.* You can only query tables and Metabase models; Metabase metrics are not supported in SQL for now-* You can not apply the edits for the user. Never say things like, "Let me know if you'd like me to apply this change".\ No newline at end of file+* You can not apply the edits for the user. Never say things like, "Let me know if you'd like me to apply this change".diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.cljindex ce9b49039f8..57d56a8e07b 100644--- a/src/metabase/agent_api/api.clj+++ b/src/metabase/agent_api/api.clj@@ -714,6 +714,15 @@;;; ------------------------------------------------- Create Question ------------------------------------------------+(defn- frontend-url+ "Prefix `channel.urls` relative path `path` with the configured site URL, returning it relative when+ site-url is unset so the agent never emits an absolute URL with an empty host."+ [path]+ (let [base (channel.urls/site-url)]+ (if (str/blank? base)+ path+ (str base path))))+(mr/def ::card-display"Display types accepted by Card. Validates LLM-passed values so a bogusvalue (e.g. `\"potato\"`) gets a 400 rather than persisting junk."@@ -785,7 +794,7 @@{:id api/*current-user-id*})]{:id (:id card):name (:name card)- :url (channel.urls/card-url (:id card))+ :url (frontend-url (channel.urls/card-path (:id card))):display (name (:display card)):collection_id (:collection_id card):collection_path (collection-path (:collection_id card))@@ -971,7 +980,7 @@(events/publish-event! :event/dashboard-create {:object dash :user-id api/*current-user-id*}){:id (:id dash):name (:name dash)- :url (channel.urls/dashboard-url (:id dash))+ :url (frontend-url (channel.urls/dashboard-path (:id dash))):collection_id (:collection_id dash):collection_path (collection-path (:collection_id dash)):description (:description dash)diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.cljindex 45f71f21131..15033731199 100644--- a/src/metabase/agent_lib/representations/repair.clj+++ b/src/metabase/agent_lib/representations/repair.clj@@ -166,6 +166,53 @@node))form))+;;; ============================================================+;;; Pass 1.75 -- strip stray double-quotes from portable-FK field references.+;;;+;;; The field metadata shown to the LLM historically rendered column names wrapped in+;;; double quotes (`<field name="\"col\"">`), and LLMs are SQL-trained to quote identifiers,+;;; so the model frequently emits a portable field reference whose column segment carries+;;; literal surrounding quotes:+;;;+;;; ["field" {} ["DB" "SCH" "TBL" "\"col\""]] (portable-FK column segment)+;;;+;;; The resolver rejects `"col"` as `:unknown-field`. A double-quote never legitimately wraps+;;; a portable identifier segment, so we strip a single balanced pair from each string segment+;;; of the **portable-FK vector** target. We only touch a `field` clause's target vector (never+;;; arbitrary strings), so filter literals such as `["=" {} <field> "\"paid\""]` are left+;;; untouched. Cross-stage *string* targets (`["field" {} "\"col\""]`) are deliberately left to+;;; the resolution-aware [[match-cross-stage-column]] pass, which only strips when the result+;;; matches a real previous-stage column.+;;; ============================================================++(defn- dequote-identifier+ "Strip one balanced pair of surrounding ASCII double-quotes from `s`. Idempotent; returns+ non-strings and unquoted strings unchanged."+ [s]+ (if (and (string? s)+ (>= (count s) 2)+ (str/starts-with? s "\"")+ (str/ends-with? s "\""))+ (subs s 1 (dec (count s)))+ s))++(defn- dequote-field-target+ "Dequote each string segment of a `field` clause's portable-FK vector target. Non-vector+ targets (cross-stage column-name strings) are returned unchanged."+ [target]+ (if (vector? target)+ (mapv #(if (string? %) (dequote-identifier %) %) target)+ target))++(defn- dequote-field-targets*+ [form]+ (walk/postwalk+ (fn [node]+ (if (field-clause-shape? node)+ (assoc node 2 (dequote-field-target (nth node 2)))+ node))+ form))+;;; ============================================================;;; Pass 1.81 -- canonicalise common operator-name aliases.;;;@@ -2094,24 +2141,45 @@(second (re-matches #"\"(.*)\"" s)))s))+(defn- normalize-col-key+ "Loose matching key for an LLM-authored cross-stage column name: lowercased, with hyphens and+ whitespace folded to underscores. Lets the natural `count-where` (or `Count Where`) the LLM+ tends to write match the canonical `count_where` that lib emits as an aggregation's output+ column name - so the model doesn't have to memorise the hyphen-vs-underscore output-naming+ rule."+ [s]+ (when (string? s)+ (-> s u/lower-case-en (str/replace #"[-\s]+" "_"))))+(defn- match-cross-stage-column"Find the canonical column entry in `name->types` for `col-name`. Returns `[canonical-nametypes]` or `nil` when no column matches.- Prefers an exact match. Falls back to the double-quote-stripped name, but only when stripping- actually resolves to a real column - so a column whose name legitimately contains surrounding- quotes (vanishingly rare) is never clobbered, and unmatched names are left for the resolver to- report with a better message."+ Tries, in order:+ 1. an exact match;+ 2. the double-quote-stripped name (only when stripping actually resolves);+ 3. a loose match that folds case and hyphens/whitespace to underscores, but **only when+ exactly one** real column matches - so `count-where` resolves to `count_where` while+ genuine ambiguity is left for the resolver to report.++ A column whose name legitimately needs quotes (vanishingly rare) is never clobbered, and+ unmatched names are passed through for the resolver to surface with a better message."[name->types col-name]- (cond- (contains? name->types col-name)- [col-name (get name->types col-name)]+ (let [stripped (strip-surrounding-double-quotes col-name)]+ (cond+ (contains? name->types col-name)+ [col-name (get name->types col-name)]- :else- (let [stripped (strip-surrounding-double-quotes col-name)]- (when (and (not= stripped col-name)- (contains? name->types stripped))- [stripped (get name->types stripped)]))))+ (and (not= stripped col-name) (contains? name->types stripped))+ [stripped (get name->types stripped)]++ :else+ (let [target (normalize-col-key stripped)+ hits (when target+ (filter #(= target (normalize-col-key %)) (keys name->types)))]+ (when (= 1 (count hits))+ (let [canon (first hits)]+ [canon (get name->types canon)]))))))(defn- maybe-fill-cross-stage-types"Given a cross-stage field clause and a name→types map, return the clause with its column name@@ -2440,6 +2508,7 @@ensure-clause-options*unwrap-boolean-wrappers*unwrap-nested-field-clauses*+ dequote-field-targets*rewrite-operator-name-aliases*rewrite-temporal-bucket-aliases*rewrite-direction-aliases*@@ -2466,6 +2535,9 @@1.5. normalise `expressions:` shape - accept map form `{Name: clause, …}` or thecanonical sequential form, always output sequential with `lib/expression-name`stamped into each clause's options from the map key when missing;+ 1.75. strip stray surrounding double-quotes from the string segments of `field` clauses'+ portable-FK vector targets, e.g. `\"col\"` → `col` (cross-stage string targets are left+ to the resolution-aware cross-stage matching in pass 5);1.88. merge a trailing extra options-map back into position-1 options on fixed-aritytuple clauses (e.g. `[\"time-interval\" {} <expr> -1 \"month\" {\"include-current\" true}]`);2. fill in missing `\"lib/type\"` markers on the query and stages;diff --git a/src/metabase/channel/urls.clj b/src/metabase/channel/urls.cljindex c8e9a7dd135..a9458d675f5 100644--- a/src/metabase/channel/urls.clj+++ b/src/metabase/channel/urls.clj@@ -23,12 +23,22 @@[](str (site-url) "/trash"))+(defn dashboard-path+ "Relative frontend path for a `Dashboard` with ID, e.g. \"/dashboard/10\"."+ [^Integer id]+ (format "/dashboard/%d" id))++(defn card-path+ "Relative frontend path for a `Card` with ID, e.g. \"/question/10\"."+ [^Integer id]+ (format "/question/%d" id))+(defn dashboard-url"Return an appropriate URL for a `Dashboard` with ID.(dashboard-url 10) -> \"http://localhost:3000/dashboard/10\""([^Integer id]- (format "%s/dashboard/%d" (site-url) id))+ (str (site-url) (dashboard-path id)))([^Integer id parameters & [tab-id]](let [base-url (dashboard-url id)url-params (cond-> (flatten@@ -49,7 +59,7 @@(card-url 10) -> \"http://localhost:3000/question/10\""[^Integer id]- (format "%s/question/%d" (site-url) id))+ (str (site-url) (card-path id)))(def ^:dynamic *dashcard-parameters*"Bind dashboard parameters for dashcard deeplinked urls"diff --git a/src/metabase/metabot/agent/core.clj b/src/metabase/metabot/agent/core.cljindex 52c5c3a1336..f27c581a397 100644--- a/src/metabase/metabot/agent/core.clj+++ b/src/metabase/metabot/agent/core.clj@@ -609,7 +609,9 @@(let [start-ms (u/start-timer)](binding [*debug-log* (when debug? (atom []))scope/*current-user-scope* scopes- scope/*current-user-metabot-permissions* perms]+ scope/*current-user-metabot-permissions* perms+ scope/*current-user-capabilities* (get-in opts [:context :capabilities] #{})+ scope/*current-loadable-skill-ids* (atom #{})](try(let [agent (init-agent opts){result :resultdiff --git a/src/metabase/metabot/agent/messages.clj b/src/metabase/metabot/agent/messages.cljindex 4d3a8003f3a..314486eb323 100644--- a/src/metabase/metabot/agent/messages.clj+++ b/src/metabase/metabot/agent/messages.clj@@ -9,6 +9,7 @@[metabase.metabot.agent.memory :as memory][metabase.metabot.agent.prompts :as prompts][metabase.metabot.agent.user-context :as user-context]+ [metabase.metabot.skills :as skills][metabase.util.json :as json][metabase.util.log :as log]))@@ -164,10 +165,16 @@steps (memory/get-steps memory)input-parts (mapcat input-message->parts input-messages)step-parts (mapcat step->parts steps)- result (vec (concat input-parts step-parts))]+ ;; Preload the active SQL dialect (if any) as a synthetic load_skill+ ;; tool-call/result pair. It is placed after the input messages (so the+ ;; first message is still the user's) and before this turn's steps, which+ ;; keeps it below the system cache breakpoint.+ preload-parts (skills/dialect-preload-parts (user-context/extract-sql-dialect context))+ result (vec (concat input-parts preload-parts step-parts))](log/info "Building message history"{:input-message-count (count input-messages):step-count (count steps)+ :preload-parts (count preload-parts):total-parts (count result)})result))@@ -186,6 +193,7 @@Returns message map with {:role \"system\" :content \"...\"}."[context profile tools](let [enriched-context (user-context/enrich-context-for-template context)- content (prompts/build-system-message-content profile enriched-context tools)]+ content (prompts/build-system-message-content+ profile enriched-context tools (:capabilities context))]{:role "system":content content}))diff --git a/src/metabase/metabot/agent/profiles.clj b/src/metabase/metabot/agent/profiles.cljindex 181071d854e..276a345eaec 100644--- a/src/metabase/metabot/agent/profiles.clj+++ b/src/metabase/metabot/agent/profiles.clj@@ -7,13 +7,13 @@`defenterprise` tools with `:ee-feature` metadata are filtered out at runtimewhen the feature is not available."(:require- [clojure.string :as str][malli.error :as me][metabase.api-scope.core :as api-scope]+ [metabase.metabot.capabilities :as capabilities][metabase.metabot.scope :as scope][metabase.metabot.settings :as metabot.settings]+ [metabase.metabot.skills :as skills][metabase.metabot.tools :as tools]- [metabase.premium-features.core :as premium-features][metabase.util.malli :as mu][metabase.util.malli.registry :as mr]))@@ -170,36 +170,6 @@#'tools/create-alert-tool#'tools/slackbot-create-dashboard-subscription-tool]})-(def ^:private api-string->capability-keyword- "Map from API capability strings (as sent by the frontend) to the keywords- used in tool :capabilities metadata. Keywords pass through unchanged."- {"frontend:navigate_user_v1" :frontend-navigate-user-v1- "permission:save_questions" :permission-save-questions- "permission:write_sql_queries" :permission-write-sql-queries- "permission:write_transforms" :permission-write-transforms})--(defn- capability->keyword- "Normalize a capability value to a keyword. Strings are looked up in the- api-string->capability-keyword map; keywords are returned as-is."- [cap]- (if (keyword? cap)- cap- (or (api-string->capability-keyword cap)- ;; Fallback: keywordize unknown strings so new capabilities degrade- ;; gracefully without requiring a map update.- (keyword (-> (str cap) (str/replace ":" "-") (str/replace "_" "-"))))))--(defn feature-capabilities- "Return set of capabilities inferred from BE state, not send from FE. Generated by function to avoid staleness."- []- (into #{}- (remove nil?)- [(when (or (not (premium-features/is-hosted?))- (premium-features/has-feature? :transforms-basic))- :feature-transforms)- (when (premium-features/has-feature? :transforms-python)- :feature-transforms-python)]))-(defn- filter-by-capabilities"Filter tool vars by user capabilities.Removes tools that require capabilities the user doesn't have.@@ -207,9 +177,7 @@while tool metadata uses keywords (e.g. :frontend-navigate-user-v1), so wenormalize to keywords before comparing."[tool-vars capabilities]- (let [capabilities-set (into (feature-capabilities)- (map capability->keyword)- capabilities)]+ (let [capabilities-set (capabilities/capability-set capabilities)](filter (fn [tool-var](every? capabilities-set (:capabilities (meta tool-var))))tool-vars)))@@ -244,10 +212,17 @@"Get tool registry filtered by profile configuration, user capabilities, and scope.Filters out EE-only tools when the feature is not available, then filters bycapabilities, then filters by `*current-user-scope*`. Returns a map of- tool-name -> tool-var."+ tool-name -> tool-var.++ When the resolved profile exposes at least one skill in its catalog, the+ `load_skill` tool is injected so the agent can pull skill bodies on demand."[profile-id capabilities]- (some-> (get-profile profile-id)- :tools- (filter-by-capabilities capabilities)- filter-by-scope- tool-map))+ (when-let [profile (get-profile profile-id)]+ (let [base (-> profile+ :tools+ (filter-by-capabilities capabilities)+ filter-by-scope+ tool-map)]+ (cond-> base+ (seq (:catalog (skills/build-skill-manifest profile (keys base) capabilities)))+ (assoc "load_skill" #'tools/load-skill-tool)))))diff --git a/src/metabase/metabot/agent/prompts.clj b/src/metabase/metabot/agent/prompts.cljindex 9659e01892b..c1712b88a26 100644--- a/src/metabase/metabot/agent/prompts.clj+++ b/src/metabase/metabot/agent/prompts.clj@@ -3,19 +3,30 @@Handles:- System prompt templates from resources/metabot/prompts/system/- - SQL dialect instructions from resources/metabot/prompts/dialects/- - Tool-specific prompts from resources/metabot/prompts/tools/- Template rendering with context variables- - Template caching for performance"+ - Template caching for performance++ SQL dialect bodies are owned by `metabase.metabot.skills` (loaded as on-demand skills), not+ here."(:require[clojure.java.io :as io][metabase.metabot.scope :as scope][metabase.metabot.settings :as metabot.settings]+ [metabase.metabot.skills :as skills][metabase.util.log :as log][selmer.parser :as selmer]))(set! *warn-on-reflection* true)+;; Kept local rather than required from metabase.metabot.tools to avoid a prompts->tools cycle;+;; mirrors the SQL entries in metabase.metabot.tools/query-generation-tool-names.+(def ^:private sql-generation-tool-names+ "SQL-writing tools.+ Their presence in the capability-filtered tool set — not the `:permission/metabot-sql-generation`+ permission alone — is what lets the model write SQL, since they're gated by the+ `permission:write_sql_queries` capability."+ #{"create_sql_query" "edit_sql_query" "replace_sql_query"})+;;; Template Loading(defn- load-resource@@ -35,30 +46,6 @@(log/warn "System prompt template not found:" path)nil))))-(defn load-dialect-instructions- "Load SQL dialect instructions from resources/metabot/prompts/dialects/.-- Example: (load-dialect-instructions \"postgresql\")- Returns nil if dialect not found."- [dialect-name]- (when dialect-name- (let [path (str "metabot/prompts/dialects/" dialect-name ".md")]- (or (load-resource path)- (do- (log/debug "Dialect instructions not found:" path)- nil)))))--(defn load-tool-prompt-template- "Load a tool-specific prompt template from resources/metabot/prompts/tools/.-- Example: (load-tool-prompt-template \"query-datasource/system.selmer\")"- [template-path]- (let [path (str "metabot/prompts/tools/" template-path)]- (or (load-resource path)- (do- (log/debug "Tool prompt template not found:" path)- nil))))-(defn load-llm-shape-template"Load the LLM-shape (output-side XML) template from resources/metabot/prompts/."[template-name]@@ -94,17 +81,6 @@;; Return template as-is on errortemplate)))-(defn render-tool-prompt- "Render a tool-specific prompt template with context variables.-- Similar to render-system-prompt but for tool-level prompts."- [template context]- (try- (selmer/render template context)- (catch Exception e- (log/error e "Error rendering tool prompt template")- template)))-;;; Template Caching(def ^:private template-cache@@ -137,19 +113,6 @@[template-name](:template (cached-load-template "system" template-name load-system-prompt-template)))-(defn get-cached-dialect-instructions- "Get dialect instructions from cache or load them.- Returns instructions string or nil."- [dialect-name]- (when dialect-name- (:template (cached-load-template "dialect" dialect-name load-dialect-instructions))))--(defn get-cached-tool-prompt- "Get tool prompt template from cache or load it.- Returns template string or nil."- [template-path]- (:template (cached-load-template "tool" template-path load-tool-prompt-template)))-(defn get-cached-llm-shape-template"Get the LLM-shape (output-side XML) template from cache or load it."[]@@ -169,30 +132,6 @@[](reset! template-cache {}))-;;; Tool Instructions Extraction--(defn extract-tool-instructions- "Extract system instructions from tool definitions by loading prompt files.-- For each tool, loads a markdown prompt file from `resources/metabot/prompts/tools/`.- The filename is determined by:- 1. `:prompt` key in the tool definition map (if present), or- 2. `\"<tool-name>.md\"` as default.-- Only tools with a corresponding prompt resource file are included.-- Returns vector of maps: [{:tool_name \"search\" :instructions \"...\"}]"- [tools]- (vec- (for [[tool-name tool-def] tools- :let [fname (or (:prompt tool-def)- (str tool-name ".md"))- prompt (some-> (io/resource (str "metabot/prompts/tools/" fname))- slurp)]- :when prompt]- {:tool_name tool-name- :instructions prompt})))-;;; High-Level API(defn build-system-message-content@@ -201,18 +140,23 @@Parameters:- profile: Profile map with :prompt-template key- context: Agent context map with user info, viewing context, etc.- - tools: Tool registry map+ - tools: Tool registry map (name -> tool def/var)+ - capabilities: Sequence of capability strings/keywords for the request, used to+ gate which skills appear in the manifest.++ Tool-specific instructions are no longer embedded in the prompt; instead a+ skills manifest (one line per available skill) is rendered, and bodies are+ loaded on demand via the `load_skill` tool. SQL dialect instructions are+ preloaded into the message stream (see `metabase.metabot.skills`), not here.Returns rendered system message string."- [{:keys [prompt-template]} context tools]+ [{:keys [prompt-template] :as profile} context tools capabilities](let [template-name (or prompt-template "internal.selmer")template (get-cached-system-prompt template-name)](if template(let [sql-dialect (or (get context :sql_dialect)(get context :sql-dialect))- dialect-instructions (when sql-dialect- (get-cached-dialect-instructions sql-dialect))- tool-instructions (extract-tool-instructions tools)+ {:keys [always-on catalog]} (skills/build-skill-manifest profile (keys tools) capabilities)current-user-info (or (get context :current_user_info)(get context :current-user-info))current-time (or (get context :current_time)@@ -225,15 +169,20 @@(get context :recent-views))perms (or scope/*current-user-metabot-permissions*scope/perm-type-defaults)- has-sql? (= :yes (:permission/metabot-sql-generation perms))+ ;; The SQL guidance tells the model to load SQL skills and use the SQL tools, so gate it+ ;; on those tools actually being active — the permission can be `:yes` while the request+ ;; lacks the `permission:write_sql_queries` capability that registers them.+ has-sql? (and (= :yes (:permission/metabot-sql-generation perms))+ (boolean (some sql-generation-tool-names (keys tools))))has-nlq? (= :yes (:permission/metabot-nlq perms))template-context {:metabot_name (metabot.settings/metabot-name):current_time current-time:current_user_info current-user-info:first_day_of_week first-day-of-week:sql_dialect sql-dialect- :sql_dialect_instructions dialect-instructions- :tool_instructions tool-instructions+ :sql_dialect_loaded (some? (skills/dialect-skill sql-dialect))+ :skill_catalog catalog+ :skill_always_on (mapv :body always-on):viewing_context viewing-context:recent_views recent-views:has_sql_generation has-sql?@@ -273,11 +222,5 @@(render-system-prompt template {:current-time "2024-01-15 14:30:00":sql-dialect "postgresql"})- ;; Load dialect instructions- (load-dialect-instructions "postgresql")-;; Clear cache during development- (clear-cache!)-- ;; Extract tool instructions- (extract-tool-instructions {"search" #'some-tool-var}))+ (clear-cache!))diff --git a/src/metabase/metabot/capabilities.clj b/src/metabase/metabot/capabilities.cljnew file mode 100644index 00000000000..95a3f75b7da--- /dev/null+++ b/src/metabase/metabot/capabilities.clj@@ -0,0 +1,50 @@+(ns metabase.metabot.capabilities+ "Capability normalization shared by profiles and skills.++ Capabilities arrive from the API as strings (e.g. \"frontend:navigate_user_v1\") while tool/skill+ metadata uses keywords (e.g. :frontend-navigate-user-v1).+ Some capabilities are inferred from backend state rather than sent by the frontend."+ (:require+ [clojure.string :as str]+ [metabase.premium-features.core :as premium-features]))++(set! *warn-on-reflection* true)++(def ^:private api-string->capability-keyword+ "Map from API capability strings (as sent by the frontend) to the keywords used in tool/skill+ `:capabilities` metadata."+ {"frontend:navigate_user_v1" :frontend-navigate-user-v1+ "permission:save_questions" :permission-save-questions+ "permission:write_sql_queries" :permission-write-sql-queries+ "permission:write_transforms" :permission-write-transforms})++(defn- capability->keyword+ "Normalize a capability value to a keyword.+ Strings are looked up in the api-string->capability-keyword map; keywords are returned as-is."+ [cap]+ (if (keyword? cap)+ cap+ (or (api-string->capability-keyword cap)+ ;; Fallback: keywordize unknown strings so new capabilities degrade+ ;; gracefully without requiring a map update.+ (keyword (-> (str cap) (str/replace ":" "-") (str/replace "_" "-"))))))++(defn- feature-capabilities+ "Return the set of capabilities inferred from BE state rather than sent from the FE.+ Generated by function to avoid staleness."+ []+ (into #{}+ (remove nil?)+ [(when (or (not (premium-features/is-hosted?))+ (premium-features/has-feature? :transforms-basic))+ :feature-transforms)+ (when (premium-features/has-feature? :transforms-python)+ :feature-transforms-python)]))++(defn capability-set+ "Build the full set of capability keywords for a request: the backend-inferred feature capabilities+ unioned with the (normalized) capabilities from the API."+ [capabilities]+ (into (feature-capabilities)+ (map capability->keyword)+ capabilities))diff --git a/src/metabase/metabot/scope.clj b/src/metabase/metabot/scope.cljindex cacf38cddeb..c20703a7d92 100644--- a/src/metabase/metabot/scope.clj+++ b/src/metabase/metabot/scope.clj@@ -147,6 +147,18 @@consumers should fall back to `perm-type-defaults`."nil)+(def ^:dynamic *current-user-capabilities*+ "The request's capabilities (strings/keywords as sent by the API). Bound in the request path+ alongside `*current-user-scope*` so capability-gated checks (e.g. which skills are loadable)+ match the manifest, which is built from the same capabilities. Defaults to `#{}`."+ #{})++(def ^:dynamic *current-loadable-skill-ids*+ "Request-scoped atom containing the set of skill ids that appeared in the current+ profile's skill manifest. When bound, `load_skill` rejects ids outside this set+ even if the skill otherwise satisfies capability/scope gates."+ nil)+;;; ──────────────────────────────────────────────────────────────────;;; Permission → Scope mapping;;; ──────────────────────────────────────────────────────────────────diff --git a/src/metabase/metabot/skills.clj b/src/metabase/metabot/skills.cljnew file mode 100644index 00000000000..f418b234ec0--- /dev/null+++ b/src/metabase/metabot/skills.clj@@ -0,0 +1,295 @@+(ns metabase.metabot.skills+ "First-class skill registry for the agent.++ A *skill* is a chunk of task-specific instructions that the agent loads on demand (via the `load_skill`+ tool) instead of carrying in the system prompt at all times.+ This keeps the cached system-prompt prefix small while keeping rich, capability-specific guidance+ available when needed.++ Skills are decoupled from tools: a skill may associate with zero, one, or many tools; a tool may have+ many skills; and cross-cutting skills associate with no tool at all.+ Association is expressed on the skill (`:tools`, `:profiles`), so tools and profiles don't need to know+ about skills.++ Most skills are authored as markdown files with YAML frontmatter under `resources/metabot/skills/`.+ SQL dialect skills are registered programmatically from the `resources/metabot/prompts/dialects/` files+ and surfaced only by `dialect-preload-parts`.+ `skills-for-profile` removes them from the manifest, so the catalog omits them and an explicit+ `load_skill` of their id is rejected by the manifest gate in `skill-loadable?`."+ (:require+ [clojure.java.io :as io]+ [clojure.string :as str]+ [malli.error :as me]+ [metabase.api-scope.core :as api-scope]+ [metabase.driver :as driver]+ [metabase.metabot.capabilities :as capabilities]+ [metabase.metabot.scope :as scope]+ [metabase.util.files :as u.files]+ [metabase.util.malli :as mu]+ [metabase.util.malli.registry :as mr]+ [metabase.util.yaml :as yaml])+ (:import+ (java.nio.file Path)))++(set! *warn-on-reflection* true)++(def ^:private skill-schema+ [:map+ [:id :keyword]+ [:title :string]+ [:description :string]+ [:body :string]+ [:tools {:optional true} [:vector :string]]+ [:profiles {:optional true} [:maybe [:vector :keyword]]]+ [:capabilities {:optional true} [:vector :keyword]]+ [:scope {:optional true} :keyword]+ [:always-on {:optional true} :boolean]+ [:priority {:optional true} :int]+ [:dialect {:optional true} :string]])++(def ^:private *skills+ "Map of skill-id (keyword) -> skill definition map."+ (atom {}))++;;; Registration++(def ^:private skills-dir "metabot/skills")++(defn- normalize-skill+ "Apply defaults and coerce frontmatter values (YAML strings) into the types the schema expects."+ [skill]+ (cond-> skill+ (:id skill) (update :id keyword)+ true (update :tools (fnil #(mapv name %) []))+ (:profiles skill) (update :profiles #(mapv keyword %))+ (:capabilities skill) (update :capabilities #(mapv keyword %))+ (:scope skill) (update :scope keyword)+ true (update :priority (fnil int 50))+ true (update :always-on boolean)))++(defn- validate-skill!+ [skill]+ (when-not (mr/validate skill-schema skill)+ (throw (ex-info "Invalid skill definition"+ {:skill skill+ :errors (me/humanize (mu/explain skill-schema skill))})))+ (when-let [required-scope (:scope skill)]+ (when-not (api-scope/registered-scope? required-scope)+ (throw (ex-info (str "Skill has unregistered scope: " required-scope)+ {:skill skill :scope required-scope}))))+ skill)++(defn- split-frontmatter+ "Split a skill markdown file into [frontmatter-string body-string].+ Frontmatter is a leading block delimited by lines of `---`.+ Returns nil when no closed frontmatter block is present."+ [s]+ (when (str/starts-with? s "---")+ (let [after-open (subs s 3)]+ (when-let [close-idx (str/index-of after-open "\n---")]+ [(str/trim (subs after-open 0 close-idx))+ (str/triml (subs after-open (+ close-idx (count "\n---"))))]))))++(defn- resolve-skill+ "Resolve `skill-or-path` — a markdown resource path (relative to `metabot/skills/`) or a+ fully-specified skill map — into a validated skill map.+ The markdown form parses YAML frontmatter for metadata and uses the remaining text as `:body`."+ [skill-or-path]+ (-> (if (map? skill-or-path)+ skill-or-path+ (let [resource (io/resource (str skills-dir "/" skill-or-path))]+ (when-not resource+ (throw (ex-info "Skill resource not found" {:path skill-or-path})))+ (let [[fm body] (or (split-frontmatter (slurp resource))+ (throw (ex-info "Skill file is missing YAML frontmatter"+ {:path skill-or-path})))]+ (assoc (yaml/parse-string fm) :body (str/trim body)))))+ normalize-skill+ validate-skill!))++;;; Registry — markdown skills++(defn- markdown-resource-names+ "Names of the `.md` files under resource directory `dir`, sorted.+ Works both from the filesystem and from inside the uberjar."+ [dir]+ (u.files/with-open-path-to-resource [path dir]+ (->> (u.files/files-seq path)+ (keep (fn [^Path file]+ (let [filename (str (.getFileName file))]+ (when (str/ends-with? filename ".md")+ filename))))+ sort+ vec)))++(defn- markdown-skills []+ (map resolve-skill (markdown-resource-names skills-dir)))++;;; Registry — dialect skills (programmatic, hidden from catalog)++(def ^:private dialects-dir "metabot/prompts/dialects")++(defn- dialect-skill-id+ "Skill id (keyword) for a SQL engine, e.g. \"postgresql\" -> :sql-dialect-postgresql."+ [engine]+ (keyword (str "sql-dialect-" engine)))++(defn- dialect-skills+ "A hidden skill per dialect instruction file under resources/metabot/prompts/dialects/.+ The file name (sans extension) is the engine name (the lowercased `sql_engine` from viewing context)."+ []+ (for [filename (markdown-resource-names dialects-dir)+ :let [engine (str/replace filename #"\.md$" "")]]+ (resolve-skill {:id (dialect-skill-id engine)+ :title (str engine " SQL dialect")+ :description (str "SQL dialect instructions for " engine ".")+ :dialect engine+ :body (str/trim (slurp (io/resource (str dialects-dir "/" filename))))})))++(defn load-skills!+ "Scan the skill resource directories and (re)populate the registry.+ Runs at namespace load; public so a REPL can refresh the registry after editing skill files."+ []+ ;; Build the full map before touching the registry: a failed refresh (e.g. a malformed skill file)+ ;; throws without clobbering the existing registry, and readers never observe a partial one.+ ;; The reset! also means re-initializing drops removed or renamed skills.+ (reset! *skills (into {}+ (map (juxt :id identity))+ (concat (markdown-skills) (dialect-skills)))))++(load-skills!)++;;; Lookup / resolution++(defn get-skill+ "Return the skill definition for `id` (keyword), or nil."+ [id]+ (get @*skills id))++(defn all-skills+ "Return all registered skill definitions."+ []+ (vals @*skills))++(defn skills-for-tool+ "Return non-dialect skills associated with `tool-name` (a string)."+ [tool-name]+ (filter (fn [s]+ (and (not (:dialect s))+ (some #{tool-name} (:tools s))))+ (all-skills)))++(defn skill-scope-ok?+ "Whether the current user's scope satisfies `skill`'s `:scope` (if any).+ Skills without `:scope` are unrestricted."+ [skill]+ (let [required-scope (:scope skill)]+ (or (nil? required-scope)+ (api-scope/scope-matches? scope/*current-user-scope* required-scope))))++(defn skill-visible?+ "Whether `skill` is available given the request's `capability-set` and the current user's scope.+ Skills without `:capabilities`/`:scope` are unrestricted."+ [skill capability-set]+ (and (every? capability-set (:capabilities skill))+ (skill-scope-ok? skill)))++(defn skill-loadable?+ "Whether `skill` may be loaded on demand by the current request.+ Applies the **same** capability + scope gate as the catalog (`skill-visible?`) and, when a request+ manifest has been built, requires the id to be present in that manifest. This prevents a request+ with `load_skill` from loading hidden skills for inactive tools/profiles by guessing ids."+ [skill]+ (and (skill-visible? skill (capabilities/capability-set scope/*current-user-capabilities*))+ (or (nil? scope/*current-loadable-skill-ids*)+ (contains? @scope/*current-loadable-skill-ids* (:id skill)))))++(defn- record-loadable-skill-ids!+ "Remember the exact visible skill ids from the current request's manifest, when request+ scope tracking is enabled."+ [visible]+ (when-let [allowed-ids scope/*current-loadable-skill-ids*]+ (reset! allowed-ids (set (map :id visible)))))++(defn skills-for-profile+ "Return the distinct, non-dialect skills relevant to `profile` given its `active-tool-names` (strings).+ A skill is relevant when it is listed on the profile's `:skills`, associates with an active tool, or is+ cross-cutting (no `:tools`) and matches the profile (`:profiles` nil or contains the name)."+ [profile active-tool-names]+ (let [active (set active-tool-names)+ explicit (set (:skills profile))+ profile-name (:name profile)+ relevant? (fn [s]+ (or (contains? explicit (:id s))+ (some active (:tools s))+ (and (empty? (:tools s))+ (let [ps (:profiles s)]+ (or (nil? ps) (contains? (set ps) profile-name))))))]+ (->> (all-skills)+ (remove :dialect)+ (filter relevant?)+ distinct)))++(defn build-skill-manifest+ "Build the skill manifest for a profile + active tools, gated by `capabilities` and the user's scope.+ Returns {:always-on [skill-map…] :catalog [{:id :title :description}…]} sorted by descending priority+ then id."+ [profile active-tool-names capabilities]+ (let [cap-set (capabilities/capability-set capabilities)+ visible (->> (skills-for-profile profile active-tool-names)+ (filter #(skill-visible? % cap-set))+ (sort-by (juxt (comp - :priority) (comp str :id))))]+ (record-loadable-skill-ids! visible)+ {:always-on (filter :always-on visible)+ :catalog (->> visible+ (remove :always-on)+ (mapv (fn [s]+ {:id (name (:id s))+ :title (:title s)+ :description (:description s)})))}))++;;; Dialect preload++(defn- engine->dialect+ "Resolve a SQL `engine` (the driver name from viewing context, e.g. \"postgres\") to the dialect name+ its skill is registered under (the dialect file's base name, e.g. \"postgresql\").+ Resolution goes through [[metabase.driver/llm-sql-dialect-resource]], the canonical driver->dialect-file+ mapping (it isn't 1:1 — `:sparksql` shares databricks.md)."+ [engine]+ (when-let [path (try+ (driver/llm-sql-dialect-resource (keyword engine))+ ;; `engine` comes from FE-supplied viewing context and may not name a driver.+ (catch Exception _ nil))]+ (-> path (str/split #"/") peek (str/replace #"\.md$" ""))))++(defn dialect-skill+ "The registered dialect skill for SQL `engine` (a driver name or dialect name), or nil.+ Tries `engine` as a dialect name first so bare dialect inputs never touch the driver system."+ [engine]+ (when engine+ (or (get-skill (dialect-skill-id engine))+ (some-> (engine->dialect engine) dialect-skill-id get-skill))))++(defn dialect-preload-parts+ "Given a SQL `engine` name (e.g. \"postgres\", as extracted from viewing context), return AISDK parts+ that preload its dialect skill body into the message stream as a synthetic `load_skill` tool call ++ result.+ These sit below the system cache breakpoint, so the cached system prefix stays identical across+ databases.++ Returns [] when `engine` is nil or has no matching dialect skill.+ Dialect context only arises in SQL-editor sessions, so its presence is itself the gate.++ Invariant: the emitted pair references the `load_skill` tool, which+ [[metabase.metabot.agent.profiles/get-tools-for-profile]] registers whenever the skill catalog is+ non-empty.+ Any profile that can reach SQL-editor/dialect context also exposes query skills (the cross-cutting+ `read-resource` skill alone keeps the catalog non-empty), so `load_skill` is always registered when+ this returns a non-empty preload."+ [engine]+ (or (when-let [skill (dialect-skill engine)]+ (let [skill-id (:id skill)+ call-id (str "skill_preload_" (name skill-id))]+ [{:type :tool-input :id call-id :function "load_skill" :arguments {:ids [(name skill-id)]}}+ {:type :tool-output :id call-id :result {:output (:body skill)}}]))+ []))diff --git a/src/metabase/metabot/tools.clj b/src/metabase/metabot/tools.cljindex 429288987f5..e59f4349ed0 100644--- a/src/metabase/metabot/tools.clj+++ b/src/metabase/metabot/tools.clj@@ -21,6 +21,7 @@[metabase.metabot.tools.resources :as tools.resources][metabase.metabot.tools.search :as tools.search][metabase.metabot.tools.shared :as shared]+ [metabase.metabot.tools.skills :as tools.skills][metabase.metabot.tools.slackbot-query :as tools.slackbot-query][metabase.metabot.tools.snippets :as tools.snippets][metabase.metabot.tools.sql :as tools.sql]@@ -86,7 +87,9 @@[tools.create-alertcreate-alert-tool][tools.create-dashboard-subscription- slackbot-create-dashboard-subscription-tool])+ slackbot-create-dashboard-subscription-tool]+ [tools.skills+ load-skill-tool])(def query-generation-tool-names"Tool names that produce a runnable query (SQL or notebook). Both the in-app@@ -127,9 +130,10 @@values are tool definition maps (with :doc, :schema, :prompt, :fn, andoptionally :decode keys).- Tool-specific instructions are loaded from `resources/metabot/prompts/tools/`- by `extract-tool-instructions` in `prompts.clj`, keyed by `:prompt` or- `<tool-name>.md` by default."+ Tool-specific *instructions* are no longer carried in the prompt. They live in+ the skill registry (`metabase.metabot.skills`) and are surfaced as a manifest+ in the system prompt, with full bodies loaded on demand via the `load_skill`+ tool."[tools memory-atom metabot-id](reduce-kv(fn [acc tool-name tool-var]diff --git a/src/metabase/metabot/tools/field_stats.clj b/src/metabase/metabot/tools/field_stats.cljindex 09f3f8489f4..4b610167e72 100644--- a/src/metabase/metabot/tools/field_stats.clj+++ b/src/metabase/metabot/tools/field_stats.clj@@ -32,6 +32,17 @@(build-field-statistics fvs fp limit))(build-field-statistics nil fingerprint limit)))+(defn- field-metadata-output+ "Build the `:field-metadata` tool result for `col` of `query`. Surfaces the column's portable+ FK + join label (via `->result-column`) so a drilled-into field/dimension detail tells the LLM+ exactly how to reference the column."+ [query col field-id limit]+ {:structured-output (merge {:result-type :field-metadata+ :field_id field-id+ :value_metadata (field-statistics col limit)}+ (select-keys (metabot.tools.u/->result-column query col)+ [:portable_fk :table_reference]))})+(defn- table-field-stats[table-id field-id limit](try@@ -40,9 +51,7 @@{:agent-error? true :status-code 404})))visible-cols (lib/visible-columns query)col (metabot.tools.u/find-column-by-field-id field-id visible-cols)]- {:structured-output {:result-type :field-metadata- :field_id field-id- :value_metadata (field-statistics col limit)}})+ (field-metadata-output query col field-id limit))(catch Exception ex(metabot.tools.u/handle-agent-error ex))))@@ -54,9 +63,7 @@{:agent-error? true :status-code 404})))visible-cols (lib/visible-columns query)col (metabot.tools.u/find-column-by-field-id field-id visible-cols)]- {:structured-output {:result-type :field-metadata- :field_id field-id- :value_metadata (field-statistics col limit)}})+ (field-metadata-output query col field-id limit))(catch Exception ex(metabot.tools.u/handle-agent-error ex))))@@ -68,9 +75,7 @@{:agent-error? true :status-code 404})))filterable-cols (lib/filterable-columns query)col (metabot.tools.u/find-column-by-field-id field-id filterable-cols)]- {:structured-output {:result-type :field-metadata- :field_id field-id- :value_metadata (field-statistics col limit)}})+ (field-metadata-output query col field-id limit))(catch Exception ex(metabot.tools.u/handle-agent-error ex))))diff --git a/src/metabase/metabot/tools/metadata.clj b/src/metabase/metabot/tools/metadata.cljindex b8f2460f428..2a9ccf7430a 100644--- a/src/metabase/metabot/tools/metadata.clj+++ b/src/metabase/metabot/tools/metadata.clj@@ -126,9 +126,10 @@(defn- format-field-metadata-output;; NOTE: keep in sync with read_resource.clj/format-content :field-metadata branch- [{:keys [field_id value_metadata]}]+ [{:keys [field_id value_metadata portable_fk table_reference]}](format-with-instructions- (llm-shape/field-metadata->xml {:field_id field_id :value_metadata value_metadata})+ (llm-shape/field-metadata->xml {:field_id field_id :value_metadata value_metadata+ :portable_fk portable_fk :table_reference table_reference})instructions/field-metadata-instructions))(defn- add-outputdiff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.cljindex d066158f582..3b13cddeb8f 100644--- a/src/metabase/metabot/tools/shared/llm_shape.clj+++ b/src/metabase/metabot/tools/shared/llm_shape.clj@@ -84,6 +84,31 @@(str/replace ">" ">")(str/replace "\"" """))))+(defn- escape-xml-content+ "Like `escape-xml` but leaves double-quotes intact. Safe for element/table-cell *content*+ (only `& < >` are structural there), so a value such as a JSON portable-FK array renders+ readably instead of with `"` noise."+ [s]+ (when s+ (-> (str s)+ (str/replace "&" "&")+ (str/replace "<" "<")+ (str/replace ">" ">"))))++(defn- escape-pipes+ "Escape `|` so a value can't break a markdown table row.+ Custom `:value-fn`s replace [[metabase.metabot.tmpl/markdown-table]]'s default, which does this."+ [s]+ (when s+ (str/replace s "|" "\\|")))++(defn- json-cell-safe+ "Keep a JSON string valid inside a markdown table cell. Markdown `\\|` escaping is not+ valid JSON, so encode pipe characters as JSON unicode escapes instead."+ [s]+ (when s+ (str/replace s "|" "\\u007c")))+(defn- database-type-or-unknown"Return database type or 'unknown' if nil."[database-type]@@ -151,11 +176,12 @@(te/markdown-tablefields columns{:value-fn (fn [k v]- (escape-xml- (cond- (nil? v) ""- (and (#{:type :base-type} k) (keyword? v)) (clojure.core/name v)- :else (str v))))}))+ (escape-pipes+ (escape-xml+ (cond+ (nil? v) ""+ (and (#{:type :base-type} k) (keyword? v)) (clojure.core/name v)+ :else (str v)))))}))(defn- fully-qualified-name"Get fully qualified name for a table."@@ -175,8 +201,11 @@(render-llm-template:field{:field_id field_id- ;; Uses |safe in template to preserve literal \" quotes, so we escape the name for XML safety- :field_name_quoted (str "\\\"" (escape-xml name) "\\\"")+ ;; The bare physical column name — emitted unquoted so the LLM copies it verbatim into a+ ;; portable field reference (`[db schema table COL]`). Wrapping it in quotes here caused the+ ;; model to paste `"COL"` into MBQL field refs, which the resolver rejects. Uses |safe in the+ ;; template, so escape for XML safety here.+ :field_name (escape-xml name):field_display_name (or display_name name):field_base_type (when type (clojure.core/name type)):field_database_type (database-type-or-unknown database_type)@@ -238,6 +267,43 @@:related_table_fqn fully_qualified_name:related_table_fields_xml (when (seq fields) (str/join "\n" (map field->xml fields)))}))+(defn- dimension-source-table+ "Human-readable `schema.table` for a queryable dimension, derived from its portable FK, plus+ the join label when the dimension is reached through an FK from the base table."+ [{:keys [portable_fk table_reference]}]+ (when (and (vector? portable_fk) (>= (count portable_fk) 3))+ (let [[_db schema table] portable_fk+ fqn (fully-qualified-name schema table)]+ (if (not-empty table_reference)+ (str fqn " (via " table_reference ")")+ fqn))))++(defn format-metric-dimensions-table+ "Render a metric's queryable dimensions as a markdown table that names the **source table**+ each dimension comes from and the exact **portable FK** to copy into a `field` clause.++ A metric's dimensions span its base table and every FK-reachable table, so a bare field list+ is ambiguous: the LLM can't tell which table a name like `name` lives on, and duplicate names+ across joined tables (e.g. several `campaign_id`/`id` columns) are indistinguishable. The+ `Source table` and `Reference` columns remove that ambiguity."+ [dims]+ (te/markdown-table+ (map (fn [d]+ (assoc d+ :source (dimension-source-table d)+ :reference (when (vector? (:portable_fk d)) (json/encode (:portable_fk d)))))+ dims)+ {:name "Field Name" :field_id "Field ID" :type "Type"+ :source "Source table" :reference "Reference (copy into a field clause)"}+ {:value-fn (fn [k v]+ (cond+ (nil? v) ""+ (keyword? v) (escape-pipes (clojure.core/name v))+ ;; `reference` is a JSON array the LLM copies verbatim. Keep the cell valid+ ;; JSON by encoding pipes as `\u007c` instead of markdown `\|`.+ (= k :reference) (json-cell-safe (escape-xml-content v))+ :else (escape-pipes (escape-xml (str v)))))}))+(defn metric->xml"Format metric for LLM consumption.Matches Python Metric.get_llm_representation exactly, except we additionally surface@@ -263,7 +329,7 @@:metric_collection_xml (when collection (collection->xml collection)):metric_default_time_dimension (:name default_time_dimension_field):metric_dimensions_table (when (seq queryable-dimensions)- (format-fields-table queryable-dimensions))}))+ (format-metric-dimensions-table queryable-dimensions))}))(defn table->xml"Format table for LLM consumption.@@ -616,7 +682,7 @@Matches Python FieldValuesMetadata.llm_representation exactly.Note: Tables are used with |safe in the template, so values must be escaped."[{:keys [field_values statistics]}]- (let [escape-value (fn [_k v] (escape-xml (str v)))+ (let [escape-value (fn [_k v] (escape-pipes (escape-xml (str v))))sample-values-table (when (seq field_values)(te/markdown-table(map vector field_values)@@ -636,11 +702,18 @@(defn field-metadata->xml"Format field metadata for LLM consumption.- Matches Python GetFieldMetadataResultSchema.llm_representation exactly."- [{:keys [field_id value_metadata]}]+ Matches Python GetFieldMetadataResultSchema.llm_representation exactly, plus an optional+ `source table` + `reference` (portable FK) when the caller supplies them — so a drilled-into+ field/dimension detail tells the LLM exactly how to reference the column."+ [{:keys [field_id value_metadata portable_fk table_reference]}](render-llm-template:field_metadata{:field_metadata_field_id field_id+ :field_metadata_source (dimension-source-table {:portable_fk portable_fk+ :table_reference table_reference})+ ;; rendered with |safe — escape XML structural chars but keep the JSON's quotes readable,+ ;; like the `:reference` column in [[format-metric-dimensions-table]]+ :field_metadata_reference (when (vector? portable_fk) (escape-xml-content (json/encode portable_fk))):field_metadata_value_xml (when value_metadata(field-values-metadata->xml value_metadata))}))diff --git a/src/metabase/metabot/tools/skills.clj b/src/metabase/metabot/tools/skills.cljnew file mode 100644index 00000000000..f41cb1a03bd--- /dev/null+++ b/src/metabase/metabot/tools/skills.clj@@ -0,0 +1,44 @@+(ns metabase.metabot.tools.skills+ "The `load_skill` tool: loads the full body of one or more skills on demand.++ Skill bodies are returned as the tool result (i.e. into the message stream,+ below the system cache breakpoint) so the cached system prefix stays stable as+ skills are loaded."+ (:require+ [clojure.string :as str]+ [metabase.metabot.skills :as skills]+ [metabase.util.log :as log]+ [metabase.util.malli :as mu]))++(set! *warn-on-reflection* true)++(defn- load-one+ "Resolve and format a single skill id, or an inline message when it is unknown+ or not available to the current user."+ [id]+ (let [skill (skills/get-skill (keyword id))]+ (cond+ (nil? skill)+ (do (log/info "Unknown skill requested by load_skill" {:id id})+ (format "Unknown skill: \"%s\". Load only ids listed under \"Available skills\"." id))++ (not (skills/skill-loadable? skill))+ (do (log/info "Skill not available to current request" {:id id})+ (format "Skill \"%s\" is not available to you." id))++ :else+ (format "<skill id=\"%s\">\n%s\n</skill>" (name (:id skill)) (:body skill)))))++(mu/defn ^{:tool-name "load_skill"}+ load-skill-tool+ "Load the full instructions for one or more skills listed under \"Available+ skills\". Call this immediately before doing the related work; you may load+ several skills at once. Load only what is relevant to the current task."+ [{:keys [ids]} :- [:map {:closed true}+ [:ids [:sequential+ [:string {:description "A skill id, e.g. construct-notebook-query-core"}]]]]]+ (try+ {:output (str/join "\n\n" (map load-one ids))}+ (catch Exception e+ (log/error e "Failed to load skill(s)" {:ids ids})+ {:output (str "Failed to load skill(s): " (or (ex-message e) "Unknown error"))})))diff --git a/src/metabase/search/scoring.clj b/src/metabase/search/scoring.cljindex 3d76e2ceddf..b30880adb16 100644--- a/src/metabase/search/scoring.clj+++ b/src/metabase/search/scoring.clj@@ -29,7 +29,9 @@"Wrap a string column/value SQL expr with the normalization the text scorers compare on:lower-case, replace commas with spaces, collapse whitespace runs to one space, trim.`db-type` picks the regexp_replace dialect -- Postgres needs the 'g' flag; H2 replaces all by default and- rejects 'g'."+ rejects 'g'.+ Only :postgres and :h2 can reach this: the appdb engine is gated to those (see+ [[metabase.search.appdb.core/supported-db?]]) and semantic search passes :postgres explicitly."([expr] (normalize-text-expr (mdb/db-type) expr))([db-type expr];; Replace commas with a space, not nothing, so `a,b` doesn't collapse into `ab`.diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.cljindex 16cce8cf63e..dad419e4af5 100644--- a/test/metabase/agent_api/api_test.clj+++ b/test/metabase/agent_api/api_test.clj@@ -686,6 +686,25 @@{:name "Bad Dashboard":question_ids [999999]})))+(deftest create-entity-url-test+ (testing "create question/dashboard return a frontend URL"+ (testing "absolute when site-url is set"+ (mt/with-temporary-setting-values [site-url "https://mb.example.com"]+ (let [construct (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"+ {:query (orders-query :limit 1)})+ q (mt/user-http-request :rasta :post 200 "agent/v1/question"+ {:name "URL Q" :query (:query construct)})+ d (mt/user-http-request :rasta :post 200 "agent/v1/dashboard" {:name "URL D"})]+ (is (= (str "https://mb.example.com/question/" (:id q)) (:url q)))+ (is (= (str "https://mb.example.com/dashboard/" (:id d)) (:url d)))+ (t2/delete! :model/Card :id (:id q))+ (t2/delete! :model/Dashboard :id (:id d)))))+ (testing "relative when site-url is unset (no \"null\" prefix)"+ (mt/with-temporary-setting-values [site-url nil]+ (let [d (mt/user-http-request :rasta :post 200 "agent/v1/dashboard" {:name "Relative URL D"})]+ (is (= (str "/dashboard/" (:id d)) (:url d)))+ (t2/delete! :model/Dashboard :id (:id d)))))))+(deftest create-collection-test(testing "Creates a root-level collection"(mt/with-current-user (mt/user->id :crowberto)diff --git a/test/metabase/agent_lib/representations/repair_test.clj b/test/metabase/agent_lib/representations/repair_test.cljindex 36c8a835299..8592b24b40b 100644--- a/test/metabase/agent_lib/representations/repair_test.clj+++ b/test/metabase/agent_lib/representations/repair_test.clj@@ -228,6 +228,38 @@(is (= ["field" {"temporal-unit" "month"} "MY_COLUMN"]output)))))+;;; ============================================================+;;; Pass 1.75 - strip stray double-quotes from field-reference targets+;;; ============================================================++(deftest ^:parallel dequote-portable-fk-column-test+ (testing "a double-quoted column segment in a portable FK is stripped"+ (let [input ["field" {} ["Sample" "PUBLIC" "ORDERS" "\"STATUS\""]]+ output (repair/repair trivial-mp input)]+ (is (= ["field" {} ["Sample" "PUBLIC" "ORDERS" "STATUS"]] output)))))++(deftest ^:parallel dequote-leaves-cross-stage-strings-to-resolution-aware-pass-test+ (testing "a bare cross-stage string target is NOT touched by this pass (the resolution-aware+ cross-stage pass owns that case and only strips when it resolves)"+ (let [input ["field" {} "\"campaign_name\""]+ output (repair/repair trivial-mp input)]+ (is (= ["field" {} "\"campaign_name\""] output)))))++(deftest ^:parallel dequote-leaves-filter-literals-untouched-test+ (testing "only field targets are dequoted; a quoted filter literal is preserved verbatim"+ (let [input ["=" {} ["field" {} ["Sample" "PUBLIC" "ORDERS" "\"STATUS\""]] "\"paid\""]+ output (repair/repair trivial-mp input)]+ (is (= ["=" {} ["field" {} ["Sample" "PUBLIC" "ORDERS" "STATUS"]] "\"paid\""] output)))))++(deftest ^:parallel dequote-is-idempotent-test+ (testing "dequoting is a fixed point"+ (let [input ["field" {} ["Sample" "PUBLIC" "ORDERS" "\"STATUS\""]]+ once (repair/repair trivial-mp input)]+ (is (= once (repair/repair trivial-mp once)))))+ (testing "an already-bare name is left alone"+ (let [input ["field" {} ["Sample" "PUBLIC" "ORDERS" "STATUS"]]]+ (is (= input (repair/repair trivial-mp input))))))+;;; ============================================================;;; Pass 1.81 - rewrite operator-name aliases to canonical lib heads;;; ============================================================@@ -1817,6 +1849,45 @@twice (repair/repair mp-fks once)](is (= once twice)))))+(deftest ^:parallel cross-stage-loose-name-remap-test+ (testing "a hyphenated cross-stage ref (`count-where`) is remapped to the canonical+ underscore output column (`count_where`) the aggregation actually produces"+ (let [q {"lib/type" "mbql/query"+ "database" "Sample"+ "stages" [{"lib/type" "mbql.stage/mbql"+ "source-table" ["Sample" "PUBLIC" "ORDERS"]+ "aggregation" [["count-where" {}+ [">" {} ["field" {} ["Sample" "PUBLIC" "ORDERS" "ID"]] 5]]]+ "breakout" [["field" {} ["Sample" "PUBLIC" "ORDERS" "PRODUCT_ID"]]]}+ {"lib/type" "mbql.stage/mbql"+ "filters" [[">" {} ["field" {} "count-where"] 0]]}]}+ out (repair/repair mp-fks q)+ field-clause (get-in out ["stages" 1 "filters" 0 2])]+ (testing "the name is canonicalised to the real output column"+ (is (= "count_where" (nth field-clause 2))))+ (testing "and base-type is stamped from the resolved prefix column"+ (is (contains? (nth field-clause 1) "base-type")))+ (testing "idempotent"+ (is (= out (repair/repair mp-fks out))))))+ (testing "a loose key matching no real column is left untouched for the resolver"+ (let [out (repair/repair mp-fks+ (assoc-in multi-stage-base-query+ ["stages" 1 "filters" 0 2 2] "totally-unknown"))]+ (is (= "totally-unknown" (get-in out ["stages" 1 "filters" 0 2 2])))))+ (testing "a loose key colliding with two columns is left for the resolver (the hits>1 guard)"+ ;; `normalize-col-key` folds case and hyphen/space to underscore, so `Count Where` and+ ;; `count-where` both normalize to `count_where`. Real lib output names don't collide like this,+ ;; so exercise the guard directly on the private matcher.+ (is (nil? (#'repair/match-cross-stage-column+ {"Count Where" {"base-type" "type/Integer"}+ "count-where" {"base-type" "type/Integer"}}+ "count_where")))+ (testing "but a single loose hit still resolves"+ (is (= ["count_where" {"base-type" "type/Integer"}]+ (#'repair/match-cross-stage-column+ {"count_where" {"base-type" "type/Integer"}}+ "Count-Where"))))))+(deftest ^:parallel cross-stage-field-type-end-to-end-resolve-test(testing (str "End-to-end: a multi-stage YAML with a stage-1 cross-stage ref lacking\n""base-type is repaired and then `resolve-query` + `lib/query` accept the\n"diff --git a/test/metabase/metabot/agent/prompt_cache_test.clj b/test/metabase/metabot/agent/prompt_cache_test.cljindex 0f434e05624..967b9ca5ca4 100644--- a/test/metabase/metabot/agent/prompt_cache_test.clj+++ b/test/metabase/metabot/agent/prompt_cache_test.clj@@ -62,7 +62,8 @@(prompts/build-system-message-content{:prompt-template template-name}per-request-context- {})))+ {}+ [])))(defn- prefix-of [rendered](let [idx (.indexOf ^String rendered ^String cache-breakpoint)]diff --git a/test/metabase/metabot/agent/prompt_gating_test.clj b/test/metabase/metabot/agent/prompt_gating_test.cljindex b24678b6bbd..76c194b347c 100644--- a/test/metabase/metabot/agent/prompt_gating_test.clj+++ b/test/metabase/metabot/agent/prompt_gating_test.clj@@ -5,14 +5,22 @@[metabase.metabot.scope :as scope][metabase.test :as mt]))+(def ^:private active-sql-tool-names+ "Active-tool names including a SQL write tool, so SQL guidance gates on permissions rather than on+ the SQL tools being absent."+ ["create_sql_query"])+(defn- render-internal-template- "Render the internal.selmer template with given permission flags."- [perms]- (binding [scope/*current-user-metabot-permissions* perms]- (prompts/build-system-message-content- {:prompt-template "internal.selmer"}- {:current_time "2026-03-25T12:00:00Z"}- {})))+ "Render internal.selmer for `perms` and `active-tool-names` (default [[active-sql-tool-names]]).+ The prompt builder reads only tool names, so a name->nil map stands in for the real name->var one."+ ([perms] (render-internal-template perms active-sql-tool-names))+ ([perms active-tool-names]+ (binding [scope/*current-user-metabot-permissions* perms]+ (prompts/build-system-message-content+ {:prompt-template "internal.selmer"}+ {:current_time "2026-03-25T12:00:00Z"}+ (zipmap active-tool-names (repeat nil))+ []))))(def ^:private all-yes-perms{:permission/metabot-sql-generation :yes@@ -53,6 +61,13 @@(testing "denial suggests NLQ as alternative"(is (re-find #"natural language query builder" rendered)))))+(deftest ^:parallel prompt-excludes-sql-sections-when-tools-inactive-test+ (testing "SQL permission alone does not render SQL guidance when no SQL write tool is active+ (the tools are capability-gated, so the prompt must not cite tools/skills that are absent)"+ (let [rendered (render-internal-template all-yes-perms ["construct_notebook_query"])]+ (is (not (re-find #"# Writing SQL" rendered)))+ (is (re-find #"You cannot write SQL" rendered)))))+(deftest ^:parallel prompt-gates-nql-section-test(let [with-nql (render-internal-template all-yes-perms)without-nql (render-internal-template no-nql-perms)]@@ -143,7 +158,8 @@(prompts/build-system-message-content{:prompt-template "slackbot.selmer"}{:current_time "2026-03-25T12:00:00Z"}- {})))+ {}+ [])))(deftest ^:parallel slackbot-nlq-sections-gated-test(let [with-nlq (render-slackbot-template all-yes-perms)@@ -208,7 +224,8 @@(prompts/build-system-message-content{:prompt-template template-name}{:current_time "2026-03-25T12:00:00Z"}- {})))+ {}+ [])))(deftest custom-chat-instructions-injected-when-set-test(mt/with-premium-features #{:ai-controls}diff --git a/test/metabase/metabot/agent/prompts_test.clj b/test/metabase/metabot/agent/prompts_test.cljindex 1b04d62a7be..0231e030b78 100644--- a/test/metabase/metabot/agent/prompts_test.clj+++ b/test/metabase/metabot/agent/prompts_test.clj@@ -1,5 +1,6 @@(ns metabase.metabot.agent.prompts-test(:require+ [clojure.java.io :as io][clojure.string :as str][clojure.test :refer :all][metabase.metabot.agent.prompts :as prompts]))@@ -21,30 +22,14 @@(is (nil? template)))))(deftest ^:parallel construct-notebook-query-prompt-database-name-examples-test- (let [prompt (prompts/load-tool-prompt-template "construct_notebook_query.md")]+ ;; This .md is the canonical construct_query format reference, served verbatim as an MCP resource+ ;; (see metabase.mcp.resources) and the source the construct-notebook-query-* skills were split from.+ (let [prompt (slurp (io/resource "metabot/prompts/tools/construct_notebook_query.md"))](is (some? prompt))(testing "examples use the exact sample database name, not the old abbreviated portable FK"(is (str/includes? prompt "Sample Database"))(is (not (re-find #"\[Sample\s*," prompt))))))-(deftest ^:parallel load-dialect-instructions-test- (testing "loads postgresql dialect"- (let [instructions (prompts/load-dialect-instructions "postgresql")]- (is (some? instructions))- (is (string? instructions))- (is (re-find #"PostgreSQL" instructions))))- (testing "loads mysql dialect"- (let [instructions (prompts/load-dialect-instructions "mysql")]- (is (some? instructions))- (is (string? instructions))- (is (re-find #"MySQL" instructions))))- (testing "returns nil for non-existent dialect"- (let [instructions (prompts/load-dialect-instructions "non-existent")]- (is (nil? instructions))))- (testing "returns nil for nil dialect"- (let [instructions (prompts/load-dialect-instructions nil)]- (is (nil? instructions)))))-(deftest ^:parallel render-system-prompt-test(testing "renders template with variables"(let [template "Hello {{name}}, today is {{day}}"@@ -81,31 +66,15 @@;; Load again - should return from cache(let [template2 (prompts/get-cached-system-prompt "internal.selmer")](is (= template1 template2)))))- (testing "caches dialect instructions"- ;; Clear cache first- (prompts/clear-cache!)- ;; Load dialect - should cache it- (let [dialect1 (prompts/get-cached-dialect-instructions "postgresql")]- (is (some? dialect1))- ;; Load again - should return from cache- (let [dialect2 (prompts/get-cached-dialect-instructions "postgresql")]- (is (= dialect1 dialect2)))))(testing "clear-cache! removes all cached templates";; Load some templates(prompts/get-cached-system-prompt "internal.selmer")- (prompts/get-cached-dialect-instructions "postgresql");; Clear cache(prompts/clear-cache!);; Cache should be empty (we can't directly test this, but we can reload)(let [template (prompts/get-cached-system-prompt "internal.selmer")](is (some? template)))))-(deftest ^:parallel extract-tool-instructions-test- (testing "finds correct instructions"- (is (=? [{:tool_name "read_resource"- :instructions #(str/includes? % "you have access to a unified interface")}]- (prompts/extract-tool-instructions {"read_resource" identity})))))-(deftest ^:parallel build-system-message-content-test(testing "builds complete system message"(let [profile {:prompt-template "embedding-next.selmer"}@@ -113,7 +82,7 @@:first_day_of_week "Sunday":sql-dialect "postgresql"}tools {}- content (prompts/build-system-message-content profile context tools)]+ content (prompts/build-system-message-content profile context tools [])](is (some? content))(is (string? content))(is (> (count content) 100))@@ -126,7 +95,7 @@context {:current_time "2024-01-15 14:30:00":sql-dialect "postgresql"}tools {}- content (prompts/build-system-message-content profile context tools)]+ content (prompts/build-system-message-content profile context tools [])](is (some? content));; Note: The embedding template might not reference dialect instructions,;; but they should be available in the template context@@ -137,7 +106,7 @@(let [profile {:prompt-template "non-existent.selmer"}context {}tools {}- content (prompts/build-system-message-content profile context tools)]+ content (prompts/build-system-message-content profile context tools [])](is (some? content))(is (= "You are Metabot, a data analysis assistant for Metabase." content)))))@@ -146,7 +115,7 @@(let [profile {}context {:current_time "2024-01-15 14:30:00"}tools {}- content (prompts/build-system-message-content profile context tools)]+ content (prompts/build-system-message-content profile context tools [])](is (some? content))(is (string? content))(is (> (count content) 1000)))))@@ -157,7 +126,7 @@context {:current_time "2024-01-15 14:30:00":sql-dialect "postgresql"}tools {}- content (prompts/build-system-message-content profile context tools)]+ content (prompts/build-system-message-content profile context tools [])](is (some? content))(is (string? content))(is (str/includes? content "{{#model_id-short-slug}}"))@@ -173,7 +142,7 @@context {:current_time "2024-01-15 14:30:00":current_user_info "<user><name>Jane Doe</name></user>"}tools {}- content (prompts/build-system-message-content profile context tools)]+ content (prompts/build-system-message-content profile context tools [])](is (some? content))(is (not (str/includes? content "Here is some information about the user:")))(is (not (str/includes? content "<user><name>Jane Doe</name></user>"))))))diff --git a/test/metabase/metabot/skills_test.clj b/test/metabase/metabot/skills_test.cljnew file mode 100644index 00000000000..745e8941319--- /dev/null+++ b/test/metabase/metabot/skills_test.clj@@ -0,0 +1,127 @@+(ns metabase.metabot.skills-test+ (:require+ [clojure.string :as str]+ [clojure.test :refer [deftest is testing]]+ [metabase.metabot.scope :as scope]+ [metabase.metabot.skills :as skills]+ [metabase.test :as mt]))++(set! *warn-on-reflection* true)++(deftest ^:parallel skill-loadable?-capability-gate-test+ (testing "load_skill applies the same capability gate as the catalog, so a capability-gated+ skill hidden from the manifest is not loadable by id either"+ (let [gated {:id :x :title "x" :description "x" :body "x"+ :capabilities [:permission-write-sql-queries]}]+ (testing "loadable when the request carries the capability"+ (binding [scope/*current-user-capabilities* ["permission:write_sql_queries"]]+ (is (skills/skill-loadable? gated))))+ (testing "not loadable when the request lacks it"+ (binding [scope/*current-user-capabilities* #{}]+ (is (not (skills/skill-loadable? gated)))))))+ (testing "an ungated skill is loadable regardless of capabilities"+ (binding [scope/*current-user-capabilities* #{}]+ (is (skills/skill-loadable? {:id :y :title "y" :description "y" :body "y"})))))++(deftest ^:parallel skill-loadable?-manifest-gate-test+ (testing "when a request manifest has been tracked, load_skill is limited to ids from that manifest"+ (let [allowed-skill (skills/get-skill :construct-notebook-query-core)+ hidden-skill (skills/get-skill :read-resource)]+ (binding [scope/*current-loadable-skill-ids* (atom #{:construct-notebook-query-core})]+ (is (skills/skill-loadable? allowed-skill))+ (is (not (skills/skill-loadable? hidden-skill)))))))++(deftest ^:parallel registry-populated-test+ (testing "markdown skills and dialect skills are registered at load"+ (let [ids (set (map :id (skills/all-skills)))]+ (is (contains? ids :construct-notebook-query-core))+ (is (contains? ids :read-resource))+ (is (contains? ids :sql-dialect-postgresql)))+ (testing "construct monolith is split into three skills"+ (is (every? (set (map :id (skills/all-skills)))+ [:construct-notebook-query-core+ :construct-notebook-query-advanced+ :construct-notebook-query-operators])))))++(deftest ^:parallel skill-shape-test+ (testing "a parsed markdown skill has frontmatter + body"+ (let [s (skills/get-skill :construct-notebook-query-core)]+ (is (= "construct-notebook-query-core" (name (:id s))))+ (is (string? (:title s)))+ (is (str/includes? (:description s) "construct_notebook_query"))+ (is (= ["construct_notebook_query"] (:tools s)))+ (is (str/includes? (:body s) "Universal clause shape"))+ ;; the YAML frontmatter delimiter must not leak into the body+ (is (not (str/starts-with? (:body s) "---"))))))++(deftest ^:parallel skills-for-tool-test+ (testing "all three construct skills associate with the construct tool"+ (is (= #{:construct-notebook-query-core+ :construct-notebook-query-advanced+ :construct-notebook-query-operators}+ (set (map :id (skills/skills-for-tool "construct_notebook_query"))))))+ (testing "dialect skills are never returned by tool association"+ (is (empty? (filter :dialect (skills/skills-for-tool "construct_notebook_query"))))))++(deftest ^:parallel skills-for-profile-test+ (let [profile {:name :internal}]+ (testing "tool-associated skills surface for active tools"+ (let [ids (set (map :id (skills/skills-for-profile profile ["construct_notebook_query"])))]+ (is (contains? ids :construct-notebook-query-core))+ (is (not (contains? ids :read-resource)))))+ (testing "no skills for tools the profile is not using"+ (is (empty? (skills/skills-for-profile profile []))))+ (testing "dialect skills are excluded even though they have no tools"+ (is (empty? (filter :dialect (skills/skills-for-profile profile ["construct_notebook_query"])))))))++(deftest ^:parallel build-skill-manifest-test+ (let [profile {:name :internal}+ manifest (skills/build-skill-manifest+ profile+ ["construct_notebook_query" "read_resource"]+ [])]+ (testing "catalog lists available skills with string ids"+ (let [ids (map :id (:catalog manifest))]+ (is (every? string? ids))+ (is (some #{"construct-notebook-query-core"} ids))+ (is (some #{"read-resource"} ids))))+ (testing "catalog entries are display-only (id/title/description), no body"+ (is (every? #(= #{:id :title :description} (set (keys %))) (:catalog manifest))))+ (testing "catalog is sorted by descending priority then id"+ ;; core has priority 60, the rest 50, operators 40 -> core first, operators last+ (is (= "construct-notebook-query-core" (:id (first (:catalog manifest))))))+ (testing "no always-on skills in this migration"+ (is (empty? (:always-on manifest))))))++(deftest ^:parallel build-skill-manifest-records-loadable-skill-ids-test+ (testing "building the manifest records the request's loadable skill ids"+ (binding [scope/*current-loadable-skill-ids* (atom #{})]+ (skills/build-skill-manifest {:name :internal} ["construct_notebook_query"] [])+ (is (contains? @scope/*current-loadable-skill-ids* :construct-notebook-query-core))+ (is (not (contains? @scope/*current-loadable-skill-ids* :read-resource))))))++(deftest ^:parallel dialect-preload-parts-test+ (testing "resolves a synthetic load_skill pair when the dialect is known"+ (let [parts (skills/dialect-preload-parts "postgresql")]+ (is (= 2 (count parts)))+ (is (= :tool-input (:type (first parts))))+ (is (= "load_skill" (:function (first parts))))+ (is (= ["sql-dialect-postgresql"] (get-in (first parts) [:arguments :ids])))+ (is (= :tool-output (:type (second parts))))+ (is (str/includes? (get-in (second parts) [:result :output]) "PostgreSQL"))+ (testing "the tool-input and tool-output share an id"+ (is (= (:id (first parts)) (:id (second parts)))))))+ (testing "resolves a raw driver name through driver/llm-sql-dialect-resource"+ ;; the FE sends the driver name (`postgres`), not the dialect file's name (`postgresql`)+ (let [parts (skills/dialect-preload-parts "postgres")]+ (is (= ["sql-dialect-postgresql"] (get-in (first parts) [:arguments :ids])))))+ (testing "a bare dialect name resolves from the registry without touching the driver system"+ (mt/with-dynamic-fn-redefs [skills/engine->dialect+ (fn [engine]+ (throw (ex-info "driver lookup should not run" {:engine engine})))]+ (is (= ["sql-dialect-postgresql"]+ (get-in (first (skills/dialect-preload-parts "postgresql")) [:arguments :ids])))))+ (testing "returns empty when no dialect is given"+ (is (= [] (skills/dialect-preload-parts nil))))+ (testing "returns empty when the dialect has no registered skill"+ (is (= [] (skills/dialect-preload-parts "nonexistent-engine")))))diff --git a/test/metabase/metabot/tools/field_stats_test.clj b/test/metabase/metabot/tools/field_stats_test.cljindex 37d2257f9bb..1314c6a280f 100644--- a/test/metabase/metabot/tools/field_stats_test.clj+++ b/test/metabase/metabot/tools/field_stats_test.clj@@ -27,14 +27,24 @@(is (thrown-with-msg? clojure.lang.ExceptionInfo #"You don't have permissions to do that."(metabot.tools.field-stats/field-values{:entity-type "table", :entity-id people-id, :field-id state-id, :limit 5}))))+ (testing "A table field detail surfaces its portable FK so the LLM can reference it directly."+ (mt/as-admin+ (is (=? {:structured-output {:portable_fk ["test-data (h2)" "PUBLIC" "PRODUCTS" "CATEGORY"]}}+ (metabot.tools.field-stats/field-values+ {:entity-type "table", :entity-id products-id, :field-id category-id, :limit 5})))))+ (testing "A field-id not on the table is an agent error, not a field-metadata result."+ (mt/as-admin+ (is (=? {:output #"Field -1 not found"}+ (metabot.tools.field-stats/field-values+ {:entity-type "table", :entity-id products-id, :field-id -1, :limit 5})))))(testing "Getting statistics and values for table fields works."(mt/as-admin(are [table-id field-id value-metadata]- (= {:structured-output {:result-type :field-metadata- :field_id field-id- :value_metadata value-metadata}}- (metabot.tools.field-stats/field-values- {:entity-type "table", :entity-id table-id, :field-id field-id, :limit 5}))+ (=? {:structured-output {:result-type :field-metadata+ :field_id field-id+ :value_metadata value-metadata}}+ (metabot.tools.field-stats/field-values+ {:entity-type "table", :entity-id table-id, :field-id field-id, :limit 5}))people-id birth-date-id {:statistics{:distinct-count 2308:percent-null 0.0diff --git a/test/metabase/metabot/tools/shared/llm_shape_test.clj b/test/metabase/metabot/tools/shared/llm_shape_test.cljindex eb251ce0d8f..dcca8531d2f 100644--- a/test/metabase/metabot/tools/shared/llm_shape_test.clj+++ b/test/metabase/metabot/tools/shared/llm_shape_test.clj@@ -25,9 +25,12 @@:database_type "INTEGER":description "The user identifier"}xml (llm-shape/field->xml field)]- ;; Python format: name="\"user_id\""+ ;; The column name is emitted bare (unquoted) so the LLM copies it verbatim into a+ ;; portable field reference; wrapping it in quotes made the model paste `"user_id"`+ ;; into MBQL field refs, which the resolver rejected.(is (str/includes? xml "id=\"f1\""))- (is (str/includes? xml "name=\"\\\"user_id\\\"\""))+ (is (str/includes? xml "name=\"user_id\""))+ (is (not (str/includes? xml "name=\"\\\"user_id\\\"\"")))(is (str/includes? xml "display_name=\"User ID\""))(is (str/includes? xml "type=\"integer\""))(is (str/includes? xml "database_type=\"INTEGER\""))@@ -37,7 +40,7 @@(let [field {:field_id "f1" :name "test"}xml (llm-shape/field->xml field)](is (str/includes? xml "id=\"f1\""))- (is (str/includes? xml "name=\"\\\"test\\\"\""))+ (is (str/includes? xml "name=\"test\""))(is (str/includes? xml "database_type=\"unknown\""))))(testing "FK columns expose `fk_target_fully_qualified_name` so the LLM can join via the target table";; Regression: earlier the `<field>` element rendered no FK hint, so a bare `customer_id`@@ -98,6 +101,61 @@(is (str/includes? xml "is_verified=\"false\""))(is (not (str/includes? xml "### Dimensions"))))))+(deftest ^:parallel format-metric-dimensions-table-test+ (testing "dimensions carry their source table + a copy-paste portable FK, disambiguating+ duplicate names across the metric's joined tables"+ (let [dims [{:name "campaign_id" :field_id 757 :type "number"+ :portable_fk ["Analytics" "customerio_enriched" "int_customerio_engagement_facts" "campaign_id"]}+ {:name "name" :field_id 722 :type "string"+ :portable_fk ["Analytics" "customerio_data" "campaign" "name"]+ :table_reference "Campaign"}+ {:name "campaign_id" :field_id 887 :type "number"+ :portable_fk ["Analytics" "customerio_data" "campaign" "id"]+ :table_reference "Campaign"}]+ table (llm-shape/format-metric-dimensions-table dims)]+ (testing "attribution columns are present"+ (is (str/includes? table "Source table"))+ (is (str/includes? table "Reference")))+ (testing "each dimension shows its owning table (with join label when joined in)"+ (is (str/includes? table "customerio_enriched.int_customerio_engagement_facts"))+ (is (str/includes? table "customerio_data.campaign (via Campaign)")))+ (testing "reference is the exact, unescaped portable FK to copy"+ (is (str/includes? table "[\"Analytics\",\"customerio_data\",\"campaign\",\"name\"]")))+ (testing "the two campaign_id dimensions are distinguishable by table + reference"+ (is (str/includes? table "[\"Analytics\",\"customerio_enriched\",\"int_customerio_engagement_facts\",\"campaign_id\"]"))+ (is (str/includes? table "[\"Analytics\",\"customerio_data\",\"campaign\",\"id\"]")))))+ (testing "a pipe in a value is escaped so it can't break the table row"+ (let [table (llm-shape/format-metric-dimensions-table+ [{:name "weird|name" :field_id 1 :type "string"+ :portable_fk ["Analytics" "public" "t" "weird|name"]}])]+ (is (str/includes? table "weird\\|name"))+ (testing "but the copyable reference remains valid JSON"+ (is (str/includes? table "\"weird\\u007cname\""))+ (is (not (str/includes? table "\"weird\\|name\"")))))))++(deftest ^:parallel field-metadata->xml-reference-test+ (testing "a drilled-into field detail surfaces the source table + portable FK when provided"+ (let [xml (llm-shape/field-metadata->xml+ {:field_id 722+ :value_metadata {:field_values ["Onboarding" "Welcome Series"]}+ :portable_fk ["Analytics" "customerio_data" "campaign" "name"]+ :table_reference "Campaign"})]+ (is (str/includes? xml "Source table: customerio_data.campaign (via Campaign)"))+ (is (str/includes? xml "[\"Analytics\",\"customerio_data\",\"campaign\",\"name\"]"))))+ (testing "without a portable FK the detail is unchanged (backward compatible)"+ (let [xml (llm-shape/field-metadata->xml+ {:field_id 1 :value_metadata {:field_values ["x"]}})]+ (is (not (str/includes? xml "Source table:")))+ (is (not (str/includes? xml "Reference (copy")))))+ (testing "XML structural chars in a portable-FK segment are escaped (the template uses |safe)"+ (let [xml (llm-shape/field-metadata->xml+ {:field_id 1+ :value_metadata {:field_values ["x"]}+ :portable_fk ["DB" "public" "t" "a<&>b"]})]+ (is (str/includes? xml "a<&>b"))+ (testing "but the JSON's quotes stay readable"+ (is (str/includes? xml "\"a<&>b\""))))))+(deftest ^:parallel measure->xml-test(testing "formats measure with all attributes"(let [;; The new contract: `:definition` is a portable aggregation clause vector,@@ -624,7 +682,10 @@(testing "handles empty field values"(let [metadata {:field_values []}xml (llm-shape/field-values-metadata->xml metadata)]- (is (str/includes? xml "This field hasn't been sampled yet")))))+ (is (str/includes? xml "This field hasn't been sampled yet"))))+ (testing "a pipe in a sample value is escaped so it can't break the table"+ (let [xml (llm-shape/field-values-metadata->xml {:field_values ["a|b"]})]+ (is (str/includes? xml "a\\|b")))))(deftest ^:parallel field-metadata->xml-test(testing "formats field metadata"diff --git a/test/metabase/metabot/tools/skills_test.clj b/test/metabase/metabot/tools/skills_test.cljnew file mode 100644index 00000000000..b5d2f7816c5--- /dev/null+++ b/test/metabase/metabot/tools/skills_test.clj@@ -0,0 +1,33 @@+(ns metabase.metabot.tools.skills-test+ (:require+ [clojure.string :as str]+ [clojure.test :refer [deftest is testing]]+ [metabase.metabot.tools.skills :as tools.skills]))++(set! *warn-on-reflection* true)++(deftest ^:parallel load-skill-tool-metadata-test+ (testing "the tool var carries the metadata profiles require"+ (let [m (meta #'tools.skills/load-skill-tool)]+ (is (= "load_skill" (:tool-name m)))+ (is (some? (:schema m))))))++(deftest ^:parallel load-skill-returns-body-test+ (testing "loading a known skill returns its body wrapped in a <skill> tag"+ (let [out (:output (tools.skills/load-skill-tool {:ids ["construct-notebook-query-operators"]}))]+ (is (str/includes? out "<skill id=\"construct-notebook-query-operators\">"))+ (is (str/includes? out "</skill>"))+ (is (str/includes? out "Aggregations")))))++(deftest ^:parallel load-skill-multiple-test+ (testing "multiple ids are concatenated"+ (let [out (:output (tools.skills/load-skill-tool+ {:ids ["construct-notebook-query-core" "read-resource"]}))]+ (is (str/includes? out "<skill id=\"construct-notebook-query-core\">"))+ (is (str/includes? out "<skill id=\"read-resource\">")))))++(deftest ^:parallel load-skill-unknown-test+ (testing "an unknown id yields an inline message, not an exception"+ (let [out (:output (tools.skills/load-skill-tool {:ids ["does-not-exist"]}))]+ (is (str/includes? out "Unknown skill"))+ (is (str/includes? out "does-not-exist")))))