tabletalk 0.2.1__tar.gz → 0.5.0__tar.gz

tabletalk-0.5.0/.github/workflows/db_provider_tests.yml

@@ -0,0 +1,84 @@
+name: Test supported providers
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          cache-suffix: py${{ matrix.python-version }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install supported database extras
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Run static checks
+        run: |
+          uv run ruff check tabletalk
+          uv run mypy tabletalk
+
+  package:
+    name: Verify PyPI distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Validate PyPI metadata
+        run: uvx twine check --strict dist/*
+
+      - name: Verify wheel contents and installation
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          from zipfile import ZipFile
+
+          wheel = next(Path("dist").glob("*.whl"))
+          with ZipFile(wheel) as archive:
+              names = archive.namelist()
+          assert not any("/tests/" in name for name in names)
+          assert not any(".data/data/tabletalk/static/" in name for name in names)
+          assert "tabletalk/static/index.html" in names
+          PY
+          uv venv .package-test
+          uv pip install --python .package-test/bin/python dist/*.whl
+          .package-test/bin/tabletalk --version
+          .package-test/bin/python -c "from tabletalk import Agent, EvalSuite, Project"

tabletalk-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,96 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Verify release tag matches package version
+        run: |
+          PACKAGE_VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "${GITHUB_REF_NAME#v}" = "$PACKAGE_VERSION"
+
+      - name: Build wheel and source distribution
+        run: uv build
+
+      - name: Validate PyPI metadata
+        run: uvx twine check --strict dist/*
+
+      - name: Inspect wheel contents
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          from zipfile import ZipFile
+
+          wheel = next(Path("dist").glob("*.whl"))
+          with ZipFile(wheel) as archive:
+              names = archive.namelist()
+          assert not any("/tests/" in name for name in names)
+          assert not any("tabletalk/static/" in name for name in names)
+          assert "tabletalk/app.py" not in names
+          for required in (
+              "tabletalk/agents.py",
+              "tabletalk/evals/__init__.py",
+              "tabletalk/manifest.py",
+              "tabletalk/project.py",
+              "tabletalk/runtime/__init__.py",
+              "tabletalk/validation.py",
+          ):
+              assert required in names, f"missing wheel module: {required}"
+          PY
+
+      - name: Verify wheel installation
+        run: |
+          uv venv .package-test
+          uv pip install --python .package-test/bin/python dist/*.whl
+          .package-test/bin/tabletalk --version
+          .package-test/bin/python -c "from tabletalk import Agent, EvalSuite, Project"
+
+      - name: Upload verified distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish verified distribution
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tabletalk
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI using trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

{tabletalk-0.2.1 → tabletalk-0.5.0}/.gitignore

@@ -65,8 +65,28 @@ user_settings.json
 
 # Database
 *.db
+*.duckdb
+*.duckdb.wal
+examples/ecommerce/evals/fixtures/*.duckdb
 __pycache__
 
+# TableTalk generated output and per-user runtime state
+.tabletalk/
+/examples/*/manifest/
+.tabletalk_history.jsonl
+.tabletalk_favorites.json
+.tabletalk_audit.jsonl
+.tabletalk_schedules.json
+.tabletalk_history/
+.tabletalk_memory/
+
+# dbt generated and per-user state
+.user.yml
+dbt_packages/
+logs/
+/examples/*/dbt_project/dbt_packages/
+/examples/*/dbt_project/logs/
+
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
 __pypackages__/
 
@@ -128,6 +148,12 @@ docs/_build/
 .pybuilder/
 target/
 
+# The reference project's manifest is a dbt-generated acceptance fixture.
+!examples/dbt-analytics/target/
+examples/dbt-analytics/target/*
+!examples/dbt-analytics/target/manifest.json
+!examples/dbt-analytics/target/catalog.json
+
 # Jupyter Notebook
 .ipynb_checkpoints
 

tabletalk-0.5.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: tabletalk
+Version: 0.5.0
+Summary: Evaluation and observability for natural-language agents over dbt projects
+Project-URL: Homepage, https://github.com/wtbates99/tabletalk
+Project-URL: Repository, https://github.com/wtbates99/tabletalk
+Author-email: william bates <wtbates99@gmail.com>
+License: CC BY-NC 4.0
+License-File: LICENSE
+Keywords: ai,database,dbt,llm,natural-language,sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: sqlglot>=25.0
+Provides-Extra: all
+Requires-Dist: duckdb>=0.9; extra == 'all'
+Requires-Dist: snowflake-connector-python>=3.0; extra == 'all'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.9; extra == 'duckdb'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python>=3.0; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# TableTalk
+
+TableTalk is an evaluation and observability framework for natural-language agents built on existing
+dbt projects. `manifest.json` is the complete authority for what an agent may query; warehouse
+connections are read-only execution adapters for those dbt relations.
+
+## Start from a dbt project
+
+```console
+cd my-dbt-project
+dbt parse
+dbt docs generate  # recommended: adds physical warehouse types
+tabletalk init
+tabletalk agent create
+tabletalk eval create revenue
+tabletalk eval run revenue
+tabletalk ask revenue "What was recognized revenue last month?"
+```
+
+`tabletalk init` finds `dbt_project.yml` and `target/manifest.json`, resolves a supported SQLite,
+DuckDB, or Snowflake target from the dbt profile, and writes only non-secret TableTalk settings.
+Agent creation asks the user to choose a displayed dbt group, tag, model, path, package, or source and
+whether to include lineage. It previews the exact resolved models, descriptions, catalog types, tests,
+constraints, and lineage before writing a small selector-based resource. Raw selectors remain available
+for automation.
+
+```yaml
+name: revenue
+description: Answers questions about recognized revenue.
+select:
+  - group:finance
+  - tag:revenue
+exclude:
+  - model:customer_sensitive
+instructions:
+  - Use recognized revenue unless the user explicitly requests bookings.
+sample_questions:
+  - What was recognized revenue last month?
+```
+
+Descriptions, columns, tests, constraints, ownership, access, tags, and lineage stay in dbt. They are
+never duplicated into an agent file.
+
+## Correctness and provenance
+
+Live questions and eval cases call the exact same `Runtime.answer` path. Before execution, TableTalk
+parses generated SQL and requires one read-only query, in-scope manifest relations, known columns,
+explicit join conditions, row and timeout limits, and explicit sensitive-data permission. It derives
+used dbt nodes and columns from that parsed SQL—not from model output.
+
+Every result includes the answer, interpretation, assumptions, generated and executed SQL, dbt nodes,
+columns, relevant test health, bounded evidence, evidence-linked claims, verification outcomes,
+manifest and agent fingerprints, model and warehouse identity, latency, and token usage. Terminal and
+web views expose “How this answer was formed” without separate flags.
+
+Eval correctness is determined by execution, scope, model/column expectations, result equality,
+reference-query matching, shape/count assertions, tolerance, and claim evidence. Eval creation uses the
+reviewed SQL as the default changing-data reference, runs it immediately, and writes a verification
+record. A live answer is labeled `VERIFIED` only when its exact normalized question matches an approved
+eval case and all hard checks pass; otherwise it is visibly `UNVERIFIED` and exits nonzero.
+
+See the dbt-generated [reference project](examples/dbt-analytics/README.md) and the
+[workflow guide](docs/getting-started.md).
+
+## Commands
+
+- `tabletalk init`
+- `tabletalk agent create|list|show`
+- `tabletalk eval create|run`
+- `tabletalk ask`
+- `tabletalk doctor`
+
+There is no compile/plan/apply lifecycle or applied-artifact authorization state. Source changes are
+active immediately and reproducibility records live under `.tabletalk/runs` and
+`.tabletalk/eval-results`.

tabletalk-0.5.0/README.md

@@ -0,0 +1,75 @@
+# TableTalk
+
+TableTalk is an evaluation and observability framework for natural-language agents built on existing
+dbt projects. `manifest.json` is the complete authority for what an agent may query; warehouse
+connections are read-only execution adapters for those dbt relations.
+
+## Start from a dbt project
+
+```console
+cd my-dbt-project
+dbt parse
+dbt docs generate  # recommended: adds physical warehouse types
+tabletalk init
+tabletalk agent create
+tabletalk eval create revenue
+tabletalk eval run revenue
+tabletalk ask revenue "What was recognized revenue last month?"
+```
+
+`tabletalk init` finds `dbt_project.yml` and `target/manifest.json`, resolves a supported SQLite,
+DuckDB, or Snowflake target from the dbt profile, and writes only non-secret TableTalk settings.
+Agent creation asks the user to choose a displayed dbt group, tag, model, path, package, or source and
+whether to include lineage. It previews the exact resolved models, descriptions, catalog types, tests,
+constraints, and lineage before writing a small selector-based resource. Raw selectors remain available
+for automation.
+
+```yaml
+name: revenue
+description: Answers questions about recognized revenue.
+select:
+  - group:finance
+  - tag:revenue
+exclude:
+  - model:customer_sensitive
+instructions:
+  - Use recognized revenue unless the user explicitly requests bookings.
+sample_questions:
+  - What was recognized revenue last month?
+```
+
+Descriptions, columns, tests, constraints, ownership, access, tags, and lineage stay in dbt. They are
+never duplicated into an agent file.
+
+## Correctness and provenance
+
+Live questions and eval cases call the exact same `Runtime.answer` path. Before execution, TableTalk
+parses generated SQL and requires one read-only query, in-scope manifest relations, known columns,
+explicit join conditions, row and timeout limits, and explicit sensitive-data permission. It derives
+used dbt nodes and columns from that parsed SQL—not from model output.
+
+Every result includes the answer, interpretation, assumptions, generated and executed SQL, dbt nodes,
+columns, relevant test health, bounded evidence, evidence-linked claims, verification outcomes,
+manifest and agent fingerprints, model and warehouse identity, latency, and token usage. Terminal and
+web views expose “How this answer was formed” without separate flags.
+
+Eval correctness is determined by execution, scope, model/column expectations, result equality,
+reference-query matching, shape/count assertions, tolerance, and claim evidence. Eval creation uses the
+reviewed SQL as the default changing-data reference, runs it immediately, and writes a verification
+record. A live answer is labeled `VERIFIED` only when its exact normalized question matches an approved
+eval case and all hard checks pass; otherwise it is visibly `UNVERIFIED` and exits nonzero.
+
+See the dbt-generated [reference project](examples/dbt-analytics/README.md) and the
+[workflow guide](docs/getting-started.md).
+
+## Commands
+
+- `tabletalk init`
+- `tabletalk agent create|list|show`
+- `tabletalk eval create|run`
+- `tabletalk ask`
+- `tabletalk doctor`
+
+There is no compile/plan/apply lifecycle or applied-artifact authorization state. Source changes are
+active immediately and reproducibility records live under `.tabletalk/runs` and
+`.tabletalk/eval-results`.

{tabletalk-0.2.1 → tabletalk-0.5.0}/docs/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= ../.venv/bin/sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 

tabletalk-0.5.0/docs/architecture.md

@@ -0,0 +1,28 @@
+# Runtime safety and architecture
+
+Every live and eval question follows one pipeline:
+
+```text
+manifest → resolved agent scope → interpretation/SQL → AST validation
+         → read-only connector → evidence rows → answer/claims → trace verification
+```
+
+`manifest.py` owns artifact normalization, selection, graph navigation, and fingerprints. `agents.py`
+contains only selector resources and resolved in-memory scopes. `validation.py` parses SQL and derives
+actual model/column use. `connections.py` resolves the selected dbt target and exposes only read-only
+query execution. `runtime` constructs the answer and shared trace. `evals` calls that exact runtime and
+adds deterministic comparisons. `traces.py` persists one schema for live and eval records.
+
+Validation rejects multiple statements, writes/commands, forbidden external-read functions,
+out-of-scope or ambiguous relations, unknown columns, unconditioned joins, excessive limits, and
+unapproved sensitive resources. Connector permissions remain the final security boundary.
+
+Lineage proves dependency, not semantic join correctness. TableTalk never labels a join verified merely
+because two nodes share a lineage edge. Safe join evidence belongs in dbt constraints, relationship
+tests, explicit `meta`, and passing eval coverage.
+
+Post-execution verification requires successful execution and validates every claim’s row/column
+evidence. Numeric claims must appear in cited result cells. Correctness additionally requires an exact
+approved eval-question match and passing deterministic comparisons. Reported models and columns always
+come from the validated AST. Trace records hold fingerprints and identities, not credentials or
+deployment state.

tabletalk-0.5.0/docs/commands.md

@@ -0,0 +1,16 @@
+# Commands
+
+- `tabletalk init`: initialize from `dbt_project.yml`, a parsed manifest, and a dbt target.
+- `tabletalk agent create`: guided selector preview and agent authoring.
+- `tabletalk agent list`: list source agents and resolved model counts.
+- `tabletalk agent show NAME`: show source, resolved node IDs, fingerprint, and warnings.
+- `tabletalk eval create NAME`: execute and approve a question/reference case.
+- `tabletalk eval run [NAME] [--case CASE] [--trials N]`: run deterministic hard-gate evals and
+  optionally override the suite's independent-trial count.
+- `tabletalk ask NAME QUESTION`: answer (quoted or unquoted), show provenance, and require passing exact eval coverage for a
+  `VERIFIED` status.
+- `tabletalk doctor`: fail on artifact, target, connectivity, selector, or eval-coverage blockers and
+  report incomplete dbt descriptions as non-blocking metadata warnings.
+
+`compile`, `plan`, `apply`, `connect`, `discover`, `connections`, and registry-style `agents` commands
+were removed. A source agent is active immediately and asking never depends on applied state.

tabletalk-0.5.0/docs/conf.py

@@ -0,0 +1,48 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -------------------------------------------------------
+
+project = "tabletalk"
+copyright = "2025, william bates"
+author = "william bates"
+release = "0.5.0"
+
+# -- General configuration -----------------------------------------------------
+
+extensions = [
+    "myst_parser",
+]
+
+# MyST parser settings — enable common markdown extensions
+myst_enable_extensions = [
+    "colon_fence",  # ::: fenced directives
+    "deflist",  # definition lists
+    "tasklist",  # - [ ] checkboxes
+]
+
+# Auto-generate anchors for headings up to level 3 (enables #anchor-name links)
+myst_heading_anchors = 3
+
+# Use index.md as the root document
+root_doc = "index"
+
+source_suffix = {
+    ".md": "markdown",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_theme = "alabaster"
+html_static_path = []
+
+html_theme_options = {
+    "description": "dbt-native evaluation and observability for natural-language agents",
+    "github_user": "wtbates99",
+    "github_repo": "tabletalk",
+    "github_button": True,
+    "fixed_sidebar": True,
+}

tabletalk-0.5.0/docs/configuration.md

@@ -0,0 +1,48 @@
+# Configuration and resources
+
+`tabletalk.yaml` is intentionally small:
+
+```yaml
+dbt:
+  project_dir: .
+  manifest: target/manifest.json
+  catalog: target/catalog.json
+  run_results: target/run_results.json
+  target: dev
+
+llm:
+  provider: ollama
+  model: gemma4:31b-cloud
+  base_url: http://localhost:11434/v1
+```
+
+Commands first look for `tabletalk.yaml` in the current directory, then for
+`tabletalk/tabletalk.yaml`. This keeps TableTalk in its own repository folder without requiring a
+`--project-folder` option on every command.
+
+`project_dir`, `manifest`, and optional `profiles_dir` paths are relative to `tabletalk.yaml`. The dbt
+target remains in `profiles.yml`; environment variables are resolved only at runtime. Supported
+adapters are SQLite, DuckDB, and Snowflake, all opened or governed as read-only.
+
+Agents support only `group:`, `tag:`, `model:`, `source:`, `path:`, and `package:` selectors plus exclusions.
+`include_parents` and `include_children` are explicit booleans. Ephemeral and disabled models are not
+queryable. Sources require an explicit `source:SOURCE.TABLE` selector; lineage expansion never grants
+source access. Physical relation names must resolve to one dbt unique ID in the agent scope.
+
+`instructions` documents business rules the manifest cannot express, while `reject_if_contains`
+provides a small deterministic guardrail for known concepts that the selected dbt resources cannot
+answer. Rejections happen before an LLM call and should be used sparingly for unambiguous missing-data
+boundaries, not as a general intent router.
+
+Optional `catalog.json` enriches physical types and statistics; optional `run_results.json` adds recent
+dbt-test health. Neither can add queryable resources. The manifest fingerprint changes with any
+manifest content change and is included in every run; the catalog has its own fingerprint. `tabletalk
+init` detects both artifacts beside the manifest automatically.
+
+The model prompt receives each selected resource's relation, description, physical catalog types,
+column descriptions, tests, constraints, owner, access, materialization, package, explicit join
+metadata, and upstream/downstream lineage. Lineage is provenance, never automatic join permission.
+
+Sensitive models use `meta: {sensitive: true}`; sensitive columns use column-level
+`meta: {sensitive: true}` or model `meta.sensitive_columns`. The agent must explicitly list allowed dbt
+unique IDs or column names under `allow_sensitive`.

tabletalk-0.5.0/docs/contributing.md

@@ -0,0 +1,29 @@
+# Contributing
+
+TableTalk requires Python 3.10+ and uses `uv`:
+
+```console
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run mypy tabletalk
+```
+
+The acceptance fixture is a real dbt project under `examples/dbt-analytics`. When its dbt resources
+change, regenerate the checked-in artifact instead of hand-editing it:
+
+```console
+cd examples/dbt-analytics
+uv run dbt deps
+uv run dbt parse --profiles-dir . --no-partial-parse
+uv run dbt docs generate --profiles-dir .
+```
+
+Keep these boundaries intact: manifest selection is the only source of query scope; database
+introspection cannot add resources; all live and eval questions use `Runtime.answer`; model and column
+usage comes from parsed SQL; result comparison is the hard correctness gate; and persisted records are
+observability evidence, never deployment authorization.
+
+Tests should cover manifest selection, SQL safety/scope, connectors, deterministic comparisons,
+evidence-linked traces, and the complete dbt → agent → eval → ask journey. Snowflake behavior should use
+a mocked connector contract unless a test is explicitly marked for live credentials.

tabletalk-0.5.0/docs/evals.md

@@ -0,0 +1,49 @@
+# Execution-based evals
+
+Suites may declare `kind: regression|capability`, a human-readable `description`, and `trials: 1..20`.
+Regression suites are expected to remain nearly perfect; capability suites hold harder tasks with room
+to improve. Repeated trials are persisted separately, all must pass for the command to succeed, and the
+terminal reports aggregate trial pass rate.
+
+Create evals interactively with `tabletalk eval create AGENT`. The default is the generated SQL the
+user just reviewed, so changing warehouse data is compared by executing candidate and golden queries
+against the same snapshot. The proposed case runs immediately and automated authoring refuses to save
+an already-failing case. Literal rows remain available for stable fixtures and CI.
+
+```yaml
+name: revenue-regression
+agent: revenue
+cases:
+  - name: july-revenue
+    question: What was recognized revenue in July 2026?
+    expect:
+      reference_sql: |
+        select sum(recognized_revenue) as recognized_revenue
+        from {{ ref('fct_orders') }}
+        where order_date >= '2026-07-01'
+          and order_date < '2026-08-01'
+      result:
+        comparison: scalar
+        tolerance: 0.01
+      models:
+        required: [model.analytics.fct_orders]
+      columns:
+        required: [recognized_revenue, order_date]
+```
+
+Result modes are `scalar`, `ordered`, `ordered_values`, `unordered`, and `keyed`; keyed comparisons
+require `keys`. `ordered_values` deliberately ignores presentation-only aliases while preserving row
+and value order.
+Expectations may also include literal `value` or `rows`, `row_count`, exact result `columns`, forbidden
+models/columns, `allow_extra_columns: true` for harmless additional evidence fields, and
+`outcome: ambiguity|rejection`. Reference SQL supports only dbt `ref()` templating,
+is parsed with the same read-only scope validator, and executes against the same warehouse snapshot.
+
+Hard gates are execution, SQL safety/scope, expected models/columns, expected rejection, result
+comparison and tolerance, shape/count, and evidence-linked claims. Latency and token usage are recorded
+but informational. Empty literal row sets are enforced rather than treated as a missing expectation.
+Results are written to `.tabletalk/eval-results/AGENT` and failures exit with code 3.
+
+Live correctness uses exact normalized question matching, not semantic guesswork. A covered question is
+`VERIFIED` only when every hard gate passes. Uncovered questions still return their inspectable trace,
+but are labeled `UNVERIFIED` and exit with code 4.

tabletalk-0.5.0/docs/getting-started.md

@@ -0,0 +1,38 @@
+# Get started
+
+TableTalk starts with a parsed, runnable dbt project. It does not discover arbitrary database tables.
+
+```console
+cd my-dbt-project
+dbt parse
+dbt docs generate
+tabletalk init
+```
+
+Initialization finds the dbt project and manifest, reads the project profile, asks for a target, checks
+that its adapter is SQLite, DuckDB, or Snowflake, summarizes dbt version/models/groups/tags, and writes
+`tabletalk.yaml`. Credentials stay in environment variables and `profiles.yml`.
+
+Create an agent from dbt selectors:
+
+```console
+tabletalk agent create
+```
+
+Choose a displayed dbt group, tag, model, path, package, or source, then choose whether to include its
+lineage. The guided preview shows exact resources, catalog types, tests, constraints, and metadata gaps.
+Create the first eval when prompted. TableTalk shows the interpretation and SQL before read-only
+execution, uses that reviewed SQL as the default golden query, verifies it immediately, and saves both
+the case and result record.
+
+```console
+tabletalk eval run revenue
+tabletalk ask revenue "What was recognized revenue last month?"
+```
+
+Both commands use the same runtime. `ask` prints `VERIFIED` only for an exact normalized question match
+against an approved, passing eval; new or changed questions print `UNVERIFIED` and exit nonzero. Run
+`tabletalk doctor` in CI or locally to detect missing/stale
+artifacts, unsupported targets, connectivity failures, broken selectors, metadata gaps, and uncovered
+agents. Metadata gaps are warnings; conditions that prevent safe or verified execution fail the command.
+The complete runnable journey is in `examples/dbt-analytics`.