Skip to content
Back to search

dex

Analytics engineering for Claude Code and any agent: data warehouse exploration, dbt transformation and semantic modeling, and schema-drift maintenance on dbt.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/exmergo/dex with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/exmergo/dex'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/exmergo--dex/badge.svg)](/listings/exmergo--dex)

HTML

<a href="/listings/exmergo--dex"><img src="/api/listings/exmergo--dex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Any agent** (run in your terminal):

npx skills add exmergo/dex

**Claude Code** (run these inside Claude Code, one at a time):

/plugin marketplace add exmergo/exmergo-agent-plugins
/plugin install dex@exmergo

**Codex**:

npx skills add exmergo/dex --agent codex

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 37 lines
  1. {
  2. "name": "dex",
  3. "displayName": "Exmergo Dex",
  4. "description": "Analytics engineering for Claude Code and any agent: data warehouse exploration, dbt transformation and semantic modeling, and schema-drift maintenance on dbt.",
  5. "version": "1.18.0",
  6. "author": {
  7. "name": "Exmergo, Inc.",
  8. "email": "support@exmergo.com",
  9. "url": "https://www.exmergo.com"
  10. },
  11. "homepage": "https://docs.exmergo.com/dex",
  12. "repository": "https://github.com/exmergo/dex",
  13. "license": "Apache-2.0",
  14. "privacyPolicyUrl": "https://www.exmergo.com/privacy/dex",
  15. "termsOfServiceUrl": "https://www.exmergo.com/terms/dex",
  16. "supportUrl": "https://github.com/exmergo/dex/issues",
  17. "keywords": [
  18. "analytics-engineering",
  19. "dbt",
  20. "claude-code",
  21. "text-to-sql",
  22. "semantic-layer",
  23. "duckdb",
  24. "snowflake",
  25. "bigquery",
  26. "databricks",
  27. "data-engineering",
  28. "agent",
  29. "metricflow",
  30. "schema-drift",
  31. "data-contracts",
  32. "redshift",
  33. "postgres",
  34. "clickhouse",
  35. "trino"
  36. ]
  37. }
README.md · README · 481 lines
  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset="assets/preview-dark.png" />
  3. <img alt="Dex: let your agent build your analytics. Explore, transform, maintain. Connects to your data and authors your semantic layer: dbt, SLayer, Cube, Apache Ossie, Snowflake Semantic Views and Databricks Metric Views." src="assets/preview-light.png" />
  4. </picture>
  5. > *Most deadly errors arise from obsolete assumptions.*
  6. >
  7. > Frank Herbert, *Children of Dune*
  8. # Dex
  9. **Dex lets your agent build your analytics.**
  10. Explore your data, build models and semantic layers, and keep them in sync
  11. as schemas change.
  12. Works with databases, data warehouses, lakehouses, and SQL engine endpoints
  13. through [supported connectors](#connectors).
  14. **Built by [Exmergo](https://www.exmergo.com)**
  15. [![PyPI](https://img.shields.io/pypi/v/exmergo-dex-core?logo=pypi&logoColor=white&color=165dfc)](https://pypi.org/project/exmergo-dex-core/)
  16. [![License](https://img.shields.io/badge/license-Apache--2.0-165dfc)](LICENSE)
  17. [![data-eng-bench](https://img.shields.io/badge/data--eng--bench-57%25-33cf56)](benchmarks/data-eng-bench/README.md)
  18. [![ADE-bench](https://img.shields.io/badge/ADE--bench-80%25-33cf56)](benchmarks/ade_bench/README.md)
  19. [![CI](https://github.com/exmergo/dex/actions/workflows/ci.yml/badge.svg)](https://github.com/exmergo/dex/actions/workflows/ci.yml)
  20. [![Docs](https://img.shields.io/badge/docs-docs.exmergo.com%2Fdex-165dfc?logo=readthedocs&logoColor=white)](https://docs.exmergo.com/dex)
  21. [![Discord](https://img.shields.io/badge/Discord-Join%20the%20community-165dfc?logo=discord&logoColor=white)](https://trydex.ai/discord)
  22. [![LinkedIn](https://img.shields.io/badge/LinkedIn-Exmergo-165dfc?logo=linkedin&logoColor=white)](https://www.linkedin.com/company/exmergo/)
  23. [![X](https://img.shields.io/badge/Follow-%40exmergo-165dfc?logo=x&logoColor=white)](https://x.com/exmergo)
  24. [![Star the repo!](https://img.shields.io/github/stars/exmergo/dex?style=flat&label=Star%20the%20repo!%20%E2%AD%90&labelColor=555&logo=github&logoColor=white&color=165dfc)](https://github.com/exmergo/dex)
  25. ## Install
  26. **Any agent** (run in your terminal):
  27. ```bash
  28. npx skills add exmergo/dex
  29. ```
  30. **Claude Code** (run these inside Claude Code, one at a time):
  31. ```
  32. /plugin marketplace add exmergo/exmergo-agent-plugins
  33. ```
  34. ```
  35. /plugin install dex@exmergo
  36. ```
  37. **Codex**:
  38. ```bash
  39. npx skills add exmergo/dex --agent codex
  40. ```
  41. ## What you get
  42. - **Explore** your database, data warehouse, or SQL endpoint. Find the tables that matter, understand their structure, and verify how they join. Get column profiles, personal-data flags, and an ER diagram.
  43. - **Transform** your dbt project and semantic layer. Create models, tests, docs, and metrics as reviewable plans, then build and verify on a dev target.
  44. - **Maintain** your models and metrics as sources change. Detect drift in schemas, volumes, grain, and metric definitions, with proposed fixes to review.
  45. Your source data stays read-only. Builds run on a dev target, query costs are
  46. quoted before spend, and every project change is a diff you review.
  47. Works in Claude Code, Codex, or any agent that loads Agent Skills.
  48. > [!IMPORTANT]
  49. > **Dex needs [`uv`](https://docs.astral.sh/uv/) on your `PATH`.** No agent installs
  50. > it for you. Run `brew install uv` or `pipx install uv`, or see the
  51. > [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/)
  52. > for other platforms. `uv` supplies Python and the engine. Use uv 0.13.4 or
  53. > later (`uv self update`): earlier releases still trust the emSign CA roots
  54. > withdrawn after their keys were compromised.
  55. In Claude Code the skills appear as `/dex:explore`, `/dex:transform`, and
  56. `/dex:maintain` and trigger on matching intent. Update later with
  57. `/plugin marketplace update exmergo`. Codex also gets a native plugin, with no MCP
  58. server needed. Any other agent can be pointed at [`AGENTS.md`](AGENTS.md).
  59. Run Dex from your project directory, so it finds your `.dex/config.yml` and keeps
  60. its cache next to your project. Dex needs an agent with a local shell, so it does
  61. not run in claude.ai chat.
  62. > [!TIP]
  63. > **Skip the first-run wait.** The first command installs the engine, which takes
  64. > tens of seconds on a cold `uv` cache. Ask your agent to warm Dex once after
  65. > installing, or run the command below in a CI or container build step. Add
  66. > `--connector snowflake` (or any connector) to warm one before a project exists.
  67. ```bash
  68. uv run --no-project --script skills/<skill>/scripts/run.py --warm
  69. ```
  70. ## Why
  71. Writing SQL is one part of analytics engineering. Your agent also needs to:
  72. - understand the schema without starting from scratch every session,
  73. - find the relevant tables among thousands,
  74. - account for what a query costs,
  75. - keep personal data out of its context,
  76. - keep models and metric definitions coherent as their sources change.
  77. Dex gives the agent a repeatable explore, transform, maintain loop, with
  78. guardrails enforced in the engine.
  79. ## Quickstart
  80. ### Initialize
  81. If you want to use the python package `exmergo-dex-core`:
  82. 1. Install it with `uv`, with the extras you need (i.e. DuckDB)
  83. ```bash
  84. uv tool install "exmergo-dex-core[duckdb]"
  85. ```
  86. 2. Initialize a Dex project (creatively called "analytics")
  87. ```bash
  88. dex init analytics
  89. ```
  90. ### Demo
  91. Try Dex in a demo experience with no existing database, no credentials,
  92. no cloud account, and no network once the package is installed:
  93. ```bash
  94. uv tool install "exmergo-dex-core[duckdb]"
  95. dex init analytics --mode demo
  96. dex explore map
  97. ```
  98. `dex init analytics --mode demo` creates the e-commerce DuckDB warehouse
  99. (`dex_demo.duckdb`, 7 tables, 29,512 rows), a dbt project under `analytics/`,
  100. repository-level Dex configuration, and onboarding documentation. Reruns preserve
  101. authored files. The lower-level `dex demo` command remains available for creating
  102. just the warehouse and config. The data comes from a pinned seed.
  103. `explore map` maps all 7 tables, infers 5 joins, flags 6 columns as personal data,
  104. and reports 6 data-quality findings. Every command answers with one JSON envelope.
  105. An excerpt, for one table:
  106. ```json
  107. {
  108. "identifier": "dex_demo.main.order_items",
  109. "row_count": 14000,
  110. "grain": null,
  111. "data_quality": [
  112. "order_item_id is not unique: 13000 distinct over 14000 rows (1000 rows would have to be removed for it to be unique, so it is unique for 92.9% of rows); joins on it will fan out"
  113. ]
  114. }
  115. ```
  116. ### The demo is broken (on purpose!)
  117. A first run that reports a clean bill of health doesn't teach us much,
  118. so the demo ships with real defects. Dig into them:
  119. ```bash
  120. dex explore profile order_items products
  121. dex explore relationships --verify
  122. dex explore query "select email from customers"
  123. ```
  124. - **A broken grain.** A batch was loaded twice, so `order_item_id` is unique for only 92.9% of rows. Dex reports the duplicates and leaves the grain unknown rather than guessing a key.
  125. - **A key that mixes id schemes.** `sku` is `90% numeric, 10% 32-character hexadecimal (md5-shaped)`. Cast it to a number and you silently drop 10% of products.
  126. - **A join that looks right and is not.** `web_events.customer_id` shares a name with the CRM's key, but verification finds 100% of its values have no match.
  127. - **A refusal.** The query firewall will not put `customers.email` into context. `select count(distinct email) from customers` runs, because a statistic is not a value.
  128. There is also a table an interrupted load left empty, two columns whose declared
  129. type contradicts their content, and two designed PII false positives. See the
  130. [`dex demo` reference](https://docs.exmergo.com/dex/cli/demo).
  131. > [!NOTE]
  132. > DuckDB is free and local, so nothing here asks you to confirm a spend. On a
  133. > metered connector the same commands return an estimate first and run only once
  134. > you agree to it.
  135. ## How it works
  136. <picture>
  137. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/how-it-works-dark.png" />
  138. <img width="760" height="630" alt="How it works: your coding agent runs a Dex skill, which calls the exmergo-dex-core engine; the engine queries your data (SELECT-only, cost-capped, dbt builds on dev only), writes plans as reviewable diffs to your repository, keeps its cache in .dex/, and returns one sanitized JSON envelope to the agent" src="assets/readme/how-it-works-light.png" />
  139. </picture>
  140. The skills connect your agent to the `exmergo-dex-core` engine, which holds the
  141. logic and guardrails behind a [small command contract](https://docs.exmergo.com/dex/reference/command-contract).
  142. Your dbt project and semantic-layer definitions live in your repository as
  143. reviewable files. The `.dex/` directory holds Dex's cache and snapshots.
  144. ### Explore
  145. Find the tables that matter, profile their columns, and verify joins before
  146. writing SQL. Answer ad-hoc questions through a query firewall that checks for
  147. personal data, read and query the semantic layer, and map relationships as a
  148. Mermaid ER diagram. Exploration is read-only and needs no dbt project.
  149. [Skill](skills/explore/SKILL.md) · [methodology](https://docs.exmergo.com/dex/concepts/methodology) · [commands](https://docs.exmergo.com/dex/cli/explore)
  150. <picture>
  151. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/explore-dark.png" />
  152. <img width="522" height="343" alt="Explore" src="assets/readme/explore-light.png" />
  153. </picture>
  154. ### Transform
  155. Build and refactor dbt models from staging to marts, with tests, docs, and declared
  156. grain and population. Define semantic models and metrics over them, or work with a
  157. native semantic layer without a dbt project. Review each stored plan before
  158. applying it, then build and verify on a dev target.
  159. [Skill](skills/transform/SKILL.md) · [what Dex writes](https://docs.exmergo.com/dex/concepts/dbt-project) · [commands](https://docs.exmergo.com/dex/cli/transform)
  160. <picture>
  161. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/transform-dark.png" />
  162. <img width="504" height="271" alt="Transform" src="assets/readme/transform-light.png" />
  163. </picture>
  164. ### Maintain
  165. Compare database schemas and profiles, the dbt project, and the semantic layer
  166. with the last snapshot. See which models and metrics a change affects and review
  167. the proposed edits. `maintain verify` also checks a project as it stands, with no
  168. baseline needed.
  169. [Skill](skills/maintain/SKILL.md) · [commands](https://docs.exmergo.com/dex/cli/maintain)
  170. <picture>
  171. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/maintain-dark.png" />
  172. <img width="484" height="344" alt="Maintain" src="assets/readme/maintain-light.png" />
  173. </picture>
  174. > [!TIP]
  175. > **Give every agent in your repository the same procedure.**
  176. > `dex procedure --block` prints the procedure every Dex skill follows, ready to
  177. > paste into your `CLAUDE.md` or `AGENTS.md`, so an agent follows it even before
  178. > it loads a skill. Dex never writes the file;
  179. > `dex procedure --check CLAUDE.md` tells you when an upgrade has made your copy
  180. > stale. See
  181. > [`dex procedure`](https://docs.exmergo.com/dex/cli/procedure).
  182. ## Connectors
  183. | Connector | Type | Self-hostable | Extra / `--connector` | Cost guardrail | Connection details |
  184. | --- | --- | :---: | --- | --- | --- |
  185. | <img src="https://www.exmergo.com/connectors/snowflake.png" width="20" height="20" alt=""> [**Snowflake**](https://docs.exmergo.com/dex/connectors/snowflake) | Cloud warehouse | ❌ | `snowflake` | Warehouse-seconds, with credits | `connections.toml`, `SNOWFLAKE_*` env, or a dbt profile |
  186. | <img src="https://www.exmergo.com/connectors/bigquery.png" width="20" height="20" alt=""> [**BigQuery**](https://docs.exmergo.com/dex/connectors/bigquery) | Cloud warehouse | ❌ | `bigquery` | Bytes scanned | Application Default Credentials |
  187. | <img src="https://www.exmergo.com/connectors/databricks.png" width="20" height="20" alt=""> [**Databricks**](https://docs.exmergo.com/dex/connectors/databricks) | Lakehouse via SQL endpoint | ❌ | `databricks` | Warehouse-seconds, with DBUs | `databricks auth login`, `DATABRICKS_*` env, or a dbt profile |
  188. | <img src="https://www.exmergo.com/connectors/redshift.png" width="20" height="20" alt=""> [**Amazon Redshift**](https://docs.exmergo.com/dex/connectors/redshift) | Cloud warehouse, Serverless-first | ❌ | `redshift` | Compute-seconds, with RPU-hours | The AWS credential chain or `REDSHIFT_*` env |
  189. | <img src="https://www.exmergo.com/connectors/postgresql.png" width="20" height="20" alt=""> [**Postgres**](https://docs.exmergo.com/dex/connectors/postgres) | Operational database | ✅ | `postgres` | Database-seconds | `pg_service.conf`, `DATABASE_URL`, `PG*` env, or a dbt profile<br>Also works with <img src="assets/supabase-logo.png" width="20" height="20" alt=""> [Supabase](https://supabase.com/), <img src="assets/neon-logo.png" width="20" height="20" alt=""> [Neon](https://neon.com/), and [more managed Postgres platforms](references/postgres.md#managed-postgres-platforms) |
  190. | <img src="https://www.exmergo.com/connectors/duckdb.png" width="20" height="20" alt=""> [**DuckDB**](https://docs.exmergo.com/dex/connectors/duckdb) | Embedded analytical | ✅ | `duckdb` | Free and local | None, just a file path |
  191. | <img src="https://www.exmergo.com/connectors/clickhouse.png" width="20" height="20" alt=""> [**ClickHouse**](https://docs.exmergo.com/dex/connectors/clickhouse) | Analytical database | ✅ | `clickhouse` | Compute-seconds on Cloud, database-seconds self-hosted | `CLICKHOUSE_URL`, `CLICKHOUSE_*` env, or a dbt profile |
  192. | <img src="https://www.exmergo.com/connectors/trino.png" width="20" height="20" alt=""> [**Trino**](https://docs.exmergo.com/dex/connectors/trino) | Federated query engine | ✅ | `trino` | Cluster-seconds| `TRINO_URL`, `TRINO_*` env, or a dbt profile<br>Also works with: <img src="assets/mysql-logo.png" width="20" height="20" alt=""> MySQL, <img src="assets/sqlserver-logo.png" width="20" height="20" alt=""> SQL Server, <img src="assets/mongodb-logo.png" width="20" height="20" alt=""> MongoDB, and [more databases through Trino catalogs](references/trino.md#databases-through-configured-catalogs) |
  193. Credentials are discovered and never enter the agent's context.
  194. Every scan is estimated, confirmed, and capped server-side, and settled spend is
  195. recorded in a local ledger ([cost controls](https://docs.exmergo.com/dex/guardrails/cost-controls)).
  196. Self-hosted databases bill no dollars and are still gated, because an unbounded
  197. scan on a production Postgres primary is a real cost too.
  198. **Coming next:** MotherDuck, Starburst Galaxy, Microsoft Fabric.
  199. ## Semantic layers
  200. Choose the semantic layer independently of your database connector.
  201. Configure the choice in `.dex/config.yml`.
  202. ([overview](https://docs.exmergo.com/dex/semantic-layers/overview))
  203. | Semantic layer | Authorable | Hosted | Queryable | `vendor` / `deployment` | Read through | Documentation |
  204. | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :----: | :-------: | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
  205. | <img src="https://www.exmergo.com/connectors/ossie.png" width="20" height="20" alt=""> **[Apache Ossie](https://github.com/apache/ossie)** (incubating) | ✅ | ❌ | ❌ | `ossie` / `local` | Native documents in the repository, no dbt or MetricFlow in the path | [Docs](https://docs.exmergo.com/dex/semantic-layers/ossie) |
  206. | <img src="https://www.exmergo.com/connectors/dbt.png" width="20" height="20" alt=""> **[dbt](https://github.com/dbt-labs/dbt-core)** | ✅ | ✅ | ✅ | `dbt` / `local` or `dbt_cloud` | MetricFlow locally, run through the Dex connector and its cost guard, or the hosted dbt Cloud Semantic Layer API | [Docs](https://docs.exmergo.com/dex/semantic-layers/overview#choosing-a-backend-ambient-like-a-connector) |
  207. | <img src="https://www.exmergo.com/connectors/databricks.png" width="20" height="20" alt=""> **[Databricks Metric Views](https://docs.databricks.com/aws/en/metric-views/)** | ✅ | 🚧 | 🚧 | `databricks` / `local` | Metric View YAML files in the repository, read and authored statically with no workspace connection; nothing is deployed, and querying is not yet supported | [Docs](https://github.com/exmergo/dex/tree/main/packages/dex-core#semantic-layers) |
  208. | <img src="https://www.exmergo.com/connectors/snowflake.png" width="20" height="20" alt=""> **[Snowflake Semantic Views](https://docs.snowflake.com/en/user-guide/views-semantic/overview)** | ✅ | ✅ | ✅ | `snowflake` / `local` or `snowflake_account` | Semantic View YAML files in the repository, read and authored statically, or the views deployed on the account; Dex renders `SEMANTIC_VIEW()` and runs it under the cost guard. Under `local` (or `--local`) the deployed view is checked against its file first; account results name a matching file but are not checked against it | [Docs](https://docs.exmergo.com/dex/semantic-layers/snowflake-semantic-views) |
  209. | <img src="assets/motley-logo.jpeg" width="20" height="20" alt=""> **[SLayer](https://github.com/MotleyAI/slayer)** (by Motley) | ✅ | 🚧 | ✅ | `slayer` / `local` | SLayer model files, validated by one pinned release; SLayer renders, Dex runs it under the cost guard | [Docs](https://docs.exmergo.com/dex/semantic-layers/overview#slayer-models-vendor-slayer) |
  210. | <img src="assets/cube-logo.png" width="20" height="20" alt=""> **[Cube](https://github.com/cube-js/cube)** | ✅ | 🚧 | ✅ | `cube` / `local` | Plain YAML model files, read statically with no Node or Cube server; querying asks a running Cube server to render, Dex runs it under the cost guard | [Docs](https://docs.exmergo.com/dex/semantic-layers/overview#cube-models-vendor-cube) |
  211. **Coming next:** hosted Cube, hosted SLayer, hosted and queryable Databricks Metric Views, and Looker / LookML.
  212. ## Dex Semantics
  213. **Let your agent build analytics with 25% fewer errors**, thanks to data that
  214. explains itself to your coding agent.
  215. A join can keep running after the source changes underneath it, and quietly
  216. count every row twice. Dex Semantics keeps each model's meaning with the model,
  217. as code, so that kind of error is caught instead of shipped:
  218. - **Declare the rules.** Every model your agent creates or changes carries a
  219. declaration: what one row is, which rows belong, how each number adds up, and
  220. the assumptions behind it. Dex drafts what it measured; the intent is yours.
  221. - **Check the results.** `transform build --verify` holds the built data to the
  222. declaration: duplicate keys, rows the population excludes, a running total
  223. summed across time.
  224. - **Keep the context.** The declaration becomes dbt tests, is read back by the
  225. next agent session, and derives the semantic model for any layer above.
  226. <picture>
  227. <source media="(prefers-color-scheme: dark)" srcset="assets/readme/semantics-dark.png" />
  228. <img width="760" height="340" alt="Dex Semantics: the declaration lives with your models (one row per shipment; production counts harvests; revenue uses the agreed price), Dex checks the built data (S01 and S02: expected 1 row, found 2; without Dex 200 t, with Dex 100 t), and the meaning flows to tests, semantic models and the next agent session" src="assets/readme/semantics-light.png" />
  229. </picture>
  230. 25% fewer failed tasks on [ADE-bench](benchmarks/ade_bench/README.md) with
  231. Claude Sonnet 5.5 (15 against 20 of 75). The image is an illustrated workflow on
  232. synthetic data.
  233. [Dex Semantics](references/dex-semantics.md) · [declarations](skills/transform/references/declarations.md) · [the film](https://www.youtube.com/watch?v=-iYwYuzZFg0)
  234. ## See it on a real project
  235. **[github-repo-analytics](https://github.com/exmergo/github-repo-analytics)** is a template that tracks GitHub traffic, stars, downloads and contributors for your open-source projects, free on GitHub Actions.
  236. Every model and metric was built and is maintained with Dex. Its [audit trail](https://github.com/exmergo/github-repo-analytics/blob/main/.dex/review/README.md) holds the raw envelopes, including the drift Dex blocked.
  237. ## Use Dex from Python
  238. The engine is a plain Python package, `exmergo-dex-core`:
  239. ```bash
  240. pip install exmergo-dex-core # or: uv add exmergo-dex-core
  241. ```
  242. Drive the same loop from Python instead of parsing CLI output:
  243. ```python
  244. from exmergo_dex_core import DexEngine
  245. with DexEngine(connector="duckdb", path="shop.duckdb") as eng:
  246. mapped = eng.map() # a DexCache, not a JSON blob
  247. rows = eng.query("select status, count(*) from orders group by status")
  248. print(mapped.relationship_count, rows.cells)
  249. ```
  250. Every guarantee the CLI makes holds here, because it is the same code. An
  251. unconfirmed billed call raises `ConfirmationRequiredError` carrying the estimate.
  252. By default nothing is written to disk; `DexEngine.from_repo("path/to/repo")` opts in
  253. to a project on disk, the way the CLI does.
  254. For hosts embedding Dex:
  255. - **Values-free mode** keeps every table value out of the model's view, aggregates only. ([values-free mode](https://docs.exmergo.com/dex/guardrails/values-free-mode))
  256. - **Per-user credentials**: pass a `ConnectionSource` so each request reaches the connected system as its own principal.
  257. - **Multi-process lifecycles**: export a plan, verify and apply it elsewhere, and get typed evidence of what a build established. ([host integration](https://docs.exmergo.com/dex/reference/host-integration))
  258. - **Other formats and stores**: plug in a [project format](https://docs.exmergo.com/dex/reference/project-formats) or a [storage backend](https://docs.exmergo.com/dex/reference/storage-backends).
  259. More in the [package README](packages/dex-core/README.md).
  260. ## Benchmarks
  261. We run Dex on two public analytics-engineering benchmarks and commit every run's
  262. raw per-task results, including the ones that flatter us least.
  263. | Benchmark | Setup | Result | Details |
  264. |---|---|---|---|
  265. | **data-eng-bench** (Snowflake, 103 tasks) | Dex + Claude Sonnet 5 | **57.3%** resolved, 89.7% of assertions pass | [README](benchmarks/data-eng-bench/README.md) |
  266. | **ADE-bench** (dbt Labs, 75 tasks) | Dex 1.17.4 + Claude Sonnet 5.5 | **80%** resolved vs 73.3% without Dex; **25% fewer failures** | [README](benchmarks/ade_bench/README.md) |
  267. On ADE-bench, the same Claude Sonnet 5.5 model solves **60 of 75 tasks with Dex**,
  268. compared with **55 without it**: **+6.7 percentage points**, with net gains across
  269. six of seven projects. Both configurations make one scored attempt per task.
  270. [Compare the runs and raw results](benchmarks/ade_bench/README.md).
  271. We believe that benchmarks are important, but not as important as user/agent experience.
  272. Trust in a diff, cost surfaced before spend, and sensitive data kept out of context. We optimize for that experience
  273. and treat these scores as guide posts. ([evaluation](https://docs.exmergo.com/dex/reference/evaluation))
  274. ## Managing the Dex lifecycle
  275. ### What Dex sends where
  276. - **On install**, `uv` downloads the pinned engine (and a Python 3.11 to 3.14 if you have none, or if your newest is a 3.15, which Dex does not support yet) from PyPI or your configured index.
  277. - **Your connected database, data warehouse, or SQL endpoint** gets SELECT-only SQL from Dex, plus the dbt builds you confirm on a dev target, with credentials from your existing credential chain.
  278. - **dbt Cloud** is contacted only if you enable the hosted semantic layer.
  279. - **dbt-core**, when Dex runs it, sends dbt Labs no usage statistics: Dex sets `DO_NOT_TRACK=1` for every dbt process it starts. `transform deps` downloads the packages your `packages.yml` declares.
  280. - **Your repository** holds Dex's state in `.dex/`. dbt writes its usual `target/` and `logs/`.
  281. > [!IMPORTANT]
  282. > **Dex sends nothing to Exmergo.** No telemetry, analytics, license check, or
  283. > update ping. See the [Dex privacy policy](https://trydex.ai/privacy)
  284. > and the [Dex terms of service](https://trydex.ai/terms).
  285. ### What to commit in `.dex/`
  286. Dex keeps its working state in `.dex/`. Most of it is safe to commit; the
  287. exception is any file that can carry data values. Commit the lockfile and the
  288. config, and keep the exploration cache out of a repo that must not publish
  289. data values:
  290. | File | Commit? | Can it contain data values? |
  291. | --- | --- | --- |
  292. | `.dex/config.yml` | Yes | No: connector targets, `pii_overrides` (column names, not values), budgets and limits. Credentials live in environment variables or dbt profiles, never in this file. |
  293. | `.dex/snapshot.json` | Like a lockfile, where its values may be public; otherwise take a metadata-only baseline or keep it out | Yes: when snapshotted from a cache it pins the cache's datasets wholesale, including each non-PII column's capped value domain and min/max. A metadata-only baseline (no cache) carries schema and volume only. PII-flagged columns never carry value domains. |
  294. | `.dex/cache.json` | Only if values may be public | Yes: column profiles with capped value domains (actual values with counts). Never for PII-flagged columns. |
  295. | `.dex/plans/*.json` | Optional, as an audit trail | No data values: the proposed contents of project files. |
  296. | `.dex/queries.jsonl` | Optional, as a ledger | SQL text, which may hold literals. |
  297. | `.dex/drift.json` | No: regenerate with `maintain check` | Aggregates only: counts, names and schema metadata in drift findings. |
  298. For a repo that must not publish data values, ignore the rest:
  299. ```gitignore
  300. # Dex state that can publish data values, or is local-only output.
  301. .dex/cache.json
  302. .dex/dex.db
  303. .dex/dex.db-journal
  304. .dex/queries.jsonl
  305. .dex/drift.json
  306. .dex/spend.jsonl
  307. .dex/spend.lock
  308. .dex/cache.lock
  309. ```
  310. `.dex/dex.db` is the SQLite backend's equivalent of `cache.json`, so it gets
  311. the same caution. `.dex/spend.jsonl` is the billed-command ledger: byte
  312. counts, job ids and statement hashes only, never SQL values or credentials,
  313. but it is local spend history, so there is no reason to commit it.
  314. ### What Dex will never do
  315. - **Write to your source data.** Dex's own SQL is SELECT-only. The only data writes are the dbt builds you confirm, on a dev target.
  316. - **Put personal data in your agent's context.** PII is flagged by column, category, and confidence, and never surfaced. Only a human clears a flag. ([PII policy](https://docs.exmergo.com/dex/guardrails/pii-policy))
  317. - **Spend before quoting.** A metered scan returns an estimate and runs only with your confirmation and a budget. ([cost controls](https://docs.exmergo.com/dex/guardrails/cost-controls))
  318. - **Change your project behind your back.** Every edit is a diff, and a human edit made since planning is never overwritten. ([source of truth](https://docs.exmergo.com/dex/concepts/source-of-truth))
  319. - **Build anywhere but dev.** Prod-looking targets are refused outright.
  320. ## Further reading
  321. - [Documentation](https://docs.exmergo.com/dex): start here
  322. - [CLI reference](https://docs.exmergo.com/dex/cli/overview): every command and flag
  323. - [Command contract](https://docs.exmergo.com/dex/reference/command-contract) and [`AGENTS.md`](AGENTS.md): how any agent drives the engine
  324. - [Cost controls](https://docs.exmergo.com/dex/guardrails/cost-controls) and [PII policy](https://docs.exmergo.com/dex/guardrails/pii-policy): the two guardrails that cut across everything
  325. - [Configuration](https://docs.exmergo.com/dex/cli/config): read and change `.dex/config.yml` as a confirmed diff
  326. - [Connectors](https://docs.exmergo.com/dex/connectors/duckdb): setup, cost, and read-only enforcement per connector
  327. - [Changelog](https://docs.exmergo.com/dex/changelog)
  328. - [`references/`](references/): the same material as Markdown, for agents and offline reading
  329. ## Dex Enterprise
  330. Dex Enterprise runs Dex as automated workflows in your own CI. It turns tickets into
  331. draft pull requests with `explore` and `transform`, and runs `maintain` on a schedule
  332. to turn drift into draft pull requests for your engineers to review. No Exmergo
  333. service sits in the request path, and everything in this repository stays
  334. Apache-2.0. [Learn more](https://trydex.ai/enterprise).
  335. ## Community
  336. ### Community Integrations
  337. | Integration&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Maintainer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | What it does | Details |
  338. | --- | --- | --- | --- |
  339. | <img src="assets/dagster-logo.png" width="20" height="20" alt=""> **[dagster-dex](https://github.com/catincloud-labs/dagster-dex)** | <img src="assets/catincloudlabs-logo.png" width="20" height="20" alt=""> [CatInCloud Labs](https://github.com/catincloud-labs) | Explore and maintain your Dagster assets with Dex, using the asset graph in place of a dbt project. | [Repository](https://github.com/catincloud-labs/dagster-dex) |
  340. | <img src="assets/openlakeforge-logo.png" width="20" height="20" alt=""> **[OpenLakeForge](https://github.com/OpenLakeForge/openlakeforge)** | <img src="assets/openlakeforge-logo.png" width="20" height="20" alt=""> [OpenLakeForge](https://github.com/OpenLakeForge) | Explore an OpenLakeForge lakehouse alongside Dex through the `olf` CLI, with read-only access to Trino data, OpenMetadata domains and products, and Dagster jobs and runs. | [Skill](https://github.com/OpenLakeForge/openlakeforge/blob/main/skills/exploring-openlakeforge/SKILL.md) |
  341. ### Connect with the Community
  342. Join the agent-native data/analytics community!
  343. - 🌟 [Star Us on GitHub](https://github.com/exmergo/dex/)
  344. - 👾 [Join Our Discord Community](https://trydex.ai/discord)
  345. - 🔗 [Follow Us on LinkedIn](https://www.linkedin.com/company/exmergo/)
  346. - 🐦 [Follow Us on X](https://x.com/exmergo)
  347. - 🔨 [Follow Us on GitHub](https://github.com/exmergo/)
  348. ## Feedback and bug reports
  349. Found something wrong, or something Dex should do? Open an issue: bug reports and
  350. ideas are welcome, including ones your agent drafts for you. Run `dex feedback`
  351. for the environment to paste and links that prefill the
  352. [bug report](https://github.com/exmergo/dex/issues/new?template=bug_report.yml)
  353. and [feature request](https://github.com/exmergo/dex/issues/new?template=feature_request.yml)
  354. forms; nothing is sent. Security problems go to [SECURITY.md](SECURITY.md), never
  355. a public issue. More in [SUPPORT.md](SUPPORT.md).
  356. ## Contributing
  357. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, linting, the pre-commit
  358. hook, and changelog fragments. Every pull request into `main` must pass Lint and
  359. CI, and adds a fragment under [`changelog.d/`](changelog.d/) unless no user can
  360. see the change. Please also read the [code of conduct](CODE_OF_CONDUCT.md).
  361. ## License
  362. Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). The licence governs the
  363. software. Exmergo's distribution, documentation, support, and trademarks are
  364. covered by the [Dex terms of service](https://www.exmergo.com/terms/dex).

Version history

  • v1.18.011/17/2026

  • v1.17.911/14/2026

  • v1.17.811/13/2026

  • v1.17.711/12/2026

  • v1.17.611/11/2026

  • v1.17.411/7/2026

  • v1.17.311/5/2026

  • v1.17.111/2/2026

  • v1.17.011/1/2026

  • v1.16.610/31/2026

  • v1.16.510/30/2026

  • v1.16.410/29/2026

  • v1.16.310/28/2026

  • v1.16.210/27/2026

  • v1.16.110/26/2026

  • v1.16.010/25/2026

  • v1.15.310/24/2026

  • v1.15.210/23/2026

  • v1.15.110/21/2026

  • v1.14.110/19/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.