Metadata-Version: 2.4
Name: dataface
Version: 0.1.5.dev278
Summary: Dataface - dbt-native dashboard and visualization layer
Author: Fivetran, Inc.
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.10
Requires-Dist: dbt-adapters>=1.20
Requires-Dist: dbt-common>=1.0
Requires-Dist: dbt-duckdb>=1.10
Requires-Dist: duckdb>=0.9.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: fonttools>=4.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: plotext>=5.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pygments>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlglot>=28.0.0
Requires-Dist: titlecase>=2.4
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Requires-Dist: typing-extensions>=4.5.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: vl-convert-python>=1.0.0
Provides-Extra: bigquery
Requires-Dist: dbt-bigquery<2.0,>=1.10; extra == 'bigquery'
Requires-Dist: google-cloud-bigquery>=3.33.0; extra == 'bigquery'
Provides-Extra: chat
Requires-Dist: anthropic>=0.39.0; extra == 'chat'
Requires-Dist: mcp>=1.0.0; extra == 'chat'
Requires-Dist: openai>=2.7.2; extra == 'chat'
Requires-Dist: prompt-toolkit>=3.0.43; extra == 'chat'
Provides-Extra: databricks
Requires-Dist: dbt-databricks<2.0,>=1.10; extra == 'databricks'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: mkdocs-plugin
Requires-Dist: mkdocs>=1.4.0; extra == 'mkdocs-plugin'
Provides-Extra: playground
Requires-Dist: dataface-playground; extra == 'playground'
Provides-Extra: postgresql
Requires-Dist: dbt-postgres<2.0,>=1.10; extra == 'postgresql'
Provides-Extra: redshift
Requires-Dist: dbt-redshift<2.0,>=1.10; extra == 'redshift'
Provides-Extra: server
Requires-Dist: fastapi>=0.100.0; extra == 'server'
Requires-Dist: uvicorn>=0.23.0; extra == 'server'
Provides-Extra: snowflake
Requires-Dist: dbt-snowflake<2.0,>=1.10; extra == 'snowflake'
Provides-Extra: spark
Requires-Dist: dbt-spark<2.0,>=1.10; extra == 'spark'
Description-Content-Type: text/markdown

# Dataface

**Declarative, dbt-native dashboards in YAML**

Dataface is a Python-based dashboard framework that compiles YAML dashboard definitions into interactive visualizations. It integrates seamlessly with dbt's Semantic Layer (MetricFlow) to provide a simple, declarative way to create dashboards.

---

## Why Dataface?

**Database + Interface = Dataface.** Dataface is designed to be the universal language of data visualization—perfect for humans and AI alike.

### The Problem

If you're a data analyst working with dbt, you've probably experienced this:
- You have great metrics and dimensions defined in dbt's Semantic Layer
- You want to create dashboards to share insights with your team
- But building dashboards requires learning complex BI tools, writing SQL queries, or coding

### The Solution

Dataface lets you:
- **Write dashboards in YAML** — simple, human-readable format
- **Reference your existing dbt metrics** — no need to redefine them
- **Create interactive visualizations** — filters, drill-downs, and click actions
- **Share and collaborate** — dashboards are version-controlled YAML files
- **Stay in sync with dbt** — dashboards and models deploy together through Git branches, eliminating broken dashboards after data migrations

### How It Works

1. **You write a YAML file** describing what data to show and how to visualize it
2. **Dataface compiles it** into an interactive dashboard
3. **The dashboard queries your dbt Semantic Layer** (MetricFlow) to fetch data
4. **Users interact** with filters, click charts, and explore the data

---

## Getting Started

### Prerequisites

- **Python 3.10-3.13**
- **dbt** project (optional but highly recommended)

### Install

```bash
pip install "dataface"
```

Verify:

```bash
dft --version
```

### Without dbt (optional)

If you don't already have a dbt project, install Dataface with the warehouse adapter you need:

```bash
pip install "dataface[bigquery]"
pip install "dataface[databricks]"
pip install "dataface[postgresql]"
pip install "dataface[redshift]"
pip install "dataface[snowflake]"
pip install "dataface[spark]"
```

### AI chat (optional)

For the AI agent (`dft chat`), add the `[chat]` extras and set `OPENAI_API_KEY` in your environment:

```bash
pip install "dataface[chat]"
dft chat
```

### MCP (optional)

Dataface ships an MCP server for use with any compatible AI agent:

```bash
pip install "dataface[mcp]"
dft init mcp
```

### Quick Start

```bash
# Bootstrap a new project
dft init

# Validate a face for errors
dft validate faces/hello.yml

# Start a live preview server
dft serve
```

### Environment variables

`dft` reads `DFT_PROJECT_DIR` when no `--project-dir` is passed — handy in CI or when working in multiple project trees from one shell. The flag wins if both are set. See the [CLI environment variables reference](https://docs.it-dataface.com/cli/#environment-variables) for the full list (themes, ports, dbt overrides, etc.).

### Place faces in your dbt project

```
my-dbt-project/
├── dbt_project.yml
├── models/
├── faces/                   # Your faces here
│   ├── sales_overview.yml
│   ├── marketing.yml
│   └── finance.yml
└── assets/                  # Assets directory (optional)
    ├── images/             # Logos, icons, images
    └── data/               # CSV files and other data
```

---

## Key Features

### dbt-Native
- Uses dbt Semantic Layer (MetricFlow) directly
- Reads your `profiles.yml` automatically
- Works with all dbt adapters (Snowflake, BigQuery, Postgres, etc.)
- No need to redefine metrics
- Dashboards sync with dbt models through Git branches — no broken dashboards after data migrations

### Declarative YAML
- Human-readable, version-control friendly
- No code required
- AI-friendly format (perfect for LLMs to generate)

### Interactive Visualizations
- Variables/filters that update in real-time
- Click interactions (drill-down, set variables, filter)
- Built on Vega-Lite (declarative charting)

### Multiple Output Modes
- **Live mode:** Interactive web dashboard (FastAPI server)
- **Static mode:** Shareable HTML snapshot (data baked in)
- **PDF mode:** Printable/shareable PDF reports

### AI-First
- YAML is perfect for AI generation
- MCP server for any compatible AI agent (Cursor, VS Code, Claude Desktop, Codex)
- AI can create, modify, and iterate on dashboards

---

## Interactive Playground

Try Dataface online without installing anything:

**[play.it-dataface.com](https://play.it-dataface.com)**

A split-pane YAML editor with live preview. No dbt project needed (uses sample data).

---

## CLI Commands

The Dataface CLI is called `dft` (short for **D**ata**F**ace **T**ool), intentionally mirroring `dbt` (Data Build Tool). Just as dbt transforms your data, dft transforms your dashboards.

### Validate

Validate dashboards for errors:

```bash
dft validate [PATH]

# Examples:
dft validate                        # Validate all in faces/
dft validate faces/                 # Validate all in a directory
dft validate faces/hello.yml        # Validate one file
dft validate --strict               # Fail on warnings
```

### Serve

Start interactive preview server:

```bash
dft serve [OPTIONS]

# Examples:
dft serve
dft serve --port 3000
dft serve --host 0.0.0.0  # bind on the LAN, not just localhost
```

### Render

Render a dashboard to a self-contained file:

```bash
dft render FACE [OPTIONS]

# Examples:
dft render faces/hello.yml --format html
dft render faces/hello.yml --format pdf
dft render faces/hello.yml --format png --output hello.png
dft render faces/hello.yml --format json   # resolved layout + executed data
```

---

## Example Dashboards

### Simple KPI Dashboard

```yaml
title: "Executive KPIs"

queries:
  q_totals:
    metrics: [total_revenue, order_count, customer_count]

charts:
  revenue:
    label: "Total Revenue"
    query: q_totals
    type: kpi
    value: total_revenue
  orders:
    label: "Total Orders"
    query: q_totals
    type: kpi
    value: order_count
  customers:
    label: "Total Customers"
    query: q_totals
    type: kpi
    value: customer_count

rows:
  - title: "Key Metrics"
    cols:
      - revenue
      - orders
      - customers
```

### Interactive Dashboard with Filters

```yaml
title: "Sales Dashboard"

variables:
  date_range:
    input: daterange
    default: "2024-01-01"

  region:
    input: multiselect
    options:
      static: ["North", "South", "East", "West"]
    default: ["North", "South"]

queries:
  q_sales:
    metrics: [total_revenue, order_count]
    dimensions: [month, region]
    filters:
      order_date: "{{ date_range }}"
      region: "{{ region }}"

charts:
  revenue_trend:
    title: "Revenue Over Time"
    query: q_sales
    type: line
    x: month
    y: total_revenue
    color: region

rows:
  - title: "Revenue Trends"
    cols:
      - revenue_trend
```

---

## Architecture

Dataface is built on:

- **Python 3.10+** - Core language
- **Pydantic** - Schema validation and data models
- **Jinja2** - Template engine (same as dbt!)
- **Vega-Lite** - Declarative charting via `vl-convert`
- **FastAPI** - Web server for live mode
- **dbt adapters** - Direct database access

### How It Works

```
YAML Dashboard → Python Compiler → Vega-Lite Specs → Renderer
                     ↓
                 (Validation)
                     ↓
              dbt MetricFlow → Query Data → Charts
                     ↓
              Live HTML or Static PDF
```

---

## Comparison to Other Tools

| Feature | Dataface | Lightdash | Looker | Superset |
|---------|----------|-----------|--------|----------|
| **Format** | YAML | UI + YAML | LookML | UI |
| **dbt Integration** | Native (MetricFlow) | dbt metrics | Separate | Limited |
| **Installation** | `pip install dataface` | Self-host + PostgreSQL | Enterprise license | Self-host + database |
| **Version Control** | Native (Git) | Export/Import | Native (Git) | Limited |
| **AI-Friendly** | YAML | UI-first | LookML | No |
| **Static Export** | PDF, HTML | No | Enterprise only | No |

---

## Documentation

- [Getting Started Guide](https://docs.it-dataface.com/guides/getting-started) — Step-by-step onboarding
- [YAML Style Guide](https://docs.it-dataface.com/guides/yaml-style-guide) — Dashboard YAML conventions
- [CLI Reference](https://docs.it-dataface.com/cli/) — All `dft` commands
- [Chart Types](https://docs.it-dataface.com/charts/types) — Available chart types and configuration
- [Variables & Filters](https://docs.it-dataface.com/variables/) — Interactive variables and UI elements

---

## Contributing

Contributions welcome! See the [GitHub repository](https://github.com/Fivetran/dataface) for contributor setup, architecture docs, and development workflows.
