Package com.tnsai.annotations

Annotation Interface InputGuardrail

@Documented @Retention(RUNTIME) @Target({METHOD,TYPE}) public @interface InputGuardrail
Configures input validation and sanitization for actions.

Input guardrails protect agents from malicious or malformed input by validating and sanitizing data before processing.

Usage on Method


 @ActionSpec(type = ActionType.LOCAL, description = "Process user message")
 @InputGuardrail(
     maxLength = 10000,
     validators = PiiInputValidator.class,
     sanitizers = PiiInputSanitizer.class,
     onFailure = InputGuardrail.FailureAction.SANITIZE,
     blockPatterns = {"ignore previous", "system prompt"}
 )
 public String processMessage(String message) {
     // message is validated and sanitized before this runs
 }

Usage on Type (Role-level default)


 @InputGuardrail(
     maxLength = 5000,
     validators = PiiInputValidator.class,
     onFailure = InputGuardrail.FailureAction.REJECT
 )
 public class UserInputRole extends Role {
     // All actions inherit these guardrails
 }

Built-in PII Extensions

PiiInputValidator detects common PII and PiiInputSanitizer replaces it with stable tokens. Applications may supply their own implementations of InputValidator and InputSanitizer.

Author:
TnsAI Team
See Also:

  • Element Details

    • maxLength

      int maxLength
      Maximum input length in characters.

      0 means no limit.

      Returns:
      max length
      Default:
      0

    • minLength

      int minLength
      Minimum input length in characters.
      Returns:
      min length
      Default:
      0

    • validators

      Class<?>[] validators
      Validator classes to apply.

      Each class must implement InputValidator and expose a public no-argument constructor. Validators run in declaration order against every runtime String value, including values declared as Object. Booleans, default-rendering enums, and exact immutable JDK number types are validated through stable textual forms. Custom-rendering enums, containers, and arbitrary objects fail closed unless the policy is InputGuardrail.FailureAction.WARN because they cannot be inspected safely.

      Returns:
      validator classes
      Default:
      {}

    • sanitizers

      Class<?>[] sanitizers
      Sanitizer classes to apply (in order).

      Each class must implement InputSanitizer and expose a public no-argument constructor. They run after a validator rejects a value when onFailure() is InputGuardrail.FailureAction.SANITIZE.

      Returns:
      sanitizer classes
      Default:
      {}

    • blockPatterns

      String[] blockPatterns
      Regex patterns to block (prompt injection protection).

      Input matching any pattern is rejected. Runtime enforcement limits each pattern and inspected input to 1,024 characters each, and rejects backreferences, nested quantifiers, comments mode, multi-token escapes, multiple alternation groups, and more than one backtracking quantifier per pattern before matching. Fixed repetitions and possessive quantifiers may be repeated. A single non-capturing alternation group, lookarounds, other inline flags, and lazy or possessive quantifier modifiers remain supported.

      Returns:
      block patterns
      Default:
      {}

    • allowPatterns

      String[] allowPatterns
      Regex patterns that input must match.

      Input not matching is rejected. The same bounded, backtracking-safe regex subset documented by blockPatterns() applies.

      Returns:
      allow patterns
      Default:
      {}

    • jsonSchema

      String jsonSchema
      JSON schema for validation (if input is JSON).

      Path to schema file or inline schema.

      Returns:
      JSON schema
      Default:
      ""

    • detectInjection

      boolean detectInjection
      Whether to enable prompt injection detection.
      Returns:
      true to detect injection
      Default:
      true

    • injectionThreshold

      double injectionThreshold
      Injection detection sensitivity (0.0 - 1.0).

      Higher values are more strict.

      Returns:
      sensitivity threshold
      Default:
      0.7

    • moderateContent

      boolean moderateContent
      Whether to enable content moderation.
      Returns:
      true to moderate content
      Default:
      false

    • blockCategories

      InputGuardrail.ContentCategory[] blockCategories
      Content categories to block.
      Returns:
      blocked categories
      Default:
      {}

    • onFailure

      InputGuardrail.FailureAction onFailure
      Action to take on validation failure.
      Returns:
      failure action
      Default:
      REJECT

    • errorMessage

      String errorMessage
      Custom error message on failure.
      Returns:
      error message
      Default:
      ""

    • logFailures

      boolean logFailures
      Whether to log validation failures.
      Returns:
      true to log
      Default:
      true