Package {AIGRA}

Apply AIGRA Diagram Agent to generated results

Description

Inspects generated items and automatically sets diagram_required and diagram_prompt when a visual diagram is likely needed.

Usage

aigra_apply_diagram_agent(result, overwrite_prompt = FALSE)

Arguments

Value

Updated result data frame.

Get AIGRA backend path

Description

Returns the configured AIGRA Python backend path.

Usage

aigra_backend_path()

Details

AIGRA first checks the active session configuration. If no backend has been set in the current R session, it checks the AIGRA_BACKEND_PATH environment variable.

Value

Backend path as a character string.

Build a safe diagram prompt from an item stem

Description

Build a safe diagram prompt from an item stem

Usage

aigra_build_diagram_prompt(
  stem,
  option_A = "",
  option_B = "",
  option_C = "",
  option_D = ""
)

Arguments

Value

A diagram-generation prompt.

Build a diagram prompt from a result row

Description

Build a diagram prompt from a result row

Usage

aigra_build_diagram_prompt_from_row(result, row = 1)

Arguments

Value

A diagram prompt.

Create source diagrams for the AIGRA multimodal template

Description

Create source diagrams for the AIGRA multimodal template

Usage

aigra_create_sample_source_diagrams(diagram_dir)

Arguments

Value

Named character vector of diagram paths.

Detect whether an item likely requires a diagram

Description

Uses rule-based visual triggers in the item stem, topic, objective, and options.

Usage

aigra_detect_diagram_required(stem, topic = "", objective = "", options = "")

Arguments

Value

TRUE or FALSE.

Get path to bundled AIGRA example item bank

Description

Get path to bundled AIGRA example item bank

Usage

aigra_example_item_bank()

Value

Path to the bundled example CSV item bank.

Find uv executable

Description

Find uv executable

Usage

aigra_find_uv()

Value

Path to uv executable.

Generate a single AIGRA diagram from a prompt

Description

Generate a single AIGRA diagram from a prompt

Usage

aigra_generate_diagram(
  prompt,
  output_path,
  provider = "gemini",
  model = "gemini-2.5-flash-image",
  size = "1024x1024"
)

Arguments

Value

Output path.

Generate a diagram with fallback image models

Description

Tries multiple image-generation models in order until one succeeds.

Usage

aigra_generate_diagram_fallback(
  prompt,
  output_path,
  provider = "gemini",
  models = c("gemini-2.5-flash-image", "gemini-3.1-flash-image-preview",
    "gemini-3-pro-image-preview"),
  size = "1024x1024"
)

Arguments

Value

Output path.

Generate and review assessment items

Description

Runs the AIGRA Python backend pipeline to generate, solve, review, and export assessment items.

Usage

aigra_generate_items(
  pdf_path = NULL,
  target_language = "English",
  n_clones = 1,
  max_items = 1,
  provider = "gemini",
  model = "gemini-3.1-pro-preview",
  source_language = "Russian",
  review_language = "English",
  subject = "Physics",
  exam = "Kazakhstan UNT",
  read_csv = TRUE
)

Arguments

Value

A data frame if read_csv is TRUE; otherwise invisibly returns latest CSV path.

Generate multimodal items from a tabular item bank

Description

Runs item generation and diagram generation in one workflow.

Usage

aigra_generate_multimodal_tabular_items(
  file_path,
  provider = "gemini",
  model = "gemini-3.1-pro-preview",
  image_provider = "gemini",
  image_model = "gemini-3-pro-image-preview",
  source_language = "English",
  target_language = "English",
  subject = "General",
  exam = "AIGRA Multimodal Item Bank",
  n_clones = 1,
  max_items = NULL,
  max_images = NULL,
  write_reports = TRUE,
  include_key = TRUE,
  only_accepted = TRUE
)

Arguments

Details

Text-only items are generated normally. Items that require diagrams are processed through the Source Diagram Agent and Clone Diagram Agent.

Value

A list containing result, result_with_diagrams, report_path, admin_file, and student_file.

Generate diagrams for rows in an AIGRA result

Description

Generates diagram images for result rows and returns the updated data frame with diagram_path, diagram_prompt, image_provider, and image_model columns.

Usage

aigra_generate_result_diagrams(
  result,
  output_dir = NULL,
  provider = "gemini",
  model = "gemini-2.5-flash-image",
  rows = NULL,
  only_required = TRUE,
  force = FALSE,
  max_images = 1,
  overwrite = FALSE
)

Arguments

Value

Updated result data frame.

Generate diagrams using the AIGRA Diagram Agent

Description

Applies the Diagram Agent, then generates diagrams for rows marked as requiring diagrams.

Usage

aigra_generate_result_diagrams_auto(
  result,
  provider = "gemini",
  model = "gemini-3-pro-image-preview",
  rows = NULL,
  max_images = 3,
  overwrite = FALSE
)

Arguments

Value

Updated result data frame with diagram paths.

Generate items from a tabular item bank

Description

Runs the AIGRA generation, solver, critic, and export pipeline using a CSV or Excel item bank.

Usage

aigra_generate_tabular_items(
  file_path,
  provider = "gemini",
  model = "gemini-3.1-pro-preview",
  source_language = "English",
  target_language = "English",
  review_language = "English",
  subject = "General",
  exam = "Item Bank",
  n_clones = 1,
  max_items = NULL,
  output_dir = NULL,
  read_csv = TRUE
)

Arguments

Value

A data frame if read_csv is TRUE; otherwise invisibly returns the CSV path.

List supported AIGRA image models

Description

Returns the image model registry known to AIGRA. This function is CRAN-safe and does not call external APIs or require the Python backend.

Usage

aigra_image_models(provider = NULL)

Arguments

Value

Supported image models.

Get latest AIGRA CSV output path

Description

Get latest AIGRA CSV output path

Usage

aigra_latest_csv()

Value

Path to latest CSV output.

Get latest AIGRA CSV output path

Description

Get latest AIGRA CSV output path

Usage

aigra_latest_output()

Value

Path to the latest AIGRA CSV output.

List AIGRA output files

Description

Lists generated CSV and JSONL files from the backend output directory.

Usage

aigra_list_outputs()

Value

A data frame of output files.

Localize AIGRA diagram prompts

Description

Adds a language instruction to diagram prompts so generated diagrams use the target language for visible labels.

Usage

aigra_localize_diagram_prompts(result, target_language = "English")

Arguments

Value

Updated result data frame.

Create AIGRA multimodal template items

Description

Create AIGRA multimodal template items

Usage

aigra_multimodal_template_items(diagram_dir = NULL, create_diagrams = TRUE)

Arguments

Value

A data frame containing multimodal sample items.

AIGRA output directory

Description

AIGRA output directory

Usage

aigra_output_dir()

Value

Path to the backend output directory.

List AIGRA output files

Description

List AIGRA output files

Usage

aigra_outputs(pattern = "aigra(_tabular)?_results_.*\\.(csv|jsonl)$")

Arguments

Value

A data frame of output files.

Parse assessment items from a PDF

Description

Parses a supported assessment-item PDF through the AIGRA Python backend and returns a data frame of source items.

Usage

aigra_parse_items(
  pdf_path = NULL,
  source_language = "Russian",
  subject = "Physics",
  exam = "Kazakhstan UNT"
)

Arguments

Value

A data frame of parsed assessment items.

Parse tabular item bank

Description

Parses a CSV or Excel item bank directly from the supplied file path.

Usage

aigra_parse_tabular_items(
  file_path,
  source_language = "English",
  subject = "General",
  exam = "Item Bank"
)

Arguments

Value

A data frame of parsed assessment items.

Plot an AIGRA diagram image

Description

Plot an AIGRA diagram image

Usage

aigra_plot_diagram(image_path)

Arguments

Value

Invisibly returns the image path.

Plot AIGRA output quality summary

Description

Creates a simple bar chart of item review statuses in an AIGRA output.

Usage

aigra_plot_summary(data = NULL)

Arguments

Value

Invisibly returns the status table used for plotting.

Print an AIGRA quality summary

Description

Prints a compact quality summary for an AIGRA output.

Usage

aigra_print_summary(data = NULL)

Arguments

Value

Invisibly returns the summary list.

Examples

result <- data.frame(
  status = c('ok', 'edited', 'reject'),
  solver_matches_key = c(TRUE, TRUE, FALSE),
  stringsAsFactors = FALSE
)
aigra_print_summary(result)

Print tabular item-bank validation results

Description

Print tabular item-bank validation results

Usage

aigra_print_validation(validation)

Arguments

Value

Invisibly returns the validation object.

Examples

validation <- list(
  summary = list(file = 'items.csv', rows = 1, issue_count = 0),
  valid = TRUE,
  missing_required_columns = character(),
  unknown_columns = character(),
  issues = data.frame()
)
aigra_print_validation(validation)

Show AIGRA Python environment information

Description

Show AIGRA Python environment information

Usage

aigra_python_info(backend_path = NULL)

Arguments

Value

A list with Python environment information.

Examples

info <- aigra_python_info(backend_path = tempdir())
is.list(info)

Read latest AIGRA CSV output

Description

Read latest AIGRA CSV output

Usage

aigra_read_latest_csv()

Value

A data frame containing the latest AIGRA CSV output.

Read latest AIGRA CSV output

Description

Read latest AIGRA CSV output

Usage

aigra_read_latest_output()

Value

A data frame containing the latest AIGRA CSV output.

Repair diagram prompts for diagram-dependent AIGRA results

Description

Strengthens diagram prompts when a generated item requires a figure but the prompt is too vague for solving/review.

Usage

aigra_repair_diagram_prompts(result)

Arguments

Value

Updated result data frame.

Set the AIGRA Python backend

Description

Connects the R package to the AIGRA Python backend.

Sets the path to the AIGRA Python backend.

Usage

aigra_set_backend(backend_path = NULL)

aigra_set_backend(backend_path = NULL)

Arguments

Value

Invisibly returns backend configuration.

Invisibly returns the normalized backend path.

Show a diagram from an AIGRA result row

Description

Show a diagram from an AIGRA result row

Usage

aigra_show_result_diagram(result, row = 1)

Arguments

Value

Invisibly returns the image path.

Check AIGRA backend status

Description

Checks whether the R package can access the Python backend.

Usage

aigra_status(backend_path = NULL)

Arguments

Value

A list containing backend path, Python path, Python version, and import status.

Summarise an AIGRA output

Description

Summarises the latest or supplied AIGRA CSV output.

Usage

aigra_summarise_output(data = NULL)

Arguments

Value

A list with quality counts and simple rates.

Create an AIGRA tabular item-bank template

Description

Creates a sample item-bank data frame with the required columns for CSV/Excel-based AIGRA generation.

Usage

aigra_template_items()

Value

A data frame containing sample item-bank rows.

Translate/localize AIGRA diagram prompts using an LLM

Description

This rewrites diagram prompts into the target language before image generation. Scientific symbols and units are preserved.

Usage

aigra_translate_diagram_prompts(
  result,
  target_language = "English",
  provider = "gemini",
  model = "gemini-3.1-pro-preview"
)

Arguments

Value

Updated result data frame.

Use AIGRA backend

Description

Backward-compatible alias for aigra_set_backend().

Usage

aigra_use_backend(backend_path = NULL)

Arguments

Value

Invisibly returns backend path.

Validate a tabular AIGRA item bank

Description

Checks a CSV or Excel item bank before parsing or generation.

Usage

aigra_validate_tabular_items(file_path)

Arguments

Value

A list containing validation status, issues, and a summary.

Write an AIGRA administration HTML file

Description

Creates a print-ready HTML file containing generated item stems, diagrams, response options, and an answer key.

Usage

aigra_write_admin_html(
  result,
  file = NULL,
  title = "AIGRA Generated Assessment Items",
  include_key = TRUE,
  include_metadata = FALSE,
  only_accepted = TRUE
)

Arguments

Value

Path to the HTML file.

Examples

result <- data.frame(
  original_id = 'ITEM001',
  clone_stem = 'What is 2 + 3?',
  opt_A = '4',
  opt_B = '5',
  opt_C = '6',
  opt_D = '7',
  correct_answer = 'B',
  status = 'ok',
  stringsAsFactors = FALSE
)
html <- aigra_write_admin_html(
  result,
  file = tempfile(fileext = '.html'),
  include_key = TRUE,
  only_accepted = FALSE
)
file.exists(html)

Write an AIGRA multimodal Excel template

Description

Creates source diagram PNGs and writes a ready-to-run Excel item bank.

Usage

aigra_write_multimodal_template_excel(
  file = NULL,
  diagram_dir = NULL,
  overwrite = FALSE
)

Arguments

Value

Path to the Excel file.

Write an AIGRA HTML report

Description

Writes a CRAN-safe local HTML report from an AIGRA result data frame. If diagram_path is present, generated diagrams are shown inline.

Usage

aigra_write_report(result = NULL, file = NULL, title = "AIGRA Quality Report")

Arguments

Value

Path to the report.

Write an AIGRA CSV item-bank template

Description

Write an AIGRA CSV item-bank template

Usage

aigra_write_template_csv(file = "aigra_item_template.csv", overwrite = FALSE)

Arguments

Value

The normalized output file path.

Write an AIGRA Excel item-bank template

Description

Write an AIGRA Excel item-bank template

Usage

aigra_write_template_excel(
  file = "aigra_item_template.xlsx",
  overwrite = FALSE
)

Arguments

Value

The normalized output file path.

Ensure 'AIGRA' 'Python' Environment

Description

Creates or repairs the 'Python' virtual environment used by the 'AIGRA' backend.

Usage

ensure_aigra_python(
  backend_path = NULL,
  python_version = "3.11",
  force = FALSE,
  install_providers = TRUE,
  verbose = FALSE
)

Arguments

Value

A list with 'Python' environment information.

Examples

# This function creates or repairs a backend environment,
# so the example only inspects the function interface.
names(formals(ensure_aigra_python))