You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@camel.apache.org by "Claus Ibsen (Jira)" <ji...@apache.org> on 2026/07/02 16:30:00 UTC

[jira] [Resolved] (CAMEL-23882) camel - improve llms.txt for better AI assistance

     [ https://issues.apache.org/jira/browse/CAMEL-23882?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Claus Ibsen resolved CAMEL-23882.
---------------------------------
    Resolution: Fixed

> 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)