Claus Ibsen created CAMEL-24330:
-----------------------------------
Summary: Improve AI component documentation based on real-world
user feedback
Key: CAMEL-24330
URL: https://issues.apache.org/jira/browse/CAMEL-24330
Project: Camel
Issue Type: Improvement
Components: camel-openai
Reporter: Claus Ibsen
A blog post by a user building LLM-powered resume processing pipelines with
Camel documented several documentation gaps they hit in practice. These are
actionable improvements that would help users adopting the AI components.
Blog: https://my-tech-profile.dev/insights/llm-integration-with-apache-camel
*Summary of documentation improvements:*
*1. No decision guide for choosing between AI components*
The user treated {{camel-openai}} as the only option and noted it creates
provider lock-in. They were unaware of {{camel-langchain4j-chat}} which
provides provider-agnostic abstraction. Each component documents itself in
isolation and the {{ai-summary.adoc}} index page is auto-generated with no
guidance.
Add a decision matrix or short guide explaining when to use {{camel-openai}}
(OpenAI-compatible APIs, MCP tool calling, agentic loops) vs
{{camel-langchain4j-chat}} (multi-provider abstraction, RAG pipelines).
Cross-reference between the two component docs.
*2. Structured output options (outputClass/jsonSchema) are not prominent enough*
The user hand-coded JSON parsing and validation processors after the model
call, unaware that {{outputClass}} and {{jsonSchema}} endpoint options exist
and would handle this automatically. These options exist in the docs but are
buried and not promoted as the primary approach for structured extraction tasks.
Promote structured output as the recommended approach in the component doc,
especially near the error handling section.
*3. Temperature is not documented for chat operations*
The user listed temperature tuning as something you will not learn from the
docs. The OpenAI component only documents {{audioTemperature}} for audio
operations. For chat, there is no mention of how to control temperature.
Document how to set temperature for chat operations (e.g. via
{{additionalBodyProperty.temperature=0.1}}) and note that low values are
important for structured JSON output.
*4. Streaming patterns for web-facing use cases*
The user said streaming docs were thinner than they would like and abandoned
Camel for their SSE-to-browser feature. The docs describe the mechanism
({{streaming=true}} returns {{Iterator<ChatCompletionChunk>}}) but do not show
practical integration patterns like combining streaming with {{platform-http}}
for SSE responses.
Add a practical streaming example and guidance on when streaming through Camel
fits vs when a dedicated async handler is more appropriate.
*5. Dynamic prompt construction examples*
The user noted that per-exchange prompt headers with Simple expressions are
genuinely convenient but not obvious from the docs. Current examples show only
static prompts.
Add an example showing dynamic prompt construction using Simple expressions
with the {{CamelOpenAIUserMessage}} header.
*6. Prompt management at scale*
The user found prompt management gets messy with multiple routes using inline
prompt strings. No documentation covers patterns for centralizing prompts.
Add a brief best practices note covering loading prompts from resource files,
using property placeholders for prompt fragments, and the template variable
support in LangChain4j.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
