dataface 0.1.5.dev48__py3-none-any.whl → 0.1.5.dev151__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -19,7 +19,7 @@ dft validate faces/my_dashboard.yml
 To verify that your database connection works, run a simple query:
 
 ```bash
-dft query 'SELECT 1' --source <your_source>
+dft query <your_source> 'SELECT 1'
 ```
 
 A successful result means your data source is reachable.
@@ -138,7 +138,7 @@ variables:
   region:
     input: select                  # See `dft docs variables` for all 14 input types
     options: { static: [US, EU, APAC] }
-    default: US
+    # No default: starts on All regions
 ```
 
 Reference variables inside queries with bare `{{ region }}` — no `variables.` prefix.
@@ -461,7 +461,6 @@ charts:
 
     # Style + behavior
     sort: { by: total, order: desc }
-    stack: zero               # false | zero | normalize | center
     format: integer           # named alias or raw D3 spec (e.g. ",.0f")
     x_label: "Month"
     y_label: "Revenue (USD)"
@@ -470,7 +469,7 @@ charts:
 
     style:                    # Chart-local style patch (typed; not raw CSS) — paint only
       orientation: vertical   # style: does NOT accept height or aspect_ratio
-      stack: true
+      stack: zero               # false | true | zero | normalize | center
 ```
 
 ### Chart types (29 total)
@@ -523,7 +522,6 @@ All chart types accept the channels and style fields below — but each type rej
 | `longitude` | string | Longitude field (point/bubble map) |
 | `background` | string \| object | Background channel — color, `{value}`, `{field, scale/when}`, or map layer |
 | `sort` | object | `{by, order}` — categorical sort |
-| `stack` | bool \| enum | `false`, `zero`, `normalize`, or `center` |
 | `link` | string | Click-through URL template for drill-down links |
 | `filters` | object | Post-execution row filters: `{col: var_name}` (implicit `eq`) or `{col: {op: var}}` where op is one of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `not_in`, `between`. Implicit-eq values may also be Jinja templates (e.g. `"{{ region }}"`) resolved at execute time. A filter is skipped when the variable is `None`, `""`, or renders to `"none"`. |
 | `layers` | list | Layer definitions for `type: layered` (see [Composition](#composition)) |
@@ -561,7 +559,8 @@ color: segment         # Optional: one line per segment
 type: area
 x: date
 y: value
-stack: normalize       # 100% stacked
+style:
+  stack: normalize     # 100% stacked
 
 # scatter — x and y numeric
 type: scatter
@@ -695,7 +694,6 @@ layers:
   - type: bar                       # bar | line | area | circle | square | tick | rule | trail | rect | image | scatter
     y: actual
     label: Actual
-    fill: "#0369a1"                 # static paint (use fill:, not color: {value:})
   - type: line
     y: target
     label: Target
@@ -704,7 +702,7 @@ layers:
       title: "Target"
 ```
 
-Each layer accepts: `type`, `query` (optional layer-specific query), `x`, `y`, `label`, `color` (data channel, bare field name), `fill` (static hex paint for fixed-color marks), `size`, `shape`, `axis_y`. Vega-Lite `encoding:` is not allowed inside a layer — use the typed channels.
+Each layer accepts: `type`, `query` (optional layer-specific query), `x`, `y`, `label`, `color` (data channel, bare field name), `axis_y`. Vega-Lite `encoding:` is not allowed inside a layer — use the typed channels.
 
 ### Conditional formatting
 
@@ -846,7 +844,7 @@ variables:
     description: "Restrict every query to one region."
     options:
       static: [US, EU, APAC]
-    default: US
+    # No default: starts on All regions
 ```
 
 Input types (14 total):
@@ -894,7 +892,7 @@ variables:
   product:
     input: select
     options:
-      static: [All, Electronics, Clothing]    # Hardcoded list
+      static: [Electronics, Clothing]         # Hardcoded list; blank -- All -- is implicit
       # OR
       query: products_list                     # Query whose first column is the option list
       column: product_name                     # Optional: which column in that query
@@ -907,6 +905,8 @@ variables:
 
 Top-level option-source binding (alternative to `options:`): `column`, `query`, `dimension` (MetricFlow), `measure` (MetricFlow), `model` (dbt).
 
+For `select` and `multiselect`, omitting `default` starts the variable unset. The renderer adds a blank `-- All --` option for that unset state; `{{ filter('column', variable) }}` emits `1=1` unless the SQL call site opts into `none='deny'`.
+
 Disabled forms:
 
 ```yaml

dataface/_docs_site.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import os
 
-DEFAULT_DOCS_SITE_URL = "https://docs.dataface.com"
+DEFAULT_DOCS_SITE_URL = "https://docs.it-dataface.com"
 
 
 def docs_site_url() -> str:

dataface/agent_api/__init__.py

@@ -37,10 +37,6 @@ CLI/MCP files that contain logic beyond parse-and-dispatch.
 """
 
 from dataface.agent_api import skills as skills
-from dataface.agent_api._paths import (
-    RenderSetup as RenderSetup,
-    setup_render_for_face as setup_render_for_face,
-)
 from dataface.agent_api.dashboards import (
     RenderedDashboard as RenderedDashboard,
     render_dashboard as render_dashboard,
@@ -55,8 +51,10 @@ from dataface.agent_api.init import (
     InitResult as InitResult,
     init_project as init_project,
 )
+from dataface.agent_api.project import Project as Project
 from dataface.agent_api.query import QueryFaceResult, query_face
 from dataface.agent_api.validate import ValidateDashboardArgs, ValidateResult
+from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
 
 __all__ = [
     "DescribeFaceArgs",
@@ -65,8 +63,9 @@ __all__ = [
     "DocsResult",
     "DocsSearchHit",
     "InitResult",
+    "Project",
+    "ProjectSourcesConfig",
     "QueryFaceResult",
-    "RenderSetup",
     "RenderedDashboard",
     "Topic",
     "ValidateDashboardArgs",
@@ -75,5 +74,4 @@ __all__ = [
     "init_project",
     "query_face",
     "render_dashboard",
-    "setup_render_for_face",
 ]

dataface/agent_api/_init_templates/README.md

@@ -10,7 +10,7 @@ for your data project.
 
 ## Authoring modes
 
-**YAML (`.yml`)** — structured dashboards with queries, charts, and layout.
+**YAML (`.yaml`)** — structured dashboards with queries, charts, and layout.
 See the [dataface guide](guide) for a working example covering queries, charts, and variables.
 
 **Markdown (`.md`)** — prose pages like this one. Add YAML frontmatter for
@@ -18,7 +18,7 @@ queries and charts, then embed them inline with `{% raw %}{{ chart my_chart }}{%
 
 ## Next steps
 
-1. Open `faces/guide.yml` and tweak the content.
+1. Open `faces/guide.yaml` and tweak the content.
 2. Run `dft serve` and open the URL it prints.
-3. Add new `.yml` or `.md` files under `faces/` — they appear automatically.
+3. Add new `.yaml` or `.md` files under `faces/` — they appear automatically.
 4. Run `dft validate` to validate your face YAML for errors.

dataface/agent_api/_init_templates/{guide.yml → guide.yaml}

@@ -20,7 +20,7 @@ description: "A tour of Dataface: queries, charts, layout, KPIs, and variables."
 text: |
   Welcome to **Dataface** — dashboards as YAML files.
 
-  This file is your starter guide. Edit it, add new `.yml` files under
+  This file is your starter guide. Edit it, add new `.yaml` files under
   `faces/`, and run `dft serve` to preview everything in your browser.
 
 # ── Queries ───────────────────────────────────────────────────────────────────
@@ -105,14 +105,13 @@ charts:
 # ── Variables ─────────────────────────────────────────────────────────────────
 # Variables add interactive dropdowns. Wire them to SQL queries with {{ varname }}.
 # With `type: values` data above they show the UI but don't filter — swap to SQL
-# queries and use `WHERE category = '{{ segment }}'` to make them live.
+# queries and use `WHERE {{ filter('category', segment) }}` to make them live.
 variables:
   segment:
     label: Segment
     input: select
-    default: All
     options:
-      static: [All, Software, Services, Hardware]
+      static: [Software, Services, Hardware]
 
 # ── Layout ────────────────────────────────────────────────────────────────────
 # `rows:` stacks content vertically.

dataface/agent_api/_paths.py

@@ -5,23 +5,67 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 
-from dataface.core.execute.adapters import AdapterRegistry, build_adapter_registry
+from dataface.core.execute.adapters import (
+    AdapterRegistry as AdapterRegistry,
+    build_adapter_registry as build_adapter_registry,
+)
 from dataface.core.project_roots import (
-    discover_render_context,
-    discovery_boundary_for_face,
-    find_dataface_project,
+    discover_render_context as discover_render_context,
+    discovery_boundary_for_face as discovery_boundary_for_face,
+    find_dft_root as find_dft_root,
 )
 from dataface.core.scoped_paths import (
-    _resolve_against_project,
-    project_root_for as project_root_for,
-    resolve_scoped_path as resolve_scoped_path,
+    resolve_scoped_path as _core_resolve_scoped_path,
 )
 
 
+def resolve_project_dir(project_dir: Path | None) -> Path:
+    """Resolve the caller's `project_dir`, walking up from cwd when omitted.
+
+    Boundary helper: every agent_api / CLI callsite that today forwards a
+    possibly-None `project_dir` into a core helper routes through this so the
+    cwd read stays at the agent_api boundary, not inside `dataface/core`.
+    """
+    if project_dir is not None:
+        return project_dir.resolve()
+    cwd = Path.cwd().resolve()
+    return find_dft_root(cwd) or cwd
+
+
+def resolve_project_dir_from_paths(
+    paths: list[Path] | None, project_dir: Path | None
+) -> Path:
+    """Resolve project_dir for a multi-path CLI verb (validate / describe).
+
+    Explicit `--project-dir` wins. Otherwise, when all supplied paths are
+    absolute, walk up from the first path's parent to anchor on the project
+    that contains the file. Otherwise fall back to a cwd walk.
+    """
+    if project_dir is not None:
+        return project_dir.resolve()
+    if paths and all(p.is_absolute() for p in paths):
+        anchor = paths[0].parent.resolve()
+        return find_dft_root(anchor) or anchor
+    return resolve_project_dir(None)
+
+
+def resolve_scoped_path(path: Path, project_dir: Path | None = None) -> Path:
+    """agent_api wrapper: resolves `None → cwd-walked root` at the boundary,
+    then delegates to `core.scoped_paths.resolve_scoped_path`.
+
+    Absolute paths with no explicit `project_dir` resolve directly (no
+    containment check) — the caller supplied the path, so no project context is
+    needed to validate containment.
+    """
+    if path.is_absolute() and project_dir is None:
+        return path.resolve()
+    return _core_resolve_scoped_path(path, resolve_project_dir(project_dir))
+
+
 def no_project_hint(project_dir: Path | None) -> str:
     """Return a hint string when no project marker is found, else empty string."""
     check = project_dir if project_dir is not None else Path.cwd()
-    if find_dataface_project(check) is not None:
+    if find_dft_root(check) is not None:
         return ""
     return (
         f" No Dataface project marker found at or above {check}."
@@ -30,89 +74,93 @@ def no_project_hint(project_dir: Path | None) -> str:
 
 
 @dataclass(frozen=True)
-class RenderSetup:
-    """Resolved arguments for an `agent_api.render_dashboard` call.
-
-    Bundles the scoped path, scoped base, and adapter registry produced by
-    discovery. CLI/serve callers building this from a face on disk avoid
-    duplicating discovery boilerplate; tests can construct one directly.
-    """
+class FaceRenderContext:
+    """Resources resolved from a face path + project root for rendering."""
 
-    adapter_registry: AdapterRegistry
+    face_file: Path
     scoped_path: Path | None
-    scoped_base: Path | None
+    scoped_base: Path
+    project_root: Path
+    output_dir: Path
+    adapter_registry: AdapterRegistry
 
 
-def setup_render_for_face(
+def build_face_render_context(
     face_path: Path,
     project_dir: Path | None = None,
     *,
     read_only: bool = True,
-) -> tuple[RenderSetup, Path]:
-    """Build a RenderSetup + resolved face_file for a face on disk.
+) -> FaceRenderContext:
+    """Resolve a face path, walk for dbt context, and build the adapter registry.
 
-    Mirrors `core.render.face_api.render_face`'s discovery: walk upward from
-    the face's parent to find dbt_project.yml and any sibling _sources.yaml.
-    `project_dir` overrides project_root for project-level data paths but
-    never the discovered dbt path.
+    ``project_dir=None`` means "walk freely from the face's parent" — used by
+    the CLI when ``--project-dir`` is omitted so a face under a dbt sub-project
+    still anchors on that sub-project's root. A given ``project_dir`` is
+    authoritative; the walk only contributes the dbt project path.
     """
-    face_file = face_path
-    if not face_file.is_absolute():
-        face_file = _resolve_against_project(face_file, project_dir)
+    if face_path.is_absolute():
+        face_file = face_path.resolve()
+    elif ".." in face_path.parts:
+        face_file = (Path.cwd() / face_path).resolve()
     else:
-        face_file = face_file.resolve()
-
-    project_root, dbt_project_path = discover_render_context(
+        anchor = (
+            project_dir.resolve()
+            if project_dir is not None
+            else resolve_project_dir(None)
+        )
+        face_file = (anchor / face_path).resolve()
+
+    walk_root, dbt_project_path = discover_render_context(
         face_file.parent,
         discovery_boundary_for_face(face_file.parent, project_dir),
     )
-    if project_dir:
-        project_root = project_dir.resolve()
+    project_root = project_dir.resolve() if project_dir is not None else walk_root
 
     try:
         scoped_path: Path | None = face_file.relative_to(project_root)
-        scoped_base: Path | None = project_root
     except ValueError:
         scoped_path = face_file
-        scoped_base = None
 
-    adapter_registry = build_adapter_registry(
-        project_root,
-        read_only=read_only,
-        dbt_project_path=dbt_project_path,
-    )
-    return (
-        RenderSetup(
-            adapter_registry=adapter_registry,
-            scoped_path=scoped_path,
-            scoped_base=scoped_base,
+    return FaceRenderContext(
+        face_file=face_file,
+        scoped_path=scoped_path,
+        scoped_base=project_root,
+        project_root=project_root,
+        output_dir=project_root,
+        adapter_registry=build_adapter_registry(
+            project_root, read_only=read_only, dbt_project_path=dbt_project_path
         ),
-        face_file,
     )
 
 
-def setup_render_for_yaml(
+@dataclass(frozen=True)
+class YamlRenderContext:
+    """Resources resolved from a project root for rendering inline YAML."""
+
+    project_root: Path
+    output_dir: Path
+    adapter_registry: AdapterRegistry
+
+
+def build_yaml_render_context(
     project_dir: Path | None = None,
     *,
     read_only: bool = True,
-) -> RenderSetup:
-    """Build a RenderSetup for a stdin/yaml_content render (no face path).
+) -> YamlRenderContext:
+    """Walk for dbt context and build the adapter registry for inline YAML.
 
-    Walks upward from `project_dir` (or cwd) to discover the dbt project so
-    yaml fed via stdin still resolves dbt-managed sources correctly.
+    ``project_dir=None`` walks from cwd to discover the project root; a given
+    ``project_dir`` is authoritative.
     """
-    output_dir = project_root_for(project_dir)
-    project_root, dbt_project_path = discover_render_context(output_dir, None)
-    if project_dir:
-        project_root = output_dir
-
-    adapter_registry = build_adapter_registry(
-        project_root,
-        read_only=read_only,
-        dbt_project_path=dbt_project_path,
+    anchor = (
+        project_dir.resolve() if project_dir is not None else resolve_project_dir(None)
     )
-    return RenderSetup(
-        adapter_registry=adapter_registry,
-        scoped_path=None,
-        scoped_base=project_root,
+    walk_root, dbt_project_path = discover_render_context(anchor, None)
+    project_root = anchor if project_dir is not None else walk_root
+    return YamlRenderContext(
+        project_root=project_root,
+        output_dir=project_root,
+        adapter_registry=build_adapter_registry(
+            project_root, read_only=read_only, dbt_project_path=dbt_project_path
+        ),
     )

dataface/agent_api/dashboards.py

@@ -108,7 +108,7 @@ class RenderDashboardArgs(BaseModel):
 
 
 def list_dashboards(
-    directory: Path = Path("."),
+    directory: Path,
     recursive: bool = True,
 ) -> ListDashboardsResult:
     """List all available dashboards in a directory."""
@@ -197,8 +197,9 @@ def list_dashboards(
 
 def get_dashboard(
     path: Path,
+    *,
+    project_dir: Path,
     include_raw: bool = False,
-    project_dir: Path | None = None,
 ) -> CompiledDashboard:
     """Get the compiled structure of a dashboard."""
     try:

dataface/agent_api/describe.py

@@ -7,11 +7,11 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
-from dataface.core.compile.models.chart.compiled import (
+from dataface.core.compile.models.chart.normalized import (
     Chart,
 )
-from dataface.core.compile.models.face.compiled import Layout
-from dataface.core.compile.models.query.compiled import (
+from dataface.core.compile.models.face.normalized import Layout
+from dataface.core.compile.models.query.normalized import (
     CsvQuery,
     DbtModelQuery,
     HttpQuery,
@@ -84,7 +84,11 @@ class DescribeFaceArgs(BaseModel):
 
     path: Path = Field(description="Path to the dashboard YAML file to describe")
     project_dir: Path | None = Field(
-        None, description="Project root for resolving relative paths"
+        default=None,
+        description=(
+            "Project root for resolving relative paths. Optional on the wire; "
+            "the MCP server injects ctx.default_project_dir or cwd when omitted."
+        ),
     )
 
 
@@ -186,7 +190,7 @@ def _encoding_for_chart(chart: Chart) -> dict[str, Any]:
 # ---------------------------------------------------------------------------
 
 
-def describe_face(path: Path, project_dir: Path | None = None) -> DescribeFaceResult:
+def describe_face(path: Path, *, project_dir: Path) -> DescribeFaceResult:
     """Describe the structure of a face: queries, charts, variables, layout."""
     from dataface.agent_api._paths import no_project_hint, resolve_scoped_path
     from dataface.core.compile.compiler import compile_file
@@ -300,7 +304,8 @@ def describe_face(path: Path, project_dir: Path | None = None) -> DescribeFaceRe
 
 def describe_paths(
     paths: list[Path],
-    project_dir: Path | None = None,
+    *,
+    project_dir: Path,
 ) -> list[DescribeFaceResult]:
     """Describe N face files / directories.
 
@@ -310,13 +315,13 @@ def describe_paths(
     """
     out: list[DescribeFaceResult] = []
     for p in paths:
-        out.extend(_describe_one_path(p, project_dir=project_dir))
+        out.extend(_describe_one_path(p, project_dir))
     return out
 
 
 def _describe_one_path(
     path: Path,
-    project_dir: Path | None = None,
+    project_dir: Path,
 ) -> list[DescribeFaceResult]:
     """Per-argv expansion: file → [one], dir → walk."""
     # WHY: dataface.core.inspect.manifest_utils triggers the inspect package

dataface/agent_api/describe_query.py

@@ -109,7 +109,7 @@ def _duckdb_describe(
     sql: str, source: str | None, adapter_registry: AdapterRegistry
 ) -> list[DescribeQueryColumn]:
     """Run DESCRIBE ({sql}) via the registry's read-only SqlAdapter."""
-    from dataface.core.compile.models.query.compiled import SqlQuery
+    from dataface.core.compile.models.query.normalized import SqlQuery
 
     result = adapter_registry.execute(SqlQuery(sql=f"DESCRIBE ({sql})", source=source))
     if result.error: