Metadata-Version: 2.3
Name: dbt-osmosis
Version: 1.5.0
Summary: A dbt utility for managing YAML to make developing with dbt more delightful.
Author-email: z3z1ma <butler.alex2010@gmail.com>
License: Apache-2.0
Keywords: dbt,osmosis,yaml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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 :: Software Development :: Build Tools
Requires-Python: <3.14,>=3.10
Requires-Dist: agate<2,>=1.9
Requires-Dist: click<9,>7
Requires-Dist: dbt-common<2,>=1
Requires-Dist: dbt-core-interface>=1.1.7
Requires-Dist: dbt-core>=1.8
Requires-Dist: packaging<26,>=24
Requires-Dist: pluggy<2,>=1.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: rich>=10
Requires-Dist: ruamel-yaml<0.20,>=0.17
Requires-Dist: sqlglot<31,>=28
Requires-Dist: typing-extensions<5,>=4.12
Provides-Extra: azure
Requires-Dist: azure-identity<2,>=1.19; extra == 'azure'
Provides-Extra: dev
Requires-Dist: basedpyright<1.40.0,>=1.38.4; extra == 'dev'
Requires-Dist: dbt-duckdb<2,>=1; extra == 'dev'
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: mutmut; extra == 'dev'
Requires-Dist: pre-commit<5,>3.0.0; extra == 'dev'
Requires-Dist: pytest-cov~=6.0; extra == 'dev'
Requires-Dist: pytest<9.2.0,>=8.3.4; extra == 'dev'
Requires-Dist: ruff==0.15.17; extra == 'dev'
Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
Provides-Extra: duckdb
Requires-Dist: dbt-duckdb<2,>=1; extra == 'duckdb'
Provides-Extra: openai
Requires-Dist: openai<2.42.0,>=1.58.1; extra == 'openai'
Provides-Extra: proxy
Requires-Dist: mysql-mimic>=2.5.7; extra == 'proxy'
Provides-Extra: workbench
Requires-Dist: feedparser~=6.0.12; extra == 'workbench'
Requires-Dist: ipython<9,>=8; extra == 'workbench'
Requires-Dist: pandas<3,>=2.2; extra == 'workbench'
Requires-Dist: setuptools<81,>=70; extra == 'workbench'
Requires-Dist: streamlit-ace~=0.1.1; extra == 'workbench'
Requires-Dist: streamlit-elements-fluence>=0.1.4; extra == 'workbench'
Requires-Dist: streamlit<2.0,>=1.45.0; extra == 'workbench'
Requires-Dist: ydata-profiling>=4.17.0; extra == 'workbench'
Description-Content-Type: text/markdown

# dbt-osmosis

![PyPI](https://img.shields.io/pypi/v/dbt-osmosis)
[![Downloads](https://static.pepy.tech/badge/dbt-osmosis)](https://pepy.tech/project/dbt-osmosis)
![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)
[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://dbt-osmosis-playground.streamlit.app/)

`dbt-osmosis` is a Python CLI and package for dbt development workflows.

It centers on four primary surfaces:

- schema YAML management (`yaml organize`, `yaml document`, `yaml refactor`)
- column-level documentation inheritance across dbt lineage
- ad-hoc SQL compile/run helpers
- an optional Streamlit workbench for interactive dbt SQL development

The repository also ships additional command families for generation, natural-language helpers, schema diffing, migration planning, validation, documentation analysis, SQL linting, and test suggestions.

The Docusaurus site is the canonical reference for the current CLI, configuration model, support matrix, and workflow guides:

- Docs site: https://z3z1ma.github.io/dbt-osmosis/
- CLI reference: https://z3z1ma.github.io/dbt-osmosis/docs/reference/cli
- Configuration guide: https://z3z1ma.github.io/dbt-osmosis/docs/tutorial-yaml/configuration
- Migration guide: https://z3z1ma.github.io/dbt-osmosis/docs/migrating

[![dbt-osmosis](/screenshots/docs_site.png)](https://z3z1ma.github.io/dbt-osmosis/)

## Supported runtime

`dbt-osmosis` currently targets:

- Python 3.10-3.13
- dbt Core 1.8+ package resolution
- a dbt adapter version compatible with the dbt Core runtime in that environment

Audited blocking support covers dbt Core 1.8.x through 1.11.x in CI. The package metadata intentionally remains `dbt-core>=1.8` without an upper bound so installers can resolve newer dbt releases. Future dbt Core minors are canary-only until explicitly audited; scheduled/manual canary CI uses unpinned latest `dbt-core` and `dbt-duckdb` to make upstream breakage visible without redefining audited support. Install a dbt adapter version that is compatible with the dbt Core runtime in your environment; adapter compatibility is owned by the adapter and dbt Core pairing, not by dbt-osmosis extras.

Optional extras:

- `dbt-osmosis[workbench]` for the Streamlit workbench and related UI dependencies
- `dbt-osmosis[duckdb]` for the DuckDB adapter used by the demo project and local fixture workflows
- `dbt-osmosis[openai]` for LLM-assisted synthesis and natural-language generation features
- `dbt-osmosis[azure]` for Azure AD authentication used with Azure OpenAI
- `dbt-osmosis[proxy]` only installs dependencies for the experimental opt-in SQL proxy runtime; it does not expand the supported product surface, start a proxy server, configure authentication, TLS, or listen/bind settings, or make comment middleware durable. The proxy module entrypoint is a local-only experiment with `mysql-mimic` defaults, not a hardened user-facing server; do not expose it to untrusted networks. The proxy comment middleware is in-memory only, and `ticket:c10proxy25` owns proxy support semantics.

## Install

With `uv`:

```bash
uv tool install --with="dbt-<adapter>" dbt-osmosis
```

With `pip`:

```bash
pip install "dbt-osmosis" "dbt-<adapter>"
```

Replace `<adapter>` with your dbt adapter package, for example `duckdb`, `snowflake`, `bigquery`, `postgres`, or `redshift`.

## Quick start

1. Configure YAML routing in `dbt_project.yml`:

```yaml title="dbt_project.yml"
models:
  your_project_name:
    +dbt-osmosis: "_{model}.yml"
```

2. Optionally set per-folder behavior with `+dbt-osmosis-options` and a repo-level YAML formatter in `dbt-osmosis.yml`:

```yaml title="dbt-osmosis.yml"
formatter: "prettier --write"
```

3. Preview changes safely:

```bash
dbt-osmosis yaml refactor --dry-run --check
```

4. Apply the update once the diff looks right:

```bash
dbt-osmosis yaml refactor --auto-apply
```

## CLI surface

Top-level commands currently exposed by `dbt-osmosis --help`:

- `yaml` — manage schema YAML files and documentation inheritance
- `sql` — compile or run ad-hoc SQL in dbt context
- `workbench` — launch the Streamlit workbench
- `generate` — generate sources, staging models, models, and SQL
- `nl` — natural-language query/model helpers
- `test` — suggest dbt tests
- `test-llm` — validate LLM client configuration
- `diff` — report schema drift between YAML and the database
- `migration` — plan database migration SQL from schema diffs
- `validate` — dry-run selected models without materializing them
- `analyze` — inspect documentation coverage, gaps, and style
- `lint` — lint SQL strings, models, or a whole project

For command-by-command flags and examples, use the docs-site CLI reference rather than relying on this landing page.

## Developer tooling

Local development in this repository is built around `uv`, `task`, and Ruff.

Common workflows:

```bash
task format
task lint
task test
```

Notes:

- Ruff is the active formatter, linter, and import sorter.
- `task` is not just verification; the default task formats, lints, runs tests, and then ensures the dev environment is synced.
- Repository test fixtures are DuckDB-only today; contributor examples use `demo_duckdb`, and targeted core tests may need `uv run dbt parse --project-dir demo_duckdb --profiles-dir demo_duckdb -t test` to refresh `demo_duckdb/target/manifest.json`.
- Docs-site commands use the Node toolchain under `docs/`:

```bash
npm --prefix docs run start
npm --prefix docs run build
npm --prefix docs run serve
```

## Workbench

The optional workbench is a Streamlit app for interactive dbt SQL development.

Install the extra and launch it with:

```bash
pip install "dbt-osmosis[workbench]" "dbt-<adapter>"
dbt-osmosis workbench
```

The hosted demo is linked from the badge at the top of this README.

## Pre-commit hook

You can run `dbt-osmosis yaml refactor -C` as a pre-commit hook:

```yaml title=".pre-commit-config.yaml"
repos:
  - repo: https://github.com/z3z1ma/dbt-osmosis
    rev: v1.3.0
    hooks:
      - id: dbt-osmosis
        files: ^models/
        args: [--target=prod]
        additional_dependencies: [dbt-<adapter>]
```

That hook keeps schema YAML changes visible in the commit that introduced them.
