# holoviz/lumen: an agent framework that turns natural language into SQL, charts and dashboards

> Lumen is a Python agent framework from the HoloViz project that generates declarative data pipelines, SQL and visual output from prompts. It installs from conda or PyPI and serves a chat interface over your own files and databases.

**holoviz/lumen** — Illuminate your data. Agent framework turning natural language into SQL, charts, dashboards and reports.

- Repository: https://github.com/holoviz/lumen
- Website: https://lumen.holoviz.org
- Stars: 312 · Forks: 44
- Language: Python
- License: BSD-3-Clause
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/holoviz-lumen

## What holoviz/lumen actually solves, and for whom

Most text-to-SQL tools stop at a query string. You get a SELECT statement back, you paste it somewhere, and the rest of the work (cleaning, joining, plotting, sharing) is yours again. Lumen aims at the whole chain. The README describes it as "a fully open-source and extensible agent based framework for chatting with data and for retrieval augmented generation (RAG)", and the mechanism it uses to get there is the part that matters: output is not free text, it is a declarative Lumen specification that can be serialized.

The audience is narrower than the tagline suggests. Lumen is built on Panel, and its data model is the HoloViz data model. If you already work with Panel, HoloViews or hvPlot, the generated artifacts land in familiar territory. If you have never seen a HoloViz pipeline, the payoff is real but the learning surface is larger, because you will be reading and editing generated specifications rather than just accepting or rejecting a query. The repository lists ai-agents, text-to-sql, duckdb, panel and rag among its topics, which is an accurate summary of the dependency footprint as well as the intent.

The project is not archived and the last push was on 2026-09-09, with v1.3.0 released on 2026-07-29. That is a recent release cadence, but cadence is not the same as stability for your use case, and the README does not publish accuracy numbers for generated SQL.

## How the agent pipeline turns a prompt into a shareable specification

The architecture visible in the README has three layers. At the bottom is a declarative data model: sources, transformations and output components described as data rather than as imperative code. In the middle sit agents and tools that an LLM drives. On top is Panel, which renders whatever the specification describes.

The design choice that follows from this is that the LLM does not write Python that runs directly. It populates a specification. The README states that "the declarative nature of Lumen's data model make it possible for LLMs to easily generate entire data transformation pipelines, visualizations and other many other types of output", and that once generated, "the data pipelines and visual output can be easily serialized". That serialization is the interesting property: a generated pipeline can be shared, reopened in a notebook, or composed into a dashboard. It is also the property that makes review possible, because you are inspecting structured output instead of trusting a code string.

DuckDB is a core dependency and appears in the project topics, so local files and SQL sources are queried through it. Documents for RAG are handled separately: markitdown, semchunk and tiktoken are in the dependency list, which points at converting documents to text, splitting them into chunks and counting tokens. The README does not document which vector store backs the embeddings, so treat retrieval configuration as something to confirm against the docs before you design around it.

## Installing Lumen and running a first chat over a CSV

Lumen requires Python 3.11 or newer according to pyproject.toml, and the README says it works on Linux, Windows or Mac. The recommended install path is conda:

```bash
conda install -c pyviz lumen
```

The PyPI path installs the AI extras, which is what you want if you intend to chat with data rather than only use the declarative API:

```bash
pip install 'lumen[ai]'
```

After installing, the README gives a single command to start the explorer server. Replace the argument with the path to your own data:

```bash
lumen-ai serve data.csv
```

What you should see is a Lumen Explorer server serving a chat interface. The README points to the getting started page at lumen.holoviz.org for the details of that flow. Note that the command is lumen-ai, not lumen; the README does not describe a separate CLI entry point for the non-AI declarative workflow, so check the docs if you only want to build specifications by hand.

The README does not state which LLM provider is configured by default, nor which environment variables or config keys select a model. That is the first thing to resolve after install, because the serve command will need an LLM endpoint to do anything useful. The docs at lumen.holoviz.org are the place to look for that configuration.

## Where Lumen is the wrong tool

The dependency list is the clearest limitation. Lumen pulls in bokeh, panel, holoviews, hvplot, panel-material-ui, panel-graphic-walker, panel-splitjs, pyarrow, duckdb, intake, narwhals, sqlglot, pydantic, instructor and more. That is a large install for what may be a single question about a table. If your actual need is "turn this English sentence into a SELECT statement and return the string", Lumen is carrying a visualization and dashboard stack you will never touch.

Second, Lumen is interactive-first. The README frames it around chatting, inspecting, refining and manually editing results, and around dashboards. There is no described headless batch mode for generating a thousand SQL queries and writing them to disk. If your pipeline is automated and unattended, the human-in-the-loop framing of the README is a mismatch.

Third, the README does not report accuracy on any text-to-SQL benchmark, and it does not describe a validation step that proves a generated query is correct before it runs. The README does say that "all LLM outputs can easily be inspected for mistakes, refined, and manually edited if needed", which is an admission that inspection is part of the workflow rather than an optional extra. Treat generated SQL against a production database as untrusted input until you have read it.

Finally, the project is Python-only. There is no documented JavaScript or Go client for the agent layer.

## Compared with Streamlit and with a plain text-to-SQL library

The closest comparison in spirit is Streamlit plus an LLM library. Streamlit gives you a Python script that reruns top to bottom and renders widgets; the output is a running app, and the app is the artifact. Lumen inverts that. The artifact is a declarative specification, and the app is one rendering of it. That difference shows up when you want to hand the result to someone else: with Lumen you can serialize the pipeline and reopen it in a notebook, which the README explicitly calls out as a goal. With a script-based tool you hand over code.

The other comparison is a dedicated text-to-SQL library. Those tend to do one thing: schema in, query out, with evaluation harnesses around it. Lumen does less benchmarking and more composition. If your success criterion is a measured execution-accuracy number on a public benchmark, a focused text-to-SQL library is the better fit, because Lumen's README makes no such claim. If your success criterion is a colleague opening a browser, asking a question about a Parquet file, and getting a chart they can then adjust by hand, Lumen is aimed squarely at that.

A third option worth naming is writing the Panel app yourself. That is what Lumen generates, minus the LLM. It is more work, but it removes the model from the critical path entirely, which matters if you cannot send your data to a hosted model.

## Licence, upgrade cost and release history

Lumen is BSD-3-Clause, and pyproject.toml declares the license as BSD with the classifier "License :: OSI Approved :: BSD License". That is a permissive licence, which means you can generally use it in commercial and closed products, but the usual caveats apply: the BSD-3-Clause text includes a clause about not using contributor names for endorsement, and it comes with no warranty. This is a description of the licence file, not legal advice; read LICENSE in the repository if the terms matter to your organisation.

The dependency constraints are where upgrade cost lives. pyproject.toml pins param to >=2.2.1,<2.5.0 and requires panel >=1.9.0, holoviews >=1.17.0, bokeh >=3.9.0, duckdb >=1.2.0 and griffe <2. Those upper bounds are few, but the lower bounds are high, so Lumen will force relatively new versions of the HoloViz stack into your environment. If you have another HoloViz-based application pinned to older Panel or Bokeh, expect to resolve a conflict.

The release history shows v1.1.0 on 2026-03-24, v1.2.0 on 2026-06-10 and v1.3.0 on 2026-07-29, roughly quarterly. The CHANGELOG.md at the repository root is the place to read before upgrading, since the README does not document a deprecation policy or a rollback procedure.

## Conclusion

Adopt holoviz/lumen when you want generated SQL, charts or dashboards that stay as editable declarative specifications, and when you are already comfortable in the HoloViz stack. Do not adopt it if you need a headless text-to-SQL service with a documented benchmark, or if you cannot run an LLM endpoint. Before committing, verify that your Python is 3.11 or newer, that the extras you need actually pull in your LLM provider, and that the generated pipeline specification round-trips into a notebook the way you expect.

## FAQ

### How do I install holoviz/lumen?

The README recommends conda with conda install -c pyviz lumen, or PyPI with pip install 'lumen[ai]' if you want the AI features. It requires Python 3.11 or newer according to pyproject.toml.

### How do I set up holoviz/lumen and start using it?

After installing, run lumen-ai serve data.csv, replacing data.csv with your own data path. The README says this starts a Lumen Explorer server, and points to the getting started documentation for the rest of the flow.

### What exactly is holoviz/lumen?

It is an open source, extensible agent framework for chatting with data and for retrieval augmented generation, built on Panel. It generates SQL pipelines, charts, tables and dashboards from natural language as declarative specifications.

## Sources

- [holoviz/lumen on GitHub](https://github.com/holoviz/lumen)
- [License: BSD-3-Clause](https://github.com/holoviz/lumen/blob/main/LICENSE)
- [Project website](https://lumen.holoviz.org)
- [README](https://github.com/holoviz/lumen/blob/main/README.md)
- [Releases](https://github.com/holoviz/lumen/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/holoviz-lumen