Skip to contents

Assertions for Output Validation

Source: R/assertion.R
assertions.Rd

S7 classes and helper functions for defining output validation constraints with backtracking support. Hard assertions trigger retries when they fail, while soft suggestions log warnings but allow execution to continue.

Define validation constraints for module outputs. Hard assertions (assert_output) trigger retries when they fail, while soft suggestions (suggest_output) log warnings but allow execution to continue.

Usage

Assertion(
  condition = function() NULL,
  message = "Assertion failed",
  field = NULL,
  type = "assert"
)

AssertionSet(assertions = list())

assert_output(condition, message = "Assertion failed", field = NULL)

suggest_output(condition, message = "Suggestion not met", field = NULL)

assertion_set(...)

Arguments

condition

A formula or function that takes the output and returns TRUE/FALSE. For formulas, use .x to reference the output (e.g., ~ nchar(.x$answer) <= 100).

message

Error message to display when the assertion fails.

field

Optional. The specific output field to validate. If NULL, the entire output is passed to the condition.

type

For Assertion class: "assert" for hard assertion, "suggest" for soft suggestion. Use the helper functions assert_output() and suggest_output() instead of setting this directly.

assertions

For AssertionSet class: A list of Assertion objects.

...

Assertion objects or a list of Assertion objects.

Value

An Assertion object.

An AssertionSet object.

Details

Backtracking Behavior

When wrapped with with_assertions(), modules will:

  1. Run the module normally

  2. Evaluate all assertions against the output

  3. If hard assertions fail and retries remain, inject feedback and retry

  4. If max retries exceeded, raise an error (or warning if configured)

  5. Soft suggestions always log but never trigger retries

Condition Functions

Conditions can be specified as:

  • Formulas: ~ nchar(.x$answer) <= 100 - .x is the output

  • Functions: function(x) nchar(x$answer) <= 100

Examples

if (FALSE) { # \dontrun{
# Hard assertion - must be satisfied
assert_output(~ nchar(.x$answer) <= 100, "Answer must be 100 chars or less")

# Soft suggestion - logs warning but continues
suggest_output(~ grepl("^[A-Z]", .x$answer), "Should start with capital")

# Field-specific assertion
assert_output(~ nchar(.x) <= 50, "Too long", field = "summary")
} # }

if (FALSE) { # \dontrun{
assertions <- assertion_set(
  assert_output(~ nchar(.x$answer) <= 100, "Too long"),
  suggest_output(~ grepl("^[A-Z]", .x$answer), "Should capitalize")
)
} # }