OpenGuardrails Java SDK

OpenGuardrails Java Client — A Context-Aware AI Safety Guardrails System Powered by LLMs.

Overview

OpenGuardrails is a context-aware AI safety guardrail system based on large language models (LLMs). It understands conversational context to perform intelligent safety detection. Unlike traditional keyword-based methods, our guardrail interprets deep semantic meaning and contextual relationships within conversations.

Key Features

• 🧠 Context Awareness – Based on LLM-powered conversational understanding, not simple batch detection
• 🔍 Prompt Injection Detection – Identifies malicious prompt injections and jailbreak attacks
• 📋 Content Compliance Detection – Ensures compliance with fundamental security requirements for generative AI services
• 🔐 Sensitive Data Leakage Prevention – Detects and prevents the leakage of personal or enterprise-sensitive information
• 🧩 User-Level Blocking Policy – Supports risk identification and blocking strategies at the user level
• 🖼️ Multimodal Detection – Supports image content safety detection
• 🛠️ Easy Integration – Compatible with the OpenAI API format; integrate with just one line of code
• ⚡ OpenAI-Style API – Familiar interface design for quick adoption
• 🚀 Sync/Async Support – Supports both synchronous and asynchronous modes to meet diverse application needs

Requirements

• Java 8 or later
• Maven 3.6+ or Gradle 6.0+

Installation

Maven

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.openguardrails</groupId>
    <artifactId>openguardrails</artifactId>
    <version>3.0.0</version>
</dependency>

Gradle

Add the dependency to your build.gradle:

implementation 'com.openguardrails:openguardrails:3.0.0'

Quick Start

Basic Usage

import com.openguardrails.OpenGuardrailsClient;
import com.openguardrails.model.*;

// Initialize client
OpenGuardrailsClient client = new OpenGuardrailsClient("your-api-key");

// Check user input
GuardrailResponse result = client.checkPrompt("User input text");
System.out.println(result.getOverallRiskLevel()); // Safe / Low / Medium / High
System.out.println(result.getSuggestAction());     // Allow / Block / Substitute

// Check input with user ID (optional)
GuardrailResponse result2 = client.checkPrompt("User input text", "user-123");

// Context-based response checking
GuardrailResponse ctxResult = client.checkResponseCtx(
    "Teach me to cook",
    "I can teach you how to make simple home dishes"
);
System.out.println(ctxResult.getOverallRiskLevel());
System.out.println(ctxResult.getSuggestAction());

// With user ID (optional)
GuardrailResponse ctxResult2 = client.checkResponseCtx(
    "Teach me to cook",
    "I can teach you how to make simple home dishes",
    "user-123"
);

Conversation Context Detection (Recommended)

import java.util.Arrays;
import java.util.List;

// Detect full conversation context — core feature
List<Message> messages = Arrays.asList(
    new Message("user", "User’s question"),
    new Message("assistant", "Assistant’s response"),
    new Message("user", "Follow-up question")
);

GuardrailResponse result = client.checkConversation(messages);

// Check detection result
if (result.isSafe()) {
    System.out.println("Conversation is safe");
} else if (result.isBlocked()) {
    System.out.println("Conversation has risks — block it");
} else if (result.hasSubstitute()) {
    System.out.println("Suggested safe answer: " + result.getSuggestAnswer());
}

// With user ID (optional)
GuardrailResponse result2 = client.checkConversation(messages, "OpenGuardrails-Text", "user-123");

Asynchronous API (Recommended for Better Performance)

import com.openguardrails.AsyncOpenGuardrailsClient;
import java.util.concurrent.CompletableFuture;

// Async client
AsyncOpenGuardrailsClient asyncClient = new AsyncOpenGuardrailsClient("your-api-key");

// Async prompt check
CompletableFuture<GuardrailResponse> future = asyncClient.checkPromptAsync("User question");

// Option 1: Block until complete
GuardrailResponse result = future.get();
System.out.println(result.getOverallRiskLevel());

// Option 2: Use callback (recommended)
asyncClient.checkPromptAsync("User question")
    .thenAccept(result -> {
        System.out.println("Async check completed:");
        System.out.println("Risk Level: " + result.getOverallRiskLevel());
        System.out.println("Suggested Action: " + result.getSuggestAction());
    })
    .exceptionally(throwable -> {
        System.err.println("Check failed: " + throwable.getMessage());
        return null;
    });

// Async conversation detection
List<Message> messages = Arrays.asList(
    new Message("user", "User question"),
    new Message("assistant", "Assistant answer")
);
asyncClient.checkConversationAsync(messages)
    .thenAccept(result -> {
        if (result.isSafe()) {
            System.out.println("Conversation is safe");
        } else {
            System.out.println("Conversation risks: " + result.getAllCategories());
        }
    });

asyncClient.close(); // Remember to close resources

Multimodal Image Detection (Added in v2.3.0)

Version 2.3.0 introduces multimodal detection — analyzing both text and image semantics for safety assessment.

import com.openguardrails.OpenGuardrailsClient;
import com.openguardrails.model.GuardrailResponse;
import java.util.Arrays;
import java.util.List;

OpenGuardrailsClient client = new OpenGuardrailsClient("your-api-key");

// Local image
GuardrailResponse result = client.checkPromptImage(
    "Is this image safe?",
    "/path/to/image.jpg"
);
System.out.println(result.getOverallRiskLevel());
System.out.println(result.getSuggestAction());

// Image URL
result = client.checkPromptImage(
    "",  // prompt optional
    "https://example.com/image.jpg"
);

// Multiple images
List<String> images = Arrays.asList(
    "/path/to/image1.jpg",
    "https://example.com/image2.jpg",
    "/path/to/image3.png"
);
result = client.checkPromptImages("Are these images safe?", images);
System.out.println(result.getOverallRiskLevel());

// With user ID (optional)
result = client.checkPromptImage(
    "Is this image safe?",
    "/path/to/image.jpg",
    "OpenGuardrails-VL",
    "user-123"
);

result = client.checkPromptImages(
    "Are these images safe?",
    images,
    "OpenGuardrails-VL",
    "user-123"
);

Using try-with-resources

// Sync client
try (OpenGuardrailsClient client = new OpenGuardrailsClient("your-api-key")) {
    GuardrailResponse result = client.checkPrompt("User question");
    System.out.println(result.getOverallRiskLevel());
}

// Async client
try (AsyncOpenGuardrailsClient asyncClient = new AsyncOpenGuardrailsClient("your-api-key")) {
    CompletableFuture<GuardrailResponse> future = asyncClient.checkPromptAsync("User question");
    GuardrailResponse result = future.get();
    System.out.println(result.getOverallRiskLevel());
}

API Reference

OpenGuardrailsClient (Synchronous Client)

Constructor

// Default config
OpenGuardrailsClient client = new OpenGuardrailsClient("your-api-key");

// Custom config
OpenGuardrailsClient client = new OpenGuardrailsClient(
    "your-api-key",
    "https://api.openguardrails.com/v1",
    30, // timeout in seconds
    3   // max retries
);

Methods

checkPrompt(content)

Checks the safety of a single prompt.

GuardrailResponse checkPrompt(String content)
GuardrailResponse checkPrompt(String content, String model)

Parameters:

• content (String): Content to check
• model (String, optional): Model name (default: "OpenGuardrails-Text")

checkConversation(messages)

Checks the safety of a conversation (recommended).

GuardrailResponse checkConversation(List<Message> messages)
GuardrailResponse checkConversation(List<Message> messages, String model)

healthCheck()

Checks the API service health.

Map<String, Object> healthCheck()

getModels()

Retrieves available models.

Map<String, Object> getModels()

AsyncOpenGuardrailsClient (Asynchronous Client — Recommended)

Constructor

AsyncOpenGuardrailsClient asyncClient = new AsyncOpenGuardrailsClient("your-api-key");

AsyncOpenGuardrailsClient asyncClient = new AsyncOpenGuardrailsClient(
    "your-api-key",
    "https://api.openguardrails.com/v1",
    30,
    3
);

Async Methods

checkPromptAsync(content)

Asynchronously checks a single prompt.

CompletableFuture<GuardrailResponse> checkPromptAsync(String content)
CompletableFuture<GuardrailResponse> checkPromptAsync(String content, String model)

checkConversationAsync(messages)

Asynchronously checks conversation safety.

CompletableFuture<GuardrailResponse> checkConversationAsync(List<Message> messages)
CompletableFuture<GuardrailResponse> checkConversationAsync(List<Message> messages, String model)

healthCheckAsync()

Asynchronously checks API health.

CompletableFuture<Map<String, Object>> healthCheckAsync()

getModelsAsync()

Asynchronously retrieves model list.

CompletableFuture<Map<String, Object>> getModelsAsync()

Data Models

Message

public class Message {
    private String role;    // "user", "system", "assistant"
    private String content; // message content
    
    public Message(String role, String content)
    // getters/setters...
}

GuardrailResponse

public class GuardrailResponse {
    private String id;
    private GuardrailResult result;
    private String overallRiskLevel;
    private String suggestAction;
    private String suggestAnswer;
    private Double score;  // 检测置信度分数 (v2.4.1新增)
    
    public boolean isSafe()
    public boolean isBlocked()
    public boolean hasSubstitute()
    public List<String> getAllCategories()
    public Double getScore()
}

GuardrailResult

public class GuardrailResult {
    private ComplianceResult compliance;
    private SecurityResult security;
    private DataResult data; // Added in v2.4.0
}

ComplianceResult / SecurityResult / DataResult

public class ComplianceResult {
    private String riskLevel;
    private List<String> categories;
}

public class DataResult {
    private String riskLevel;
    private List<String> categories; // Detected sensitive data types
}

Example Response

{
  "id": "guardrails-xxx",
  "result": {
    "compliance": {
      "risk_level": "Safe",
      "categories": []
    },
    "security": {
      "risk_level": "Safe",
      "categories": []
    },
    "data": {
      "risk_level": "Safe",
      "categories": []
    }
  },
  "overall_risk_level": "Safe",
  "suggest_action": "Allow",
  "suggest_answer": null
}

Exception Handling

import com.openguardrails.exception.*;

try {
    GuardrailResponse result = client.checkPrompt("test content");
    System.out.println(result);
} catch (AuthenticationException e) {
    System.err.println("Authentication failed — check API key: " + e.getMessage());
} catch (RateLimitException e) {
    System.err.println("Rate limit exceeded — try again later: " + e.getMessage());
} catch (ValidationException e) {
    System.err.println("Invalid input: " + e.getMessage());
} catch (NetworkException e) {
    System.err.println("Network error: " + e.getMessage());
} catch (OpenGuardrailsException e) {
    System.err.println("API error: " + e.getMessage());
}

Exception Types

• OpenGuardrailsException – Base exception
• AuthenticationException – Authentication failed
• RateLimitException – Rate limit exceeded
• ValidationException – Invalid input parameters
• NetworkException – Network errors

Use Cases

1. Content Moderation

String userContent = "User-generated content...";
GuardrailResponse result = client.checkPrompt(userContent);

if (!result.isSafe()) {
    System.out.println("Unsafe content: " + result.getAllCategories());
}

2. Chatbot Protection

List<Message> conversation = Arrays.asList(
    new Message("user", "User question"),
    new Message("assistant", "Assistant response")
);

GuardrailResponse result = client.checkConversation(conversation);

if ("Substitute".equals(result.getSuggestAction()) && result.getSuggestAnswer() != null) {
    return result.getSuggestAnswer();
} else if (result.isBlocked()) {
    return "Sorry, I can’t answer that.";
}

3. Batch Content Checking

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class BatchContentChecker {
    private final OpenGuardrailsClient client;
    private final ExecutorService executor;
    
    public BatchContentChecker(String apiKey) {
        this.client = new OpenGuardrailsClient(apiKey);
        this.executor = Executors.newFixedThreadPool(10);
    }
    
    public CompletableFuture<GuardrailResponse> checkAsync(String content) {
        return CompletableFuture.supplyAsync(() -> {
            try {
                return client.checkPrompt(content);
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }, executor);
    }
    
    public void close() {
        client.close();
        executor.shutdown();
    }
}

4. Spring Boot Integration

@Configuration
public class OpenGuardrailsConfig {
    
    @Value("${openguardrails.api-key}")
    private String apiKey;
    
    @Value("${openguardrails.base-url:https://api.openguardrails.com/v1}")
    private String baseUrl;
    
    @Bean
    public OpenGuardrailsClient openguardrailsClient() {
        return new OpenGuardrailsClient(apiKey, baseUrl, 30, 3);
    }
}

@Service
public class ContentModerationService {
    
    @Autowired
    private OpenGuardrailsClient openguardrailsClient;
    
    public boolean isContentSafe(String content) {
        try {
            GuardrailResponse response = openguardrailsClient.checkPrompt(content);
            return response.isSafe();
        } catch (Exception e) {
            log.error("Content check failed", e);
            return false;
        }
    }
}

Best Practices

1. Use Contextual Detection: Prefer checkConversation over checkPrompt for more accurate results.
2. Resource Management: Always close clients using try-with-resources or manually.
3. Exception Handling: Implement robust retry and fallback logic.
4. Connection Reuse: Reuse the same OpenGuardrailsClient instance for better performance.
5. Tuning: Adjust timeout and retry parameters as needed.
6. Logging: Log all detection results for auditing and improvement.

Thread Safety

OpenGuardrailsClient is thread-safe and can be shared across threads.

License

Apache 2.0

Support

• Website: https://openguardrails.com
• Docs: https://docs.openguardrails.com
• Issues: https://github.com/openguardrails/openguardrails-java/issues
• Email: thomas@openguardrails.com