Metadata-Version: 2.5
Name: prumi-adapter-dbt
Version: 0.1.0
Summary: Prumi adapter for dbt semantic models: MetricFlow compiles, Prumi executes
Project-URL: Repository, https://github.com/prumihq/prumi
Project-URL: Issues, https://github.com/prumihq/prumi/issues
Project-URL: Changelog, https://github.com/prumihq/prumi/blob/main/CHANGELOG.md
Author: Denner Rodrigues Campelo
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: dbt,metricflow,metrics,prumi,semantic-layer
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.12
Requires-Dist: metricflow==0.213.0
Requires-Dist: prumi<0.2,>=0.1.0
Provides-Extra: duckdb
Requires-Dist: duckdb; extra == 'duckdb'
Description-Content-Type: text/markdown

# prumi-adapter-dbt

Prumi adapter for dbt semantic models. MetricFlow compiles a semantic query into SQL for the warehouse; Prumi executes that SQL over its own connection; the warehouse enforces access rules.

Install it with Prumi: `uv tool install "prumi[dbt]"` installs both, with DuckDB; the dbt-style `pip install prumi "prumi-adapter-dbt[duckdb]"` gives the same packages. Import name: `prumi_adapter_dbt`.

## Preparing your dbt project

### What Prumi reads

Prumi reads one file: `target/semantic_manifest.json`, which `dbt parse` (or any dbt command that parses the project) writes. It doesn't run dbt and doesn't need your dbt project folder.

For Prumi to show anything, the project needs:

- `semantic_models:` with entities, dimensions and measures, and `metrics:` built on them ([dbt docs](https://docs.getdbt.com/docs/build/semantic-models));
- a time spine model, which MetricFlow requires for time grains.

Prumi shows your metrics as they are: names, labels, descriptions, types and valid dimensions all come from the manifest. It never copies or changes your definitions.

### Display formats: add `config.meta.prumi` (recommended)

dbt's semantic layer describes how a metric is **computed**, but not how it should be **displayed**: it has no field saying that `revenue` is money in USD, or that `gross_margin_pct` is a fraction to show as a percentage. Without that, every dashboard guesses, and the same metric ends up as `0.25` on one page and `25%` on another, or with currencies mixed on one chart.

Prumi takes formats from the metric definition so they're the same everywhere. We suggest adding them under `config.meta.prumi` on each metric:

```yaml
metrics:
  - name: revenue
    label: Revenue
    description: Net sales after discounts, in USD.
    type: simple
    type_params:
      measure: revenue_amount
    config:
      meta:
        prumi:
          format: currency   # number | integer | percent | currency
          unit: USD          # ISO 4217 code for currency; free text otherwise ("orders")
          decimals: 2        # optional
        owner: sales-analytics
```

| Key | Values | Meaning |
|---|---|---|
| `format` | `number`, `integer`, `percent`, `currency` | `percent` means the value is a fraction: 0.25 shows as 25% |
| `unit` | ISO 4217 code for `currency` (`USD`, `EUR`, `BRL`); any text otherwise | Required for `currency`. Prumi warns when one block mixes units |
| `decimals` | 0–20 | Optional. Defaults: up to 2 for `number`, 0 for `integer`, 1 for `percent`, and the currency's usual digits for `currency` (2 for USD, 0 for JPY) |

- **It's optional.** A metric without `meta.prumi` still works: it's shown as a plain number, and the validator warns that no format is declared (`R10.no_format`). An invalid entry is treated the same way.
- **Why under a `prumi` key:** `meta` is dbt's free-form dictionary for other tools, and dbt itself ignores it. Several tools read keys like `meta.format` with their own meanings, so Prumi keeps its settings in its own namespace to avoid clashes.
- **Owner:** Prumi shows `config.meta.owner` (a common convention, outside the `prumi` key) as the metric's owner when it's a string.

The demo project in [`examples/demo-dbt-project`](https://github.com/prumihq/prumi/tree/main/examples/demo-dbt-project) uses this convention on every metric except `discount_rate`, which is left without a format on purpose.

### Dimension names

Prumi uses MetricFlow's names for dimensions (`customer__region`: the `region` of the `customer` entity). When MetricFlow can reach the same attribute through several join paths, Prumi shows only the shortest one for each metric, so agents don't see near-duplicates.
