Metadata-Version: 2.4
Name: dt-ai-toolkit
Version: 0.2.4
Summary: Data-team toolkit for building, interacting with, and improving data projects with coding agents
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: claude-agent-sdk>=0.1
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: textual>=8
Requires-Dist: typer<0.27,>=0.26
Provides-Extra: turso
Requires-Dist: libsql>=0.1.11; extra == 'turso'
Description-Content-Type: text/markdown

# dt-ai-toolkit

**A CLI that gets a whole data team working with coding agents the same way.**

If your team uses [Claude Code](https://claude.com/claude-code) for data work, every
teammate ends up solving the same problems by hand: how to lay out a project so an agent
can work in it, which skills to give the agent, how to run repeatable agent workflows, and
how to turn analysis into a polished PDF. `dt-ai-toolkit` packages those answers into one
installable tool — run `dat setup` in a fresh directory and a teammate gets the same
agent-ready project, curated skills, and report pipeline as everyone else.

## What it does

- **Scaffolds agent-ready data projects** — standard folders (`data/`, `reports/`,
  `sandbox/`), a managed `.gitignore`, and tool installs, customizable per team via a
  TOML profile.
- **Installs curated Agent Skills** — a bundled set focused on data honesty (profiling
  datasets before trusting them, critiquing charts and talking points), plus install from
  any local folder or git repo, with provenance tracking.
- **Runs agent workflows** — repeatable flows via the Claude Agent SDK, defined as plain
  markdown files with YAML frontmatter. Bundled flows included; write your own in minutes.
- **Generates real reports** — scaffolds a React TSX → HTML → PDF pipeline so agent
  output can ship as a formatted document, not a wall of markdown.
- **Evaluates skills & agents in a gym** — run curated tasks against a skill or agent in
  an isolated sandbox, score the transcript with an LLM judge, or A/B two targets
  head-to-head (`dat gym run` / `dat gym ab` / `dat gym manage`). Makes real API calls.
- **Chat-edits everything with the agent of your choice** — every record in the manage
  TUIs can be built or edited in an interactive coding-agent chat (multi-line block paste,
  split-screen live preview, `/copy` to clipboard), backed by Claude (pick model + effort
  per session, up to `fable`) or any CLI coding agent you register (`dat providers`).
- **Keeps everyone unblocked** — `dat doctor` checks the whole environment (uv, git,
  claude CLI, auth, bun, playwright) and `dat docs` is a built-in interactive docs browser.

Agents, skills, and setup profiles live in a local SQLite database, so teams can inspect,
edit, back up, and share their configuration (`dat db info`, `dat agent backup` /
`restore`, and the same for skills and profiles).

## Install

```bash
# no install needed — run it straight from PyPI
uvx dt-ai-toolkit --help

# or install it once and get the short `dat` command
uv tool install dt-ai-toolkit

# prefer not to install? alias `dat` to uvx in your shell config instead
uvx dt-ai-toolkit alias
```

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/). Every `dat ...` command below
also works as `uvx dt-ai-toolkit ...`.

## Quickstart

```bash
dat db setup       # one-time: create the toolkit database, seed bundled content

mkdir my-project && cd my-project
dat setup          # folders + gitignore + installs Claude Code & omnigent
dat doctor         # verify the environment
dat docs           # interactive docs browser
```

## Commands

| command | what it does |
|---|---|
| `setup` | Scaffold a data project (`data/`, `reports/`, `sandbox/`, managed .gitignore block) and install tooling. Customizable via a `dt-setup.toml` profile (`setup config init`). |
| `skills` | Install Agent Skills into `.claude/skills/` from the curated set, a local folder, or a git repo. `list` / `install` / `update` with provenance tracking. |
| `agent` | Run agent flows via the Claude Agent SDK: bundled `sourcing-report` and `project-review`, or your own frontmatter-markdown agent files. |
| `report` | Scaffold the React TSX → HTML/PDF report pipeline (`report new <name>`). |
| `gym` | Evaluate, run, and A/B test skills & agents against curated tasks with an LLM judge (`gym run` / `gym ab` / `gym manage`). |
| `db` | Manage the toolkit database — the source of truth for agents, skills, and setup profiles. `setup` / `info` / `path` / `upgrade-backup`. |
| `providers` | Configure which agents back the interactive chats: `claude` built in, plus any coding-agent CLI (opencode, pi, ...) via `providers.toml` — `list` / `init` / `manage`. |
| `doctor` | Check the environment: uv, git, claude CLI, omnigent, auth, bun, playwright. |
| `alias` | Write a `dat` alias into your shell config (bash, zsh, fish, PowerShell) so `dat` works without a tool install. |
| `docs` | Browse documentation — an interactive TUI, or `--plain` / `show <topic>` / `export` for non-interactive use. |

## Bundled skills

The curated skills lean toward *data honesty* — making sure what an agent (or you)
produces can survive scrutiny:

- **interrogate-data** — structured protocol for profiling and stress-testing a dataset before trusting it
- **critique-talking-points** — adversarial claim-by-claim review of narratives before they ship
- **critique-visualization** — chart-honesty review, including re-deriving plotted values from source data
- **tsx-report-generator** — walks Claude through the full TSX → HTML/PDF report pipeline
- **dt-setup-config** — helps Claude build a custom `dt-setup.toml` for your team
- **dt-ai-toolkit** — meta skill teaching Claude how to call this CLI itself (`uvx dt-ai-toolkit ...`)
- **grill-me** — Socratic quiz rounds that test *your* understanding of a dataset, pipeline, or report before someone else does

```bash
dat skills list                        # the toolkit-db catalog (what you install from)
dat skills install                     # install every db skill (idempotent sync)
dat skills install interrogate-data    # a single db skill by name
dat skills installed                   # what's installed in this project
dat skills install https://github.com/your-org/team-skills.git --all
```

## Custom agent flows

Agents are markdown files with YAML frontmatter — config on top, prompt below,
`{placeholders}` filled from the command line:

```markdown
---
name: data-audit
description: Audit a dataset for quality issues
allowed_tools: [Read, Glob, Grep, Bash]
args:
  data_path: {required: true}
---
Audit the dataset at {data_path}. Cite the query behind every finding.
```

```bash
dat agent run data-audit.md --arg data_path=data/sales.csv
dat agent run sourcing-report --arg topic="Q3 readmissions" --dry-run
```

## Development

```bash
uv sync
uv run pytest
uv run dat --help
```

See `CLAUDE.md` for architecture conventions.
