gh-giuseppe-trisciuoglio-developer-kit-developer-kit/skills/langchain4j-spring-boot-integration/references/references.md

LangChain4j Spring Boot Integration - API References

Complete API reference for Spring Boot integration with LangChain4j.

Spring Boot Starter Dependencies

Maven

<!-- Core Spring Boot LangChain4j integration -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.27.0</version>
</dependency>

<!-- OpenAI integration -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId>
    <version>0.27.0</version>
</dependency>

Gradle

implementation 'dev.langchain4j:langchain4j-spring-boot-starter:0.27.0'
implementation 'dev.langchain4j:langchain4j-open-ai-spring-boot-starter:0.27.0'

Auto-Configuration Properties

OpenAI Configuration

langchain4j:
  open-ai:
    api-key: ${OPENAI_API_KEY}
    model-name: gpt-4o-mini
    temperature: 0.7
    top-p: 1.0
    max-tokens: 2000
    timeout: 60s
    log-requests: true
    log-responses: true

  openai-embedding:
    api-key: ${OPENAI_API_KEY}
    model-name: text-embedding-3-small
    timeout: 60s

Vector Store Configuration

langchain4j:
  vector-store:
    type: in-memory  # or pinecone, weaviate, qdrant, etc.
    
  # Pinecone
  pinecone:
    api-key: ${PINECONE_API_KEY}
    index-name: my-index
    namespace: production
    
  # Qdrant
  qdrant:
    host: localhost
    port: 6333
    collection-name: documents
    
  # Weaviate
  weaviate:
    host: localhost
    port: 8080
    collection-name: Documents

Spring Configuration Annotations

@Configuration

@Configuration
public class AiConfig {
    
    @Bean
    public ChatModel chatModel() {
        // Bean definition
    }
    
    @Bean
    @ConditionalOnMissingBean
    public EmbeddingModel embeddingModel() {
        // Fallback bean
    }
}

@ConditionalOnProperty

@Configuration
@ConditionalOnProperty(
    prefix = "app.ai",
    name = "enabled",
    havingValue = "true"
)
public class AiFeatureConfig {
    // Configuration only if enabled
}

@EnableConfigurationProperties

@Configuration
@EnableConfigurationProperties(AiProperties.class)
public class AiConfig {
    
    @Autowired
    private AiProperties aiProperties;
}

Dependency Injection

Constructor Injection (Recommended)

@Service
public class ChatService {
    private final ChatModel chatModel;
    private final EmbeddingModel embeddingModel;
    
    public ChatService(ChatModel chatModel, EmbeddingModel embeddingModel) {
        this.chatModel = chatModel;
        this.embeddingModel = embeddingModel;
    }
}

Field Injection (Discouraged)

@Service
public class ChatService {
    @Autowired
    private ChatModel chatModel;  // Not recommended
}

Setter Injection

@Service
public class ChatService {
    private ChatModel chatModel;
    
    @Autowired
    public void setChatModel(ChatModel chatModel) {
        this.chatModel = chatModel;
    }
}

REST Annotations

@RestController with RequestMapping

@RestController
@RequestMapping("/api/chat")
public class ChatController {
    
    @PostMapping
    public ResponseEntity<Response> chat(@RequestBody ChatRequest request) {
        // Implementation
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<Response> getChat(@PathVariable String id) {
        // Implementation
    }
}

RequestBody Validation

@PostMapping
public ResponseEntity<Response> chat(@Valid @RequestBody ChatRequest request) {
    // Validates request object
}

public class ChatRequest {
    @NotBlank(message = "Message cannot be blank")
    private String message;
    
    @Min(0)
    @Max(100)
    private int maxTokens = 2000;
}

Exception Handling

@ControllerAdvice

@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<ErrorResponse> handleBadRequest(IllegalArgumentException e) {
        return ResponseEntity.badRequest()
            .body(new ErrorResponse(400, e.getMessage()));
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGlobalException(Exception e) {
        return ResponseEntity.internalServerError()
            .body(new ErrorResponse(500, "Internal server error"));
    }
}

ResponseStatusException

if (!authorized) {
    throw new ResponseStatusException(
        HttpStatus.FORBIDDEN,
        "User not authorized"
    );
}

Async and Reactive

@Async

@Service
@EnableAsync
public class AsyncService {
    
    @Async
    public CompletableFuture<String> processAsync(String input) {
        String result = processSync(input);
        return CompletableFuture.completedFuture(result);
    }
}

@Scheduled

@Component
public class ScheduledTasks {
    
    @Scheduled(fixedRate = 60000)  // Every minute
    public void performTask() {
        // Task implementation
    }
    
    @Scheduled(cron = "0 0 * * * *")  // Daily at midnight
    public void dailyTask() {
        // Daily task
    }
}

Testing

@SpringBootTest

@SpringBootTest
class ChatServiceTest {
    
    @Autowired
    private ChatService chatService;
    
    @Test
    void testChat() {
        // Test implementation
    }
}

@WebMvcTest

@WebMvcTest(ChatController.class)
class ChatControllerTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @MockBean
    private ChatService chatService;
    
    @Test
    void testChatEndpoint() throws Exception {
        mockMvc.perform(post("/api/chat")
            .contentType(MediaType.APPLICATION_JSON)
            .content("{\"message\": \"Hello\"}"))
            .andExpect(status().isOk());
    }
}

@DataJpaTest

@DataJpaTest
class DocumentRepositoryTest {
    
    @Autowired
    private DocumentRepository repository;
    
    @Test
    void testFindByUserId() {
        // Test implementation
    }
}

Logging Configuration

application.yml

logging:
  level:
    root: INFO
    dev.langchain4j: DEBUG
    org.springframework: WARN
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/app.log

Health Checks

Custom Health Indicator

@Component
public class AiHealthIndicator extends AbstractHealthIndicator {
    
    @Override
    protected void doHealthCheck(Health.Builder builder) {
        try {
            // Check AI service availability
            chatModel.chat("ping");
            builder.up();
        } catch (Exception e) {
            builder.down().withDetail("reason", e.getMessage());
        }
    }
}

Actuator Integration

Maven Dependency

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Configuration

management:
  endpoints:
    web:
      exposure:
        include: health, metrics, info
  endpoint:
    health:
      show-details: always

Security Configuration

@EnableWebSecurity

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .authorizeRequests()
            .antMatchers("/api/public/**").permitAll()
            .antMatchers("/api/private/**").authenticated()
            .and()
            .httpBasic();
        return http.build();
    }
}

Bean Lifecycle

@PostConstruct and @PreDestroy

@Service
public class AiService {
    
    @PostConstruct
    public void init() {
        // Initialize resources
        embeddingStore = createEmbeddingStore();
    }
    
    @PreDestroy
    public void cleanup() {
        // Clean up resources
        embeddingStore.close();
    }
}

Best Practices

1. Use Constructor Injection: Explicitly declare dependencies
2. Externalize Configuration: Use application.yml for settings
3. Handle Exceptions: Use @ControllerAdvice for consistent error handling
4. Implement Caching: Cache AI responses when appropriate
5. Use Async Processing: For long-running AI operations
6. Add Health Checks: Implement custom health indicators
7. Log Appropriately: Debug AI service calls in development
8. Test Thoroughly: Use @SpringBootTest and @WebMvcTest
9. Secure APIs: Implement authentication and authorization
10. Monitor Performance: Track AI service metrics