create-report

Create Report

End-to-end workflow for creating a data-driven report using Motley.

Overview

Motley helps to create reports based on the user's data and requirements.

A report in Motley is a document consisting of blocks (markdown text, tables, and charts). Blocks can reference data queries, other blocks, and context variables.

The report creation workflow has 3 phases:

1. Research & Plan — understand the user's needs & the relevant data
2. Creating a document in Motley – based on the research, write the report content into a document
3. Output and iteration – show the report to the user, ask for feedback, and iterate until it's ready

The end result of the workflow is a document in Motley (can be opened via link) and, secondarily, a Markdown export of it.

---

Phase 1: Research & Plan

Enter plan mode.

Make sure you understand why the user wants to create this report, what exactly they want to show.

Explore Models

Data is central to the report generation. It can be used both for charts and inline queries embedded in the text.

The purpose of this step is to find the relevant data for the queries and charts that should be in the report. Data is represented as models (data models), containing measures and dimensions, that can be queried.

Understand what models are available:

models_summary()

Then inspect relevant models to see measures, dimensions, and sample data:

inspect_model(model_name="revenue", num_rows=3)
inspect_model(model_name="customers", num_rows=3)

If the existing models don't have the data you need, you can create custom models from SQL (create_model), or add computed measures/dimensions to existing models (edit_model). See the explore-model skill for details.

Ask questions

Until it's completely clear what the user wants, ask them questions.

If it's unclear from where the data should come, ask them to point exactly.

If anything about the data is ambiguous, ask them for clarification, also listing the possible options.

---

Phase 2: Create a document in Motley

A document is a flat sequence of text (Markdown) blocks, table blocks, and charts. Text and table blocks can reference queries.

To create a document, use the create_document tool:

create_document(
    name="<descriptive name>",
    source_id=<source_id>
)

You need to provide the source_id of the models you are going to use. Currently, all the models in a document must come from a single source. The source_id can be found in outputs of models_summary and inspect_model tools.

Set Context Variables

Documents have global variables substituted into queries (filters) and text blocks ({var_name}) at resolution time. Use them for anything that might change on a re-run (customer, region, etc.) so the report can be regenerated by swapping values.

Required variables:

• start_date / end_date — always required (used by query time filtering); often it's all you need
• Source-specific variables from parametrized default filters — required when the source declares them

Available/required variables appear in create_document response and in get_doc_variables response. New variables can also be created as needed.

set_doc_variables(
    doc_id=<id>,
    variables={"start_date": "2025-01-01", "end_date": "2025-12-31", "foo": "bar"}
)

Merges with existing values and re-resolves all blocks. Only provide keys you want to change.

Create Blocks

Creating blocks and updating them is done using the tools:

• update_text_block
• update_table_block
• update_chart_block
• update_query_block

Each block must have a unique name by which it can be referenced. To create a new block provide a new, unique name.

Chart Blocks

update_chart_block(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<chart_block>"},
    query={
        measures: [{name: "total_revenue", cube_name: "revenue"}],
        time_dimension: {
            dimension: {name: "created_at", cube_name: "revenue"},
            granularity: "month"
        },
        limit: 12,
        order: [{column: {name: "created_at", cube_name: "revenue"}, order: "ASC"}]
    },
    chart_details={
        series_default: {type: "LINE", y_axis: "left", number_format: {style: "currency"}, show_values: false},
        x_axis: {lines: false, label: false},
        y_axis: {lines: true, label: "Revenue"},
        y_right_axis: {lines: false},
        title: "Monthly Revenue"
    }
)

Then verify:

render_chart(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<chart_block>"}
)

See the update-chart skill for chart type guidance and configuration patterns.

Text Blocks

First create query blocks for the data:

update_query_block(
    location={doc_id: <id>, slide_name: "<slide>", parent_block: "<text_block>"},
    query_name="<name>",
    query={<query_config>}
)

Then set the template:

update_text_block(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<text_block>"},
    user_prompt="<template with {variables}>",
    call_llm=<true/false>
)

Verify the text block by checking the returned content. See the update-text-block skill for template syntax and modes.

Table Blocks

Same pattern as text — create query blocks first, then set the template:

update_query_block(
    location={doc_id: <id>, slide_name: "<slide>", parent_block: "<table_block>"},
    query_name="<name>",
    query={<query_config>},
    mode="table"
)

update_table_block(
    location={doc_id: <id>, slide_name: "<slide>", block_name: "<table_block>"},
    user_prompt="{<query_name>}"
)

See the update-table-block skill for table patterns.

---

Phase 3: Output and iteration

Export as Markdown and review

Export the document to markdown format:

export_document(document_id=<id>, format="markdown", mode="table")

This will embed the data for the charts as markdown tables, with chart metadata next to them.

Check the output carefully. Does it look as expected? If not, go back and update the blocks.

Render for the user

Show the user the rendered document as markdown. Show a button to open the document in Motley. Ask the user for feedback.

If the user wants to make changes, understand the feedback and go back and update the blocks, then render again.

The Motley document is the result of this workflow.

(Optional) Export to another format

On user request, export the report to the user's preferred format.

If available, you can use the frontend-slides skill to create a presentation using the content of the document.