Documentation / Reporting & Data

AI Reporting

Ask Nexus questions in plain language and get governed, auditable answers — every AI query compiles to reviewable UQL and runs through the same permissions, bridges, and audit log as a human user, inside your own Azure tenant.

AI reporting lets a person or an AI assistant ask Nexus questions in natural language and get answers drawn from your live business systems. It is built for analysts, operators, and admins who want fast answers without writing UQL by hand — and for the engineering and compliance teams who need every one of those answers to be permissioned, logged, and reproducible.

The central design decision: there is no separate "AI back door" to your data. An AI assistant connects through the same governed interface as any other client, and a natural-language question is never run as opaque magic — it is compiled into a concrete, reviewable UQL query or a saved report that you can inspect, keep, and audit.

Natural language compiles to reviewable UQL

This is the part that turns "AI reporting" from a liability into a governance feature. When an assistant answers a data question, it does not reach into a database with generated SQL of unknown provenance. It calls Nexus's typed tools, and the query it constructs is a structured UQL definition — the same JSON where / group_by / post_processing shape a human author writes. That definition is the artifact of record:

You can see the query before it runs. The assistant proposes a structured read; the read is what executes. There is no hidden translation layer between "what the AI said" and "what hit your data."
You can keep the query. When the assistant saves its work as a report, the definition is committed to your per-tenant version-controlled repository — history, diff, and restore included. The lineage of any recurring number is preserved: who created it, what it reads, and every revision since.
You can review it like code. Because the output is a declarative report definition rather than free-form code, a reviewer can read exactly which bridge, collection, filter, and aggregation produced an answer, and re-run it deterministically.

For a skeptical platform team, this is the difference between "an AI queried our ERP somehow" and "here is the exact, permission-bounded, version-controlled report the assistant ran, and here it is in the audit log." Natural language is the input; a reviewable UQL report is the durable output.

How it works

Nexus exposes its capability surface over the Model Context Protocol (MCP), an open standard for connecting AI assistants to tools and data. Assistants such as Claude, Copilot, or any MCP-compatible client connect to your Nexus instance and call the same tools your applications use:

Discover what data sources (bridges) exist and what schema they expose.
Query data ad hoc, or run a saved, parameterized report.
Author reports, Python pipelines, hosted sites, and reusable skills — all version-controlled.

Because the AI works through the platform's defined tools rather than touching databases directly, every action it takes is something Nexus already knows how to authorize, validate, and record.

A typical flow an assistant follows:

list_bridges — see which data sources the tenant actually has. Nothing is assumed.
discover_schema — inspect a source's collections and fields before querying, so the generated query references real columns.
query_data or execute_report — read data, with the engine pushing filters and aggregations down to the source where the adapter supports it, and finishing the rest in-engine.

It rides the same capability model

An AI-authored query is bound by exactly the same UQL capability model as a hand-written one (ADR-0058). The assistant does not get a faster or looser path to your data:

Each adapter declares typed capabilities and pushdown. The engine hands the assistant's where clause to the adapter as a hint, then re-applies the filter in memory unless the adapter supports full pushdown and every operator is pushable — so an AI-generated filter never returns extra rows because an operator wasn't supported at the source.
Group-by and aggregations the source cannot push are computed in-engine, bounded by a post-processing row budget. An AI question that fans out too far is bounded, not unbounded.
discover_schema grounds the assistant in your real schema, so it filters and groups on columns that exist.

In other words, the same correctness and safety properties that make hand-written reports trustworthy apply verbatim to AI-generated ones. The model chooses what to ask; Nexus decides how — and whether — to run it. See the capability matrix for what each connector can push down.

Governance is the point

Every AI query runs inside your Azure tenant and is subject to the same controls as a human session. Nexus does not relax any rule because the caller is an AI.

Control	How it applies to AI
Authentication	The assistant connects with a real, scoped credential. No anonymous access.
RBAC	Every call is checked against `resource:action` permissions. The AI can only see and do what its identity is granted — no more.
Admin / human-only gates	Privileged actions (for example, saving a Python pipeline, which executes real code) require the Admin role; some actions are reserved for humans entirely.
Audit trail	Reads, writes, and authoring actions are logged the same way human actions are.
Version control	Anything the AI authors — a report, a pipeline, a site, a skill — becomes a commit in your per-tenant repository. You can view history, diff revisions, and roll back.
Tenant isolation	One tenant's data, sources, and content never cross to another.

In short: if a person with the assistant's permissions could not run a query, the assistant cannot either — and whatever it does run is traceable after the fact. The MCP server is governed by the identical RBAC and audit machinery as the REST API; there is no privileged AI role. For the connection and identity details, see Connecting AI agents and the MCP server documentation.

What it does, honestly

AI reporting is an interface, not magic. Nexus does not invent data, and it does not bypass your access model to "be helpful." When an assistant answers a question, it does so by calling real tools against real sources you have configured, returning the same results a saved report would.

Two practical consequences worth stating plainly:

Accuracy comes from your data and queries, not from the model's training. A good answer depends on the bridges, schema, and reports you have set up. The assistant can pick the wrong column or misread an ambiguous question — which is exactly why the compiled UQL is reviewable and why recurring numbers should be pinned to saved reports.
Authored content is reviewable and revertible. Because AI-generated reports and pipelines are version-controlled and permission-gated, you can inspect precisely what was created before it runs in production, and restore a prior version at any time.

Prefer saved reports for repeatable work

Ad-hoc natural-language queries are ideal for exploration. For numbers you will pull again — a weekly KPI, a board metric, a reconciliation — have the assistant save a report: a parameterized JSON query definition that pushes work down to the source and produces the same result every time it runs. Reports are version-controlled, so the definition behind a recurring number is always auditable, and an execution role can pin the exact permissions the report runs under (see Execution roles).

You: "How many open orders do we have per region this month?"

Nexus (via MCP):
  list_bridges        -> finds the configured order system
  discover_schema     -> confirms the orders collection + fields
  execute_report      -> runs a saved, parameterized query
                         (grouped by region, filtered to this month)
  -> returns rows; the compiled UQL and every step recorded in the audit log

Limits & guarantees

The query is the artifact. Natural language compiles to a reviewable UQL definition; that definition — not free-form code — is what runs and what gets saved.
No privileged AI path. The assistant is bound by the same RBAC, capability model, audit log, and version control as a human client.
Correctness is preserved. Unsupported filters re-apply in-engine; aggregations that can't push run in-engine within a bounded row budget. AI-generated queries inherit these guarantees.
Judgement still matters. The model can misinterpret a question or pick the wrong field — pin repeatable numbers to saved, reviewed reports rather than trusting a fresh ad-hoc answer each time.
Writes are gated. Anything that changes state (saving a pipeline, writing records) requires the appropriate role, and code-executing actions require Admin.

Getting started

Deploy Nexus into your Azure tenant and configure at least one bridge to a data source.
Connect your MCP-compatible AI client to your Nexus instance.
Grant the connecting identity the roles and permissions it should have — and nothing more.
Ask questions. Review the compiled queries, and save the ones you will ask again as reports.