dataface 0.4.1.dev53__py3-none-any.whl → 0.4.1.dev224__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -307,9 +307,11 @@ style:
   text:
     align: left
     column:
-      number: 2
+      max_number: 2
       gap: 24
-      rule: "1px solid #cbd5e1"
+      rule:
+        width: 1
+        color: "#cbd5e1"
 ```
 
 CSS-only keys like `border-radius`, `border-left`, `margin-top` are not board-style fields and are rejected.
@@ -926,6 +928,8 @@ variables:
 
 Top-level option-source binding (alternative to `options:`): `column`, `query`, `dimension` (MetricFlow), `measure` (MetricFlow), `model` (dbt).
 
+Top-level `column` is `table.column`, and the table may be schema-qualified when it is not in the connection's default schema — `column: gis.fact_sales.property_type`. `filter()` accepts the same qualified form.
+
 Enabled/disabled forms (`enabled: false` means the control is inactive):
 
 ```yaml

dataface/agent_api/_init_templates/meta.yaml

@@ -6,8 +6,8 @@
 # directory and its subdirectories; each face overrides what it sets.
 #
 # A meta.yaml deeper in the tree layers on top of the ones above it, and a face
-# always wins over meta. Nested style keys merge (a face setting style.board.margin
-# keeps a meta-supplied style.board.width).
+# always wins over meta. Nested style keys merge (a face setting style.frame.margin
+# keeps a meta-supplied style.frame.width).
 #
 # Uncomment and edit to set project-wide defaults:
 #
@@ -15,5 +15,5 @@
 # source: my_warehouse    # default data source for faces that don't name one
 #
 # style:
-#   board:
+#   frame:
 #     width: 1000

dataface/agent_api/board_artifact.py

@@ -22,6 +22,7 @@ from pydantic import BaseModel, ConfigDict
 
 from dataface.agent_api._paths import resolve_face_or_error
 from dataface.core.compile import compile_file
+from dataface.core.compile.models.face.resolved import ChartResolveFailure
 from dataface.core.compile.variables import normalize_multiselect_values
 from dataface.core.diagnostics import ERR_FILE_NOT_FOUND, Diagnostic
 from dataface.core.diagnostics.base import DatafaceError
@@ -133,14 +134,27 @@ def emit_board_artifact(
     set_filter_variables_context(
         frozenset(face.variable_registry) if face.variable_registry else frozenset()
     )
+    resolve_errors: dict[str, ChartResolveFailure] = {}
     try:
-        resolved, _render_cache = build_resolved_face(face, executor, merged_variables)
+        resolved, _render_cache = build_resolved_face(
+            face, executor, merged_variables, resolve_errors=resolve_errors
+        )
     except DatafaceError as exc:
         return EmitBoardArtifactResult(success=False, errors=[exc.to_diagnostic()])
     finally:
         set_auto_link_context(False)
         set_filter_variables_context(frozenset())
 
+    # A chart-level resolve failure no longer raises — it leaves a hole in the
+    # face instead. Publishing that hole silently would be worse than the fatal
+    # it replaced, since a live render at least draws an error tile where an
+    # artifact just has nothing. Artifacts stay all-or-nothing.
+    if resolve_errors:
+        return EmitBoardArtifactResult(
+            success=False,
+            errors=[failure.diagnostic for failure in resolve_errors.values()],
+        )
+
     recording = record_board(resolved, executor, merged_variables)
 
     artifact_path.parent.mkdir(parents=True, exist_ok=True)

dataface/agent_api/dashboards.py

@@ -7,13 +7,20 @@ values. No bare dict[str, Any] in any return position. Tool/CLI callers use
 
 from __future__ import annotations
 
+import sys
 from pathlib import Path
-from typing import Any, Literal
+from typing import Literal
 
 import yaml
-from pydantic import BaseModel, ConfigDict, Field, field_serializer
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, model_validator
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
 
 from dataface.agent_api._paths import resolve_face_or_error
+from dataface.agent_api.query import VariableBinding, variables_to_dict as _vars_to_dict
 from dataface.core.compile import Face, compile_file
 from dataface.core.dashboard import RenderedDashboard as RenderedDashboard
 from dataface.core.diagnostics import Diagnostic
@@ -112,8 +119,12 @@ class RenderDashboardArgs(BaseModel):
             "the list of available chart ids."
         ),
     )
-    variables: dict[str, Any] | None = Field(
-        None, description="Variable values to apply to the dashboard"
+    variables: list[VariableBinding] | None = Field(
+        None,
+        description=(
+            "Variable values to apply to the dashboard, as an array of {name, value} pairs. "
+            'Example: [{"name": "region", "value": "US"}, {"name": "year", "value": 2024}]'
+        ),
     )
     format: Literal["json", "text", "yaml", "svg", "terminal", "data"] | None = Field(
         None,
@@ -148,6 +159,12 @@ class RenderDashboardArgs(BaseModel):
         ),
     )
 
+    @model_validator(mode="after")
+    def _no_duplicate_variable_names(self) -> Self:
+        if self.variables is not None:
+            _vars_to_dict(self.variables)
+        return self
+
 
 # ---------------------------------------------------------------------------
 # Public verbs

dataface/agent_api/docs/yaml-reference.md

@@ -11,7 +11,7 @@ AuthoredFace (dataface) definition from YAML.
 | `tags` | list[str] | ✓ | Tags for categorization and search. |
 | `aliases` | list[str] | ✓ | Additional URLs that redirect to this face's canonical file-path URL. Each entry must be absolute (leading /). Requests to these URLs are redirected (302) to the face's real path, query string preserved. Valid on .yml, .yaml, .md, and folder index.* faces. |
 | `text` | str | ✓ | Markdown text content for text-only sections. |
-| `allow_html` | bool | ✓ | Render the face's body text as raw HTML via foreignObject instead of markdown. TRUSTED-CONTENT ONLY: the HTML (including any Jinja-interpolated values) is rendered as-authored — this is NOT a security sandbox. mdsvg strips <script>/event-handlers as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control. |
+| `html_policy` | enum: "none", "safe-subset", "trusted-raw" | ✓ | HTML rendering policy for the face's body text. One of: "none" (default) — HTML is escaped and rendered as plain markdown; "safe-subset" — reserved for a parser-checked allowlist (not yet enforced — currently renders as none); "trusted-raw" — raw HTML via foreignObject. TRUSTED-CONTENT ONLY: this is NOT a security sandbox. <script>/event-handlers are stripped as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control. |
 | `source` | str | ✓ | Default source name for all queries in this face. Inheritable via meta.yaml cascade. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy for every query in this dashboard, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts the whole dashboard out. Inheritable via the meta.yaml cascade. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
@@ -26,7 +26,7 @@ AuthoredFace (dataface) definition from YAML.
 | `details` | [FaceDetails](#facedetails) | ✓ | Collapsible section metadata. String shorthand: details: 'text' → FaceDetails(summary='text'). Block form: details: {summary: ..., expanded_title: ..., expanded: false}. |
 | `id` | str | ✓ | Explicit ID for this face. Auto-generated from filename if omitted. |
 | `style` | [Style](#style) | ✓ | Style patch (background, padding, border, etc.). Background and semantic color tokens (accent, muted) cascade to nested child faces. |
-| `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). On the root face there is no parent to place it into, so it instead sets the board's own width (equivalent to 'style.board.width') — percentages are rejected there since there's nothing to size relative to. |
+| `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). On the root face there is no parent to place it into, so it instead sets the board's own width (equivalent to 'style.frame.width') — percentages are rejected there since there's nothing to size relative to. |
 | `height` | str \| int | ✓ | Height when nested (e.g., '300px' or an integer in pixels). |
 | `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe. |
 | `extends` | str \| list[str] | ✓ | Face name(s) or relative path(s) this face inherits from, low to high priority. |
@@ -54,7 +54,7 @@ Variable definition from YAML.
 | `required` | bool | ✓ | When True, a value must be provided before queries execute. |
 | `visible` | bool | ✓ | When False, the variable is not rendered in the UI but can still be set via URL params. |
 | `enabled` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Enable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. None = enabled. Absent variable in a string expression raises (use a default). |
-| `column` | str | ✓ | Column name in the query result to use as option values. |
+| `column` | str | ✓ | Table column to draw option values from, as 'table.column'. The table may be schema-qualified ('schema.table.column') when it is not in the connection's default schema. |
 | `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) | ✓ | Query name or inline query definition for populating options. |
 | `dimension` | str | ✓ | MetricFlow dimension name for populating options. |
 | `measure` | str | ✓ | MetricFlow measure name for populating options. |
@@ -496,7 +496,7 @@ Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `board` | [BoardStyle](#boardstyle) | ✓ | Face-level structural board dimensions. |
+| `frame` | [FrameStyle](#framestyle) | ✓ | Face-level structural frame dimensions. |
 | `background` | str | ✓ | Working-surface background color (board and card fills). |
 | `accent` | str | ✓ | Accent color token cascaded to sparklines, bars, and focus rings. |
 | `muted` | str | ✓ | Muted secondary-text color token (KPI support rows, table and spark subtitles). |
@@ -1023,13 +1023,13 @@ Tab layout item.
 | `grid` | [GridLayout](#gridlayout) | ✓ | CSS-grid layout for this tab's content. |
 | `tabs` | [TabLayout](#tablayout) | ✓ | Nested tab layout (tabs within tabs). |
 
-<a id="boardstyle"></a>
-## BoardStyle
-Authored overlay for BoardStyle. Face-level structural dimensions. Do NOT cascade to child faces.
+<a id="framestyle"></a>
+## FrameStyle
+Authored overlay for FrameStyle. Face-level structural dimensions. Do NOT cascade to child faces.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `width` | float | ✓ | Maximum dashboard width in pixels. Caps the measured layout width, setting the board's proportions. Rendered as an on-screen pixel maximum everywhere except the dft HTML page (dft serve, dft render --format html), which scales the board to its container. |
+| `width` | float | ✓ | Maximum board width in pixels. Caps the measured layout width, setting the board's proportions. Rendered as an on-screen pixel maximum everywhere except the dft HTML page (dft serve, dft render --format html), which scales the board to its container. |
 | `min_height` | float | ✓ | Minimum board height in pixels. |
 | `margin` | float | ✓ | Board outer margin in pixels. |
 | `card_padding` | float | ✓ | Padding added to each card side in pixels. |
@@ -1689,7 +1689,7 @@ Authored overlay for TableTitleStyle.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `height` | float | ✓ | Table title row height in pixels. |
+| `height` | float | ✓ | Minimum title-block height in pixels. Applies as a floor only when a subtitle is present; a title-only block sizes to its natural content height instead. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Table title font style overrides. Unset fields fall back to [`style.charts.table.font`](#tablechartstyle). |
 
 <a id="paginationconfig"></a>
@@ -1898,9 +1898,9 @@ Authored overlay for TextColumnStyle. Author overrides for the column layout of
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `number` | int | ✓ | Ceiling on the column count. The renderer may choose fewer when there is not enough text to fill them. None = no ceiling. |
+| `max_number` | int | ✓ | Ceiling on the column count. The renderer may choose fewer when there is not enough text to fill them. None = no ceiling. |
 | `gap` | float | ✓ | Gap between columns in pixels. None = 1.5 line boxes, so the gutter scales with the type it separates. |
-| `rule` | str | ✓ | CSS column-rule shorthand, e.g. '1px solid #e5e7eb'. None = no rule. |
+| `rule` | [ColumnRuleStyle](#columnrulestyle) | ✓ | Vertical rule drawn between columns. None = no rule. |
 | `max_chars` | int | ✓ | Column width as a character count, overriding the shipped measure. The width is used exactly and the column count follows from it. |
 
 <a id="textcodestyle"></a>
@@ -2620,6 +2620,16 @@ Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark fill and boun
 | `fill` | str | ✓ | Neutral geoshape fill color. |
 | `stroke` | [StrokeStyle](#strokestyle) | ✓ | Geoshape boundary stroke style. |
 
+<a id="columnrulestyle"></a>
+## ColumnRuleStyle
+Authored overlay for ColumnRuleStyle. Vertical rule drawn between prose columns, structured like BorderStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `width` | float | ✓ | Rule line width in pixels. |
+| `color` | str | ✓ | Rule color as a CSS color string. |
+| `style` | enum: "solid", "dashed", "dotted" | ✓ | Rule line style. |
+
 <a id="circlemarkstyle"></a>
 ## CircleMarkStyle
 Authored overlay for CircleMarkStyle. Circle mark opacity and stroke.
@@ -2847,7 +2857,7 @@ Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offs
 |-------|------|:--------:|-------------|
 | `offset` | float | ✓ | Radial offset of slice labels from the arc in pixels. |
 | `line_height` | float | ✓ | Line height for slice labels in pixels. Reserved vertical space above the disk is ``line_height × &lt;rendered lines&gt;`` per row, so the same value handles 1-line, 2-line, and multi-line templates. |
-| `font` | [FontStyle](#fontstyle) | ✓ | Slice label font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
+| `font` | [FontStyle](#fontstyle) | ✓ | Slice label font style overrides. ``color`` only takes effect on single-series pies (no ``color:`` channel authored); multi-series pies always paint each label the dark companion of its own wedge color and ignore an authored ``color`` here. Unset fields fall back to [`style.charts.font`](#chartsstyle) (except `color`). |
 | `default_template` | [LabelsDefaultTemplate](#labelsdefaulttemplate) | ✓ | Default Jinja templates for per-slice labels when template is not authored. |
 | `template` | str | ✓ | Jinja2 label template. Overrides default_template when authored. |
 | `where` | str | ✓ | Jinja2 boolean filter — labels only render on rows where this is truthy. |

dataface/agent_api/pack.py

@@ -274,7 +274,7 @@ def _build_face_dict(dashboard: ProposedDashboard) -> dict[str, Any]:
         "title": dashboard.title,
         "description": dashboard.purpose,
         "text": (
-            f"Dashboard for {dashboard.primary_entity}. " "Add queries and charts here."
+            f"Dashboard for {dashboard.primary_entity}. Add queries and charts here."
         ),
     }
     if dashboard.canonical_data_url:

dataface/agent_api/project_session.py

@@ -365,8 +365,11 @@ class ProjectSession:
         self,
         name: str,
         path: Path,
+        vars: dict[str, Any] | None = None,
     ) -> _query.FaceQueryLookupResult:
-        return _query.lookup_face_query_sql(name=name, path=path, project=self.project)
+        return _query.lookup_face_query_sql(
+            name=name, path=path, project=self.project, vars=vars
+        )
 
     def query_face(
         self,

dataface/agent_api/query.py

@@ -1,9 +1,15 @@
 """Typed query verbs for the agent API."""
 
+import sys
 from pathlib import Path, PurePosixPath
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
 
 from dataface.agent_api._paths import resolve_face_path
 from dataface.core.compile import compile_file
@@ -16,6 +22,34 @@ from dataface.core.validate import normalize_data_for_json
 MAX_QUERY_LIMIT = 1000
 
 
+class VariableBinding(BaseModel):
+    """One variable binding in a tool call: a name–value pair.
+
+    Used in the ``variables`` / ``vars`` fields of ``render_dashboard``,
+    ``execute_query``, and ``query_face`` instead of an open-keyed dict, so
+    that OpenAI strict mode can validate the full tool-call structure.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(..., description="Variable name, e.g. 'region'")
+    value: str | int | float | bool = Field(
+        ..., description="Scalar value for the variable"
+    )
+
+
+def variables_to_dict(
+    bindings: list[VariableBinding],
+) -> dict[str, str | int | float | bool]:
+    """Convert a VariableBinding list to a dict, raising on duplicate names."""
+    result: dict[str, str | int | float | bool] = {}
+    for binding in bindings:
+        if binding.name in result:
+            raise ValueError(f"Duplicate variable name: {binding.name!r}")
+        result[binding.name] = binding.value
+    return result
+
+
 class FaceQueryLookupResult(BaseModel):
     """Result of extracting SQL from a named face query for offline use (validate/describe)."""
 
@@ -33,12 +67,17 @@ def lookup_face_query_sql(
     path: Path,
     *,
     project: Project,
+    vars: dict[str, Any] | None = None,
 ) -> FaceQueryLookupResult:
-    """Compile a face file and extract the SQL + source for one named SQL query.
+    """Compile a face file, render the SQL template, and return it for offline use.
 
-    Used by validate and describe paths that need the raw SQL text without
-    executing it against a warehouse.
+    Expands ``{{ queries.X }}`` and substitutes variables so callers receive
+    valid SQL rather than a raw Jinja template.  Used by validate and describe
+    paths that need the rendered SQL text without executing it against a
+    warehouse.
     """
+    from dataface.core.compile.parameterized import render_parameterized_with_queries
+
     try:
         file_path = resolve_face_path(path, project)
     except ValueError as e:
@@ -74,7 +113,18 @@ def lookup_face_query_sql(
             ],
         )
 
-    return FaceQueryLookupResult(success=True, sql=query.sql, source=query.source)
+    merged_vars = {**face.variable_defaults, **(vars or {})}
+    try:
+        rendered = render_parameterized_with_queries(
+            query.sql,
+            merged_vars,
+            queries=face.queries,
+            strict=not query.lenient_variables,
+        )
+    except (ValueError, KeyError, TypeError) as exc:
+        return FaceQueryLookupResult(success=False, errors=[str(exc)])
+
+    return FaceQueryLookupResult(success=True, sql=rendered.sql, source=query.source)
 
 
 class ExecuteQueryArgs(BaseModel):
@@ -84,8 +134,12 @@ class ExecuteQueryArgs(BaseModel):
         ...,
         description="SQL query to execute. Use {{ variable_name }} for parameterized values — these work identically in dashboard YAML, so queries you test here will be cached when reused in dashboards.",
     )
-    variables: dict[str, Any] | None = Field(
-        None, description='Variable values to substitute (e.g. {"region": "US"})'
+    variables: list[VariableBinding] | None = Field(
+        None,
+        description=(
+            "Variable values to substitute, as an array of {name, value} pairs. "
+            'Example: [{"name": "region", "value": "US"}, {"name": "year", "value": 2024}]'
+        ),
     )
     source: str | None = Field(None, description="Data source name to execute against")
     limit: int | None = Field(None, description="Maximum rows to return (default 50)")
@@ -93,6 +147,20 @@ class ExecuteQueryArgs(BaseModel):
         False,
         description="When True, undefined Jinja variables degrade gracefully (useful for iterative chart editing where not all variables are set).",
     )
+    # Display only — never reaches execute_query(). Ad-hoc SQL is the one query
+    # surface with no author to describe it: a named face query carries the
+    # `description:` its YAML already declares, and this is the equivalent for
+    # a query that exists only for the length of one tool call.
+    description: str | None = Field(
+        None,
+        description="Short phrase naming what this query is for (e.g. 'Leads by industry'), shown to the user in place of the raw SQL.",
+    )
+
+    @model_validator(mode="after")
+    def _no_duplicate_variable_names(self) -> Self:
+        if self.variables is not None:
+            variables_to_dict(self.variables)
+        return self
 
 
 class ExecuteQueryResult(BaseModel):
@@ -218,8 +286,12 @@ class QueryFaceArgs(BaseModel):
         ..., description="Name of the query inside the face's `queries:` block"
     )
     path: Path = Field(..., description="Path to the face YAML file")
-    vars: dict[str, Any] | None = Field(
-        None, description='Variable overrides (e.g. {"country": "FR"})'
+    vars: list[VariableBinding] | None = Field(
+        None,
+        description=(
+            "Variable overrides as an array of {name, value} pairs. "
+            'Example: [{"name": "country", "value": "FR"}]'
+        ),
     )
     limit: int = Field(
         20, ge=1, le=1000, description="Max rows to return (default 20, max 1000)"
@@ -227,6 +299,12 @@ class QueryFaceArgs(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
+    @model_validator(mode="after")
+    def _no_duplicate_variable_names(self) -> Self:
+        if self.vars is not None:
+            variables_to_dict(self.vars)
+        return self
+
 
 class QueryFaceResult(BaseModel):
     model_config = ConfigDict(frozen=True)
@@ -236,6 +314,9 @@ class QueryFaceResult(BaseModel):
     path: PurePosixPath
     query_type: str | None = None
     sql: str | None = None
+    #: The query's authored `description:`, when its YAML declares one. Lets a
+    #: caller label the run with what it is for rather than its identifier.
+    description: str | None = None
     columns: list[str] = []
     data: list[dict[str, Any]] = []
     row_count: int = 0
@@ -249,11 +330,19 @@ def _fail(
     path: PurePosixPath,
     errors: list[str],
     available: list[str] | None = None,
+    sql: str | None = None,
+    description: str | None = None,
 ) -> QueryFaceResult:
+    """A failure reports the query it was running whenever it got far enough to
+    know it: an undefined-variable error is unreadable without the SQL holding
+    the `{{ }}` that went unbound. Failures before the query is looked up
+    (unresolvable path, compile error, unknown name) have neither to report."""
     return QueryFaceResult(
         success=False,
         name=name,
         path=path,
+        sql=sql,
+        description=description,
         errors=errors,
         available_queries=available or [],
     )
@@ -298,6 +387,8 @@ def query_face(
 
     merged_vars = {**face.variable_defaults, **(vars or {})}
     query = face.queries[name].model_copy(update={"limit": limit + 1})
+    sql = query.sql if isinstance(query, SqlQuery) else None
+    described = query.description
 
     # Detect file sources before dispatching — the adapter path has no materializer
     # and would fall through to SqlAdapter with a cryptic dbt error. File-source
@@ -324,6 +415,8 @@ def query_face(
                         "(dft render / dft serve). "
                         "Use dft render to preview this dashboard."
                     ],
+                    sql=sql,
+                    description=described,
                 )
 
     try:
@@ -331,10 +424,16 @@ def query_face(
             query, variables=merged_vars or None, face=face, query_name=name
         )
     except Exception as e:  # noqa: BLE001
-        return _fail(name, resolved_display, [str(e)])
+        return _fail(name, resolved_display, [str(e)], sql=sql, description=described)
 
     if exec_result.error:
-        return _fail(name, resolved_display, [exec_result.error])
+        return _fail(
+            name,
+            resolved_display,
+            [exec_result.error],
+            sql=sql,
+            description=described,
+        )
 
     data = normalize_data_for_json(exec_result.data)
     truncated = len(data) > limit
@@ -345,7 +444,8 @@ def query_face(
         name=name,
         path=resolved_display,
         query_type=query.query_type,
-        sql=query.sql if isinstance(query, SqlQuery) else None,
+        sql=sql,
+        description=described,
         columns=list(data[0].keys()) if data else [],
         data=data,
         row_count=len(data),

dataface/agent_api/serve.py

@@ -58,9 +58,7 @@ def prepare_serve(
     from dataface.core.serve.port import resolve_port
     from dataface.core.serve.server import create_server
 
-    env_theme = os.environ.get(
-        "DFT_DEFAULT_THEME"
-    )  # noqa: TID251 — DFT_DEFAULT_THEME knob
+    env_theme = os.environ.get("DFT_DEFAULT_THEME")  # noqa: TID251 — DFT_DEFAULT_THEME knob
     # Empty string is treated as unset (matches get_default_theme_name, which
     # falls back to the shipped default) — only a non-empty unknown name errors.
     if env_theme:

dataface/ai/llm.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import copy
 import json
 import logging
 import os
@@ -93,24 +94,69 @@ def _resolve_model(
     return explicit_model or os.getenv(env_var) or default_model
 
 
+def _to_strict_json_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Transform a JSON Schema dict in-place to conform to OpenAI strict-mode rules.
+
+    Mirrors openai/lib/_pydantic.py::_ensure_strict_json_schema:
+    - Every object gets additionalProperties: false.
+    - required covers all property keys whenever properties is present.
+    - 'default: null' entries are stripped (non-null defaults are left intact).
+    Recurses into $defs, definitions, properties, items, anyOf, allOf, oneOf.
+    """
+    if schema.get("type") == "object":
+        schema.setdefault("additionalProperties", False)
+    props = schema.get("properties", {})
+    if props:
+        schema["required"] = list(props.keys())
+
+    if schema.get("default") is None and "default" in schema:
+        del schema["default"]
+
+    for defs_key in ("$defs", "definitions"):
+        for sub in schema.get(defs_key, {}).values():
+            _to_strict_json_schema(sub)
+
+    for sub in schema.get("properties", {}).values():
+        _to_strict_json_schema(sub)
+
+    for key in ("anyOf", "allOf", "oneOf"):
+        for sub in schema.get(key, []):
+            _to_strict_json_schema(sub)
+
+    if "items" in schema:
+        _to_strict_json_schema(schema["items"])
+
+    return schema
+
+
 def _normalize_openai_tools(
     tools: list[dict[str, Any]] | None,
 ) -> list[dict[str, Any]]:
     # None means "use default agent tools"; [] means "no tools, text-only completion".
     source_tools = ALL_TOOLS if tools is None else tools
-    if not source_tools:
-        return []
-    if "input_schema" in source_tools[0]:
-        return [
-            {
-                "type": "function",
-                "name": tool["name"],
-                "description": tool["description"],
-                "parameters": tool["input_schema"],
-            }
-            for tool in source_tools
-        ]
-    return source_tools
+    result: list[dict[str, Any]] = []
+    for tool in source_tools:
+        if "input_schema" in tool:
+            # First-party tool in MCP/input_schema format — strict-transform and
+            # convert to OpenAI Responses API format. Strict mode is a property of
+            # schemas we authored, not of the transport; MCP passthrough schemas
+            # (already in OpenAI function format) are appended below unchanged.
+            result.append(
+                {
+                    "type": "function",
+                    "strict": True,
+                    "name": tool["name"],
+                    "description": tool["description"],
+                    "parameters": _to_strict_json_schema(
+                        copy.deepcopy(tool["input_schema"])
+                    ),
+                }
+            )
+        else:
+            # Already in OpenAI function format (e.g. MCP passthrough) — pass through
+            # untouched. Caller-supplied schemas must not be strict-marked or rewritten.
+            result.append(tool)
+    return result
 
 
 class LLMClientError(RuntimeError):

dataface/ai/skills/dashboard-build/SKILL.md

@@ -260,12 +260,14 @@ Named presets (prefer these over raw D3 strings):
 | Preset | Example output | Notes |
 |--------|---------------|-------|
 | `integer` | `1,234` | |
+| `year` | `2025` — no grouping, no SI scaling | an identifier, not a quantity |
 | `currency_whole` | `$1,234` | |
 | `currency_compact` | `$1.2M` | |
 | `percent` | `2.3%` — input is decimal fraction (0.023) | line/bar/area/scatter via `style.number_format` |
 | `percent_number` | `2.3%` — input is whole-number percent (2.3) | **KPI only** (`style.value.format`) |
 | `percent_delta` | `+2.3%` — input is decimal fraction | |
 | `percent_number_delta` | `+2.3%` — input is whole-number (2.3) | **KPI only** |
+| `percentage_points_delta` | `+3.2 pts` — the difference of two percentages | for a point delta, not a ratio delta |
 
 **`percent_number` and `percent_number_delta` only work on `type: kpi`.** Using them on line/bar/area/scatter causes a render error. For those chart types use `percent` or `percent_delta` (decimal-fraction input) or omit formatting and accept axis defaults.