Skip to content

[integration][openai] Align default parameters for openai chat model between java and python#883

Open
rob-9 wants to merge 10 commits into
apache:mainfrom
rob-9:fix/464-align-connection-defaults
Open

[integration][openai] Align default parameters for openai chat model between java and python#883
rob-9 wants to merge 10 commits into
apache:mainfrom
rob-9:fix/464-align-connection-defaults

Conversation

@rob-9

@rob-9 rob-9 commented Jul 7, 2026

Copy link
Copy Markdown

fixes #464

purpose

the Java OpenAI chat model connections (OpenAICompletionsConnection and AzureOpenAIChatModelConnection) didn't set explicit defaults for timeout and max_retries, falling thru to the openai-java SDK's internal values. the Python SDK explicitly defaults to timeout=60s and max_retries=3, meaning the same agent config behaves differently across languages.

this PR aligns Java to match Python:

  • adds shared DEFAULT_TIMEOUT_SECONDS = 60 / DEFAULT_MAX_RETRIES = 3 constants.
  • both Java connections now resolve these via Optional.orElse(DEFAULT_*) so absent args get the explicit default.
  • invalid values (timeout ≤ 0, retries < 0) are clamped to the default instead of silently skipped.
  • javadoc updated to document the new defaults.

testing

  • new OpenAICompletionsConnectionTest asserts correct defaults, explicit overrides work, and api_key validation holds.
  • extended AzureOpenAIChatModelConnectionTest with default-resolution and override assertions.
  • new Python test pinning timeout == 60.0 and max_retries == 3.

docs

  • doc-not-needed

@github-actions github-actions Bot added doc-not-needed Your PR changes do not impact docs fixVersion/0.4.0 priority/major Default priority of the PR or issue. labels Jul 7, 2026
@wenjin272 wenjin272 changed the title [fix][java] align connection default parameters with python SDK [integration][opneai] Align default parameters for openai chat model between java and python Jul 9, 2026
@wenjin272 wenjin272 changed the title [integration][opneai] Align default parameters for openai chat model between java and python [integration][openai] Align default parameters for openai chat model between java and python Jul 9, 2026
@github-actions github-actions Bot added doc-not-needed Your PR changes do not impact docs and removed doc-not-needed Your PR changes do not impact docs labels Jul 9, 2026

@wenjin272 wenjin272 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks for taking this on @rob-9. The code looks good to me, but I think we should also update the documentation.

The user-facing docs still describe the old Java defaults. After this PR, Java OpenAI/Azure connections explicitly default to timeout=60 and max_retries=3, but these tables still mention SDK fallback/None and max_retries=2. Please update the docs to match the new constructor behavior.

@rob-9

rob-9 commented Jul 9, 2026

Copy link
Copy Markdown
Author

@wenjin272 thx

.map(Number::intValue)
.orElse(OpenAIChatCompletionsUtils.DEFAULT_TIMEOUT_SECONDS);
this.timeoutSeconds =
rawTimeout > 0 ? rawTimeout : OpenAIChatCompletionsUtils.DEFAULT_TIMEOUT_SECONDS;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Python validates both fields with Field(ge=0) (openai_chat_model.py:62-71, azure_openai_chat_model.py:70-79), so timeout=-5 or max_retries=-1 raise a ValidationError at construction. Here — and identically in AzureOpenAIChatModelConnection.java:134-143 — an invalid value is silently rewritten to the default. ge=0 also means Python accepts timeout=0, where this > 0 check turns it into 60. So the clamp ends up being the one behavior a parity PR leaves divergent. Is that intentional, or would failing fast (or logging the override) match the Python contract better?

Either way, the branch is currently unexercised — the Java tests cover only the unset and valid-override cases (timeout=120, max_retries=5), so a test pinning whichever behavior you settle on would be worth adding.


private OpenAIChatCompletionsUtils() {}

/** default timeout in seconds for openai api requests (aligned with python sdk). */

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Small housekeeping on these two constants: the Javadoc starts lowercase (default timeout in seconds...) whereas the rest of this file uses sentence case (e.g. Convert a list of... a few lines below). They're also placed after the private constructor and ahead of the mapper/MAP_TYPE fields — constants conventionally sit at the top of the class. Minor, but tidying both would keep the file consistent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc-not-needed Your PR changes do not impact docs fixVersion/0.4.0 priority/major Default priority of the PR or issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Tech Debt] Align default value for python and java openai chatmodel

3 participants