Skip to content

Add Mosaic visualization support - #2090

Draft
SuMayaBee wants to merge 15 commits into
holoviz:mainfrom
SuMayaBee:mosaic-agent
Draft

SuMayaBee wants to merge 15 commits into
holoviz:mainfrom
SuMayaBee:mosaic-agent

Conversation

@SuMayaBee

@SuMayaBee SuMayaBee commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adds Mosaic visualization support to Lumen through the published panel-mosaic-viz Panel extension.

@philippjfr suggested creating the Panel extension first, so this PR integrates that extension into Lumen and lets Lumen render Mosaic charts.

Fixes #1985

AI Disclosure

Tool & Model: OpenAI Codex (GPT-5)
Usage: Used to help implement, test, and document the integration. I reviewed and tested all changes.

  • I have tested all AI-generated content in my PR.
  • I take responsibility for all AI-generated content in my PR.

Checklist

  • Tests added and are passing
  • Added documentation

Addresses the review on holoviz#1985 ("best to have a Mosaic pane in
Panel first"). MosaicView previously rendered Mosaic's own anywidget through
pn.pane.IPyWidget + ipywidgets_bokeh; it now renders through `Mosaic`, a
Panel component written with no Lumen imports so it can be contributed
upstream to close holoviz/panel#7358.

Panel's `AnyWidgetComponent` cannot run Mosaic's anywidget as-is, which is why
that issue has stalled: `AnyWidgetModelAdapter` exposes no `send`, so the
browser cannot request data, and its `msg:custom` callback receives the
message without the Arrow buffers Mosaic replies with. `JSComponent` supports
both directions, so the ESM module here is a Panel-native reimplementation of
Mosaic's render loop. It imports only `@uwdata/mosaic-spec`, keeping vgplot and
mosaic-core in one module graph, and gives each pane its own coordinator rather
than the module-wide singleton, so several panes can share a page. Arrow IPC
results are base64-encoded into the JSON message since `JSComponent` has no
binary channel; Mosaic only ships query results, so payloads stay small.

Verified in a headless browser: a scatter and a linked bar chart render, and
brushing the scatter re-queries DuckDB and refilters the bars, with the
selection's SQL predicate syncing back to Python via `params`.

This drops the `ai-mosaic` extra entirely -- duckdb and pyarrow are already
core dependencies, so the pane needs no new ones, and mosaic-widget and
ipywidgets_bokeh are no longer required.

MosaicAgent is now registered alongside VegaLiteAgent rather than replacing it,
with conditions scoped to cross-filtered and linked views, and its prompt
updated to main's template style rules.
Follow-up from holoviz#1985: MosaicView handed the pane a materialized
DataFrame, which defeats the reason to use Mosaic at all -- it pushes its SQL
down to DuckDB so only aggregates reach the browser, no matter how large the
table is.

When the pipeline is DuckDB-backed and its result is expressible entirely in
SQL, the pane is now given a cursor on that connection plus a temp view over
the pipeline's own query, rebuilt the way DuckDBSource.get does: the filter
conditions followed by the declared SQL transforms.

The guard matters more than the optimization. Anything Lumen computes in
pandas *after* the query -- Python transforms, a ParamFilter, a chained
pipeline, or a source that filters outside SQL -- is absent from that SQL, so
pushing down would silently chart unfiltered data. Those cases fall back to
sending the computed frame, which also keeps every non-DuckDB Source working.

Two details worth keeping: the view is created on a cursor, a separate session
on the same database, so it cannot collide with another chart's view or mutate
the schema the rest of Lumen sees; and it is deliberately not named after the
table, because a temp view shadows the base table of the same name and DuckDB
rejects `VIEW "t" AS SELECT * FROM "t"` as infinite recursion.

Tests assert the pushdown charts the same rows as the pandas path for plain,
filtered and SQL-transformed pipelines, that each fallback case is taken, and
that the empty-result error fires on both paths so the agent's retry loop
behaves the same either way. Verified in a browser: the pushdown path renders
and cross-filters through the temp view.
@codecov

codecov Bot commented Sep 12, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.48669% with 29 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.19%. Comparing base (925e4c8) to head (e2fb755).
⚠️ Report is 2 commits behind head on main.

Files with missing lines Patch % Lines
lumen/ai/agents/mosaic.py 84.09% 14 Missing ⚠️
lumen/ai/editors.py 90.38% 10 Missing ⚠️
lumen/views/base.py 95.89% 3 Missing ⚠️
lumen/tests/ai/test_mosaic.py 98.80% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2090      +/-   ##
==========================================
+ Coverage   76.96%   77.19%   +0.23%     
==========================================
  Files         216      218       +2     
  Lines       40674    41201     +527     
==========================================
+ Hits        31303    31805     +502     
- Misses       9371     9396      +25     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@ghostiee-11 ghostiee-11 added the wip Work in progress; not yet ready to merge label Sep 14, 2026
@SuMayaBee

Copy link
Copy Markdown
Contributor Author

@ahuang11 I have run the lumen with mosaic with the classic iris dataset, with those qns:

1. Create a scatter plot of sepal length versus sepal width, colored by species.

Screenshot_2026-09-16_21-55-21

2. Make a box plot of petal length for each species.

Screenshot_2026-09-16_21-57-34

3. Show a histogram of petal width, split by species.

Screenshot_2026-09-16_22-00-18

4. Create a correlation heatmap for all numeric columns.

Screenshot_2026-09-16_22-02-31

5. Make a pair plot of sepal and petal measurements, colored by species.

Screenshot_2026-09-16_22-05-01

6. Show the average sepal length and petal length for each species as a grouped bar chart.

Screenshot_2026-09-16_22-06-59

@SuMayaBee
SuMayaBee marked this pull request as ready for review September 16, 2026 16:24
@ahuang11

Copy link
Copy Markdown
Contributor

Can you show usage with mosaic's interactivity e.g.

image image

@SuMayaBee
SuMayaBee marked this pull request as draft September 16, 2026 17:09
@SuMayaBee

Copy link
Copy Markdown
Contributor Author

@ahuang11 There is some usage with mosaic's interactivity on iris dataset.

  1. Make the scatter plot interactive. Add a brush selection, a PetalWidthCm histogram, and a data table. Update the histogram and table when I select points in the scatter plot.
2026-09-17.17-49-10.mp4
  1. Add a slider called “Maximum petal length”. Filter the scatter plot, histogram, and table so they show only rows whose PetalLengthCm is at or below the selected value.
2026-09-17.17-52-01.mp4
  1. Add a Species dropdown filter. When I choose a species, update the scatter plot, histogram, and table to show only that species.
2026-09-17.17-45-37.mp4

@SuMayaBee
SuMayaBee marked this pull request as ready for review September 17, 2026 12:21
@ahuang11

Copy link
Copy Markdown
Contributor

Nice! Any way to stretch the container so it takes up the whole space?

@SuMayaBee

Copy link
Copy Markdown
Contributor Author

Nice! Any way to stretch the container so it takes up the whole space?

Let me see, what can be done to achieve that.

@ghostiee-11

Copy link
Copy Markdown
Collaborator

Damn!! This is cool..

@SuMayaBee
SuMayaBee marked this pull request as draft September 18, 2026 11:57
@ahuang11

Copy link
Copy Markdown
Contributor

Is this ready now?

@SuMayaBee

Copy link
Copy Markdown
Contributor Author

Is this ready now?

It's not ready yet, I am working on it

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

wip Work in progress; not yet ready to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Propose MosaicAgent as the chart-generating agent

3 participants