Skip to content

CAMEL-26514: camel-langchain4j-embeddings - set the CamelLangChain4jEmbeddingsResponseModel header - #29654

Merged
davsclaus merged 2 commits into
apache:mainfrom
urunni88:CAMEL-26514-embeddings-response-model
Nov 12, 2026
Merged

davsclaus merged 2 commits into
apache:mainfrom
urunni88:CAMEL-26514-embeddings-response-model

Conversation

@urunni88

Copy link
Copy Markdown
Contributor

Description

CAMEL-26514: the producer called EmbeddingModel.embed(TextSegment) and embedAll(List), whose Response does not carry the model name, so the documented CamelLangChain4jEmbeddingsResponseModel header was never set.

Following the recommendation on the JIRA, the producer now calls embed(EmbeddingRequest) for both a single body and a List body, and sets the header from EmbeddingResponse.modelName() when it is not null.

As noted on the JIRA, this has two side effects, both described in the 4.24 upgrade guide:

  • EmbeddingResponse has no finish reason, so the CamelLangChain4jEmbeddingsFinishReason header is no longer set. Happy to deprecate that header here or in a follow-up if you prefer.
  • A model that only overrides embed(TextSegment) is bypassed: LangChain4j's default methods then call each other until a StackOverflowError. The stub models of LangChain4jEmbeddingsObservabilityTest and LangChain4jEmbeddingsErrorMetadataTest hit exactly this, so they now implement embedAll(List<TextSegment>), as the LangChain4j models do.

Test: LangChain4jEmbeddingsObservabilityTest.shouldSetResponseModelHeader sends a single body and a List body and checks the header on each message. It fails without the fix (the header is null) and passes with it. All 21 tests of the module pass.

Target

  • I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

  • If this is a large change, bug fix, or code improvement, I checked there is a JIRA issue filed for the change (usually before you start working on it).

Apache Camel coding standards and style

  • I checked that each commit in the pull request has a meaningful subject line and body.

  • I have run mvn clean install -DskipTests locally from root folder and I have committed all auto-generated changes.

AI-assisted contributions

  • If this PR includes AI-generated code, commits have proper co-authorship attribution (e.g., Co-authored-by trailers) and the PR description identifies the AI tool used.

This PR was prepared with the help of Claude (Anthropic), credited with a Co-authored-by trailer in the commit.

…mbeddingsResponseModel header

The producer now calls embed(EmbeddingRequest), whose EmbeddingResponse gives the model name. The test models implement embedAll, as the default methods of LangChain4j need.

Co-authored-by: Claude <noreply@anthropic.com>

@gnodet-bot gnodet-bot 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.

The PR migrates from Response<Embedding> to EmbeddingResponse API, but removeResultHeaders was not updated to match.

Bug: Stale RESPONSE_MODEL header

In populateHeaders, the PR replaces:

message.setHeader(LangChain4jEmbeddingsHeaders.FINISH_REASON, result.finishReason().toString());

with:

message.setHeader(LangChain4jEmbeddingsHeaders.RESPONSE_MODEL, result.modelName());

However, removeResultHeaders (called at the top of both populateHeaders and populateBatchHeaders to clear stale values) was NOT updated — it still removes FINISH_REASON (which is never set anymore) and does NOT remove RESPONSE_MODEL (which IS now set).

This means when a Message object is reused across multiple calls, RESPONSE_MODEL can carry a stale value from the previous call.

Fix: In removeResultHeaders, replace:

message.removeHeader(LangChain4jEmbeddingsHeaders.FINISH_REASON);

with:

message.removeHeader(LangChain4jEmbeddingsHeaders.RESPONSE_MODEL);

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@oscerd oscerd 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.

Correct fix for the real bug: embed(TextSegment) / embedAll(List) return a Response that does not carry the model name, so the documented CamelLangChain4jEmbeddingsResponseModel header was never set, and moving to embed(EmbeddingRequest) is the way to get an EmbeddingResponse that has modelName(). Setting the header only when modelName() is non-null is the right guard.

What makes this a good PR rather than just a fix is that the upgrade guide is honest about the two consequences, both of which matter:

  • FINISH_REASON is no longer set because EmbeddingResponse has no finish reason. For embeddings that header was effectively always null anyway (the generic Response.finishReason() is not populated for an embedding call), so in practice nobody was receiving it, and the guide says so. The one loose end is that LangChain4jEmbeddingsHeaders.FINISH_REASON is still declared with @Metadata, so it now advertises a header the producer never sets; worth either dropping that declaration for consistency or leaving a line, though keeping the constant does avoid breaking anyone who references it.
  • The sharper one, and good that it is called out, is that a custom EmbeddingModel that only overrides embed(TextSegment) is no longer invoked and the LangChain4j default methods then recurse into a StackOverflowError. That is a genuine breaking change for downstream custom models, and spelling out that they must implement embedAll(List) or doEmbed(EmbeddingRequest) is exactly the guidance those users need.

Tests updated for the metadata and observability paths. CI does not appear to have run on the fork, so this is a source review; the behaviour change is real but documented. LGTM.

Claude Code on behalf of oscerd

@github-actions

Copy link
Copy Markdown
Contributor

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

  • First-time contributors require MANUAL approval for the GitHub Actions to run
  • You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
  • You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
  • Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

@davsclaus davsclaus 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 @urunni88, this follows the option recommended on CAMEL-26514, and the upgrade guide entry explains both side effects (no finish reason, a model that only overrides embed(TextSegment) now fails). I checked the StackOverflowError claim against LangChain4j 1.23.0: embed(EmbeddingRequest) → doEmbed → embedAll → embed(EmbeddingRequest), so a model has to override embedAll or doEmbed. Note that the batch path already went through embedAll before this PR, so only the single-body path changes for such a model.

Findings:

  1. (medium) The GenAI span still has no response model. GenAiUsage.of(input, output, finishReason, responseModel): the 4th argument is the response model, and both calls pass null (LangChain4jEmbeddingsProducer.java:95 and :129). The JIRA mentions this too ("and the GenAI usage has no response model"). Pass result.modelName() there, the way LangChain4jChatProducer does, so gen_ai.response.model is set (GenAiObservabilityImpl only sets the tag when it is not blank). shouldEmitGenAiSpanFromEmbeddingsProducer can then also assert tags.get(GenAiAttributes.RESPONSE_MODEL).

  2. (medium) removeResultHeaders (LangChain4jEmbeddingsProducer.java:186) clears the headers of an earlier call, but it does not remove RESPONSE_MODEL, which this PR now sets. When a message goes through two embeddings endpoints, and the second model returns no model name, the first model's name stays on the message. Add message.removeHeader(LangChain4jEmbeddingsHeaders.RESPONSE_MODEL). gnodet-bot proposed replacing the FINISH_REASON removal; I would keep that line too, because the header name is still public and a stale value should still be cleared.

  3. (low) FINISH_REASON is still declared with @Metadata (LangChain4jEmbeddingsHeaders.java:23-24), so the catalog and the component doc still list a header that is never set. Either mark it deprecated in this PR (constant @Deprecated and a deprecation note in @Metadata, then commit the regenerated langchain4j-embeddings.json, catalog JSON and endpoint DSL), or open a follow-up JIRA. I am fine either way; say which one in the PR.

  4. (low) result.embeddings().get(0) (LangChain4jEmbeddingsProducer.java:215) throws a bare IndexOutOfBoundsException if a model returns no embedding. LangChain4j's own embed(TextSegment) checks the size with ensureEq. A check with a clear message would be nicer, but it is optional.

  5. (nit) The upgrade-guide section is added after the last "Jackson 3 - ..." subsection, so it reads as part of that group. Moving it before === Jackson 3, next to the other component sections, would be better.

Tests: shouldSetResponseModelHeader covers the single and the List body, uses AssertJ and assertIsSatisfied with a timeout. Good. CI is running on the head.

Claude Code on behalf of Claus Ibsen. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

🧪 CI tested the following changed modules:

  • components/camel-ai/camel-langchain4j-embeddings
  • docs

🔬 Scalpel shadow comparison — Scalpel: 10 of 722 tested, 26 compile-only — current: 10 all tested

Maveniverse Scalpel detected 10 affected modules (current approach: 10).

Skip-tests mode would test 10 modules (2 direct + 9 downstream), skip tests for 26 (generated code, meta-modules)

Modules Scalpel would test (10)
  • camel-jbang-mcp ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-mcp ← downstream of org.apache.camel:camel-jbang-core
  • camel-jbang-plugin-tui ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-validate ← downstream of org.apache.camel:camel-yaml-dsl-validator
  • camel-jbang-run ← downstream of org.apache.camel:camel-catalog
  • camel-langchain4j-embeddings ← components/camel-ai/camel-langchain4j-embeddings/src/main/java/org/apache/camel/component/langchain4j/embeddings/LangChain4jEmbeddingsProducer.java, components/camel-ai/camel-langchain4j-embeddings/src/test/java/org/apache/camel/component/langchain4j/embeddings/LangChain4jEmbeddingsErrorMetadataTest.java, components/camel-ai/camel-langchain4j-embeddings/src/test/java/org/apache/camel/component/langchain4j/embeddings/LangChain4jEmbeddingsObservabilityTest.java
  • camel-langchain4j-embeddingstore ← downstream of org.apache.camel:camel-langchain4j-embeddings
  • camel-launcher-container ← downstream of org.apache.camel:camel-launcher
  • camel-yaml-dsl-validator ← downstream of org.apache.camel:camel-catalog
  • camel-yaml-dsl-validator-maven-plugin ← downstream of org.apache.camel:camel-yaml-dsl-validator
Modules with tests skipped (26)
  • apache-camel
  • camel-allcomponents
  • camel-catalog
  • camel-catalog-console
  • camel-catalog-maven
  • camel-catalog-suggest
  • camel-componentdsl
  • camel-endpointdsl
  • camel-endpointdsl-support
  • camel-itest
  • camel-jbang-core
  • camel-jbang-it
  • camel-jbang-main
  • camel-jbang-plugin-edit
  • camel-jbang-plugin-generate
  • camel-jbang-plugin-kubernetes
  • camel-jbang-plugin-test
  • camel-kamelet-main
  • camel-launcher
  • camel-report-maven-plugin
  • camel-route-parser
  • camel-yaml-dsl
  • camel-yaml-dsl-deserializers
  • camel-yaml-dsl-maven-plugin
  • coverage
  • dummy-component

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

All tested modules (37 modules, 5m 16s total)

Total reactor time: 5m 16s

Module Duration Status
Camel :: YAML DSL :: Validator 30.5s SUCCESS
Camel :: Component DSL 27.7s SUCCESS
Camel :: JBang :: Plugin :: Validate 25.6s SUCCESS
Camel :: Catalog :: Camel Catalog 24.8s SUCCESS
Camel :: YAML DSL 24.3s SUCCESS
Camel :: AI :: LangChain4j :: EmbeddingStore 23.3s SUCCESS
Camel :: JBang :: Run 21.9s SUCCESS
Camel :: JBang :: Plugin :: Kubernetes 20.1s SUCCESS
Camel :: Kamelet Main 18.7s SUCCESS
Camel :: Docs 15.8s SUCCESS
Camel :: JBang :: Plugin :: Testing 13.1s SUCCESS
Camel :: Assembly 10.5s SUCCESS
Camel :: Catalog :: Camel Report Maven Plugin 8.4s SUCCESS
Camel :: YAML DSL :: Deserializers 7.8s SUCCESS
Camel :: Catalog :: Camel Route Parser 7.8s SUCCESS
Camel :: JBang :: Plugin :: Generate 6.2s SUCCESS
Camel :: All Components Sync point 5.3s SUCCESS
Camel :: YAML DSL :: Validator Maven Plugin 5.2s SUCCESS
Camel :: Catalog :: Maven 3.2s SUCCESS
Camel :: YAML DSL :: Maven Plugins 3.0s SUCCESS
Camel :: Catalog :: Suggest (deprecated) 3.0s SUCCESS
Camel :: JBang :: Plugin :: MCP 2.2s SUCCESS
Camel :: Coverage 1.5s SUCCESS
Camel :: JBang :: Integration tests 1.1s SUCCESS
Camel :: Catalog :: Dummy Component 1.0s SUCCESS
Camel :: JBang :: Plugin :: Edit 1.0s SUCCESS
Camel :: Endpoint DSL :: Support 1.0s SUCCESS
Camel :: Catalog :: Console 0.8s SUCCESS
Camel :: Launcher :: Container 0.8s SUCCESS
Camel :: JBang :: Main 0.7s SUCCESS
Camel :: AI :: LangChain4j :: Embedding n/a
Camel :: Endpoint DSL n/a
Camel :: Integration Tests n/a
Camel :: JBang :: Core n/a
Camel :: JBang :: MCP n/a
Camel :: JBang :: Plugin :: TUI n/a
Camel :: Launcher n/a

Top 20 slowest modules:

  • Camel :: YAML DSL :: Validator (30.5s)
  • Camel :: Component DSL (27.7s)
  • Camel :: JBang :: Plugin :: Validate (25.6s)
  • Camel :: Catalog :: Camel Catalog (24.8s)
  • Camel :: YAML DSL (24.3s)
  • Camel :: AI :: LangChain4j :: EmbeddingStore (23.3s)
  • Camel :: JBang :: Run (21.9s)
  • Camel :: JBang :: Plugin :: Kubernetes (20.1s)
  • Camel :: Kamelet Main (18.7s)
  • Camel :: Docs (15.8s)
  • Camel :: JBang :: Plugin :: Testing (13.1s)
  • Camel :: Assembly (10.5s)
  • Camel :: Catalog :: Camel Report Maven Plugin (8.4s)
  • Camel :: YAML DSL :: Deserializers (7.8s)
  • Camel :: Catalog :: Camel Route Parser (7.8s)
  • Camel :: JBang :: Plugin :: Generate (6.2s)
  • Camel :: All Components Sync point (5.3s)
  • Camel :: YAML DSL :: Validator Maven Plugin (5.2s)
  • Camel :: Catalog :: Maven (3.2s)
  • Camel :: YAML DSL :: Maven Plugins (3.0s)

⚙️ View full build and test results

Pass the response model to the GenAI span, clear a stale CamelLangChain4jEmbeddingsResponseModel header, fail clearly when a model returns no embedding, and move the upgrade guide section before the Jackson 3 sections.

Co-authored-by: Claude <noreply@anthropic.com>
@urunni88

Copy link
Copy Markdown
Contributor Author

Thanks for the review, @davsclaus! I pushed a commit for the findings:

  1. The response model is now passed to GenAiUsage.of(...) in both paths, and shouldEmitGenAiSpanFromEmbeddingsProducer asserts the gen_ai.response.model tag.
  2. removeResultHeaders now also removes RESPONSE_MODEL (this was gnodet-bot's point too). I kept the FINISH_REASON removal, as you suggested.
  3. For FINISH_REASON, I'd prefer a follow-up JIRA to deprecate it, so this PR stays focused. I can open it and send a PR for it.
  4. An empty embeddings list now fails with an IllegalStateException with a clear message instead of an IndexOutOfBoundsException.
  5. The upgrade guide section is moved before the Jackson 3 sections.

All 21 tests of the module pass locally.

@gnodet-bot gnodet-bot 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.

Following up on my earlier review — all 4 findings have been addressed in the new commit.

✅ Stale RESPONSE_MODEL header — removeResultHeaders now clears RESPONSE_MODEL before repopulating headers.
✅ GenAI span missing response model — both processSingle and processBatch now pass result.modelName() as the 4th argument to GenAiUsage.of().
✅ Empty embeddings guard — populateHeaders now checks result.embeddings() for null/empty and throws IllegalStateException with a clear message instead of a bare IndexOutOfBoundsException.
✅ Upgrade guide position — the langchain4j-embeddings section now appears before the Jackson 3 sections.

The FINISH_REASON @Metadata constant remaining declared (davsclaus finding #3) is pre-existing and the deferral to a follow-up JIRA is acceptable.

Test stubs correctly override embedAll(List<TextSegment>), which is where LangChain4j's default embed(EmbeddingRequest) dispatches. LGTM.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@davsclaus davsclaus 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 @urunni88 for the quick turnaround. I went through 02af57f against my earlier review:

  1. GenAI span response model: fixed. Both GenAiUsage.of(...) calls now pass result.modelName() (LangChain4jEmbeddingsProducer.java:95 and :129). shouldEmitGenAiSpanFromEmbeddingsProducer asserts gen_ai.response.model (LangChain4jEmbeddingsObservabilityTest.java:92).
  2. Stale RESPONSE_MODEL: fixed. removeResultHeaders now also clears RESPONSE_MODEL (:189), and the FINISH_REASON removal stays.
  3. FINISH_REASON still declared with @Metadata: you chose a follow-up JIRA, which is fine with me. I could not find it in JIRA yet; when you open it, please link it here so the loose end stays visible.
  4. Empty embeddings: fixed. An empty or null list now fails with IllegalStateException("The embedding model returned no embedding") (:216-218). It is thrown inside the try, so the error is still recorded on the span.
  5. Upgrade-guide position: fixed. The section now sits before === Jackson 3.

I found no new problems in the delta, and the PR still merges cleanly with main. CI on the head is still running; approving on the condition that it goes green.

Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.

@urunni88

Copy link
Copy Markdown
Contributor Author

Thanks @davsclaus! I opened the follow-up for FINISH_REASON: https://issues.apache.org/jira/browse/CAMEL-26873. I'll send a PR for it once this one is merged.

@davsclaus
davsclaus merged commit c764c51 into apache:main Nov 12, 2026
7 checks passed
@davsclaus davsclaus added this to the 4.24.0 milestone Nov 12, 2026
@davsclaus davsclaus added enhancement New feature or request and removed components docs components-ai labels Nov 12, 2026
@urunni88
urunni88 deleted the CAMEL-26514-embeddings-response-model branch November 13, 2026 03:58
@urunni88

Copy link
Copy Markdown
Contributor Author

The follow-up PR for CAMEL-26873 is here: #29794

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

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants