dt-ai-toolkit 0.1.0__tar.gz

dt_ai_toolkit-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+plans/

dt_ai_toolkit-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

dt_ai_toolkit-0.1.0/CLAUDE.md

@@ -0,0 +1,57 @@
+# dt-ai-toolkit
+
+A Typer CLI published to PyPI as `dt-ai-toolkit`, run by teammates via `uvx dt-ai-toolkit`.
+It helps a data team set up Claude-ready data projects (`setup`), install curated Agent
+Skills (`skills`), run agent flows via the Claude Agent SDK (`agent`), scaffold the TSX ->
+HTML/PDF report pipeline (`report`), check the environment (`doctor`), and browse docs
+(`docs`, a Textual TUI).
+
+## Tooling
+
+uv only — never pip:
+
+- `uv sync` — install deps (dev group included)
+- `uv run dt-ai-toolkit ...` — run the CLI
+- `uv run pytest` — run tests
+- `uvx --from . dt-ai-toolkit ...` — end-to-end check of the packaged entry point
+- `uv add <pkg>` / `uv add --dev <pkg>` — manage dependencies
+
+## Architecture rules
+
+- `src/dt_ai_toolkit/commands/` — thin Typer layers: argument parsing and console output only.
+- `src/dt_ai_toolkit/core/` — pure logic; **no typer imports** (keeps it unit-testable).
+- `src/dt_ai_toolkit/data/` — package data (bundled skills, agent defs, templates, docs
+  guides); access only via `core/resources.py` (`importlib.resources`), never relative paths.
+- `src/dt_ai_toolkit/tui/` — Textual app(s); consume plain dataclasses from core, no typer.
+- All console output goes through `dt_ai_toolkit.console` (`console` / `err_console`).
+
+## Conventions
+
+- Python floor is 3.11 — no 3.12+-only syntax. `.python-version` (3.14) is just the dev interpreter.
+- pathlib everywhere; dataclasses over pydantic.
+- Every action that executes commands or overwrites files: print what will happen, require
+  confirmation unless `--yes`, and support `--dry-run`. Never overwrite without `--force`.
+- Windows: core logic must not assume POSIX; install steps support `windows_command`.
+- typer is pinned to a minor version because `core/cli_introspect.py` walks
+  `typer.main.get_group(app)` (private-ish API; vendored click since typer 0.26). Never
+  `isinstance` against real `click` objects. A canary test covers this.
+
+## Key formats (sources of truth)
+
+- Setup profile TOML schema: `src/dt_ai_toolkit/data/setup/example.toml` (annotated).
+- Skill format: `.claude/skills/<name>/SKILL.md`, YAML frontmatter `name` + `description`.
+- Agent definition: frontmatter markdown; the frontmatter -> `ClaudeAgentOptions` mapping
+  lives in `core/agent_defs.py`.
+- Skill provenance lockfile: `.claude/skills/.dt-skills.json`.
+
+## Testing
+
+- pytest with `tmp_path`; CLI via `typer.testing.CliRunner`.
+- Tests never hit the network or the Anthropic API; subprocess and the Agent SDK are mocked.
+- Git-install tests use a local `git init` fixture repo (real git, no network).
+
+## Release
+
+1. Bump `__version__` in `src/dt_ai_toolkit/__init__.py` and `version` in `pyproject.toml` together.
+2. `uv build`, smoke-test the wheel (`uvx --from dist/<wheel> dt-ai-toolkit doctor`).
+3. `uv publish` (only when the user asks), then tag `v<version>`.

dt_ai_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Wiley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dt_ai_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: dt-ai-toolkit
+Version: 0.1.0
+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: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: textual>=8
+Requires-Dist: typer<0.27,>=0.26
+Description-Content-Type: text/markdown
+
+# dt-ai-toolkit
+
+A data-team toolkit for building, interacting with, and improving data projects
+with coding agents. One install (uv) gets a teammate a Claude-ready project,
+curated Agent Skills, runnable agent flows, and a PDF report pipeline.
+
+```bash
+# no install needed — run it straight from PyPI
+uvx dt-ai-toolkit --help
+```
+
+## Quickstart
+
+```bash
+mkdir my-project && cd my-project
+uvx dt-ai-toolkit setup          # folders + gitignore + installs Claude Code & omnigent
+uvx dt-ai-toolkit doctor         # verify the environment
+uvx dt-ai-toolkit 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 bundled 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>`). |
+| `doctor` | Check the environment: uv, git, claude CLI, omnigent, auth, bun, playwright. |
+| `docs` | Browse documentation — a Textual TUI, or `--plain` / `show <topic>` / `export` for non-interactive use. |
+
+## Bundled skills
+
+- **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
+uvx dt-ai-toolkit skills list --available
+uvx dt-ai-toolkit skills install interrogate-data
+uvx dt-ai-toolkit 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
+dt-ai-toolkit agent run data-audit.md --arg data_path=data/sales.csv
+dt-ai-toolkit agent run sourcing-report --arg topic="Q3 readmissions" --dry-run
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run dt-ai-toolkit --help
+```
+
+See `CLAUDE.md` for architecture conventions.

dt_ai_toolkit-0.1.0/README.md

@@ -0,0 +1,77 @@
+# dt-ai-toolkit
+
+A data-team toolkit for building, interacting with, and improving data projects
+with coding agents. One install (uv) gets a teammate a Claude-ready project,
+curated Agent Skills, runnable agent flows, and a PDF report pipeline.
+
+```bash
+# no install needed — run it straight from PyPI
+uvx dt-ai-toolkit --help
+```
+
+## Quickstart
+
+```bash
+mkdir my-project && cd my-project
+uvx dt-ai-toolkit setup          # folders + gitignore + installs Claude Code & omnigent
+uvx dt-ai-toolkit doctor         # verify the environment
+uvx dt-ai-toolkit 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 bundled 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>`). |
+| `doctor` | Check the environment: uv, git, claude CLI, omnigent, auth, bun, playwright. |
+| `docs` | Browse documentation — a Textual TUI, or `--plain` / `show <topic>` / `export` for non-interactive use. |
+
+## Bundled skills
+
+- **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
+uvx dt-ai-toolkit skills list --available
+uvx dt-ai-toolkit skills install interrogate-data
+uvx dt-ai-toolkit 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
+dt-ai-toolkit agent run data-audit.md --arg data_path=data/sales.csv
+dt-ai-toolkit agent run sourcing-report --arg topic="Q3 readmissions" --dry-run
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run dt-ai-toolkit --help
+```
+
+See `CLAUDE.md` for architecture conventions.

dt_ai_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "dt-ai-toolkit"
+version = "0.1.0"
+description = "Data-team toolkit for building, interacting with, and improving data projects with coding agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.26,<0.27",
+    "rich>=13",
+    "textual>=8",
+    "claude-agent-sdk>=0.1",
+    "pyyaml>=6",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+dt-ai-toolkit = "dt_ai_toolkit.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dt_ai_toolkit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]

dt_ai_toolkit-0.1.0/src/dt_ai_toolkit/__init__.py

@@ -0,0 +1,3 @@
+"""dt-ai-toolkit: data-team toolkit for agent-assisted data projects."""
+
+__version__ = "0.1.0"

dt_ai_toolkit-0.1.0/src/dt_ai_toolkit/cli.py

@@ -0,0 +1,43 @@
+"""Root Typer app wiring all sub-apps."""
+
+from typing import Annotated
+
+import typer
+
+from dt_ai_toolkit import __version__
+from dt_ai_toolkit.commands import agent, docs, doctor, report, setup, skills
+from dt_ai_toolkit.console import console
+
+app = typer.Typer(
+    name="dt-ai-toolkit",
+    help="Data-team toolkit for building, interacting with, and improving data projects with coding agents.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+app.add_typer(setup.app, name="setup")
+app.add_typer(skills.app, name="skills")
+app.add_typer(agent.app, name="agent")
+app.add_typer(report.app, name="report")
+app.command(name="doctor", help=doctor.HELP)(doctor.doctor)
+app.add_typer(docs.app, name="docs")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"dt-ai-toolkit {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version and exit."),
+    ] = False,
+) -> None:
+    pass
+
+
+if __name__ == "__main__":
+    app()

dt_ai_toolkit-0.1.0/src/dt_ai_toolkit/commands/agent.py

@@ -0,0 +1,123 @@
+"""`agent` sub-app: run agent flows via the Claude Agent SDK."""
+
+import asyncio
+import shutil
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.panel import Panel
+
+from dt_ai_toolkit.console import console, err_console
+from dt_ai_toolkit.core import resources
+from dt_ai_toolkit.core.agent_defs import AgentSpecError, parse_agent_spec, resolve_agent
+
+app = typer.Typer(
+    help="Run agent flows (built-in or your own frontmatter-markdown files).", no_args_is_help=True
+)
+
+
+@app.command("list")
+def list_() -> None:
+    """List bundled agent flows."""
+    for name in resources.bundled_agent_names():
+        spec = parse_agent_spec(resources.read_bundled_agent(name), source=name)
+        console.print(f"[bold]{name}[/bold] — {spec.description}")
+    console.print(
+        "\n[dim]run one:      dt-ai-toolkit agent run <name> --arg key=value"
+        "\nor your own:  dt-ai-toolkit agent run path/to/agent.md[/dim]"
+    )
+
+
+def _parse_args(pairs: list[str] | None) -> dict[str, str]:
+    parsed = {}
+    for pair in pairs or []:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            raise AgentSpecError(f"--arg must be key=value, got {pair!r}")
+        parsed[key] = value
+    return parsed
+
+
+@app.command()
+def show(
+    name_or_path: Annotated[str, typer.Argument(help="Bundled agent name or path to an agent .md file.")],
+) -> None:
+    """Show an agent definition: description, options, and declared args."""
+    try:
+        spec = resolve_agent(name_or_path)
+    except AgentSpecError as exc:
+        err_console.print(str(exc))
+        raise typer.Exit(code=1) from exc
+    console.print(f"[bold]{spec.name}[/bold] — {spec.description}")
+    console.print(f"source: {spec.source}")
+    if spec.options:
+        console.print("options:")
+        for key, value in spec.options.items():
+            console.print(f"  {key}: {value}")
+    if spec.args:
+        console.print("args:")
+        for arg_name, arg in spec.args.items():
+            req = "[red]required[/red]" if arg.required else f"default: {arg.default!r}"
+            console.print(f"  {arg_name} ({req}) {arg.help}")
+    console.print(Panel(spec.body.strip(), title="prompt template"))
+
+
+@app.command()
+def run(
+    name_or_path: Annotated[str, typer.Argument(help="Bundled agent name or path to an agent .md file.")],
+    arg: Annotated[list[str] | None, typer.Option("--arg", "-a", help="Prompt args as key=value (repeatable).")] = None,
+    model: Annotated[str | None, typer.Option("--model", help="Override the model.")] = None,
+    max_turns: Annotated[int | None, typer.Option("--max-turns", help="Override max turns.")] = None,
+    permission_mode: Annotated[str | None, typer.Option("--permission-mode", help="Override the permission mode.")] = None,
+    cwd: Annotated[Path | None, typer.Option("--cwd", help="Working directory for the agent.")] = None,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Print the final prompt and options; no API call.")] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show thinking and tool results.")] = False,
+    dangerously_allow_all: Annotated[
+        bool, typer.Option("--dangerously-allow-all", help="Permit permission_mode: bypassPermissions.")
+    ] = False,
+) -> None:
+    """Run an agent flow and stream its progress."""
+    try:
+        spec = resolve_agent(name_or_path)
+        prompt = spec.render_prompt(_parse_args(arg))
+        overrides = {
+            "model": model,
+            "max_turns": max_turns,
+            "permission_mode": permission_mode,
+            "cwd": str(cwd) if cwd else None,
+        }
+        options = spec.build_options(overrides, allow_bypass=dangerously_allow_all)
+    except AgentSpecError as exc:
+        err_console.print(str(exc))
+        raise typer.Exit(code=1) from exc
+
+    if dry_run:
+        console.print(Panel(prompt, title=f"prompt — {spec.name}"))
+        console.print(Panel(_describe_options(options), title="ClaudeAgentOptions"))
+        return
+
+    if shutil.which("claude") is None:
+        err_console.print(
+            "the `claude` CLI is required to run agents.\n"
+            "install it with `dt-ai-toolkit setup` (or check `dt-ai-toolkit doctor`)."
+        )
+        raise typer.Exit(code=1)
+
+    from dt_ai_toolkit.core.agent_runner import run_agent
+
+    console.print(f"[bold]running {spec.name}[/bold] [dim]({spec.source})[/dim]\n")
+    outcome = asyncio.run(run_agent(prompt, options, console, verbose=verbose))
+    if outcome.is_error:
+        raise typer.Exit(code=1)
+
+
+def _describe_options(options) -> str:
+    import dataclasses
+
+    lines = []
+    for f in dataclasses.fields(options):
+        value = getattr(options, f.name)
+        if value not in (None, [], {}, False):
+            lines.append(f"{f.name}: {value}")
+    return "\n".join(lines)