Java SDK

<dependency>
  <groupId>com.oronts</groupId>
  <artifactId>oguardai-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

OGuardAIClient client = OGuardAIClient.builder()
    .baseUrl("http://localhost:3000")
    .apiKey(System.getenv("GUARDAI_API_KEY")) // only if the server runs with auth
    .build();

TransformResponse result = client.transform(new TransformRequest()
    .input("Contact Julia Schneider at julia@example.com")
    .policy("default"));
// result.safeText: "Contact {{person:p_001:2f9a4d81c6e0}} at {{email:e_001:b57e03d2a941}}"

String llmReply = callYourLLM(result.safeText); // sees tokens only

RehydrateResponse restored = client.rehydrate(new RehydrateRequest()
    .output(llmReply)
    .sessionState(result.sessionState)
    .outputChannel("customer_email")
    .restoreMode("formatted"));
// restored.restoredText: "Dear Frau Julia Schneider, ..."

String answer = client.guardedCall(
    safe -> callYourLLM(safe),
    "Draft a reply to Julia Schneider",
    new OGuardAIClient.GuardedCallOptions().policy("default").outputChannel("customer_email"));

List<Map<String, Object>> messages = List.of(
    Map.of("role", "system", "content", "You are a support agent."),
    Map.of("role", "user", "content", "I am Julia Schneider, julia@example.com"));

GuardedChatResult chat = client.guardedChat(messages,
    new OGuardAIClient.GuardedChatOptions().policy("german-support"));

String reply = callYourChatLLM(chat.safeMessages); // sees tokens only
String restored = client.rehydrateReply(reply, chat.sessionState, "customer_email");

DetectResponse detected = client.detect(new DetectRequest("Email test@example.com, SSN 123-45-6789"));
for (DetectedEntity e : detected.entities) {
    System.out.printf("%s: %s (%.2f)%n", e.type, e.value, e.confidence);
}

// includeValues is a boxed Boolean, so a false is transmitted verbatim to keep raw
// values out of a value-free caller (a primitive would be dropped and default to true).
client.detect(new DetectRequest("SSN 123-45-6789").includeValues(false));

HealthResponse health = client.health();          // health.status == "healthy"
CapabilitiesResponse caps = client.capabilities(); // caps.entityTypes, caps.languages, caps.detectors

Session session = client.newSession("german-support");

TransformResponse turn1 = session.transform("Ich bin Anna Mueller, Kundennummer 948221");
String reply = callYourLLM(turn1.safeText);
RehydrateResponse restored = session.rehydrate(reply, "customer_email");

// Turn 2: entities are deduplicated across turns, so Anna Mueller stays p_001.
TransformResponse turn2 = session.transform("Meine E-Mail ist anna@example.com");

StringBuilder safe = new StringBuilder();
StreamEvent terminal = client.transformStream(
    "Contact Julia Schneider",
    new OGuardAIClient.TransformStreamOptions().policy("default"),
    chunk -> safe.append(chunk));

String sessionState = terminal.sessionState; // rehydrate the streamed output with this

BatchTransformResponse batch = client.batchTransform(new BatchTransformRequest()
    .sessionMode("independent")
    .items(List.of(
        new BatchTransformRequest.Item("Ich bin Anna Mueller").language("de"),
        new BatchTransformRequest.Item("Contact john@example.com").language("en"))));
for (BatchTransformResponse.Result r : batch.results) {
    System.out.println(r.index + " " + r.safeText + " " + r.error);
}

// includeValues(false) keeps raw values out of a value-free caller.
BatchDetectResponse detected = client.batchDetect(new BatchDetectRequest()
    .includeValues(false)
    .items(List.of(new BatchDetectRequest.Item("SSN 123-45-6789").policy("strict-pii"))));

// Revoke a value so future rehydrates return [DELETED].
client.revoke("email", "julia@example.com");
client.bulkRevoke(List.of(new RevokeRequest("email", "a@b.com")));

// Preview policy decisions without transforming (evaluate-policy).
EvaluatePolicyResponse decision = client.evaluatePolicy(
    List.of(new PolicyEntity("email", "julia@example.com")),
    "default");

// 1. Ingest: chunk + tokenize a document, store safe chunks in your vector DB
RagIngestResponse ingest = client.ragIngest(new RagIngestRequest(documentText)
    .chunkingStrategy("paragraph")
    .corpusId("support-kb"));
List<String> docSessions = ingest.chunks.stream()
    .map(c -> c.chunkSessionState).collect(Collectors.toList());

// 2. Query: tokenize the user question for vector search
RagQueryResponse query = client.ragQuery(new RagQueryRequest(userQuestion).corpusId("support-kb"));
List<Hit> hits = vectorSearch(query.safeQuery);

// 3. Context: merge retrieved chunks into a safe LLM context
RagContextResponse ctx = client.ragContext(new RagContextRequest(
        hits.stream().map(h -> h.text).collect(Collectors.toList()), query.sessionState)
    .documentSessions(docSessions)
    .corpusId("support-kb"));
String llmAnswer = callYourLLM(String.join("\n", ctx.safeChunks));

// 4. Answer: restore host-side using the accumulated RAG session
RagAnswerResponse answer = client.ragAnswer(new RagAnswerRequest(llmAnswer, ctx.sessionState)
    .outputChannel("user_output"));

// GDPR erasure: forget every value in an ingest session
client.ragDelete(ingest.chunks.get(0).chunkSessionState);

try {
    client.transform(new TransformRequest().input("..."));
} catch (OGuardAIException e) {
    if (e.isPolicyDenied()) {
        // 403: a redacted entity's rule set on_redact: reject
    } else if (e.isSessionExpired()) {
        // 410: session TTL elapsed
    } else if (e.isOutputBlocked()) {
        // 422: the output guard blocked newly generated PII
    } else if (e.isRateLimited()) {
        String retryAfter = e.retryAfter();
    } else {
        System.out.printf("error [%s] status=%d%n", e.code(), e.statusCode());
    }
}

OGuardAIClient client = OGuardAIClient.builder()
    .baseUrl("http://localhost:3000")   // required
    .apiKey("your-api-key")             // optional: sent as X-API-Key
    .timeout(Duration.ofSeconds(30))    // optional per-attempt timeout (default 30s)
    .maxRetries(3)                       // optional; retries 429/503, honors Retry-After, 0 to disable
    .build();