Package {LLMR.shiny}

LLMR.shiny: Shared 'Shiny' Components for 'LLMR' Family Applications

Description

Reusable 'Shiny' user interface and server components from which the graphical applications in the 'LLMR' package family are assembled.

Author(s)

Maintainer: Ali Sanaei sanaei@uchicago.edu

See Also

Useful links:

• https://github.com/asanaei/LLMR.shiny

• Report bugs at https://github.com/asanaei/LLMR.shiny/issues

Mark a result frame as demonstration output

Description

Marks a result produced without a live model: a run_mode column set to "demo", a demo_notice column, and the llmrshiny_demo_result class that is_demo_result() tests and demo_banner_ui() announces. demo_runner() applies it automatically; call it directly for demonstration results built some other way.

Usage

annotate_demo_result(x)

Arguments

Value

x with the two source columns and the demonstration class added.

Examples

annotate_demo_result(data.frame(response_text = "stub"))

Coerce an arbitrary result to a display table

Description

Data frames and matrices pass through (head-limited). For a list, name the component to display. Anything else becomes a one-column capture of its structure.

Usage

as_display_table(x, max_rows = 500L, component = NULL, digits = 3L)

Arguments

Value

A data frame.

Examples

x <- data.frame(
  item_id = c(1000001, 1000002),
  share = c(0.123456, 0.987654),
  count = c(3L, 7L)
)
as_display_table(x)

Build an LLM config

Description

Build an LLM config

Usage

build_llm_config(
  provider,
  model,
  ...,
  temperature = NULL,
  max_tokens = NULL,
  reasoning_effort = NULL
)

Arguments

Value

An LLMR::llm_config.

Build an execution function for a mode

Description

Build an execution function for a mode

Usage

build_runner(mode, responder = NULL)

Arguments

Value

A callable function that accepts a request data frame.

Column names of a data frame, for a mapping select input

Description

Column names of a data frame, for a mapping select input

Usage

column_names_for_mapping(data)

Arguments

Value

A character vector of column names.

Error category of a caught condition

Description

LLMR's classed errors carry their category in the condition class (llmr_api_auth_error, llmr_api_rate_limit_error, and so on); the class is read first. A plain category field or attribute is honored as a fallback for conditions built by other tools.

Usage

condition_category(e)

Arguments

Value

A length-1 character category (e.g. "auth", "rate_limit", "param", "server", "unknown"), or NA.

A banner announcing a demonstration result

Description

A banner announcing a demonstration result

Usage

demo_banner_ui()

Value

A warning card.

Demo-result notice string

Description

Demo-result notice string

Usage

demo_notice()

Value

The marker text stamped on every demo result.

An offline demonstration response function

Description

Returns a function accepted by .runner arguments. It adds LLMR response columns to a request data frame. The per-row response text is decided by responder, a function (text) -> character. Results are marked as demonstrations.

Usage

demo_runner(
  responder = NULL,
  text_cols = c("text", "unit", "document", "prompt", "input")
)

## S3 method for class 'llmrshiny_demo_result'
print(x, ...)

Arguments

Value

A response function of class llmrshiny_demo_runner.

Render an object's diagnostics() as a display table

Description

Render an object's diagnostics() as a display table

Usage

diagnostics_table(x, ...)

Arguments

Value

A data frame, or NULL when no method applies.

Extract call/token counts from a result frame

Description

Extract call/token counts from a result frame

Usage

extract_token_counts(x, fallback_calls = 0L)

Arguments

Value

A list with token totals and either calls, when explicit call provenance is available, or result_rows.

Guess a column for a data-mapping role

Description

Column names are matched without regard to case or common separators. When no recognized name remains, the first available column is returned. Text names include text, body, content, response, message, and utterance; label names include label, labels, code, category, and class; identifier names include id, doc_id, and unit_id.

Usage

guess_column(cols, kind = c("text", "label", "id"), exclude = character())

Arguments

Value

One column name as a character vector of length one, or NULL when no column remains.

Examples

cols <- c("id", "text", "label")
text_col <- guess_column(cols, "text")
guess_column(cols, "label", exclude = text_col)

Inline help tooltip

Description

Inline help tooltip

Usage

help_tip(text, placement = "right")

Arguments

Value

A focusable information icon wrapped in a bslib tooltip.

Examples

shiny::tags$label(
  "Turn-taking flow",
  help_tip("How the next speaker is chosen.")
)

Install-guidance card for a missing package

Description

Install-guidance card for a missing package

Usage

install_guidance_ui(package, title = package)

Arguments

Value

A bslib::card with an installation command.

Is a result a demonstration result?

Description

Is a result a demonstration result?

Usage

is_demo_result(x)

Arguments

Value

TRUE when the result has the demonstration class or source fields.

Key state for a provider, read from the environment only

Description

Never returns the key value; only whether one was found and in which variable.

Usage

key_state(provider)

Arguments

Value

A list: provider, display, env_vars, found, env_var.

A tile reporting key state (never the key value)

Description

A tile reporting key state (never the key value)

Usage

key_state_tile(state)

Arguments

Value

A bslib value box or warning card.

A banner shown when a live run is blocked for want of a key

Description

A banner shown when a live run is blocked for want of a key

Usage

live_run_blocker_ui(state)

Arguments

Value

A warning card.

Shared theme for an LLMR studio

Description

The family theme uses a common Bootstrap palette and a studio accent only for the active navigation underline.

Usage

llmr_theme(studio = c("content", "panel", "focus"), ...)

Arguments

Value

A Bootstrap 5 bslib theme.

Examples

theme <- llmr_theme("content")
if (interactive()) {
  shiny::shinyApp(
    bslib::page_navbar(
      bslib::nav_panel("Home", "Demo"),
      title = "LLMRcontent",
      theme = theme
    ),
    function(input, output, session) {}
  )
}

Map user columns to text (and optionally labels)

Description

Map user columns to text (and optionally labels)

Usage

map_columns(data, text_col, label_col = NULL, keep_original = TRUE)

Arguments

Value

A data frame with a text column (and labels when requested), always with one row per input row.

Server for the persona selector module

Description

Renders a compact overview of data as a multi-select table, reports the live selected-row count, and returns the selected row indices (relative to data) as a reactive. When data carries the persona contract (see LLMR::llm_persona_overview()), the overview columns are chosen automatically; otherwise the first few columns are shown.

Usage

persona_selector_server(
  id,
  data,
  overview = NULL,
  page_length = 8L,
  height = "260px",
  empty_selection_note = "A seeded sample of the requested size will be drawn."
)

Arguments

Value

A reactive returning an integer vector of selected row indices into data (integer(0) when nothing is selected). When DT is not installed the module renders nothing and the reactive is always integer(0), matching the install guidance shown by persona_selector_ui().

See Also

persona_selector_ui().

UI for the persona selector module

Description

Renders the selectable persona table. Pair with persona_selector_server(). The table's height is set by the height argument of persona_selector_server(), which controls the scrollable body.

Usage

persona_selector_ui(id)

Arguments

Value

Shiny UI elements for a live selection count and a DT output.

See Also

persona_selector_server().

Provider choices for a select input

Description

Provider choices for a select input

Usage

provider_choices()

Value

A named character vector (display -> provider).

Default model for a provider

Description

Default model for a provider

Usage

provider_default_model(provider)

Arguments

Value

The default model string, or "" for an unknown provider.

Display name for a provider

Description

Display name for a provider

Usage

provider_display_name(provider)

Arguments

Value

The display name, or the provider id.

Environment-variable names a provider's key may live in

Description

Environment-variable names a provider's key may live in

Usage

provider_env_vars(provider)

Arguments

Value

A length-2 character vector c("<P>_API_KEY", "<P>_KEY").

Provider registry

Description

The registry supplies a working default model for each provider. Set the LLMR.shiny.default_models option to a named character vector to replace selected defaults without changing the others.

Usage

provider_registry(
  default_models = getOption("LLMR.shiny.default_models", character())
)

Arguments

Details

Built-in defaults are ⁠openai/gpt-oss-20b⁠ for Groq and Together, ⁠gpt-4o-mini⁠ for OpenAI, claude-haiku-4-5 for Anthropic, deepseek-v4-flash for DeepSeek, and gemini-3.1-flash-lite for Gemini.

Value

A data frame of provider, display, and default_model.

Read a CSV from a path

Description

Read a CSV from a path

Usage

read_csv_path(path)

Arguments

Value

A data frame.

Read an uploaded CSV (a Shiny fileInput value)

Description

Read an uploaded CSV (a Shiny fileInput value)

Usage

read_csv_upload(file)

Arguments

Value

A data frame.

Render an object's report() prose, falling back to print output

Description

Render an object's report() prose, falling back to print output

Usage

report_text(x, ...)

Arguments

Value

A character scalar of report text.

Run an expression, capturing any error as a banner

Description

Evaluates expr; on error returns a list with ok = FALSE and a ready-made ui banner (auth-aware) instead of stopping. On success returns ok = TRUE and the value.

Usage

safe_llmr_call(expr, provider = NULL)

Arguments

Value

list(ok, value, error, ui).

Wire the standard sidebar and return the shared reactive context

Description

Call once at the top of a GUI's server with the top-level input, output, session. It keeps the model field in sync with the provider, renders the key and usage tiles, tracks usage, and returns a list of reactives and mutators (provider, model, mode, temperature, max_tokens, reasoning_effort, key, can_run, set_plan, add_usage) for the per-package modules to consume.

Usage

shell_context(input, output, session)

Arguments

Value

A shared-context list.

The standard GUI sidebar: mode, live configuration, and usage

Description

The standard GUI sidebar: mode, live configuration, and usage

Usage

shell_sidebar(
  id = NULL,
  default_provider = "groq",
  max_tokens_help = "Leave blank to use the model default.",
  max_tokens_placeholder = "Model default"
)

Arguments

Value

A bslib::sidebar.

Output container for long text results

Description

Output container for long text results

Usage

text_block_output(id, height = "18rem")

Arguments

Value

A bordered, scrollable Shiny output container.

Examples

text_block_output("report")

Add realized usage to a usage record

Description

Add realized usage to a usage record

Usage

usage_add(state, tokens)

Arguments

Value

The updated usage record.

An empty usage record

Description

An empty usage record

Usage

usage_empty()

Value

A list with zeroed counters.

Record a planned run on a usage record

Description

Record a planned run on a usage record

Usage

usage_set_plan(state, calls, label = "Next run")

Arguments

Value

The updated usage record.

A value box reporting session usage

Description

A value box reporting session usage

Usage

usage_tile(state)

Arguments

Value

A bslib::value_box.

Validate a column mapping

Description

Validate a column mapping

Usage

validate_column_mapping(data, text_col, label_col = NULL)

Arguments

Value

TRUE, or an error.