Run AI model on books with cumulative chapter context

This function implements a cumulative multi-turn design where each simulation creates one persistent chat per book and identity. The chat first establishes a baseline, then processes chapters sequentially in order, one turn per chapter, preserving context across the full book.

Usage

run_ai_cumulative_chapters(
  book_texts,
  groups,
  context_text,
  question_text,
  n_simulations = 1,
  temperature = 0,
  seed = 42,
  model = "gemini-2.5-flash-lite",
  integration = getOption("nalanda.integration"),
  virtual_key = getOption("nalanda.virtual_key"),
  base_url = getOption("nalanda.base_url"),
  excerpt_chars = 200
)

Arguments

book_texts

A nested list of books -> chapters as returned by read_book_texts().

groups

Character vector of group labels (length >= 2).

context_text

Character. Either a scalar template containing {identity} or a character vector of length length(groups).

question_text

Character scalar. A question template containing the placeholder {group}, which will be replaced with each group label.

n_simulations

Integer. Number of repeated simulations per book per identity.

temperature

Numeric. Sampling temperature passed to the chat backend.

seed

Integer. Random seed for reproducibility (incremented for each simulation).

model

Character. Model name for the chat backend.

integration

Optional Portkey/gateway route slug. Use a route returned by ellmer::models_portkey(base_url = "https://ai-gateway.apps.cloud.rt.nyu.edu/v1/") when working with the NYU gateway.

virtual_key

Optional legacy virtual key.

base_url

Character. Base URL for API calls.

excerpt_chars

Integer. Number of chapter characters to retain in the stored prompt previews shown in results.

Value

A tibble or named list of tibbles with cumulative turn-level rows. The baseline turn is followed by one post turn per chapter, all within the same chat per book/identity/simulation.

Examples

if (FALSE) { # \dontrun{
raw_cumulative <- run_ai_cumulative_chapters(
  book_texts = list(
    "Book A" = list(
      chapter_1 = "A first chapter about cooperation.",
      chapter_2 = "A second chapter about conflict and repair."
    )
  ),
  groups = c("Democrat", "Republican"),
  context_text = "You are simulating an American adult who politically identifies as a {identity}.",
  question_text = "On a scale from 0 to 100, how warmly do you feel towards {group}s?",
  n_simulations = 1,
  temperature = 0,
  seed = 42
)

compute_run_ai_metrics_cumulative(raw_cumulative)
} # }