Package {AIGENIE}

Type:	Package
Title:	Automatic Item Generation and Validation via Network-Integrated Evaluation
Version:	2.1.2
Date:	2026-08-26
Maintainer:	Hudson Golino <hfg9s@virginia.edu>
Description:	Automated psychological scale development and structural validation using large language models (LLMs) and network psychometric methods. Implements the AI-GENIE framework (Automatic Item Generation and Validation via Network-Integrated Evaluation) to generate candidate items, compute embedding representations, and estimate dimensional structure using Exploratory Graph Analysis (EGA). Item quality is evaluated using Unique Variable Analysis to identify redundant items and Bootstrap EGA to assess item and dimension stability. Supports both fully automated item generation and analysis of user-provided item sets, facilitating efficient, theory-informed measurement development prior to empirical data collection.
License:	AGPL (≥ 3)
Encoding:	UTF-8
Depends:	R (≥ 3.6.0), EGAnet (≥ 2.4.0)
Imports:	reticulate, ggplot2, igraph, patchwork, jsonlite
Suggests:	testthat (≥ 3.0.0), tictoc, knitr, rmarkdown
VignetteBuilder:	knitr
URL:	https://laralee.github.io/AIGENIE/, https://github.com/laralee/AIGENIE
BugReports:	https://github.com/laralee/AIGENIE/issues
RoxygenNote:	7.3.3
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-08-26 16:37:32 UTC; Hudson
Author:	Lara Russell-Lasalandra [aut, cph], Alexander Christensen [aut, cph], Hudson Golino [aut, cre, cph]
Repository:	CRAN
Date/Publication:	2026-09-08 13:50:09 UTC

AIGENIE: Automatic Item Generation and Validation via Network-Integrated Evaluation

Description

Automated psychological scale development and structural validation using large language models (LLMs) and network psychometric methods. Implements the AI-GENIE framework (Automatic Item Generation and Validation via Network-Integrated Evaluation) to generate candidate items, compute embedding representations, and estimate dimensional structure using Exploratory Graph Analysis (EGA). Item quality is evaluated using Unique Variable Analysis to identify redundant items and Bootstrap EGA to assess item and dimension stability. Supports both fully automated item generation and analysis of user-provided item sets, facilitating efficient, theory-informed measurement development prior to empirical data collection.

AIGENIE is an R package for automated psychological scale development and structural validation using large language models (LLMs) and network psychometric methods. The package implements the AI-GENIE framework (Automatic Item Generation and Validation via Network-Integrated Evaluation) to generate candidate items, compute embedding representations, and estimate dimensional structure using Exploratory Graph Analysis (EGA). Item quality is further evaluated using Unique Variable Analysis to identify redundant items and Bootstrap EGA to assess item and dimension stability. AI-GENIE supports both fully automated item generation and analysis of user-provided item sets, facilitating efficient, theory-informed measurement development prior to empirical data collection.

Main Functions

AIGENIE

Full pipeline: generate items using LLMs, compute embeddings, and perform EGA-based redundancy and stability item pool reduction and structural validation.

GENIE

Embedding and item-pool reduction (or filtering) only: takes existing items, computes embeddings, and performs EGA, UVA, and bootEGA. Use when you already have candidate items.

local_AIGENIE

Full pipeline using local GGUF models instead of cloud APIs. Requires downloading model files.

local_GENIE

GENIE with local embedding models.

Supported LLM Providers

For item generation, AIGENIE supports:

• OpenAI: GPT-4o, GPT-4, GPT-3.5-turbo, o1 series, plus newer models.

• Anthropic: Claude Sonnet 4.5, Opus 4.5, Haiku 4.5, plus newer models

• Groq: Llama 3.3 70b versatile, Llama 4 Maverick 17b 128e instruct, GPT-OSS-120b, GPT-OSS-20b, plus other models

• Local: Any GGUF model via llama-cpp-python

Supported Embedding Providers

For computing semantic embeddings, AIGENIE supports:

• OpenAI: text-embedding-3-small, text-embedding-3-large

• Jina AI: jina-embeddings-v3, jina-embeddings-v4 (with task adapters), and others

• HuggingFace: BAAI/bge, thenlper/gte, sentence-transformers models, and others

• Local: BERT, RoBERTa, DistilBERT, and other transformer models

Environment Setup Functions

reinstall_python_env

Reinstall the Python environment if you encounter issues.

install_gpu_support

Enable GPU acceleration for faster local model inference.

install_local_llm_support

Install llama-cpp-python for running local GGUF models.

python_env_info

Display diagnostic information about the Python environment.

set_huggingface_token

Configure HuggingFace authentication for gated models.

Quick Start

# Define what you want to measure
item.attributes <- list(
  anxiety = c("worry", "nervousness", "fear"),
  depression = c("sadness", "hopelessness", "fatigue")
)

# Generate and reduce items (OpenAI)
results <- AIGENIE(
  item.attributes = item.attributes,
  openai.API = Sys.getenv("OPENAI_API_KEY"),
  domain = "clinical psychology",
  scale.title = "Mood Assessment Scale",
  target.N = 30
)

# Or use Anthropic Claude with Jina embeddings
results <- AIGENIE(
  item.attributes = item.attributes,
  anthropic.API = Sys.getenv("ANTHROPIC_API_KEY"),
  jina.API = Sys.getenv("JINA_API_KEY"),
  model = "sonnet",
  embedding.model = "jina-embeddings-v3",
  domain = "clinical psychology",
  scale.title = "Mood Assessment Scale",
  target.N = 30
)

# Or use free Groq API
results <- AIGENIE(
  item.attributes = item.attributes,
  groq.API = Sys.getenv("GROQ_API_KEY"),
  openai.API = Sys.getenv("OPENAI_API_KEY"),
  model = "llama-3.3-70b-versatile",
  domain = "clinical psychology",
  scale.title = "Mood Assessment Scale",
  target.N = 30
)

Getting API Keys

• OpenAI: the OpenAI account dashboard

• Anthropic: https://platform.claude.com/docs/en/manage-claude/authentication

• Groq: https://console.groq.com/ (free tier available)

• Jina AI: https://jina.ai/ (free tier available)

• HuggingFace: https://huggingface.co/settings/tokens

Dependencies

AIGENIE uses a Python backend managed via UV for embedding generation and some LLM interactions. The Python environment is automatically configured on first use. Required R packages include EGAnet for network analysis and reticulate for Python integration.

Author(s)

Maintainer: Hudson Golino hfg9s@virginia.edu (ORCID) [copyright holder]

Authors:

• Lara Russell-Lasalandra llr7cb@virginia.edu (ORCID) [copyright holder]

• Alexander Christensen alexander.christensen@vanderbilt.edu (ORCID) [copyright holder]

Lara Lee Russell-Lasalandra, Hudson Golino, Alexander P. Christensen

References

Russell-Lasalandra, L. L., Christensen, A. P., & Golino, H. (2026). Generative psychometrics via AI-GENIE: Automatic item generation and validation with network-integrated evaluation. Behavior Research Methods, 58(8), 217. doi:10.3758/s13428-026-03082-1

Russell-Lasalandra, L. L., & Golino, H. (2026). Prompt engineering for scale development in generative psychometrics. PsyArXiv. https://osf.io/preprints/psyarxiv/znqkm_v2

Russell-Lasalandra, L. L., Golino, H., Garrido, L. E., & Christensen, A. P. (2026). The ultimate tutorial for AI-driven scale development in generative psychometrics: Releasing AIGENIE from its bottle. PsyArXiv. https://osf.io/preprints/psyarxiv/arfg3_v1

Garrido, L. E., Russell-Lasalandra, L. L., & Golino, H. (2025). Estimating dimensional structure in generative psychometrics: Comparing PCA and network methods using large language model item embeddings. PsyArXiv. https://osf.io/preprints/psyarxiv/2s7pw_v1

Golino, H., & Christensen, A. P. (2024). EGAnet: Exploratory Graph Analysis. R package. https://r-ega.net

Golino, H., Garrido, L., & Russell-Lasalandra, L. L. (2026). Optimizing the Landscape of LLM Embeddings with Dynamic Exploratory Graph Analysis for Generative Psychometrics: A Monte Carlo Study. arXiv. arXiv:2601.17010. doi:10.48550/arXiv.2601.17010

Christensen, A. P., & Golino, H. (2021a). Estimating the stability of the number of factors via Bootstrap Exploratory Graph Analysis: A tutorial. Psych, 3(3), 479-500.

Christensen, A. P., Garrido, L. E., & Golino, H. (2023). Unique variable analysis: A network psychometrics method to detect local dependence. Multivariate Behavioral Research.

Golino, H., Moulder, R., Shi, D., Christensen, A. P., Garrido, L. E., Nieto, M. D., Nesselroade, J., Sadana, R., Thiyagarajan, J. A., & Boker, S. M. (2020). Entropy fit indices: New fit measures for assessing the structure and dimensionality of multiple latent variables. Multivariate Behavioral Research.

Golino, H., Shi, D., Christensen, A. P., Garrido, L. E., Nieto, M. D., Sadana, R., Thiyagarajan, J. A., & Martinez-Molina, A. (2020). Investigating the performance of exploratory graph analysis and traditional techniques to identify the number of latent factors: A simulation and tutorial. Psychological Methods, 25, 292-320.

See Also

Useful links:

• https://laralee.github.io/AIGENIE/

• https://github.com/laralee/AIGENIE

• Report bugs at https://github.com/laralee/AIGENIE/issues

AIGENIE for the main function, GENIE for embedding-only analysis, EGAnet for the underlying EGA analysis methods.

Generate, Validate, and Check Items using AI-GENIE

Description

Generate, validate, and check your items for quality and redundancy using AI-GENIE (Generative Psychometrics via AI-GENIE: Automatic Item Generation and Validation via Network-Integrated Evaluation). AI-GENIE is a methodology that combines the latest open-source LLMs and generative artificial intelligence with advances in network psychometrics to facilitate scale generation, selection, and validation. The pipeline eliminates the need to generate hundreds of items by content experts, recruit diverse and experienced researchers, administer items to thousands of participants, and employ modern psychometric methods in the collected data.

Usage

AIGENIE(
  item.attributes,
  openai.API = NULL,
  hf.token = NULL,
  main.prompts = NULL,
  groq.API = NULL,
  anthropic.API = NULL,
  jina.API = NULL,
  model = "gpt4o",
  temperature = 1,
  top.p = 1,
  embedding.model = "text-embedding-3-small",
  target.N = NULL,
  domain = NULL,
  scale.title = NULL,
  item.examples = NULL,
  audience = NULL,
  item.type.definitions = NULL,
  response.options = NULL,
  prompt.notes = NULL,
  system.role = NULL,
  EGA.model = NULL,
  EGA.algorithm = NULL,
  EGA.uni.method = NULL,
  uva.cut.off = 0.2,
  boot.iter = 500,
  ncores = NULL,
  keep.org = FALSE,
  items.only = FALSE,
  embeddings.only = FALSE,
  adaptive = TRUE,
  run.overall = FALSE,
  all.together = FALSE,
  plot = TRUE,
  silently = FALSE
)

Arguments

Value

The structure of the return value depends on the function flags.

Defaults: items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, keep.org = FALSE, all.together = FALSE.

When items.only = TRUE: Returns a data.frame of generated items with columns: ID, statement, type, and attribute.

When embeddings.only = TRUE: Returns a named list with two elements:

• embeddings — an embedding matrix/list (columns or rownames correspond to item IDs).

• items — the items data.frame described above.

Default behaviour (items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, keep.org = FALSE, all.together = FALSE): Returns a named list with two top-level elements:

item_type_level

A named list where each name is an item type and each element is a per-type named list containing:

final_NMI

Numeric: final normalized mutual information after reduction.

initial_NMI

Numeric: initial NMI of the pre-reduced item pool.

embeddings

List or matrix of embeddings for this item type (see 'Notes on embeddings' below).

UVA

List from Unique Variable Analysis (contains at least n_removed, n_sweeps, redundant_pairs data.frame).

bootEGA

List with bootEGA results (e.g. initial_boot, final_boot, n_removed, items_removed, initial_boot_with_redundancies).

EGA.model_selected

Character: chosen EGA model (e.g. "TMFG" or "Glasso").

final_items

data.frame: final items after reduction (columns include ID, statement, attribute, type, EGA_com).

final_EGA

EGA object (from EGAnet) after reduction.

initial_EGA

Initial EGA object computed on the pre-reduced item set.

start_N

Integer: initial number of items in this type.

final_N

Integer: final number of items in this type.

network_plot

ggplot / patchwork object comparing networks before vs after reduction.

stability_plot

ggplot / patchwork object showing item stability before vs after reduction.

overall

Named list with aggregated results across all item types. Under the default this contains:

final_items

data.frame of final items across all types (columns as above).

embeddings

Embeddings for the full reduced item set (see 'Notes on embeddings' below). Note: overall$embeddings does not include selected.

When keep.org = TRUE (in addition to defaults above): The top-level shape remains (item_type_level and overall) but includes original (pre-reduction) information:

item_type_level

Each per-type sublist contains: final_NMI, initial_NMI, embeddings, UVA, bootEGA, EGA.model_selected, final_items, initial_items, final_EGA, initial_EGA, start_N, final_N, network_plot, stability_plot.

overall

Contains final_items, initial_items, and embeddings for the full item pool.

For keep.org = TRUE, per-type embeddings contains at least: full_org, sparse_org, selected, full, and sparse. (overall$embeddings contains the same subcomponents except selected is omitted.)

When run.overall = TRUE (items.only = FALSE, embeddings.only = FALSE):

item_type_level

Same per-type structure as the default (see above).

overall

A named list with aggregated results (not limited to final_items and embeddings) containing: final_NMI, initial_NMI, embeddings, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, and network_plot.

When all.together = TRUE (regardless of run.overall): Results are not split into item_type_level and overall. Instead the function returns a single named list (applies to the full — possibly keep.org modified — result set) containing: final_NMI, initial_NMI, embeddings, UVA, bootEGA, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, network_plot, and stability_plot.

References

Golino, H. F., & Epskamp, S. (2017). Exploratory graph analysis: A new approach for estimating the number of dimensions in psychological research. PLOS ONE, 12(6), e0174035. doi:10.1371/journal.pone.0174035

Christensen, A. P., Garrido, L. E., & Golino, H. (2023). Unique variable analysis: A network psychometrics method to detect local dependence. Multivariate Behavioral Research, 58(6), 1165–1182. doi:10.1080/00273171.2023.2194606

Christensen, A. P., & Golino, H. (2021). Estimating the stability of psychological dimensions via bootstrap exploratory graph analysis: A Monte Carlo simulation and tutorial. Psych, 3(3), 479–500. doi:10.3390/psych3030032

Danon, L., Díaz-Guilera, A., Duch, J., & Arenas, A. (2005). Comparing community structure identification. Journal of Statistical Mechanics: Theory and Experiment, 2005(9), P09008. doi:10.1088/1742-5468/2005/09/P09008

Russell-Lasalandra, L. L., Christensen, A. P., & Golino, H. F. (2026). Generative psychometrics via AI-GENIE: Automatic item generation and validation with network-integrated evaluation. Behavior Research Methods, 58(8), 217. doi:10.3758/s13428-026-03082-1

Examples

## Not run: 
########################################################
#### Example 1: Using AI-GENIE with Default Prompts ####
########################################################

# Add an OpenAI API key
key <- "INSERT YOUR KEY HERE"

# Item type definitions
trait.definitions <- list(
  neuroticism = paste0(
    "Neuroticism is a personality trait that describes one's ",
    "tendency to experience negative emotions like anxiety, ",
    "depression, irritability, anger, and self-consciousness."
  ),
  openness = paste0(
    "Openness is a personality trait that describes how ",
    "open-minded, creative, and imaginative a person is."
  ),
  extraversion = paste0(
    "Extraversion is a personality trait that describes people ",
    "who are more focused on the external world than their ",
    "internal experience."
  )
)

# Item attributes
aspects.of.personality.traits <- list(
  neuroticism = c("anxious", "depressed", "insecure", "emotional"),
  openness = c("creative", "perceptual", "curious", "philosophical"),
  extraversion = c("friendly", "positive", "assertive", "energetic")
)

# Name the field or specialty
domain <- "Personality Measurement"

# Name the Inventory being created
scale.title <- "Three of 'Big Five:' A Streamlined Personality Inventory"

# Run AI-GENIE to generate, validate, and redundancy-check an item pool for your new scale.
personality.inventory.results <- AIGENIE(
  item.attributes = aspects.of.personality.traits,
  openai.API = key,
  domain = domain,
  scale.title = scale.title,
  item.type.definitions = trait.definitions
)

# View the final item pool
View(personality.inventory.results)


#######################################################
#### Example 2: Using AI-GENIE with Custom Prompts ####
#######################################################


# Define a custom system role
system.role <- paste0(
  "You are an expert methodologist who specializes in scale ",
  "development for personality measurement. You are especially ",
  "equipped to create novel personality items that mimic the ",
  "style of popular 'Big Five' assessments."
)

# Define custom prompts for each personality trait
custom.personality.prompts <- list(

  # Prompt for generating neuroticism traits
  neuroticism = paste0(
    "Generate unique, psychometrically robust single-statement items designed to assess ",
    "the Big Five personality trait neuroticism.",
    paste0(
      "Neuroticism has the following characteristics: anxious, ",
      "depressed, insecure, and emotional. "
    )
  ),

  # Prompt for generating openness traits
  openness = paste0(
    "Generate unique, psychometrically robust single-statement items designed to assess ",
    "the Big Five personality trait openness.",
    paste0(
      "Openness has the following characteristics: creative, ",
      "perceptual, curious, and philosophical"
    )
  ),

  # Prompt for generating extraversion traits
  extraversion = paste0(
    "Generate unique, psychometrically robust single-statement items designed to assess ",
    "the Big Five personality trait extraversion.",
    paste0(
      "Extraversion has the following characteristics: friendly, ",
      "positive, assertive, and energetic."
    )
  )

)

# Run AI-GENIE to generate, validate, and redundancy-check an item pool for your new scale.
personality.inventory.results.custom <- AIGENIE(
  item.attributes = aspects.of.personality.traits, # created in example 1
  main.prompts = custom.personality.prompts,
  system.role = system.role,
  openai.API = key, # created in example 1
  scale.title = scale.title # created in example 1
)

# View the final item pool
View(personality.inventory.results.custom)

################################################################
###### Or, Run AIGENIE with an Open Source Model via Groq ######
################################################################

# Add your API Key from Groq
groq.key <- "INSERT YOUR KEY HERE"

# Chose an open-source model like 'DeepSeek' or 'GPT oss'
open.source.model <- "GPT oss 120b"

# Use AIGENIE with an open source model via Groq
personality.inventory.results.gptoss <- AIGENIE(
  item.attributes = aspects.of.personality.traits, # created in example 1
  openai.API = key, # Created in example 1
  domain = domain, # Created in example 1
  scale.title = scale.title, # Created in example 1
  model = open.source.model, # Select a model available on Groq's API
  groq.API = groq.key
)

# View the final item pool
View(personality.inventory.results.gptoss)

################################################################
###### Or, Run AIGENIE with a Hugging Face Embedding Model #####
################################################################

# Chose a BAAI/bge series OR thenlper/gte series model
hf.embedding.model <- "BAAI/bge-large-en-v1.5"

# Create a HF Token to access the best models. Moderate useage will still be FREE
hf.token <- "INSERT YOUR KEY HERE"


# Use AIGENIE with an open source model via Groq
personality.inventory.results.hf <- AIGENIE(
  item.attributes = aspects.of.personality.traits, # created in example 1
  # OpenAI API key is not needed for this example #
  domain = domain, # Created in example 1
  scale.title = scale.title, # Created in example 1
  model = open.source.model, # Select a model available on Groq's API
  groq.API = groq.key,
  embedding.model = hf.embedding.model,
  hf.token = hf.token
)

# View the final item pool
View(personality.inventory.results.hf)

################################################################
#### Example 4: Using Anthropic Claude for Item Generation ####
################################################################

# Add your Anthropic API key
anthropic.key <- "INSERT YOUR KEY HERE"

# Use Claude Sonnet (or "opus", "haiku", or full model names)
personality.inventory.claude <- AIGENIE(
  item.attributes = aspects.of.personality.traits,
  anthropic.API = anthropic.key,
  openai.API = key,  # Still needed for embeddings
  model = "sonnet",  # Alias for claude-sonnet-4-5-20250929
  domain = domain,
  scale.title = scale.title,
  item.type.definitions = trait.definitions
)

# View the final item pool
View(personality.inventory.claude)

################################################################
#### Example 5: Using Jina AI Embeddings ####
################################################################

# Add your Jina API key (free tier available)
jina.key <- "INSERT YOUR KEY HERE"

# Use Jina embeddings with Groq for generation
personality.inventory.jina <- AIGENIE(
  item.attributes = aspects.of.personality.traits,
  groq.API = groq.key,
  jina.API = jina.key,
  model = "llama-3.3-70b-versatile",
  embedding.model = "jina-embeddings-v3",
  domain = domain,
  scale.title = scale.title,
  item.type.definitions = trait.definitions
)

# View the final item pool
View(personality.inventory.jina)

################################################################
#### Example 6: Anthropic + Jina (No OpenAI Required) ####
################################################################

# Full pipeline without OpenAI
personality.inventory.no.openai <- AIGENIE(
  item.attributes = aspects.of.personality.traits,
  anthropic.API = anthropic.key,
  jina.API = jina.key,
  model = "sonnet",
  embedding.model = "jina-embeddings-v3",
  domain = domain,
  scale.title = scale.title,
  item.type.definitions = trait.definitions
)

# View the final item pool
View(personality.inventory.no.openai)


## End(Not run)

The use of the psychometric reduction component of AIGENIE on your pre-existing item pool

Description

GENIE applies the psychometric reduction steps present in AIGENIE on user-supplied items. Users provide their own items and optionally their own embeddings, then GENIE performs redundancy reduction and structural validation to assess item quality and dimensionality.

Usage

GENIE(
  items,
  embedding.matrix = NULL,
  openai.API = NULL,
  hf.token = NULL,
  jina.API = NULL,
  embedding.model = "text-embedding-3-small",
  EGA.model = NULL,
  EGA.algorithm = NULL,
  EGA.uni.method = NULL,
  uva.cut.off = 0.2,
  boot.iter = 500,
  ncores = NULL,
  embeddings.only = FALSE,
  run.overall = FALSE,
  all.together = FALSE,
  plot = TRUE,
  silently = FALSE
)

Arguments

Value

The structure of the return value depends on the function flags.

Defaults: items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, all.together = FALSE.

When items.only = TRUE: Returns a data.frame of generated items with columns: ID, statement, type, and attribute.

When embeddings.only = TRUE: Returns a named list with two elements:

• embeddings — an embedding matrix/list (columns or rownames correspond to item IDs).

• items — the items data.frame described above.

Default behaviour (items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, all.together = FALSE): Returns a named list with two top-level elements:

item_type_level

A named list where each name is an item type and each element is a per-type named list containing:

final_NMI

Numeric: final normalized mutual information after reduction.

initial_NMI

Numeric: initial NMI of the pre-reduced item pool.

embeddings

List or matrix of embeddings for this item type (see 'Notes on embeddings' below).

UVA

List from Unique Variable Analysis (contains at least n_removed, n_sweeps, redundant_pairs data.frame).

bootEGA

List with bootEGA results (e.g. initial_boot, final_boot, n_removed, items_removed, initial_boot_with_redundancies).

EGA.model_selected

Character: chosen EGA model (e.g. "TMFG" or "Glasso").

final_items

data.frame: final items after reduction (columns include ID, statement, attribute, type, EGA_com).

final_EGA

EGA object (from EGAnet) after reduction.

initial_EGA

Initial EGA object computed on the pre-reduced item set.

start_N

Integer: initial number of items in this type.

final_N

Integer: final number of items in this type.

network_plot

ggplot / patchwork object comparing networks before vs after reduction.

stability_plot

ggplot / patchwork object showing item stability before vs after reduction.

overall

Named list with aggregated results across all item types. Under the default this contains:

final_items

data.frame of final items across all types (columns as above).

embeddings

Embeddings for the full reduced item set (see 'Notes on embeddings' below). Note: overall$embeddings does not include selected.

When run.overall = TRUE (items.only = FALSE, embeddings.only = FALSE):

item_type_level

Same per-type structure as the default (see above).

overall

A named list with aggregated results (not limited to final_items and embeddings) containing: final_NMI, initial_NMI, embeddings, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, and network_plot.

When all.together = TRUE (regardless of run.overall): Results are not split into item_type_level and overall. Instead the function returns a single named list containing: final_NMI, initial_NMI, embeddings, UVA, bootEGA, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, network_plot, and stability_plot.

References

Golino, H. F., & Epskamp, S. (2017). Exploratory graph analysis: A new approach for estimating the number of dimensions in psychological research. PLOS ONE, 12(6), e0174035. doi:10.1371/journal.pone.0174035

Christensen, A. P., Garrido, L. E., & Golino, H. (2023). Unique variable analysis: A network psychometrics method to detect local dependence. Multivariate Behavioral Research, 58(6), 1165–1182. doi:10.1080/00273171.2023.2194606

Christensen, A. P., & Golino, H. (2021). Estimating the stability of psychological dimensions via bootstrap exploratory graph analysis: A Monte Carlo simulation and tutorial. Psych, 3(3), 479–500. doi:10.3390/psych3030032

Danon, L., Díaz-Guilera, A., Duch, J., & Arenas, A. (2005). Comparing community structure identification. Journal of Statistical Mechanics: Theory and Experiment, 2005(9), P09008. doi:10.1088/1742-5468/2005/09/P09008

Russell-Lasalandra, L. L., Christensen, A. P., & Golino, H. F. (2026). Generative psychometrics via AI-GENIE: Automatic item generation and validation with network-integrated evaluation. Behavior Research Methods, 58(8), 217. doi:10.3758/s13428-026-03082-1

Examples

 ## Not run: 
#####################################################################
#### GENIE with Bundled GPT-5.4 Items and Frozen Embeddings      ####
#####################################################################

# Load the example item pool and its matching embedding matrix.
# No API key is required.
data("items.gpt5.4.example")
data("embeddings.gpt5.4.example")

# Run GENIE using the pre-computed embeddings.
gpt5.4.example.results <- GENIE(
  items = items.gpt5.4.example,
  embedding.matrix = embeddings.gpt5.4.example,
  EGA.model = "glasso",
  EGA.algorithm = "walktrap",
  EGA.uni.method = "louvain",
  uva.cut.off = 0.20,
  run.overall = TRUE,
  plot = FALSE,
  silently = FALSE
)

# Final retained items
gpt5.4.example.results$item_type_level$conscientiousness$final_items
gpt5.4.example.results$item_type_level$openness$final_items

# Publication-ready audit of every filtered item:
# what was removed, why, the filtering statistic and cutoff,
# redundancy partner(s), item stability, and pre-reduction
# network-loading diagnostics.
gpt5.4.example.results$filtering_audit

# Stage-by-stage NMI trajectories
gpt5.4.example.results$item_type_level$conscientiousness$reduction_summary
gpt5.4.example.results$item_type_level$openness$reduction_summary

# Pooled post-reduction fit, when run.overall = TRUE
gpt5.4.example.results$overall

############################################################
#### Using GENIE with OpenAI's Embeddings (Recommended) ####
############################################################

# Add an OpenAI API Key
key <- "INSERT YOUR KEY HERE"


# Specify item statements that you already have written
statements <- c(
  "I find myself naturally initiating conversations with strangers at social gatherings.",
  "I enjoy creating a welcoming atmosphere for people I meet for the first time.",
  "I generally maintain a hopeful outlook, even when faced with challenges.",
  "I frequently find myself in a good mood, spreading cheer to those around me.",
  "I often have the drive to engage in exciting activities, even after a long day.",
  "I tend to tackle projects with enthusiasm and high energy from start to finish.",
  paste0(
    "I actively seek to include others in group activities, ",
    "making them feel part of the team."
  ),
  "I frequently reach out to new acquaintances to foster connections and friendships.",
  paste0(
    "I habitually focus on the silver lining in difficult ",
    "situations, maintaining an optimistic perspective."
  ),
  paste0(
    "I often express gratitude for the positive aspects of my ",
    "life, which enhances my overall mood."
  ),
  "I find joy in taking on new challenges that require a burst of energy and enthusiasm.",
  "I thrive in dynamic environments that keep me on my toes and invigorate my spirit.",
  "I take pleasure in introducing people to one another, acting as a social connector.",
  "I enjoy making others comfortable by engaging them in light-hearted conversation.",
  "I often set a positive tone in group settings with my upbeat demeanor.",
 "I approach each day with a sense of excitement and a positive mindset.",
 "I am drawn to fast-paced environments where I can express my high energy levels.",
 "I feel invigorated when working on multiple projects that demand my full attention.",
 "I take delight in meeting new people and quickly making them feel at ease.",
 paste0(
   "I find it rewarding to help shy or reserved individuals ",
   "become involved in group discussions."
 ),
 "I have a natural tendency to uplift others with my positive remarks and outlook.",
 paste0(
   "I find happiness in highlighting the successes of others, ",
   "contributing to a cheerful environment."
 ),
 "I eagerly immerse myself in activities that demand stamina and sustained energy.",
 "I often channel my vitality into hobbies and sports that require physical exertion.",
 "I feel rejuvenated when I bring people together to collaborate and share ideas.",
 "I often extend a genuine greeting to others, creating an inviting atmosphere.",
 "I regularly see challenges as opportunities for growth and learning.",
 "I commonly radiate positivity, influencing the mood of those around me.",
 "I approach mornings with anticipation and vigor, ready to embrace the day.",
 paste0(
   "I consistently infuse enthusiasm into group activities, ",
   "boosting collective energy levels."
 ),
 "I make an effort to connect with people by remembering details about their lives.",
 "I genuinely enjoy learning about people's diverse experiences and viewpoints.",
 "I have a habit of encouraging others to see the bright side of their situations.",
 "I believe in celebrating small victories, finding joy in daily accomplishments.",
 "I often find myself eager to start the day with ambitious plans and goals.",
 paste0(
   "I am known for sustaining high levels of energy during ",
   "extended work sessions or projects."
 ),
 "I make an effort to engage those around me in meaningful and enjoyable conversations.",
 "I often seek opportunities to bring people together, fostering a sense of community.",
 "I naturally inspire others with my optimistic outlook, even in uncertain times.",
 paste0(
   "I frequently look for the positive aspects in challenging ",
   "situations and share them with others."
 ),
 "I approach new experiences with an eagerness and fervor that motivates those around me.",
 "I thrive on maintaining high energy levels throughout demanding and fast-paced days.",
 paste0(
   "I take pleasure in initiating warm interactions in group ",
   "settings to make everyone comfortable."
 ),
 "I enjoy hosting gatherings that connect friends and encourage social bonding.",
 paste0(
   "I am skilled at turning setbacks into learning experiences ",
   "to maintain a positive outlook."
 ),
 "I always try to highlight the benefits in situations, enhancing a cheerful atmosphere.",
 "I find excitement in starting the day with a list of activities to energize my routine.",
 paste0(
   "I relish the challenge of keeping up with dynamic schedules ",
   "that require sustained energy."
 ),
 "I often find joy in making newcomers feel welcome and appreciated in group settings.",
 "I genuinely enjoy striking up conversations to learn more about the people I encounter.",
 "I have a knack for seeing potential in situations that others might overlook.",
 paste0(
   "I consistently try to uplift the mood in my surroundings ",
   "with hopeful and encouraging words."
 ),
 paste0(
   "I frequently harness my energy to inspire and motivate those ",
   "around me in team environments."
 ),
 "I often feel invigorated by challenges that require sustained focus and dynamic thinking.",
 "I often create environments where people feel encouraged to share their thoughts freely.",
 "I find it fulfilling to engage deeply with people, building lasting connections.",
 "I see potential in every day, believing it holds opportunities for something good.",
 "I actively focus on the pleasures of life, which naturally enhances my mood.",
 "I am invigorated by opportunities to engage in lively and spirited events.",
 "I tend to maintain momentum throughout the day, sustaining my energy levels.",
 paste0(
   "I frequently experience sudden shifts in my emotions even ",
   "when there is no apparent reason."
 ),
 "People often find it difficult to predict my emotional reactions to different situations.",
 "I often doubt my abilities and worry about whether I am meeting expectations.",
 "I frequently question my self-worth and tend to seek reassurance from others.",
 "I become annoyed easily over small inconveniences or delays.",
 paste0(
   "I often find myself feeling agitated or frustrated in ",
   "situations that don't bother most people."
 ),
 "My mood can change drastically over the course of a day, often without any clear reason.",
 "I tend to experience emotional highs and lows more intensely than those around me.",
 "I sometimes avoid taking on new challenges because I fear not being good enough.",
 "I often feel uncertain about my social standing and worry about being accepted by others.",
 "I find myself getting irritated quickly when things don't go my way.",
 "Minor annoyances often cause my patience to wear thin unusually fast.",
 "I frequently struggle to maintain a stable emotional state throughout the day.",
 "Unexpected events can cause me to experience drastic emotional swings.",
 "I often feel inadequate in comparison to others around me.",
 "I tend to second-guess my choices due to a lack of confidence in myself.",
 "I tend to become frustrated when things do not proceed as I have planned.",
 "I am prone to irritation when faced with unexpected changes to my routine.",
 paste0(
   "My emotional state is often unpredictable, shifting from ",
   "contentment to sadness with little warning."
 ),
 "People have commented that my emotions seem to fluctuate more than those of others.",
 "I frequently feel self-conscious about my achievements compared to those of my peers.",
 paste0(
   "I often worry excessively about making mistakes, even in ",
   "situations where it might be inconsequential."
 ),
 "Small disruptions in my daily routine can trigger strong feelings of annoyance.",
 "I find myself becoming irritated more quickly than others when under stress or pressure.",
 paste0(
   "I often find my emotional responses to be unpredictable, ",
   "feeling fine one moment and unsettled the next."
 ),
 "I experience strong emotions that can shift unexpectedly, often catching me off guard.",
 "I regularly feel uncertain about my ability to manage new responsibilities effectively.",
 "I often question my decisions, fearing they might not lead to the best outcomes.",
 paste0(
   "I frequently find myself reacting with impatience to ",
   "situations perceived as minor interruptions."
 ),
 "Even minor provocations can sometimes lead to an exaggerated sense of annoyance for me.",
 paste0(
   "My emotional state is often inconsistent, and I can feel ",
   "ecstatic or despondent within short timeframes."
 ),
 paste0(
   "I notice that my feelings can be quite volatile and intense, ",
   "affecting how I interact with others throughout the day."
 ),
 "I regularly doubt whether I am capable of achieving my personal or professional goals.",
 "I often seek validation from others to feel reassured about my self-worth.",
 paste0(
   "I am sensitive to disturbances and find my patience wearing ",
   "thin quickly when things aren't orderly."
 ),
 paste0(
   "I occasionally struggle to contain my annoyance over trivial ",
   "issues that disrupt my sense of calm."
 ),
 "I can go from feeling upbeat to being downcast without an obvious cause.",
 "My emotional responses can sometimes be unpredictable, shifting with little notice.",
 "I often feel the need for affirmation about my abilities from friends or colleagues.",
 "I tend to compare myself to others and feel uncertain about my achievements.",
 "I find myself easily bothered by noises or disturbances in my environment.",
 "I get easily flustered by situations that interrupt my planned activities.",
 paste0(
   "I find it challenging to maintain a consistent emotional ",
   "state, regardless of external situations."
 ),
 "My emotional reactions can be intense and differ significantly from moment to moment.",
 "I have a persistent fear of not measuring up to the expectations placed on me.",
 "I often feel anxious about others' perceptions of my capabilities and appearance.",
 "I am quick to express frustration at minor inconveniences in my daily routine.",
 paste0(
   "I find that small, unforeseen events often disrupt my sense ",
   "of calm and lead to irritation."
 ),
 paste0(
   "My emotional reactions can be strong and relentless, ",
   "impacting my behavior throughout the day."
 ),
 paste0(
   "I often find myself emotionally labile, with an inner ",
   "turbulence that others rarely perceive."
 ),
 "I frequently worry about my competence in areas where others seem confident.",
 paste0(
   "I have a tendency to second-guess myself and require ",
   "affirmation to feel reassured about my choices."
 ),
 "Small disruptions can ignite a lingering sense of agitation within me.",
 "I often catch myself feeling irritable even in relatively calm settings.",
 paste0(
   "I find myself swinging from happy to melancholic in a short ",
   "span of time, often surprising even myself."
 ),
 paste0(
   "Others often comment on how quickly my mood can change in ",
   "response to seemingly minor events."
 ),
 paste0(
   "I tend to feel apprehensive about presenting my opinions, ",
   "fearing they may be judged harshly."
 ),
 "I often require reassurance from peers to feel confident in my decisions and ideas.",
 "Interruptions during focused tasks often lead to an outpour of irritation from me.",
 "I struggle to keep my frustration in check when things do not unfold as expected."
)


# Create the item type and attribute labels
item.attributes <- c(
 rep(c("friendly", "positive", "energetic"), each = 2, times = 10),
 rep(c("moody", "insecure", "irritable"), each = 2, times = 10)
)
item.types <- c(
 rep("extraversion", 60),
 rep("neuroticism", 60)
)




# Build your data frame with the required columns: ID, statement, attribute, and type
items_df <- data.frame(
 ID = rep(as.factor(1:length(statements))),
 statement = statements,
 attribute = item.attributes,
 type = item.types
)


# Run GENIE with items you provide (embedding items via OpenAI)
example_reduction <- GENIE(items = items_df,
                          openai.API = key)

# View the results
View(example_reduction)


################################################################
###### Or, Run GENIE with a Hugging Face Embedding Model #######
################################################################

# Chose a BAAI/bge series OR thenlper/gte series model
hf.embedding.model <- "BAAI/bge-large-en-v1.5"

# Create a HF Token to access the best models. Moderate useage will still be FREE
hf.token <- "INSERT YOUR KEY HERE"

# Run GENIE using the Hugging Face Embedding model
example_reduction_HF <- GENIE(items = items_df,
                             embedding.model = hf.embedding.model,
                             hf.token = hf.token)




## End(Not run)

Build GENIE item-filtering audit table

Description

Combines the stage-specific evidence that caused item removal with pre-reduction network-loading diagnostics. UVA rows report wTO redundancy evidence and the retained redundant partner. bootEGA rows report empirical item stability. Network loadings are descriptive context and are not used as filtering thresholds.

Usage

build_filtering_audit(
  items,
  type_name,
  uva_log,
  boot_removed,
  initial_ega,
  uva.cut.off,
  stability.cut.off = 0.75,
  selection_dropped = character(0),
  final_dropped = character(0)
)

Arguments

Value

A tidy data frame with one row per filtered item and the evidence for its removal.

Build item.attributes Object from Items Data Frame

Description

Reverse engineers the item.attributes object structure required by AIGENIE from a validated items data frame. This allows GENIE to work with user-provided items by reconstructing the expected attribute structure.

Usage

build_item_attributes_from_items(items)

Arguments

Value

A named list where:

• Names are the unique item types from items$type

• Each element is a character vector of unique attributes for that type

• All values are normalized (lowercase, trimmed) to match AIGENIE expectations

Build the final GENIE/AIGENIE return object

Description

Build the final GENIE/AIGENIE return object

Usage

build_return(item_type_level, overall_result, run.overall, keep.org)

Arguments

Value

A named list containing item_type_level and a combined filtering_audit; when run.overall = TRUE, also includes overall.

Run bootstrapped EGA on the initial set of items

Description

Computes a pre-reduction bootEGA baseline for stability plots using the same EGA settings and bootstrap count as the reduction pipeline.

Usage

calc_final_stability(
  result,
  data,
  EGA.algorithm,
  EGA.uni.method,
  corr = "auto",
  ncores = NULL,
  boot.iter = 500,
  silently,
  EGA.type = "EGA.fit"
)

Arguments

Value

A list with successful and the updated result.

Chat with an LLM via API Calls

Description

Send one or more prompts to a remote large-language model (LLM) using the appropriate provider API (OpenAI, Hugging Face, Groq, or Anthropic). A valid API key for at least one provider is required. To use a local model (no API call), see local_chat().

Usage

chat(
  prompts,
  model,
  system.role = NULL,
  openai.API = NULL,
  hf.token = NULL,
  groq.API = NULL,
  anthropic.API = NULL,
  reps = 1,
  top.p = 1,
  temperature = 1,
  max.tokens = 2048L,
  silently = FALSE
)

Arguments

Details

The function includes a retry mechanism (up to 5 attempts) for transient API failures. If all attempts fail, the function stops with an informative error.

Value

A data.frame with one row per API call (i.e., per prompt × repetition) containing:

• rep — repetition index

• prompt — the prompt text sent to the model

• response — the raw text response returned by the model

Important

This function requires a valid API key corresponding to the selected model. Network access is required. For local (non-API) models, use local_chat().

See Also

local_chat

Examples

## Not run: 
#################################################
### Example 1: Writing a Very Basic Prompt  #####
#################################################

# First, define your API key
key <- "INSERT YOUR KEY HERE"
# Then, define your LLM model. This model should correspond to your API key.
model <- "gpt4o" # in this example, you would need an OpenAI API key.

# Then, write your prompt. This will be given to the model directly.
prompt <- "Why does the planet Saturn have rings? Give a 100 word explanation."

# Optionally, add a system role (a model persona)
system.role <- "You specialize in tutoring astronomy for high school students."

# Add the number of prompt repetitions. By default, this is set to 1. But it
# may bu useful to increase the number of repetitions to get a sense of how
# consistent your output might be.
reps <- 3

# Now you are ready to chat with an LLM
first_chat <- chat(
  # Set your own API key. If you are not using OpenAI, change the 1st
  # argument to match your API key. Choices are `hf.token`, `groq.API`,
  # `anthropic.API`, and `openai.API`. In this example, I'm using
  # `openai.API` since I want to chat with a GPT model.
  openai.API = key,
  model = model, # Ensure your model corresponds to your API key.
  prompts = prompt,
  system.role = system.role,
  reps = reps
)

# Check how the output changes from iteration to iteration
first_chat$response[[1]] # first iteration output
first_chat$response[[2]] # second iteration output
first_chat$response[[2]] # third iteration output


####################################################################
### Example 2: Send multiple prompts in a single function call #####
####################################################################

# You are also able to send more than one prompt in a single call
# Let's pull the first prompt from Example 1:
prompt1 <- "Why does the planet Saturn have rings? Give a 100 word explanation."
prompt2 <- "Which planet is the hottest in our solar system? How do we know?"

# Aggregate the prompts in a single object
prompts <- c(prompt1, prompt2)

# Ask the model the questions
second_chat <- chat(
  openai.API = key, # defined in Example 1
  model = model, # defined in Example 1
  prompts = prompts, # NEW
  system.role = system.role, # defined in Example 1
  reps = reps # defined in Example 1
)

# The outputted data frame for this example will have 6 rows
# since the number of prompts (2) times the number of reps (3)
# gives a total of 6 API calls.
second_chat$response[second_chat$prompt==prompt1] # the responses from prompt 1
second_chat$response[second_chat$prompt==prompt2] # the responses from prompt 2


####################################################################
### Example 3: Send multiple prompts with different System Roles ###
####################################################################

# Perhaps your prompts are not related. In that case, you would probably want
# to set a different system role for each prompt.
# Let's change `prompt 2` to be entirely unrelated to astronomy.
prompt2 <- "What is the difference between eukaryotes and prokaryotes? Why?"

# This new second prompt does not fit with the astronomy tutor persona. Let's
# write a persona to match this new prompt topic.
system.role2 <- "You specialize in tutoring biology for middle school students."

# Now, let's combine the system roles into a single object
system.role <- c(system.role, # defined in Example 1: the astronomy tutor
                 system.role2 # defined above: the biology tutor
                 )

# Aggregate our prompts in a single object again
prompts <- c(prompt1, # Asks about Saturn's rings (needs astronomy tutor)
             prompt2 # Asks about types of cells (needs biology tutor)
             )

# Ask the model the questions
third_chat <- chat(
  openai.API = key, # defined in Example 1
  model = model, # defined in Example 1
  prompts = prompts, # NEW
  system.role = system.role, # NEW
  reps = reps # defined in Example 1
)

# View the outputted data frame to examine the responses
View(third_chat)

## End(Not run)

Check for users who pasted the example code but didn't add an API key

Description

Check for users who pasted the example code but didn't add an API key

Usage

check_for_default_APIs(
  hf.token,
  groq.API = NULL,
  openai.API,
  anthropic.API = NULL,
  jina.API = NULL
)

Arguments

Check Local LLM Setup

Description

Verifies that all requirements for local LLM inference are met, including Python environment, llama-cpp-python installation, and model file accessibility.

Usage

check_local_llm_setup(model.path, silently = FALSE)

Arguments

Value

Logical. TRUE if setup is complete, FALSE otherwise.

Check if UV is Available

Description

Check if UV is Available

Usage

check_uv_available()

Value

TRUE if UV is available, otherwise stops with an error

Clean and Parse LLM Response

Description

Parses LLM-generated text to extract structured item data. Handles JSON format and falls back to text parsing.

Usage

cleaning_function(raw_text, item_type)

Arguments

Value

Data frame with type, attribute, statement columns

Clear PyTorch Environment Variables

Description

Clear PyTorch Environment Variables

Usage

clear_pytorch_environment()

Combine filtering audits across item types

Description

Combine filtering audits across item types

Usage

combine_filtering_audits(item_type_level)

Arguments

Value

A single data frame containing all available item-level filtering audit rows across item types.

Construct Item Examples String for Prompts

Description

Formats previous items as JSON for inclusion in prompts.

Usage

construct_item.examples_string(item.examples, current_type)

Arguments

Value

JSON-formatted string or NULL

Construct Formatted String of Example Items for Prompts

Description

Given a validated item examples data frame, this function constructs a JSON string of example items for a given type, to be used in prompt building.

Usage

construct_item.examples_string_for_prompt(item.examples, current_type)

Arguments

Value

A single JSON-formatted string (or NULL if no matches).

Create the AI-GENIE Python Virtual Environment

Description

Create the AI-GENIE Python Virtual Environment

Usage

create_aigenie_env(env_path)

Arguments

Value

TRUE invisibly on success

Create Initial Main Prompts for Item Generation

Description

Constructs structured prompts for an LLM to generate scale items based on a list of item attributes, optional item type definitions, audience and domain context, and example items. Each resulting prompt includes strict formatting requirements, attribute listings, and item-generation instructions.

Usage

create_main.prompts(
  item.attributes,
  item.type.definitions,
  domain,
  scale.title,
  prompt.notes,
  audience,
  item.examples
)

Arguments

Value

A named list of character strings. Each entry corresponds to one item type and contains a complete prompt to guide an LLM in generating two distinct items per attribute, formatted as a JSON array.

Create a System Role Prompt for an LLM Item Writer

Description

Constructs a system-level prompt to guide an LLM in behaving like an expert scale developer. The prompt communicates role identity, domain expertise, scale context, audience constraints, and response option considerations.

Usage

create_system.role(
  domain,
  scale.title,
  audience,
  response.options,
  system.role
)

Arguments

Value

A single character string representing the full system prompt to be passed to an LLM interface (e.g., OpenAI Chat API). If system.role is not provided, the function dynamically constructs one based on the other parameters.

Detect LLM Provider from Model Name

Description

Determines which API provider to use based on the model name.

Usage

detect_llm_provider(
  model,
  groq.API = NULL,
  openai.API = NULL,
  hf.token = NULL,
  anthropic.API = NULL
)

Arguments

Value

A list with provider name and normalized model string

Embed Items Using OpenAI's Embedding API

Description

Generates embeddings using OpenAI's embedding models.

Usage

embed_items(embedding.model, openai.API, items, silently)

Arguments

Value

A list with 'embeddings' matrix and 'success' flag

Embed Items Using HuggingFace Models

Description

Generates embeddings using HuggingFace models. Tries the Inference API first, then falls back to the sentence-transformers library for unsupported models.

Usage

embed_items_huggingface(
  embedding.model = "BAAI/bge-base-en-v1.5",
  hf.token = NULL,
  items,
  silently = FALSE
)

Arguments

Value

A list with 'embeddings' matrix and 'success' flag

Embed Items Using HuggingFace Inference API

Description

Embed Items Using HuggingFace Inference API

Usage

embed_items_huggingface_api(embedding.model, hf.token, items, silently = FALSE)

Embed Items Using Jina AI Embedding API

Description

Generates embeddings using Jina AI's embedding models via their REST API at https://api.jina.ai/v1/embeddings. Uses Bearer token auth and supports Jina-specific features: task adapters, Matryoshka dimension truncation, and late chunking.

The Jina API follows an OpenAI-compatible request/response schema, with additional parameters for task type and output dimensions.

Usage

embed_items_jina(
  embedding.model = "jina-embeddings-v3",
  jina_api_key,
  items,
  task = "text-matching",
  dimensions = NULL,
  silently = FALSE
)

Arguments

Value

A list with 'embeddings' matrix and 'success' flag

Embed Items Using Local Transformer Models

Description

Generates raw embeddings using locally loaded BERT-family models. These are raw encoder outputs, not similarity-optimized embeddings.

Usage

embed_items_local(
  embedding.model,
  items,
  pooling.strategy = "mean",
  device = "auto",
  batch.size = 32,
  max.length = 512,
  silently = FALSE
)

Arguments

Value

A list with 'embeddings' matrix and 'success' flag

Embed Items Using Sentence-Transformers Library

Description

Embed Items Using Sentence-Transformers Library

Usage

embed_items_via_sentence_transformers(
  embedding.model,
  items,
  hf.token = NULL,
  silently = FALSE
)

Validate and Detect Embedding Model Provider

Description

Determines which provider to use for embeddings based on the model name.

Validates that the embedding model is one of the supported OpenAI, Jina AI, or HuggingFace models.

Usage

embedding.model_validate(embedding.model, provider = "auto", hf.token = NULL)

embedding.model_validate(embedding.model, provider = "auto", hf.token = NULL)

Arguments

Details

Allowed OpenAI models:

• "text-embedding-3-small"

• "text-embedding-3-large"

• "text-embedding-ada-002"

Allowed Jina AI models:

• jina-embeddings-v4, jina-embeddings-v3, jina-clip-v2

• jina-code-embeddings-1.5b, jina-code-embeddings-0.5b

• jina-embeddings-v2-base-en/zh/de/es/code, jina-embeddings-v2-small-en

Allowed HuggingFace models:

• BAAI/bge series (bge-small-en-v1.5, bge-base-en-v1.5, bge-large-en-v1.5)

• thenlper/gte series (gte-small, gte-base, gte-large)

Value

Character string: "openai", "jina", "huggingface", or "local"

Validate Embedding Matrix for GENIE

Description

Validates that the optional embedding matrix meets all requirements for GENIE processing. Ensures proper structure, dimensions, column names match item IDs, and numeric content.

Usage

embedding_matrix_validate_GENIE(embedding.matrix, items, silently = FALSE)

Arguments

Value

A validated embedding matrix (always as matrix type) or NULL if not provided

GPT-5.4 Example Item Embeddings

Description

A numeric embedding matrix corresponding to items.gpt5.4.example, provided for demonstrating GENIE without requiring an external embedding API call.

Usage

data("embeddings.gpt5.4.example")

Format

A 1536 x 180 numeric matrix. Rows are embedding dimensions and columns are items. Column names correspond to the item IDs in items.gpt5.4.example.

Details

The embeddings were generated from the GPT-5.4 example item pool using OpenAI's text-embedding-3-small embedding model. The matrix is oriented in the format expected by GENIE: embedding dimensions in rows and items in columns.

The corresponding item metadata are available as items.gpt5.4.example.

See Also

items.gpt5.4.example, GENIE

Examples

data("embeddings.gpt5.4.example")

dim(embeddings.gpt5.4.example)

data("items.gpt5.4.example")
all(
  colnames(embeddings.gpt5.4.example) %in%
    as.character(items.gpt5.4.example$ID)
)

Ensure AI-GENIE Python Environment is Ready

Description

Sets up the Python environment with all required dependencies for AI-GENIE. Uses UV for fast, reliable package management. This function is called automatically when needed, but can also be called directly.

Usage

ensure_aigenie_python(
  force_reinstall = FALSE,
  include_huggingface = TRUE,
  include_local_llm = FALSE,
  gpu = FALSE
)

Arguments

Value

TRUE invisibly on success

Ensure Python Environment for Local Models (Alias)

Description

Legacy compatibility function. Now calls ensure_aigenie_python with appropriate settings for local model support.

Usage

ensure_aigenie_python_local(force = FALSE, silently = FALSE)

Arguments

Value

TRUE invisibly on success

Ensure llama-cpp-python is Installed

Description

Ensure llama-cpp-python is Installed

Usage

ensure_llama_cpp_python(silently = FALSE, force_reinstall = FALSE)

Arguments

Extract item-level UVA removal evidence

Description

Creates one row per item removed by UVA, retaining the strongest redundant relationship as the primary diagnostic and all redundant partners for auditability.

Usage

extract_uva_removal_details(
  uva_object,
  removed_ids,
  remaining_ids,
  items,
  sweep,
  cut.off
)

Fetch Available Models from Anthropic API

Description

Queries the Anthropic /v1/models endpoint with pagination support.

Usage

fetch_anthropic_models(api_key)

Arguments

Value

Data frame of models or NULL on failure

Fetch Available Models from Groq API

Description

Fetch Available Models from Groq API

Usage

fetch_groq_models(api_key)

Arguments

Value

Data frame of models or NULL on failure

Fetch Available Models from OpenAI API

Description

Fetch Available Models from OpenAI API

Usage

fetch_openai_models(api_key)

Arguments

Value

Data frame of models or NULL on failure

Run Final Community Detection with EGA

Description

Run Final Community Detection with EGA

Usage

final_community_detection(
  embedding_matrix,
  true_communities,
  model = "glasso",
  algorithm = "walktrap",
  uni.method = "louvain",
  corr = "auto"
)

Arguments

Value

A list with final communities, final NMI, dropped items, EGA object, and success flag.

Generate Embeddings Using Any Supported Provider

Description

Unified interface for generating embeddings that automatically routes to the appropriate provider based on the model name.

Usage

generate_embeddings(
  embedding.model,
  items,
  openai.API = NULL,
  hf.token = NULL,
  jina.API = NULL,
  silently = FALSE,
  ...
)

Arguments

Value

A list with 'embeddings' matrix and 'success' flag

Generate Items via LLM

Description

Generates scale items using the specified LLM provider. Supports OpenAI, Groq, and local GGUF models.

Usage

generate_items_via_llm(
  main.prompts,
  system.role,
  model,
  top.p,
  temperature,
  adaptive,
  silently,
  groq.API,
  openai.API,
  anthropic.API = NULL,
  target.N
)

Arguments

Value

A list with 'items' data frame and 'successful' flag

Generate Items Using Local LLM (GGUF)

Description

Generates items using a locally installed GGUF model via llama-cpp-python.

Usage

generate_items_via_local_llm(
  main.prompts,
  system.role,
  model.path,
  temperature,
  top.p,
  adaptive,
  silently,
  target.N,
  n.ctx = 4096,
  n.gpu.layers = -1,
  max.tokens = 1024
)

Arguments

Value

A list with 'items' data frame and 'successful' flag

Generate Text Using Anthropic Messages API

Description

Generates text using Anthropic's Claude models via the /v1/messages endpoint. Uses the requests library directly (no extra SDK dependency).

Usage

generate_text_anthropic(
  prompt,
  system.role = NULL,
  model = "claude-sonnet-4-5-20250929",
  temperature = 1,
  top.p = 1,
  max_tokens = 2048,
  api_key
)

Arguments

Value

Character string with the generated text

Generate Text Using Groq API

Description

Generate Text Using Groq API

Usage

generate_text_groq(
  prompt,
  system.role = NULL,
  model = "llama-3.3-70b-versatile",
  temperature = 1,
  top.p = 1,
  max_tokens = 2048,
  api_key
)

Arguments

Value

Character string with the generated text

Generate Text Using HuggingFace Inference API

Description

Generate Text Using HuggingFace Inference API

Usage

generate_text_huggingface(
  prompt,
  system.role = NULL,
  model,
  temperature = 1,
  top.p = 1,
  max_tokens = 2048,
  hf_token = NULL
)

Arguments

Value

Character string with the generated text

Generate Text Using Any Supported LLM Provider

Description

Unified interface for text generation that automatically routes to the appropriate provider (OpenAI, Groq, Anthropic, or HuggingFace).

Usage

generate_text_llm(
  prompt,
  system.role = NULL,
  model = "gpt-4o",
  temperature = 1,
  top.p = 1,
  max_tokens = 2048,
  openai.API = NULL,
  groq.API = NULL,
  anthropic.API = NULL,
  hf.token = NULL
)

Arguments

Value

Character string with the generated text

Generate Text Using OpenAI API

Description

Generate Text Using OpenAI API

Usage

generate_text_openai(
  prompt,
  system.role = NULL,
  model = "gpt-4o",
  temperature = 1,
  top.p = 1,
  max_tokens = 2048,
  api_key
)

Arguments

Value

Character string with the generated text

Get the Path to AI-GENIE Python Environment

Description

Get the Path to AI-GENIE Python Environment

Usage

get_aigenie_env_path()

Value

Character string with the path to the virtual environment

Get Core Python Packages Required by AI-GENIE

Description

Get Core Python Packages Required by AI-GENIE

Usage

get_core_packages()

Value

Character vector of package specifications

Get HuggingFace-Related Python Packages

Description

Get HuggingFace-Related Python Packages

Usage

get_huggingface_packages()

Value

Character vector of package specifications

Get Jina AI Embedding Models

Description

Returns a curated list of Jina AI embedding models. Jina does not provide a model listing API endpoint, so this list is maintained manually.

Usage

get_jina_models()

Value

Data frame of Jina AI embedding models

Download a Local LLM Model

Description

Downloads a GGUF model from HuggingFace for use with local_AIGENIE. Models are saved to a user-specified directory or the default AIGENIE models directory.

Usage

get_local_llm(repo_id, filename, save_dir = NULL, hf.token = NULL)

Arguments

Value

Character string with the full path to the downloaded model file.

Examples

## Not run: 
# Download a Mistral 7B model
model_path <- get_local_llm(
  repo_id = "TheBloke/Mistral-7B-Instruct-v0.2-GGUF",
  filename = "mistral-7b-instruct-v0.2.Q4_K_M.gguf"
)

# Use it with local_AIGENIE
results <- local_AIGENIE(
  item.attributes = my_attributes,
  model.path = model_path
)

## End(Not run)

Get Local LLM Support Packages

Description

Get Local LLM Support Packages

Usage

get_local_llm_packages()

Value

Character vector of package specifications

Get Python Executable Path Based on OS

Description

Get Python Executable Path Based on OS

Usage

get_python_path(env_path)

Arguments

Value

Character string with the path to the Python executable

Install AI-GENIE Python Packages Using UV

Description

Install AI-GENIE Python Packages Using UV

Usage

install_aigenie_packages(
  env_path,
  include_huggingface = TRUE,
  include_local_llm = FALSE,
  gpu = FALSE
)

Arguments

Value

TRUE invisibly on success

Install GPU Support for AI-GENIE

Description

Reinstalls the Python environment with GPU-enabled PyTorch for faster inference with local embedding models. Requires a CUDA-compatible NVIDIA GPU and proper driver installation.

Usage

install_gpu_support()

Details

This function:

1. Removes the existing Python environment

2. Creates a new environment with GPU-enabled PyTorch

3. Installs all HuggingFace dependencies

On Apple Silicon Macs, MPS (Metal Performance Shaders) acceleration is used automatically without needing this function.

Value

Invisible TRUE on success.

See Also

reinstall_python_env, python_env_info.

Examples

## Not run: 
# Enable GPU acceleration (requires NVIDIA GPU + CUDA)
install_gpu_support()

## End(Not run)

Install Local LLM Support

Description

Installs llama-cpp-python for running local GGUF models with local_AIGENIE. On Apple Silicon Macs, this includes Metal acceleration support for fast inference.

Usage

install_local_llm_support()

Details

After installation, you can use any GGUF model file with local_AIGENIE(). Download GGUF models from HuggingFace (search for "GGUF" format).

Popular model recommendations:

• Llama 3 8B: Good balance of quality and speed

• Mistral 7B: Fast with good quality

• Qwen 2.5: Strong multilingual support

Value

Invisible TRUE on success.

See Also

local_AIGENIE, reinstall_python_env.

Examples

## Not run: 
# Install local LLM support
install_local_llm_support()

# Then download a GGUF model and use with local_AIGENIE
results <- local_AIGENIE(
  item.attributes = my_traits,
  model.path = "~/models/llama-3-8b.Q4_K_M.gguf",
  embedding.model = "bert-base-uncased"
)

## End(Not run)

Validate and Clean item.examples Against Cleaned items.attributes

Description

Ensures item.examples is a data frame with required string columns and that the values in type and attribute align with the cleaned structure of items.attributes. Returns a cleaned version of the data frame with normalized values:

• type and attribute are trimmed and lowercased

• statement is trimmed (case preserved)

Usage

item.examples_validate(item.examples, items.attributes)

Arguments

Value

A cleaned version of item.examples with normalized values.

Validate and Clean item.type.definitions

Description

Validates that item.type.definitions is a named list where:

• Names are unique (after trim + case-fold)

• Names exist in items.attributes

• Values are non-empty strings

Usage

item.type.definitions_validate(item.type.definitions, items.attributes)

Arguments

Details

Returns a cleaned version with:

• Normalized names (trimmed and lowercased)

• Trimmed values (case preserved)

Value

A cleaned version of item.type.definitions.

Validate items.attributes

Description

Validates that items.attributes is a named list whose names are truly unique after trimming whitespace and ignoring case, and that each element is itself a list containing only strings, with at least two truly unique strings (same trimming + case-insensitive rule).

Usage

items.attributes_validate(items.attributes)

Arguments

Value

A cleaned version of items.attributes with normalized names and values. Errors are thrown if validation fails.

GPT-5.4 Example Item Pool

Description

An example item pool generated with GPT-5.4 for demonstrating the psychometric reduction workflow implemented in GENIE. The data contain 180 personality items: 90 conscientiousness items and 90 openness items.

Usage

data("items.gpt5.4.example")

Format

A data frame with 180 rows and 4 variables:

ID

Unique item identifier.

statement

The generated item statement.

type

Higher-order item type: conscientiousness or openness.

attribute

Target attribute represented by the item.

Details

The item pool is the GPT-5.4 example used to illustrate AI-GENIE/GENIE item reduction. Conscientiousness items represent self-efficacy, achievement-striving, and perseverance. Openness items represent introspection, aesthetics, and abstract-thinking.

The corresponding embedding matrix is available as embeddings.gpt5.4.example.

See Also

embeddings.gpt5.4.example, GENIE

Examples

data("items.gpt5.4.example")

dim(items.gpt5.4.example)
head(items.gpt5.4.example)
table(items.gpt5.4.example$type)
table(items.gpt5.4.example$attribute)

Validate Items Data Frame for GENIE

Description

Validates that the items data frame meets all requirements for GENIE processing. Ensures proper structure, column presence, data types, and content validity.

Usage

items_validate_GENIE(items)

Arguments

Value

A cleaned and validated items data frame with standardized formatting

Iteratively run BootEGA to ensure structural stability of items

Description

Iteratively run BootEGA to ensure structural stability of items

Usage

iterative_stability_check(
  embedding_matrix,
  items,
  cut.off = 0.75,
  model = "NULL",
  algorithm = "",
  uni.method,
  corr = "auto",
  ncores = NULL,
  boot.iter = 500,
  EGA.type = "EGA.fit",
  silently
)

Arguments

Value

A list containing the final embedding, initial/final bootEGA objects, and an items_removed data frame. For each removed item, the table retains the bootstrap run, empirical item stability, cutoff, stability deficit, and removal reason. Zero-removal runs return an empty data frame, not NULL.

List Available Models

Description

Queries the OpenAI, Groq, Anthropic, and/or Jina AI APIs to retrieve currently available models. Requires API keys for live provider queries. Jina AI models are returned from a curated static list (no list endpoint).

Usage

list_available_models(
  provider = NULL,
  openai.API = NULL,
  groq.API = NULL,
  anthropic.API = NULL,
  type = NULL
)

Arguments

Value

A data frame with columns: provider, model, type, display_name, created

Generate and Validate Psychometric Scale Items Using Local Models

Description

Local version of AI-GENIE that uses locally installed language models and embeddings for complete privacy and offline operation. Generates items, creates embeddings, and performs network psychometric reduction entirely on the user's machine.

Usage

local_AIGENIE(
  item.attributes,
  model.path,
  embedding.model = "bert-base-uncased",
  main.prompts = NULL,
  temperature = 1,
  top.p = 1,
  target.N = NULL,
  domain = NULL,
  scale.title = NULL,
  item.examples = NULL,
  audience = NULL,
  item.type.definitions = NULL,
  response.options = NULL,
  prompt.notes = NULL,
  system.role = NULL,
  EGA.model = NULL,
  EGA.algorithm = NULL,
  EGA.uni.method = NULL,
  uva.cut.off = 0.2,
  boot.iter = 500,
  ncores = NULL,
  n.ctx = 4096,
  n.gpu.layers = -1,
  max.tokens = 1024,
  device = "auto",
  batch.size = 32,
  pooling.strategy = "mean",
  max.length = 512L,
  keep.org = FALSE,
  items.only = FALSE,
  embeddings.only = FALSE,
  adaptive = TRUE,
  run.overall = FALSE,
  all.together = FALSE,
  plot = TRUE,
  silently = FALSE
)

Arguments

Value

The structure of the return value depends on the function flags.

Defaults: items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, keep.org = FALSE, all.together = FALSE.

When items.only = TRUE: Returns a data.frame of generated items with columns: ID, statement, type, and attribute.

When embeddings.only = TRUE: Returns a named list with two elements:

• embeddings — an embedding matrix/list (columns or rownames correspond to item IDs).

• items — the items data.frame described above.

Default behaviour (items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, keep.org = FALSE, all.together = FALSE): Returns a named list with two top-level elements:

item_type_level

A named list where each name is an item type and each element is a per-type named list containing:

final_NMI

Numeric: final normalized mutual information after reduction.

initial_NMI

Numeric: initial NMI of the pre-reduced item pool.

embeddings

List or matrix of embeddings for this item type (see 'Notes on embeddings' below).

UVA

List from Unique Variable Analysis (contains at least n_removed, n_sweeps, redundant_pairs data.frame).

bootEGA

List with bootEGA results (e.g. initial_boot, final_boot, n_removed, items_removed, initial_boot_with_redundancies).

EGA.model_selected

Character: chosen EGA model (e.g. "TMFG" or "Glasso").

final_items

data.frame: final items after reduction (columns include ID, statement, attribute, type, EGA_com).

final_EGA

EGA object (from EGAnet) after reduction.

initial_EGA

Initial EGA object computed on the pre-reduced item set.

start_N

Integer: initial number of items in this type.

final_N

Integer: final number of items in this type.

network_plot

ggplot / patchwork object comparing networks before vs after reduction.

stability_plot

ggplot / patchwork object showing item stability before vs after reduction.

overall

Named list with aggregated results across all item types. Under the default this contains:

final_items

data.frame of final items across all types (columns as above).

embeddings

Embeddings for the full reduced item set (see 'Notes on embeddings' below). Note: overall$embeddings does not include selected.

When keep.org = TRUE (in addition to defaults above): The top-level shape remains (item_type_level and overall) but includes original (pre-reduction) information:

item_type_level

Each per-type sublist contains: final_NMI, initial_NMI, embeddings, UVA, bootEGA, EGA.model_selected, final_items, initial_items, final_EGA, initial_EGA, start_N, final_N, network_plot, stability_plot.

overall

Contains final_items, initial_items, and embeddings for the full item pool.

For keep.org = TRUE, per-type embeddings contains at least: full_org, sparse_org, selected, full, and sparse. (overall$embeddings contains the same subcomponents except selected is omitted.)

When run.overall = TRUE (items.only = FALSE, embeddings.only = FALSE):

item_type_level

Same per-type structure as the default (see above).

overall

A named list with aggregated results (not limited to final_items and embeddings) containing: final_NMI, initial_NMI, embeddings, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, and network_plot.

When all.together = TRUE (regardless of run.overall): Results are not split into item_type_level and overall. Instead the function returns a single named list (applies to the full — possibly keep.org modified — result set) containing: final_NMI, initial_NMI, embeddings, UVA, bootEGA, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, network_plot, and stability_plot.

References

Golino, H. F., & Epskamp, S. (2017). Exploratory graph analysis: A new approach for estimating the number of dimensions in psychological research. PLOS ONE, 12(6), e0174035. doi:10.1371/journal.pone.0174035

Christensen, A. P., Garrido, L. E., & Golino, H. (2023). Unique variable analysis: A network psychometrics method to detect local dependence. Multivariate Behavioral Research, 58(6), 1165–1182. doi:10.1080/00273171.2023.2194606

Christensen, A. P., & Golino, H. (2021). Estimating the stability of psychological dimensions via bootstrap exploratory graph analysis: A Monte Carlo simulation and tutorial. Psych, 3(3), 479–500. doi:10.3390/psych3030032

Danon, L., Díaz-Guilera, A., Duch, J., & Arenas, A. (2005). Comparing community structure identification. Journal of Statistical Mechanics: Theory and Experiment, 2005(9), P09008. doi:10.1088/1742-5468/2005/09/P09008

Russell-Lasalandra, L. L., Christensen, A. P., & Golino, H. F. (2026). Generative psychometrics via AI-GENIE: Automatic item generation and validation with network-integrated evaluation. Behavior Research Methods, 58(8), 217. doi:10.3758/s13428-026-03082-1

Examples

## Not run: 
########################################################
#### Running AIGENIE with a downloaded LLM model ######
########################################################

# Item type definitions
trait.definitions <- list(
 neuroticism = paste0(
   "Neuroticism is a personality trait that describes one's ",
   "tendency to experience negative emotions like anxiety, ",
   "depression, irritability, anger, and self-consciousness."
 ),
 extraversion = paste0(
   "Extraversion is a personality trait that describes people ",
   "who are more focused on the external world than their ",
   "internal experience."
 )
)

# Item attributes
aspects.of.personality.traits <- list(
 neuroticism = c("anxious", "depressed", "insecure", "emotional"),
 extraversion = c("friendly", "positive", "assertive", "energetic")
)

# Name the field or specialty
domain <- "Personality Measurement"

# Name the Inventory being created
scale.title <- "Two of 'Big Five:' A Streamlined Personality Inventory"

# Add a file path name to a local text generation model downloaded on your computer
model.path <- "ADD FILE PATH TO DOWNLOADED MODEL HERE"


# Generate and validate items using a model installed on your machine
local_example <- local_AIGENIE(
 item.attributes = aspects.of.personality.traits,
 item.type.definitions = trait.definitions,
 domain = domain,
 model.path = model.path
)


## End(Not run)

Local Generative Network-Integrated Evaluation (local_GENIE)

Description

Local version of GENIE that uses locally installed embedding models for complete privacy and offline operation. Provides the same psychometric validation and quality assessment for user-supplied items as GENIE, but generates embeddings locally using transformer models instead of API calls.

Usage

local_GENIE(
  items,
  embedding.matrix = NULL,
  embedding.model = "bert-base-uncased",
  device = "auto",
  batch.size = 32,
  pooling.strategy = "mean",
  max.length = 512,
  EGA.model = NULL,
  EGA.algorithm = NULL,
  EGA.uni.method = NULL,
  uva.cut.off = 0.2,
  boot.iter = 500,
  ncores = NULL,
  embeddings.only = FALSE,
  run.overall = FALSE,
  all.together = FALSE,
  plot = TRUE,
  silently = FALSE
)

Arguments

Value

Defaults: items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, all.together = FALSE.

When items.only = TRUE: Returns a data.frame of generated items with columns: ID, statement, type, and attribute.

When embeddings.only = TRUE: Returns a named list with two elements:

• embeddings — an embedding matrix/list (columns or rownames correspond to item IDs).

• items — the items data.frame described above.

Default behaviour (items.only = FALSE, embeddings.only = FALSE, run.overall = FALSE, all.together = FALSE): Returns a named list with two top-level elements:

item_type_level

A named list where each name is an item type and each element is a per-type named list containing:

final_NMI

Numeric: final normalized mutual information after reduction.

initial_NMI

Numeric: initial NMI of the pre-reduced item pool.

embeddings

List or matrix of embeddings for this item type (see 'Notes on embeddings' below).

UVA

List from Unique Variable Analysis (contains at least n_removed, n_sweeps, redundant_pairs data.frame).

bootEGA

List with bootEGA results (e.g. initial_boot, final_boot, n_removed, items_removed, initial_boot_with_redundancies).

EGA.model_selected

Character: chosen EGA model (e.g. "TMFG" or "Glasso").

final_items

data.frame: final items after reduction (columns include ID, statement, attribute, type, EGA_com).

final_EGA

EGA object (from EGAnet) after reduction.

initial_EGA

Initial EGA object computed on the pre-reduced item set.

start_N

Integer: initial number of items in this type.

final_N

Integer: final number of items in this type.

network_plot

ggplot / patchwork object comparing networks before vs after reduction.

stability_plot

ggplot / patchwork object showing item stability before vs after reduction.

overall

Named list with aggregated results across all item types. Under the default this contains:

final_items

data.frame of final items across all types (columns as above).

embeddings

Embeddings for the full reduced item set (see 'Notes on embeddings' below). Note: overall$embeddings does not include selected.

When run.overall = TRUE (items.only = FALSE, embeddings.only = FALSE):

item_type_level

Same per-type structure as the default (see above).

overall

A named list with aggregated results (not limited to final_items and embeddings) containing: final_NMI, initial_NMI, embeddings, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, and network_plot.

When all.together = TRUE (regardless of run.overall): Results are not split into item_type_level and overall. Instead the function returns a single named list containing: final_NMI, initial_NMI, embeddings, UVA, bootEGA, EGA.model_selected, final_items, final_EGA, initial_EGA, start_N, final_N, network_plot, and stability_plot.

References

Golino, H. F., & Epskamp, S. (2017). Exploratory graph analysis: A new approach for estimating the number of dimensions in psychological research. PLOS ONE, 12(6), e0174035. doi:10.1371/journal.pone.0174035

Christensen, A. P., Garrido, L. E., & Golino, H. (2023). Unique variable analysis: A network psychometrics method to detect local dependence. Multivariate Behavioral Research, 58(6), 1165–1182. doi:10.1080/00273171.2023.2194606

Christensen, A. P., & Golino, H. (2021). Estimating the stability of psychological dimensions via bootstrap exploratory graph analysis: A Monte Carlo simulation and tutorial. Psych, 3(3), 479–500. doi:10.3390/psych3030032

Danon, L., Díaz-Guilera, A., Duch, J., & Arenas, A. (2005). Comparing community structure identification. Journal of Statistical Mechanics: Theory and Experiment, 2005(9), P09008. doi:10.1088/1742-5468/2005/09/P09008

Russell-Lasalandra, L. L., Christensen, A. P., & Golino, H. F. (2026). Generative psychometrics via AI-GENIE: Automatic item generation and validation with network-integrated evaluation. Behavior Research Methods, 58(8), 217. doi:10.3758/s13428-026-03082-1

Examples

## Not run: 
###################################################
#### Using GENIE with a Local Embedding Model  ####
###################################################

# First, ensure that your machine is configured to compute local generation
install_local_llm_support()
# Once ready, continue to run GENIE on your data frame


# Specify item statements that you already have written
statements <- c(
  "I find myself naturally initiating conversations with strangers at social gatherings.",
  "I enjoy creating a welcoming atmosphere for people I meet for the first time.",
  "I generally maintain a hopeful outlook, even when faced with challenges.",
  "I frequently find myself in a good mood, spreading cheer to those around me.",
  "I often have the drive to engage in exciting activities, even after a long day.",
  "I tend to tackle projects with enthusiasm and high energy from start to finish.",
  paste0(
    "I actively seek to include others in group activities, ",
    "making them feel part of the team."
  ),
  "I frequently reach out to new acquaintances to foster connections and friendships.",
  paste0(
    "I habitually focus on the silver lining in difficult ",
    "situations, maintaining an optimistic perspective."
  ),
  paste0(
    "I often express gratitude for the positive aspects of my ",
    "life, which enhances my overall mood."
  ),
  "I find joy in taking on new challenges that require a burst of energy and enthusiasm.",
  "I thrive in dynamic environments that keep me on my toes and invigorate my spirit.",
  "I take pleasure in introducing people to one another, acting as a social connector.",
  "I enjoy making others comfortable by engaging them in light-hearted conversation.",
  "I often set a positive tone in group settings with my upbeat demeanor.",
  "I approach each day with a sense of excitement and a positive mindset.",
  "I am drawn to fast-paced environments where I can express my high energy levels.",
  "I feel invigorated when working on multiple projects that demand my full attention.",
  "I take delight in meeting new people and quickly making them feel at ease.",
  paste0(
    "I find it rewarding to help shy or reserved individuals ",
    "become involved in group discussions."
  ),
  "I have a natural tendency to uplift others with my positive remarks and outlook.",
  paste0(
    "I find happiness in highlighting the successes of others, ",
    "contributing to a cheerful environment."
  ),
  "I eagerly immerse myself in activities that demand stamina and sustained energy.",
  "I often channel my vitality into hobbies and sports that require physical exertion.",
  "I feel rejuvenated when I bring people together to collaborate and share ideas.",
  "I often extend a genuine greeting to others, creating an inviting atmosphere.",
  "I regularly see challenges as opportunities for growth and learning.",
  "I commonly radiate positivity, influencing the mood of those around me.",
  "I approach mornings with anticipation and vigor, ready to embrace the day.",
  paste0(
    "I consistently infuse enthusiasm into group activities, ",
    "boosting collective energy levels."
  ),
  "I make an effort to connect with people by remembering details about their lives.",
  "I genuinely enjoy learning about people's diverse experiences and viewpoints.",
  "I have a habit of encouraging others to see the bright side of their situations.",
  "I believe in celebrating small victories, finding joy in daily accomplishments.",
  "I often find myself eager to start the day with ambitious plans and goals.",
  paste0(
    "I am known for sustaining high levels of energy during ",
    "extended work sessions or projects."
  ),
  "I make an effort to engage those around me in meaningful and enjoyable conversations.",
  "I often seek opportunities to bring people together, fostering a sense of community.",
  "I naturally inspire others with my optimistic outlook, even in uncertain times.",
  paste0(
    "I frequently look for the positive aspects in challenging ",
    "situations and share them with others."
  ),
  "I approach new experiences with an eagerness and fervor that motivates those around me.",
  "I thrive on maintaining high energy levels throughout demanding and fast-paced days.",
  paste0(
    "I take pleasure in initiating warm interactions in group ",
    "settings to make everyone comfortable."
  ),
  "I enjoy hosting gatherings that connect friends and encourage social bonding.",
  paste0(
    "I am skilled at turning setbacks into learning experiences ",
    "to maintain a positive outlook."
  ),
  "I always try to highlight the benefits in situations, enhancing a cheerful atmosphere.",
  "I find excitement in starting the day with a list of activities to energize my routine.",
  paste0(
    "I relish the challenge of keeping up with dynamic schedules ",
    "that require sustained energy."
  ),
  "I often find joy in making newcomers feel welcome and appreciated in group settings.",
  "I genuinely enjoy striking up conversations to learn more about the people I encounter.",
  "I have a knack for seeing potential in situations that others might overlook.",
  paste0(
    "I consistently try to uplift the mood in my surroundings ",
    "with hopeful and encouraging words."
  ),
  paste0(
    "I frequently harness my energy to inspire and motivate those ",
    "around me in team environments."
  ),
  paste0(
    "I often feel invigorated by challenges that require ",
    "sustained focus and dynamic thinking."
  ),
  "I often create environments where people feel encouraged to share their thoughts freely.",
  "I find it fulfilling to engage deeply with people, building lasting connections.",
  "I see potential in every day, believing it holds opportunities for something good.",
  "I actively focus on the pleasures of life, which naturally enhances my mood.",
  "I am invigorated by opportunities to engage in lively and spirited events.",
  "I tend to maintain momentum throughout the day, sustaining my energy levels.",
  paste0(
    "I frequently experience sudden shifts in my emotions even ",
    "when there is no apparent reason."
  ),
  paste0(
    "People often find it difficult to predict my emotional ",
    "reactions to different situations."
  ),
  "I often doubt my abilities and worry about whether I am meeting expectations.",
  "I frequently question my self-worth and tend to seek reassurance from others.",
  "I become annoyed easily over small inconveniences or delays.",
  paste0(
    "I often find myself feeling agitated or frustrated in ",
    "situations that don't bother most people."
  ),
  "My mood can change drastically over the course of a day, often without any clear reason.",
  "I tend to experience emotional highs and lows more intensely than those around me.",
  "I sometimes avoid taking on new challenges because I fear not being good enough.",
  paste0(
    "I often feel uncertain about my social standing and worry ",
    "about being accepted by others."
  ),
  "I find myself getting irritated quickly when things don't go my way.",
  "Minor annoyances often cause my patience to wear thin unusually fast.",
  "I frequently struggle to maintain a stable emotional state throughout the day.",
  "Unexpected events can cause me to experience drastic emotional swings.",
  "I often feel inadequate in comparison to others around me.",
  "I tend to second-guess my choices due to a lack of confidence in myself.",
  "I tend to become frustrated when things do not proceed as I have planned.",
  "I am prone to irritation when faced with unexpected changes to my routine.",
  paste0(
    "My emotional state is often unpredictable, shifting from ",
    "contentment to sadness with little warning."
  ),
  "People have commented that my emotions seem to fluctuate more than those of others.",
  "I frequently feel self-conscious about my achievements compared to those of my peers.",
  paste0(
    "I often worry excessively about making mistakes, even in ",
    "situations where it might be inconsequential."
  ),
  "Small disruptions in my daily routine can trigger strong feelings of annoyance.",
  "I find myself becoming irritated more quickly than others when under stress or pressure.",
  paste0(
    "I often find my emotional responses to be unpredictable, ",
    "feeling fine one moment and unsettled the next."
  ),
  "I experience strong emotions that can shift unexpectedly, often catching me off guard.",
  "I regularly feel uncertain about my ability to manage new responsibilities effectively.",
  "I often question my decisions, fearing they might not lead to the best outcomes.",
  paste0(
    "I frequently find myself reacting with impatience to ",
    "situations perceived as minor interruptions."
  ),
  "Even minor provocations can sometimes lead to an exaggerated sense of annoyance for me.",
  paste0(
    "My emotional state is often inconsistent, and I can feel ",
    "ecstatic or despondent within short timeframes."
  ),
  paste0(
    "I notice that my feelings can be quite volatile and intense, ",
    "affecting how I interact with others throughout the day."
  ),
  "I regularly doubt whether I am capable of achieving my personal or professional goals.",
  "I often seek validation from others to feel reassured about my self-worth.",
  paste0(
    "I am sensitive to disturbances and find my patience wearing ",
    "thin quickly when things aren't orderly."
  ),
  paste0(
    "I occasionally struggle to contain my annoyance over trivial ",
    "issues that disrupt my sense of calm."
  ),
  "I can go from feeling upbeat to being downcast without an obvious cause.",
  "My emotional responses can sometimes be unpredictable, shifting with little notice.",
  "I often feel the need for affirmation about my abilities from friends or colleagues.",
  "I tend to compare myself to others and feel uncertain about my achievements.",
  "I find myself easily bothered by noises or disturbances in my environment.",
  "I get easily flustered by situations that interrupt my planned activities.",
  paste0(
    "I find it challenging to maintain a consistent emotional ",
    "state, regardless of external situations."
  ),
  "My emotional reactions can be intense and differ significantly from moment to moment.",
  "I have a persistent fear of not measuring up to the expectations placed on me.",
  "I often feel anxious about others' perceptions of my capabilities and appearance.",
  "I am quick to express frustration at minor inconveniences in my daily routine.",
  paste0(
    "I find that small, unforeseen events often disrupt my sense ",
    "of calm and lead to irritation."
  ),
  paste0(
    "My emotional reactions can be strong and relentless, ",
    "impacting my behavior throughout the day."
  ),
  paste0(
    "I often find myself emotionally labile, with an inner ",
    "turbulence that others rarely perceive."
  ),
  "I frequently worry about my competence in areas where others seem confident.",
  paste0(
    "I have a tendency to second-guess myself and require ",
    "affirmation to feel reassured about my choices."
  ),
  "Small disruptions can ignite a lingering sense of agitation within me.",
  "I often catch myself feeling irritable even in relatively calm settings.",
  paste0(
    "I find myself swinging from happy to melancholic in a short ",
    "span of time, often surprising even myself."
  ),
  paste0(
    "Others often comment on how quickly my mood can change in ",
    "response to seemingly minor events."
  ),
  paste0(
    "I tend to feel apprehensive about presenting my opinions, ",
    "fearing they may be judged harshly."
  ),
  "I often require reassurance from peers to feel confident in my decisions and ideas.",
  "Interruptions during focused tasks often lead to an outpour of irritation from me.",
  "I struggle to keep my frustration in check when things do not unfold as expected."
)


# Create the item type and attribute labels
item.attributes <- c(
  rep(c("friendly", "positive", "energetic"), each = 2, times = 10),
  rep(c("moody", "insecure", "irritable"), each = 2, times = 10)
)
item.types <- c(
  rep("extraversion", 60),
  rep("neuroticism", 60)
)


# Build your data frame with the required columns: ID, statement, attribute, and type
items_df <- data.frame(
  ID = rep(as.factor(1:length(statements))),
  statement = statements,
  attribute = item.attributes,
  type = item.types
)


# Run GENIE with items you provide with the default local embedding model ("bert-base-uncased")
example_reduction <- local_GENIE(items = items_df)

# View the results
View(example_reduction)


########################################################################################
###### Or, Run local_GENIE with a locally-install Embedding Model of your Choice #######
#######################################################################################

# Provide the path to a compatible locally installed embedding model
# Note that this package will not install the model for you, it should already be
# installed and ready to go
embedding.model <- "ADD YOUR PATH HERE"

# Run GENIE using the Hugging Face Embedding model
example_reduction_your_model <- local_GENIE(items = items_df,
                              embedding.model = embedding.model)


## End(Not run)

Chat with a local LLM (no API calls)

Description

Send one or more prompts to a locally available large-language model (LLM) without making remote API calls. The local model must be installed/available on the machine as a local model directory. This function is intended for fully local inference (no API key required).

Usage

local_chat(
  prompts,
  model.path,
  n.ctx = 4096,
  n.gpu.layers = -1,
  max.tokens = 1024,
  system.role = NULL,
  reps = 1,
  temperature = 1,
  top.p = 1,
  silently = FALSE
)

Arguments

Details

Before running this function check that you are able to run the local environment via check_local_llm_setup().

For each prompt × repetition the function constructs a full_prompt that includes the system.role and the user prompt, sets a deterministic generation seed per generation, and calls the local model. A retry loop (up to 5 attempts, with brief waits) handles transient failures; if all attempts fail the function aborts with an informative error.

Value

A data.frame with one row per generation (i.e., per prompt × repetition) containing:

• rep — repetition index

• prompt — the prompt text sent to the model

• response — the raw text response returned by the model

Important / Warnings

• Local model inference can be resource intensive. Large models may require substantial disk space, RAM, and (optionally) GPU support. Performance and feasibility depend on model size and hardware.

• model.path must point to a model already present; this function will not download remote models.

See Also

chat

Examples

## Not run: 
#################################################
### Example 1: Writing a Very Basic Prompt  #####
#################################################

# For local_chat you do NOT need an API key, but you DO need a text generation
# model available locally.
model <- "path/to/local-model" # replace with your local model path

# Then, write your prompt. This will be given to the model directly.
prompt <- "Why does the planet Saturn have rings? Give a 100 word explanation."

# Optionally, add a system role (a model persona)
system.role <- "You specialize in tutoring astronomy for high school students."

# Add the number of prompt repetitions. By default, this is set to 1. But it
# may be useful to increase the number of repetitions to get a sense of how
# consistent your output might be.
reps <- 3

# Now you are ready to chat with the local model
first_chat <- local_chat(
  model.path = model, # local model identifier or path
  prompts = prompt,
  system.role = system.role,
  reps = reps
)

# Check how the output changes from iteration to iteration
first_chat$response[[1]] # first iteration output
first_chat$response[[2]] # second iteration output
first_chat$response[[3]] # third iteration output


####################################################################
### Example 2: Send multiple prompts in a single function call #####
####################################################################

# You are able to send more than one prompt in a single call
prompt1 <- "Why does the planet Saturn have rings? Give a 100 word explanation."
prompt2 <- "Which planet is the hottest in our solar system? How do we know?"

# Aggregate the prompts in a single object
prompts <- c(prompt1, prompt2)

# Ask the model the questions
second_chat <- local_chat(
  model.path = model, # defined above
  prompts = prompts, # NEW
  system.role = system.role, # defined above
  reps = reps # defined above
)

# The outputted data frame for this example will have 6 rows
# since the number of prompts (2) times the number of reps (3)
# gives a total of 6 generations.
second_chat$response[second_chat$prompt == prompt1] # the responses from prompt 1
second_chat$response[second_chat$prompt == prompt2] # the responses from prompt 2


####################################################################
### Example 3: Send multiple prompts with different System Roles ###
####################################################################

# Perhaps your prompts are not related. In that case, you would probably want
# to set a different system role for each prompt.
prompt2 <- "What is the difference between eukaryotes and prokaryotes? Why?"

# This new second prompt does not fit with the astronomy tutor persona. Let's
# write a persona to match this new prompt topic.
system.role2 <- "You specialize in tutoring biology for middle school students."

# Now, let's combine the system roles into a single object
system.role <- c(system.role, # defined earlier: the astronomy tutor
                 system.role2 # defined above: the biology tutor
                 )

# Aggregate our prompts in a single object again
prompts <- c(prompt1, # Asks about Saturn's rings (needs astronomy tutor)
             prompt2 # Asks about types of cells (needs biology tutor)
             )

# Ask the model the questions
third_chat <- local_chat(
  model.path = model,
  prompts = prompts,
  system.role = system.role,
  reps = reps
)

# View the outputted data frame to examine the responses
View(third_chat)

## End(Not run)

Validate and Normalize main.prompts

Description

Validates that main.prompts is a named list of non-empty strings, one for each attribute in items.attributes, matched by normalized name.

Usage

main.prompts_validate(main.prompts, items.attributes, silently)

Arguments

Value

A cleaned and ordered named list of trimmed prompt strings. Also returns the appropriate 'custom' flag (TRUE if custom ok, FALSE if not)

Check that max.tokens is an integer

Description

Check that max.tokens is an integer

Usage

## S3 method for class 'tokens_validate'
max(max.tokens, silently)

Arguments

Value

if valid, the max.tokens value as an integer object type

Modify Main Prompts with Contextual Enhancements

Description

This function appends structured context and formatting instructions to a list of main prompts used for item generation. It ensures that each prompt includes relevant domain information, audience guidance, scale definitions, JSON formatting rules, and optionally example items or critical author notes – but only if these elements are not already present in the prompt (checked case-insensitively and with whitespace trimmed).

Usage

modify_main.prompts(
  main.prompts,
  item.attributes,
  item.type.definitions,
  domain,
  scale.title,
  prompt.notes,
  audience,
  item.examples
)

Arguments

Value

A modified list of character strings, with each prompt updated to include relevant metadata, instructions, and formatting examples as needed.

Compute pre-reduction item-level network-loading diagnostics

Description

Uses EGAnet::net.loads() on an EGA solution and reports, for each item, the loading on its assigned EGA community, its strongest loading on another community, and the absolute primary-to-cross-loading gap. These statistics are descriptive audit information; they are not item-removal criteria.

Usage

network_loading_diagnostics(ega_object, items)

Arguments

Value

A data frame with one row per item represented in the EGA network.

Normalize Model Name (Legacy Compatibility)

Description

Validates and normalizes model names. This function maintains backward compatibility with existing code.

Converts model names to the standardized format: Provider/model-name Maintains backward compatibility with existing model names.

Usage

normalize_model_name(
  model,
  groq.API = NULL,
  openai.API = NULL,
  anthropic.API = NULL,
  silently = FALSE
)

normalize_model_name(
  model,
  groq.API = NULL,
  openai.API = NULL,
  anthropic.API = NULL,
  silently = FALSE
)

Arguments

Value

Normalized model name string

List with normalized model name and detected provider

Plot Comparisons

Description

Generates a comparative plot of two network analysis results, typically representing the item network before and after AI-GENIE reduction. The plot includes provided captions, displays NMI values for each network, and incorporates a scale title to contextualize the comparison. The layout may be adjusted based on the ident parameter.

Usage

plot_comparison(p1, p2, caption1, caption2, nmi2, nmi1, title)

Arguments

Value

A plot object that visually compares the two network structures. The plot will typically display the two networks (either side-by-side or in an overlaid manner) with the provided captions and NMI values. The exact type of the plot object (e.g., a ggplot object or a base R plot) depends on the implementation.

Plot Stability Comparison (network + item stability dotplot, side by side)

Description

Builds a 4-panel comparison: pre-reduction network + pre-reduction item stability, next to post-reduction network + post-reduction item stability. Mirrors the layout of the AIGENIE simulation/reference figure.

Usage

plot_stability_comparison(boot1, boot2, caption1, caption2, nmi1, nmi2, title)

Arguments

Value

A patchwork object combining the four panels.

Print Results

Description

Displays a summary of the AI-GENIE analysis results, including the EGA model used, embedding type, starting and final number of items, and NMI values before and after reduction. The summary includes the number of iterations for both UVA (Unique Variable Analysis) and bootstrapped EGA steps.

Usage

print_results(obj, obj2, run.overall)

Arguments

Value

No return value; the function prints the results to the console.

Get AI-GENIE Python Environment Info

Description

Returns diagnostic information about the AIGENIE Python environment, including paths, installation status, and installed packages. Useful for troubleshooting Python-related issues.

Usage

python_env_info()

Value

A list with the following elements:

See Also

reinstall_python_env to fix environment issues.

Examples

## Not run: 
# Check environment status
info <- python_env_info()

# Is the environment set up?
info$env_exists

# What packages are installed?
cat(info$installed_packages, sep = "\n")

# Is UV available?
info$uv_available

## End(Not run)

Reduce Redundancy via Iterative UVA (with Redundant Pair Logging)

Description

Applies EGAnet::UVA iteratively and logs human-readable redundant item sets.

Usage

reduce_redundancy_uva(
  embedding_matrix,
  items,
  corr = "auto",
  uva.cut.off = 0.2
)

Arguments

Value

A list with the reduced matrix, sweep metadata, human-readable redundancy groups, and removal_log, a tidy item-level table containing removed IDs, retained redundant partners, and wTO statistics.

Reinstall AI-GENIE Python Environment

Description

Removes and recreates the Python virtual environment with all required dependencies. Use this function if you encounter Python-related errors, want to update Python packages, or need to change the environment configuration.

AIGENIE uses UV (https://docs.astral.sh/uv/) for fast, reliable Python environment management.

Usage

reinstall_python_env(
  include_huggingface = TRUE,
  include_local_llm = FALSE,
  gpu = FALSE
)

Arguments

Value

Invisible TRUE on success.

See Also

python_env_info to check environment status, install_gpu_support for GPU setup, install_local_llm_support for local model setup.

Examples

## Not run: 
# Fix Python environment issues
reinstall_python_env()

# Reinstall with GPU support
reinstall_python_env(gpu = TRUE)

# Minimal install (API-only, no HuggingFace - faster)
reinstall_python_env(include_huggingface = FALSE)

# Full install with local LLM support
reinstall_python_env(include_huggingface = TRUE, include_local_llm = TRUE)

## End(Not run)

Resolve and Normalize Model Name

Description

Accepts a free-form model name and returns a standardized string. Known aliases are resolved to canonical model names. If the model is not recognized, a warning is issued and the cleaned original input is returned.

Usage

resolve_model_name(model, silently)

Arguments

Value

A standardized model name.

Validate and Clean response.options

Description

Validates that response.options is an atomic vector of non-empty strings, with no missing or invalid values. Whitespace is trimmed from each string.

Usage

response.options_validate(response.options)

Arguments

Modify the items data frame to run the reduction on all items together

Description

Modify the items data frame to run the reduction on all items together

Usage

run_all_together(items)

Arguments

Value

A data frame whose attribute and type columns are modified so the entire sample can be analyzed as one item type.

Check that the run.overall and all.together flags are logically consistent with the number of item types.

Description

Check that the run.overall and all.together flags are logically consistent with the number of item types.

Usage

run_flags_validate(run.overall, all.together, item.attributes, silently)

Arguments

Value

a named list with the updated all.together and run.overall flags

Run reduction pipeline for all item types

Description

Run reduction pipeline for all item types

Usage

run_item_reduction_pipeline(
  embedding_matrix,
  items,
  EGA.model = NULL,
  EGA.algorithm = "walktrap",
  EGA.uni.method = "louvain",
  corr = "auto",
  ncores = NULL,
  boot.iter = 500,
  uva.cut.off = 0.2,
  keep.org,
  silently,
  plot
)

Arguments

Value

A named list of pipeline results, one per item type

Run a pooled post-reduction fit across all item types

Description

run.overall = TRUE is a fit-only analysis: it takes the union of items that survived the type-level GENIE reductions and evaluates the pooled structure without applying additional UVA or bootEGA filtering. This is intentionally distinct from all.together = TRUE, which performs reduction on the entire item pool jointly.

Usage

run_pipeline_for_all(
  item_level,
  items,
  embeddings,
  model = NULL,
  algorithm = "walktrap",
  uni.method = "louvain",
  corr = "auto",
  ncores = NULL,
  boot.iter = 500,
  uva.cut.off = 0.2,
  keep.org = FALSE,
  silently,
  plot
)

Arguments

Value

A list with overall_result and success. overall_result contains pooled pre/post EGA fits, NMI values, the union of type-level survivors, a pooled filtering audit, and a pooled reduction summary.

Run full pipeline for a single item type

Description

Run full pipeline for a single item type

Usage

run_pipeline_for_item_type(
  embedding_matrix,
  items,
  type_name,
  model = NULL,
  algorithm = "walktrap",
  uni.method = "louvain",
  corr = "auto",
  ncores = NULL,
  boot.iter = 500,
  uva.cut.off = 0.2,
  keep.org = FALSE,
  silently,
  plot
)

Arguments

Value

A named list containing pipeline results for this type, including a filtering_audit table with one row per removed item and a reduction_summary table describing NMI and item-count changes by stage.

Select Optimal Embedding and EGA Model Based on NMI

Description

Select Optimal Embedding and EGA Model Based on NMI

Usage

select_optimal_embedding(
  embedding_matrix,
  sparse_matrix,
  true_communities,
  model = NULL,
  algorithm = "walktrap",
  uni.method = "louvain",
  corr = "auto"
)

Arguments

Details

Full embeddings are evaluated before sparse embeddings. Therefore, exact within-model NMI ties retain the full representation. When model = NULL, exact cross-model NMI ties prefer TMFG.

Value

A list with best embedding, model, communities, NMI, and comparison log.

Set Hugging Face Token

Description

Configure your HuggingFace API token for accessing gated models like Google's EmbeddingGemma or other restricted models.

Usage

set_huggingface_token(token, save = TRUE)

Arguments

Details

Some embedding models on HuggingFace require authentication:

• google/embeddinggemma-300m

• Other gated models

Before using these models, you must:

1. Create an account at https://huggingface.co

2. Accept the model's license on its model page

3. Generate an access token at https://huggingface.co/settings/tokens

4. Call this function with your token

Value

Invisible TRUE on success.

Examples

## Not run: 
# Set token (saved permanently for future sessions)
set_huggingface_token("hf_xxxxxxxxxxxxxxxxx")

# Set token for this session only (not saved)
set_huggingface_token("hf_xxxxxxxxxxxxxxxxx", save = FALSE)

# Now you can use gated HuggingFace models
results <- GENIE(
  items = my_items,
  embedding.model = "BAAI/bge-large-en-v1.5",
  hf.token = "hf_xxxxxxxxxxxxxxxxx"
)

## End(Not run)

Sparsify Embedding Matrix

Description

Applies sparsification to an embedding matrix by zeroing out values between specified quantiles. Includes fallback strategies if initial sparsification results in all zeros.

Usage

sparsify_embeddings(
  embedding_matrix,
  lower_quantile = 0.025,
  upper_quantile = 0.975,
  fallback_lower = 0.1,
  fallback_upper = 0.9
)

Arguments

Details

Sparsification process:

1. Zero out values between lower and upper quantiles

2. If result is all zeros, try fallback quantiles

3. If still all zeros, return original matrix

silently is always TRUE. It is only set to FALSE for developement and diagnostic purposes.

Value

Sparsified embedding matrix with same dimensions as input

Validate and Expand target.N for Each Item Attribute

Description

Ensures that target.N is either:

• NULL -> defaults to 60 per attribute

• A single integer -> repeated for each attribute

• A list/vector of integers -> must match number of attributes

Usage

target.N_validate(
  target.N,
  items.attributes,
  items.only,
  embeddings.only,
  silently
)

Arguments

Value

A list of integers, one per attribute (named).

Validate temperature for Text Generation

Description

Ensures temperature is a numeric value between 0 and 2

Usage

temperature_validate(temperature)

Arguments

Validate top.p for Text Generation

Description

Ensures top.p is a numeric value between 0 and 1, or NULL.

Usage

top.p_validate(top.p)

Arguments

Validate uva.cut.off

Description

Ensures uva.cut.off is a single numeric value in ⁠[0, 1)⁠.

Usage

uva.cut.off_validate(uva.cut.off)

Arguments

Validate Boolean Arguments

Description

Validates that all arguments passed to the function are scalar boolean values (TRUE or FALSE). If any argument is not a boolean, an error is thrown that identifies the offending variable by name and instructs the user to set it to either TRUE or FALSE.

Usage

validate_booleans(...)

Arguments

Validate EGA Parameters

Description

Validates and normalizes the EGA algorithm, unidimensionality method, and model parameters. Trims whitespace and performs case-insensitive matching. Returns canonical-cased values.

Usage

validate_ega_params(EGA.algorithm, EGA.uni.method, EGA_model)

Arguments

Value

A named list with cleaned and correctly-cased values.

Validate Local Embedding Model

Description

Validates that the embedding model is appropriate for local raw embeddings. Checks for BERT-family models that provide raw feature extraction.

Usage

validate_local_embedding_model(embedding.model, silently = FALSE)

Arguments

Value

The validated model identifier or path

Validate Local Embedding Parameters

Description

Validates parameters specific to local embedding generation

Usage

validate_local_embedding_params(
  device,
  batch.size,
  pooling.strategy,
  max.length
)

Arguments

Value

A list of validated parameters

Validate Local LLM Generation Parameters

Description

Validates parameters specific to local LLM generation

Usage

validate_local_llm_params(n.ctx, n.gpu.layers, max.tokens)

Arguments

Value

A list of validated parameters

Validate Local Model Path

Description

Validate Local Model Path

Usage

validate_model.path(model.path, silently = FALSE)

Arguments

Value

The expanded, validated path

Validate and Normalize prompt.notes

Description

Accepts a string, NULL, or a named list of strings/NULLs. Ensures one entry per attribute in items.attributes, returning a fully named and cleaned list.

Usage

validate_prompt.notes(prompt.notes, items.attributes)

Arguments

Value

A named list of strings, one per attribute, with NULLs replaced by "".

Check that reps is an integer

Description

Check that reps is an integer

Usage

validate_reps(reps)

Arguments

Value

if valid, the reps value as an integer object type

Validate That Inputs Are Strings

Description

Ensures that each argument is a single, non-NA string. Throws an error if any argument is not a character scalar.

Usage

validate_strings(...)

Arguments

Checks system.role and prompts for the chat function

Description

Checks system.role and prompts for the chat function

Usage

validate_system.role_prompts(system.role, prompts)

Arguments

Value

if valid, a list with the system.role and prompts objects

Validate All User Inputs for AI-GENIE

Description

This function performs comprehensive validation and normalization of all user-supplied inputs to the AI-GENIE package. It checks logical flags, strings, model names, item attribute structures, and ensures consistency across all interdependent components.

Usage

validate_user_input_AIGENIE(
  item.attributes,
  openai.API,
  hf.token,
  main.prompts,
  groq.API,
  anthropic.API,
  jina.API,
  model,
  temperature,
  top.p,
  embedding.model,
  target.N,
  domain,
  scale.title,
  item.examples,
  audience,
  item.type.definitions,
  response.options,
  prompt.notes,
  system.role,
  EGA.model,
  EGA.algorithm,
  EGA.uni.method,
  keep.org,
  items.only,
  embeddings.only,
  adaptive,
  run.overall,
  all.together,
  plot,
  silently
)

Arguments

Details

If any input is invalid or misaligned with the package’s expected structure, informative errors or warnings are raised. Cleaned and normalized objects are returned for use downstream.

Value

A named list containing:

target.N

A named list of integers, aligned with item.attributes

EGA.model

Canonical model string or NULL

EGA.uni.method

Canonical unidimensionality method

EGA.algorithm

Canonical community detection algorithm

model

Resolved model string for text generation

item.type.definitions

Cleaned item type definitions (if provided)

item.examples

Cleaned item examples (if provided)

item.attributes

Cleaned and normalized item attributes

prompt.notes

Cleaned and normalized prompt notes (if provided)

main.prompts

Cleaned and normalized main prompts (if provided)

custom

A flag signaling whether we are in custom mode or not

Validate All User Inputs for GENIE

Description

Validate All User Inputs for GENIE

Usage

validate_user_input_GENIE(
  items,
  embedding.matrix,
  openai.API,
  hf.token,
  jina.API,
  embedding.model,
  EGA.model,
  EGA.algorithm,
  EGA.uni.method,
  embeddings.only,
  run.overall,
  all.together,
  plot,
  silently
)

Arguments

Value

A named list containing all validated and normalized parameters

Validate All User Inputs for Local AI-GENIE

Description

Comprehensive validation of all inputs for local model execution. Reuses existing validators where applicable and adds local-specific validations.

Usage

validate_user_input_local_AIGENIE(
  item.attributes,
  model.path,
  embedding.model,
  main.prompts,
  temperature,
  top.p,
  target.N,
  domain,
  scale.title,
  item.examples,
  audience,
  item.type.definitions,
  response.options,
  prompt.notes,
  system.role,
  EGA.model,
  EGA.algorithm,
  EGA.uni.method,
  n.ctx,
  n.gpu.layers,
  max.tokens,
  device,
  batch.size,
  pooling.strategy,
  max.length,
  keep.org,
  items.only,
  embeddings.only,
  adaptive,
  run.overall,
  all.together,
  plot,
  silently
)

Arguments

Value

A list of all validated parameters

Validate All User Inputs for Local GENIE

Description

Validate All User Inputs for Local GENIE

Usage

validate_user_input_local_GENIE(
  items,
  embedding.matrix,
  embedding.model,
  device,
  batch.size,
  pooling.strategy,
  max.length,
  EGA.model,
  EGA.algorithm,
  EGA.uni.method,
  embeddings.only,
  run.overall,
  all.together,
  plot,
  silently
)

Arguments

Value

A list of all validated parameters ready for local GENIE execution