Claus Ibsen created CAMEL-23882:
-----------------------------------
Summary: 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
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)
