dataface 0.4.1.dev134__py3-none-any.whl → 0.4.1.dev304__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -11,7 +11,7 @@ Dataface workflow — from a dbt project to a running dashboard.
 ### Step 1 — Validate your YAML
 
 ```bash
-dft validate faces/my_dashboard.yml
+dft validate charts/my_dashboard.yml
 ```
 
 `dft validate` performs YAML schema + cross-reference validation. It checks that every field, chart reference, query name, and variable is correctly structured. **No database connection is required.**
@@ -62,8 +62,8 @@ rows:
 Then validate and render:
 
 ```bash
-dft validate faces/my_dashboard.yml
-dft render faces/my_dashboard.yml
+dft validate charts/my_dashboard.yml
+dft render charts/my_dashboard.yml
 ```
 
 Add each additional chart after the previous one validates and renders cleanly.
@@ -189,7 +189,7 @@ title: "Sales Overview"
 description: "Monthly KPIs and trend"
 tags: [sales, weekly]
 
-source: my_profile             # Default source (a name from dataface.yml's sources: registry)
+source: my_profile             # Default source (a name from dbt_charts.yml's sources: registry)
 
 variables:                     # Optional — interactive controls
 queries:                       # Named queries
@@ -220,7 +220,7 @@ Top-level fields (22 total):
 | `description` | string | Description text |
 | `tags` | list[string] | Tags for categorization/search |
 | `text` | string | Markdown body for text-only faces |
-| `source` | string | Default source name for every query below (from `dataface.yml`'s `sources:` registry), or an inline file path for a single colocated CSV/JSON/Parquet file. Inheritable via the `meta.yaml` cascade. |
+| `source` | string | Default source name for every query below (from `dbt_charts.yml`'s `sources:` registry), or an inline file path for a single colocated CSV/JSON/Parquet file. Inheritable via the `meta.yaml` cascade. |
 | `variables` | object | See [Variables](#variables) |
 | `queries` | object | See [Queries](#queries) |
 | `charts` | object | See [Charts](#charts) |
@@ -265,7 +265,7 @@ query param of the same name — which the face then reads as its variable.  Thi
 gives a single detail face a clean per-entity URL:
 
 ```yaml
-# faces/milestone.yml  (canonical URL: /milestone)
+# charts/milestone.yml  (canonical URL: /milestone)
 aliases:
   - /milestones/<name>
 variables:
@@ -284,7 +284,7 @@ and `milestone.yml` renders with `name` bound to `m3-public-launch`.
   treated as patterns.
 
 There are two ways to override a data/inspector route for a given path:
-- **Face file at that path** — create `faces/data/warehouse/schema/table.yml` and the server renders it directly (no redirect).
+- **Face file at that path** — create `charts/data/warehouse/schema/table.yml` and the server renders it directly (no redirect).
 - **`aliases:` entry** — any face can declare `/data/…/` as an alias; the server issues a 302 to the declaring face's canonical URL.
 
 Both approaches work.  A face file wins without a redirect round-trip; an alias lets a face live anywhere and still capture a system-view URL.
@@ -411,7 +411,7 @@ Common fields (all query types):
 | Field | Description |
 |-------|-------------|
 | `description` | Metadata sentence for AI search and tooltips |
-| `source` | Source name (from `dataface.yml`'s `sources:` registry), or an inline file path (`./data/x.csv`) for a single colocated CSV/JSON/Parquet. An inline connection dict (`{type: postgres, ...}`) is rejected — reference a named source instead. Not accepted on `http` queries. |
+| `source` | Source name (from `dbt_charts.yml`'s `sources:` registry), or an inline file path (`./data/x.csv`) for a single colocated CSV/JSON/Parquet. An inline connection dict (`{type: postgres, ...}`) is rejected — reference a named source instead. Not accepted on `http` queries. |
 | `target` | dbt target name (defaults to `dev`) |
 | `filters` | Post-execution result filters |
 | `limit` | Maximum rows returned |
@@ -424,7 +424,7 @@ HTTP fields: `url`, `method`, `headers`, `params`, `body`, `json_path`.
 dbt-model fields: `model`, `columns`.
 Inline-values fields: `columns`, `values` (or `rows` for record-shape).
 
-Connection source types (named in the project root `dataface.yml`'s `sources:`
+Connection source types (named in the project root `dbt_charts.yml`'s `sources:`
 registry — never inline in a face): `postgres`, `snowflake`, `bigquery`,
 `redshift`, `mysql`, `duckdb`, `sqlite`, `csv`, `json`, `parquet`, `http`, `dbt_profile`.
 CSV/JSON/Parquet may instead be referenced inline as a `source:` file path
@@ -928,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/__init__.py

@@ -16,7 +16,7 @@ Quick Start:
     >>> from dataface import compile, Executor, render
     >>> from dataface.core.execute.adapters import build_adapter_registry
     >>>
-    >>> # Compile YAML to Face
+    >>> # Compile YAML to Board
     >>> result = compile(yaml_content)
     >>> if result.success:
     ...     face = result.face
@@ -53,10 +53,10 @@ if TYPE_CHECKING:
     from dataface.core import validate as validate
     from dataface.core.compile import (
         AnyQuery as AnyQuery,
-        AuthoredFace as AuthoredFace,
+        AuthoredBoard as AuthoredBoard,
+        Board as Board,
         CompilationError as CompilationError,
         CompileResult as CompileResult,
-        Face as Face,
         Layout as Layout,
         LayoutItem as LayoutItem,
         Variable as Variable,
@@ -80,11 +80,11 @@ __all__ = [
     "compile",
     "compile_file",
     "CompileResult",
-    "Face",
+    "Board",
     "AnyQuery",
     "Layout",
     "LayoutItem",
-    "AuthoredFace",
+    "AuthoredBoard",
     "Variable",
     "CompilationError",
     # Execute
@@ -105,10 +105,10 @@ __all__ = [
 _LAZY_ATTRS: dict[str, tuple[str, str]] = {
     "validate": ("dataface.core", "validate"),
     "AnyQuery": ("dataface.core.compile", "AnyQuery"),
-    "AuthoredFace": ("dataface.core.compile", "AuthoredFace"),
+    "AuthoredBoard": ("dataface.core.compile", "AuthoredBoard"),
     "CompilationError": ("dataface.core.compile", "CompilationError"),
     "CompileResult": ("dataface.core.compile", "CompileResult"),
-    "Face": ("dataface.core.compile", "Face"),
+    "Board": ("dataface.core.compile", "Board"),
     "Layout": ("dataface.core.compile", "Layout"),
     "LayoutItem": ("dataface.core.compile", "LayoutItem"),
     "Variable": ("dataface.core.compile", "Variable"),

dataface/agent_api/__init__.py

@@ -50,9 +50,9 @@ if TYPE_CHECKING:
         project_sources_for_face as project_sources_for_face,
     )
     from dataface.agent_api.describe import (
-        DescribeFaceArgs as DescribeFaceArgs,
+        DescribeBoardArgs as DescribeBoardArgs,
         DescribeFaceResult as DescribeFaceResult,
-        describe_face as describe_face,
+        describe_board as describe_board,
     )
     from dataface.agent_api.docs import (
         DocsArgs as DocsArgs,
@@ -72,15 +72,20 @@ if TYPE_CHECKING:
     from dataface.agent_api.project_session import ProjectSession as ProjectSession
     from dataface.agent_api.query import (
         QueryFaceResult as QueryFaceResult,
-        query_face as query_face,
+        query_board as query_board,
     )
     from dataface.agent_api.schema_hints import SchemaHints as SchemaHints
     from dataface.agent_api.validate import (
-        ValidateDashboardArgs as ValidateDashboardArgs,
+        ValidateBoardArgs as ValidateBoardArgs,
         ValidateResult as ValidateResult,
     )
     from dataface.agent_api.validate_query import QueryDiagnostic as QueryDiagnostic
     from dataface.core.attribution import set_surface as set_surface
+    from dataface.core.board import (
+        BoardRenderResult as BoardRenderResult,
+        RenderFormat as RenderFormat,
+        render_dashboard as render_dashboard,
+    )
     from dataface.core.compile.compiler import (
         CompileResult as CompileResult,
         compile as compile,
@@ -88,11 +93,6 @@ if TYPE_CHECKING:
     from dataface.core.compile.config import (
         ProjectSourcesConfig as ProjectSourcesConfig,
     )
-    from dataface.core.dashboard import (
-        RenderedDashboard as RenderedDashboard,
-        RenderFormat as RenderFormat,
-        render_dashboard as render_dashboard,
-    )
     from dataface.core.diagnostics import Diagnostic as Diagnostic
     from dataface.core.execute.cache_backend import (
         QueryResultCache as QueryResultCache,
@@ -110,6 +110,7 @@ if TYPE_CHECKING:
         FaceFile as FaceFile,
         InMemoryFace as InMemoryFace,
         Project as Project,
+        posix_relpath as posix_relpath,
     )
     from dataface.core.render.board_links import LinkContext as LinkContext
     from dataface.core.render.errors import RenderError as RenderError
@@ -117,7 +118,7 @@ if TYPE_CHECKING:
 __all__ = [
     "compile",
     "CompileResult",
-    "DescribeFaceArgs",
+    "DescribeBoardArgs",
     "DescribeFaceResult",
     "Diagnostic",
     "DocsArgs",
@@ -132,15 +133,16 @@ __all__ = [
     "Project",
     "ProjectSession",
     "set_surface",
+    "posix_relpath",
     "ProjectSourcesConfig",
     "QueryDiagnostic",
     "QueryFaceResult",
-    "RenderedDashboard",
+    "BoardRenderResult",
     "RenderError",
     "RenderFormat",
     "SchemaHints",
     "Topic",
-    "ValidateDashboardArgs",
+    "ValidateBoardArgs",
     "ValidateResult",
     # Execution extension seams
     "AllowlistedSourceResolver",
@@ -148,11 +150,11 @@ __all__ = [
     "QueryResultCache",
     "SourceResolver",
     "WarehouseObserver",
-    "describe_face",
+    "describe_board",
     "get_fonts_dir",
     "init_project",
     "migrate_paths",
-    "query_face",
+    "query_board",
     "render_dashboard",
 ]
 
@@ -177,9 +179,9 @@ _LAZY_ATTRS: dict[str, tuple[str, str]] = {
         "dataface.agent_api._paths",
         "project_sources_for_face",
     ),
-    "DescribeFaceArgs": ("dataface.agent_api.describe", "DescribeFaceArgs"),
+    "DescribeBoardArgs": ("dataface.agent_api.describe", "DescribeBoardArgs"),
     "DescribeFaceResult": ("dataface.agent_api.describe", "DescribeFaceResult"),
-    "describe_face": ("dataface.agent_api.describe", "describe_face"),
+    "describe_board": ("dataface.agent_api.describe", "describe_board"),
     "DocsArgs": ("dataface.agent_api.docs", "DocsArgs"),
     "DocsResult": ("dataface.agent_api.docs", "DocsResult"),
     "DocsSearchHit": ("dataface.agent_api.docs", "DocsSearchHit"),
@@ -191,18 +193,18 @@ _LAZY_ATTRS: dict[str, tuple[str, str]] = {
     "migrate_paths": ("dataface.agent_api.migrate", "migrate_paths"),
     "ProjectSession": ("dataface.agent_api.project_session", "ProjectSession"),
     "QueryFaceResult": ("dataface.agent_api.query", "QueryFaceResult"),
-    "query_face": ("dataface.agent_api.query", "query_face"),
+    "query_board": ("dataface.agent_api.query", "query_board"),
     "SchemaHints": ("dataface.agent_api.schema_hints", "SchemaHints"),
-    "ValidateDashboardArgs": ("dataface.agent_api.validate", "ValidateDashboardArgs"),
+    "ValidateBoardArgs": ("dataface.agent_api.validate", "ValidateBoardArgs"),
     "ValidateResult": ("dataface.agent_api.validate", "ValidateResult"),
     "QueryDiagnostic": ("dataface.agent_api.validate_query", "QueryDiagnostic"),
     "set_surface": ("dataface.core.attribution", "set_surface"),
     "compile": ("dataface.core.compile.compiler", "compile"),
     "CompileResult": ("dataface.core.compile.compiler", "CompileResult"),
     "ProjectSourcesConfig": ("dataface.core.compile.config", "ProjectSourcesConfig"),
-    "RenderedDashboard": ("dataface.core.dashboard", "RenderedDashboard"),
+    "BoardRenderResult": ("dataface.core.board", "BoardRenderResult"),
     "RenderFormat": ("dataface.core.render_format", "RenderFormat"),
-    "render_dashboard": ("dataface.core.dashboard", "render_dashboard"),
+    "render_dashboard": ("dataface.core.board", "render_dashboard"),
     "Diagnostic": ("dataface.core.diagnostics", "Diagnostic"),
     "QueryResultCache": ("dataface.core.execute.cache_backend", "QueryResultCache"),
     "WarehouseObserver": (
@@ -222,6 +224,7 @@ _LAZY_ATTRS: dict[str, tuple[str, str]] = {
     "FaceFile": ("dataface.core.project", "FaceFile"),
     "InMemoryFace": ("dataface.core.project", "InMemoryFace"),
     "Project": ("dataface.core.project", "Project"),
+    "posix_relpath": ("dataface.core.project", "posix_relpath"),
     "LinkContext": ("dataface.core.render.board_links", "LinkContext"),
     "RenderError": ("dataface.core.render.errors", "RenderError"),
 }

dataface/agent_api/_init_templates/README.md

@@ -4,7 +4,7 @@ title: Dataface
 
 # Welcome to Dataface
 
-This is your project's landing page. Everything under `faces/` becomes a
+This is your project's landing page. Everything under `charts/` becomes a
 served page — edit the files here to build dashboards, reports, and docs
 for your data project.
 
@@ -18,7 +18,7 @@ queries and charts, then embed them inline with `{% raw %}{{ chart my_chart }}{%
 
 ## Next steps
 
-1. Open `faces/guide.yaml` and tweak the content.
+1. Open `charts/guide.yaml` and tweak the content.
 2. Run `dft serve` and open the URL it prints.
-3. Add new `.yaml` or `.md` files under `faces/` — they appear automatically.
+3. Add new `.yaml` or `.md` files under `charts/` — they appear automatically.
 4. Run `dft validate` to validate your face YAML for errors.

dataface/agent_api/_init_templates/guide.yaml

@@ -21,7 +21,7 @@ text: |
   Welcome to **Dataface** — dashboards as YAML files.
 
   This file is your starter guide. Edit it, add new `.yaml` files under
-  `faces/`, and run `dft serve` to preview everything in your browser.
+  `charts/`, and run `dft serve` to preview everything in your browser.
 
 # ── Queries ───────────────────────────────────────────────────────────────────
 # `type: values` embeds data directly — no database needed.

dataface/agent_api/_init_templates/meta.yaml

@@ -1,4 +1,4 @@
-# Directory defaults for every face under faces/
+# Directory defaults for every face under charts/
 #
 # meta.yaml is a *partial face* — it uses the exact same authoring surface as a
 # face file (source, theme, queries, charts, style, variables), but without a
@@ -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/_link_scan.py

@@ -15,18 +15,18 @@ import re
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from dataface.core.project import FACES_SUBDIR, Project
+from dataface.core.project import CHARTS_SUBDIR, Project
 
-_FACES_GLOB = f"{FACES_SUBDIR}/**/*"
+_FACES_GLOB = f"{CHARTS_SUBDIR}/**/*"
 
 
-def face_slug(relpath: str) -> str | None:
-    """Return the dashboard slug for a ``faces/`` path (no prefix, no suffix).
+def board_slug(relpath: str) -> str | None:
+    """Return the dashboard slug for a ``charts/`` path (no prefix, no suffix).
 
-    ``faces/finance/rev.yml`` -> ``finance/rev``. Returns None for a path
-    outside ``faces/`` -- link scanning only has meaning for dashboard slugs.
+    ``charts/finance/rev.yml`` -> ``finance/rev``. Returns None for a path
+    outside ``charts/`` -- link scanning only has meaning for dashboard slugs.
     """
-    prefix = f"{FACES_SUBDIR}/"
+    prefix = f"{CHARTS_SUBDIR}/"
     if not relpath.startswith(prefix):
         return None
     tail = relpath[len(prefix) :]

dataface/agent_api/_paths.py

@@ -16,7 +16,7 @@ from dataface.core.diagnostics import (
 )
 from dataface.core.diagnostics.base import DatafaceError
 from dataface.core.project import (
-    FACES_SUBDIR,
+    CHARTS_SUBDIR as CHARTS_SUBDIR,
     FaceFile,
     Project,
     ProjectPath,
@@ -37,19 +37,19 @@ if TYPE_CHECKING:
 def resolve_face_relpath(relpath: PurePosixPath, project: Project) -> ProjectPath:
     """Project-relative face identity -> ProjectPath, with the faces-first retry.
 
-    The relpath-native counterpart to ``resolve_face_path``: for callers that
+    The relpath-native counterpart to ``resolve_board_path``: for callers that
     already hold a project-relative face identity (Cloud's context strings)
     rather than a real filesystem path, this is the single owner of the
     face-relative vs root-relative reconciliation — a bare name like
-    ``looker/x.yaml`` retries under ``FACES_SUBDIR`` when it doesn't exist at
-    root, without producing a ``faces/faces/...`` double prefix when the
-    caller already supplies the full ``faces/looker/x.yaml``.
+    ``looker/x.yaml`` retries under ``CHARTS_SUBDIR`` when it doesn't exist at
+    root, without producing a ``charts/charts/...`` double prefix when the
+    caller already supplies the full ``charts/looker/x.yaml``.
 
     Existence is checked via ``project.exists(...)`` so it works for all
     ``Project`` implementations (FilesystemProject, CloudManagedProject
     git-blob store, etc.) — not just the local filesystem. Paths that exist
     at root resolve from root — non-faces paths like ``models/schema.sql``
-    are not rewritten under faces/. ``str`` is used only at the identity seam
+    are not rewritten under charts/. ``str`` is used only at the identity seam
     (``project.path`` / ``project.exists``); everything else is real
     ``PurePosixPath`` operations.
     """
@@ -57,8 +57,8 @@ def resolve_face_relpath(relpath: PurePosixPath, project: Project) -> ProjectPat
     assert_relpath(relpath_str)
     if project.exists(relpath_str):
         return project.path(relpath_str)
-    if not relpath.parts or relpath.parts[0] != FACES_SUBDIR:
-        candidate = PurePosixPath(FACES_SUBDIR) / relpath
+    if not relpath.parts or relpath.parts[0] != CHARTS_SUBDIR:
+        candidate = PurePosixPath(CHARTS_SUBDIR) / relpath
         candidate_str = str(candidate)
         if project.exists(candidate_str):
             return project.path(candidate_str)
@@ -78,7 +78,7 @@ def _relpath_for_fs_location(path: Path, project: Project) -> str:
     Two-try containment check (mirrors the pre-refactor behavior): ``resolve()``
     follows symlinks (handles e.g. ``/var`` -> ``/private/var`` on macOS); a
     symlink-blind ``normpath`` fallback accepts paths through intentional
-    project-internal symlinks (e.g. ``faces/tasks/`` -> ``../../tasks/``).
+    project-internal symlinks (e.g. ``charts/tasks/`` -> ``../../tasks/``).
     Raises ``ValueError`` if neither check places *path* inside the root.
     """
     if not isinstance(project, FilesystemProject):
@@ -99,13 +99,13 @@ def _relpath_for_fs_location(path: Path, project: Project) -> str:
         raise ValueError(f"Path {path!r} is outside project root {root!r}") from None
 
 
-def resolve_face_path(path: Path, project: Project) -> ProjectPath:
+def resolve_board_path(path: Path, project: Project) -> ProjectPath:
     """User/agent-supplied filesystem-shaped face path -> ProjectPath.
 
     Absolute and ``..``-leading paths are explicit locations: they relativize
     against a concrete ``FilesystemProject`` root (``_relpath_for_fs_location``,
     a leading ``..`` resolving against cwd for CLI shell-nav feel) and are
-    returned as-is — no ``faces/`` retry, even when the exact path doesn't
+    returned as-is — no ``charts/`` retry, even when the exact path doesn't
     exist. A bare relative name (no explicit location) delegates to
     ``resolve_face_relpath`` for the faces-first retry, which works against
     any ``Project`` implementation.
@@ -131,7 +131,7 @@ def resolve_face_or_error(path: Path, project: Project) -> FaceFile | Diagnostic
     (``ERR-INTERNAL``) or a missing face (``ERR-FILE-NOT-FOUND``).
     """
     try:
-        resolved = resolve_face_path(path, project)
+        resolved = resolve_board_path(path, project)
     except ValueError as exc:
         return DatafaceError.from_code(ERR_INTERNAL, message=str(exc)).to_diagnostic()
     if not resolved.exists():
@@ -238,11 +238,11 @@ def project_sources_for_face(face_path: Path) -> ProjectSourcesConfig:
     parse finding trustworthy enough to report.
 
     A face outside any project needs no special case: `find_project_root`
-    falls back to the starting directory, which has no `dataface.yml`, and the
+    falls back to the starting directory, which has no `dbt_charts.yml`, and the
     registry comes back empty — compile then stays silent about SQL syntax
     rather than guessing a dialect.
 
-    A `dataface.yml` that exists but does not load raises, deliberately. That
+    A `dbt_charts.yml` that exists but does not load raises, deliberately. That
     is a real fault at a real location, and swallowing it here would decide on
     the author's behalf that a broken project config is invisible — while
     handing the caller an empty registry indistinguishable from "no project".

dataface/agent_api/board_artifact.py

@@ -1,7 +1,7 @@
 """Emit a resolved-board artifact + recording, and render one back.
 
 `emit_board_artifact` compiles, resolves, and executes a face, then writes the
-board's published `ResolvedFace` contract and a data sidecar (the rows it was
+board's published `ResolvedBoard` contract and a data sidecar (the rows it was
 resolved against). `render_board_from_files` reads both back and renders
 without a compile step or a warehouse connection — the "skip the
 compilation" win the resolved-board artifact exists for.
@@ -22,7 +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.models.board.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
@@ -89,7 +89,7 @@ def emit_board_artifact(
 ) -> EmitBoardArtifactResult:
     """Compile, resolve, and execute a face, then write its artifact + recording.
 
-    Writes `artifact_path` (the published, data-free `ResolvedFace` contract)
+    Writes `artifact_path` (the published, data-free `ResolvedBoard` contract)
     and `recording_path` (the rows it was resolved against, the variable
     values, and a `recorded_at` stamp) — kept separate so the board contract
     carries no data payload.

dataface/agent_api/{dashboards.py → boards.py}

@@ -7,18 +7,25 @@ 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.core.compile import Face, compile_file
-from dataface.core.dashboard import RenderedDashboard as RenderedDashboard
+from dataface.agent_api.query import VariableBinding, variables_to_dict as _vars_to_dict
+from dataface.core.board import BoardRenderResult as BoardRenderResult
+from dataface.core.compile import Board, compile_file
 from dataface.core.diagnostics import Diagnostic
 from dataface.core.project import (
-    FACES_SUBDIR,
+    CHARTS_SUBDIR,
     Project,
     ProjectDirectory,
     ProjectPath,
@@ -32,7 +39,7 @@ DASHBOARD_KEYS = frozenset({"queries", "charts", "rows", "cols", "grid", "tabs"}
 # ---------------------------------------------------------------------------
 
 
-class DashboardSummary(BaseModel):
+class BoardSummary(BaseModel):
     model_config = ConfigDict(
         arbitrary_types_allowed=True, populate_by_name=True, frozen=True
     )
@@ -62,12 +69,12 @@ class SkippedFile(BaseModel):
         return pf.relpath
 
 
-class ListDashboardsResult(BaseModel):
+class ListBoardsResult(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
 
     success: bool
     errors: list[Diagnostic] = []
-    dashboards: list[DashboardSummary] = []
+    boards: list[BoardSummary] = []
     count: int = 0
     directory: ProjectDirectory
     skipped_files: list[SkippedFile] = []
@@ -77,26 +84,26 @@ class ListDashboardsResult(BaseModel):
         return d.relpath
 
 
-class CompiledDashboard(BaseModel):
+class CompiledBoard(BaseModel):
     model_config = ConfigDict(frozen=True)
 
     success: bool
-    dashboard: Face | None = None
+    board: Board | None = None
     errors: list[Diagnostic] = []
     warnings: list[Diagnostic] = []
     raw_yaml: str | None = None
 
 
-class RenderDashboardArgs(BaseModel):
+class RenderBoardArgs(BaseModel):
     """Validate, compile, and render a Dataface dashboard, returning resolved chart semantics + executed data for reasoning. Use this to verify YAML is valid, inspect query results, and iterate on a dashboard. When 'path' is provided, the response also includes a localhost URL the user can open in a browser to view the live dashboard (from the embedded HTTP server used by agent sessions). Pass `as_link=true` with a path to skip execution and return only the preview URL."""
 
     path: Path | None = Field(
         None,
         description=(
             "Path to dashboard YAML file (use this OR yaml_content). "
-            "Face-relative (no faces/ prefix needed, e.g. 'looker/x.yaml') or "
-            "root-relative (e.g. 'faces/looker/x.yaml') both resolve. If the "
-            "path came from search_dashboards, use the hit's face_path."
+            "Face-relative (no charts/ prefix needed, e.g. 'looker/x.yaml') or "
+            "root-relative (e.g. 'charts/looker/x.yaml') both resolve. If the "
+            "path came from search_boards, use the hit's face_path."
         ),
     )
     yaml_content: str | None = Field(
@@ -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,20 +159,26 @@ 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
 # ---------------------------------------------------------------------------
 
 
-def list_dashboards(
+def list_boards(
     project: Project,
     *,
-    under: str = FACES_SUBDIR,
+    under: str = CHARTS_SUBDIR,
     recursive: bool = True,
-) -> ListDashboardsResult:
+) -> ListBoardsResult:
     """List all available dashboards in a project."""
-    dashboards: list[DashboardSummary] = []
+    dashboards: list[BoardSummary] = []
     skipped: list[SkippedFile] = []
 
     for pf in project.iter_faces(under=under, recursive=recursive):
@@ -176,7 +193,7 @@ def list_dashboards(
                 continue
             stem = pf.stem
             dashboards.append(
-                DashboardSummary(
+                BoardSummary(
                     file=pf,
                     title=content.get("title", stem),
                     description=content.get("description", ""),
@@ -190,31 +207,31 @@ def list_dashboards(
         except OSError as e:
             skipped.append(SkippedFile(file=pf, reason=f"Read error: {e}"))
 
-    return ListDashboardsResult(
+    return ListBoardsResult(
         success=True,
-        dashboards=dashboards,
+        boards=dashboards,
         count=len(dashboards),
         directory=project.directory(under),
         skipped_files=skipped,
     )
 
 
-def get_dashboard(
+def get_board(
     path: Path,
     *,
     project: Project,
     include_raw: bool = False,
-) -> CompiledDashboard:
+) -> CompiledBoard:
     """Get the compiled structure of a dashboard."""
     # One faces-first resolve/exists/is-file seam, shared with the render path.
     face = resolve_face_or_error(path, project)
     if isinstance(face, Diagnostic):
-        return CompiledDashboard(success=False, errors=[face])
+        return CompiledBoard(success=False, errors=[face])
     result = compile_file(face)
 
-    return CompiledDashboard(
+    return CompiledBoard(
         success=result.success,
-        dashboard=result.face if result.success else None,
+        board=result.face if result.success else None,
         errors=list(result.errors),
         warnings=result.warnings,
         raw_yaml=face.content if include_raw else None,

dataface/agent_api/cache.py

@@ -53,7 +53,7 @@ def project_cache_ctx(
     Precedence: ``no_cache=True`` (the CLI's ``--no-cache``) skips the cache
     entirely; ``cache_path`` (``--cache PATH``, or its ``DFT_CACHE_PATH`` env
     backing) opens that persistent file. Otherwise the project's
-    ``dataface.yml`` ``cache:`` block picks the location — a configured ``path``
+    ``dbt_charts.yml`` ``cache:`` block picks the location — a configured ``path``
     opens that file (created if absent); no path opens the zero-config
     in-memory default. A project-level ``cache: false`` defaults the *cascade*
     to off without closing the door on a nearer scope's opt-in, so it still