| Title: | Agentic Item Generation, Review, and Analysis |
|---|---|
| Description: | Provides tools for validating, generating, reviewing, reporting, and visualising assessment item generation workflows. The package supports tabular item-bank templates, item-bank validation, 'Python'-backed agentic generation workflows, multimodal diagram generation, quality summaries, and 'HTML' reporting. External artificial intelligence services and related 'API' calls require user-supplied credentials and are not called during package checks. The workflow is informed by automatic item generation methods described by Gierl and Haladyna (2013, ISBN:9780415897518) and evidence-centered assessment design described by Mislevy et al. (2003) <doi:10.1002/j.2333-8504.2003.tb01908.x>. |
| Authors: | Moses O. Omopekunola [aut, cre] |
| Maintainer: | Moses O. Omopekunola <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.2 |
| Built: | 2026-06-05 14:40:14 UTC |
| Source: | https://github.com/cran/AIGRA |
Inspects generated items and automatically sets diagram_required and diagram_prompt when a visual diagram is likely needed.
aigra_apply_diagram_agent(result, overwrite_prompt = FALSE)aigra_apply_diagram_agent(result, overwrite_prompt = FALSE)
result |
A data frame returned by AIGRA. |
overwrite_prompt |
If TRUE, replace existing diagram prompts. |
Updated result data frame.
Prints a short guide for configuring the external 'AIGRA' backend.
aigra_backend_help()aigra_backend_help()
Invisibly returns NULL.
aigra_backend_help()aigra_backend_help()
Returns the configured AIGRA Python backend path.
aigra_backend_path()aigra_backend_path()
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.
Backend path as a character string.
Build a safe diagram prompt from an item stem
aigra_build_diagram_prompt( stem, option_A = "", option_B = "", option_C = "", option_D = "" )aigra_build_diagram_prompt( stem, option_A = "", option_B = "", option_C = "", option_D = "" )
stem |
Item stem. |
option_A |
Option A. |
option_B |
Option B. |
option_C |
Option C. |
option_D |
Option D. |
A diagram-generation prompt.
Build a diagram prompt from a result row
aigra_build_diagram_prompt_from_row(result, row = 1)aigra_build_diagram_prompt_from_row(result, row = 1)
result |
A data frame returned by AIGRA. |
row |
Row number. |
A diagram prompt.
Create source diagrams for the AIGRA multimodal template
aigra_create_sample_source_diagrams(diagram_dir)aigra_create_sample_source_diagrams(diagram_dir)
diagram_dir |
Directory where source diagram PNG files should be saved. |
Named character vector of diagram paths.
Uses rule-based visual triggers in the item stem, topic, objective, and options.
aigra_detect_diagram_required(stem, topic = "", objective = "", options = "")aigra_detect_diagram_required(stem, topic = "", objective = "", options = "")
stem |
Item stem. |
topic |
Optional topic. |
objective |
Optional objective. |
options |
Optional option text. |
TRUE or FALSE.
Get path to bundled AIGRA example item bank
aigra_example_item_bank()aigra_example_item_bank()
Path to the bundled example CSV item bank.
Find uv executable
aigra_find_uv()aigra_find_uv()
Path to uv executable.
Generate a single AIGRA diagram from a prompt
aigra_generate_diagram( prompt, output_path, provider = "gemini", model = "gemini-2.5-flash-image", size = "1024x1024" )aigra_generate_diagram( prompt, output_path, provider = "gemini", model = "gemini-2.5-flash-image", size = "1024x1024" )
prompt |
Diagram prompt. |
output_path |
Output PNG path. |
provider |
Image provider. |
model |
Image model. |
size |
Image size. |
Output path.
Tries multiple image-generation models in order until one succeeds.
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" )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" )
prompt |
Diagram prompt. |
output_path |
Output PNG path. |
provider |
Image provider. |
models |
Character vector of model names to try in order. |
size |
Image size. |
Output path.
A user-friendly wrapper around aigra_generate_tabular_items() that allows users to provide provider API keys directly in R.
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, ... )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, ... )
file_path |
Path to the item-bank template file. |
model |
Model name or alias. For example, |
provider |
Provider name. Use |
gemini.API |
Optional 'Gemini' API key. |
openai.API |
Optional 'OpenAI' API key. |
groq.API |
Optional 'Groq' API key. |
anthropic.API |
Optional 'Anthropic' API key. |
backend_path |
Optional path to the external 'AIGRA_BACKEND' folder. |
... |
Additional arguments passed to |
A data frame of generated items and review information.
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 ) }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 ) }
Runs item generation and diagram generation in one workflow.
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 )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 )
file_path |
Path to CSV or Excel item bank. |
provider |
Text-generation provider. |
model |
Text-generation model. |
image_provider |
Image-generation provider. |
image_model |
Image-generation model. |
source_language |
Source item language. |
target_language |
Target generated item language. |
subject |
Subject name. |
exam |
Exam or item-bank name. |
n_clones |
Number of clones per item. |
max_items |
Maximum source items to process. Use NULL for all. |
max_images |
Maximum diagrams to generate. Use NULL for all generated rows. |
write_reports |
If TRUE, writes quality and administration HTML reports. |
include_key |
If TRUE, include answer key in administration HTML. |
only_accepted |
If TRUE, administration HTML includes only ok/edited rows. |
Text-only items are generated normally. Items that require diagrams are processed through the Source Diagram Agent and Clone Diagram Agent.
A list containing result, result_with_diagrams, report_path, admin_file, and student_file.
Generates diagram images for result rows and returns the updated data frame with diagram_path, diagram_prompt, image_provider, and image_model columns.
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 )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 )
result |
A data frame returned by AIGRA. |
output_dir |
Directory for generated images. |
provider |
Image provider. |
model |
Image model. |
rows |
Optional row numbers to process. |
only_required |
If TRUE, process only rows where diagram_required is true. |
force |
If TRUE, generate even when diagram_required is false or missing. |
max_images |
Maximum number of images to generate. |
overwrite |
If TRUE, overwrite existing image files. |
Updated result data frame.
Applies the Diagram Agent, then generates diagrams for rows marked as requiring diagrams.
aigra_generate_result_diagrams_auto( result, provider = "gemini", model = "gemini-3-pro-image-preview", rows = NULL, max_images = 3, overwrite = FALSE )aigra_generate_result_diagrams_auto( result, provider = "gemini", model = "gemini-3-pro-image-preview", rows = NULL, max_images = 3, overwrite = FALSE )
result |
A data frame returned by AIGRA. |
provider |
Image provider. |
model |
Image model. |
rows |
Optional row numbers to process. |
max_images |
Maximum number of images to generate. |
overwrite |
If TRUE, overwrite existing image files. |
Updated result data frame with diagram paths.
Runs the AIGRA generation, solver, critic, and export pipeline using a CSV or Excel item bank.
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 )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 )
file_path |
Path to CSV or Excel item bank. |
provider |
LLM provider, such as "gemini", "openai", "groq", or "anthropic". |
model |
Provider model name. |
source_language |
Language of the source item bank. |
target_language |
Language for generated items. |
review_language |
Language for review comments. |
subject |
Subject name. |
exam |
Examination or item-bank name. |
n_clones |
Number of clones per source item. |
max_items |
Maximum number of valid source items to process. Use NULL to process all valid items. |
output_dir |
Optional output directory. |
read_csv |
If TRUE, returns the CSV output as a data frame. |
A data frame if read_csv is TRUE; otherwise invisibly returns the CSV path.
Returns the image model registry known to AIGRA. This function is CRAN-safe and does not call external APIs or require the Python backend.
aigra_image_models(provider = NULL)aigra_image_models(provider = NULL)
provider |
Optional image provider, such as "gemini" or "openai". |
Supported image models.
Get latest AIGRA CSV output path
aigra_latest_csv()aigra_latest_csv()
Path to latest CSV output.
Get latest AIGRA CSV output path
aigra_latest_output()aigra_latest_output()
Path to the latest AIGRA CSV output.
Lists generated CSV and JSONL files from the backend output directory.
aigra_list_outputs()aigra_list_outputs()
A data frame of output files.
Adds a language instruction to diagram prompts so generated diagrams use the target language for visible labels.
aigra_localize_diagram_prompts(result, target_language = "English")aigra_localize_diagram_prompts(result, target_language = "English")
result |
A data frame returned by AIGRA. |
target_language |
Target language for visible diagram text labels. |
Updated result data frame.
Create AIGRA multimodal template items
aigra_multimodal_template_items(diagram_dir = NULL, create_diagrams = TRUE)aigra_multimodal_template_items(diagram_dir = NULL, create_diagrams = TRUE)
diagram_dir |
Directory where source diagrams are stored or should be created. |
create_diagrams |
If TRUE, creates sample source diagram PNG files. |
A data frame containing multimodal sample items.
AIGRA output directory
aigra_output_dir()aigra_output_dir()
Path to the backend output directory.
List AIGRA output files
aigra_outputs(pattern = "aigra(_tabular)?_results_.*\\.(csv|jsonl)$")aigra_outputs(pattern = "aigra(_tabular)?_results_.*\\.(csv|jsonl)$")
pattern |
File-name pattern. |
A data frame of output files.
Parses a supported assessment-item PDF through the AIGRA Python backend and returns a data frame of source items.
aigra_parse_items( pdf_path = NULL, source_language = "Russian", subject = "Physics", exam = "Kazakhstan UNT" )aigra_parse_items( pdf_path = NULL, source_language = "Russian", subject = "Physics", exam = "Kazakhstan UNT" )
pdf_path |
Path to the source item-bank PDF. Defaults to backend data/Kz.pdf. |
source_language |
Language of the source item bank. |
subject |
Subject name. |
exam |
Examination name. |
A data frame of parsed assessment items.
Parses a CSV or Excel item bank directly from the supplied file path.
aigra_parse_tabular_items( file_path, source_language = "English", subject = "General", exam = "Item Bank" )aigra_parse_tabular_items( file_path, source_language = "English", subject = "General", exam = "Item Bank" )
file_path |
Path to CSV or Excel item bank. |
source_language |
Default source language if the file does not contain source_language. |
subject |
Default subject if the file does not contain subject. |
exam |
Default exam name if the file does not contain exam. |
A data frame of parsed assessment items.
Plot an AIGRA diagram image
aigra_plot_diagram(image_path)aigra_plot_diagram(image_path)
image_path |
Path to a PNG image. |
Invisibly returns the image path.
Creates a simple bar chart of item review statuses in an AIGRA output.
aigra_plot_summary(data = NULL)aigra_plot_summary(data = NULL)
data |
Optional AIGRA output data frame. If NULL, reads the latest CSV output. |
Invisibly returns the status table used for plotting.
Prints a compact quality summary for an AIGRA output.
aigra_print_summary(data = NULL)aigra_print_summary(data = NULL)
data |
Optional AIGRA output data frame. If NULL, reads the latest CSV output. |
Invisibly returns the summary list.
Print tabular item-bank validation results
aigra_print_validation(validation)aigra_print_validation(validation)
validation |
Validation result returned by |
Invisibly returns the validation object.
Show AIGRA Python environment information
aigra_python_info(backend_path = NULL)aigra_python_info(backend_path = NULL)
backend_path |
Path to the AIGRA_BACKEND folder. |
A list with Python environment information.
Read latest AIGRA CSV output
aigra_read_latest_csv()aigra_read_latest_csv()
A data frame containing the latest AIGRA CSV output.
Read latest AIGRA CSV output
aigra_read_latest_output()aigra_read_latest_output()
A data frame containing the latest AIGRA CSV output.
Strengthens diagram prompts when a generated item requires a figure but the prompt is too vague for solving/review.
aigra_repair_diagram_prompts(result)aigra_repair_diagram_prompts(result)
result |
A data frame returned by AIGRA. |
Updated result data frame.
Sets API keys for supported providers from within R. These environment variables are inherited by the external 'Python' backend when generation functions are called.
aigra_set_api_keys( gemini.API = NULL, openai.API = NULL, groq.API = NULL, anthropic.API = NULL )aigra_set_api_keys( gemini.API = NULL, openai.API = NULL, groq.API = NULL, anthropic.API = NULL )
gemini.API |
Optional 'Gemini' API key. |
openai.API |
Optional 'OpenAI' API key. |
groq.API |
Optional 'Groq' API key. |
anthropic.API |
Optional 'Anthropic' API key. |
Invisibly returns a named logical vector showing which keys are set.
keys <- aigra_set_api_keys() is.logical(keys)keys <- aigra_set_api_keys() is.logical(keys)
Connects the R package to the AIGRA Python backend.
Sets the path to the AIGRA Python backend.
aigra_set_backend(backend_path = NULL) aigra_set_backend(backend_path = NULL)aigra_set_backend(backend_path = NULL) aigra_set_backend(backend_path = NULL)
backend_path |
Path to the AIGRA_BACKEND folder. If NULL, uses the AIGRA_BACKEND_PATH environment variable. |
Invisibly returns backend configuration.
Invisibly returns the normalized backend path.
Show a diagram from an AIGRA result row
aigra_show_result_diagram(result, row = 1)aigra_show_result_diagram(result, row = 1)
result |
A data frame returned by AIGRA. |
row |
Row number to display. |
Invisibly returns the image path.
Checks whether the R package can access the Python backend.
aigra_status(backend_path = NULL)aigra_status(backend_path = NULL)
backend_path |
Optional path to the AIGRA_BACKEND folder. |
A list containing backend path, Python path, Python version, and import status.
Summarises the latest or supplied AIGRA CSV output.
aigra_summarise_output(data = NULL)aigra_summarise_output(data = NULL)
data |
Optional AIGRA output data frame. If NULL, reads the latest CSV output. |
A list with quality counts and simple rates.
Creates a sample item-bank data frame with the required columns for CSV/Excel-based AIGRA generation.
aigra_template_items()aigra_template_items()
A data frame containing sample item-bank rows.
This rewrites diagram prompts into the target language before image generation. Scientific symbols and units are preserved.
aigra_translate_diagram_prompts( result, target_language = "English", provider = "gemini", model = "gemini-3.1-pro-preview" )aigra_translate_diagram_prompts( result, target_language = "English", provider = "gemini", model = "gemini-3.1-pro-preview" )
result |
A data frame returned by AIGRA. |
target_language |
Target language for visible diagram labels. |
provider |
Text LLM provider. |
model |
Text LLM model. |
Updated result data frame.
Backward-compatible alias for aigra_set_backend().
aigra_use_backend(backend_path = NULL)aigra_use_backend(backend_path = NULL)
backend_path |
Optional backend path. If NULL, uses AIGRA_BACKEND_PATH. |
Invisibly returns backend path.
Checks a CSV or Excel item bank before parsing or generation.
aigra_validate_tabular_items(file_path)aigra_validate_tabular_items(file_path)
file_path |
Path to CSV or Excel item bank. |
A list containing validation status, issues, and a summary.
Creates a print-ready HTML file containing generated item stems, diagrams, response options, and an answer key.
aigra_write_admin_html( result, file = NULL, title = "AIGRA Generated Assessment Items", include_key = TRUE, include_metadata = FALSE, only_accepted = TRUE )aigra_write_admin_html( result, file = NULL, title = "AIGRA Generated Assessment Items", include_key = TRUE, include_metadata = FALSE, only_accepted = TRUE )
result |
A data frame returned by AIGRA, preferably after diagram generation. |
file |
Output HTML file. If NULL, writes to backend outputs folder. |
title |
Title shown at the top of the paper. |
include_key |
If TRUE, include answer key at the end. |
include_metadata |
If TRUE, show topic, section, and difficulty. |
only_accepted |
If TRUE, include only rows with status ok or edited. |
Path to the HTML file.
Creates source diagram PNGs and writes a ready-to-run Excel item bank.
aigra_write_multimodal_template_excel( file = NULL, diagram_dir = NULL, overwrite = FALSE )aigra_write_multimodal_template_excel( file = NULL, diagram_dir = NULL, overwrite = FALSE )
file |
Output Excel file path. |
diagram_dir |
Directory for source diagram PNGs. |
overwrite |
If TRUE, overwrite the Excel file. |
Path to the Excel file.
Writes a CRAN-safe local HTML report from an AIGRA result data frame. If diagram_path is present, generated diagrams are shown inline.
aigra_write_report(result = NULL, file = NULL, title = "AIGRA Quality Report")aigra_write_report(result = NULL, file = NULL, title = "AIGRA Quality Report")
result |
A data frame returned by AIGRA. If NULL, reads latest output. |
file |
Output HTML path. If NULL, writes to backend outputs folder. |
title |
Report title. |
Path to the report.
Write an AIGRA CSV item-bank template
aigra_write_template_csv(file = "aigra_item_template.csv", overwrite = FALSE)aigra_write_template_csv(file = "aigra_item_template.csv", overwrite = FALSE)
file |
Output CSV file path. |
overwrite |
If TRUE, overwrite an existing file. |
The normalized output file path.
Write an AIGRA Excel item-bank template
aigra_write_template_excel( file = "aigra_item_template.xlsx", overwrite = FALSE )aigra_write_template_excel( file = "aigra_item_template.xlsx", overwrite = FALSE )
file |
Output Excel file path. |
overwrite |
If TRUE, overwrite an existing file. |
The normalized output file path.
Creates or repairs the 'Python' virtual environment used by the 'AIGRA' backend.
ensure_aigra_python( backend_path = NULL, python_version = "3.11", force = FALSE, install_providers = TRUE, verbose = FALSE )ensure_aigra_python( backend_path = NULL, python_version = "3.11", force = FALSE, install_providers = TRUE, verbose = FALSE )
backend_path |
Path to the 'AIGRA' backend folder. If |
python_version |
'Python' version to use with 'uv'. |
force |
If |
install_providers |
If |
verbose |
If |
A list with 'Python' environment information.
# This function creates or repairs a backend environment, # so the example only inspects the function interface. names(formals(ensure_aigra_python))# This function creates or repairs a backend environment, # so the example only inspects the function interface. names(formals(ensure_aigra_python))