---
title: "AI-Optimized Reports"
output:
  rmarkdown::html_vignette:
    toc: true
    fig_width: 10.08
    fig_height: 6
tags: [r, report, AI, LLM]
vignette: >
  %\VignetteIndexEntry{AI-Optimized Reports}
  \usepackage[utf8]{inputenc}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

```{r setup, echo=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE
)
```

## How to Use `report()` and get AI-Optimized Output

### The *"last statistical mile"*

The **report** package was originally designed in a pre-AI era with one overarching goal: to produce human-readable prose. It was built to bridge the scientist's *"last statistical mile"*: that final, often tedious transition from the raw output of statistical software to the polished, written sentences of a manuscript. To achieve this, we leveraged the power **easystats**'s ecosystem to automatically and flexibly extract relevant information to engineer text with very specific characteristics: the output had to be **deterministic**, perfectly **consistent**, and adhere to fixed **reporting norms** (such as APA style). By automating this translation, our aim was to facilitate **fully reproducible research** (enabling reproducible *manuscripts*) and drastically reduce human error. Ultimately, this allowed us to shift the focus of **statistics education** away from memorizing where to find the right numbers and how to format them, empowering researchers to focus entirely on how to interpret and use those numbers to answer their research questions.

### *easystats* in the Age of AI

However, the analytical landscape has fundamentally changed. Today, researchers increasingly rely on AI agents and Large Language Models (LLMs) to help interpret results, summarize findings, and draft manuscripts, often by simply **pasting raw outputs directly into a chat window**. This shift prompted us to ask: should the scope of the *report* package be expanded to **support** this new workflow, rather than pretending it doesn't exist? And it wasn't even a matter of staying relevant, it was a matter of empowering our users to get the best possible results from their new AI assistants. 

While our standard narrative outputs are excellent for humans, they are remarkably suboptimal for AI: verbose prose forces an LLM to waste valuable context tokens re-parsing implicit structures, wasting tokens and context memory. The answer to this challenge is `report_ai()`, a function that can be triggered via an argument from the main `report()` function. By stripping away the narrative bloat in favour of highly structured, token-efficient formats, `report_ai()` bridges the gap between R and the context window, giving your AI assistant exactly the information it needs in the most effective way possible.

## Basic Usage

```{r}
library(report)

m <- lm(mpg ~ wt + hp, data = mtcars)

# Human-readable report (default)
report(m)
```

```{r}
# AI-optimized report
report(m, audience = "ai")
```

The AI output is a single character vector of class `report_ai` that you can
pass directly to any LLM API, embed in a system prompt, or include in a
context window.

## Setting the Option Globally

For a single analysis session or a whole document you can flip **all** `report()`
calls at once with one option:

```{r eval=FALSE}
options(report_audience = "ai")

# Every subsequent report() call now returns an AI-optimized output
report(m)
report(lm(mpg ~ am, data = mtcars))
```

Reset to the default at any time:

```{r eval=FALSE}
options(report_audience = "humans")
```

## Converting a Quarto Document

If you have an existing Quarto (`.qmd`) or R Markdown (`.Rmd`) document that
already uses `report()` throughout, converting it to produce AI-optimized
output requires only **one line** added to the `setup` chunk:

````{verbatim}
---
title: "My Analysis"
format: html
---

```{r setup, include=FALSE}
library(report)

# One line — all report() calls in this document become AI-optimised
options(report_audience = "ai")
```

```{r model}
m <- lm(mpg ~ wt + hp, data = mtcars)
report(m)   # automatically AI-optimised because of the global option
```
````

To make the option permanent across an entire Quarto project, add it to the
project-level `_quarto.yml` execute block or to your `.Rprofile`.