dataface 0.1.2__py3-none-any.whl

dataface-0.1.2.dist-info/METADATA

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: dataface
+Version: 0.1.2
+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: pyarrow>=14.0.1
+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
+
+### Install
+
+Install from PyPI:
+
+```bash
+pip install "dataface"
+```
+
+For the AI agent (`dft chat`), use the `[chat]` extras bracket:
+
+```bash
+pip install "dataface[chat]"
+```
+
+### 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.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 (Model Context Protocol) integration
+- AI can create, modify, and iterate on dashboards
+- Configure your IDE: `dft init mcp` (auto-detects Cursor, VS Code, Claude Desktop, Codex)
+
+---
+
+## Interactive Playground
+
+Try Dataface online without installing anything:
+
+**[play.dataface.com](https://play.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 | ❌ |
+| **Static Export** | ✅ PDF, HTML | ❌ | ⚠️ Enterprise | ❌ |
+
+---
+
+## Documentation
+
+- [Getting Started Guide](https://docs.dataface.com/guides/getting-started) — Step-by-step onboarding
+- [YAML Style Guide](https://docs.dataface.com/guides/yaml-style-guide) — Dashboard YAML conventions
+- [CLI Reference](https://docs.dataface.com/cli/) — All `dft` commands
+- [Chart Types](https://docs.dataface.com/charts/types) — Available chart types and configuration
+- [Variables & Filters](https://docs.dataface.com/variables/) — Interactive variables and UI elements
+- [Architecture](https://docs.dataface.com/contributing/architecture) — How Dataface works (compile → execute → render)
+
+---
+
+## Contributing
+
+Contributions welcome! See the [GitHub repository](https://github.com/Fivetran/dataface) for contributor setup, architecture docs, and development workflows.