What is Lumen?Lumen is an open-source framework for conversational data exploration and analysis. You ask a question about your data, and an LLM proposes the SQL, the transformations and the chart. Every step stays visible, editable and re-runnable. Lumen is built on Panel and the rest of the HoloViz ecosystem, so the results are interactive tables, plots and dashboards. If you are new to it, the Lumen 1.0 announcement explains the design.One chat, many outputs: your question goes to your data sources and comes back as maps, charts and tables.New Release!We are excited to announce the 1.4.0 release of Lumen! This release makes Lumen easier to start and cheaper to run well. You no longer need an API key to try it, answers rest on better table context, and a report can write its own story. Here’s a high-level overview of the highlights:Run it without an API key: lumen-ai serve works with the Claude Code, Codex and GitHub Copilot CLIs you are already signed in to, with Kilo’s free models, or with a local Ollama. With nothing set up, it tells you which of these to try.Maps from geometry columns: a table’s own geometry column now draws as a choropleth, and GeoJSON files load end to end.Reports with a story: an Annotate button writes a summary and a note under each section, and a report exports to Word.Answers you can check: agents get a compact, exact profile of each table, tool errors go back to the model instead of ending the attempt, and every SQL result is checked for data-quality problems.Usage and cost tracking: see tokens and dollars per call, and trace every model and tool call.Polars and PyArrow: sources can return polars or pyarrow frames, and filters and most transforms run on them natively.Lumen 1.4 requires Python 3.11 or later, Panel 1.9 or later and Bokeh 3.9 or later.Many thanks to the contributors to this release: @ghostiee-11, @philippjfr, @ahuang11, @vignesh-chaturvedi, @SajalDevX, @DevForge255, @7487, @rimsha152007-dotcom, @fly1d, @Vamshi1404, @hoxbro, @AmirF194, @yiboban, @raashish1601, @nightcityblade, @mayuriphad, @mahdibani, @latent-9, @Zayn329, @SuMayaBee, @Mr-Neutr0n, @Coderambling, @umi008, @jadhavgaurav.A special welcome to our new contributors: @vignesh-chaturvedi, @SajalDevX, @DevForge255, @7487, @rimsha152007-dotcom, @fly1d, @Vamshi1404, @AmirF194, @yiboban, @raashish1601, @nightcityblade, @mayuriphad, @mahdibani, @latent-9, @Zayn329, @Mr-Neutr0n, @umi008, @jadhavgaurav.Run Lumen Without an API KeyWithout an API key, lumen-ai serve used to start against a provider that was not there. In 1.4 there are four ways to get going without one.Coding CLIsIf you are signed in to Claude Code, Codex or the GitHub Copilot CLI, Lumen can use it as its LLM:lumen-ai serve penguins.csv --provider claude-codeThe other values are codex-cli and copilot-cli, and antigravity-cli is available too. The Claude Code and Copilot providers run the CLI with its own tools switched off and in an empty temporary directory, so it answers Lumen’s prompts without reading the folder you launched from.One limit: Lumen’s own tools are not forwarded to these CLIs. An action that needs the model to call a tool, such as fetching a URL from the chat, cannot run, so pass your data on the command line.Free models with Kilolumen-ai serve penguins.csv --provider kiloKilo’s free tier needs no account. It is a shared service, so expect it to be slow and to have limits. In our tests a question that ended in a chart took five to six minutes, and after roughly 40 minutes of steady use it answered with a 429 that points to a free sign-up. The free router also changes which model it uses over time, and some of those models reject the structured requests the planner makes. When Kilo answers with an upstream error, Lumen now falls back to asking for JSON in plain text and keeps doing that for the session.For a local model, Lumen reads OLLAMA_HOST, and the local providers now default to a 9B model, which you can fetch with ollama pull qwen3.5:9b.If nothing is set up, Lumen no longer guesses. It picks a provider only when its API key is set, and otherwise prints what would work on your machine:ERROR: No LLM provider found: no API key is set.Pick one of these to get started:- Free models, no signup: --provider kilo- Use a coding CLI you are signed in to: --provider claude-code- Sign in to one of these coding CLIs first: --provider copilot-cli, --provider antigravity-cli- Set an API key, e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY- Use an OpenAI-compatible server: --provider openai --provider-endpoint URL- Ollama is running with no models: `ollama pull qwen3.5:9b`Docs: https://lumen.holoviz.org/configuration/llm_providers/Maps and Geospatial DataA table that has a geometry column can now be drawn as a map directly. Start Lumen on a GeoJSON file, a WKT file or a zipped shapefile, and ask for the map:lumen-ai serve countries.geojson --provider claude-codeMap each country’s estimated population as a choropleth on a log colour scale using the Equal Earth projection, with a legend.A table with a geometry column becomes a choropleth: chat on the left, the Vega-Lite spec above and the map below.The chart is a plain Vega-Lite spec, shown above the map. If something is off, edit the YAML or ask for the change.Maps are interactive: hover a state to see its values, and the view follows the light or dark theme.A choropleth of average PM2.5 by US state in dark mode, with a tooltip on Texas.Around that feature, geospatial support got a round of fixes:GeoJSON uploads load end to end (#1996), and the coordinate reference system of a GeoDataFrame survives ingest into DuckDB (#2077).A choropleth whose lookup named an unregistered dataset no longer renders blank (#2001), and point layers on a basemap are fed the table (#2151).The DeckGL prompt knows GeoJsonLayer and data-driven colours (#1999), and datetime columns in GeoJSON layers serialize (#1997).Geometry now renders in Vega-Lite views, both from a table’s own geometry and when a spec joins external boundaries (#2232).Gridded data handles cftime dimensions on xarray-sql 0.6, and a to_dataset result that is not a grid is no longer gridded (#2144, #2049).Charts From a SentenceMaps are one case of a general ability: describe a chart and Lumen writes the SQL and the spec. Here is a prompt with several moving parts, run on the Gapminder data:For the ten most populous countries in 2005, draw a connected scatter plot of fertility against life expectancy from 1955 to 2005, with bubbles sized by population at each point and the country name at the 2005 end of each path.Ten countries from 1955 to 2005: fertility falls as life expectancy rises, bubbles sized by population.A language model writes each chart, so a rerun gives a different one, and a first pass sometimes needs a follow-up. In this one, a few labels near the bottom right overlap. The specs and SQL behind this figure are in the repro/ folder of this post.Follow-ups work on the chart you already have. Here Lumen draws UK electricity per capita from fossil fuels, nuclear and renewables as a stacked area, and a follow-up can redraw it, for example as a line chart comparing just fossil fuels and renewables:A stacked area chart of UK electricity per capita from fossil fuels, nuclear and renewables.The Vega-Lite agent also got better at stacking and ordering: asked for the US athletes with the most Olympic medals, it draws a stacked bar by medal type (#1992).A stacked bar chart of the ten US athletes with the most Olympic medals, led by Michael Phelps, split by medal type.Two more prompts on data-centre electricity demand: a slope chart that highlights the United States in red, and a ranking bar chart that labels each bar with its value.A slope chart and a ranking bar chart of data-centre share of electricity demand for the United States, China and the world.Reports With a StoryA Lumen report collects the tables and charts from your explorations. In 1.4 you can ask it to write the story around them. The Annotate button uses an LLM to write an overall summary at the top and a short note under each section. The narrative shows in the report and flows into the Notebook and HTML exports.A report can now also be exported as a Word document. The .docx carries the headings, the narrative, native tables and the charts as images, respects the section selection, and includes the story and notes (#1924). The story’s prose is editable with Panel’s TextEditor (#2017), so you can fix a sentence instead of regenerating the whole thing. The Word export needs python-docx, which Lumen now installs.Lumen’s AI-written story on a report about the Palmer penguins, with the export menu open.Answers You Can CheckMost of the engine work in this release is about giving the model better facts and catching mistakes cheaply.A compact, exact view of your tablesThe table context agents see used to be built from a shuffled 100-row sample with no SQL types or keys. It could list wrong ranges and incomplete value lists, it dropped NULLs, and it changed on every run, which defeated prompt caching. It is now profiled with the cheapest accurate strategy for each source: engine metadata first, one exact pass for tables up to a million rows, and a seeded sample above that (#2105). This is what the model sees for the penguins data:import asynciofrom lumen.ai.schemas import get_metasetfrom lumen.sources.duckdb import DuckDBSourceurl = "https://datasets.holoviz.org/penguins/v1/penguins.csv"source = DuckDBSource( uri=":memory:", tables={"penguins": f"read_csv('{url}', nullstr='NA')"},)print(asyncio.run(get_metaset([source], ["penguins"])).compact_context())penguins (344 rows) species VARCHAR {Adelie:152, Gentoo:124, Chinstrap:68} island VARCHAR {Biscoe:168, Dream:124, Torgersen:52} bill_length_mm DOUBLE 32.1..59.6 nulls