@rasmusengelbrecht/pi-semantic-query 0.1.1 → 0.1.3

package/README.md

@@ -40,7 +40,7 @@ pi -e /absolute/path/to/pi-semantic-query
 
 ## Tools
 
-The package registers these pi tools:
+The package registers a bundled `semantic-query` skill plus these pi tools:
 
 - `semantic_metrics` — list metrics with discovery metadata
 - `semantic_search_metrics` — search metrics by id, name, description, synonyms, and teams
@@ -48,6 +48,8 @@ The package registers these pi tools:
 - `semantic_validate` — validate a semantic model
 - `semantic_compile` — compile a metric request to SQL
 
+The skill teaches pi the default workflow: search before guessing metric IDs, describe ambiguous metrics, validate model changes, prefer `period`, and never present compiled SQL as executed results.
+
 All tools shell out to the local `semantic` CLI. By default they look for one of:
 
 - `semantic.yml`
@@ -83,6 +85,23 @@ Example request shape for `semantic_compile`:
 }
 ```
 
+For target series, pass `targetTable`. Use `targetProject` and `targetSchema` when the warehouse needs a qualified target relation but you want to keep the table name generic:
+
+```json
+{
+  "metricId": "revenue",
+  "period": "current year",
+  "dialect": "bigquery",
+  "targetProject": "warehouse-project",
+  "targetSchema": "analytics",
+  "targetTable": "metric_targets",
+  "request": {
+    "timeGrain": "monthly",
+    "targetSeries": "budget_current"
+  }
+}
+```
+
 ## Safety boundary
 
 This package is compile-only by design. `semantic_compile` returns SQL; it does not run the SQL. Query execution touches credentials, cost, and data access, so execution should stay in the caller's existing warehouse tooling or a separate explicitly configured integration.

package/extensions/semantic-query.ts

@@ -65,7 +65,9 @@ const CompileParams = Type.Intersect([
       Type.Literal("json"),
       Type.Literal("explain"),
     ], { description: "Output format. Defaults to sql." })),
-    targetTable: Type.Optional(Type.String({ description: "Optional target table for targetSeries requests." })),
+    targetTable: Type.Optional(Type.String({ description: "Optional target table for targetSeries requests. May be fully qualified, or bare when targetProject/targetSchema are supplied." })),
+    targetProject: Type.Optional(Type.String({ description: "Optional target table project/catalog." })),
+    targetSchema: Type.Optional(Type.String({ description: "Optional target table schema/dataset." })),
     targetMetricColumn: Type.Optional(Type.String({ description: "Target metric id column. Defaults to metric_id." })),
     targetSeriesColumn: Type.Optional(Type.String({ description: "Target series column. Defaults to target_series." })),
     targetTimeColumn: Type.Optional(Type.String({ description: "Target time column. Defaults to metric_time." })),
@@ -249,6 +251,8 @@ export default function semanticQueryExtension(pi: ExtensionAPI) {
         if (params.dialect) args.push("--dialect", params.dialect);
         if (params.format) args.push("--format", params.format);
         if (params.targetTable) args.push("--target-table", params.targetTable);
+        if (params.targetProject) args.push("--target-project", params.targetProject);
+        if (params.targetSchema) args.push("--target-schema", params.targetSchema);
         if (params.targetMetricColumn) args.push("--target-metric-column", params.targetMetricColumn);
         if (params.targetSeriesColumn) args.push("--target-series-column", params.targetSeriesColumn);
         if (params.targetTimeColumn) args.push("--target-time-column", params.targetTimeColumn);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasmusengelbrecht/pi-semantic-query",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Compile and inspect governed semantic metrics from pi coding agent",
   "keywords": [
     "pi-package",
@@ -25,10 +25,14 @@
   "pi": {
     "extensions": [
       "./extensions"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "files": [
     "extensions",
+    "skills",
     "README.md",
     "package.json"
   ],

package/skills/semantic-query/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: semantic-query
+description: Compile and inspect governed semantic metrics with semantic-query-compiler from pi. Use when the user asks for semantic metrics, metric discovery, governed SQL compilation, semantic model validation, or SQL for a metric request.
+---
+
+# Semantic Query
+
+Use the `semantic_*` tools from this package to discover governed metrics and compile inspectable SQL. These tools do **not** execute warehouse queries.
+
+## Default workflow
+
+1. Start with `semantic_search_metrics` when the user describes a metric in business language.
+2. Use `semantic_metrics` when they ask what metrics exist or when search is too narrow.
+3. Use `semantic_describe` before compiling if the metric semantics, grain, filters, dimensions, teams, or formula are unclear.
+4. Use `semantic_validate` after model edits, before trusting a new model, or when compile errors suggest the model may be invalid.
+5. Use `semantic_compile` to generate SQL for the chosen metric and request.
+6. Say clearly that compiled SQL is not executed results.
+
+## Request guidance
+
+Prefer period-based requests for CLI/agent workflows:
+
+```json
+{
+  "metricId": "revenue",
+  "period": "last 12 complete months",
+  "dialect": "bigquery",
+  "request": {
+    "timeGrain": "monthly",
+    "breakdownDimensionIds": ["country"]
+  }
+}
+```
+
+For target series, pass `targetTable`. If the warehouse needs qualified table names, prefer generic relation parts instead of hard-coded company presets:
+
+```json
+{
+  "metricId": "revenue",
+  "period": "current year",
+  "dialect": "bigquery",
+  "targetProject": "warehouse-project",
+  "targetSchema": "analytics",
+  "targetTable": "metric_targets",
+  "request": {
+    "timeGrain": "monthly",
+    "targetSeries": "budget_current"
+  }
+}
+```
+
+Use raw `fromDate` / `toDate` only when the user needs exact fixed boundaries or provides a request JSON shape that already has them.
+
+## Safety boundary
+
+`semantic_compile` returns SQL only. Do not claim row counts, metric values, parity, or dashboard results unless a separate warehouse/query tool actually executed the SQL.
+
+If the user asks to run the query, use their normal warehouse tooling or ask which execution environment to use. This package intentionally does not handle credentials, warehouse cost, or data access.
+
+## Model discovery
+
+By default, tools look for common model filenames in the current project (`semantic.yml`, `model.yml`, `semantic_layer.yml`, and `.yaml` variants). Pass `model` explicitly when the model lives elsewhere.