Java SDK

Install and configure the Cognisafe Java SDK.

Installation

Maven (pom.xml)

<dependency>
  <groupId>uk.cognisafe</groupId>
  <artifactId>cognisafe-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Requires Java 11 or higher.

Configuration

Configure the SDK once at application startup using the builder pattern:

import uk.cognisafe.Cognisafe;
import uk.cognisafe.CognisafeConfig;

Cognisafe.configure(
    CognisafeConfig.builder()
        .apiKey("csk_your_key_here")   // or reads COGNISAFE_API_KEY
        .projectId("my-app")           // or reads COGNISAFE_PROJECT_ID
        .proxyUrl("http://localhost:8080")  // default; omit for cloud
        .apiUrl("http://localhost:8000")    // default; omit for cloud
        .build()
);

Configuration options

Option	Type	Required	Default	Description
apiKey	String	Yes*	COGNISAFE_API_KEY	Your project API key (csk_...)
projectId	String	Yes*	COGNISAFE_PROJECT_ID	Project identifier for grouping requests
proxyUrl	String	No	http://localhost:8080	Cognisafe Go proxy URL
apiUrl	String	No	http://localhost:8000	Cognisafe FastAPI backend URL

* Required if the corresponding environment variable is not set.

The SDK is thread-safe. Call Cognisafe.configure() once at startup (e.g., in your Spring @Configuration class or main() method) — it initialises a shared singleton. Do not call configure() per-request.

Patching the OpenAI Java client

import uk.cognisafe.Cognisafe;
import uk.cognisafe.CognisafeConfig;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

Cognisafe.configure(
    CognisafeConfig.builder()
        .apiKey("csk_your_key_here")
        .projectId("my-app")
        .build()
);

// The SDK provides a factory method that returns a pre-configured client
OpenAIClient client = Cognisafe.openAIClient();

var response = client.chat().completions().create(
    ChatCompletionCreateParams.builder()
        .model(ChatModel.GPT_4O)
        .addUserMessage("Hello from Java!")
        .build()
);

System.out.println(response.choices().get(0).message().content());

Cognisafe.openAIClient() returns a standard OpenAIClient with the baseUrl pre-configured to point at the Cognisafe proxy. You can also configure your own client by setting the base URL manually:

OpenAIClient client = OpenAIOkHttpClient.builder()
    .baseUrl(Cognisafe.getProxyUrl())
    .apiKey("your-openai-api-key")
    .build();

The @CognisafeTrace annotation (Spring Boot)

For Spring Boot applications, use the @CognisafeTrace annotation on any method that calls an LLM. The SDK uses Spring AOP to intercept the call and log the inputs and outputs:

import uk.cognisafe.annotation.CognisafeTrace;
import org.springframework.stereotype.Service;

@Service
public class LlmService {

    @CognisafeTrace(model = "gpt-4o")
    public String summarise(String text) {
        // your LLM call — HTTP, custom client, etc.
        return callMyInternalModel(text);
    }
}

The annotation captures:

• Method arguments (serialised to JSON)
• Return value (serialised to JSON)
• Execution time (latency)

Results are shipped to /internal/log in a background thread — the annotated method is not blocked.

@CognisafeTrace requires the cognisafe-sdk-spring module. Add it alongside the core SDK:

<dependency>
  <groupId>uk.cognisafe</groupId>
  <artifactId>cognisafe-sdk-spring</artifactId>
  <version>1.0.0</version>
</dependency>

Non-Spring usage (manual trace)

Without Spring AOP, wrap calls manually using Cognisafe.trace():

import uk.cognisafe.Cognisafe;
import java.util.concurrent.Callable;

String result = Cognisafe.trace(
    () -> callMyInternalModel(prompt),
    "my-model",   // model name tag
    prompt        // input to record
);