Skip to content
TruthVouch Docs

Java SDK Quick Start

The TruthVouch Java SDK provides drop-in replacements for OpenAI, Anthropic, and Google AI providers. All LLM calls are automatically governed with fact-checking, PII detection, and policy enforcement. Works with Java 17+ and Kotlin.

Status: Coming Soon (Q2 2026)

Expected Installation

Maven

<dependency>
  <groupId>com.truthvouch</groupId>
  <artifactId>truthvouch-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle

dependencies {
    implementation 'com.truthvouch:truthvouch-sdk:1.0.0'
}

Requires Java 17+.

Planned Features

  • Drop-in provider replacements (OpenAI, Anthropic, Google AI)
  • Streaming support via Stream<T> and async callbacks
  • Manual content scanning
  • Batch scanning
  • Circuit breaker with fail-open/fail-closed modes
  • OpenTelemetry integration
  • Virtual thread support
  • Spring Boot starter (auto-configuration)
  • Records and sealed classes for modern Java patterns

Planned Quick Start

import com.truthvouch.sdk.TruthVouch;
import com.truthvouch.sdk.requests.ChatRequest;
import com.truthvouch.sdk.responses.ChatResponse;


public class Main {
    public static void main(String[] args) throws Exception {
        TruthVouch tv = TruthVouch.builder()
            .apiKey("tv_live_...")
            .build();


        // Drop-in OpenAI replacement
        var openai = tv.openai();
        ChatResponse response = openai.chat().create(
            ChatRequest.builder()
                .model("gpt-4o")
                .addMessage("user", "What is TruthVouch?")
                .build()
        );


        System.out.println(response.content());
        System.out.printf("Verdict: %s%n", response.governance().verdict());
    }
}

Planned API Overview

Client Initialization

TruthVouch tv = TruthVouch.builder()
    .apiKey("tv_live_...")
    .gatewayUrl("https://gateway.truthvouch.com")
    .timeoutSeconds(30)
    .maxRetries(3)
    .failMode(FailMode.OPEN)
    .build();

Drop-In Providers

// OpenAI
var openai = tv.openai();
ChatResponse response = openai.chat().create(request);


// Anthropic
var anthropic = tv.anthropic();
AnthropicResponse response = anthropic.messages().create(request);


// Google AI
var google = tv.google();
GoogleResponse response = google.generateContent(prompt);

Manual Scanning

ScanResult result = tv.scan(ScanRequest.of(
    "Tell me about NASA",
    "NASA was founded in 1958..."
));


System.out.printf("Verdict: %s%n", result.verdict());
System.out.printf("Trust Score: %.2f%n", result.trustScore());

Batch Scanning

BatchJob job = tv.batch().submit(BatchScanRequest.builder()
    .sourceUrl("s3://my-bucket/docs.jsonl")
    .format("jsonl")
    .scanMode("deep")
    .callbackUrl("https://myapp.com/webhooks/scan-complete")
    .build()
);


BatchStatus status = tv.batch().getStatus(job.id());
System.out.printf("Progress: %d%%%n", status.progressPercent());

Error Handling

try {
    ChatResponse response = openai.chat().create(request);
} catch (PolicyBlockedError e) {
    System.out.printf("Blocked by policy: %s%n", e.governanceReport().policyId());
} catch (RateLimitError e) {
    System.out.printf("Rate limited, retry after %d seconds%n", e.retryAfterSeconds());
} catch (AuthenticationError e) {
    System.out.printf("Auth failed: %s%n", e.getMessage());
} catch (TruthVouchException e) {
    System.out.printf("Error: %s%n", e.getMessage());
}

Exception hierarchy:

TruthVouchException (base)
├── GatewayUnreachableException
├── PolicyBlockedError
├── AuthenticationError
├── RateLimitError
├── InvalidRequestException
└── UpstreamProviderException

Streaming

try (var stream = openai.chat().createStream(request)) {
    stream.stream()
        .filter(chunk -> chunk.content() != null)
        .forEach(chunk -> System.out.print(chunk.content()));


    System.out.println();
    System.out.printf("Verdict: %s%n", stream.governanceReport().verdict());
}

Spring Boot Integration

Planned Spring Boot starter with auto-configuration:

@Configuration
@EnableTruthVouch
public class AppConfig {
    // Auto-configured TruthVouch bean
}


@RestController
public class ChatController {
    private final TruthVouch tv;


    public ChatController(TruthVouch tv) {
        this.tv = tv;
    }


    @PostMapping("/ask")
    public ResponseEntity<String> ask(@RequestBody String question) {
        // Use tv.openai(), tv.anthropic(), etc.
    }
}

Configuration via application.yml:

truthvouch:
  api-key: ${TRUTHVOUCH_API_KEY}
  gateway-url: https://gateway.truthvouch.com
  timeout-seconds: 30
  fail-mode: open

Spring AI Integration (Planned)

<dependency>
  <groupId>com.truthvouch</groupId>
  <artifactId>truthvouch-spring-ai-starter</artifactId>
  <version>1.0.0</version>
</dependency>
@Autowired
ChatClient chatClient;  // Auto-configured with TruthVouch


public String chat(String message) {
    return chatClient.prompt()
        .user(message)
        .call()
        .content();
}

Timeline

  • Q2 2026: Public beta release with core provider support
  • Q3 2026: GA release with full feature parity
  • Q3 2026: Spring Boot starter and Spring AI integration

Next Steps