Metadata-Version: 2.4
Name: logictrace
Version: 0.1.0
Summary: Trace a dbt column through medallion layers with LLM-generated explanations
Project-URL: Homepage, https://github.com/chridgn/logictrace
Project-URL: Repository, https://github.com/chridgn/logictrace
Project-URL: Issues, https://github.com/chridgn/logictrace/issues
Author-email: Christian Quebral <christianquebral@gmail.com>
License: MIT
Keywords: data engineering,dbt,lineage,llm,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.28
Requires-Dist: rich>=13.0
Requires-Dist: sqlglot>=25.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://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

```bash
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):

```bash
logictrace auth
```

Or set it as an environment variable:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

## Usage

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

```bash
logictrace trace --table fct_revenue_monthly --column revenue
```

Point to a manifest in a different location:

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

### Options

| Flag | Short | Description |
|---|---|---|
| `--table` | `-t` | dbt model name to trace from |
| `--column` | `-c` | Column name to trace |
| `--manifest` | `-m` | Path to `manifest.json` (default: `./target/manifest.json`) |

## 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

```bash
pip install -e ".[dev]"
pytest
```
