dataface 0.1.2__py3-none-any.whl

dataface/ai/skills/kpi-row/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: kpi-row
+kind: pattern
+description: >
+  Pattern for a row of 3–5 KPI cards at the top of a face. Use when showing
+  summary metrics (revenue, orders, conversion rate, avg order value) from a
+  single aggregated query. Triggers on: 'KPI row', 'summary metrics', 'top
+  metrics', 'hero numbers', 'scorecard'. Each KPI needs a separate single-row
+  query OR one query with multiple columns. Do NOT use for time-series trends
+  (use time-series-trend). Do NOT use for a single hero metric (use
+  single-metric-bignum). Do NOT use if the data has more than 1 row per KPI.
+metadata:
+  author: fivetran
+---
+
+# KPI Row
+
+A horizontal row of 3–5 KPI cards placed at the top of a face. Each KPI
+displays one aggregate value (a number, currency, or percent) with a label and
+an optional prior-period delta in the support row.
+
+## When to reach for this
+
+- The face opens with a "how are we doing overall?" summary before detail charts
+- You have 3–5 numeric aggregates drawn from the same time window
+- Some metrics have a prior-period comparison to show trend direction
+
+## When NOT to use this
+
+- Single hero metric with a sparkline → use `single-metric-bignum`
+- Data has multiple rows per KPI → aggregate to one row first
+- More than 6 KPIs → split into two rows or a `two-by-two-grid-overview`
+
+## The pattern
+
+```yaml
+queries:
+  kpis:
+    columns: [revenue, orders, avg_order, rev_delta, ord_delta]
+    values: [[248500, 1420, 175, 0.12, 0.08]]
+
+charts:
+  revenue_kpi:
+    type: kpi
+    query: kpis
+    label: Revenue
+    value: revenue
+    format: currency_whole
+    support:
+      value: rev_delta
+      label: vs last period
+      format: percent_delta
+      glyph: "▲"
+      tone: positive
+
+  orders_kpi:
+    type: kpi
+    query: kpis
+    label: Orders
+    value: orders
+    support:
+      value: ord_delta
+      label: vs last period
+      format: percent_delta
+      glyph: "▲"
+      tone: positive
+
+rows:
+  - height: 120
+    cols: [revenue_kpi, orders_kpi]
+```
+
+See `examples/kpi-row.yml` for the full 3-KPI worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| No delta | omit `support:` | Prior period not available |
+| Currency | `format: currency_whole` | Revenue, spend, cost |
+| Percent | `format: percent` | Rate, conversion, margin |
+| Negative delta | `tone: negative`, `glyph: "▼"` | Unfavorable direction |
+| Fixed row height | `height: 120` on the row | Prevent KPIs growing taller than charts below |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Query returns multiple rows | `ChartDataError` — KPI expects exactly 1 row | Add `SUM()`/`COUNT()` to aggregate to one row |
+| Delta column missing from query | Render error — column not found | Include delta columns in the same query |
+| `glyph: "▲"` without `tone:` | Arrow renders but no semantic color | Add `tone: positive` or `tone: negative` |
+| Overloaded label | Hard to scan at a glance | ≤ 3 words per label |
+
+## Worked example
+
+See `examples/kpi-row.yml` — three KPIs (Revenue, Orders, Avg Order Value)
+from one inline-data query. Compiles and renders without a warehouse.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/kpi-row/examples/kpi-row.yml

@@ -0,0 +1,55 @@
+title: Q1 Sales Summary
+description: KPI row pattern — three summary metrics from one aggregated query
+
+queries:
+  kpis:
+    description: Single-row aggregate with current values and prior-period deltas
+    columns: [revenue, orders, avg_order, rev_delta, ord_delta, aov_delta]
+    values:
+      - [248500, 1420, 175, 0.12, 0.08, 0.04]
+
+charts:
+  revenue_kpi:
+    type: kpi
+    query: kpis
+    label: Revenue
+    value: revenue
+    format: currency_whole
+    support:
+      value: rev_delta
+      label: vs last quarter
+      format: percent_delta
+      glyph: "▲"
+      tone: positive
+
+  orders_kpi:
+    type: kpi
+    query: kpis
+    label: Orders
+    value: orders
+    support:
+      value: ord_delta
+      label: vs last quarter
+      format: percent_delta
+      glyph: "▲"
+      tone: positive
+
+  aov_kpi:
+    type: kpi
+    query: kpis
+    label: Avg Order Value
+    value: avg_order
+    format: currency
+    support:
+      value: aov_delta
+      label: vs last quarter
+      format: percent_delta
+      glyph: "▲"
+      tone: positive
+
+rows:
+  - height: 120
+    cols:
+      - revenue_kpi
+      - orders_kpi
+      - aov_kpi

dataface/ai/skills/report-design/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: report-design
+kind: workflow
+description: >
+  Design principles for Dataface narrative reports — data-driven documents
+  that answer specific questions. Use when creating analyses, investigations,
+  periodic reports, or when the user says 'write a report', 'analyze this
+  data', 'create an analysis', 'narrative report'. Covers narrative
+  structure, chart selection for reports, content writing, and the
+  executive-summary-first pattern. Do NOT use for at-a-glance monitoring
+  dashboards (use dashboard-design). Do NOT use for the
+  build-test-iterate workflow (use dashboard-build).
+metadata:
+  author: fivetran
+---
+
+# Report Design
+
+Reports are narrative-driven documents that tell a story with data and answer specific questions. They are NOT dashboards.
+
+> Implementing in YAML? Switch to `{{ s_skill_build }}` for the build-test-iterate workflow.
+
+## Report vs. Dashboard
+
+| | Report | Dashboard |
+|--|--------|-----------|
+| **Purpose** | Answer a question, tell a story | Monitor status at a glance |
+| **Text** | Extensive — narrative + recommendations | Minimal — titles and labels |
+| **Charts** | Support the narrative (3-6 typically) | ARE the content |
+| **Structure** | Executive summary → analysis → conclusions | KPIs → trends → breakdowns |
+| **Interaction** | Read in minutes | Scan in seconds |
+
+If the user needs at-a-glance monitoring, use the `dashboard-design` skill instead.
+
+## Core Principles
+
+1. **Answer the question first** — lead with the conclusion, not the methodology
+2. **Every chart serves the narrative** — no chart without explanatory text above it
+3. **Tell a story** — setting (context) → conflict (problem/question) → resolution (findings + recommendations)
+4. **Be specific** — "Revenue dropped 12% because Region X lost 3 key accounts" not "Revenue decreased"
+5. **Professional tone** — direct, concise, active voice
+
+## Metadata Requirement
+
+When producing Dataface YAML, include `description` metadata for AI context/search:
+
+- `queries.*.description`: query purpose
+- `charts.*.description`: what evidence the chart provides
+- `variables.*.description`: filter meaning (if variables are present)
+- Layout object `description` fields (`rows`/`cols`/`grid.items`/`tabs.items`) where section context helps
+
+## Narrative Structure
+
+Every report follows this arc:
+
+```
+1. EXECUTIVE SUMMARY
+   - 2-3 sentences with key findings
+   - Recommendation in bold
+   - The answer, upfront
+
+2. CONTEXT
+   - Time period, scope, data sources
+   - Why this analysis was needed
+
+3. ANALYSIS SECTIONS (2-4)
+   - Each section: one finding
+   - Pattern: State finding → explain significance → show chart evidence
+   - Transition between sections
+
+4. CONCLUSIONS & RECOMMENDATIONS
+   - Numbered, specific, actionable (who/what/when)
+   - Quantify expected impact when possible
+```
+
+## Chart Selection for Reports
+
+Reports use fewer charts than dashboards. Each must be referenced in the narrative:
+
+| Report Need | Chart Type | Example Narrative |
+|-------------|-----------|-------------------|
+| The trend that tells the story | `line` | "Revenue has been declining since March" |
+| Segments that matter | `bar` | "Region X underperformed by 23%" |
+| A key metric | `kpi` | "Total impact: $2.3M" |
+| Detailed breakdown | `table` | "Here are the top 10 affected accounts" |
+| Composition change | `area` (stacked) | "The product mix shifted toward lower-margin items" |
+
+**Prefer:** Fewer charts with more text. Tables for evidence. KPIs for anchoring key numbers.
+
+**Avoid:** Many KPIs in a row (dashboard pattern). Charts without narrative context. Interactive filters (reports present a specific analysis).
+
+## Writing Content
+
+Use `text:` blocks in YAML for narrative text (Markdown).
+
+**Opening each section:**
+- State the finding first
+- Explain why it matters
+- Introduce the chart
+
+**Closing each section:**
+- Summarize the implication
+- Transition to the next section
+
+**Tone guidelines:**
+- Active voice: "Revenue declined" not "A decline was observed"
+- Specific numbers: "12% decline" not "significant decrease"
+- No filler: Cut "It's worth noting that..." — just note it
+- Honest about uncertainty where data doesn't fully support a claim
+
+## YAML Structure for Reports
+
+Reports use heavier `text:` usage than dashboards:
+
+```yaml
+title: "Q3 Revenue Analysis"
+source: warehouse
+
+queries:
+  revenue_trend:
+    sql: SELECT month, revenue FROM monthly_revenue ORDER BY month
+
+charts:
+  trend:
+    query: revenue_trend
+    type: line
+    x: month
+    y: revenue
+
+rows:
+  - text: |
+      ## Executive Summary
+      Q3 revenue declined 12% quarter-over-quarter, driven primarily
+      by the loss of three enterprise accounts in the West region.
+      **Recommendation: Prioritize retention program for accounts >$100K ARR.**
+
+  - text: |
+      ## Revenue Trend
+      Monthly revenue peaked in June and has declined each month since.
+  - trend
+
+  - text: |
+      ## Conclusions
+      1. Launch retention program for enterprise accounts by end of month
+      2. Investigate West region account manager capacity
+```
+
+Key differences from dashboard YAML:
+- Heavy `text:` blocks with narrative
+- Fewer charts (3-6), more text
+- No `variables:` — reports present a specific analysis
+- Top-level flow follows the narrative arc
+
+## Quality Checklist
+
+- [ ] Answers the question in the executive summary
+- [ ] Executive summary comes first (conclusion before methodology)
+- [ ] Every chart has narrative context above it
+- [ ] Findings are specific (numbers, percentages, comparisons)
+- [ ] Recommendations are actionable (who/what/when)
+- [ ] Story flows logically section to section
+- [ ] Appropriate length (3-6 analysis sections)
+- [ ] Professional tone (direct, specific, active voice)
+- [ ] Query/chart/variable/layout `description` metadata is filled for AI context
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Methodology before conclusions | Lead with the answer — executives read top-down |
+| Chart without narrative context | Every chart needs explanatory text above it |
+| Vague findings ("revenue decreased") | Be specific: "revenue declined 12% QoQ" |
+| Dashboard patterns in a report (KPI row) | Reports use narrative flow, not monitoring layout |
+| Too many charts | 3-6 max — each must serve the story |
+| Hedging without reason | Be confident where data supports it |
+
+## Rationalizations to Resist
+
+| Excuse | Reality |
+|--------|---------|
+| "User wants the methodology first" | They don't. They want the answer. Methodology can follow. |
+| "Adding more charts shows thoroughness" | It shows clutter. Every chart must serve the narrative. |
+| "I'll add filters so they can explore" | That's a dashboard. Reports present a specific analysis. |
+| "The data speaks for itself" | It never does. Interpret it — that's the report's job. |

dataface/ai/skills/single-metric-bignum/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: single-metric-bignum
+kind: pattern
+description: >
+  Pattern for a single hero KPI displayed at large scale with a prior-period
+  delta in the support row. Use when one metric is the primary signal of the
+  face and should visually dominate. Triggers on: 'hero metric', 'big number',
+  'single KPI', 'headline metric', 'north star', 'key metric', 'monthly
+  recurring revenue', 'MRR'. Optionally add a sparkline for trend context.
+  Do NOT use for three or more metrics (use kpi-row). Do NOT use when the
+  chart type is more important than the number (use time-series-trend).
+metadata:
+  author: fivetran
+---
+
+# Single-Metric Bignum
+
+One KPI rendered at the largest readable size, backed by a one-row query,
+with a support row showing the prior-period delta. The visual emphasis signals
+"this is what matters most on this face."
+
+## When to reach for this
+
+- A face exists to answer one question: "what is our MRR today?"
+- The metric is a North Star that stakeholders check every day
+- You want delta context (up X% vs last period) without a full chart
+
+## When NOT to use this
+
+- Three or more equally-important metrics → `kpi-row`
+- Trend history is the point, not the current value → `time-series-trend`
+- Sparkline is critical (needs array data) → note this in the face description
+
+## The pattern
+
+```yaml
+queries:
+  hero:
+    # Compute current and prior totals upstream (e.g. in your dbt model) and
+    # select two columns. Inline window math against an aggregate row tends
+    # to break across warehouses — keep this query trivial.
+    sql: |
+      SELECT mrr, prior_mrr, (mrr - prior_mrr) / prior_mrr AS delta
+      FROM mrr_summary
+
+charts:
+  mrr_kpi:
+    type: kpi
+    query: hero
+    label: Monthly Recurring Revenue
+    value: mrr
+    format: "$,.2s"           # e.g. $1.84M
+    support:
+      value: delta
+      label: vs last month
+      format: "+.1%"
+      glyph: "▲"
+      tone: positive          # positive / negative / warning
+```
+
+See `examples/single-metric-bignum.yml` for the worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| Large currency | `format: "$,.2s"` | Millions/billions (e.g., `$1.84M`) |
+| Plain count | `format: ",.0f"` | Raw integer |
+| Percent | `format: ".1%"` | Conversion rate, margin |
+| Negative delta | `tone: negative`, `glyph: "▼"` | Unfavorable direction |
+| Status string | `query: { rows: [{ status: "On track" }] }` + `value: status` | Qualitative health status |
+| Sparkline | add a `spark` column in the query (array type) | Requires a warehouse that supports arrays |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Query returns multiple rows | ChartDataError | Use `SUM()`/`MAX()` to collapse to exactly 1 row |
+| `format: "$,.2s"` on a small number | Rounds aggressively (e.g. `$175` → `$0.00k`) | Use `"$,.0f"` for values under $10k |
+| `tone:` without `glyph:` | Delta has semantic color but no directional icon | Add `glyph: "▲"` or `"▼"` |
+| Overlong label | Label wraps awkwardly at large sizes | ≤ 4 words |
+
+## Worked example
+
+See `examples/single-metric-bignum.yml` — a hero MRR KPI with a +14.2%
+support row. Inline data, no warehouse required.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/single-metric-bignum/examples/single-metric-bignum.yml

@@ -0,0 +1,27 @@
+title: Monthly Recurring Revenue
+description: Single-metric bignum pattern — hero KPI with prior-period delta support row
+
+queries:
+  hero:
+    description: Current MRR and month-over-month growth rate
+    columns: [mrr, delta_pct]
+    values:
+      - [1840000, 0.142]
+
+charts:
+  mrr_kpi:
+    description: Hero MRR metric with month-over-month delta
+    type: kpi
+    query: hero
+    label: Monthly Recurring Revenue
+    value: mrr
+    format: currency_compact
+    support:
+      value: delta_pct
+      label: vs last month
+      format: percent_delta
+      glyph: "▲"
+      tone: positive
+
+rows:
+  - mrr_kpi

dataface/ai/skills/table-heavy-ops-dashboard/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: table-heavy-ops-dashboard
+kind: pattern
+description: >
+  Pattern for operational dashboards dominated by sortable tables with
+  per-column formatting, labels, and conditional formatting. Use when users
+  need to monitor status, triage incidents, or review row-level data with
+  currency/percent/date formatting and visual severity cues. Triggers on:
+  'ops dashboard', 'incident table', 'ticket queue', 'status monitor',
+  'formatted table', 'sortable list', 'operational view'. Do NOT use when a
+  chart communicates the pattern better (use top-n-with-detail for rankings).
+  Do NOT use for purely aggregated summaries (use kpi-row or
+  two-by-two-grid-overview).
+metadata:
+  author: fivetran
+---
+
+# Table-Heavy Ops Dashboard
+
+An operational view where one or more tables dominate. Each table uses
+`style.columns` to configure labels, number formats, and per-column widths.
+Conditional formatting adds severity colors without changing the data.
+
+## When to reach for this
+
+- Users need to scan, sort, and triage rows (incidents, tickets, pipelines)
+- Columns have mixed types: currency, percent, status strings, dates
+- Severity or thresholds matter (P1 red, P2 yellow, resolved grey)
+
+## When NOT to use this
+
+- Data is better shown as a chart → pair with `top-n-with-detail`
+- Data has only 1–5 aggregated rows → use `kpi-row` instead
+- Table has hundreds of columns → subset in SQL first
+
+## The pattern
+
+```yaml
+charts:
+  incidents:
+    type: table
+    query: open_incidents
+    title: Open Incidents
+    style:
+      columns:
+        - column: ticket_id
+          label: Ticket
+        - column: priority
+          label: Priority
+        - column: status
+          label: Status
+        - column: revenue_impact
+          label: Revenue Impact
+          format: "$,.0f"
+          align: right
+          width: 140
+        - column: created_at
+          label: Opened
+          format: "%Y-%m-%d"
+          header_overflow: wrap-two
+    conditional_formatting:
+      priority:
+        when:
+          - eq: P1
+            background: "#fee2e2"
+            font:
+              color: "#991b1b"
+              weight: "600"
+          - eq: P2
+            background: "#fef3c7"
+            font:
+              color: "#92400e"
+          - default: true
+            font:
+              color: "#334155"
+```
+
+See `examples/table-heavy-ops-dashboard.yml` for the inline-data worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| Currency column | `format: "$,.0f"` | Revenue, cost, spend |
+| Percent column | `format: ".1%"` | Rate, margin, conversion |
+| Date column | `format: "%Y-%m-%d"` | ISO dates |
+| Link cell | `link: "/detail?id={{ ticket_id }}"` | Click-through to detail |
+| Header wrapping | `header_overflow: wrap-two` | Long column labels |
+| Spark cell | `spark: line` or `spark.type: bar-normalize` | Trend arrays or % values |
+| Continuous color | `scale.background.palette` | Numeric intensity |
+| Header style | `style.table.header.*` | BI or minimal header tone |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Too many columns | Hard to scan, horizontal scroll | Limit to 6–8 most important columns |
+| Formatting strings not D3/Excel format | Wrong output | Use D3 format specs: `"$,.0f"`, `".1%"` |
+| Conditional rule with no style override | `ConditionalRule` validation error | Set `background:`, `font.color`, `font.weight`, or `glyph:` on each rule |
+| Sorting expectation mismatch | Default sort is query order | Add `ORDER BY priority` in SQL for triage queues |
+
+Conditional predicates are `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `between`,
+`in`, `is_null`, and `default`. Use `in:` in YAML, not `in_:`. `default: true`
+must be the last rule.
+
+## Worked example
+
+See `examples/table-heavy-ops-dashboard.yml` — five incident rows with
+priority, status, revenue impact, and owner columns. Inline data, no warehouse
+needed.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/table-heavy-ops-dashboard/examples/table-heavy-ops-dashboard.yml

@@ -0,0 +1,48 @@
+title: Incident Queue
+description: Table-heavy ops dashboard pattern — formatted table with per-column labels and types
+
+queries:
+  open_incidents:
+    description: Open and in-progress incidents with severity and impact
+    columns: [ticket_id, priority, status, assignee, revenue_impact]
+    values:
+      - ["T-001", "P1", "Open",        "Alice", 15000]
+      - ["T-002", "P2", "In Progress", "Bob",    4500]
+      - ["T-003", "P1", "Open",        "Carol", 22000]
+      - ["T-004", "P3", "Resolved",    "Dave",    800]
+      - ["T-005", "P2", "In Progress", "Alice",  7200]
+
+charts:
+  incidents_table:
+    description: Triageable incident list with priority, owner, and revenue impact
+    type: table
+    query: open_incidents
+    title: Open Incidents
+    style:
+      columns:
+        ticket_id:
+          label: Ticket
+        priority:
+          label: Priority
+        status:
+          label: Status
+        assignee:
+          label: Owner
+        revenue_impact:
+          label: Revenue Impact
+          format: currency_whole
+    conditional_formatting:
+      priority:
+        when:
+          - eq: P1
+            background: "#fee2e2"
+            font:
+              color: "#991b1b"
+              weight: "600"
+          - eq: P2
+            background: "#fef3c7"
+            font:
+              color: "#92400e"
+
+rows:
+  - incidents_table