trellum
Blog / Why trellum exists

Why trellum exists

I didn't set out to build a reporting framework. I wanted answers from my data, faster, with AI. trellum is what was left standing after everything that didn't work.

Dashboards took too long, even before AI

The old way was manual. Building a dashboard meant hours of clicking, arranging and polishing. I spent a lot of time learning visual dashboard tools and still had more to learn. And when agents arrived they couldn't help me there: a drag-and-drop tool has no code for an agent to write.

So the agents got a folder

My AI workflow became a folder. Queries, notes, schema descriptions, a few Python scripts. Context I could point an agent at so it would stop guessing what "revenue" meant. Colleagues used it too, and since asking was suddenly cheap, the ad-hoc analyses multiplied. Another question, another agent-generated dashboard, another HTML file.

The one-off HTML trend

Honestly, those dashboards were garbage in nice clothing. Giant HTML files with the data baked in, numbers that were sometimes hallucinated, and no two regenerations that ever matched.

In practice that hurt, because I needed numbers quickly and they had to look good enough to go straight into presentations. So I was stuck in a loop: ask the AI for a dashboard, get something not quite presentable, rework it by hand, run out of time, ask again. Publishing one decent set of charts could eat my whole day.

The strange part: people loved them anyway. And then someone asked the obvious question:

"This is great. Can we get it every day?"

I did it, and it worked. But only because I wrote custom code every time to pin the layout and the numbers down, which cost me a lot of time. And the smallest change still made the agent query all the data again and rebuild the whole report. Minutes per iteration, at best.

Make the agent write code instead

The fix was not a better prompt. It was moving the AI to the other side of the line:

beforeyou prompt → the AI improvises the whole report, every day
Mon
Tue
Wed
Thu
afterthe agent writes code once → scheduled builds, every morning
Mon
Tue
Wed
Thu

The agent still does the creative work. It just commits code instead of re-performing the report. That is trellum: an open-source Python framework for BI reports written as code, built deterministically.

Building it was a process. But because it came out of a real necessity, it turned into something my peers and I genuinely love using. The report is just there every morning, and I don't think about it anymore. I think others will love that too.

Separate the data from the report

The other half of the fix: getting the data and building the report are two separate steps.

any source, combined compiled dataset · cached report build, in seconds

Report code can bring together databases, warehouses, files, and APIs through trellum's built-in readers or a service's Python SDK. With query caching configured, repeated builds can reuse the data while you iterate on the report. Themes and shared annotations ride on the same build: define them once and reuse them across reports.

What's in the box

Everything I kept rebuilding by hand, built in:

display interaction statistics report-wide
line · area · bar · stacked combo · doughnut · scatter heatmap · funnel · treemap KPI rows tables & pivots filters & cross-filtering date selectors tab groups A/B compare CUPED & bootstrap CIs AI context widgets CSV & PDF export themes & custom themes shared annotations

And when none of it fits, your agent can write a custom HTML visualization and wire it to the framework's theme, filters, and shared data. That connection is ordinary report code, so I can inspect and change it too.

This is for everyone

Data scientists and analysts will probably feel it first. But trellum is not a specialist tool. If you have an agent and a question, you can have a report: marketing, ops, finance, founders, anyone. Ask for it, review the code, then schedule builds in the portal or your own CI. Everyone reads the same published report, with the calculation kept in Git instead of reinvented each morning.

Making charts used to be the work. Now the work is asking better questions. Go ask one.

Sixty seconds to a report

$ python -m venv .venv && . .venv/bin/activate
$ python -m pip install trellum
$ python -m trellum.demo --dest demo-project
$ cd demo-project
$ python -m trellum.run reports/player-overview --no-serve --portable
$ python -m trellum serve --background

Or skip even that. My honest recommendation is to not set anything up yourself and let your agent do it:

paste to your agentRead https://github.com/trellumhq/trellum#readme. In this existing folder, preserve unrelated files and the existing Git history. Create a Python 3.11+ virtual environment, install `trellum` with `python -m pip install trellum`, then run `python -m trellum` for the trellum CLI's own instructions and add the smallest useful report here. Do not clone another repository or overwrite this one.

Open the result in your browser, export the PDF, send it. Explore the demo gallery or start from the repository README.

trellum is a true passion project. It came out of necessity, it was built with love, and I hope everyone enjoys it as much as I do.

— Apollo