trellum
Docs / Recommended workflow / The analytics repository

The analytics repository

Applies to: latest

One repository holds two things: the reports you ship, and everything an assistant needs to know to write them. This page covers what trellum actually requires — which is very little — and then what we would recommend putting alongside it.

Set up the project

Run python -m trellum.init in your project to create source/report folders, agent guidance, editable context/ notes and an analysis/ investigation area. For an existing project, python -m trellum setup project adds the guidance and context without replacing your notes. Both commands preserve authored context on subsequent runs. python -m trellum.demo --dest my-project also installs this guidance alongside the offline demo.

Start with source discovery and named queries (python -m trellum data and python -m trellum guide answer). Keep reproducible queries and sanitized findings in analysis/; save CSV exports under analysis/results/, which is ignored by Git by default. Record source, query, parameters, data dates and limitations beside each investigation. Promote verified facts into context/ and approved metric definitions into the existing registry. These are editable project notes, not an automatic portal assistant memory or data-ingestion job.

python -m trellum setup project --remove removes only unchanged context files that setup recorded as its own in .trellum/project-context.json. Keep that ownership record with the project for safe removal. Existing files, edited notes, queries and exports remain untouched. The results ignore file stays while any local results remain; malformed ownership metadata is retained and reported.

What trellum requires

All of it:

What we require

reports/
└── <anything>/
    ├── report.yaml
    └── generator.py

A directory under reports/ with those two files is discovered as a report. Data sources, metrics, and other supported project settings are read when used.

What is yours

  • dbt, notebooks, pipelines, another BI framework entirely
  • your own tooling, CI, scripts, internal documentation
  • whatever already lives in the repository you have today

Add reports/ to an existing repository and nothing else has to move.

Directories whose names start with _ are skipped. A report needs report.yaml and generator.py. An analysis uses the same directory convention with kind: analysis in report.yaml and content.md instead of a generator. See Publish an analysis for the article and evidence format. Point a studio at the repository and it works.

No other directory structure is required for report discovery. Project files such as data-sources/config.yaml, metrics.yaml, and config.yaml are read when reports use the corresponding data, metric, or extension features; the context and assistant files below remain your own conventions.

Everything else is yours

The rest of the repository does not need a prescribed layout. You do not need a new repository, and adding a reports/ directory to one you already have is a perfectly normal way to start.

What we recommend alongside it

your-analytics/
├── AGENTS.md            # how your team works
├── .mcp.json            # optional: the portal as an MCP server
├── context/
│   ├── warehouse.md     # the tables that matter
│   └── metrics.md       # how each KPI is counted
├── data-sources/
│   └── config.yaml      # which sources exist; never their secrets
├── analysis/            # ad-hoc scripts, kept or not
└── reports/
    └── weekly-revenue/
        ├── report.yaml
        ├── generator.py
        └── queries.py      # optional; SQL or source reads

AGENTS.md

The house rules an assistant reads first: which sources and definitions are authoritative, naming conventions, which fields or tables are deprecated, that database SQL belongs in queries.py, and that nothing merges without review.

context/metrics.md

The canonical definition of every number people argue about — what it counts, what it excludes, which table it comes from, and who decided. This is usually the highest-value file in the repository, and the one that pays for itself fastest.

context/warehouse.md

For database sources, document the grain of important tables, safe joins, and common traps. For other source types, record their fields, meaning, and known limitations. Write down what you would tell a new analyst in their first week.

data-sources/config.yaml — the sources, never the secrets

Where connections are declared. The same file serves both places a report runs, which is worth being precise about.

The file never holds credentials. It describes a source and names an environment prefix to fetch the secrets from:

sources:
  warehouse:
    type: postgres
    host: warehouse.internal
    port: 5432
    database: analytics
    credentials:
      local: WAREHOUSE          # read WAREHOUSE_USER, WAREHOUSE_PASS from .env

On your own machine, you set those variables — a .env file beside your project is loaded automatically — and the framework connects. The same file serves both workflows: a report and a throwaway script reach the source identically. See Ad-hoc analysis.

On the portal, commit the file. Every publish reads it and mirrors the declarations into the studio: each source appears on the studio's Data sources page with its type and connection details already filled in, read-only, and asks only for the credentials. Those are stored encrypted and injected, decrypted, into that studio's own builds — the credentials: block above is for your machine and is ignored there. Before every build the worker writes the data-sources/config.yaml the build reads from the portal's own settings, so your committed copy is never the file the report opens. See Connecting your data sources.

Note

Because the file holds references rather than secrets, committing it is safe and useful — on the portal it is how a source comes into existence at all, and a colleague cloning the repository sees which sources exist and which variables to set. What must never be committed is the .env holding the values. That indirection is the whole reason connection secrets are not part of the repository contract: a warehouse password would otherwise live in every clone and every fork of your history.

.mcp.json — optional

The portal is an MCP server. With this file and a personal API key, the assistant working in the repository can read what the portal has built — build status, validation, published numbers — and, on a write key, build a report or publish. Setup and the tool list are in Working with AI agents. Useful, never required: an assistant reaches your data perfectly well through the configured sources above.

analysis/ — optional

Somewhere for ad-hoc scripts to land. Some teams keep them as a record of what has been asked; others delete them freely. These scripts are not discovered or scheduled. Published analysis articles go under reports/<slug>/ with kind: analysis, so the portal can discover and publish them.

Start with definitions, not reports

Before the first report, write context/metrics.md. One entry per number the business argues about. This single file removes most of the disagreement that otherwise surfaces after a dashboard ships, when it is expensive.

Next

Validate changes before merging

Use the CI validation recipe to build your reports on pull requests and fail the check on validation errors.