Skip to main content

Visivo

BI as code, built for people and agents

Define sources, a semantic layer and dashboards in YAML. Develop locally with instant reload, review changes in pull requests, and let an AI agent draft the next chart against the same definitions.

Docs · Quick start · Build with AI · Website · Visivo Cloud · Discussions

PyPI version Python versions License GitHub stars

A Visivo dashboard of NYC taxi trips: a borough filter, KPI cards, a weekly revenue line, a payment-method donut, trips by hour, top pickup zones, and average fare and tip rate by borough

This dashboard is one YAML file: a DuckDB source, three models with metrics and dimensions, a relation, one input, ten insights, ten charts, one dashboard. The borough dropdown re-filters the charts in the browser.

A dashboard in 60 seconds

pip install visivo                 # Python 3.12+
visivo init --example ev-sales     # copies a sample project, starts the dev server, opens the browser

init --example writes a project.visivo.yml, a small DuckDB file and the CSV it came from, then runs visivo serve on http://localhost:8000. The other bundled examples are github-releases and college-football.

Prefer a single binary with no Python? curl -fsSL https://visivo.sh | bash installs one to ~/.visivo/bin (macOS 15+, Linux x86_64, Windows through WSL). To start from your own data, run visivo init and the in-browser wizard walks you through adding a source.

The bundled EV Sales example dashboard

Edit the YAML and save. The dev server recompiles and re-runs what changed, and layout and style edits redraw in the open tab without a reload. No build step.

Saving three YAML edits in a row: the chart title changes, the bar chart becomes a line, then the line turns orange, each without a page reload

What a project looks like

Every Visivo project is the same chain of objects: a source you query, models that name a SQL query, a semantic layer of metrics, dimensions and relations on top of those models, insights that pick fields and aggregates to plot, charts that give insights a Plotly layout, and dashboards that lay charts, tables, markdown and inputs out in rows.

sources:
  - name: taxi
    type: duckdb
    database: taxi.duckdb

models:
  - name: trips
    source: ${ref(taxi)}
    sql: SELECT * FROM yellow_trips
    metrics:
      - name: revenue
        expression: SUM(total_amount)
      - name: tip_rate
        expression: SUM(tip_amount) / SUM(fare_amount)
    dimensions:
      - name: pickup_week
        expression: date_trunc('week', tpep_pickup_datetime)
      - name: payment_method
        expression: CASE payment_type WHEN 1 THEN 'Credit card' WHEN 2 THEN 'Cash' ELSE 'Other' END

inputs:
  - name: payment
    type: single-select
    options: ["Credit card", "Cash"]

insights:
  - name: revenue_by_week
    props:
      type: scatter
      mode: lines
      x: ?{ ${ref(trips).pickup_week} }
      y: ?{ ${ref(trips).revenue} }
    interactions:
      - filter: ?{ ${ref(trips).payment_method} = '${ref(payment).value}' }

charts:
  - name: revenue_by_week_chart
    insights:
      - ${ref(revenue_by_week)}
    layout:
      title:
        text: Weekly revenue

dashboards:
  - name: Revenue
    rows:
      - height: compact
        items:
          - input: ${ref(payment)}
      - height: medium
        items:
          - chart: ${ref(revenue_by_week_chart)}

?{ } wraps a SQL expression. ${ref(object).field} points at a model column, a metric, a dimension or an input value, and Visivo resolves the joins and the GROUP BY for you. Define revenue once and every insight that references it computes it the same way.

Why Visivo

It is code, so it gets the software workflow. Projects are YAML in git. A dashboard change is a branch, a diff and a pull request. In CI, visivo run executes the queries and visivo deploy -s <stage> publishes a preview stage named after the branch to Visivo Cloud, so a reviewer opens the rendered dashboard next to the diff. visivo archive -s <stage> cleans it up when the PR closes. The CI/CD guide has a complete GitHub Actions workflow.

A semantic layer that people and agents share. Metrics, dimensions and relations live in the project, not in each chart. Model columns are dimensions by default; relations declare how models join so an insight can pull fields from two models and get the right SQL. The same definitions are what the built-in agent and external MCP clients read before they write anything.

The semantic layer view: the trips model with its columns, metric chips and a dimension, joined to the zones model through the trips_to_zones relation

Interactive without round trips. Inputs (dropdowns, radios, tabs, sliders, range sliders, date ranges, chips, checkboxes) feed filter, split and sort interactions. Those run in the browser on the insight's pre-computed data through DuckDB-WASM, so switching a filter re-aggregates instantly and never touches your warehouse.

Switching the pickup borough dropdown from Manhattan to Queens to Bronx; the KPI cards and the charts update in place

Local first. visivo serve runs the project, watches your files and rebuilds on every save. The same server hosts a workspace where you can explore a source, draft insights against live data, lay out a dashboard on a canvas, edit the theme, and commit the result back to your YAML.

The Visivo workspace: object sidebar on the left, the dashboard canvas in the middle, an edit panel on the right

Layout is drag and drop: pull a chart from the Library onto a row, grab a selected card by its frame to reorder it, then save the result to the YAML.

On the workspace canvas, the tip_rate_by_borough_chart row is dragged from the Library and dropped at the end of the last dashboard row, where it renders; then the Payment method donut is selected and dragged in front of the Weekly revenue chart in its row

Push, not pull. visivo run executes the queries wherever you run it, on your laptop or in CI, and writes the results next to the project. visivo deploy ships those results, so the hosted viewer never needs a connection to your warehouse.

Build with an agent

Visivo ships an agent and an MCP server. Both use the same tools and the same packaged skills, and neither can write your YAML files or commit: every write lands as a draft that you review in the workspace, then commit or discard.

Your agent, over MCP. visivo serve exposes http://localhost:8000/api/mcp/ (Streamable HTTP, no auth on localhost). Point Claude Code, Cursor, Gemini CLI or any MCP client at it:

claude mcp add --transport http visivo http://localhost:8000/api/mcp/

The server offers list_*, get_*, validate_* and write_* for every project object type (sources, models, metrics, dimensions, relations, insights, charts, tables, markdown, inputs, dashboards), read-only data tools (describe_source, query_source, profile_model, profile_columns, preview_insight), charting advisors (recommend_charts, recommend_inputs, check_input_wiring, recommend_layout, score_candidates) and read_skill for the packaged skills such as choose-a-chart, design-a-dashboard and make-it-interactive. The skills encode measured chart rules for every Plotly trace type, so an agent gets the chart family, the input wiring and the layout right instead of guessing.

An MCP client writes a model, an input, insights, charts and a dashboard against an empty project; the dashboard builds and renders in the viewer as the calls arrive

The built-in agent. The Agent tab in visivo serve runs the same loop with your own Anthropic, OpenAI or Google key, or with inference from your Visivo Cloud account. visivo init also writes an AGENTS.md where you keep naming rules and business definitions for either path. Read Build with AI for the four ways to run it and the draft boundary.

Everything else in the box

  • Sources: PostgreSQL, MySQL, SQLite, Snowflake, BigQuery, Redshift, ClickHouse, DuckDB, CSV and Excel files. One dashboard can read from several.
  • 48 chart types, every Plotly trace: bar, line, scatter, pie, indicator (KPI), heatmap, histogram, box, candlestick, sankey, funnel, treemap, choropleth and mapbox maps, 3D, and more. Plus tables with pivots, cell formatting and paging, and markdown.
  • dbt™ integration: a dbt: block turns your dbt models and targets into Visivo models and sources (visivo dbt refreshes them).
  • Themes: built-in light and dark modes with a viewer toggle, a theme: block for colorway, fonts and surfaces, and a plotly_layout escape hatch.
  • Query-backed inputs: options: ?{ SELECT DISTINCT region FROM ${ref(sales)} } fills a dropdown from your data at build time.
  • Static distribution: visivo dist packages the viewer and the last run's data into a folder you can host on S3, GitHub Pages or any static host.
  • Visivo Cloud: visivo deploy pushes the project and its data to app.visivo.io under a named stage, with sharing, teams and roles.
  • Lineage: every dashboard has a Lineage view that draws its DAG from sources to the dashboard, so you can see what a change touches.

The Lineage view of the NYC Taxi dashboard: the taxi DuckDB source on the left feeding the trips, zone_ranks and zones models and the borough input, then ten insights, then their ten charts, then the dashboard node on the right

Rows stack on phones, so the same dashboard reads on a 390 px screen.

The same taxi dashboard on a 390 px wide phone viewport, with the input, KPI cards and charts stacked

How it compares

GUI BI tools (Tableau, Looker, Power BI, Metabase, ...) Visivo
Definition Click-built in a GUI; hard or impossible to version YAML in git
Review No diff, no pull request Branch, diff, PR, preview stage
Environments Usually one shared instance Named stages for dev, CI and production
Data access You hand the vendor credentials to pull your data You run the queries and push the results
Agents Vendor chat features over vendor-held metadata A local MCP server and a built-in agent over the same project files, drafts you review
Where it lives Outside your transformation stack Next to your dbt, Django or Rails project

Visivo is not a warehouse, a transformation tool or a notebook. It reads the tables you already have and turns them into reviewable dashboards.

Learn more

Community and contributing

  • GitHub Discussions for questions and show-and-tell
  • Issues for bugs and feature requests
  • CONTRIBUTING.md for the development setup: Python CLI in visivo/, React viewer in viewer/, tests in tests/

Visivo collects anonymous usage telemetry (command names, no queries, no file contents, no personal data). Run visivo telemetry off to opt out on a machine, or set VISIVO_TELEMETRY_DISABLED=true. Details are in the telemetry docs.

License

Visivo is released under the GNU General Public License v3.0.

Metadata

Release files for visivo 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for visivo 2.3.0
File Interpreter ABI Platform Actions
visivo-2.3.0-py3-none-any.whl Python 3 none any Details for visivo-2.3.0-py3-none-any.whl

Release files / visivo-2.3.0-py3-none-any.whl

Download URL visivo-2.3.0-py3-none-any.whl
Size 46.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
7305b37359831721a28dc12d0aea4386300510cb9e512ad872b02aefea448066
BLAKE2b-256 checksum
How to use checksums
944b2a76528cbace36517e2e24f03b9b6eba36c86b8dba596c9673e3d6ee79c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for visivo 2.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.3.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page