KEMBAR78
Refactor spring boot starters by kpavlov · Pull Request #886 · JetBrains/koog · GitHub
Skip to content

Conversation

kpavlov
Copy link
Collaborator

@kpavlov kpavlov commented Sep 30, 2025

Refactor LLM client auto-configuration structure

  • Removed KoogAutoConfiguration and related legacy configuration files.
  • Introduced modular LLM provider-specific auto-configuration classes (e.g., OpenAILLMAutoConfiguration).
  • Updated test setup to align with the new modular configuration.
  • Enhanced property validation with enabled flag support for finer-grained control.
  • Introduced a String.masked extension to obfuscate sensitive string parts. Added test coverage for various input scenarios, including custom mask characters and edge cases.
  • Updated KoogAutoConfigurationTest to include scenarios where providers are explicitly disabled.
  • Refactored parameterized tests to use textBlock = PROVIDERS with @CsvSource.
  • Adjusted ApplicationContextRunner configuration logic for clean test scenarios.
  • Introduced ignoreUnknownFields to all ConfigurationProperties to improve flexibility with unmapped fields.
  • Expanded property documentation for all LLM clients (e.g., OpenAI, Google, Anthropic) to include detailed descriptions, usage examples, and retry behavior.
  • Improved autowiring safety with @ConditionalOnBean for LLM-specific executors.
  • Updated spring-boot.md to detail enabled flags and their default behavior for LLM providers.
  • Improved clarity by reformatting the supported provider list.
  • Added explanations for default base URLs and explicit activation for non-API-key providers (e.g., Ollama).

A blog post about writing Spring Boot starters is here

NB! Tests need a split and some love, but this PR is already big enough. I will refactor them separately.

Motivation and Context

  • The Spring Boot configuration in general is not very Spring Boot idiomatic
  • The current Spring Boot starter does not expose LLM Clients. In order to get the LLM client in the application, developers have to use reflection to a get a field from the executor 🤯
  • All configuration is encapsulated in one file, which makes extensibility difficult (SRP is violated).
  • Defaults are hardcoded in classes instead of being provided in the resources
  • Ollama is enabled by the presence of the base URL, which is interesting.
  • There is no explicit way to disable an LLM provider: no enabled=true property

Breaking Changes

  • AutoConfiguration classes moved to their respective packages
  • Ollama provider needs ai.koog.ollama.enabled=true to be set explicitly in order to activate.

Type of the changes

  • New feature (non-breaking change which adds functionality)
  • Bug fix (non-breaking change which fixes an issue)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Tests improvement
  • Refactoring

Checklist

  • The pull request has a description of the proposed change
  • I read the Contributing Guidelines before opening the pull request
  • The pull request uses develop as the base branch
  • Tests for the changes have been added
  • All new and existing tests passed
Additional steps for pull requests adding a new feature
  • An issue describing the proposed change exists
  • The pull request includes a link to the issue
  • The change was discussed and approved in the issue
  • Docs have been added / updated

- Introduced a `String.masked` extension to obfuscate sensitive string parts. Added test coverage for various input scenarios, including custom mask characters and edge cases.
- Removed `KoogAutoConfiguration` and related legacy configuration files.
- Introduced modular `LLM` provider-specific auto-configuration classes (e.g., `OpenAILLMAutoConfiguration`).
- Updated test setup to align with the new modular configuration.
- Enhanced property validation with `enabled` flag support for finer-grained control.
@kpavlov kpavlov added enhancement New feature or request refactoring Code improvements that enhance structure, readability, and quality without changing functionality labels Sep 30, 2025
- Updated `KoogAutoConfigurationTest` to include scenarios where providers are explicitly disabled.
- Refactored parameterized tests to use `textBlock = PROVIDERS` with `@CsvSource`.
- Adjusted `ApplicationContextRunner` configuration logic for clean test scenarios.
- Introduced `ignoreUnknownFields` to all `ConfigurationProperties` to improve flexibility with unmapped fields.
- Expanded property documentation for all LLM clients (e.g., OpenAI, Google, Anthropic) to include detailed descriptions, usage examples, and retry behavior.
- Improved autowiring safety with `@ConditionalOnBean` for LLM-specific executors.
- Updated `spring-boot.md` to detail `enabled` flags and their default behavior for LLM providers.
- Improved clarity by reformatting the supported provider list.
- Added explanations for default base URLs and explicit activation for non-API-key providers (e.g., Ollama).
@kpavlov kpavlov requested review from devcrocod and removed request for devcrocod September 30, 2025 10:21
@kpavlov kpavlov added the documentation Improvements or additions to documentation label Sep 30, 2025
@kpavlov kpavlov requested a review from devcrocod September 30, 2025 10:32
@kpavlov kpavlov marked this pull request as ready for review September 30, 2025 10:32
@github-actions
Copy link

github-actions bot commented Sep 30, 2025

Qodana for JVM

832 new problems were found

Inspection name Severity Problems
Check Kotlin and Java source code coverage 🔶 Warning 809
Vulnerable imported dependency 🔶 Warning 17
Missing KDoc for public API declaration 🔶 Warning 5
Unused import directive 🔶 Warning 1
@@ Code coverage @@
+ 70% total lines covered
12529 lines analyzed, 8785 lines covered
# Calculated according to the filters of your coverage tool

☁️ View the detailed Qodana report

Contact Qodana team

Contact us at qodana-support@jetbrains.com

Copy link
Contributor

@devcrocod devcrocod left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm 👍

there are a few minor things

- Replaced `@param` annotations with `@property` for consistency in property definitions across all LLM client classes.
- Updated inline documentation in properties and methods for clarity.
- Grouped multi-line `withPropertyValues` calls in tests for conciseness and improved readability.
@kpavlov kpavlov merged commit 5a05fed into develop Sep 30, 2025
11 checks passed
@kpavlov kpavlov deleted the kpavlov/refactor-spring-boot-starters branch September 30, 2025 19:24
Ololoshechkin pushed a commit that referenced this pull request Oct 2, 2025
Refactor LLM client auto-configuration structure

- Removed `KoogAutoConfiguration` and related legacy configuration
files.
- Introduced modular `LLM` provider-specific auto-configuration classes
(e.g., `OpenAILLMAutoConfiguration`).
- Updated test setup to align with the new modular configuration.
- Enhanced property validation with `enabled` flag support for
finer-grained control.
- Introduced a `String.masked` extension to obfuscate sensitive string
parts. Added test coverage for various input scenarios, including custom
mask characters and edge cases.
- Updated `KoogAutoConfigurationTest` to include scenarios where
providers are explicitly disabled.
- Refactored parameterized tests to use `textBlock = PROVIDERS` with
`@CsvSource`.
- Adjusted `ApplicationContextRunner` configuration logic for clean test
scenarios.
- Introduced `ignoreUnknownFields` to all `ConfigurationProperties` to
improve flexibility with unmapped fields.
- Expanded property documentation for all LLM clients (e.g., OpenAI,
Google, Anthropic) to include detailed descriptions, usage examples, and
retry behavior.
- Improved autowiring safety with `@ConditionalOnBean` for LLM-specific
executors.
- Updated `spring-boot.md` to detail `enabled` flags and their default
behavior for LLM providers.
- Improved clarity by reformatting the supported provider list.
- Added explanations for default base URLs and explicit activation for
non-API-key providers (e.g., Ollama).

A blog post about writing Spring Boot starters is
[here](https://kpavlov.me/blog/spring-boot-starters)

**NB! Tests need a split and some love, but this PR is already big
enough. I will refactor them separately.**

## Motivation and Context

- The Spring Boot configuration in general is not very Spring Boot
idiomatic
- The current Spring Boot starter does not expose LLM Clients. In order
to get the LLM client in the application, developers have to use
reflection to a get a field from the executor 🤯
- All configuration is encapsulated in one file, which makes
extensibility difficult (SRP is violated).
- Defaults are hardcoded in classes instead of being provided in the
resources
- Ollama is enabled by the presence of the base URL, which is
interesting.
- There is no explicit way to disable an LLM provider: no `enabled=true`
property

## Breaking Changes

- AutoConfiguration classes moved to their respective packages
- Ollama provider needs `ai.koog.ollama.enabled=true` to be set
explicitly in order to activate.

---

#### Type of the changes
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [x] Tests improvement
- [x] Refactoring

#### Checklist
- [x] The pull request has a description of the proposed change
- [ ] I read the [Contributing
Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md)
before opening the pull request
- [x] The pull request uses **`develop`** as the base branch
- [ ] Tests for the changes have been added
- [ ] All new and existing tests passed

##### Additional steps for pull requests adding a new feature
- [ ] An issue describing the proposed change exists
- [ ] The pull request includes a link to the issue
- [ ] The change was discussed and approved in the issue
- [x] Docs have been added / updated

(cherry picked from commit 5a05fed)
karloti pushed a commit to karloti/koog that referenced this pull request Oct 21, 2025
Refactor LLM client auto-configuration structure

- Removed `KoogAutoConfiguration` and related legacy configuration
files.
- Introduced modular `LLM` provider-specific auto-configuration classes
(e.g., `OpenAILLMAutoConfiguration`).
- Updated test setup to align with the new modular configuration.
- Enhanced property validation with `enabled` flag support for
finer-grained control.
- Introduced a `String.masked` extension to obfuscate sensitive string
parts. Added test coverage for various input scenarios, including custom
mask characters and edge cases.
- Updated `KoogAutoConfigurationTest` to include scenarios where
providers are explicitly disabled.
- Refactored parameterized tests to use `textBlock = PROVIDERS` with
`@CsvSource`.
- Adjusted `ApplicationContextRunner` configuration logic for clean test
scenarios.
- Introduced `ignoreUnknownFields` to all `ConfigurationProperties` to
improve flexibility with unmapped fields.
- Expanded property documentation for all LLM clients (e.g., OpenAI,
Google, Anthropic) to include detailed descriptions, usage examples, and
retry behavior.
- Improved autowiring safety with `@ConditionalOnBean` for LLM-specific
executors.
- Updated `spring-boot.md` to detail `enabled` flags and their default
behavior for LLM providers.
- Improved clarity by reformatting the supported provider list.
- Added explanations for default base URLs and explicit activation for
non-API-key providers (e.g., Ollama).

A blog post about writing Spring Boot starters is
[here](https://kpavlov.me/blog/spring-boot-starters)

**NB! Tests need a split and some love, but this PR is already big
enough. I will refactor them separately.**

## Motivation and Context

- The Spring Boot configuration in general is not very Spring Boot
idiomatic
- The current Spring Boot starter does not expose LLM Clients. In order
to get the LLM client in the application, developers have to use
reflection to a get a field from the executor 🤯
- All configuration is encapsulated in one file, which makes
extensibility difficult (SRP is violated).
- Defaults are hardcoded in classes instead of being provided in the
resources
- Ollama is enabled by the presence of the base URL, which is
interesting.
- There is no explicit way to disable an LLM provider: no `enabled=true`
property

## Breaking Changes

- AutoConfiguration classes moved to their respective packages
- Ollama provider needs `ai.koog.ollama.enabled=true` to be set
explicitly in order to activate.

---

#### Type of the changes
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [x] Tests improvement
- [x] Refactoring

#### Checklist
- [x] The pull request has a description of the proposed change
- [ ] I read the [Contributing
Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md)
before opening the pull request
- [x] The pull request uses **`develop`** as the base branch
- [ ] Tests for the changes have been added
- [ ] All new and existing tests passed

##### Additional steps for pull requests adding a new feature
- [ ] An issue describing the proposed change exists
- [ ] The pull request includes a link to the issue
- [ ] The change was discussed and approved in the issue
- [x] Docs have been added / updated

(cherry picked from commit 5a05fed)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request refactoring Code improvements that enhance structure, readability, and quality without changing functionality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants