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.

Show 'AIGRA' Backend Setup Help

Description

Prints a short guide for configuring the external 'AIGRA' backend.

Usage

aigra_backend_help()

Value

Invisibly returns NULL.

Examples

aigra_backend_help()

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 Assessment Item Clones with Simplified API-Key Handling

Description

A user-friendly wrapper around aigra_generate_tabular_items() that allows users to provide provider API keys directly in R.

Usage

aigra_generate_items(
  file_path,
  model = "gemini-3.1-pro-preview",
  provider = "auto",
  gemini.API = NULL,
  openai.API = NULL,
  groq.API = NULL,
  anthropic.API = NULL,
  backend_path = NULL,
  ...
)

Arguments

Value

A data frame of generated items and review information.

Examples

if (interactive()) {
  out <- aigra_generate_items(
    file_path = "items.xlsx",
    model = "sonnet",
    anthropic.API = "your_key",
    backend_path = "path/to/AIGRA_BACKEND",
    source_language = "English",
    target_language = "English",
    subject = "Mathematics",
    exam = "Demo",
    n_clones = 1,
    max_items = 2
  )
}

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.

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.

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.

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 'AIGRA' API Keys

Description

Sets API keys for supported providers from within R. These environment variables are inherited by the external 'Python' backend when generation functions are called.

Usage

aigra_set_api_keys(
  gemini.API = NULL,
  openai.API = NULL,
  groq.API = NULL,
  anthropic.API = NULL
)

Arguments

Value

Invisibly returns a named logical vector showing which keys are set.

Examples

keys <- aigra_set_api_keys()
is.logical(keys)

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.

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))