Metadata-Version: 2.4
Name: exmergo-dex-core
Version: 0.1.2
Summary: Analytics engineering for Claude Code and any agent: data warehouse exploration, dbt transformation and semantic modeling, and schema-drift maintenance on dbt.
Project-URL: Homepage, https://www.exmergo.com/dex
Project-URL: Repository, https://github.com/exmergo/dex
Author-email: "Exmergo, Inc." <support@exmergo.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,analytics-engineering,claude-code,data-engineering,dbt,duckdb,semantic-layer,text-to-sql
Requires-Python: >=3.11
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Provides-Extra: all
Requires-Dist: databricks-sdk>=0.30; extra == 'all'
Requires-Dist: databricks-sql-connector>=3; extra == 'all'
Requires-Dist: dbt-bigquery>=1.9; extra == 'all'
Requires-Dist: dbt-duckdb>=1.9; extra == 'all'
Requires-Dist: duckdb>=1; extra == 'all'
Requires-Dist: google-cloud-bigquery>=3; extra == 'all'
Requires-Dist: psycopg[binary]>=3; extra == 'all'
Requires-Dist: snowflake-connector-python>=3; extra == 'all'
Requires-Dist: sqlglot>=25; extra == 'all'
Provides-Extra: bigquery
Requires-Dist: dbt-bigquery>=1.9; extra == 'bigquery'
Requires-Dist: google-cloud-bigquery>=3; extra == 'bigquery'
Requires-Dist: sqlglot>=25; extra == 'bigquery'
Provides-Extra: databricks
Requires-Dist: databricks-sdk>=0.30; extra == 'databricks'
Requires-Dist: databricks-sql-connector>=3; extra == 'databricks'
Requires-Dist: sqlglot>=25; extra == 'databricks'
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff==0.15.19; extra == 'dev'
Provides-Extra: duckdb
Requires-Dist: dbt-duckdb>=1.9; extra == 'duckdb'
Requires-Dist: duckdb>=1; extra == 'duckdb'
Requires-Dist: sqlglot>=25; extra == 'duckdb'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3; extra == 'postgres'
Requires-Dist: sqlglot>=25; extra == 'postgres'
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python>=3; extra == 'snowflake'
Requires-Dist: sqlglot>=25; extra == 'snowflake'
Description-Content-Type: text/markdown

# exmergo-dex-core

The portable, Apache-2.0 analytics-engineering engine behind
[dex](https://github.com/exmergo/dex). All non-trivial logic lives here; the
Claude Code skills and the cross-agent `AGENTS.md` are thin wrappers that drive it
through one stable command contract.

dex is the agent-native analytics engineering toolkit: explore an unfamiliar
warehouse, transform raw data into clean dbt models and a semantic layer on top,
and maintain all of it as the data underneath changes. Read-only against your data;
every change is a reviewable diff.

## Install

```
pip install "exmergo-dex-core[duckdb]"
```

Connector client libraries live behind extras, so the zero-credential DuckDB
on-ramp installs only `duckdb` and `sqlglot`:

```
exmergo-dex-core[duckdb]       # the on-ramp and the eval/benchmark engine
exmergo-dex-core[snowflake]
exmergo-dex-core[bigquery]
exmergo-dex-core[databricks]
exmergo-dex-core[postgres]
exmergo-dex-core[all]          # every connector at once
```

## The command contract

Every subcommand prints exactly one sanitized JSON envelope to stdout and nothing
else; nothing reaches agent context except through that envelope. Credentials
never cross it, and data values cross only from profiled, PII-cleared columns,
bounded and capped by the query firewall. State persists in `.dex/`, so
subcommands are stateless and the agent orchestrates multi-step flows.

```
dex connect test --path data.duckdb
```

See [`references/command-contract.md`](../../references/command-contract.md) for
the full surface and the envelope spec.

## Status

Early and under active development; expect pre-release versions. Today the engine
runs Explore and Transform end to end on DuckDB and on BigQuery.

Explore: ranks what matters in an unfamiliar warehouse, profiles columns
selectively, flags PII, surfaces grain and data-quality warnings, infers joins
and verifies them with overlap probes (`--verify`), and executes agent-authored
ad-hoc SELECTs behind a PII-aware query firewall (`explore query`), all
read-only.

Transform: bootstraps a dbt project where none exists (`transform init`, with an
explicit connector, never a default), turns agent-authored edits and
deterministic staging scaffolds into reviewable, conflict-checked diffs
(`transform plan` / `apply`, with human edits authoritative on conflict), runs
gated dev-target-only builds with cost surfaced before any spend
(`transform build`), and authors the semantic layer as MetricFlow-validated dbt
semantic models (`semantic define|update|plan`, applied with `transform apply`).

BigQuery: connects through Application Default Credentials
(`gcloud auth application-default login`; dex discovers credentials, it never
asks for keys). Metadata is free; every scan is dry-run first, returned as a
`needs_confirmation` estimate, and runs only with `--confirm --budget <bytes>`,
capped server-side by `maximum_bytes_billed` and recorded in a local
`.dex/spend.jsonl` ledger. dbt builds go to a dedicated dev dataset via
dbt-bigquery, which the `[bigquery]` extra carries. See
[`references/bigquery.md`](../../references/bigquery.md).

Maintain detects drift against the `.dex/` snapshot on four axes and proposes
the fix: schema (structure), volume (freshness), grain (uniqueness and fanout),
and semantic (definitions, dangling references, and dimension cardinality).
`maintain check` sweeps all of them, ranked by blast radius; `reconcile`
proposes reviewable diffs tagged mechanical or advisory, applied through
`transform apply`. Detection is read-only on every connector; on billed
connectors the metadata axes (schema, volume, references) stay free while the
scanning axes (grain, dimension cardinality) take the `--confirm --budget`
handshake, so `check` is two-phase.

The remaining cloud connectors (Snowflake, Databricks, PostgreSQL) and the Viz
preview report `not_implemented` until they land.

## License

Apache-2.0.
