Skip to contents

Run AI model on book chapters with a single prompt per simulation

Source: R/run_ai_on_chapters_one_turn.R
run_ai_on_chapters_one_turn.Rd

This function implements a one-turn design where identity context, chapter text, and the rating question are combined into a single prompt. Independent prompts are executed in parallel with ellmer::parallel_chat_structured().

Usage

run_ai_on_chapters_one_turn(
  book_texts,
  groups,
  context_text,
  question_text,
  output_mode = c("structured", "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,
  max_active = 10,
  rpm = 500
)

Arguments

book_texts

A single character (one chapter) or a nested list of books -> chapters as returned by read_book_texts().

groups

Character vector of group labels (length >= 2). These are the groups being compared. Example: c("Democrat", "Republican").

context_text

Character. Either:

  • A scalar template containing {identity}, which will be expanded once for each group.

  • A character vector of length equal to length(groups), where each element is the full context for the corresponding group identity.

question_text

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

output_mode

Character. "structured" (default) uses the backend's structured-output support. "text" is a compatibility mode for models that do not support structured outputs (for example some Anthropic models): nalanda appends strict JSON-only instructions to the prompt, calls the model as free text, then parses the JSON back into the same fields used by the rest of the pipeline. Text mode is best-effort and stores the original model reply in raw_response.

n_simulations

Integer. Number of repeated simulations per chapter per identity.

temperature

Numeric. Sampling temperature passed to the chat backend.

seed

Integer. Random seed for reproducibility. As in run_ai_on_chapters(), the seed varies by simulation index only, so all chapters and identities within the same sim share the same seed.

model

Character. Model name for the chat backend.

integration

Optional Portkey/gateway route slug. If supplied and model is not fully-qualified, nalanda will build "@{integration}/{model}". 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. When both nalanda.integration and nalanda.virtual_key options are set and neither argument is supplied, integration is preferred.

virtual_key

Optional legacy virtual key. If supplied and model is not fully-qualified, nalanda will build "@{virtual_key}/{model}". Use either integration or virtual_key, not both when explicitly supplying function arguments.

base_url

Character. Base URL for API calls.

excerpt_chars

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

max_active

Integer. Maximum number of concurrent requests passed to ellmer::parallel_chat_structured() in structured mode. Text mode runs plain chat requests sequentially.

rpm

Integer. Requests-per-minute cap passed to ellmer::parallel_chat_structured() in structured mode. Text mode runs plain chat requests sequentially.

Value

A tibble of raw single-turn ratings, or a named list of tibbles (one per book). Each row is one rating observation and includes chapter, sim, identity, turn_index, turn_type, target_group, and rating, plus prompt and metadata columns. Use compute_run_ai_metrics_one_turn() to derive chapter-level one-turn summaries.