Tool Guardrails

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Specify input validation guardrails before tool execution.
 * Guardrails execute in array order with fail-fast semantics.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ToolInputGuardrails {
    /**
     * Array of ToolInputGuardrail implementation classes.
     * CDI beans will be instantiated and executed in order.
     */
    Class<? extends ToolInputGuardrail>[] value();
}

import io.quarkiverse.langchain4j.RegisterAiService;
import io.quarkiverse.langchain4j.guardrails.ToolInputGuardrails;
import dev.langchain4j.agent.tool.Tool;

public class DatabaseTool {

    @Tool("Execute SQL query")
    @ToolInputGuardrails({SqlInjectionGuardrail.class, AuthorizationGuardrail.class})
    public String executeQuery(String sql) {
        // Tool implementation
    }
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Specify output validation guardrails after tool execution.
 * Guardrails execute in array order with fail-fast semantics.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ToolOutputGuardrails {
    /**
     * Array of ToolOutputGuardrail implementation classes.
     * CDI beans will be instantiated and executed in order.
     */
    Class<? extends ToolOutputGuardrail>[] value();
}

public class DataFetcher {

    @Tool("Fetch user data")
    @ToolOutputGuardrails({PiiRedactionGuardrail.class, ComplianceGuardrail.class})
    public String fetchUserData(String userId) {
        // Tool implementation
    }
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Base interface for all tool guardrails.
 * Guardrails are single-threaded per invocation and cannot run on Vert.x event loop.
 *
 * @param <P> Request type (ToolGuardrailRequest subtype)
 * @param <R> Result type (ToolGuardrailResult subtype)
 */
public interface ToolGuardrail<
    P extends ToolGuardrailRequest<P>,
    R extends ToolGuardrailResult<R>
> {
    /**
     * Perform validation on the request.
     * @param request The guardrail request containing tool metadata and context
     * @return The validation result (success, failure, or fatal)
     */
    R validate(P request);
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Guardrail for validating tool inputs before execution.
 * Use cases: input validation, authorization, rate limiting, input sanitization.
 */
public interface ToolInputGuardrail
    extends ToolGuardrail<ToolInputGuardrailRequest, ToolInputGuardrailResult> {

    /**
     * Validate tool input before execution.
     * @param request Contains tool execution request, metadata, and invocation context
     * @return Validation result indicating success, failure, or fatal error
     */
    ToolInputGuardrailResult validate(ToolInputGuardrailRequest request);
}

import io.quarkiverse.langchain4j.guardrails.ToolInputGuardrail;
import io.quarkiverse.langchain4j.guardrails.ToolInputGuardrailRequest;
import io.quarkiverse.langchain4j.guardrails.ToolInputGuardrailResult;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class AuthorizationGuardrail implements ToolInputGuardrail {

    @Override
    public ToolInputGuardrailResult validate(ToolInputGuardrailRequest request) {
        String userId = request.argumentsAsJson().getString("userId");

        if (!isAuthorized(userId)) {
            return ToolInputGuardrailResult.failure(
                "User not authorized to access this resource"
            );
        }

        return ToolInputGuardrailResult.success();
    }

    private boolean isAuthorized(String userId) {
        // Authorization logic
        return true;
    }
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Guardrail for validating and transforming tool outputs after execution.
 * Use cases: output validation, PII redaction, result transformation, compliance checks.
 */
public interface ToolOutputGuardrail
    extends ToolGuardrail<ToolOutputGuardrailRequest, ToolOutputGuardrailResult> {

    /**
     * Validate and optionally transform tool output after execution.
     * @param request Contains tool execution result, original request, metadata, and context
     * @return Validation result indicating success (possibly with modified result), failure, or fatal error
     */
    ToolOutputGuardrailResult validate(ToolOutputGuardrailRequest request);
}

import io.quarkiverse.langchain4j.guardrails.ToolOutputGuardrail;
import io.quarkiverse.langchain4j.guardrails.ToolOutputGuardrailRequest;
import io.quarkiverse.langchain4j.guardrails.ToolOutputGuardrailResult;
import dev.langchain4j.agent.tool.ToolExecutionResult;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class PiiRedactionGuardrail implements ToolOutputGuardrail {

    @Override
    public ToolOutputGuardrailResult validate(ToolOutputGuardrailRequest request) {
        if (request.isError()) {
            return ToolOutputGuardrailResult.success();
        }

        String originalText = request.resultText();
        String redactedText = redactPii(originalText);

        if (!originalText.equals(redactedText)) {
            ToolExecutionResult modifiedResult = ToolExecutionResult.builder()
                .text(redactedText)
                .build();
            return ToolOutputGuardrailResult.successWith(modifiedResult);
        }

        return ToolOutputGuardrailResult.success();
    }

    private String redactPii(String text) {
        // PII redaction logic (email, SSN, etc.)
        return text.replaceAll("\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b", "[EMAIL]");
    }
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Base sealed interface for guardrail requests.
 * Contains tool metadata and invocation context.
 *
 * @param <P> Self-referential type parameter for type safety
 */
public sealed interface ToolGuardrailRequest<P extends ToolGuardrailRequest<P>>
    permits ToolInputGuardrailRequest, ToolOutputGuardrailRequest {
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Request context for input guardrail validation.
 * Contains tool execution request, metadata, and invocation context.
 */
public record ToolInputGuardrailRequest(
    ToolExecutionRequest executionRequest,
    ToolMetadata toolMetadata,
    ToolInvocationContext invocationContext
) implements ToolGuardrailRequest<ToolInputGuardrailRequest> {

    /**
     * Get the tool name.
     */
    public String toolName();

    /**
     * Get raw JSON arguments as string.
     */
    public String arguments();

    /**
     * Get memory ID from invocation context.
     */
    public Object memoryId();

    /**
     * Parse arguments as Vert.x JsonObject for easy access.
     */
    public JsonObject argumentsAsJson();
}

@Override
public ToolInputGuardrailResult validate(ToolInputGuardrailRequest request) {
    String toolName = request.toolName();
    JsonObject args = request.argumentsAsJson();
    Object memoryId = request.memoryId();

    // Access arguments
    String query = args.getString("query");
    int limit = args.getInteger("limit", 10);

    // Perform validation
    if (query.length() > 1000) {
        return ToolInputGuardrailResult.failure("Query too long");
    }

    return ToolInputGuardrailResult.success();
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Request context for output guardrail validation.
 * Contains tool execution result, original request, metadata, and invocation context.
 */
public record ToolOutputGuardrailRequest(
    ToolExecutionResult executionResult,
    ToolExecutionRequest executionRequest,
    ToolMetadata toolMetadata,
    ToolInvocationContext invocationContext
) implements ToolGuardrailRequest<ToolOutputGuardrailRequest> {

    /**
     * Get the tool name from the original request.
     */
    public String toolName();

    /**
     * Get result text from execution result.
     */
    public String resultText();

    /**
     * Check if tool execution resulted in error.
     */
    public boolean isError();

    /**
     * Get memory ID from invocation context.
     */
    public Object memoryId();

    /**
     * Parse original arguments as Vert.x JsonObject.
     */
    public JsonObject argumentsAsJson();
}

@Override
public ToolOutputGuardrailResult validate(ToolOutputGuardrailRequest request) {
    if (request.isError()) {
        // Skip validation for errors
        return ToolOutputGuardrailResult.success();
    }

    String resultText = request.resultText();
    String toolName = request.toolName();

    // Validate output
    if (containsSensitiveData(resultText)) {
        return ToolOutputGuardrailResult.failure("Output contains sensitive data");
    }

    return ToolOutputGuardrailResult.success();
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Base sealed interface for guardrail validation results.
 *
 * @param <GR> Self-referential type parameter for type safety
 */
public sealed interface ToolGuardrailResult<GR extends ToolGuardrailResult<GR>>
    permits ToolInputGuardrailResult, ToolOutputGuardrailResult {
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Result of input guardrail validation.
 * Can indicate success (with optional request modification),
 * non-fatal failure (error message to LLM), or fatal failure (exception thrown).
 */
public record ToolInputGuardrailResult(
    boolean isSuccess,
    String errorMessage,
    Throwable cause,
    boolean isFatalFailure,
    ToolExecutionRequest modifiedRequest
) implements ToolGuardrailResult<ToolInputGuardrailResult> {

    /**
     * Validation succeeded with original request.
     */
    public static ToolInputGuardrailResult success();

    /**
     * Validation succeeded with modified request.
     * Use this to transform tool arguments before execution.
     */
    public static ToolInputGuardrailResult successWith(ToolExecutionRequest modifiedRequest);

    /**
     * Non-fatal validation failure.
     * Error message is sent to LLM, which may retry or handle gracefully.
     */
    public static ToolInputGuardrailResult failure(String errorMessage);

    /**
     * Fatal validation failure.
     * Throws ToolGuardrailException immediately, bypassing error handlers.
     */
    public static ToolInputGuardrailResult fatal(String errorMessage, Throwable cause);
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Result of output guardrail validation.
 * Can indicate success (with optional result modification),
 * non-fatal failure (error message to LLM), or fatal failure (exception thrown).
 */
public record ToolOutputGuardrailResult(
    boolean isSuccess,
    String errorMessage,
    Throwable cause,
    boolean isFatalFailure,
    ToolExecutionResult modifiedResult
) implements ToolGuardrailResult<ToolOutputGuardrailResult> {

    /**
     * Validation succeeded with original result.
     */
    public static ToolOutputGuardrailResult success();

    /**
     * Validation succeeded with modified result.
     * Use this to transform tool output (e.g., redact PII, format data).
     */
    public static ToolOutputGuardrailResult successWith(ToolExecutionResult modifiedResult);

    /**
     * Non-fatal validation failure.
     * Error message is sent to LLM.
     */
    public static ToolOutputGuardrailResult failure(String errorMessage);

    /**
     * Fatal validation failure.
     * Throws ToolGuardrailException immediately.
     */
    public static ToolOutputGuardrailResult fatal(String errorMessage, Throwable cause);
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Context for tool invocation including memory ID and custom parameters.
 */
public record ToolInvocationContext(
    InvocationContext context
) {
    /**
     * Get chat memory ID for this invocation.
     */
    public Object memoryId();

    /**
     * Get custom parameter by key.
     */
    public Object parameter(String key);

    /**
     * Get all custom parameters as immutable map.
     */
    public Map<String, Object> parameters();

    /**
     * Check if parameter exists.
     */
    public boolean hasParameter(String key);
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Metadata about a tool including specification and instance.
 */
public record ToolMetadata(
    ToolSpecification specification,
    Object toolInstance
) {
    /**
     * Get tool name from specification.
     */
    public String toolName();

    /**
     * Get tool description from specification.
     */
    public String description();
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Exception thrown by guardrails.
 * Implements PreventsErrorHandlerExecution to bypass error handlers.
 */
public class ToolGuardrailException
    extends RuntimeException
    implements PreventsErrorHandlerExecution {

    /**
     * Create non-fatal guardrail exception.
     */
    public ToolGuardrailException(String message);

    /**
     * Create guardrail exception with fatal flag.
     */
    public ToolGuardrailException(String message, boolean fatal);

    /**
     * Create guardrail exception with cause.
     */
    public ToolGuardrailException(String message, Throwable cause);

    /**
     * Create guardrail exception with cause and fatal flag.
     */
    public ToolGuardrailException(String message, Throwable cause, boolean fatal);

    /**
     * Check if exception is fatal.
     * Fatal exceptions terminate execution immediately.
     */
    public boolean isFatal();
}

// Package: io.quarkiverse.langchain4j.guardrails
/**
 * Mark field for token accumulation in output guardrails.
 * Used for streaming guardrail validation.
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface OutputGuardrailAccumulator {
}

// Package: io.quarkiverse.langchain4j.guardrails
import io.smallrye.mutiny.Multi;

/**
 * Interface to accumulate tokens when output guardrails are applied on streamed responses.
 * Implementations should be CDI beans selected using their classname in the @OutputGuardrailAccumulator annotation.
 */
public interface OutputTokenAccumulator {

    /**
     * Accumulate tokens before applying the guardrails.
     * The guardrails are invoked for each item emitted by the produced Multi.
     * If the returned Multi emits an error, the guardrail chain is not called and the error is propagated.
     * If the returned Multi completes, the guardrail chain is called with the remaining accumulated tokens.
     *
     * @param tokens the input token stream
     * @return the Multi producing the accumulated tokens
     */
    Multi<String> accumulate(Multi<String> tokens);
}

# Maximum retry attempts for guardrail failures
quarkus.langchain4j.guardrails.max-retries=3

// Package: io.quarkiverse.langchain4j.runtime.observability
/**
 * Enum representing possible guardrail validation outcomes.
 */
public enum GuardrailOutcome {
    SUCCESS("success"),
    FAILURE("failure"),
    REPROMPT("reprompt");

    /**
     * Get the string value for metrics and logging.
     * @return String representation of the outcome
     */
    public String getValue();
}

// Package: io.quarkiverse.langchain4j.runtime.observability
/**
 * Enum representing tool-specific guardrail outcomes.
 */
public enum ToolGuardrailOutcome {
    SUCCESS("success"),
    FAILURE("failure"),
    FATAL("fatal");

    /**
     * Get the string value for metrics and logging.
     * @return String representation of the outcome
     */
    public String getValue();
}