Skip to main content

TableTalk

Mount a dbt project. Review proposed agents and evaluations. Record evidence of whether your data agents stay in scope and give correct answers.

Tests Python PyPI License

TableTalk is the dbt-native development, evaluation, and observability layer for trusted data agents. It uses the analytical knowledge that a company already maintains in dbt. It creates reproducible agents and replayable evaluation evidence. It does not require a second large semantic configuration system.

TableTalk is not a general agent framework. It is not a BI dashboard. It does not replace dbt.

Status

Alpha, in maintenance mode. There is no active feature development. Bug fixes and security fixes are still reviewed, slowly (see contributing).

What works, verified offline on DuckDB with the example project in this repo (uv run pytest -q, make demo, make replay, and CI on Python 3.11 to 3.13):

  • The SQL guard: scope, columns, sensitive columns, the row limit, and a result-column backstop, tested with 87 adversarial cases.
  • tabletalk lock and tabletalk plan, including --check failing on drift.
  • Strict eval replay and tabletalk receipt replay with no model call.
  • The GitHub Action, which runs on this repository's own pull requests.
  • tabletalk mcp, tested with an in-process MCP client.
  • tabletalk score and tabletalk fix.

Not verified:

  • A real Snowflake account. Snowflake auth, the scan budget, timeouts, and query tags are tested only against a fake connector. scripts/snowflake_check.py exists to check a real account, but it has not been run against one.
  • The Claude Desktop MCP configuration in docs/mcp.md.
  • The shields.io badge that tabletalk score --badge writes.
  • Source freshness in receipts from a real dbt source freshness run. It is tested only with a hand-written sources.json, and the example project has none.
  • Live models other than the recorded gemma4:31b-cloud runs.

What TableTalk records

  • manifest.json defines the queryable resources.
  • Agent files contain dbt selectors and small TableTalk policies.
  • Every agent and eval starts as a review-only proposal.
  • Approval binds the exact proposal, manifest, base files, and resource bytes.
  • Trusted semantic statements record source evidence.
  • Inferred statements remain untrusted until a user confirms them.
  • SQL validation runs before every read-only warehouse query.
  • Live questions and evals use the same runtime.
  • Approved reference queries provide changing-data ground truth.
  • Inference artifacts support strict replay with no model request.
  • Reports include hard checks, trial metrics, uncertainty, paired comparisons, and failure ownership.

Install

pip install tabletalk
pip install "tabletalk[duckdb]"
pip install "tabletalk[snowflake]"

TableTalk requires Python 3.11 or newer. The supported warehouses are DuckDB and Snowflake. SQLite works for tests and local experiments only.

Start from an existing dbt project

cd my-dbt-project
dbt parse
dbt docs generate
tabletalk init
tabletalk propose
tabletalk approve
tabletalk eval run
tabletalk ask revenue "What was recognized revenue last month?"

tabletalk propose analyzes dbt groups, tags, packages, paths, owners, access, metrics, semantic models, tests, constraints, descriptions, and lineage. It creates at most three coherent proposals. It prefers curated marts. It shows semantic gaps and exact file diffs. It does not write project resources.

The approval command requires the exact proposal digest for automated use:

tabletalk approve prp_EXAMPLE \
  --yes \
  --digest sha256:EXAMPLE \
  --actor "$USER"

Approval fails if the manifest or a reviewed base file changed. TableTalk runs approved evals immediately.

Acquire missing meaning

Provide a targeted answer:

tabletalk propose \
  --answer "time_basis:model.analytics.orders.booked_revenue=booked_date"

Preview an organizational query as evidence:

tabletalk propose --sql-import finance/revenue.sql

Request optional model hypotheses:

tabletalk propose --infer

TableTalk marks every model hypothesis as inferred. An inferred statement cannot support an answer. A user must confirm its meaning through a new proposal.

Evaluate and replay

tabletalk eval run revenue --trials 3 --workers 2
tabletalk eval run revenue --trials 3 --cache-policy replay
tabletalk eval run revenue --baseline revenue-v1

Each run writes a concise terminal result and three detailed artifacts:

  • versioned JSON for tools
  • JUnit XML for CI
  • Markdown for a pull request.

The report identifies the model, agent, manifest, semantic knowledge, prompt, runtime, warehouse, and inference fingerprint. It reports pass rate, a Wilson confidence interval, latency, tokens, configured cost, flaky outcomes, and deterministic failure diagnoses.

Answer receipts

tabletalk ask prints a receipt for each answer and stores it as JSON. A receipt shows the trust level, the executed SQL, the evidence rows, and the dbt models and column descriptions the agent used. It also shows their tests, lineage, source freshness, and dependent dashboards, plus a replay command.

tabletalk ask revenue "What was recognized revenue in July 2026?"
tabletalk receipt replay run_5c0b6a582ba84c14

verified means that an approved eval matched the question and passed. grounded means that every hard check passed but no eval covers the question. unverified means that a check failed. The format is an open specification: tabletalk.receipt/v1.

Score readiness

tabletalk score --badge .github/badges/agent-ready.json

The score is a fixed rubric over descriptions, tests, sensitive-data flags, resolved semantics, the lock, and eval coverage. Each missing point lists its fix. See the rubric.

tabletalk fix turns the fixes it can make with certainty into a patch for your dbt project: it flags columns that look sensitive but have no flag, and copies a column description from upstream when every upstream description agrees. It never invents a description and never edits dbt files itself.

tabletalk fix --write fix.patch && git apply fix.patch

Use agents from Claude, Cursor, or any MCP client

pip install "tabletalk[mcp]"
tabletalk mcp --project-folder .

The MCP server serves only agents that match tabletalk.lock.yaml, and every answer includes its receipt. If a dbt change alters an agent's scope, that agent stops answering until the change is reviewed and locked. See MCP server.

Check every dbt pull request

- uses: wtbates99/tabletalk@main
  with:
    evals: replay

The action posts one comment with the agent plan and a model-free eval replay. See pull-request checks.

Security and retention

The warehouse identity's permissions are the security boundary. TableTalk adds checks in front of it; it does not replace it. Use a role that can only read the models in the agents' scope. See the security model.

What TableTalk enforces:

  • SQL AST guard. One read-only query statement. Writes, commands, a fixed denylist of functions, and table functions in FROM are rejected.
  • Scope. Every table must resolve to a dbt resource in the agent's selector scope, checked per CTE and subquery. Every column must exist on that resource. Joins need a condition.
  • Sensitive columns. Columns flagged sensitive are rejected anywhere in the query, including through *, unless the agent allows them. The returned column names are checked again before rows reach the model, a trace, or MCP.
  • Row limits. LIMIT max_rows is added, or an integer LIMIT above it is lowered.
  • Scan budget. On Snowflake, max_scan_bytes blocks a query whose estimated scan is over budget. Every query is tagged and has a server-side timeout. See Snowflake controls.
  • TableTalk never treats lineage as proof that a join is correct.

Known limitations, none fixed yet:

  • The guard uses a function denylist, not an allowlist. Unlisted scalar functions are allowed.
  • There is no connection-level hardening. DuckDB external access is not disabled, and no read-only Snowflake role is created or checked.
  • On DuckDB and SQLite the timeout stops waiting but may not cancel the running query. Not verified.
  • Sensitivity is also guessed from English keywords in semantic_guard.is_sensitive. Flag sensitive columns in dbt instead.
  • A computed LIMIT such as limit 10 + 999990 is not capped.

Retention:

  • TableTalk does not store credentials in traces, reports, or fingerprints.
  • Inference artifacts hash prompts by default. Set persist_prompts: true only when exact raw-prompt retention is acceptable.
  • Traces and reports retain bounded evidence rows. Exact evidence is required for deterministic replay and claim validation.
  • TableTalk does not delete artifacts automatically. The operator must apply a retention policy to .tabletalk/.

See the commerce example, the getting-started guide, and the research evidence.

Development

uv sync --locked --all-groups
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy tabletalk  # strict mode, from pyproject.toml
uv build

The live Ollama smoke test is opt-in. It uses only gemma4:31b-cloud:

TABLETALK_LIVE_OLLAMA=1 uv run pytest -m live_ollama

License and services

TableTalk is open source under the Apache License 2.0, including for commercial use. Earlier releases keep their earlier license grants. See LICENSE_HISTORY.md.

William Bates offers implementation, integration, semantic onboarding, and custom eval-suite development for teams adopting data agents on dbt. Contact William Bates.

Metadata

Release files for tabletalk 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tabletalk 0.7.0
File Size Uploaded Provenance Actions
tabletalk-0.7.0.tar.gz 396.3 kB With provenance Details for tabletalk-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tabletalk 0.7.0
File Interpreter ABI Platform Actions
tabletalk-0.7.0-py3-none-any.whl Python 3 none any Details for tabletalk-0.7.0-py3-none-any.whl

Total release size: 537.4 kB

Release files / tabletalk-0.7.0.tar.gz

Download URL tabletalk-0.7.0.tar.gz
Size 396.3 kB
Tags Source
SHA-256 checksum
How to use checksums
483d274d34a2eec10bb401952c2a3f9474c762405dd5893e9dbfa184429f828d
BLAKE2b-256 checksum
How to use checksums
e13e8e132cae8215fca6a84b6cd35510c733c492daf956f2ae63933fc68347b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / tabletalk-0.7.0-py3-none-any.whl

Download URL tabletalk-0.7.0-py3-none-any.whl
Size 141.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6da58f3c179bcd126e113bdcab05449e8f228e5c61d2773db7f355882e8d97d0
BLAKE2b-256 checksum
How to use checksums
c364f19678d4a7f26146da0d38c7ba8321eb50d13fd1fb8d5d8b99e277445055
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for tabletalk 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tabletalk-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page