@rasmusengelbrecht/pi-semantic-query 0.1.2 → 0.1.4

package/README.md

@@ -8,14 +8,14 @@ It gives pi tools to discover metrics, inspect definitions, validate a model, an
 
 - pi coding agent
 - Node/npm for installing the pi package
-- `semantic-query-compiler` installed so the `semantic` CLI is on `PATH`
+- `semantic-query-compiler >= 0.1.2` installed so the `semantic` CLI is on `PATH`
 - a semantic model in the project, usually `semantic.yml`
 
 Install the Python compiler first:
 
 ```bash
-uv tool install 'semantic-query-compiler @ git+https://github.com/rasmusengelbrecht/semantic-query-compiler.git'
-semantic --help
+uv tool install 'semantic-query-compiler>=0.1.2'
+semantic --version
 ```
 
 ## Install in pi
@@ -50,7 +50,13 @@ The package registers a bundled `semantic-query` skill plus these pi tools:
 
 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:
+All tools shell out to the local `semantic` CLI. If target relation flags fail with `unrecognized arguments`, upgrade the Python CLI:
+
+```bash
+uv tool install 'semantic-query-compiler>=0.1.2' --force
+```
+
+By default tools look for one of:
 
 - `semantic.yml`
 - `semantic.yaml`
@@ -85,6 +91,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." })),
@@ -114,6 +116,13 @@ function runSemantic(
       const result = { stdout, stderr, command: [command, ...args] };
       if (error) {
         const message = stderr.trim() || error.message;
+        if (message.includes("unrecognized arguments") && (message.includes("--target-project") || message.includes("--target-schema"))) {
+          reject(new Error(
+            `${command} failed because targetProject/targetSchema require semantic-query-compiler >= 0.1.1. `
+              + `Upgrade the Python CLI with: uv tool install semantic-query-compiler>=0.1.2 --force. Original error: ${message}`,
+          ));
+          return;
+        }
         reject(new Error(`${command} failed: ${message}`));
         return;
       }
@@ -249,6 +258,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.2",
+  "version": "0.1.4",
   "description": "Compile and inspect governed semantic metrics from pi coding agent",
   "keywords": [
     "pi-package",

package/skills/semantic-query/SKILL.md

@@ -7,6 +7,8 @@ description: Compile and inspect governed semantic metrics with semantic-query-c
 
 Use the `semantic_*` tools from this package to discover governed metrics and compile inspectable SQL. These tools do **not** execute warehouse queries.
 
+This package shells out to the local `semantic` CLI and expects `semantic-query-compiler >= 0.1.2`. If a tool reports `unrecognized arguments` for target relation flags, tell the user to upgrade with `uv tool install 'semantic-query-compiler>=0.1.2' --force` and verify `semantic --version`.
+
 ## Default workflow
 
 1. Start with `semantic_search_metrics` when the user describes a metric in business language.
@@ -32,6 +34,23 @@ Prefer period-based requests for CLI/agent workflows:
 }
 ```
 
+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