# pi-semantic-query

Pi extension for working with governed semantic metrics from `semantic-query-compiler`.

It gives pi tools to discover metrics, inspect definitions, validate a model, and compile metric requests to SQL. It does **not** execute warehouse queries.

## Requirements

- pi coding agent
- Node/npm for installing the pi package
- `semantic-query-compiler >= 0.1.4` 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>=0.1.4'
semantic --version
```

## Install in pi

From npm, after publishing:

```bash
pi install npm:@rasmusengelbrecht/pi-semantic-query
```

For local development:

```bash
pi install /absolute/path/to/pi-semantic-query
```

Or try without installing:

```bash
pi -e /absolute/path/to/pi-semantic-query
```

## 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
- `semantic_describe` — describe one metric definition
- `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. If target relation flags fail with `unrecognized arguments`, upgrade the Python CLI:

```bash
uv tool install 'semantic-query-compiler>=0.1.4' --force
```

By default tools look for one of:

- `semantic.yml`
- `semantic.yaml`
- `model.yml`
- `model.yaml`
- `semantic_layer.yml`
- `semantic_layer.yaml`

Pass `model` explicitly when your file lives somewhere else.

## Example prompt

> List available semantic metrics in this repo, find the revenue metric, then compile revenue by country for the last 12 complete months.

The agent should:

1. call `semantic_search_metrics`
2. call `semantic_describe` for the chosen metric
3. call `semantic_compile` with an inline request shape and `period`

Example request shape for `semantic_compile`:

```json
{
  "metricId": "revenue",
  "period": "last 12 complete months",
  "dialect": "bigquery",
  "request": {
    "timeGrain": "monthly",
    "breakdownDimensionIds": ["country"]
  }
}
```

For target series, pass `targetTable`. `semantic-query-compiler >= 0.1.4` accepts both core target column conventions (`metric_id`/`target_series`/`metric_time`/`target_value` and `metric`/`series`/`time`/`value`) on BigQuery. 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.

## Publishing

```bash
npm pack --dry-run
npm publish --access public
```

The `pi-package` keyword makes the package discoverable by pi package indexes.