Gradient Labs Java Client

Java client library for the Gradient Labs API.

Features

• Idiomatic Java API with fluent builders
• Type-safe models and enums
• Webhook signature verification
• Comprehensive error handling
• Java 11+ compatible
• Zero runtime dependencies (except Jackson)

Spring Boot Integration

For Spring Boot applications, use the starter dependency for zero-configuration setup:

Maven

<dependency>
    <groupId>ai.gradientlabs</groupId>
    <artifactId>gradient-labs-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'ai.gradientlabs:gradient-labs-spring-boot-starter:1.0.0'

Configuration

Configure in your application.yml:

gradientlabs:
  api-key: ${GLABS_API_KEY}
  base-url: https://api.gradient-labs.ai  # optional
  webhook-signing-key: ${GLABS_WEBHOOK_KEY}  # optional
  webhook-leeway: 10m  # optional, defaults to 5m

Or in application.properties:

gradientlabs.api-key=${GLABS_API_KEY}
gradientlabs.base-url=https://api.gradient-labs.ai
gradientlabs.webhook-signing-key=${GLABS_WEBHOOK_KEY}
gradientlabs.webhook-leeway=10m

Usage

The client will be automatically configured and available for dependency injection:

import ai.gradientlabs.client.GradientLabsClient;
import org.springframework.stereotype.Service;

@Service
public class ConversationService {

    private final GradientLabsClient client;

    public ConversationService(GradientLabsClient client) {
        this.client = client;
    }

    public void startConversation(String customerId) {
        Conversation conv = client.startConversation(
            StartConversationRequest.builder()
                .id("conv-" + UUID.randomUUID())
                .customerId(customerId)
                .channel(Channel.CHAT)
                .build()
        );
    }
}

See the Spring Boot Starter README for more details.

Installation (Standalone)

For non-Spring applications, use the core client library:

Maven

<dependency>
    <groupId>ai.gradientlabs</groupId>
    <artifactId>gradient-labs-client</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'ai.gradientlabs:gradient-labs-client:1.0.0'

Error Handling

import ai.gradientlabs.client.exception.*;

try {
    Conversation conv = client.startConversation(request);
} catch (ResponseException e) {
    System.err.println("API error: " + e.getMessage());
    System.err.println("Status code: " + e.getStatusCode());
    System.err.println("Trace ID: " + e.getTraceId());

    if (e.getDetails() != null) {
        System.err.println("Details: " + e.getDetails());
    }
} catch (GradientLabsException e) {
    System.err.println("Client error: " + e.getMessage());
}

Configuration

Custom HTTP Client

import java.net.http.HttpClient;
import java.time.Duration;

HttpClient customClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(10))
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build();

GradientLabsClient client = GradientLabsClient.builder()
    .apiKey(apiKey)
    .httpClient(customClient)
    .build();

Custom Base URL

GradientLabsClient client = GradientLabsClient.builder()
    .apiKey(apiKey)
    .baseUrl("https://custom-api.example.com")
    .build();

Webhook Configuration

import java.time.Duration;

GradientLabsClient client = GradientLabsClient.builder()
    .apiKey(apiKey)
    .webhookSigningKey(webhookKey)
    .webhookLeeway(Duration.ofMinutes(10))  // Accept webhooks up to 10 minutes old
    .build();

Requirements

• Java 11 or higher
• Jackson 2.18+ for JSON serialization

Documentation

• API Documentation
• Javadoc
• Design Document

Examples

See the examples/ directory for complete working examples:

• Basic Conversation - Starting and managing conversations
• Webhook Handler - Handling webhook events
• Notes Example - Creating and managing notes
• Hand-Off Targets Example - Managing hand-off targets for conversation routing
• Articles Example - Managing articles and topics for the knowledge base
• Procedures Example - Managing procedures and versions for AI agent instructions

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Support

For issues and questions:

• GitHub Issues
• API Documentation
• Email: support@gradient-labs.ai