Package 'foundryR'

Description

as_foundry_schema() is a small validation/conversion helper. It returns raw JSON Schema lists unchanged, so code can accept either schemas built with foundryR constructors or hand-written JSON Schema lists. If the ellmer package is installed, ellmer::type_object() specifications are converted to the equivalent strict JSON Schema, so ellmer users can pass their existing type definitions to foundry_extract() and foundry_response().

Usage

as_foundry_schema(x)

Arguments

Value

A JSON Schema represented as an R list.

Examples

schema <- foundry_schema(label = schema_string())
as_foundry_schema(schema)

Description

Apply the Foundry embedding step to new data

Usage

## S3 method for class 'step_foundry_embed'
bake(object, new_data, ...)

Arguments

Value

A tibble with embedding columns added (and optionally original text columns removed)

Description

Create a compact diff of two foundry_codebook objects, including both hashes, a unified diff of instructions, and field-level changes for schema properties and examples. Assign the result to inspect it without console output, or print it to display the diff.

Usage

codebook_diff(old, new)

## S3 method for class 'foundry_codebook_diff'
format(x, ...)

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

Arguments

Value

codebook_diff() returns a character vector of diff lines with class foundry_codebook_diff. format() returns the plain character vector. print() displays the lines and invisibly returns x.

Examples

old <- foundry_codebook(
  name = "support-sentiment",
  version = "1.0.0",
  instructions = "Label the sentiment of support tickets.",
  schema = foundry_schema(sentiment = type_enum(values = c("pos", "neg")))
)
new <- foundry_codebook(
  name = "support-sentiment",
  version = "1.1.0",
  instructions = "Label the sentiment and urgency of support tickets.",
  schema = foundry_schema(
    sentiment = type_enum(values = c("pos", "neg")),
    urgent = type_boolean()
  )
)
diff <- codebook_diff(old, new)
print(diff)

Description

foundry_agent() sends a prompt to the Responses API with user-defined R tools, executes any returned function calls locally, sends matching function_call_output items back to the service, and repeats until the model returns a final answer or max_iterations is reached.

Usage

foundry_agent(
  input,
  tools,
  model = NULL,
  instructions = NULL,
  max_iterations = 8L,
  store = TRUE,
  reasoning_effort = NULL,
  max_output_tokens = NULL,
  temperature = NULL,
  top_p = NULL,
  api_key = NULL,
  endpoint = NULL,
  ...
)

Arguments

Value

A tibble with one row per model response. It includes the standard foundry_response() columns plus iteration, final, and tool_results list-columns for executed R tools.

References

• Responses API function calling: https://learn.microsoft.com/azure/foundry/openai/how-to/responses#function-calling

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and AZURE_FOUNDRY_MODEL
# naming a deployment that supports Responses API function calling.
get_weather <- function(location) {
  list(location = location, temperature = "70 F")
}

weather_tool <- foundry_tool(
  get_weather,
  description = "Get weather for a location",
  parameters = list(
    type = "object",
    properties = list(location = list(type = "string")),
    required = "location"
  )
)

foundry_agent(
  "What is the weather in San Francisco?",
  tools = list(weather_tool)
)

## End(Not run)

Description

Create a named, versioned prompt agent on the project-scoped Agent Service. The agent bundles a model, system instructions, and optional tools so it can later be run by name through foundry_response().

Usage

foundry_agent_create(
  name,
  model = NULL,
  instructions = NULL,
  description = NULL,
  metadata = NULL,
  temperature = NULL,
  top_p = NULL,
  tools = NULL,
  tool_choice = NULL,
  definition = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = "v1"
)

Arguments

Value

A one-row tibble describing the created agent.

Examples

## Not run: 
# Requires a configured Azure project endpoint and credentials,
# plus a model deployment.
foundry_agent_create(
  name = "france-facts",
  model = "gpt-5-nano",
  instructions = "You answer questions about France concisely."
)

## End(Not run)

Description

Delete a Foundry agent

Usage

foundry_agent_delete(
  name,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = "v1"
)

Arguments

Value

A one-row tibble with agent_name, deleted, and raw_agent.

Examples

## Not run: 
# Requires a configured Azure project endpoint and credentials,
# plus an existing agent you can delete.
foundry_agent_delete("france-facts")

## End(Not run)

Description

Retrieve a Foundry agent

Usage

foundry_agent_get(
  name,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = "v1"
)

Arguments

Value

A one-row tibble describing the agent.

Examples

## Not run: 
# Requires a configured Azure project endpoint and credentials,
# plus an existing agent.
foundry_agent_get("france-facts")

## End(Not run)

Description

Build a single conversation turn for the messages argument of foundry_task_adherence().

Usage

foundry_agent_message(
  source,
  role,
  contents = NULL,
  tool_calls = NULL,
  tool_call_id = NULL
)

Arguments

Value

A named list matching the task-adherence message schema.

Examples

foundry_agent_message("Prompt", "User", "How many can I buy?")

Description

Build the agent_reference object used to run a stored Microsoft Foundry agent through foundry_response(). Pass the resulting object (or simply the agent name) to the agent argument of foundry_response().

Usage

foundry_agent_reference(name, version = NULL)

Arguments

Value

A named list describing an agent_reference.

Examples

foundry_agent_reference("my-agent")
foundry_agent_reference("my-agent", version = "2")

Description

Build a single tool definition for the tools argument of foundry_task_adherence().

Usage

foundry_agent_tool(name, description)

Arguments

Value

A named list matching the task-adherence tool schema.

Examples

foundry_agent_tool("order_car", "Buy a particular car model")

Description

Build a single tool-call entry for the tool_calls argument of foundry_agent_message().

Usage

foundry_agent_tool_call(name, id, arguments = "")

Arguments

Value

A named list matching the task-adherence tool-call schema.

Examples

foundry_agent_tool_call("get_credit_card_limit", id = "call_001")

Description

List versions of a Foundry agent

Usage

foundry_agent_versions(
  name,
  limit = NULL,
  after = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = "v1"
)

Arguments

Value

A tibble with one row per agent version.

Examples

## Not run: 
# Requires a configured Azure project endpoint and credentials,
# plus an existing agent.
foundry_agent_versions("france-facts")

## End(Not run)

Description

List Foundry agents

Usage

foundry_agents(
  limit = NULL,
  after = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = "v1"
)

Arguments

Value

A tibble with one row per agent.

Examples

## Not run: 
# Requires a configured Azure project endpoint and credentials.
foundry_agents(limit = 20)

## End(Not run)

Description

Compare model labels with reference labels using accuracy, macro precision/recall/F1, Cohen's kappa, and nominal Krippendorff's alpha for two coders. These metrics describe agreement with the reference labels; they do not establish that the reference labels are valid.

Usage

foundry_agreement(data, estimate, truth)

Arguments

Details

Rows with missing labels in either column are dropped and reported; n is the number of complete pairs. If the estimate and truth label sets differ, a warning reports the labels only seen on one side. Macro metrics use the union of labels in both columns and follow the yardstick convention: classes whose per-class denominator is undefined for a given metric are dropped from that macro average with a warning. If only one category occurs across both columns, kappa and alpha are returned as NA_real_ with a warning.

Value

A tibble with one row per metric.

Examples

labels <- data.frame(
  model = c("yes", "no", "yes"),
  human = c("yes", "no", "no")
)
foundry_agreement(labels, estimate = "model", truth = "human")

Description

Cancel a Microsoft Foundry batch

Usage

foundry_batch_cancel(
  batch_id,
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

A one-row tibble with batch metadata after cancellation.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus the ID of a batch that can be cancelled.
foundry_batch_cancel("batch_abc123")

## End(Not run)

Description

Create a Microsoft Foundry batch

Usage

foundry_batch_create(
  input_file_id,
  endpoint = "/v1/responses",
  completion_window = "24h",
  metadata = NULL,
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

A one-row tibble with batch metadata.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus the ID of an uploaded batch file.
foundry_batch_create("file_abc123", endpoint = "/v1/responses")

## End(Not run)

Description

Retrieve a Microsoft Foundry batch

Usage

foundry_batch_get(
  batch_id,
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

A one-row tibble with batch metadata.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus an existing batch ID.
foundry_batch_get("batch_abc123")

## End(Not run)

Description

Convert a data frame of prompts into a JSON Lines file that can be uploaded with foundry_file_upload(..., purpose = "batch") and submitted with foundry_batch_create().

Usage

foundry_batch_requests(
  data,
  input,
  path,
  model,
  endpoint = "/v1/responses",
  custom_id = NULL,
  body = list(),
  schema = NULL,
  schema_name = "ExtractedData",
  strict = TRUE,
  instructions = NULL,
  body_columns = NULL,
  overwrite = FALSE
)

Arguments

Value

A tibble with the JSONL path, request count, and endpoint.

Examples

local({
  jobs <- data.frame(text = c("Summarize this.", "Extract entities."))
  path <- tempfile(fileext = ".jsonl")
  on.exit(unlink(path))
  foundry_batch_requests(
    jobs, input = "text", path = path, model = "gpt-5-nano"
  )
})

Description

Retrieve a batch, download its output and error JSONL files, and parse each request result into a tibble. Responses, chat-completions, and embeddings payloads are parsed into endpoint-specific columns when possible.

Usage

foundry_batch_results(
  batch_id,
  keep_raw = FALSE,
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

A tibble with one row per batch request.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus an existing batch ID.
foundry_batch_results("batch_abc123")

## End(Not run)

Description

Poll a batch until it reaches a terminal state.

Usage

foundry_batch_wait(
  batch_id,
  interval = 60,
  timeout = Inf,
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

The final one-row batch tibble.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus an existing batch ID. Polling may run for longer than five seconds.
foundry_batch_wait("batch_abc123", interval = 60)

## End(Not run)

Description

List Microsoft Foundry batches

Usage

foundry_batches(
  limit = NULL,
  after = NULL,
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

A tibble with one row per batch.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials.
foundry_batches(limit = 10)

## End(Not run)

Description

Create, list, retrieve, delete, and edit Azure AI Content Safety blocklists.

Usage

foundry_blocklists(endpoint = NULL, api_key = NULL, api_version = "2024-09-01")

foundry_blocklist_create(
  name,
  description = NULL,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

foundry_blocklist_get(
  name,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

foundry_blocklist_delete(
  name,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

foundry_blocklist_items(
  name,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

foundry_blocklist_add_items(
  name,
  items,
  is_regex = FALSE,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

foundry_blocklist_remove_items(
  name,
  item_ids,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

Arguments

Value

Blocklist list, create, and get functions return name, description, and raw_blocklist. Item list and add functions return item_id, text, is_regex, and raw_item. Delete returns name, deleted, and raw_blocklist; remove returns name, removed, and raw_response.

Examples

# Requires a configured Azure Content Safety endpoint and credentials
# with permission to create and delete the example blocklist.
if (interactive() &&
    nzchar(Sys.getenv("AZURE_CONTENT_SAFETY_ENDPOINT")) &&
    nzchar(Sys.getenv("AZURE_CONTENT_SAFETY_KEY"))) {
  foundry_blocklists()
  foundry_blocklist_create("example-blocklist", description = "Example")
  foundry_blocklist_get("example-blocklist")
  items <- foundry_blocklist_add_items("example-blocklist", "blocked phrase")
  foundry_blocklist_items("example-blocklist")
  if (nrow(items) > 0 && !is.na(items$item_id[[1]])) {
    foundry_blocklist_remove_items("example-blocklist", items$item_id)
  }
  foundry_blocklist_delete("example-blocklist")
}

Description

Delete cached embeddings written by step_foundry_embed() with cache = "disk".

Usage

foundry_cache_clear(cache_dir = NULL)

Arguments

Value

Invisibly, the number of cache files removed.

Examples

local({
  cache_dir <- tempfile("foundryR-cache-")
  dir.create(cache_dir)
  on.exit(unlink(cache_dir, recursive = TRUE))
  saveRDS(c(1, 0, 0), file.path(cache_dir, "example.rds"))
  foundry_cache_clear(cache_dir)
})

Description

Send a message to a Microsoft Foundry deployed model and receive a response. Returns a tibble with the assistant's response and usage metadata.

Usage

foundry_chat(
  message,
  system = NULL,
  model = NULL,
  history = NULL,
  temperature = NULL,
  max_tokens = NULL,
  max_completion_tokens = NULL,
  top_p = NULL,
  frequency_penalty = NULL,
  presence_penalty = NULL,
  stop = NULL,
  reasoning_effort = NULL,
  api = c("v1", "deployment"),
  api_key = NULL,
  api_version = NULL,
  ...
)

Arguments

Value

A tibble with columns:

role

Character. Always "assistant".

content

Character. The generated response text.

model

Character. The deployment/model name used.

finish_reason

Character. Why generation stopped: "stop", "length", etc.

prompt_tokens

Integer. Tokens in the prompt.

completion_tokens

Integer. Tokens in the response.

reasoning_tokens

Integer. Hidden reasoning tokens, when reported.

cached_input_tokens

Integer. Cached prompt tokens, when reported.

total_tokens

Integer. Total tokens used.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and AZURE_FOUNDRY_MODEL
# naming a chat deployment that supports the requested parameters.
# Simple chat
foundry_chat("What is the capital of France?")

# With system prompt
foundry_chat(
  "Explain tibbles",
  system = "You are a helpful R programming tutor. Be concise."
)

# With parameters (use max_completion_tokens for newer models)
foundry_chat(
  "Write a haiku about data science",
  temperature = 0.9,
  max_completion_tokens = 100
)

# With conversation history
history <- list(
  list(role = "user", content = "My name is Alex"),
  list(role = "assistant", content = "Hello Alex! How can I help you?")
)
foundry_chat("What's my name?", history = history)

## End(Not run)

Description

Validates your Microsoft Foundry configuration and provides helpful guidance if anything is missing or misconfigured.

Usage

foundry_check_setup(model = NULL, verbose = TRUE)

Arguments

Value

Invisibly returns a list with configuration status:

endpoint

The configured endpoint URL, or NA if not set.

project_endpoint

The configured project endpoint URL, or NA if not set.

key_set

Logical. TRUE if an API key is configured.

token_set

Logical. TRUE if a bearer token is configured.

token_provider_set

Logical. TRUE if a resource-scoped bearer token provider is configured.

project_auth_set

Logical. TRUE if a project-scoped Microsoft Entra ID token or provider is configured, NA if no project endpoint is set.

model_tested

The deployment name tested, or NA if none.

api_ok

Logical. TRUE if the API test succeeded, NA if not tested.

all_ok

Logical. TRUE if all checks passed.

Examples

if (requireNamespace("withr", quietly = TRUE)) {
  withr::with_options(list(foundryR.config_file = tempfile()), {
    withr::with_envvar(c(
      AZURE_FOUNDRY_ENDPOINT = "https://example.openai.azure.com",
      AZURE_FOUNDRY_KEY = "example-key-not-a-secret",
      AZURE_FOUNDRY_TOKEN = "",
      AZURE_OPENAI_TOKEN = ""
    ), {
      status <- foundry_check_setup(verbose = FALSE)
      status$all_ok
    })
  })
}

## Not run: 
# Requires an Azure deployment, endpoint, and credentials; makes an API call.
foundry_check_setup(model = "my-gpt4")

## End(Not run)

Description

A codebook records the instructions, JSON Schema, examples, semantic version, creation time, and deterministic SHA-256 hash for an LLM annotation instrument. The hash is computed from a canonical JSON serialization of instructions, schema, examples, and version, in that order. Before serialization, schema arrays are preserved with the same internal helper used by structured outputs so single-value enum and required arrays do not collapse to scalars. The payload is serialized with jsonlite::toJSON(auto_unbox = TRUE, digits = NA, null = "null"), normalized with enc2utf8(), and hashed with SHA-256.

Usage

foundry_codebook(name, version, instructions, schema, examples = NULL)

Arguments

Value

A foundry_codebook object.

Examples

codebook <- foundry_codebook(
  name = "ai-applicability",
  version = "1.0.0",
  instructions = "Label whether the task could use AI assistance.",
  schema = foundry_schema(
    ai_applicable = type_boolean("AI could materially assist the task")
  ),
  examples = list(
    list(text = "Draft a memo", ai_applicable = TRUE),
    list(text = "Lift a heavy box", ai_applicable = FALSE)
  )
)

Description

Run the same extraction multiple times and summarize how often each input receives the same structured result. Use batch execution externally for large jobs; this helper intentionally keeps the local loop simple.

Usage

foundry_consistency(text, schema, n = 3L, ...)

Arguments

Details

The comparison covers the whole structured record after canonical JSON serialization: object names are sorted recursively, arrays keep their order, and numbers are serialized with digits = NA. Only successful runs count toward modal_share and entropy; failed runs are reported separately. With n runs, modal_share can only take values k / n. Entropy is the plug-in estimate in bits, has maximum log2(n), and is biased low for small n. Sampling settings passed through ... define what a repeat means. Stability is not accuracy: a model can be consistently wrong.

Value

A tibble with one row per input.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and AZURE_FOUNDRY_MODEL
# naming a deployment that supports structured outputs.
schema <- foundry_schema(label = schema_enum(c("yes", "no")))
foundry_consistency(c("Example text"), schema, n = 3)

## End(Not run)

Description

Create, list, retrieve, update, and delete server-side conversations used by the Responses API.

Usage

foundry_conversation_create(
  metadata = NULL,
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  project_endpoint = NULL
)

foundry_conversations(
  limit = NULL,
  after = NULL,
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  project_endpoint = NULL
)

foundry_conversation_get(
  conversation_id,
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  project_endpoint = NULL
)

foundry_conversation_update(
  conversation_id,
  metadata = NULL,
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  project_endpoint = NULL
)

foundry_conversation_delete(
  conversation_id,
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  project_endpoint = NULL
)

foundry_conversation_items(
  conversation_id,
  limit = NULL,
  after = NULL,
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  project_endpoint = NULL
)

foundry_conversation_items_add(
  conversation_id,
  items,
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  project_endpoint = NULL
)

Arguments

Details

Conversations exist only on a Foundry project endpoint, so these functions always use one: project_endpoint if you pass it, otherwise the endpoint set with foundry_set_project_endpoint().

Value

Conversation create, list, get, and update functions return conversation_id, object, created_at, metadata, and raw_conversation. Delete returns conversation_id, deleted, and raw_conversation. Item functions return item_id, type, role, content, and raw_item.

Examples

# Requires a configured project endpoint and credentials with permission
# to create and delete the conversation.
if (interactive() &&
    nzchar(Sys.getenv("AZURE_FOUNDRY_PROJECT_ENDPOINT"))) {
  conversation <- foundry_conversation_create(
    metadata = list(example = "cran")
  )
  id <- conversation$conversation_id[[1]]
  foundry_conversations(limit = 10)
  foundry_conversation_get(id)
  foundry_conversation_update(id, metadata = list(example = "updated"))
  foundry_conversation_items(id)
  foundry_conversation_delete(id)
}

Description

Generate embedding vectors for one or more text inputs using an Azure AI Foundry deployed embedding model. Returns a tibble with the input text and corresponding embedding vectors stored as a list-column.

Usage

foundry_embed(
  text,
  model = NULL,
  dimensions = NULL,
  batch_size = 100L,
  api = c("v1", "deployment"),
  api_key = NULL,
  api_version = NULL
)

Arguments

Details

Important: The model parameter must be a deployment of an embedding model, not a chat model. Common embedding models include:

• text-embedding-ada-002

• text-embedding-3-small

• text-embedding-3-large

Chat models (GPT-4, Claude, Llama, etc.) cannot generate embeddings. If you only have chat models deployed, you'll need to deploy an embedding model in Microsoft Foundry first.

Value

A tibble with columns:

text

Character. The original input text.

embedding

List. A numeric vector containing the embedding.

n_dims

Integer. The dimensionality of the embedding.

.input_idx

Integer. Original input index.

.error

Logical. Whether the row failed.

.error_msg

Character. Error message for failed rows.

raw_response

List. Raw parsed response payload for successful rows, or NULL for failed rows.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus embedding deployments.
# Single text
foundry_embed("Hello, world!", model = "text-embedding-ada-002")

# Multiple texts
texts <- c("Data science is fun", "R is great for statistics")
foundry_embed(texts, model = "text-embedding-ada-002")

# With reduced dimensions (model-dependent)
foundry_embed("Hello", model = "text-embedding-3-small", dimensions = 256)

## End(Not run)

Description

Generate embedding vectors for a large collection of texts using parallel batch processing. This function is optimized for high-throughput embedding generation, using httr2::req_perform_parallel() to process multiple batches concurrently while tracking errors gracefully.

Usage

foundry_embed_batch(
  text,
  model = NULL,
  dimensions = NULL,
  batch_size = 100L,
  max_active = 2L,
  progress = getOption("foundryR.progress", interactive()),
  api = c("v1", "deployment"),
  api_key = NULL,
  api_version = NULL
)

Arguments

Value

A tibble with columns:

.input_idx

Integer. The original index of each text in the input vector.

text

Character. The original input text.

embedding

List. A numeric vector containing the embedding, or NULL if failed. May contain multiple embeddings per batch response.

n_dims

Integer. The dimensionality of the embedding, or NA if failed.

.error

Logical. TRUE if the request for this text failed.

.error_msg

Character. Error message if failed, NA otherwise.

raw_response

List. Raw parsed response payload for successful rows, or NULL for failed rows.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus an embedding deployment.
# Embed many texts in parallel
texts <- c("Hello, world!", "Data science is fun", "R is great")
embeddings <- foundry_embed_batch(texts, model = "text-embedding-ada-002")

# With custom batch size and concurrency
large_texts <- rep("Sample text", 1000)
embeddings <- foundry_embed_batch(
  large_texts,
  model = "text-embedding-ada-002",
  batch_size = 50,
  max_active = 2
)

# Filter successful embeddings
successful <- embeddings[!embeddings$.error, ]

# Check for errors
failed <- embeddings[embeddings$.error, ]
if (nrow(failed) > 0) {
  message("Some embeddings failed:")
  print(failed[, c(".input_idx", ".error_msg")])
}

## End(Not run)

Description

Create an evaluation group that pairs a data-source configuration with one or more graders (testing_criteria). Evaluations are run against data with foundry_eval_run_create().

Usage

foundry_eval_create(
  name = NULL,
  data_source_config,
  testing_criteria,
  metadata = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A one-row tibble describing the created evaluation.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials with evals API access.
foundry_eval_create(
  name = "qa-accuracy",
  data_source_config = foundry_eval_data_config(
    type = "custom",
    item_schema = list(
      type = "object",
      properties = list(answer = list(type = "string")),
      required = list("answer")
    ),
    include_sample_schema = TRUE
  ),
  testing_criteria = foundry_grader_string_check(
    name = "exact",
    input = "{{sample.output_text}}",
    reference = "{{item.answer}}",
    operation = "eq"
  )
)

## End(Not run)

Description

Describe the shape of the data an evaluation expects. type = "custom" declares an item schema you populate per run; type = "logs" sources rows from stored completions matching a metadata filter; type = "azure_ai_source" lets Microsoft Foundry supply the rows for a service scenario, such as stored responses.

Usage

foundry_eval_data_config(
  type = c("custom", "logs", "azure_ai_source"),
  item_schema = NULL,
  include_sample_schema = FALSE,
  metadata = NULL,
  scenario = NULL
)

Arguments

Value

A named list describing a data_source_config, for use in foundry_eval_create().

Examples

foundry_eval_data_config(
  type = "custom",
  item_schema = list(
    type = "object",
    properties = list(
      question = list(type = "string"),
      answer = list(type = "string")
    ),
    required = list("question", "answer")
  ),
  include_sample_schema = TRUE
)

foundry_eval_data_config(type = "azure_ai_source", scenario = "responses")

Description

Delete an evaluation

Usage

foundry_eval_delete(
  eval_id,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Details

The returned deleted column is the service's answer. On the resource endpoint the service confirms deletion. On a project endpoint it has been observed to answer deleted = FALSE and keep the evaluation, in which case a warning says so; delete it in the Foundry portal if you need it gone.

Value

A one-row tibble with eval_id, deleted, and object.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus an existing evaluation you can delete.
foundry_eval_delete("eval_abc123")

## End(Not run)

Description

Retrieve an evaluation

Usage

foundry_eval_get(
  eval_id,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A one-row tibble describing the evaluation.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and an evaluation ID.
foundry_eval_get("eval_abc123")

## End(Not run)

Description

Model-based graders (foundry_grader_label_model() and foundry_grader_score_model()) accept an input list of message-shaped items. Each item has a role and content, and the content may embed template references such as {{item.question}} or {{sample.output_text}} that Azure resolves per row at evaluation time.

Usage

foundry_eval_item(
  content,
  role = c("user", "assistant", "system", "developer")
)

Arguments

Value

A named list with role and content, ready to place in a grader input list.

Examples

foundry_eval_item("Grade this answer: {{sample.output_text}}", role = "user")

Description

Cancel an evaluation run

Usage

foundry_eval_run_cancel(
  eval_id,
  run_id,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A one-row tibble describing the run after cancellation.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials, an evaluation ID,
# and a run ID that can be cancelled.
foundry_eval_run_cancel("eval_abc123", "evalrun_xyz")

## End(Not run)

Description

Run an evaluation against a data source. The eval's testing_criteria are applied to every row in the source.

Usage

foundry_eval_run_create(
  eval_id,
  data_source,
  name = NULL,
  metadata = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A one-row tibble describing the created run.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials, an evaluation ID,
# and an uploaded JSONL file matching its data-source configuration.
foundry_eval_run_create(
  eval_id = "eval_abc123",
  data_source = foundry_eval_run_data(file_id = "file-xyz"),
  name = "nightly"
)

## End(Not run)

Description

Point an evaluation run at its rows. Three shapes are supported:

Usage

foundry_eval_run_data(
  file_id = NULL,
  content = NULL,
  target = NULL,
  input_messages = NULL,
  response_ids = NULL
)

Arguments

Details

• Dataset rows (type = "jsonl"): supply exactly one of file_id or content. Graders read existing fields with ⁠{{item.<field>}}⁠.

• Target generation (type = "azure_ai_target_completions"): also supply target and input_messages. Microsoft Foundry sends each row to a model deployment or agent and graders read the generated output with {{sample.output_text}} or, for agents, {{sample.output_items}} (structured output including tool calls).

• Stored responses (type = "azure_ai_responses"): supply only response_ids. Foundry retrieves each stored response and graders score it. Pair it with foundry_eval_data_config(type = "azure_ai_source", scenario = "responses").

Target and stored-response runs exist only on a Foundry project endpoint. foundry_eval_run_create() and foundry_evaluate() use the configured project endpoint for them and say so.

Value

A named list describing a run data source, for use in foundry_eval_run_create().

Examples

foundry_eval_run_data(file_id = "file-abc123")

foundry_eval_run_data(content = list(
  list(item = list(question = "2+2?", answer = "4"))
))

foundry_eval_run_data(
  content = list(list(item = list(query = "What is R?"))),
  target = "gpt-5-mini",
  input_messages = "{{item.query}}"
)

foundry_eval_run_data(response_ids = c("resp_abc123", "resp_def456"))

Description

Retrieve an evaluation run

Usage

foundry_eval_run_get(
  eval_id,
  run_id,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A one-row tibble describing the run, including aggregate result counts.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and evaluation/run IDs.
foundry_eval_run_get("eval_abc123", "evalrun_xyz")

## End(Not run)

Description

Return the per-row grader results for a completed run. The result is unnested to one row per grader outcome, so a row that was scored by three graders yields three rows. The service returns output items in pages; this function follows the pagination cursor, so by default every output item is returned.

Usage

foundry_eval_run_output_items(
  eval_id,
  run_id,
  status = NULL,
  order = NULL,
  limit = NULL,
  after = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A tibble with one row per grader result, including score, label, passed, and reason where the grader supplies them.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials, an evaluation ID,
# and a completed run ID.
foundry_eval_run_output_items("eval_abc123", "evalrun_xyz")

## End(Not run)

Description

Retrieve every output item of a completed run and join the grader results to the data frame that was evaluated with foundry_evaluate(). Rows are matched only through the foundryr_row_id field that foundry_evaluate() adds to each item, and the echoed item fields are checked against data, so passing a reordered or different data frame is an error rather than a silent mismatch.

Usage

foundry_eval_run_results(
  eval_id,
  run_id,
  data,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A tibble with one row per row of data and grader, in the row order of data. It contains every column of data followed by:

.eval_id, .run_id, .output_item_id

Evaluation, run, and output item identifiers.

.status

Output item status reported by the service.

.grader, .grader_type, .metric

Grader name, type, and metric. .grader is the name you gave the grader; the resource endpoint's appended ID is removed.

.score, .label, .passed, .threshold, .reason

Grader result. Not every grader reports every field. For label_model and score_model graders, .label is the judge's chosen label and .reason joins the conclusions of the judge's reasoning steps.

.output_text, .output_items

The generated response for target runs: plain text and the structured output (a list-column).

Rows of data without an output item are kept with missing result fields, with a warning. The final run tibble, including per-criterion pass rates, target latency, and estimated target cost, is attached as the "run" attribute.

Examples

## Not run: 
# Requires a configured Foundry endpoint and credentials, plus a completed
# run started by foundry_evaluate(tickets, ..., wait = FALSE).
foundry_eval_run_results("eval_abc123", "evalrun_xyz", data = tickets)

## End(Not run)

Description

Poll an evaluation run until it reaches a terminal state ("completed", "failed", or "canceled").

Usage

foundry_eval_run_wait(
  eval_id,
  run_id,
  interval = 10,
  timeout = Inf,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

The final one-row run tibble from foundry_eval_run_get(). Check its status column: failed and canceled runs are returned, not raised.

Examples

## Not run: 
# Requires a configured Foundry endpoint and credentials, plus an evaluation
# run. Polling may take several minutes.
foundry_eval_run_wait("eval_abc123", "evalrun_xyz", interval = 15)

## End(Not run)

Description

List evaluation runs

Usage

foundry_eval_runs(
  eval_id,
  status = NULL,
  order = NULL,
  limit = NULL,
  after = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A tibble with one row per run.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and an evaluation ID.
foundry_eval_runs("eval_abc123", status = "completed")

## End(Not run)

Description

List evaluations

Usage

foundry_evals(
  limit = NULL,
  after = NULL,
  order = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A tibble with one row per evaluation.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials with evals API access.
foundry_evals(limit = 10)

## End(Not run)

Description

Run a Microsoft Foundry cloud evaluation from a data frame and get the grader results back joined to your rows. foundry_evaluate() creates the evaluation, starts a run, waits for it, and returns one row per input row and grader, so pass rates, failure reasons, and generated responses can be summarised with ordinary data-frame tools.

There are two modes:

• Grade existing columns (target = NULL). Graders read fields of data with ⁠{{item.<column>}}⁠, for example a response column that your application already produced.

• Generate, then grade (target supplied). Foundry sends input for each row to a model deployment or agent, then graders read the generated output with {{sample.output_text}} or, for agents, {{sample.output_items}} (structured output including tool calls).

Usage

foundry_evaluate(
  data,
  graders = NULL,
  target = NULL,
  input = NULL,
  instructions = NULL,
  sampling_params = NULL,
  item_schema = NULL,
  eval_id = NULL,
  name = NULL,
  metadata = NULL,
  wait = TRUE,
  interval = 10,
  timeout = Inf,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  project_endpoint = NULL
)

Arguments

Details

foundry_evaluate() creates a persistent evaluation and run in your project; both stay visible in the Foundry portal and nothing is deleted afterwards. Target generation and model-graded evaluators consume tokens on your deployments.

Evaluations that only use OpenAI graders on existing columns run on the resource endpoint by default. Built-in evaluators and model or agent targets exist only on a Foundry project endpoint, so those evaluations use the endpoint set with foundry_set_project_endpoint() and print a message. Pass the same project_endpoint (or call foundry_set_route()) when you look the evaluation up later.

Every item sent to the service carries a reserved foundryr_row_id field ("row-1", "row-2", ...), and results are matched to rows of data only through that field as the service echoes it back. Results are never matched by position. Column types map to JSON Schema types (character and factor to string, logical to boolean, integer to integer, finite double to number, list columns of named lists to object, other list columns to array). Missing values are rejected rather than silently dropped; recode them first. Supply item_schema when a list column needs a more specific schema.

In target runs, a character column that holds only numeric-looking values (such as ZIP codes) triggers a warning, because the service can convert such strings to numbers and then reject them.

Before anything is created, every ⁠{{item.<field>}}⁠ reference in the graders and input is checked against the columns of data.

Value

With wait = TRUE, the tibble returned by foundry_eval_run_results(). With wait = FALSE, the one-row run tibble returned by foundry_eval_run_create().

See Also

foundry_eval_run_results() for the result columns, vignette("evaluations", package = "foundryR") for a worked example.

Examples

## Not run: 
# Requires a Foundry project endpoint and credentials, plus deployments for
# the target and the judge model.
tickets <- data.frame(
  ticket = c("I was charged twice this month.", "The app crashes on login."),
  label = c("billing", "technical")
)

foundry_evaluate(
  tickets,
  graders = foundry_grader_string_check(
    name = "label-match",
    input = "{{sample.output_text}}",
    reference = "{{item.label}}",
    # "ilike" passes when the output contains the label, ignoring case.
    operation = "ilike"
  ),
  target = "gpt-5-mini",
  input = "ticket",
  instructions = "Reply with one word: billing, technical, or account."
)

## End(Not run)

Description

Apply a JSON Schema to one or more text inputs and return model-extracted fields as a tidy tibble. This is useful for research coding tasks such as sentiment annotation, entity extraction, study abstraction, and converting free-text records into analyzable variables.

Usage

foundry_extract(
  text,
  schema = NULL,
  text_col = NULL,
  instructions = NULL,
  schema_name = "ExtractedData",
  strict = TRUE,
  model = NULL,
  flatten = TRUE,
  store = FALSE,
  max_active = 2L,
  progress = getOption("foundryR.progress", interactive()),
  api_key = NULL,
  endpoint = NULL,
  token = NULL,
  ...
)

Arguments

Value

A tibble with one row per input text. Metadata columns are prefixed with ., followed by extracted schema fields when flatten = TRUE.

References

• Structured outputs: https://learn.microsoft.com/azure/foundry/openai/how-to/structured-outputs

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and AZURE_FOUNDRY_MODEL
# naming a deployment that supports structured outputs.
schema <- list(
  type = "object",
  properties = list(
    sentiment = list(type = "string", enum = c("positive", "negative", "neutral")),
    entities = list(type = "array", items = list(type = "string"))
  ),
  required = c("sentiment", "entities"),
  additionalProperties = FALSE
)

foundry_extract(
  c("I love using R with Azure.", "The workflow was slow and confusing."),
  schema = schema
)

## End(Not run)

Description

Prepare JSONL requests for structured extraction, upload them, and create a batch. With wait = TRUE, waits for completion and returns parsed results joined back to the input rows.

Usage

foundry_extract_batch(
  data,
  text_col,
  schema,
  model,
  wait = FALSE,
  path = tempfile(fileext = ".jsonl"),
  schema_name = "ExtractedData",
  strict = TRUE,
  instructions = NULL,
  completion_window = "24h",
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

A batch tibble when wait = FALSE, or parsed result rows when wait = TRUE.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and a batch deployment.
local({
  jobs <- data.frame(text = c("Great service.", "Slow support."))
  schema <- foundry_schema(sentiment = schema_string())
  path <- tempfile(fileext = ".jsonl")
  on.exit(unlink(path))
  foundry_extract_batch(
    jobs, text_col = "text", schema = schema,
    model = "gpt-5-nano", path = path
  )
})

## End(Not run)

Description

Download a completed extraction batch, parse structured Responses API output with the same schema-driven flattening rules as foundry_extract(), and join results back to the original input rows using the row-N custom IDs written by foundry_batch_requests().

Usage

foundry_extract_batch_results(
  batch_id,
  data,
  schema,
  text_col = NULL,
  keep_raw = FALSE,
  api_key = NULL,
  token = NULL,
  endpoint_url = NULL,
  api_version = NULL
)

Arguments

Value

A tibble containing the caller's input columns, extracted schema fields, and dot-prefixed extraction metadata.

Examples

## Not run: 
schema <- foundry_schema(sentiment = schema_string())
jobs <- data.frame(text = c("Great service.", "Slow support."))
foundry_extract_batch_results("batch_abc123", jobs, schema)

## End(Not run)

Description

Delete a Microsoft Foundry file

Usage

foundry_file_delete(
  file_id,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A tibble with deletion status.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials,
# plus the ID of a file you can delete.
foundry_file_delete("file_abc123")

## End(Not run)

Description

Download Microsoft Foundry file content

Usage

foundry_file_download(
  file_id,
  path,
  overwrite = FALSE,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A tibble with the local path, number of bytes written, and file ID.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and an uploaded file ID.
local({
  path <- tempfile(fileext = ".jsonl")
  on.exit(unlink(path))
  foundry_file_download("file_abc123", path)
})

## End(Not run)

Description

Retrieve a Microsoft Foundry file

Usage

foundry_file_get(
  file_id,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A one-row tibble with file metadata.

Examples

## Not run: 
# Requires a configured Azure endpoint, credentials, and an uploaded file ID.
foundry_file_get("file_abc123")

## End(Not run)

Description

Upload a local file for use with Foundry APIs such as Batch, fine-tuning, evals, or assistants/file-search workflows.

Usage

foundry_file_upload(
  path,
  purpose = c("assistants", "batch", "fine-tune", "evals"),
  expires_after_seconds = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Details

Files live on the endpoint where you upload them. Server-side agents search files on the project endpoint, so upload files for an agent's vector store with project_endpoint (or after foundry_set_route("project")).

Value

A one-row tibble with file metadata.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials.
local({
  path <- tempfile(fileext = ".jsonl")
  on.exit(unlink(path))
  jobs <- data.frame(text = "Summarize this.")
  foundry_batch_requests(
    jobs, input = "text", path = path, model = "gpt-5-nano"
  )
  foundry_file_upload(path, purpose = "batch")
})

## End(Not run)

Description

List uploaded Microsoft Foundry files

Usage

foundry_files(
  purpose = NULL,
  limit = NULL,
  order = NULL,
  after = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL,
  project_endpoint = NULL
)

Arguments

Value

A tibble with one row per file.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials.
foundry_files(purpose = "batch", limit = 10)

## End(Not run)

Description

Retrieve the endpoint URL from the environment or a provided value.

Usage

foundry_get_endpoint(endpoint = NULL, required = FALSE)

Arguments

Value

The endpoint URL string, or NULL if not found and not required.

Examples

foundry_get_endpoint("https://example.openai.azure.com/")

Description

Retrieve the project endpoint URL from the environment or a provided value.

Usage

foundry_get_project_endpoint(endpoint = NULL, required = FALSE)

Arguments

Value

The project endpoint URL string, or NULL.

Examples

foundry_get_project_endpoint(
  "https://example.services.ai.azure.com/api/projects/demo"
)

Description

Reference a Microsoft Foundry built-in evaluator (a ⁠builtin.*⁠ ID such as builtin.coherence or builtin.groundedness) as a grader. Built-in evaluators run only on a Foundry project endpoint; foundry_eval_create() and foundry_evaluate() switch to it when a grader of this type is present.

Usage

foundry_grader_azure_ai(
  name,
  evaluator_name,
  initialization_parameters = NULL,
  data_mapping = NULL,
  evaluator_version = NULL
)

Arguments

Value

A named list describing an azure_ai_evaluator grader.

Examples

foundry_grader_azure_ai(
  name = "coherence",
  evaluator_name = "builtin.coherence",
  initialization_parameters = list(deployment_name = "gpt-5-mini"),
  data_mapping = list(
    query = "{{item.query}}",
    response = "{{sample.output_text}}"
  )
)

Description

Use a model to assign one of a fixed set of labels to each row, then treat a subset of those labels as passing. The model must support structured outputs.

Usage

foundry_grader_label_model(name, model, input, labels, passing_labels)

Arguments

Value

A named list describing a label_model grader.

Examples

foundry_grader_label_model(
  name = "relevance-label",
  model = "gpt-5-nano",
  input = list(
    foundry_eval_item("Is the answer relevant? {{sample.output_text}}")
  ),
  labels = c("relevant", "irrelevant"),
  passing_labels = "relevant"
)

Description

Use a model to assign a numeric score to each row. Rows at or above pass_threshold pass. Scores fall within range, which defaults to c(0, 1).

Usage

foundry_grader_score_model(
  name,
  model,
  input,
  pass_threshold = NULL,
  range = NULL
)

Arguments

Value

A named list describing a score_model grader.

Examples

foundry_grader_score_model(
  name = "helpfulness",
  model = "gpt-5-nano",
  input = list(
    foundry_eval_item("Rate helpfulness 0-1: {{sample.output_text}}")
  ),
  pass_threshold = 0.7
)

Description

Compare a templated input string against a reference string with an exact or pattern operation. Useful for deterministic pass/fail checks such as verifying an extracted field matches a known value.

Usage

foundry_grader_string_check(
  name,
  input,
  reference,
  operation = c("eq", "ne", "like", "ilike")
)

Arguments

Value

A named list describing a string_check grader, for use in the testing_criteria of foundry_eval_create().

Examples

foundry_grader_string_check(
  name = "exact-match",
  input = "{{sample.output_text}}",
  reference = "{{item.answer}}",
  operation = "eq"
)

Description

Grade output text against a reference using a similarity metric such as fuzzy matching, BLEU, ROUGE, or METEOR. A row passes when its score is at least pass_threshold.

Usage

foundry_grader_text_similarity(
  input,
  reference,
  pass_threshold,
  evaluation_metric = c("fuzzy_match", "bleu", "gleu", "meteor", "rouge_1", "rouge_2",
    "rouge_3", "rouge_4", "rouge_5", "rouge_l"),
  name = NULL
)

Arguments

Value

A named list describing a text_similarity grader.

Examples

foundry_grader_text_similarity(
  input = "{{sample.output_text}}",
  reference = "{{item.answer}}",
  pass_threshold = 0.8,
  evaluation_metric = "fuzzy_match"
)

Description

Check whether an LLM-generated response is grounded in the provided source documents using the Azure AI Content Safety groundedness detection API. This helps identify hallucinations or unsupported claims in AI-generated text.

Usage

foundry_groundedness(
  text,
  grounding_sources,
  query = NULL,
  domain = c("Generic", "Medical"),
  task = c("QnA", "Summarization"),
  reasoning = FALSE,
  correction = FALSE,
  llm_resource = NULL,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-15-preview"
)

Arguments

Details

Authentication

This function uses Azure Content Safety credentials, which are separate from the Azure OpenAI credentials used by other foundryR functions.

Set environment variables:

AZURE_CONTENT_SAFETY_ENDPOINT=<your Content Safety endpoint URL>
AZURE_CONTENT_SAFETY_KEY=your-api-key

Or pass endpoint and api_key directly to the function.

Task Types

• QnA: Use when checking an answer to a specific question. The query parameter provides context about what question was being answered.

• Summarization: Use when checking a summary of source documents. The query parameter is optional.

Domain Settings

• Generic: Default setting for most use cases.

• Medical: Use for healthcare-related content. May apply stricter groundedness requirements.

Value

A tibble with one row containing:

grounded

Logical. TRUE if the text is fully grounded (no ungrounded content detected). FALSE if any ungrounded segments were found.

grounded_pct

Numeric. The percentage of text that is grounded (1 - ungroundedPercentage). Value between 0 and 1.

ungrounded_pct

Numeric. The percentage of text that is ungrounded. Value between 0 and 1.

ungrounded_segments

List. A character vector of text segments identified as ungrounded. Empty character vector if fully grounded.

ungrounded_reasons

List. A character vector, aligned with ungrounded_segments, holding the model's explanation for each segment when reasoning = TRUE. NA entries appear when no explanation was returned.

correction_text

Character. The corrected, grounding-consistent text returned when correction = TRUE, otherwise NA.

Examples

## Not run: 
# Requires a configured Azure Content Safety endpoint and credentials.
# Deprecated reasoning and correction also need an authorized Azure OpenAI
# GPT-4o deployment.
# Check groundedness of a QnA response
result <- foundry_groundedness(
  text = "The capital of France is Paris. It has a population of 12 million.",
  grounding_sources = c("Paris is the capital and largest city of France."),
  query = "What is the capital of France?",
  task = "QnA"
)

# Check if fully grounded
result$grounded

# See what percentage is grounded
result$grounded_pct

# View ungrounded segments
result$ungrounded_segments[[1]]

# Check groundedness of a summarization
summary_result <- foundry_groundedness(
  text = "The study found significant improvements in patient outcomes.",
  grounding_sources = c(
    "A clinical trial showed 40% improvement in recovery time.",
    "Patient satisfaction increased by 25% compared to control group."
  ),
  task = "Summarization",
  domain = "Medical"
)

# With reasoning enabled
llm_resource <- foundry_llm_resource(
  endpoint = "https://your-openai.openai.azure.com",
  deployment_name = "gpt-4o"
)
detailed_result <- foundry_groundedness(
  text = "The product was released in 2020 and has sold millions of units.",
  grounding_sources = c("The product launched in 2021 with strong initial sales."),
  query = "When was the product released?",
  reasoning = TRUE,
  llm_resource = llm_resource
)

# Request corrected text (requires a bring-your-own Azure OpenAI deployment)
corrected <- foundry_groundedness(
  text = "The patient name is Kevin.",
  grounding_sources = "The patient name is Jane.",
  task = "Summarization",
  domain = "Medical",
  correction = TRUE,
  llm_resource = llm_resource
)
corrected$correction_text

## End(Not run)

Description

Generate images with an image-generation deployment such as a GPT-image-series model. Returns a tibble with base64-encoded image data, a URL only if a legacy deployment returned one, and metadata about the generation.

Usage

foundry_image(
  prompt,
  model = NULL,
  n = 1L,
  size = "1024x1024",
  quality = NULL,
  style = NULL,
  response_format = NULL,
  output_format = NULL,
  output_compression = NULL,
  background = NULL,
  moderation = NULL,
  api = c("v1", "deployment"),
  api_key = NULL,
  token = NULL,
  api_version = NULL
)

Arguments

Details

Model Requirements: The model parameter must be an image-capable deployment such as a GPT-image-series deployment. Chat models cannot generate images. Azure retired DALL-E 3 on March 4, 2026; see https://learn.microsoft.com/azure/foundry/openai/how-to/dall-e.

Size Availability:

• GPT-image models in this version of foundryR: auto, 1024x1024, 1536x1024, 1024x1536.

• GPT-Image-2 and GPT-Image-2.5 support custom dimensions in the service, but this version validates only the fixed sizes above.

• Retired DALL-E models used older sizes such as 256x256, 512x512, 1792x1024, and 1024x1792.

GPT-image results are returned as base64 image data. Use foundry_save_image() to decode and write them to disk; saving base64 data requires the base64enc package.

Value

A tibble with columns:

prompt

Character. The original prompt provided.

revised_prompt

Character. Revised prompt when the service returns one, usually NA for GPT-image models.

url

Character. URL to the generated image, NA unless a legacy deployment returns a URL.

b64_json

Character. Base64-encoded image data.

output_format

Character. Requested or returned output format.

created

POSIXct. Timestamp when the image was created.

raw_image

List. Raw image object returned by the service.

Examples

## Not run: 
# Requires a configured Azure image endpoint and credentials,
# plus an image-generation deployment.
# Generate a single image
result <- foundry_image("A sunset over mountains", model = "gpt-image-2")

# View the base64 image data
result$b64_json

# Generate a smaller JPEG output
result <- foundry_image(
  "A futuristic cityscape",
  model = "gpt-image-2",
  quality = "low",
  output_format = "jpeg",
  output_compression = 60
)

# Save an image to disk
result <- foundry_image("A cat wearing a hat", model = "gpt-image-2")
local({
  path <- tempfile(fileext = ".png")
  on.exit(unlink(path))
  foundry_save_image(result, path)
})

## End(Not run)

Description

Use the v1 preview image edits endpoint to edit one or more input images with a text prompt.

Usage

foundry_image_edit(
  image,
  prompt,
  model = NULL,
  mask = NULL,
  n = 1L,
  size = "1024x1024",
  quality = NULL,
  output_format = NULL,
  background = NULL,
  api_key = NULL,
  token = NULL,
  api_version = "preview"
)

Arguments

Value

A tibble with edited image data and metadata.

Examples

## Not run: 
# Requires a configured Azure image endpoint and credentials,
# an image deployment, and your own local input.png image.
foundry_image_edit("input.png", "Make the sky more dramatic", model = "gpt-image-1")

## End(Not run)

Description

Build the llm_resource argument for foundry_groundedness(). Reasoning and correction both rely on an Azure OpenAI GPT-4o deployment that Content Safety calls on your behalf. The service currently accepts only GPT-4o versions 0513 and 0806. This bring-your-own-LLM feature is deprecated and will be removed in a future release.

Usage

foundry_llm_resource(endpoint, deployment_name, resource_type = "AzureOpenAI")

Arguments

Value

A named list matching the Content Safety LLMResource schema.

Examples

foundry_llm_resource(
  endpoint = "https://your-openai.openai.azure.com",
  deployment_name = "gpt-4o"
)

Description

List the models that the Microsoft Foundry v1 data-plane API reports for your resource, or retrieve metadata for one model. The list covers models the resource can use, including models you have not deployed, so it is not a list of your deployments. The model argument of foundry_response() and other v1 helpers takes a deployment name, which you choose when you deploy a model; see your deployments in the Foundry portal.

Usage

foundry_models(
  model = NULL,
  api_key = NULL,
  token = NULL,
  endpoint = NULL,
  api_version = NULL
)

Arguments

Value

A tibble with model metadata and the raw model object in a list-column.

Examples

## Not run: 
# Requires a configured Azure endpoint and credentials.
foundry_models()
foundry_models("gpt-5-nano")

## End(Not run)

Description

Analyze text content for potentially harmful material using the Azure Content Safety API. Returns severity scores for multiple harm categories including hate speech, sexual content, self-harm, and violence.

Usage

foundry_moderate(
  text,
  categories = c("Hate", "Sexual", "SelfHarm", "Violence"),
  output_type = c("FourSeverityLevels", "EightSeverityLevels"),
  blocklists = NULL,
  halt_on_blocklist = FALSE,
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

Arguments

Details

The Azure Content Safety API analyzes text for four types of harmful content:

• Hate: Content that attacks or discriminates against individuals or groups based on protected attributes.

• Sexual: Sexually explicit or adult content.

• SelfHarm: Content that promotes or describes self-harm behaviors.

• Violence: Content that describes or promotes violence.

Severity Labels:

• safe (0-1): No harmful content detected.

• low (2-3): Mildly concerning content.

• medium (4-5): Moderately harmful content.

• high (6-7): Severely harmful content.

The four-level scale uses the same labels at severities 0, 2, 4, and 6.

Value

A tibble with columns:

text

Character. The full input text.

.input_idx

Integer. Position of the input in text, useful for joining results back to caller data.

category

Character. The harm category: "Hate", "Sexual", "SelfHarm", or "Violence".

severity

Integer. Severity score. Range depends on output_type: 0-6 for FourSeverityLevels (values: 0, 2, 4, 6) or 0-7 for EightSeverityLevels.

label

Character. Human-readable severity label: "safe", "low", "medium", or "high".

blocklist_matches

List. Blocklist matches returned by the service for the analyzed text.

blocklist_hit

Logical. TRUE when the service returned any blocklist match for the input text.

raw_response

List. Raw Content Safety response for the analyzed text.

Authentication

You need an Azure Content Safety resource to use this function. Set up the endpoint and either an API key or a resource-scoped bearer-token provider:

• Environment variables: AZURE_CONTENT_SAFETY_ENDPOINT and AZURE_CONTENT_SAFETY_KEY

• Helper functions: foundry_set_content_safety_endpoint() and foundry_set_content_safety_key()

• Microsoft Entra ID: foundry_set_token_provider() with scope = "resource"

Examples

## Not run: 
# Requires an Azure Content Safety endpoint and credentials.
# Analyze a single text
foundry_moderate("This is a friendly message.")

# Analyze multiple texts
texts <- c(
  "Hello, how are you today?",
  "This is another message to check."
)
results <- foundry_moderate(texts)

# Filter for specific categories
foundry_moderate("Some text", categories = c("Hate", "Violence"))

# Use finer-grained severity levels
foundry_moderate("Some text", output_type = "EightSeverityLevels")

# Check results
library(dplyr)
results %>%
  filter(severity > 0) %>%
  arrange(desc(severity))

## End(Not run)

Description

Analyze an image for harmful content with Azure AI Content Safety. image can be a local file path or an HTTPS Azure Blob Storage URL.

Usage

foundry_moderate_image(
  image,
  categories = c("Hate", "Sexual", "SelfHarm", "Violence"),
  output_type = c("FourSeverityLevels", "EightSeverityLevels"),
  endpoint = NULL,
  api_key = NULL,
  api_version = "2024-09-01"
)

Arguments