logictrace

Trace a dbt column from a final mart back through your medallion layers and get a plain-English explanation of every transformation along the way.

Tracing: fct_revenue_monthly.revenue
────────────────────────────────────────────────────────────────────────────────

Step 1 · raw_transactions [source]
  Field origin: sale_price
  No transformations at this layer.

Step 2 · stg_transactions [staging]
  → Cast: sale_price → transaction_amount
  → Renamed: sale_price → transaction_amount
  ┌─ models/staging/stg_transactions.sql:3
  │  CAST(sale_price AS DOUBLE) AS transaction_amount

Step 3 · int_transactions_cleaned [intermediate]
  → Filtered: WHERE transaction_amount > 1000
  ┌─ models/intermediate/int_transactions_cleaned.sql:3
  │  transaction_amount

Step 4 · fct_revenue_monthly [marts]
  → Aggregated: transaction_amount → revenue
  → Renamed: transaction_amount → revenue
  ┌─ models/marts/fct_revenue_monthly.sql:3
  │  SUM(transaction_amount) AS revenue

────────────────────────────────────────────────────────────────────────────────

Summary
revenue is the monthly sum of sale_price (cast to DOUBLE) for transactions
above $1000. The filter is applied in int_transactions_cleaned before the
SUM aggregation occurs in the final mart.

Requirements

• Python 3.11+
• A dbt project with a compiled manifest.json (dbt compile or dbt run)
• An Anthropic API key — get one from console.anthropic.com → API Keys

  Note: this is separate from the console login used by Claude Code. Even if you're already signed in to the Anthropic Console, you need to generate an API key explicitly.

Installation

git clone https://github.com/chridgn/logictrace
cd logictrace
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Setup

Save your Anthropic API key (one-time):

logictrace auth

Or set it as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Usage

Run from the root of your dbt project (where target/manifest.json lives):

logictrace trace --table fct_revenue_monthly --column revenue

Point to a manifest in a different location:

logictrace trace --table fct_revenue_monthly --column revenue --manifest ./target/manifest.json

Options

How it works

1. Reads manifest.json to build a column-level lineage graph
2. Walks the dependency chain from the final model back to the source, following the column at each hop
3. Classifies each transformation (CAST, RENAME, FILTER, AGGREGATE, EXPRESSION)
4. Sends only the relevant SQL snippets to claude-haiku-4-5 - not full model SQL
5. Streams a plain-English explanation of the full transformation chain

Development

pip install -e ".[dev]"
pytest