AI Agents — Report Design Recommendations

Audience: End users, administrators, and developers who build reports or documents with the AI agents. Use this document when: You want the report builder or report designer to identify a document type, purpose and audience, and recommend a corporate design before generating or changing a report. Canonical for: AI document and report design recommendations, the design catalogue, custom designs, and the related agent tools. Related: AI Agents Index, Dashboard Builder, End User Guide, Administrator Guide.

What the feature does

The Report Builder agent (new reports) and the Report Designer Assistant (editing an existing saved design) now identify the intended document type, purpose and audience before producing or changing layout. They choose from a deterministic design catalogue instead of inventing layout.

The capability covers two categories:

Business documents — transactional and formal documents.
Business reports — management and analytical reports.

Each catalogue profile defines:

a stable type code and display name
aliases used for identification
default purpose and audience
required data-source type (document or tabular)
presentation template, page orientation and classification
recommended document header fields, line columns and totals
recommended semantic sections

The recommendation is deterministic and validated. The AI cannot return free-form canvas JSON or arbitrary CSS.

Business document catalogue

Type code	Typical use	Purpose	Default audience	Template
`invoice`	Sales invoice	Request payment for goods or services supplied	External customer, accounts payable	Transactional Document
`tax_invoice`	Tax or VAT invoice	Request payment and record tax	Customer, tax authority, accounts payable	Transactional Document
`purchase_order`	Purchase order	Authorize a supplier to deliver at agreed terms	Supplier, procurement, finance	Transactional Document
`quotation`	Quotation or estimate	Offer prices and terms before an order	Prospective customer, sales	Transactional Document
`proposal`	Proposal, tender, statement of work	Present a solution and commercial offer	Customer, procurement committee	Formal Letterhead
`receipt`	Proof of payment	Acknowledge payment received	Customer, payer, finance	Transactional Document
`payment_voucher`	Payment voucher	Authorize and record a payment	Finance, approvers, payee	Transactional Document
`credit_note`	Credit note or credit memo	Reduce an amount owed or refund a customer	Customer, accounts receivable	Transactional Document
`debit_note`	Debit note or debit memo	Increase an amount owed or record a charge	Supplier, customer, accounts payable	Transactional Document
`delivery_note`	Delivery or dispatch note	Confirm goods dispatched and received	Customer, logistics, warehouse	Transactional Document
`statement_of_account`	Customer or account statement	Summarize transactions and balances	Customer, credit control, finance	Financial Statement
`business_letter`	Formal business letter	Communicate a formal business message	Addressee, department, stakeholder	Formal Letterhead
`goods_received_note`	GRN or goods receipt	Record goods received against an order	Warehouse, procurement, supplier	Transactional Document
`purchase_requisition`	Purchase requisition	Request approval to purchase	Department head, procurement, finance	Transactional Document
`contract`	Contract or agreement	Record agreed terms and obligations	Contracting parties, legal, approvers	Formal Letterhead

Business report catalogue

Type code	Typical use	Purpose	Default audience	Template
`executive_report`	Board report, board paper	Concise performance, issues and decisions	Board, executive committee	Executive
`management_report`	Monthly or quarterly report	Performance against plans and actions	Management, department heads	Executive
`financial_report`	Financial report, P&L, cash flow	Financial position and performance	Finance leadership, management, auditors	Financial
`budget_expenditure_report`	Budget report, variance report	Budgeted versus actual expenditure	Finance, budget holders, management	Financial
`audit_report`	Internal or external audit	Audit scope, findings, conclusions	Audit committee, management, governance	Audit and Compliance
`compliance_report`	Compliance or regulatory report	Adherence to laws, regulations and controls	Compliance committee, regulators	Audit and Compliance
`risk_report`	Risk report or risk register	Risk exposure, controls and mitigation	Risk committee, board	Audit and Compliance
`hr_report`	HR, headcount, payroll report	Workforce and people-management information	HR leadership, management	Corporate Professional
`procurement_inventory_report`	Procurement or stock report	Purchasing, stock levels and movement	Procurement, warehouse, operations	Operational
`operational_performance_report`	Operations or department report	Operational output and service levels	Operations management, department heads	Operational

How the recommendation is produced

The report builder and report designer call a deterministic recommender, not the model's free-form judgement.

Identify — score the request against profile names, aliases, purpose, audience and module.
Filter by data source — business-document profiles require a document data source; business-report profiles require a non-document source. If the closest match is incompatible, the best compatible profile is returned with an explanatory note.
Apply overrides — an explicit document type, template, orientation, classification, purpose or audience overrides the profile defaults.
Return guidance — the result contains the document type, category, purpose, audience, confidence, matched terms, template, page settings, recommended sections, document fields, alternatives and notes.
Ask only when needed — when no profile scores strongly or two profiles tie, the result is marked ambiguous and the agent asks one short question. A custom design is offered as an option.

Using it in the Report Builder

Describe the report or document you need. The agent:

Identifies the document type, purpose and audience.
Calls the design catalogue and recommends a design, or asks one short question when the request is ambiguous.
Applies the recommended presentation template, sections, document header fields, line columns and totals.
Validates the draft and proposes it for you to apply.

Example requests:

"Create a sales invoice layout."
"Build a monthly budget and expenditure report."
"Create a statement of account."
"Create a proposal for a customer."

The applied report stores the chosen type, category, purpose, audience and design profile as report metadata. The report designer can read this later.

Using it in the Report Designer

Open a saved report in the report designer and ask for a design recommendation. The designer:

Identifies the document type, purpose and audience from the report record and your request.
Reuses the saved report's existing document type when one is available.
Proposes the presentation template, page header, report header and design metadata.
Leaves the table, data, filters, grouping, sorting, aggregations and calculations unchanged.

The change is still a proposal. You must apply it.

Custom designs

The catalogue is a starting library, not a restriction. When no profile fits, or when you want a different design:

Ask for a custom design.
Optionally name a library profile to base it on.
Describe the purpose, audience and the semantic sections or document fields you need.

The agent builds a per-report custom design from the nearest compatible library profile and records it as a custom design based on that profile. A custom design can:

reuse a library template, page orientation and header layout
add, remove or reorder allowed semantic sections (text, bullets, kpis, table, approval, divider)
choose document header fields, line columns and totals that exist in the data source
use a letter-style layout without a line table

Custom designs are stored per report. They are not saved as reusable templates. To add a reusable type, add a profile to the catalogue in code.

Data source definition

The AI does not define report or dashboard data sources. It can only use sources that already exist and that the user can access.

A developer defines a report data source as a registered report class:

A tabular report class for tabular reports.
A document report class for document reports.
A tabular report with dashboard_enabled = True for dashboard widgets.

The report class must be imported at startup and must pass its output permission. Dashboard data sources are limited to tabular reports in v1.

Canonical developer guides:

Presentation templates and layout modes

Business reports reuse the existing templates:

Corporate Professional
Executive
Financial
Audit and Compliance
Operational
Minimalist

Transactional and formal documents use the new templates:

Transactional Document — invoices, purchase orders, quotations, receipts, vouchers and notes.
Formal Letterhead — business letters, proposals and contracts.
Financial Statement — statements of account and financial documents.

Layout modes:

Mode	Behaviour
`document`	Document header fields, one line table and totals.
`letter`	Narrative letter or contract layout with no line table.
`custom`	Per-report design that may use a table or narrative sections.
empty	Standard tabular report layout.

Design metadata persisted with the report

The chosen recommendation is stored in design_json.settings.reportMeta and in the composition metadata:

Key	Meaning
`documentType`	Catalogue type code, or `custom`.
`documentCategory`	`business_document`, `business_report`, or `custom`.
`documentPurpose`	Purpose used for the design.
`documentAudience`	Intended audience.
`designProfile`	Catalogue profile code, or `custom`.
`designConfidence`	Recommendation confidence.
`basedOnProfile`	Base profile for a custom design.

This metadata survives edits and renders without a database migration.

Agent tools

Tool	Used by	Purpose
`report_list_designs`	Report Builder	List the design catalogue and categories.
`report_recommend_design`	Report Builder	Identify the type, purpose and audience and return a design recommendation, including custom designs.
`report_recommend_definition`	Report Builder	Recommend the data source, columns and composition; the response also includes the design recommendation.
`report_designer_recommend_design`	Report Designer	Recommend a design for the open saved report and propose the template/header/metadata change for user confirmation.

The designer recommendation is always a proposal. Use the normal apply action; the table and query configuration are not changed.

Permissions

Building or recommending a new design requires action.enezareporting.report_create.
Editing a saved design requires action.enezareporting.report_edit.

Page-scoped assistants remain limited to their current module and to authorized data sources.

Deployment and synchronisation

After deploying the code, administrators must seed the new tools and refresh the built-in agents:

bash

python manage.py ai_seed_tools
python manage.py ai_sync_registry

No database migration is required. The catalogue and templates are code-defined, consistent with the existing presentation template system.

A note on testing

Per project rules, the developer or agent does not run or claim test results. The user is solely responsible for all testing and validation of the behavior described in this guide.