[
https://issues.apache.org/jira/browse/CAMEL-23882?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-23882:
--------------------------------
Priority: Minor (was: Major)
> camel - improve llms.txt for better AI assistance
> -------------------------------------------------
>
> Key: CAMEL-23882
> URL: https://issues.apache.org/jira/browse/CAMEL-23882
> Project: Camel
> Issue Type: Improvement
> Components: website
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Minor
> Fix For: 4.22.0
>
>
> ```
> **Yes, I have detailed feedback.** The current `llms.txt` is already one of
> the better LLM-oriented overviews I've seen for a major open-source project.
> It does an excellent job of: - Giving a crisp, marketing-free summary of what
> Camel *is* and its value proposition. - Highlighting the modern developer
> experience (Camel CLI/JBang, hot-reload, TUI, `camel dev`/`trace`/`export`).
> - Covering AI-relevant features (MCP server, A2A, LangChain4j/OpenAI
> components). - Pointing LLMs to the right resources (Markdown docs, offline
> bundles, catalog JSON, YAML schema). - Including maintainer transparency and
> key stats. It was clearly written with LLMs in mind (following the llms.txt
> spec) and benefits from the automated Markdown conversion pipeline introduced
> in late 2025. ### Suggestions to Improve llms.txt Here are targeted,
> high-impact improvements (prioritized by likely benefit for AI accuracy): 1.
> **Add a "Core Concepts" section** (highest priority) Many LLMs still
> hallucinate or mix up fundamentals. Add short, precise definitions for: -
> `CamelContext` - `Route` / `RouteBuilder` - `Endpoint` + URI syntax -
> `Exchange` / `Message` (In/Out, headers, properties, body) - `Processor` /
> `ProcessorFactory` - `Component` - Lifecycle (start/stop, suspend/resume) 2.
> **Include 4–6 minimal, canonical examples** One YAML + one Java version for
> common patterns: - Timer → log - File polling → transform → Kafka / REST -
> Content-based router (`choice`) - Simple error handling (`onException` + Dead
> Letter Channel) - REST DSL or platform-http - Basic aggregation or splitter
> Keep them under 15–20 lines each. This dramatically reduces syntax errors in
> generated code. 3. **Expand the YAML DSL section** YAML is increasingly the
> recommended entry point for many users and AI-assisted development. Add: -
> Key syntax rules and structure (`- from:`, `steps:`, `choice:`, `when:`,
> `otherwise:`, etc.). - Mention of route templates and Kamelets. - Strong
> pointer to the canonical `camelYamlDsl-canonical.json` schema. 4. **Add a
> "Common Pitfalls & Best Practices" section** Draw from real-world experience
> (there are good community articles on this). Cover: - "God routes" (too much
> logic in one route). - Putting business logic directly in the DSL vs. using
> beans/processors. - Over-reliance on processors instead of EIPs. - Error
> handling anti-patterns. - Performance gotchas (streaming vs. in-memory, large
> payloads). - When *not* to use Camel (trivial single calls, heavy data
> transformation/ETL, etc.). 5. **Strengthen Error Handling, Testing, and
> Observability** These are areas where production accuracy matters most. Short
> dedicated subsections would help. 6. **Enhance the AI/Agent section** -
> Explicit guidance on how AI agents should use the MCP server + catalog JSON.
> - Best practices for prompting Camel code (e.g., "always validate against the
> YAML schema", "prefer EIPs over custom processors"). - Mention of structured
> output / JSON Schema support in recent releases. 7. **Other useful additions
> (keep concise)**: - Brief runtime comparison (Spring Boot vs. Quarkus vs.
> standalone). - Quick note on deployment (Kubernetes, containers, health
> checks, OpenTelemetry). - Versioning guidance (current major version, LTS
> policy). - Link to the official "When to use Apache Camel" page. **General
> formatting tips for llms.txt**: - Keep the file relatively short and
> scannable (bullets and short paragraphs work best). - Use consistent
> terminology. - Add a "How to use this file" note for AI agents at the top. -
> Consider a small "Quick Reference" table or list of most-used URIs / EIPs.
> These changes would make the file even more effective as a "system prompt" or
> context document for coding assistants. ### What AI Models Need to Learn for
> Higher Accuracy on Apache Camel To answer Camel questions reliably
> (especially code generation and architecture advice), models should
> internalize: - **Enterprise Integration Patterns (EIPs)** — Deep mapping
> between the classic patterns and Camel’s fluent/declarative implementations.
> - **Endpoint URI syntax and component parameters** — This is where most
> hallucinations happen. Models should know how to look up options via the
> catalog rather than guessing. - **YAML DSL structure** (increasingly
> important) — Declarative nature, nesting of steps, `choice`/`when`,
> expressions, etc. - **Message model & Exchange lifecycle** — Headers vs.
> properties, InOnly/InOut, fault handling. - **Expression languages**,
> especially the powerful **Simple** language. - **Error handling strategies**
> — `onException`, redelivery policies, Dead Letter Channel, circuit breakers,
> compensation patterns. - **Data transformation** — TypeConverters,
> DataFormats, marshalling/unmarshalling, content enrichment. - **Modern
> tooling** — Camel JBang/CLI commands, hot-reload workflow, `camel trace`,
> TUI, `camel export`. - **Runtime differences** — Spring Boot starters vs.
> Quarkus extensions (native mode, dev services, etc.). - **Testing patterns**
> — `CamelTestSupport`, mock endpoints, `adviceWith`, integration testing. -
> **Observability & production concerns** — OpenTelemetry, Micrometer, health
> checks, circuit breakers, idempotency. - **AI-specific integrations** — MCP
> server usage, A2A, LLM components, and how to expose routes as tools. -
> **Best practices & anti-patterns** — Route granularity, separation of
> concerns (orchestration vs. implementation), when to use beans vs. inline
> logic. **Practical recommendation for models/agents**: - Always prefer
> consulting the official Markdown docs or catalog JSON over pure memory. -
> When generating YAML, reference or simulate validation against the schema. -
> Default to modern practices (YAML + CLI for prototyping, export to production
> runtime). - Ask clarifying questions about runtime, volume, error tolerance,
> etc., before giving detailed advice. The combination of the existing
> `llms.txt` + full Markdown docs + machine-readable catalog already gives
> Camel one of the best "AI-native" documentation setups among integration
> frameworks. The suggestions above would push it even further. Would you like
> me to draft a revised/expanded version of specific sections, or focus on
> examples for a particular area?
> ```
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
