dataface 0.2.1.dev516__py3-none-any.whl → 0.2.1.dev647__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -155,7 +155,7 @@ Reference variables inside queries with bare `{{ region }}` — no `variables.`
 charts:
   revenue_trend:
     query: revenue                 # Named query reference
-    type: line                     # See `dft docs charts` for all 29 chart types
+    type: line                     # See `dft docs charts` for all 16 authorable chart types
     x: month
     y: total
     color: segment
@@ -413,7 +413,7 @@ Common fields (all query types):
 | `filters` | Post-execution result filters |
 | `limit` | Maximum rows returned |
 | `pivot` | Table-rendering cross-tab hint: `{column, value}` |
-| `ignore` | Diagnostic codes to suppress (e.g. `["fanout_risk"]`) |
+| `ignore` | Diagnostic codes to suppress (e.g. `["WARN-FANOUT-RISK"]`) |
 
 SQL fields: `sql`, `setup_sql`.
 MetricFlow fields: `metrics`, `dimensions`, `time_grain`.
@@ -531,25 +531,25 @@ charts:
       # bar/area families also accept style.orientation and style.stack
 ```
 
-### Chart types (29 total)
+### Chart types (16 authorable)
 
 Set `type:` to one of:
 
-**Basic** (one mark per chart) — `bar`, `line`, `area`, `scatter`, `pie`, `donut`, `kpi`, `table`.
+**Basic** (one mark per chart) -- `bar`, `line`, `area`, `scatter`, `pie`, `donut`, `kpi`, `table`.
 
-**Statistical** — `boxplot`, `errorbar`, `errorband`, `histogram`, `heatmap`.
+**Statistical** -- `histogram`, `heatmap`.
 
-**Geographic** — `geoshape`, `map`, `point_map`, `bubble_map`.
+**Geographic** -- `geoshape`, `map`, `point_map`, `bubble_map`.
 
-**Marks** (direct Vega-Lite mark passthroughs) — `circle`, `square`, `tick`, `rule`, `trail`, `rect`, `arc`, `image`.
+**Overlays** -- `bar`, `line`, `area`, and `scatter` accept a `layers:` field for mixed-mark or dual-axis charts (see [Combo charts](#combo-charts-barlinearea-with-layers) and [Composition](#composition)).
 
-**Overlays** — `bar`, `line`, `area`, and `scatter` accept a `layers:` field for mixed-mark or dual-axis charts (see [Combo charts](#combo-charts-barlinearea-with-layers) and [Composition](#composition)).
+**Sparklines** -- `spark_bar` (compact horizontal bars used in profiler cards).
 
-**Sparklines** — `spark_bar` (compact horizontal bars used in profiler cards).
+**Auxiliary** -- `callout` (message card with a `style.tone:` field; `message:` required).
 
-**Auxiliary** — `callout` (message card with a `style.tone:` field; `message:` required), `auto` (auto-detect from data — internal-only; not surfaced in UI dropdowns).
+Note: `donut` is an internal alias for `pie` -- `donut` is accepted but normalizes to `pie` internally. `auto` is an internal sentinel (not authored). `boxplot`, `errorbar`, and `errorband` are Vega-Lite mark types that are not in the authorable surface.
 
-Aliases that map to underlying marks: `scatter` → `circle`, `heatmap` → `rect`, `pie` / `donut` → `arc`, `histogram` → `bar` with binning, `map` → `geoshape`.
+Type aliases: `scatter` uses a circle mark, `heatmap` uses rect, `pie`/`donut` use arc, `histogram` uses bar with binning, `map` maps to geoshape.
 
 ### Shared chart fields
 
@@ -709,11 +709,6 @@ color: event_count
 type: histogram
 x: amount
 
-# boxplot / errorbar / errorband — statistical primitives
-type: boxplot
-x: region
-y: latency
-
 # geoshape — choropleth via GeoJSON
 type: geoshape
 geo_source: us-states
@@ -1115,26 +1110,26 @@ rows:
 
 ## Errors
 
-Dataface errors carry a machine-readable code in the form `DF-<CATEGORY>-<SLUG>`. The error message includes the code and a pointer to docs.
+Dataface errors carry a machine-readable code in the form `ERR-<SLUG>`. The error message includes the code and a pointer to docs; a separate `domain` field on the error records where it originated (the code string itself has no domain segment).
 
 ```
-DatafaceError [DF-RENDER-KPI-MULTIROW]: KPI chart 'revenue' returned 12 rows but `value` is a column reference.
+DatafaceError [ERR-KPI-MULTIROW]: KPI chart 'revenue' returned 12 rows but `value` is a column reference.
   Add LIMIT 1 or aggregate down to one row.
 ```
 
-Active code categories (see `dataface/core/errors/codes_*.py` for the authoritative registry):
+Active domains (see `dataface/core/diagnostics/codes_*.py` for the authoritative registry):
 
-| Prefix | Meaning |
+| Domain | Meaning |
 |--------|---------|
-| `DF-COMPILE-*` | Compile-time errors (missing fields, unknown references, malformed YAML) |
-| `DF-RENDER-*` | Chart rendering errors (wrong row counts, unknown chart types, format issues) |
-| `DF-EXECUTE-*` | Query execution errors (missing sources, inline-source policy, source typing) |
-| `DF-SERVE-*` | Server startup errors (invalid theme, launch failures) |
-| `DF-UNKNOWN-*` | Fallback codes for legacy string-message errors not yet migrated |
+| `compile` | Compile-time errors (missing fields, unknown references, malformed YAML) |
+| `render` | Chart rendering errors (wrong row counts, unknown chart types, format issues) |
+| `execute` | Query execution errors (missing sources, inline-source policy, source typing) |
+| `serve` | Server startup errors (invalid theme, launch failures) |
+| `unknown` | Fallback codes for legacy string-message errors not yet migrated |
 
 The registry is being filled out incrementally — some compile-time and variable-resolution errors still raise as plain `DatafaceError` without a structured code.
 
-Run `dft docs error-reference` for the full generated reference — every registered code, its message template, and its docs pointer, straight from `dataface.core.errors.REGISTRY`. Run `dft validate <face>` to validate a face and see structured error details.
+Run `dft docs errors` to list every registered code with a one-line summary, straight from `dataface.core.diagnostics.REGISTRY`. Run `dft docs error-reference` for the full reference — message template and docs pointer included. (`dft docs warnings` / `dft docs warning-reference` are the equivalents for `WARN-*` codes.) Run `dft validate <face>` to validate a face and see structured error details.
 
 **See also:** `dft docs queries`, `dft docs charts`, `dft docs variables` (where most errors originate),
 `dft docs all` (whole reference for context).

dataface/_install_hint.py

@@ -1,26 +1,66 @@
-"""Canonical install-command hints surfaced from runtime error messages.
+"""Install-command hints surfaced from runtime error messages.
 
 Centralized here so every CLI/runtime hint stays in lock-step with
-``dataface/README.md`` and the wheel-shipped MCP-setup skill. The bare
-``pip install`` form is used (not ``uv pip install``) — customers may
-not have ``uv`` on PATH, and bare ``pip`` is universally available with
-any Python install. ``cli/_extras.py`` separately emits ``uv pip install
---python <path>`` when uv is the active installer (the smoke-install CI
-test pins both legs); this helper is only the canonical fallback string.
-
-If you change the canonical form, also update the TypeScript mirror at
-``apps/ide/vscode-extension/src/utils/install-hint.ts``.
+``dataface/README.md`` and the wheel-shipped MCP-setup skill.
+
+This module only ever runs from an install that already exists (a
+missing extra, a missing optional dependency like ``uvicorn``) — so the
+right question is "how did *this* install get here", not "is `uv` on
+PATH". A pip/venv install with `uv` merely available on PATH must keep
+recommending `pip`; recommending `uv tool install` there would create a
+second, parallel installation alongside the one already running.
+``cli/_extras.py`` separately emits ``uv pip install --python <path>``
+when uv is the active installer for *adding an extra to the current
+interpreter* (a different question); this helper is the canonical
+reinstall hint.
+
+The TypeScript mirror at
+``apps/ide/vscode-extension/src/utils/install-hint.ts`` uses a
+*different* signal (is `uv` on PATH) because it runs before anything is
+installed — there is no existing install to inspect there. If you
+change one file, check whether the other's signal still applies before
+mirroring the change.
 """
 
 from __future__ import annotations
 
+import os
+import sys
+from pathlib import Path
+
+
+def _is_uv_tool_install() -> bool:
+    """True if this process is running from a `uv tool install` environment.
+
+    `uv tool install` creates an isolated virtualenv under uv's tool
+    directory (`uv tool dir`; e.g. `~/.local/share/uv/tools` on Linux,
+    the platform's per-user data dir on macOS/Windows, overridable via
+    `UV_TOOL_DIR`) with the tool name as an immediate child directory.
+    `sys.prefix` is that tool venv's own directory — it's the value uv
+    set up when creating the venv, not a filesystem fact to be
+    recomputed. Deliberately NOT `Path(sys.executable).resolve()`: a
+    uv-tool venv's `bin/python` is a symlink back into uv's *shared*
+    interpreter directory (`uv/python/...`), so resolving it walks
+    straight out of `uv/tools/` and defeats this check.
+    """
+    prefix = Path(sys.prefix)
+    tool_dir = os.environ.get("UV_TOOL_DIR")
+    if tool_dir and prefix.parent == Path(tool_dir):
+        return True
+    parts = prefix.parts
+    return any(
+        a == "uv" and b == "tools" for a, b in zip(parts, parts[1:], strict=False)
+    )
+
 
 def install_hint(extra: str | None = None) -> str:
-    """Return the canonical ``pip install`` one-liner for Dataface.
+    """Return the install one-liner that matches how this Dataface got installed.
 
     ``extra`` is an optional optional-dependency group (``"mcp"``,
     ``"chat"``, ``"playground"``, ``"bigquery"``); when set, the
     returned command installs Dataface with that extras bracket.
     """
     spec = f"dataface[{extra}]" if extra else "dataface"
+    if _is_uv_tool_install():
+        return f'uv tool install "{spec}"'
     return f'pip install "{spec}"'

dataface/agent_api/__init__.py

@@ -70,7 +70,7 @@ from dataface.core.dashboard import (
     RenderedDashboard as RenderedDashboard,
     render_dashboard as render_dashboard,
 )
-from dataface.core.errors.structured import StructuredError as StructuredError
+from dataface.core.diagnostics import Diagnostic as Diagnostic
 
 # Execution extension seams: the protocols a composition root injects, plus the
 # resolver base impls it subclasses. Re-exported so roots (CLI, MCP, serve,
@@ -85,7 +85,11 @@ from dataface.core.execute.source_resolver import (
     SourceResolver as SourceResolver,
 )
 from dataface.core.fonts import get_inter_font_path as get_inter_font_path
-from dataface.core.project import Project as Project
+from dataface.core.project import (
+    FaceFile as FaceFile,
+    InMemoryFace as InMemoryFace,
+    Project as Project,
+)
 from dataface.core.render.board_links import LinkContext as LinkContext
 from dataface.core.render.errors import RenderError as RenderError
 
@@ -94,9 +98,12 @@ __all__ = [
     "CompileResult",
     "DescribeFaceArgs",
     "DescribeFaceResult",
+    "Diagnostic",
     "DocsArgs",
     "DocsResult",
     "DocsSearchHit",
+    "FaceFile",
+    "InMemoryFace",
     "InitResult",
     "LinkContext",
     "Project",
@@ -107,7 +114,6 @@ __all__ = [
     "RenderedDashboard",
     "RenderError",
     "SchemaHints",
-    "StructuredError",
     "Topic",
     "ValidateDashboardArgs",
     "ValidateResult",

dataface/agent_api/_paths.py

@@ -2,20 +2,29 @@
 
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass
 from pathlib import Path
 
 # tach-ignore(agent_api->cli: runtime host-type guard in no_project_hint; the local-filesystem check needs a non-cli signal on Project — deferred)
 from dataface.cli.filesystem_project import FilesystemProject
-from dataface.core.project import Project
+from dataface.core.diagnostics import (
+    ERR_FILE_NOT_FOUND,
+    ERR_INTERNAL,
+    Diagnostic,
+)
+from dataface.core.diagnostics.base import DatafaceError
+from dataface.core.project import (
+    FACES_SUBDIR,
+    FaceFile,
+    Project,
+    ProjectPath,
+    assert_relpath,
+)
 from dataface.core.project_roots import (
     find_dft_root as find_dft_root,
     find_project_root as find_project_root,
 )
-from dataface.core.scoped_paths import (
-    resolve_face_path as resolve_face_path,
-    resolve_scoped_path as resolve_scoped_path,
-)
 
 
 def resolve_project_dir(project_dir: Path | None) -> Path:
@@ -66,6 +75,74 @@ def no_project_hint(project: Project) -> str:
     )
 
 
+def resolve_face_path(path: Path, project: Project) -> ProjectPath:
+    """User/agent-supplied face path -> ProjectPath.
+
+    Absolute and ``..``-leading paths are explicit locations: they relativize
+    through the containment seam (``project.path_for_fspath``, 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 exist. A
+    bare relative name (no explicit location) gets the faces-first retry: for
+    a relpath that doesn't exist in the project store and has no explicit
+    ``faces/`` prefix, retries under ``FACES_SUBDIR``. This lets a
+    ``search_dashboards`` ``face_path`` of ``'looker/x.yaml'`` (``faces/``
+    prefix stripped at search time) resolve to ``faces/looker/x.yaml``
+    without producing a ``faces/faces/...`` double prefix when the caller
+    already supplies the full ``faces/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/.
+    """
+    if path.is_absolute():
+        return project.path_for_fspath(path)
+    if ".." in path.parts:
+        return project.path_for_fspath(Path(os.path.normpath(Path.cwd() / path)))
+    relpath = str(path)
+    assert_relpath(relpath)
+    if project.exists(relpath):
+        return project.path(relpath)
+    if not relpath.startswith(f"{FACES_SUBDIR}/"):
+        candidate = f"{FACES_SUBDIR}/{relpath}"
+        if project.exists(candidate):
+            return project.path(candidate)
+    return project.path(relpath)  # caller reports not-found
+
+
+def resolve_face_or_error(path: Path, project: Project) -> FaceFile | Diagnostic:
+    """Faces-first resolve a path to a stored ``FaceFile``, or a structured error.
+
+    The one agent_api seam turning a user-supplied path into the compiler's
+    located input — shared by the CLI render verb and the AI render tool so the
+    faces-first retry and the ``ERR-FILE-NOT-FOUND`` envelope never drift
+    between surfaces. Returns a ``Diagnostic`` for an escaping path
+    (``ERR-INTERNAL``) or a missing face (``ERR-FILE-NOT-FOUND``).
+    """
+    try:
+        resolved = resolve_face_path(path, project)
+    except ValueError as exc:
+        return DatafaceError.from_code(ERR_INTERNAL, message=str(exc)).to_diagnostic()
+    if not resolved.exists():
+        return DatafaceError.from_code(
+            ERR_FILE_NOT_FOUND,
+            path=resolved.relpath,
+            hint=no_project_hint(project),
+        ).to_diagnostic(file=resolved.relpath)
+    if (
+        isinstance(project, FilesystemProject)
+        and not (project.root / resolved.relpath).is_file()
+    ):
+        # A directory (or other non-file) resolves + exists on disk but read_face
+        # would raise past the structured envelope. This is a filesystem-only
+        # concern — a non-filesystem store's `exists()` already gates real faces.
+        return DatafaceError.from_code(
+            ERR_INTERNAL, message=f"Not a file: {resolved.relpath}"
+        ).to_diagnostic(file=resolved.relpath)
+    return resolved.read_face()
+
+
 @dataclass(frozen=True)
 class FaceRenderContext:
     """Path resolution result from a face path + project root.

dataface/agent_api/cache.py

@@ -1,8 +1,13 @@
 """Cache constructors at the agent_api boundary."""
 
+from __future__ import annotations
+
 from collections.abc import Generator
 from contextlib import contextmanager
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+from dataface.core.compile.config import resolve_cache_boot
 
 # Re-exported: TrivialDuckDBCache is the declared return type of open_cache,
 # so embedders annotating a held cache reach it here without a core import.
@@ -10,29 +15,69 @@ from dataface.core.execute.trivial_local_cache import (
     TrivialDuckDBCache as TrivialDuckDBCache,
 )
 
-__all__ = ["TrivialDuckDBCache", "open_cache", "cache_ctx"]
+if TYPE_CHECKING:
+    from dataface.cli.filesystem_project import FilesystemProject
+
+__all__ = [
+    "TrivialDuckDBCache",
+    "open_cache",
+    "open_project_cache",
+    "project_cache_ctx",
+]
 
 
 def open_cache(path: Path | None) -> TrivialDuckDBCache:
-    """Open the query-result cache.
+    """Open the query-result cache at an already-resolved path.
 
     ``path=None`` opens an in-memory cache — ephemeral, discarded when closed.
     A path opens (or creates, if absent) a persistent DuckDB file, reused
     across invocations. Callers own the returned cache's lifecycle (close it).
+    Does not consult project config — use ``open_project_cache`` for that.
     """
     return TrivialDuckDBCache(db_path=path)
 
 
-@contextmanager
-def cache_ctx(path: Path | None) -> Generator[TrivialDuckDBCache]:
-    """Open a cache scoped to a single command invocation; closes it on exit.
+def open_project_cache(
+    project: FilesystemProject,
+    *,
+    no_cache: bool = False,
+    cache_path: Path | None = None,
+) -> TrivialDuckDBCache | None:
+    """Open the query-result cache honoring project config, with overrides.
+
+    The caller owns the project instance. Pair this with
+    ``ProjectSession.from_project(project, cache=...)`` rather than
+    ``ProjectSession.open(project_dir, cache=...)`` — ``open()`` builds its own
+    project from the path, so composing it with this function constructs two.
 
-    Use for CLI verbs and composition roots that need a cache scoped to
-    a single command invocation. Long-lived processes (server boot, MCP
-    server) call ``open_cache()`` directly and own the lifecycle.
+    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``
+    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
+    opens a store; the resolved per-query policy decides what gets written.
+
+    Returns:
+        ``None`` only when ``no_cache=True`` — callers pass this straight
+        through as ``ProjectSession(cache=...)``.
     """
-    cache = open_cache(path)
+    boot = resolve_cache_boot(project, no_cache=no_cache, cache_path=cache_path)
+    return open_cache(boot.path) if boot.enabled else None
+
+
+@contextmanager
+def project_cache_ctx(
+    project: FilesystemProject,
+    *,
+    no_cache: bool = False,
+    cache_path: Path | None = None,
+) -> Generator[TrivialDuckDBCache | None]:
+    """Context-managed ``open_project_cache``; closes the cache on exit if opened."""
+    cache = open_project_cache(project, no_cache=no_cache, cache_path=cache_path)
     try:
         yield cache
     finally:
-        cache.close()
+        if cache is not None:
+            cache.close()

dataface/agent_api/dashboards.py

@@ -13,17 +13,16 @@ from typing import Any, Literal
 import yaml
 from pydantic import BaseModel, ConfigDict, Field, field_serializer
 
-from dataface.agent_api._paths import no_project_hint, resolve_face_path
+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.core.errors import (
-    DF_COMPILE_FILE_NOT_FOUND,
-    DF_UNKNOWN_INTERNAL,
-    StructuredError,
+from dataface.core.diagnostics import Diagnostic
+from dataface.core.project import (
+    FACES_SUBDIR,
+    Project,
+    ProjectDirectory,
+    ProjectPath,
 )
-from dataface.core.errors.base import DatafaceError
-from dataface.core.project import FACES_SUBDIR, Project, ProjectPath
-from dataface.core.warnings.base import RenderWarning
 
 # Top-level keys whose presence classifies a YAML mapping as a dashboard.
 DASHBOARD_KEYS = frozenset({"queries", "charts", "rows", "cols", "grid", "tabs"})
@@ -64,23 +63,27 @@ class SkippedFile(BaseModel):
 
 
 class ListDashboardsResult(BaseModel):
-    model_config = ConfigDict(frozen=True)
+    model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
 
     success: bool
-    errors: list[StructuredError] = []
+    errors: list[Diagnostic] = []
     dashboards: list[DashboardSummary] = []
     count: int = 0
-    directory: Path
+    directory: ProjectDirectory
     skipped_files: list[SkippedFile] = []
 
+    @field_serializer("directory")
+    def _serialize_directory(self, d: ProjectDirectory) -> str:
+        return d.relpath
+
 
 class CompiledDashboard(BaseModel):
     model_config = ConfigDict(frozen=True)
 
     success: bool
     dashboard: Face | None = None
-    errors: list[StructuredError] = []
-    warnings: list[RenderWarning] = []
+    errors: list[Diagnostic] = []
+    warnings: list[Diagnostic] = []
     raw_yaml: str | None = None
 
 
@@ -182,7 +185,7 @@ def list_dashboards(
         success=True,
         dashboards=dashboards,
         count=len(dashboards),
-        directory=project.root,
+        directory=project.directory(under),
         skipped_files=skipped,
     )
 
@@ -194,63 +197,16 @@ def get_dashboard(
     include_raw: bool = False,
 ) -> CompiledDashboard:
     """Get the compiled structure of a dashboard."""
-    try:
-        file_path = resolve_face_path(path, project)
-    except ValueError as exc:
-        return CompiledDashboard(
-            success=False,
-            errors=[
-                DatafaceError.from_code(
-                    DF_UNKNOWN_INTERNAL, message=str(exc)
-                ).to_structured()
-            ],
-        )
-
-    if not file_path.exists():
-        hint = no_project_hint(project)
-        return CompiledDashboard(
-            success=False,
-            errors=[
-                DatafaceError.from_code(
-                    DF_COMPILE_FILE_NOT_FOUND,
-                    path=str(file_path),
-                    hint=hint,
-                ).to_structured(file=str(file_path))
-            ],
-        )
-    if not file_path.is_file():
-        return CompiledDashboard(
-            success=False,
-            errors=[
-                DatafaceError.from_code(
-                    DF_UNKNOWN_INTERNAL,
-                    message=f"Not a file: {path}",
-                ).to_structured(file=str(file_path))
-            ],
-        )
-
-    face_pf = project.path_for_fspath(file_path)
-    result = compile_file(face_pf, project=project)
-
-    raw_yaml: str | None = None
-    if include_raw:
-        try:
-            raw_yaml = face_pf.read_text()
-        except OSError as e:
-            return CompiledDashboard(
-                success=False,
-                errors=[
-                    DatafaceError.from_code(
-                        DF_UNKNOWN_INTERNAL,
-                        message=f"Failed to read file: {e}",
-                    ).to_structured(file=str(file_path))
-                ],
-            )
+    # 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])
+    result = compile_file(face)
 
     return CompiledDashboard(
         success=result.success,
         dashboard=result.face if result.success else None,
         errors=list(result.errors),
         warnings=result.warnings,
-        raw_yaml=raw_yaml,
+        raw_yaml=face.content if include_raw else None,
     )