Package com.tnsai.annotations

Annotation Interface OutputGuardrail

@Documented @Retention(RUNTIME) @Target({METHOD,TYPE}) public @interface OutputGuardrail
Configures output validation and formatting for actions.

Output guardrails ensure agent responses meet quality standards, follow format requirements, and don't contain harmful content.

Usage on Method


 @ActionSpec(type = ActionType.LLM_GENERATION, description = "Generate response")
 @OutputGuardrail(
     format = OutputFormat.JSON,
     schema = "response-schema.json",
     maxTokens = 1000,
     validators = {NoHallucination.class, FactCheck.class}
 )
 public String generateResponse(String query) {
     // Response is validated before returning
 }

Usage on Type (Role-level default)


 @OutputGuardrail(
     format = OutputFormat.MARKDOWN,
     maxTokens = 2000
 )
 public class ContentRole extends Role {
     // All actions inherit these guardrails
 }

Built-in Validators

  • NotEmpty - Ensures non-empty output
  • JsonValid - Validates JSON syntax
  • SchemaCompliant - Validates against JSON schema
  • NoHallucination - Checks for factual accuracy
  • NoPII - Blocks personal identifiable info
  • SafeContent - Blocks harmful content
Author:
TnsAI Team
See Also:

  • Element Details

    • format

      OutputGuardrail.OutputFormat format
      Expected output format.
      Returns:
      output format
      Default:
      TEXT

    • schema

      String schema
      JSON schema for validation.

      Path to schema file or inline schema.

      Returns:
      JSON schema
      Default:
      ""

    • maxTokens

      int maxTokens
      Maximum output length in tokens.

      0 means no limit.

      Returns:
      max tokens
      Default:
      0

    • maxChars

      int maxChars
      Maximum output length in characters.
      Returns:
      max characters
      Default:
      0

    • minChars

      int minChars
      Minimum output length in characters.
      Returns:
      min characters
      Default:
      0

    • validators

      Class<?>[] validators
      Validator classes to apply.
      Returns:
      validator classes
      Default:
      {}

    • postProcessors

      Class<?>[] postProcessors
      Post-processor classes to apply.
      Returns:
      post-processor classes
      Default:
      {}

    • maskPII

      boolean maskPII
      Whether to enable PII detection and masking.
      Returns:
      true to mask PII
      Default:
      false

    • piiTypes

      OutputGuardrail.PIIType[] piiTypes
      PII types to mask.
      Returns:
      PII types
      Default:
      {}

    • moderateContent

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

    • blockCategories

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

    • checkHallucination

      boolean checkHallucination
      Whether to check for hallucinations (requires context).
      Returns:
      true to check
      Default:
      false

    • hallucinationThreshold

      double hallucinationThreshold
      Confidence threshold for hallucination detection.
      Returns:
      threshold (0.0-1.0)
      Default:
      0.8

    • onFailure

      OutputGuardrail.FailureAction onFailure
      Action to take on validation failure.
      Returns:
      failure action
      Default:
      RETRY

    • maxRetries

      int maxRetries
      Maximum retry attempts on failure.
      Returns:
      max retries
      Default:
      3

    • fallback

      String fallback
      Fallback value if all retries fail.
      Returns:
      fallback value
      Default:
      ""

    • logFailures

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

    • includeSpec

      boolean includeSpec
      Whether to include validation metadata in response.
      Returns:
      true to include metadata
      Default:
      false