Metadata-Version: 2.4
Name: catalogkit-lineage
Version: 0.1.3
Summary: Build project-level SQL lineage artifacts from dbt manifests or SQL folders.
Author: ClearMetric Labs
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Clearmetric-Labs/CatalogKit
Project-URL: Source, https://github.com/Clearmetric-Labs/CatalogKit
Project-URL: Issues, https://github.com/Clearmetric-Labs/CatalogKit/issues
Keywords: lineage,dbt,sql,catalog,sqlglot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: catalogkit-core>=0.1.2
Requires-Dist: sqlglot>=25.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2.2; extra == "release"
Requires-Dist: twine>=5.1.1; extra == "release"

# catalogkit-lineage

`catalogkit-lineage` builds project-level SQL lineage from either:

- a dbt `manifest.json` with compiled SQL available, or
- a folder of `.sql` files

It is a headless static-analysis tool:

- input: one dbt manifest path or one SQL folder
- output: a deterministic `LineageMap` plus the shared `CatalogArtifact`
- no warehouse credentials
- no dbt execution
- no AI key

## Install

```bash
python -m pip install catalogkit-lineage
```

## Imports

```python
from catalogkit.lineage import (
    build_catalog_artifact,
    build_lineage_map,
    build_openlineage_export,
    render_json,
    render_text,
    trace_downstream,
    trace_upstream,
)
```

For local development:

```bash
python -m pip install -e ../catalogkit-core
python -m pip install -e ".[dev,release]"
```

## Quickstart

Manifest input:

```bash
catalogkit-lineage --dialect postgres ./examples/jaffle_shop/manifest.json
catalogkit-lineage --dialect postgres --format json ./examples/jaffle_shop/manifest.json
catalogkit-lineage --dialect postgres --format openlineage ./examples/jaffle_shop/manifest.json
```

Folder input:

```bash
catalogkit-lineage --dialect postgres ./examples/sql_folder
catalogkit-lineage --dialect postgres --upstream customers_report.customer_lifetime_value ./examples/sql_folder
catalogkit-lineage --dialect postgres --downstream orders_base.amount ./examples/sql_folder
```

## Output Contract

`catalogkit-lineage` exposes a module-specific `LineageMap` with:

- `version`
- `summary`
- `nodes`
- `edges`
- `warnings`

For CatalogKit composition, the package also exposes a shared
`CatalogArtifact` builder backed by `catalogkit-core`.

The shared core artifact contains:

- `version`
- `nodes`
- `edges`
- `warnings`

## Contract Docs

- [`../catalogkit-core/docs/contract.md`](../catalogkit-core/docs/contract.md)
- [`docs/limitations.md`](docs/limitations.md)
