dataface 0.1.2__py3-none-any.whl

dataface/ai/skills/time-series-trend/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: time-series-trend
+kind: pattern
+description: >
+  Pattern for a line (or area) chart tracking one or more numeric metrics over
+  time. Use when the question is "how has X changed over time?" with a date
+  dimension on x. Triggers on: 'trend', 'over time', 'time series', 'daily',
+  'weekly', 'monthly', 'historical'. Add a date-range variable to make it
+  interactive. Do NOT use for category comparisons without a time axis (use
+  top-n-with-detail or before-after-comparison). Do NOT use for composition
+  over time (use faceted-small-multiples with area type).
+metadata:
+  author: fivetran
+---
+
+# Time-Series Trend
+
+A line chart with a date dimension on x and a numeric metric on y. Data must
+be monotonically ordered by date; add `ORDER BY date` to every time-series
+query. Add a `date_range` variable when users need to zoom into a window.
+
+## When to reach for this
+
+- The data has a date/timestamp column and a numeric value per period
+- The question is directional: "is this metric going up or down?"
+- You want to compare two metrics on the same time axis (multi-series)
+
+## When NOT to use this
+
+- Comparing categories without time → `top-n-with-detail`
+- Showing composition across time → area chart in `faceted-small-multiples`
+- Single current-period metric → `single-metric-bignum`
+
+## The pattern
+
+```yaml
+variables:
+  date_range:
+    input: daterange
+    column: orders.order_date
+    default: ["2025-01-01", "2025-12-31"]
+
+queries:
+  monthly_revenue:
+    sql: |
+      SELECT DATE_TRUNC('month', order_date) AS month,
+             SUM(revenue)                    AS revenue
+      FROM orders
+      WHERE {{ filter_date_range('order_date', date_range) }}
+      GROUP BY 1
+      ORDER BY 1
+
+charts:
+  revenue_trend:
+    type: line
+    query: monthly_revenue
+    x: month
+    y: revenue
+    title: Monthly Revenue
+    style:
+      axis_x:
+        time_unit: yearmonth
+```
+
+See `examples/time-series-trend.yml` for the inline-data worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| Multi-series | `color: series_col` | Comparing two segments over time |
+| Area fill | `type: area` | Emphasize magnitude, not just direction |
+| Label cadence | `style.axis_x.label.time_unit` | Label a finer data grain at a coarser readable cadence |
+| Date-range variable | `variables: date_range: input: daterange` | User-controlled window |
+| Rolling window | wrap SQL in a window function | Smooth noisy daily data |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Missing `ORDER BY date` | Jagged, non-temporal line | Always order by the date column |
+| Date column as string without cast | Wrong sort, string ordering | `CAST(date AS DATE)` or use `DATE_TRUNC` |
+| Too many series (>5) | Legend unreadable | Filter or group remainder into "Other" |
+| Hourly data on a monthly face | Too many points, slow | Pre-aggregate to the right grain in SQL |
+
+## Worked example
+
+See `examples/time-series-trend.yml` — six months of revenue, no warehouse
+needed. Add `variables:` + `WHERE` clause when connecting to a live source.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/time-series-trend/examples/time-series-trend.yml

@@ -0,0 +1,26 @@
+title: Monthly Revenue Trend
+description: Time-series trend pattern — line chart with date on x, metric on y
+
+queries:
+  monthly_revenue:
+    description: Monthly revenue totals, ordered chronologically
+    columns: [month, revenue]
+    values:
+      - ["2025-07-01", 182000]
+      - ["2025-08-01", 194000]
+      - ["2025-09-01", 208000]
+      - ["2025-10-01", 221000]
+      - ["2025-11-01", 237000]
+      - ["2025-12-01", 248500]
+
+charts:
+  revenue_trend:
+    description: Monthly revenue trajectory over the last six months
+    type: line
+    query: monthly_revenue
+    x: month
+    y: revenue
+    title: Monthly Revenue
+
+rows:
+  - revenue_trend

dataface/ai/skills/top-n-with-detail/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: top-n-with-detail
+kind: pattern
+description: >
+  Pattern pairing a top-N bar chart with a detail table on the same query.
+  Use when the question is "which are the top performers?" and the user also
+  needs row-level detail. Triggers on: 'top N', 'top products', 'best
+  customers', 'ranked list', 'leaderboard', 'ranked + detail'. The bar chart
+  gives the ranking at a glance; the table provides drill-in context. Do NOT
+  use when there is no natural ranking (use two-by-two-grid-overview). Do NOT
+  use when detail is not needed (a plain bar chart suffices).
+metadata:
+  author: fivetran
+---
+
+# Top-N with Detail
+
+A bar chart ranking the top N categories by a metric, sitting beside a detail
+table that exposes the same rows. One query powers both — add `ORDER BY metric
+DESC LIMIT N` in the SQL so the data arrives pre-ranked.
+
+## When to reach for this
+
+- You have a "who/what is biggest?" question with a categorical dimension
+- Row-level context matters (e.g., rank + order count + avg order value)
+- The list is bounded and the user benefits from scanning the full ranked table
+
+## When NOT to use this
+
+- No natural ranking or comparison → plain `bar` chart
+- Too many categories for a table (>50 rows) → add pagination or a filter
+- Time-based ranking → pair with `time-series-trend` instead
+
+## The pattern
+
+```yaml
+queries:
+  top_products:
+    sql: |
+      SELECT product, SUM(revenue) AS revenue, COUNT(*) AS orders
+      FROM orders
+      GROUP BY product
+      ORDER BY revenue DESC
+      LIMIT 10
+
+charts:
+  ranking_bar:
+    type: bar
+    query: top_products
+    x: product
+    y: revenue
+    title: Top Products by Revenue
+
+  detail_table:
+    type: table
+    query: top_products
+    title: Product Detail
+    style:
+      columns:
+        - column: product
+          label: Product
+        - column: revenue
+          label: Revenue
+          format: "$,.0f"
+        - column: orders
+          label: Orders
+
+rows:
+  - cols: [ranking_bar, detail_table]
+```
+
+See `examples/top-n-with-detail.yml` for the inline-data worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| Color by category | `color: category_col` on the bar | Distinguish groups within the ranking |
+| Horizontal bars | `type: bar` with long labels reads naturally as horizontal | Long category names |
+| Click-through | add `link: "/detail?id={{ x }}"` to bar chart | Link to a per-item face |
+| Tighter N | `LIMIT 5` | Space-constrained layouts |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Forgetting `ORDER BY` | Arbitrary bar ordering | Always `ORDER BY metric DESC` |
+| Two separate queries | Bar and table can diverge | Use one query for both |
+| Too many bars (>15) | Bar chart unreadable | Set `LIMIT 10` or fewer |
+
+## Worked example
+
+See `examples/top-n-with-detail.yml` — top 5 products, bar + table, inline
+data. No warehouse required.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/top-n-with-detail/examples/top-n-with-detail.yml

@@ -0,0 +1,45 @@
+title: Top Products
+description: Top-N with detail pattern — bar chart and table from the same query
+
+queries:
+  top_products:
+    description: Top 5 products by revenue, pre-ranked
+    columns: [product, revenue, orders, avg_order]
+    values:
+      - ["Widget B", 85680, 320, 268]
+      - ["Widget A", 66300, 281, 236]
+      - ["Tool Z",   34900, 145, 241]
+      - ["Gadget Y", 30490, 122, 250]
+      - ["Gadget X", 18350,  88, 208]
+
+charts:
+  ranking_bar:
+    description: Top products ranked by revenue
+    type: bar
+    query: top_products
+    x: product
+    y: revenue
+    title: Top Products by Revenue
+
+  detail_table:
+    description: Row-level detail for the same top-5 ranking
+    type: table
+    query: top_products
+    title: Product Detail
+    style:
+      columns:
+        product:
+          label: Product
+        revenue:
+          label: Revenue
+          format: currency_whole
+        orders:
+          label: Orders
+        avg_order:
+          label: Avg Order
+          format: currency_whole
+
+rows:
+  - cols:
+      - ranking_bar
+      - detail_table

dataface/ai/skills/two-by-two-grid-overview/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: two-by-two-grid-overview
+kind: pattern
+description: >
+  Pattern for a 2×2 (or 2×3) grid of equally-weighted summary charts giving a
+  balanced multi-metric overview. Use when four to six metrics are equally
+  important and no single chart dominates. Triggers on: '2x2', 'grid overview',
+  'equal weight', 'four charts', 'overview dashboard', 'balanced layout',
+  'summary grid'. Each cell carries the same visual weight — no chart is
+  emphasized over another. Do NOT use when one chart is the hero (use
+  single-metric-bignum or put it in a wider column). Do NOT use when the four
+  metrics belong in a KPI row (use kpi-row for aggregated numbers).
+metadata:
+  author: fivetran
+---
+
+# Two-by-Two Grid Overview
+
+Four charts arranged in a 2×2 grid, each with equal column width, giving users
+a balanced multi-metric overview before diving into detail. Implemented as two
+`rows:` of `cols:` with two items each — Dataface splits the width evenly by
+default.
+
+## When to reach for this
+
+- A face opens with a balanced overview ("revenue / cost / margin / users")
+- All four charts have equal analytical importance
+- Each chart answers a different question about the same domain
+
+## When NOT to use this
+
+- One chart is clearly the hero → enlarge it via `width:` or move it to its own row
+- All four are KPI numbers → use `kpi-row` instead (it handles delta and format)
+- More than 6 equally-weighted charts → split into tabs or multiple faces
+
+## The pattern
+
+```yaml
+rows:
+  - title: Overview
+    cols:
+      - revenue_trend    # top-left
+      - cost_trend       # top-right
+  - cols:
+      - by_region        # bottom-left
+      - by_product       # bottom-right
+```
+
+Each chart is defined as usual in `charts:`. The 2×2 is purely a layout
+decision — swap in any chart type per cell.
+
+See `examples/two-by-two-grid-overview.yml` for the inline-data worked example.
+
+## Variations
+
+| Variation | YAML knob | When |
+|---|---|---|
+| 2×3 (six cells) | Add a third `cols:` row | Six equally-weighted metrics |
+| Asymmetric | `width: "60%"` on one cell | Slightly more emphasis on one chart |
+| Section title | `title:` on a `rows:` item | Separate the two rows conceptually |
+| Grid layout | `grid: columns: 24` + `col_span: 12` | Finer column control |
+
+## Common pitfalls
+
+| Pitfall | Why it breaks | Fix |
+|---|---|---|
+| Charts with very different heights | Mismatched row heights look accidental | Use charts of the same type per row |
+| All four showing the same metric | No additional insight | Ensure each cell answers a distinct question |
+| Nesting cols in cols | Unexpected layout behavior | Use rows at the top level, cols inside rows |
+
+## Worked example
+
+See `examples/two-by-two-grid-overview.yml` — four charts (two line + two bar)
+arranged 2×2 from two inline-data queries. No warehouse required.
+
+## YAML Reference
+
+For syntax and field details: {{ s_yaml_reference_footer }}

dataface/ai/skills/two-by-two-grid-overview/examples/two-by-two-grid-overview.yml

@@ -0,0 +1,64 @@
+title: Business Overview
+description: Two-by-two grid overview pattern — four equal-weight summary charts
+
+queries:
+  monthly:
+    description: Monthly revenue and cost trend
+    columns: [month, revenue, cost]
+    values:
+      - ["2025-09-01", 208000, 134000]
+      - ["2025-10-01", 221000, 141000]
+      - ["2025-11-01", 237000, 149000]
+      - ["2025-12-01", 248500, 155000]
+
+  by_region:
+    description: Revenue totals by region
+    columns: [region, revenue]
+    values:
+      - [North, 85000]
+      - [East,  71000]
+      - [South, 62000]
+      - [West,  54000]
+
+charts:
+  revenue_trend:
+    description: Revenue trajectory — is it growing?
+    type: line
+    query: monthly
+    x: month
+    y: revenue
+    title: Revenue Trend
+
+  cost_trend:
+    description: Cost trajectory — are costs tracking revenue?
+    type: line
+    query: monthly
+    x: month
+    y: cost
+    title: Cost Trend
+
+  revenue_by_region:
+    description: Which regions drive the most revenue?
+    type: bar
+    query: by_region
+    x: region
+    y: revenue
+    title: Revenue by Region
+
+  cost_by_month:
+    description: Monthly cost as a bar for easy comparison
+    type: bar
+    query: monthly
+    x: month
+    y: cost
+    title: Monthly Cost
+
+rows:
+  - title: Trends
+    cols:
+      - revenue_trend
+      - cost_trend
+  - title: Breakdown
+    cols:
+      - revenue_by_region
+      - cost_by_month

dataface/ai/tool_schemas.py

@@ -0,0 +1,132 @@
+"""Canonical tool definitions for Dataface AI interfaces.
+
+Single source of truth for tool names, descriptions, and input schemas.
+Consumed by both the MCP server and OpenAI function-calling wrappers.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from typing import Any
+
+from pydantic import BaseModel
+
+from dataface.agent_api.dashboards import RenderDashboardArgs
+from dataface.agent_api.describe import DescribeFaceArgs
+from dataface.agent_api.describe_query import DescribeQueryArgs
+from dataface.agent_api.query import ExecuteQueryArgs, QueryFaceArgs
+from dataface.agent_api.schema import SchemaArgs
+from dataface.agent_api.schema_search import SchemaSearchArgs
+from dataface.agent_api.search import SearchDashboardsArgs
+from dataface.agent_api.skills import GetSkillArgs, SearchSkillsArgs
+from dataface.agent_api.validate import ValidateDashboardArgs
+
+
+def _mcp_tool(name: str, model: type[BaseModel]) -> dict[str, Any]:
+    desc = textwrap.dedent(model.__doc__ or "").strip()
+    return {
+        "name": name,
+        "description": desc,
+        "input_schema": model.model_json_schema(by_alias=True),
+    }
+
+
+VALIDATE_DASHBOARD = _mcp_tool("validate_dashboard", ValidateDashboardArgs)
+RENDER_DASHBOARD = _mcp_tool("render_dashboard", RenderDashboardArgs)
+EXECUTE_QUERY = _mcp_tool("execute_query", ExecuteQueryArgs)
+DESCRIBE_QUERY = _mcp_tool("describe_query", DescribeQueryArgs)
+SCHEMA = _mcp_tool("schema", SchemaArgs)
+SCHEMA_SEARCH = _mcp_tool("schema_search", SchemaSearchArgs)
+SEARCH_DASHBOARDS = _mcp_tool("search_dashboards", SearchDashboardsArgs)
+
+DOCS = {
+    "name": "docs",
+    "description": (
+        "Browse the Dataface YAML reference offline. "
+        "Modes: no args = topic index (slug + one-line description per H2), "
+        "topic='<slug>' = one section, topic='all' = whole reference unsliced, "
+        "search='<query>' = substring search across topics. "
+        "Use this before writing YAML to learn field names, valid values, "
+        "and examples. Call with no args first to see the available topics."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "topic": {
+                "type": "string",
+                "description": "Topic slug (e.g. 'face', 'charts', 'cheatsheet') or 'all' for the whole file. Omit for the topic index.",
+            },
+            "search": {
+                "type": "string",
+                "description": "Substring query — scans all H2 sections and returns ranked hits",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Max search hits to return (default 5, max 50)",
+            },
+        },
+    },
+}
+
+QUERY_FACE = _mcp_tool("query_face", QueryFaceArgs)
+
+DESCRIBE_DASHBOARD = _mcp_tool("describe_dashboard", DescribeFaceArgs)
+
+LIST_SKILLS = {
+    "name": "list_skills",
+    "description": (
+        "List all agent skills packaged with dft. "
+        "Returns name, description, kind (workflow or pattern), and has_examples "
+        "for each skill. Call this first to discover what patterns are available, "
+        "then use get_skill to read the full guide for the pattern you want, "
+        "or search_skills to filter by keyword."
+    ),
+    "input_schema": {"type": "object", "properties": {}},
+}
+
+GET_SKILL = _mcp_tool("get_skill", GetSkillArgs)
+SEARCH_SKILLS = _mcp_tool("search_skills", SearchSkillsArgs)
+
+ALL_TOOLS: list[dict[str, Any]] = [
+    VALIDATE_DASHBOARD,
+    RENDER_DASHBOARD,
+    EXECUTE_QUERY,
+    DESCRIBE_QUERY,
+    SCHEMA,
+    SCHEMA_SEARCH,
+    SEARCH_DASHBOARDS,
+    DOCS,
+    QUERY_FACE,
+    DESCRIBE_DASHBOARD,
+    LIST_SKILLS,
+    GET_SKILL,
+    SEARCH_SKILLS,
+]
+
+
+def to_openai_tool(
+    tool: dict[str, Any],
+    property_subset: list[str] | None = None,
+    required: list[str] | None = None,
+) -> dict[str, Any]:
+    """Convert a canonical tool definition to OpenAI function-calling format."""
+    schema = dict(tool["input_schema"])
+    if property_subset is not None:
+        schema = {
+            **schema,
+            "properties": {
+                k: v for k, v in schema["properties"].items() if k in property_subset
+            },
+        }
+    if required is not None:
+        schema["required"] = required
+    elif "required" in schema and property_subset is not None:
+        schema["required"] = [r for r in schema["required"] if r in property_subset]
+    return {
+        "type": "function",
+        "function": {
+            "name": tool["name"],
+            "description": tool["description"],
+            "parameters": schema,
+        },
+    }