dataface 0.1.2__py3-none-any.whl

dataface/ai/skills/dashboard-structural-review/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: dashboard-structural-review
+kind: workflow
+description: >
+  Review a Dataface face's YAML structure and content choices without rendering.
+  Reads the face file, runs schema validation, then evaluates the YAML against
+  a design checklist (chart-data shape match, layout intent, variable wiring,
+  descriptive naming, anti-patterns). Use when asked to 'review this
+  dashboard', 'check this face', 'is this YAML well-shaped', 'find problems in
+  this dashboard', or after editing a face before delivery. Cheap — no
+  rendering, no PNG, no LLM judge in the loop. Do NOT use for visual problems
+  that need to be seen (use dashboard-visual-review). Do NOT use as a YAML
+  linter substitute — schema validation already covers that.
+metadata:
+  author: fivetran
+---
+
+# Dashboard Structural Review
+
+Read the face's YAML, run `{{ s_validate_dashboard }}`,
+then evaluate the design choices encoded in the YAML against a checklist.
+Produces a markdown findings list with severity tags. No rendering required —
+this is the cheap pass.
+
+## When to use
+
+- Post-build sanity check before delivering a new face
+- Post-edit verification after adding charts, queries, or variables
+- Pre-PR review of a face change
+- First pass inside the `dashboard-review` orchestrator
+
+## When NOT to use
+
+- Schema validation alone — `{{ s_validate_dashboard }}`
+  is the right tool, this skill calls it
+- Visual problems ("the legend is overlapping the title") — use
+  `dashboard-visual-review`
+- Comparing two versions of a face — use `looker-compare-diff` pattern instead
+
+## Protocol
+
+1. **Validate.** Run `{{ s_validate_dashboard }}`
+   on the face path:
+
+   {{ s_validate_example }}
+
+   If validation reports errors, surface them and stop — there's nothing to
+   review until the schema is valid.
+
+2. **Read the face YAML** with the agent's file-reading tool.
+
+3. **Evaluate against the checklist below.** For each finding, emit a row with
+   severity, the YAML path or chart name, and a concrete fix.
+
+## Checklist
+
+### Layout intent
+
+- [ ] Top of the face is a summary (KPI row, hero metric) — not a detail table
+- [ ] Reading order (top-down, left-to-right) tells a story: headline → trend →
+      breakdowns → detail
+- [ ] Related charts are grouped (same `cols:` row or adjacent rows)
+- [ ] No more than 8 visualizations on one face
+
+### Chart-data shape match
+
+- [ ] `type: kpi` queries return **exactly 1 row** (aggregate, not raw)
+- [ ] `type: pie` queries are pre-aggregated and have **2–3 segments** (use
+      `bar` for 4+)
+- [ ] `type: line` / `area` use a temporal x-axis
+- [ ] `type: bar` has a categorical x-axis (not a continuous date)
+- [ ] `type: table` columns make sense as a list — no 1-row tables, no
+      single-column tables that should be KPIs
+- [ ] No single-bar bar charts (one bar = use a KPI)
+
+### Variables and parameterization
+
+- [ ] Filters declared in `variables:` are referenced by at least one query
+- [ ] Queries don't hardcode values that should be variables (date ranges,
+      categorical filters)
+- [ ] Variable defaults are sensible (last 30 days, most common segment)
+- [ ] Executive / always-on dashboards have **no** filter variables
+
+### Descriptive metadata
+
+- [ ] Every query has a `description:` (what it returns and why)
+- [ ] Every chart has a `description:` (what question it answers)
+- [ ] Every variable has a `description:` (how it should be used)
+- [ ] Chart names communicate intent (`revenue_trend`, not `chart_1`)
+- [ ] Titles state what the chart answers (`"Revenue by Region, Last 30 Days"`,
+      not `"Sales"`)
+
+### Anti-patterns
+
+- [ ] No `kpi` displaying a string column (KPIs are numeric)
+- [ ] No chart that exists without a clear question it answers
+- [ ] No duplicated queries (same SQL repeated under different names)
+- [ ] No raw / unaggregated data feeding a chart that requires pre-aggregation
+
+### Formatting
+
+- [ ] No raw D3 format strings — use named presets (`currency_compact`, not `"$,.2s"`)
+- [ ] No explicit `format:` when auto-detection already produces the correct result (see auto-detection rules below)
+- [ ] Currency columns without `$`-triggering names (`arr`, `mrr`, `acv`, etc.) have an explicit `format: currency*` preset set
+- [ ] Integer columns where exact counts matter use `format: integer` (auto for large integers produces SI compact `~s`)
+
+**Preset reference**
+
+| Preset | D3 equivalent | Example |
+|--------|--------------|---------|
+| `integer` | `",.0f"` | `1,234` |
+| `number` | `",.2f"` | `1,234.56` |
+| `currency` | `"$,.2f"` | `$1,234.56` |
+| `currency_whole` | `"$,.0f"` | `$1,234` |
+| `currency_compact` | `"$,.2s"` | `$1.2M` |
+| `percent` | `".1%"` | `2.3%` |
+| `percent_whole` | `".0%"` | `2%` |
+| `percent_delta` | `"+.1%"` | `+2.3%` |
+| `compact` | `",.2s"` | `1.2M` |
+| `date_short` | `"%-d %b %Y"` | `26 May 2026` |
+
+**Auto-detection rules** (apply when no explicit `format:` is set)
+
+- Column name matches `*_pct`, `*_rate`, `*_ratio`, `*_share`, `*_proportion` → renders as `percent` (`.1%`)
+- Column name matches `*revenue*`, `*amount*`, `*cost*`, `*price*`, `*spend*`, `*profit*`, `*fee*` → renders as currency with `$`
+- Integer DB type + value ≥ 10K → SI compact `~s` (no `$`, no commas) — override with `format: integer` when exact counts matter
+- Integer DB type + value < 10K → `integer` format (`,.0f`)
+- Columns named `arr`, `mrr`, `acv`, etc. do **not** trigger currency auto-detection — always set an explicit `format: currency*` preset
+
+## Output format
+
+A markdown bulleted list, severity-tagged. Group by severity, most severe first:
+
+```markdown
+**Findings**
+
+- `blocker` `charts.revenue_kpi`: query returns 12 rows but `type: kpi` requires
+  exactly 1. Aggregate with `SUM()` or take the latest row only.
+- `warning` `charts.region_pie`: 7 segments in a pie chart — humans compare
+  angles poorly past 3. Switch to `type: bar` ordered by value.
+- `warning` `queries.orders`: no `description:` field. Add one sentence stating
+  what the query returns.
+- `nit` `charts.chart_1`: generic name. Rename to indicate intent
+  (e.g. `daily_active_users`).
+```
+
+If there are no findings: emit exactly `**No findings.**` so the orchestrator
+can short-circuit.
+
+## Severity rubric
+
+| Tag | Meaning | Examples |
+|---|---|---|
+| `blocker` | The face will render wrong, error, or mislead | KPI on multi-row query; bar chart on raw rows when GROUP BY is expected |
+| `warning` | The face renders but violates a clear design principle | Pie with >3 segments; missing descriptions; generic titles |
+| `nit` | Stylistic — author can take or leave | Suboptimal chart name; consistent-but-verbose pattern |
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Returning "looks fine" without validating first | Always run `{{ s_validate_dashboard }}` — if it fails, there's nothing to review |
+| Padding findings with `nit`-level noise | Cap at 5 findings total; promote the most severe |
+| Emitting findings without a concrete fix | Every finding needs an actionable suggestion |
+| Inventing rules not in the checklist | Stay anchored to the checklist; if you discover a real gap, file a follow-up to extend the skill |
+
+## Rationalizations to resist
+
+| Excuse | Reality |
+|---|---|
+| "The user knows what they're doing" | Reviewing is the job. Apply the checklist. |
+| "I'll just suggest the fix without the severity tag" | Severity is how the orchestrator ranks and the user prioritizes. Always tag. |
+| "If I can't find anything, I'll find something" | If the face passes the checklist, say so. Padding erodes the skill's signal. |

dataface/ai/skills/dashboard-visual-review/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: dashboard-visual-review
+kind: workflow
+description: >
+  Render a Dataface face to PNG and review the image against a visual-design
+  checklist using the agent's own vision capability. Catches problems that
+  YAML inspection can't see — overlapping text, contrast failures, axis-label
+  collisions, whitespace imbalance, KPI precision mismatches. Use when asked
+  to 'visually review', 'check how it looks', 'is this rendered correctly',
+  'review the rendered output', or when structural review surfaces ambiguous
+  'feels off but I can't say why' findings. More expensive than structural
+  review (rendering time + vision-token cost). Do NOT use for YAML schema or
+  data-shape problems (use dashboard-structural-review). Do NOT use for
+  comparing two versions of the same face (use the looker-compare-diff
+  pattern).
+metadata:
+  author: fivetran
+---
+
+# Dashboard Visual Review
+
+Render the face to PNG, then evaluate the image against a visual-design
+checklist. The agent host (Claude, GPT-4o, Gemini) provides the vision
+capability — no external API call.
+
+## When to use
+
+- Final pre-delivery polish pass
+- When structural review surfaces "feels wrong but I can't say why" findings
+- When the user reports a layout / readability complaint
+- Second pass inside the `dashboard-review` orchestrator after structural
+
+## When NOT to use
+
+- YAML schema or data-shape problems — use `dashboard-structural-review`
+- Comparing two versions of a face — out of scope for this skill
+- Pixel-exact regression testing — vision is the wrong tool; brittle
+
+## Protocol
+
+1. **Render the face to PNG.** Call `{{ s_render_dashboard }}`:
+
+   {{ s_render_png_example }}
+
+   If render fails, report the error and stop — there's nothing visual to
+   review.
+
+2. **Read the PNG** with the agent's image-loading capability.
+
+3. **Evaluate against the checklist below.** Emit findings in the same format
+   as `dashboard-structural-review` so the orchestrator can merge them.
+
+## Checklist
+
+### Visual hierarchy
+
+- [ ] Eye is drawn to the most important element first (largest KPI, headline
+      chart, top-left position)
+- [ ] Reading flow is top-down / left-to-right — no important data in
+      bottom-right that should be top-left
+- [ ] Whitespace separates groups without leaving large dead zones
+
+### Text legibility
+
+- [ ] No text overflow (clipped numbers, ellipsized labels that hide the value)
+- [ ] No wrap thrash (axis labels wrapping awkwardly mid-word)
+- [ ] Axis tick labels readable at rendered size (rotate if cramped)
+- [ ] Legend labels match the chart's encoding (no orphan legend entries)
+
+### Color and contrast
+
+- [ ] Foreground text meets WCAG AA contrast against its background
+- [ ] Color palette is consistent across charts (same series = same color)
+- [ ] No clashing or vibrating color pairs (red on green, complementary hues
+      at full saturation)
+- [ ] Conditional formatting communicates severity, not decoration
+
+### KPIs and numbers
+
+- [ ] KPI values render with appropriate precision (revenue in `$1.2M`, not
+      `1247392.7438`)
+- [ ] Units are consistent (don't mix `1,247` and `1.2K` in the same row)
+- [ ] Prior-period deltas have a sign and a directional cue (▲ / ▼ / color)
+- [ ] Currency / percent suffixes are present where expected
+
+### Composition and balance
+
+- [ ] No crammed corners — every chart has padding within its cell
+- [ ] Row heights match the visual weight of their content (KPIs short,
+      charts tall)
+- [ ] Tables don't overflow the page width (horizontal scroll only if
+      unavoidable)
+- [ ] Empty / null states render gracefully (no raw `None` or empty rectangles)
+
+## Output format
+
+Same shape as `dashboard-structural-review` so findings merge cleanly:
+
+```markdown
+**Findings**
+
+- `blocker` `charts.revenue_kpi`: KPI shows `1247392.74` — should be `$1.2M`.
+  Add `format: currency_compact` to the chart.
+- `warning` `charts.regions_bar`: x-axis labels overlap at rendered width.
+  Rotate to -45° or shorten labels.
+- `warning` `chart sequence`: revenue trend (most important) sits bottom-right
+  while a smaller breakdown sits top-left. Swap positions.
+- `nit` `charts.users_pie`: colors are vibrant and clash. Switch to a muted
+  qualitative palette.
+```
+
+If there are no findings: emit exactly `**No findings.**`.
+
+## Severity rubric
+
+Use the same tags as `dashboard-structural-review`:
+
+| Tag | Meaning |
+|---|---|
+| `blocker` | User cannot read or trust the rendered output |
+| `warning` | Renders, but violates a clear visual principle |
+| `nit` | Stylistic — author can take or leave |
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Reviewing without rendering | The PNG is the artifact under review — render first, no shortcuts |
+| Critiquing the YAML instead of the image | That's structural review's job — stay on visual signals only |
+| Inventing visual problems that aren't in the rendered output | Anchor every finding to what's visible in the PNG |
+| Re-flagging issues already raised by structural review | Visual review covers what YAML inspection can't see; trust the orchestrator to dedupe |
+
+## Rationalizations to resist
+
+| Excuse | Reality |
+|---|---|
+| "I can guess what it looks like from the YAML" | You can't — that's why visual review exists. Render or skip the pass. |
+| "Contrast looks fine to me" | If you're unsure, flag it as a `warning`. Accessibility is not subjective when it fails WCAG. |
+| "The vision model is expensive, I'll skim" | Don't run the skill at all if you're going to skim — the orchestrator can route to structural-only. |

dataface/ai/skills/dataface-mcp-setup/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: dataface-mcp-setup
+kind: workflow
+surfaces: [cli]
+description: >
+  Set up the Dataface MCP server for AI assistant integration. Use when
+  running 'dft init mcp', installing Dataface, configuring MCP for Cursor,
+  Claude Desktop, VS Code, Codex, Copilot, or any MCP-compatible client,
+  or troubleshooting MCP connection issues like 'server not starting',
+  'tools not appearing', 'MCP requires additional dependencies'. Do NOT
+  use for building dashboards (use dashboard-build). Do NOT
+  use for dashboard errors (use dataface-troubleshooting).
+metadata:
+  author: fivetran
+---
+
+# Configuring Dataface MCP Server
+
+Set up the Dataface MCP server to give AI assistants access to dashboard tools and resources.
+
+> This skill is **CLI-only** (`surfaces: [cli]`) — it walks a human operator
+> through installing the MCP server from a shell. An already-connected MCP
+> agent does not need to read it.
+
+## Quick Setup
+
+The fastest way — auto-detects your AI clients and configures them:
+
+```bash
+pip install "dataface[mcp]"
+dft init mcp
+```
+
+This detects Cursor, VS Code, Claude Desktop, Claude Code, Copilot, and Codex, then writes the appropriate config files.
+
+### Target a Specific Client
+
+```bash
+dft init mcp cursor       # Configure Cursor only
+dft init mcp vscode       # Configure VS Code only
+dft init mcp claude       # Configure Claude Desktop only
+dft init mcp claude-code  # Configure Claude Code only
+dft init mcp codex        # Configure Codex CLI only
+dft init mcp copilot      # Configure GitHub Copilot Coding Agent only
+dft init mcp --all        # Write every supported config file
+dft init mcp print        # Print JSON config to stdout (manual setup)
+```
+
+### Force Update
+
+```bash
+dft init mcp cursor -f    # Overwrite existing config
+```
+
+After running `dft init mcp`, restart your AI client for changes to take effect.
+
+## Manual Configuration
+
+If you prefer manual setup, add this to your client's MCP config.
+
+For JSON-based clients (Cursor, VS Code, Claude Desktop, Claude Code, Copilot):
+
+```json
+{
+  "mcpServers": {
+    "dataface": {
+      "command": "/path/to/dft",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+For Codex (TOML — `.codex/config.toml`):
+
+```toml
+[mcp_servers.dataface]
+command = "/path/to/dft"
+args = ["mcp", "serve"]
+```
+
+If your Dataface or dbt project lives in a subdirectory of the workspace your
+AI client opens (or the server otherwise won't be launched with cwd at the
+project root), append `"--project-dir", "/abs/path/to/your/project"` to `args`.
+`dft init mcp` will add this for you when its `--project-dir` flag is used or
+when it detects that the workspace and project roots diverge.
+
+Config file locations:
+- **Cursor**: `.cursor/mcp.json`
+- **VS Code / Copilot agent mode**: `.vscode/mcp.json` with a `servers` root key
+- **Claude Desktop**: `~/.config/claude/config.json`
+- **Claude Code**: `.mcp.json` at the project root
+- **Codex**: `.codex/config.toml` (project must be trusted by Codex) — globally, `~/.codex/config.toml`
+- **GitHub Copilot Coding Agent**: `.github/copilot/mcp.json` with a `servers` root key
+
+Use the absolute path to `dft` in the `command` field. Find it with `which dft`.
+
+## Available Tools
+
+After setup, your AI assistant has access to these tools:
+
+| Tool | Purpose |
+|------|---------|
+| `validate_dashboard` | Fast YAML schema and cross-reference validation — use after every file edit |
+| `render_dashboard` | Compile, execute queries, and generate visual HTML/text output |
+| `query_face` | Run one named query from a saved face and inspect columns/sample rows |
+| `execute_query` | Run ad-hoc SQL queries while exploring data or testing SQL |
+| `describe_query` | Return column schema for a SQL string without fetching rows |
+| `schema` | Drill the data hierarchy: source → schema → table → column. Use `--json \| jq` at the CLI for ad-hoc cross-cutting queries; use `dft schema -s <kw>` for keyword/predicate corpus search, or `schema(source=S, schema=N, table_search="pattern")` at level 3 to filter the table list by regexp (table name or cached column name match). |
+| `schema_search` | Full-text + filter search across the schema corpus (CLI equivalent: `dft schema -s <kw>`) |
+| `docs` | Browse the packaged YAML reference corpus offline |
+| `list_skills` / `get_skill` | Discover and read packaged Dataface authoring skills — `get_skill` returns the full body including example YAML |
+
+## Available Resources
+
+| Resource | Content |
+|----------|---------|
+| `dataface://docs/all` | Complete DATAFACE_SYNTAX.md (whole reference, unsliced) |
+| `dataface://docs/{topic}` | One H2 section by slug (`cheatsheet`, `face`, `charts`, `queries`, `variables`, `layout`, `errors`) |
+| `dataface://guide/dashboard-design` | Dashboard design principles and patterns |
+| `dataface://guide/report-design` | Report design principles and narrative structure |
+| `dataface://guide/dashboard-build` | Build-test-iterate workflow best practices |
+| `dataface://guide/dashboard-review` | Self-review checklist for a finished face |
+| `dataface://dashboards` | List of all dashboards in the project |
+| `dataface://dashboard/{path}` | YAML content and compiled structure of a specific dashboard |
+
+## Troubleshooting
+
+### "MCP server requires additional dependencies"
+
+Install the MCP extras:
+
+```bash
+pip install "dataface[mcp]"
+```
+
+### MCP server not starting
+
+1. Verify `dft` is accessible: `which dft`
+2. Ensure the path in MCP config is absolute, not relative
+3. Check that your Python environment has `dataface[mcp]` installed
+4. Try running `dft mcp serve` manually to see error output
+
+### "No AI client directories detected"
+
+`dft init mcp` looks for `.cursor/`, `.codex/`, `.vscode/`, `.github/`, `CLAUDE.md`, `AGENTS.md`, or `~/.config/claude/` to auto-detect clients. If none exist yet, specify the client explicitly:
+
+```bash
+dft init mcp cursor
+```
+
+### Tools not appearing in AI client
+
+1. Restart the AI client after running `dft init mcp`
+2. Verify the config file was written: check `.cursor/mcp.json` or equivalent
+3. Ensure the `command` path in the config points to the correct `dft` binary
+
+## Verifying the Setup
+
+After configuration, test by asking your AI assistant:
+
+- "List available data sources" → should invoke `schema` (no args)
+- "Show me the database schema" → should invoke `schema(source=...)`
+- "Validate this dashboard YAML file" → should invoke `validate_dashboard`
+
+If the assistant doesn't recognize these tools, the MCP server isn't connected — check the troubleshooting steps above.
+
+## Authoring Metadata Convention
+
+When the assistant edits Dataface YAML through MCP tools, require `description` metadata on:
+
+- `queries.*.description`
+- `charts.*.description`
+- `variables.*.description`
+- Layout objects (`rows`/`cols`/`grid.items`/`tabs.items`) where meaningful
+
+This improves downstream AI search/context quality and enables optional UI tooltips.