@rasmusengelbrecht/pi-semantic-query 0.1.0 → 0.1.2

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`

package/package.json

@@ -1,23 +1,38 @@
 {
   "name": "@rasmusengelbrecht/pi-semantic-query",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Compile and inspect governed semantic metrics from pi coding agent",
   "keywords": [
     "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
     "semantic-layer",
     "analytics",
     "metrics",
     "sql"
   ],
   "license": "MIT",
+  "author": "Rasmus Engelbrecht",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rasmusengelbrecht/pi-semantic-query.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rasmusengelbrecht/pi-semantic-query/issues"
+  },
+  "homepage": "https://github.com/rasmusengelbrecht/pi-semantic-query#readme",
   "type": "module",
   "pi": {
     "extensions": [
       "./extensions"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "files": [
     "extensions",
+    "skills",
     "README.md",
     "package.json"
   ],

package/skills/semantic-query/SKILL.md

@@ -0,0 +1,45 @@
+---
+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"]
+  }
+}
+```
+
+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.