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:
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.
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:
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:
Read 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