dataface 0.1.2__py3-none-any.whl

dataface/__init__.py

@@ -0,0 +1,93 @@
+"""Dataface - dbt-native dataface and visualization layer.
+
+This package provides a declarative YAML-based approach to building
+datafaces (analytics dashboards) that integrate with dbt projects.
+
+Architecture:
+    The codebase is organized into:
+
+    - core/: The engine (compile, execute, render, serve, inspect)
+    - cli/: Command-line interface
+    - ai/: AI interfaces (MCP server, tool schemas, prompts)
+    - apps/: Web applications (playground, cloud)
+
+Quick Start:
+    >>> from pathlib import Path
+    >>> from dataface import compile, Executor, render
+    >>> from dataface.core.execute.adapters import build_adapter_registry
+    >>>
+    >>> # Compile YAML to Face
+    >>> result = compile(yaml_content)
+    >>> if result.success:
+    ...     face = result.face
+    ...
+    ...     # Create executor and render
+    ...     registry = build_adapter_registry(Path.cwd())
+    ...     executor = Executor(face, registry, query_registry=result.query_registry)
+    ...     svg = render(face, executor, format="svg")
+"""
+
+import logging
+from importlib.metadata import version as _v
+
+__version__ = _v("dataface")
+
+# Set up package-level logger
+# This logger is the parent for all dataface submodule loggers
+logger = logging.getLogger("dataface")
+
+# Configure a NullHandler to avoid "No handler found" warnings
+# Actual handlers should be configured by the application entry points (CLI, serve)
+logger.addHandler(logging.NullHandler())
+
+# Re-export from core for convenience
+from dataface.core import validate
+from dataface.core.compile import (
+    AnyQuery,
+    AuthoredFace,
+    Chart,
+    CompilationError,
+    CompileResult,
+    Face,
+    Layout,
+    LayoutItem,
+    Variable,
+    compile,
+    compile_file,
+)
+from dataface.core.execute import (
+    ExecutionError,
+    Executor,
+)
+
+# Import from render submodule
+# Note: We import `render` function but this shadows `dataface.render` module access
+# Tests that need to patch `dataface.core.render.renderer` should import the module directly
+from dataface.core.render import RenderError, render
+
+__all__ = [
+    # Version
+    "__version__",
+    # Logging
+    "logger",
+    # Compile
+    "compile",
+    "compile_file",
+    "CompileResult",
+    "Face",
+    "Chart",
+    "AnyQuery",
+    "Layout",
+    "LayoutItem",
+    "AuthoredFace",
+    "Variable",
+    "CompilationError",
+    # Execute
+    "Executor",
+    "ExecutionError",
+    # Render
+    "render",
+    "RenderError",
+    # Validate
+    "validate",
+]

dataface/_docs_site.py

@@ -0,0 +1,20 @@
+"""Public docs site base URL for CLI hints and cross-links."""
+
+from __future__ import annotations
+
+import os
+
+DEFAULT_DOCS_SITE_URL = "https://docs.dataface.com"
+
+
+def docs_site_url() -> str:
+    """Return the docs site base URL without a trailing slash.
+
+    ``DFT_DOCS_URL`` overrides the shipped default when set to a non-empty
+    value. Used by ``dft docs`` (web link on the topic index), the playground
+    gallery, and other surfaces that link out to the MkDocs site.
+    """
+    raw = os.environ.get("DFT_DOCS_URL", DEFAULT_DOCS_SITE_URL).strip()
+    if not raw:
+        return DEFAULT_DOCS_SITE_URL
+    return raw.rstrip("/")

dataface/_install_hint.py

@@ -0,0 +1,26 @@
+"""Canonical 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``.
+"""
+
+from __future__ import annotations
+
+
+def install_hint(extra: str | None = None) -> str:
+    """Return the canonical ``pip install`` one-liner for Dataface.
+
+    ``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"
+    return f'pip install "{spec}"'

dataface/agent_api/__init__.py

@@ -0,0 +1,79 @@
+"""dataface.agent_api — typed Python API for Dataface agent surfaces.
+
+This package is the canonical home for every function exposed to AI agents
+via CLI commands (``dataface/cli/commands/``) or MCP server modules
+(``dataface/ai/mcp/``).
+
+Contract
+--------
+Every function in this package must satisfy all three rules:
+
+1. **Typed args and typed returns.** Function signatures use concrete Python
+   types — ``Path``, ``str``, ``int``, Pydantic models, or ``TypedDict``
+   subclasses. Return types are never ``dict[str, Any]`` or JSON strings.
+   Callers should not need to parse, coerce, or guess the shape of results.
+
+2. **No Cloud/Django assumptions.** Do not import ``django``, Django ORM
+   models, ``HttpRequest``, ``settings``, or any ``apps.cloud`` module.
+   Functions here must work in a standalone Python environment — a CLI
+   session, a test, or an MCP server — without a running Django process.
+
+3. **I/O scoped to the verb.** A ``render`` function does not write to disk.
+   A ``save`` function writes exactly one file. An ``execute`` function runs
+   SQL and nothing else. Side effects must match what the verb name implies
+   and nothing more.
+
+Thin-wrapper rule
+-----------------
+``dataface/cli/commands/`` and ``dataface/ai/mcp/`` are *thin wrappers* over
+this package. They are permitted to contain only:
+
+- Argument parsing and output formatting
+- A single call into ``dataface.agent_api``
+
+Any business logic (validation, path resolution, compilation, execution,
+rendering) belongs here, not in the CLI or MCP layer.  Code review blocks
+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,
+)
+from dataface.agent_api.describe import (
+    DescribeFaceArgs,
+    DescribeFaceResult,
+    describe_face,
+)
+from dataface.agent_api.docs import DocsArgs, DocsResult, DocsSearchHit, Topic
+from dataface.agent_api.init import (
+    InitResult as InitResult,
+    init_project as init_project,
+)
+from dataface.agent_api.query import QueryFaceResult, query_face
+from dataface.agent_api.validate import ValidateDashboardArgs, ValidateResult
+
+__all__ = [
+    "DescribeFaceArgs",
+    "DescribeFaceResult",
+    "DocsArgs",
+    "DocsResult",
+    "DocsSearchHit",
+    "InitResult",
+    "QueryFaceResult",
+    "RenderSetup",
+    "RenderedDashboard",
+    "Topic",
+    "ValidateDashboardArgs",
+    "ValidateResult",
+    "describe_face",
+    "init_project",
+    "query_face",
+    "render_dashboard",
+    "setup_render_for_face",
+]

dataface/agent_api/_init_templates/agents_dft_snippet.md

@@ -0,0 +1,26 @@
+
+<!-- dft-dataface:start -->
+## Dataface
+
+This project uses [Dataface](https://github.com/fivetran/dataface) (`dft`) for visualizations, dashboards, and reports (YAML in `faces/`).
+
+Learn how to work here — run:
+
+- `dft skills dashboard-build`
+- `dft skills dashboard-design`
+- `dft skills report-design`
+- `dft skills dashboard-review`
+- `dft skills dataface-troubleshooting`
+
+| Command | Use for |
+|---------|---------|
+| `dft schema` → `dft schema SRC` → `dft schema SRC SCH` → `dft schema SRC SCH TBL` → `dft schema SRC SCH TBL COL` | Drill data hierarchy: sources → schemas → tables → columns (each positional arg narrows one level) |
+| `dft query` | Run queries |
+| `dft serve` | Preview dashboards |
+| `dft validate` | Check face YAML |
+| `dft render` | Export |
+
+Use `dft schema` for real names — do not invent columns.
+
+More: `dft -h`, `dft docs`, `dft skills`. `dft init mcp` installs skills + wires MCP.
+<!-- dft-dataface:end -->

dataface/agent_api/_init_templates/dataface.yml

@@ -0,0 +1,15 @@
+# Dataface project configuration
+#
+# This file anchors your project root. Running `dft serve` from any
+# subdirectory will walk up to find this file and use its directory
+# as the serve root.
+#
+# Credentials and database identity stay in dbt profiles.yml / env vars.
+# Only Dataface runtime and serving preferences belong here.
+#
+# serve:
+#   # Override the SQL dialect (auto-detected from dbt profile when possible)
+#   # dialect: bigquery
+#
+#   # dbt target override (defaults to DBT_TARGET env var, then profile default)
+#   # target: dev

dataface/agent_api/_init_templates/faces-dataface.yml

@@ -0,0 +1,144 @@
+# Dataface Guide — your first dashboard
+#
+# This file is a self-contained tour of Dataface features.
+# Every section works without a database: data lives inline.
+# When you're ready, swap inline data for real SQL queries.
+#
+# Key concepts:
+#   title:      dashboard title shown at the top
+#   text:       markdown prose block — supports **bold**, *italic*, lists, code
+#   queries:    data sources — inline values, CSV files, or SQL against a warehouse
+#   charts:     visualizations wired to a query
+#   rows/cols:  layout — rows stack vertically, cols split horizontally
+#   variables:  interactive dropdowns and filters
+
+title: "Dataface Guide"
+description: "A tour of Dataface: queries, charts, layout, KPIs, and variables."
+
+# ── Text blocks ───────────────────────────────────────────────────────────────
+# Any `text:` field accepts markdown.
+text: |
+  Welcome to **Dataface** — dashboards as YAML files.
+
+  This file is your starter guide. Edit it, add new `.yml` files under
+  `faces/`, and run `dft serve` to preview everything in your browser.
+
+# ── Queries ───────────────────────────────────────────────────────────────────
+# `type: values` embeds data directly — no database needed.
+# Swap for `type: csv` (pointing at a file) or a SQL query once you're ready.
+queries:
+  monthly_revenue:
+    type: values
+    columns: [month, revenue, target]
+    values:
+      - [Jan, 82000, 80000]
+      - [Feb, 91000, 85000]
+      - [Mar, 78000, 90000]
+      - [Apr, 105000, 95000]
+      - [May, 112000, 100000]
+      - [Jun, 99000, 105000]
+
+  category_mix:
+    type: values
+    columns: [category, amount]
+    values:
+      - [Software, 48000]
+      - [Services, 31000]
+      - [Hardware, 20000]
+
+  kpi_summary:
+    type: values
+    columns: [total_revenue, revenue_delta, avg_deal]
+    values:
+      - [567000, 0.14, 18900]
+
+# ── Charts ────────────────────────────────────────────────────────────────────
+# `type:` can be bar, line, area, pie, kpi, table, or scatter.
+# `x:` and `y:` name columns from the query.
+charts:
+  revenue_trend:
+    type: line
+    query: monthly_revenue
+    title: Monthly Revenue vs Target
+    x: month
+    y: revenue
+
+  revenue_bars:
+    type: bar
+    query: monthly_revenue
+    title: Revenue by Month
+    x: month
+    y: revenue
+
+  category_pie:
+    type: pie
+    query: category_mix
+    title: Revenue Mix
+    theta: amount
+    color: category
+
+  kpi_total:
+    type: kpi
+    query: kpi_summary
+    label: Total Revenue (H1)
+    value: total_revenue
+    format: currency_compact
+    support:
+      value: revenue_delta
+      label: vs H1 last year
+      format: percent_delta
+      glyph: "▲"
+      tone: positive
+
+  kpi_avg_deal:
+    type: kpi
+    query: kpi_summary
+    label: Avg Deal Size
+    value: avg_deal
+    format: currency_compact
+
+  data_table:
+    type: table
+    query: monthly_revenue
+    title: Monthly Detail
+
+# ── 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.
+variables:
+  segment:
+    label: Segment
+    input: select
+    default: All
+    options:
+      static: [All, Software, Services, Hardware]
+
+# ── Layout ────────────────────────────────────────────────────────────────────
+# `rows:` stacks content vertically.
+# `cols:` inside a row splits horizontally.
+# Reference a chart by its key, or use a dict for text/title blocks.
+rows:
+  # KPI row — four equal-width columns
+  - cols:
+      - kpi_total
+      - kpi_avg_deal
+
+  # Charts side by side
+  - cols:
+      - revenue_trend
+      - category_pie
+
+  # Full-width bar chart
+  - revenue_bars
+
+  # Annotated table with intro text
+  - cols:
+      - title: "Monthly Detail"
+        text: |
+          Scroll the table to see all rows.
+          Add `style.pagination.enabled: true` to paginate large datasets.
+        style:
+          padding: "16px"
+
+      - data_table

dataface/agent_api/_init_templates/index.md

@@ -0,0 +1,24 @@
+---
+title: Dataface
+---
+
+# Welcome to Dataface
+
+This is your project's landing page. Everything under `faces/` becomes a
+served page — edit the files here to build dashboards, reports, and docs
+for your data project.
+
+## Authoring modes
+
+**YAML (`.yml`)** — structured dashboards with queries, charts, and layout.
+See the [dataface guide](dataface) for a working example covering queries, charts, and variables.
+
+**Markdown (`.md`)** — prose pages like this one. Add YAML frontmatter for
+queries and charts, then embed them inline with `{% raw %}{{ chart my_chart }}{% endraw %}`.
+
+## Next steps
+
+1. Open `faces/dataface.yml` 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.
+4. Run `dft validate` to validate your face YAML for errors.

dataface/agent_api/_paths.py

@@ -0,0 +1,118 @@
+"""Shared path helpers for MCP tools and CLI render setup."""
+
+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.project_roots import (
+    discover_render_context,
+    discovery_boundary_for_face,
+    find_dataface_project,
+)
+from dataface.core.scoped_paths import (
+    _resolve_against_project,
+    project_root_for as project_root_for,
+    resolve_scoped_path as resolve_scoped_path,
+)
+
+
+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:
+        return ""
+    return (
+        f" No Dataface project marker found at or above {check}."
+        f" Run from inside a Dataface project, or set project_dir."
+    )
+
+
+@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.
+    """
+
+    adapter_registry: AdapterRegistry
+    scoped_path: Path | None
+    scoped_base: Path | None
+
+
+def setup_render_for_face(
+    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.
+
+    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.
+    """
+    face_file = face_path
+    if not face_file.is_absolute():
+        face_file = _resolve_against_project(face_file, project_dir)
+    else:
+        face_file = face_file.resolve()
+
+    project_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()
+
+    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,
+        ),
+        face_file,
+    )
+
+
+def setup_render_for_yaml(
+    project_dir: Path | None = None,
+    *,
+    read_only: bool = True,
+) -> RenderSetup:
+    """Build a RenderSetup for a stdin/yaml_content render (no face path).
+
+    Walks upward from `project_dir` (or cwd) to discover the dbt project so
+    yaml fed via stdin still resolves dbt-managed sources correctly.
+    """
+    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,
+    )
+    return RenderSetup(
+        adapter_registry=adapter_registry,
+        scoped_path=None,
+        scoped_base=project_root,
+    )

dataface/agent_api/_project_agents_md.py

@@ -0,0 +1,43 @@
+"""Append or refresh the Dataface blurb in a project's AGENTS.md."""
+
+from __future__ import annotations
+
+import importlib.resources
+from typing import Literal
+
+FileAction = Literal["created", "refreshed", "appended"]
+
+_START = "<!-- dft-dataface:start -->"
+_END = "<!-- dft-dataface:end -->"
+
+_TEMPLATES = importlib.resources.files("dataface.agent_api._init_templates")
+
+
+def load_agents_snippet() -> str:
+    """Return the packaged markdown blurb (includes marker comments)."""
+    return _TEMPLATES.joinpath("agents_dft_snippet.md").read_text()
+
+
+def has_dataface_markers(text: str) -> bool:
+    if _START not in text or _END not in text:
+        return False
+    return text.index(_START) < text.index(_END)
+
+
+def merge_agents_snippet(
+    existing_text: str | None,
+    snippet: str,
+) -> tuple[str, FileAction]:
+    """Create, append, or refresh only the marked Dataface section."""
+    body = snippet if snippet.endswith("\n") else f"{snippet}\n"
+
+    if existing_text is None:
+        return body.lstrip("\n"), "created"
+
+    if has_dataface_markers(existing_text):
+        before = existing_text[: existing_text.index(_START)].rstrip()
+        after = existing_text[existing_text.index(_END) + len(_END) :].lstrip()
+        parts = [p for p in (before, body.strip(), after) if p]
+        return "\n\n".join(parts) + "\n", "refreshed"
+
+    return f"{existing_text.rstrip()}\n\n{body.lstrip()}", "appended"