trellum
Docs / Portal guide / The AI assistant

The AI assistant

Applies to: latest

A panel in the corner of the portal that answers questions about your reports in plain language. Someone asks "why did revenue drop last week", and it points them at the report that covers it, names the chart, and gives them the number — read out of the report's own already-built output.

It exists for the people who read reports rather than write them. The analyst who built the report knows which one answers the question; everyone else has to go looking, and mostly does not. That gap is the whole purpose.

It is off until an organization admin turns it on, and it needs your own model provider key. Nothing about it runs, costs anything, or sends data anywhere until someone deliberately configures it.

What it can and cannot do

It reads built report output. When a report runs, it publishes its data alongside its charts. The assistant reads that published data — filters it, aggregates it, and quotes the result. It is the same data anyone with access to the report can already see, reached a different way.

It can explore explicitly authorized PostgreSQL sources. In a studio conversation, it can discover permitted tables, inspect their columns, and run read-only analytical queries, including joins and aggregations. An administrator must first grant named users or groups access to explicit schema-qualified relations. Report visibility and administrator status do not grant this access. Queries run as durable worker jobs; the panel waits and resumes the conversation automatically. You can cancel a pending read. Report-bound conversations continue to use their report's published data.

Source results include the executed SQL, execution time, returned table and truncation indicator. They are labeled exploratory: a successful query does not prove that its calculation matches the business meaning of your question. Changes to a grant or its source configuration invalidate earlier source evidence in a conversation. Start a new conversation with the current permissions.

It cannot change anything on its own. Its read operations inspect built reports, report documentation and accessible alerts: no creating reports, no editing them, no changing settings, no running builds. An organization admin can let it propose a short list of portal actions — configure or test a data source, build a report, publish repository changes, set up an alert — and each one waits for a person to approve it in the panel. It never edits the repository. See Actions and approval.

Ask it to find an alert by report name, report slug or rule name. It returns the rule's stable ID and detail link; when names match several rules, choose the report and rule you mean. get_alert reads settings, recipient summaries, the latest live condition and interpreted evidence window. These reads use the same report visibility as the Alerts page and do not change any settings.

Updates carry the current edit_revision from discovery or the create/update result. Approval checks that all editable settings and recipient memberships still match. If somebody edited the rule meanwhile, the assistant must read it and propose again. Older pending updates without this token also require a new proposal. Frequency, delivery-time and recipient edits preserve the condition episode. Changes to the report, instructions or evaluation timezone change the condition revision; the edit revision covers all editable settings.

The assistant can explain its currently available reads, actions and limits for your role, conversation scope and organization action policy. Report-bound conversations can discover only their report's alerts and cannot update them. If you have full studio access, start a studio conversation to propose an edit. Provider chat/tool compatibility is checked separately in AI settings.

MCP uses the same discovery and update tokens. Reads need no configured model provider. MCP updates execute with a write key and enabled organization actions under the calling harness's approval; they do not create panel approval cards.

It only sees one studio. A conversation belongs to the studio it was started in, and the assistant reads that studio's reports and no others. Someone who cannot open a report in the portal cannot get its numbers out of the assistant either — access is checked the same way for both.

Check the evidence behind an answer. Analytical answers pass a structured review before delivery. The server renders referenced values from successful, authorized tool results, checks declared intended context against available executor metadata, and rejects mismatched values and unsupported complete totals. The answer names its source context and shows the assistant's actual assumptions and unresolved business-analysis rationales. Draft answers stay private while the assistant gathers evidence or corrects a submission.

These checks establish result cells and supported structured context. They do not prove that the assistant understood your question, selected the right metric, interpreted SQL correctly or explained a cause correctly. Qualitative explanations remain model assessments, including when a canonical metric was calculated. Clarifications can ask specifically which revenue definition, population or period you mean; ordinary help and documentation explanations remain available. Conversational explanations receive no numerical-evidence assurance.

The result tables come from executed reads; the model's explanation can still be mistaken. Review the query, filters, dates, metric definition and any truncation before relying on an answer. There is no guarantee that every question receives a correct answer.

Approved metric calculations

Reports can opt into an Approved calculation path by publishing explicit metric bindings and execution semantics. The assistant uses list_metrics, get_metric_definition and query_metric to calculate from those bound inputs. The evidence card displays the actual calculated values, unit/currency, period, timezone, filters and build/definition identifiers. The label describes the calculation contract; it does not certify the source data or the model's prose.

Report authors configure metrics.yaml execution metadata and report.yaml metric_bindings following the framework execution contract. Existing reports keep working without these declarations. They remain exploratory until an author supplies and reviews the business meaning, completeness and freshness rules. The initial approved path supports complete daily report artifacts: additive sums, absolute sums, ratios of summed operands, last values and averages of daily totals. It refuses stale builds, missing periods, unsupported rollups and conflicting definitions. Live queries remain exploratory; live approved bindings, multi-chunk execution and non-daily calendars are not supported.

Use the offline evaluation guide to check calculation contracts and score supplied model captures without calling a provider.

The same access checks apply when reopening stored evidence. An administrator exporting another person's account does not automatically gain that person's source or metric conversation content; restricted content is withheld.

Source-query setup and limits

Use a dedicated PostgreSQL login with only CONNECT, schema USAGE and SELECT on the intended tables or reviewed views. Do not reuse a report-building or administrator login. The executor rejects superusers, bypass-RLS identities, role/database creators, replication roles and identities with write privileges on application tables. PostgreSQL row-level security remains applicable to the source login. A shared login does not automatically implement per-portal-user row policies; use suitably restricted sources and grants for those audiences.

Grant explicit schema.table relations and named users or groups in source access settings. Enabling this access authorizes sending those relations' schema and result data to the configured model provider. Review views before granting them: their definitions are trusted database code. The pilot supports direct PostgreSQL connections and ordinary scalar types. SSH tunnels, foreign tables, custom types and other database engines are not supported for assistant SQL. Remote PostgreSQL connections require verified TLS and a trusted certificate on the worker host. The worker needs psycopg3/libpq with bounded cancellation support.

Run a runner worker to process reads. Admission allows one active read per conversation, four per organization and 32 across the installation. Each read has a ten-second execution deadline, at most 200 returned rows and 64 KiB of result evidence. Connection, DNS and cancellation have additional bounded grace periods. A question may perform up to 12 source reads across automatic resumptions. These limits do not cap scanned bytes or total database memory; use database-side resource controls appropriate to the warehouse. A failed worker never silently replays an uncertain query. A content-free execution reservation survives conversation or source deletion until completion or its bounded safety expiry. An unconfirmed cancellation is reported as such.

Where your data goes

This is the question worth answering plainly.

When someone asks a question, the assistant sends the model provider:

  • your instructions to it (assistant.md, see below);
  • for project-wide conversations, a bounded summary of metrics.yaml definitions, including names, labels, descriptions, owners and tags;
  • a catalog of your reports — names, descriptions, dataset names, column names and date ranges — and where the person is in the portal (page title, path, and the chart they asked about when they asked from one);
  • schema metadata and bounded query results from sources explicitly granted to the person asking, when the assistant uses those sources;
  • the conversation so far;
  • the results of whatever it looked up to answer — typically an aggregated table of a few dozen rows, not a raw export;
  • when Let the assistant read report source is on (the default), a report's own source files (report.yaml, queries.py) if it chooses to read one to explain how a metric is computed. Turn it off and the assistant is told those files are unavailable.

Project-wide conversations can also read bounded metric definitions from metrics.yaml, including canonical SQL, when report source sharing is enabled. The assistant prefers those definitions and identifies differences from report source. Report-bound conversations cannot read the project registry: it has no per-report visibility mapping. They explain metrics from permitted report source and identify that limitation. Missing, invalid or oversized registries also use that fallback; unavailable source is never treated as a verified definition.

It never sends data-source connection details (data-sources/config.yaml) — that file is not readable by the assistant at all — and nothing from outside the studio's project.

Everything the provider sees that came out of your reports or files is marked as data, and the assistant is instructed to treat it as data rather than as instructions. That is a mitigation, not a guarantee: a report description that says "ignore your rules" is still text going to a language model.

Which provider is your choice, and so is where it runs. The organization supplies its own API key for Anthropic or OpenAI, and billing is between you and them. Trellum never proxies the request, never sees the key in the clear, and does not have an account with either provider on your behalf.

You can keep all of it on your own network. Point the custom endpoint URL at a model server or gateway inside your perimeter and nothing leaves your infrastructure. See Routing requests through your own endpoint.

Transcripts are stored, and they expire. Conversations are saved so people can come back to them, are private to the person who started them, and are purged after RETENTION_ASSISTANT_SESSION_DAYS (180 days by default). Spend records are kept indefinitely, because a deleted cost history is an unauditable bill.

Telling it about your data

The assistant can see the shape of your reports automatically — every built report, its datasets, its columns, and the real date range each one covers. It refreshes that itself when reports rebuild.

What it cannot see is everything your team knows that the data does not say. Which revenue definition the business actually uses. That one dataset is event-grained and counting its rows counts events rather than people. That "the funnel" means one particular report. Without that, the assistant gives answers that are defensible from the data and wrong in the room.

Put it in assistant.md at the root of your analytics repository — beside config.yaml, events.yaml and metrics.yaml, not inside reports/. Every question asked in that studio is answered with that file in front of the model. It syncs like any other file in the repository: push, and the next sync picks it up.

your-analytics-repo/
├── assistant.md        ← what the assistant should know
├── config.yaml
├── events.yaml
├── metrics.yaml
└── reports/
    ├── revenue-weekly/
    └── cart-funnel/

The location is not a convention, it is a constraint. The portal takes a sparse checkout of your repository: only your reports directory and a short list of named root files ever reach the machine. A context file anywhere else — in a subdirectory, in docs/, next to a report — is never read, and nothing will tell you so. It has to be assistant.md at the root.

What to put in it

Write the things that are true about your business and invisible in the data:

  • Definitions that differ from the obvious reading. "Revenue is gross, before store commission and before refunds. Finance's net revenue is a different number and is not in these reports."
  • Traps. "The economy dataset is event-grained, not user-grained. Counting rows counts events, not people."
  • Vocabulary. "'The funnel' means the cart funnel report. 'Conversion' without qualification means purchase conversion."
  • What is not real. "The insert-coin report is built from synthetic data. Never quote its numbers as the business."

Do not restate what the assistant already reads. Listing your reports and their columns adds nothing — it has those — and every line costs a little of every answer.

A worked example ships with the product, at assistant.md in the demo project.

What it can and cannot change

The file shapes how the assistant interprets your data. It outranks the assistant's own assumptions about what a metric means or what something is called.

It cannot widen what the assistant may do. Instructions in it to write something, read another studio, or state a number without a source are ignored — those rules sit above it and are not yours to relax from a file in a repository. Treat it as briefing material, not configuration.

Keeping it honest

assistant.md is a document that claims things about data, which means it can go stale the same way a comment does. When a metric definition changes, the file is part of the change. A stale briefing is worse than none: it makes the assistant confidently wrong, in your own words.

Actions and approval

Off by default. With Let the assistant propose actions turned on (see Turning it on), the assistant can also do the things the portal itself does — and only those:

Action What happens on approval Who can approve
Configure a data source Saves the credentials, runs the connection test and queues the reports that were waiting on it — the same path as the Configure form. Studio admin; organization admin for credentials shared across studios
Test a data source Re-runs the connection test and reports the outcome. Developer
Build a report Queues a build now instead of waiting for its schedule. Developer
Publish repository changes Publishes what the studio has fetched but not yet applied (manual publish mode). Developer
Create or change an alert Saves an alert rule — a report, plain-language instructions, a trigger, recipients, cooldown and notification policy — exactly as the studio's Alerts page would. Developer

The repository is never edited. A report's report.yaml, its queries, validation suppressions and metrics.yaml stay a change you make in git. When the fix is in the repository, the assistant explains which file and which key; it does not make the change.

If you want to change report source from a local browser preview, use the coding-agent review workflow. The portal assistant remains a Q&A and approved portal-actions feature.

The same actions reach your own coding agent over MCP, where there is no card: the agent asks you before each call instead, and the key it uses must carry write scope — see Working with AI agents.

Nothing runs when the assistant asks. Calling an action only creates a proposal. A card appears in the panel saying what will happen and on what, with Approve and Reject. The assistant is told that it has proposed and waits; once you decide, it hears the outcome and carries on — re-tests the source, tells you the build is queued. A card that nobody decides expires after 24 hours and can no longer be approved.

Secrets are typed into the card, never into the chat. When an action needs a password, key or token, the card has a masked field for it. What you type there goes straight to the encrypted store, the same as the Configure form; it never enters the conversation, the stored proposal, the model's instructions or the audit trail. The assistant is instructed never to ask for a secret in chat. If it ever does, do not type one — reject the proposal instead.

Your role at the moment you click is what counts. Each action needs a studio role (the table above). Someone without it never sees the action in the first place, and a proposal made before a role changed is refused at approval, not honoured because it was once allowed.

Every approval is audited. Two rows: the action's own — data source updated, connection tested, run queued, publish requested, alert rule created or updated — carrying the proposal id, and the decision itself (approved or rejected, with the reason you gave).

"Watch this for me." Ask "is paid revenue down this week?", get the answer, and then say "watch this for me and tell me when it drops again". The assistant proposes an alert: the card shows the rule as it will be saved — a name, the report, the instructions, when it is evaluated (after every build of the report, or on a schedule), who is told and the cooldown. The instructions carry what you were just discussing — the report, the filters, the numbers — so the evaluator watches exactly that and not a vaguer version of it. Approve, and the rule is live; it appears on the studio's Alerts page like any other, where it can be tested and tuned. People named by email must already be members of the studio; an address that is not is refused rather than quietly dropped.

From an alert back to the assistant. Every alert email carries an Open in the assistant link. It opens the report with a new conversation seeded from that evaluation — the rule's instructions, the decision, the title, the message, the evidence lines it cited and when it ran — pinned above the transcript as "About alert: …", so your first question ("why did organic drop, and was it every region?") runs against the same report the evaluator looked at. The seeded lines are what the alert said at the time, not live numbers: the assistant reads the report again for anything it states. The conversation records which alert it came from, so it is recognisable in your history later.

Turning it on

Organization settings → AI settings, as an organization admin. These settings select the shared provider and model for portal chats, alert evaluations and report-build completions. If the assistant proposes an action, an organization member must approve it before it runs.

Choose Anthropic, OpenAI, LiteLLM, OpenRouter, DeepSeek, Azure OpenAI, Amazon Bedrock, Vertex AI, or a custom OpenAI-compatible endpoint. One saved connection serves chats, alerts and report builds; gateways control their own routing and fallbacks.

Setting What it does
Enabled Off by default. Turn it on after choosing a usable connection and model.
Authentication API key, gateway-managed authentication, cloud credentials, or operator-authorized workload identity, depending on the provider.
Credentials Encrypted and write-only. Blank fields keep stored credentials only while provider, resolved endpoint, authentication mode and cloud identity are unchanged. Changing that identity requires replacement credentials.
Model Anthropic defaults to claude-sonnet-4-6; OpenAI defaults to gpt-4o. Other providers require an explicit model ID. Azure requires a deployment name.
Discover models Optional catalog lookup using the saved connection. Manual entry always works. Azure catalog names are not deployment discovery.
Let the assistant read report source On by default. Off prevents reading report.yaml and queries.py; the assistant can still read built output.
Let the assistant propose actions Off by default. Each proposed action waits for a person to approve it.
Monthly / per-user budget Spend caps per calendar month. Blank means no cap.
Custom endpoint URL Under Advanced. Required for LiteLLM, custom endpoints and Azure; optional for direct APIs. Bedrock and Vertex use native cloud endpoints.
Input / output price USD per million tokens, both or neither. Required for budget enforcement when provider pricing is unknown. Zero and zero are valid for a free model.

For a new connection, leave Enabled off, enter its endpoint and credentials, then save. Discover or enter a model, enable AI, save again, and use Test connection. Discovery failure does not block manual model entry. Settings save in place and preserve drafts in neighboring forms.

Cloud connections use these fields:

  • Azure OpenAI: an HTTPS Azure resource endpoint, deployment name, and either an API key or an Entra tenant ID, client ID and client secret.
  • Bedrock: AWS region and an access key ID plus secret access key; a session token is optional. The model ID may also identify an inference profile.
  • Vertex AI: Google Cloud project and location, plus service-account JSON. Only service-account credentials with the trusted Google token endpoint are accepted; external-account credential configurations are not accepted here.

Each cloud provider also offers workload identity when the instance operator has authorized this organization for that provider. Organization admins cannot add that authorization themselves. See instance configuration. Missing organization credentials never silently select a server identity.

The page separates Chat, Alerts, and Cost metering capability checks from saved-settings chat readiness and model pricing. Chat can work when an endpoint cannot force an alert tool call; alerts remain unavailable in that case. New providers require verification for chats and alerts. Report completions do not require a successful Test connection. Existing native provider configurations retain their established behavior until rechecked.

Budgets

Spend is recorded per organization and per user, per calendar month, and checked before every model request and between the steps of a single answer — so a question that turns into a long chain of lookups stops at the cap rather than discovering it afterwards.

A reached cap blocks new questions and explains why. It does not delete anything, and the next calendar month starts clean.

Because the key is yours, these caps are Trellum's accounting of what it spent on your behalf, not a limit enforced by your provider. Set a limit at the provider too if the number matters.

AI during report builds

A generator can call ctx.ai.complete(system=..., user=..., max_tokens=8000) using this same saved connection. The worker keeps credentials private: report code receives neither the API key nor the endpoint, and needs no vendor SDK or key file. Model and endpoint changes apply on the next call. Test connection verifies the same saved endpoint when an admin runs it; it is not a prerequisite for report completions.

This is a blocking, one-shot completion, without tools or streaming. Reports must catch trellum.ai.ReportAIError to publish their remaining sections when AI is disabled, unavailable, over budget, times out or fails. Uncaught errors fail the build. Local framework builds without the portal return unavailable. See python -m trellum guide ai for the API and catch pattern.

All report-build spend uses the shared monthly organization cap and meter. It never counts against a user's monthly cap, even for a manual build. There is no per-build call-count cap; once the organization cap is reached, later calls fail cleanly with budget, while a report that catches the error can still publish. Budgeted reports need known pricing and returned token usage, but never need a stored successful Cost metering check. Missing usage fails that call without booking a guessed charge; the next call can try again. If returned usage is valid but the answer is rejected, that usage still counts toward the organization cap.

A provider may still charge for a request that times out or is stopped before usage is returned. Trellum cannot record that unknown charge. Use a provider-side limit when you need a hard billing cap, and compare the recorded totals with provider billing.

The optional model= argument selects another model for one call. Saved prices apply only to the saved model; an override uses its own known direct-provider prices. Budgeted calls fail before contacting a model whose prices are unknown. For a gateway or cloud model, save the desired model and its prices in AI settings.

Optional response_format="json" uses native JSON response format on OpenAI-protocol providers. Anthropic, Bedrock and Vertex instead receive a best-effort instruction to return JSON. Invalid JSON raises ReportAIError with invalid_response. Reports should parse the returned text and validate their own schema as well.

Routing requests through your own endpoint

Use LiteLLM or Custom OpenAI-compatible endpoint for a gateway or local model server. The endpoint must support Chat Completions, streaming and tools. Anthropic custom endpoints must support the Anthropic Messages format. Select No authentication only when an explicit endpoint authenticates for you or needs no key. Any API key supplied is sent to the selected endpoint; changing the destination does not reuse a stored key.

OpenRouter and DeepSeek have preset endpoints and require a model ID and API key. Cloud providers use their own authentication and endpoint rules.

Gateways and cloud providers do not inherit direct-provider prices from a model name. Enter your actual input and output prices if needed. Without prices, uncapped calls may run with unknown cost; unknown charges are excluded from recorded totals. Budgeted chat and alert calls require both pricing and verified token usage. If a provider stops returning usage, further budgeted chat and alert calls are blocked until metering is checked again. Report completions fail that call without booking a guessed charge or requiring a new connection test. Compare recorded estimates with provider billing.

Test connection uses only synthetic prompts and harmless synthetic tools. It verifies streamed chat, a tool roundtrip, a forced alert tool, and token usage. It uses the settings as last saved and does not execute portal actions or send report data. A successful provider test can still leave AI unavailable because it is disabled, lacks budget pricing, or cannot meter usage.

Results belong to the exact configuration revision tested. Saving a new model, endpoint or credential clears old verification; pricing and budget changes keep capability results. Delayed results from older connections are discarded. Connection failures appear as safe messages; no credentials or signed cloud URLs are shown.

Who can use it

On a studio or report page, AI assistant opens the chat directly when the organization has a working provider configuration. Existing conversations can be resumed; setup is only shown when the assistant is unavailable.

On an organization page, select AI assistant, then choose an accessible studio to open or resume its chat. The panel names that studio. Choosing a studio does not combine its data or conversations with another studio's. Docs remains a separate link to documentation.

Any studio member who can view the studio. There is no separate permission: if someone can open a report, they can ask about it, and if they cannot, the assistant will not answer about it either.

Viewers granted selected reports use conversations bound to one allowed report. Those conversations cannot read other reports or the studio-wide briefing. Changing the report context requires a conversation for that report. If a person's access is narrowed, older studio-wide conversations are hidden; report-bound conversations are available only while their report remains accessible. Restoring broader access restores access to the retained history. The conversation keeps its original scope after a promotion: report-bound conversations can propose running that report when the role permits it, but cannot configure studio-wide data sources or publishing. Action approvals also require the conversation to remain accessible.

Agentic alerts evaluate only their bound report, using their owner's current access. Losing that access pauses evaluation and delivery; recipients must still be able to view the report when an alert is sent.

It appears as a panel in the portal and on built report pages inside the portal. Shared links and exported copies of a report do not carry it — a report sent outside the portal has no assistant in it, because it has no one authenticated to answer for.

When it is not available

An unavailable AI assistant entry explains whether the organization has not configured it, disabled it, lacks a required credential, or has reached a budget cap. It links to AI settings when your role permits configuration. If the availability check fails, the entry offers Retry without requiring a page reload.

The panel says the model provider returned an error. The request left the portal and came back broken. The panel shows a safe explanation of the failure. Organization admins can check streaming, tool support and metering from AI settings. Check that the provider matches the endpoint's dialect (an Anthropic provider needs an endpoint speaking the Anthropic Messages API, not the OpenAI format), then run Test connection on the settings page: it fails the same way, with the same detail, without anyone having to ask a question.