CAMEL-24330: Improve AI component documentation based on user feedback

[davsclaus]

Summary

Improves the AI component documentation based on real-world user feedback from a blog post by a developer building LLM-powered pipelines with Camel. The author documented several documentation gaps they hit in practice.

Changes:

• AI summary page: Added a "Choosing the Right AI Component" decision guide with a comparison table between camel-openai and camel-langchain4j-chat, helping users pick the right component for their needs
• OpenAI component: Added a "Tips for Production Use" section covering:
  • Temperature and model parameters (low temperature for structured output)
  • Dynamic prompt construction with Simple expressions
  • Structured output (outputClass/jsonSchema) as the recommended approach for JSON extraction
  • Handling model output errors (200 responses with unusable content)
  • Prompt management at scale (resource files, property placeholders)
  • Streaming considerations (pipeline vs user-facing scenarios)
• LangChain4j Chat component: Added cross-reference to the OpenAI component and AI summary decision guide

Test plan

• Verify AsciiDoc renders correctly on the Camel website
• Verify all xref: links resolve to valid targets
• Review decision table for accuracy

Claude Code on behalf of davsclaus

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

[gnodet]

🤖 AI-assisted review — Claude Code on behalf of @gnodet

---

Review: CAMEL-24330 — Improve AI component documentation

Nice additions — the decision guide comparing camel-openai vs camel-langchain4j-chat, the production tips, and the cross-references between AI docs are all useful. One issue to fix:

[MINOR] Broken xref — wrong Antora module prefix

In langchain4j-chat-component.adoc, the xref uses the others: module prefix:

xref:others:ai-summary.adoc[Choosing the Right AI Component]

But ai-summary.adoc lives in the ROOT module (docs/components/modules/ROOT/pages/ai-summary.adoc) — it matches the *-summary.adoc pattern routed to ROOT by PrepareDocSymlinksMojo. Since langchain4j-chat-component.adoc is also in ROOT, this should be:

xref:ai-summary.adoc[Choosing the Right AI Component]

(Note: the others:openai-mcp.adoc xrefs in openai-component.adoc are correct since that file genuinely lives in the others module.)

Everything else looks good — the code examples are accurate and the comparison table is helpful. 👍

[github-actions]

🌟 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.

[atiaomar1978-hub]

AI-generated comment on behalf of atiaomar1978-hub

@davsclaus — per your suggestion on #25313, the useful content from this PR (OpenAI production tips, ai-summary comparison table, langchain4j cross-links) has been incorporated into #25313 in commit 28c001d79af, alongside the dedicated LLM Integration Guide.

Happy to close this PR in favour of #25313 if that works for you.

[davsclaus]

duplicate closing