[
https://issues.apache.org/jira/browse/CAMEL-24330?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-24330:
--------------------------------
Fix Version/s: 4.22.0
> 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
> Assignee: Omar Atie
> Priority: Major
> Labels: documentation
> Fix For: 4.22.0
>
>
> 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)
