davsclaus opened a new pull request, #26477: URL: https://github.com/apache/camel/pull/26477
Fixes [CAMEL-24708](https://issues.apache.org/jira/browse/CAMEL-24708). An AI assistant, in particular a small local model, writing a Java or Groovy bean for a route gets the Camel API wrong more often than the DSL (`oldExchange` is null on the first aggregation call, `${body.type}` on a `Map` body, a bean name used as a Groovy variable, `exchange.setHeader(...)`). This adds a compact API reference it can look up before writing the code, following the design in the JIRA comment. ### What - **camel-api**: `@Metadata(label = "api", description = ..., examples = ...)` on the methods that matter of `Exchange`, `Message`, `CamelContext`, `Registry` (+`BeanRepository`), `ProducerTemplate`, `TypeConverter`, `Processor`, `AggregationStrategy`, `Predicate`, `Expression`, and a class-level annotation per class carrying the common mistakes (the first-call rule of `AggregationStrategy`, the Camel 4 changes on `Exchange`: no `getOut()`, `getIn()` is `getMessage()`, no `exchange.setHeader`). - **camel-package-maven-plugin**: new `GenerateApiReferenceMojo` (in the `generate` goal, next to `GeneratePojoBeanMojo`). A class with a class-level `@Metadata(label="api")` is a card; the mojo reads the annotated methods of the class and its super types from the compiled class and lists the signatures of every non-deprecated overload, so a renamed or removed method takes its entry with it. Output: `core/camel-api/src/generated/resources/META-INF/services/org/apache/camel/api/<Class>.json` + `api.properties`. - **camel-tooling-model**: `ApiReferenceModel` (+ `ApiMethodOptionModel` with `signatures` and `examples`), `Kind.api`, `JsonMapper` round trip. - **camel-catalog**: `PrepareCatalogMojo.executeApis()` copies the cards to `org/apache/camel/catalog/apis/` + `apis.properties`; `CamelCatalog.findApiReferenceNames()` / `apiReferenceModel(name)` (also via `findNames(Kind.api)` / `model(Kind.api, name)`), `RuntimeProvider` and `JSonSchemaResolver` gained `default` methods so external providers keep compiling. - **camel-jbang** (`camel_catalog_doc`, shared by `camel mcp` and `camel tui --mcp`): `kind=api` (auto-detected for a class name such as `Exchange` or `org.apache.camel.Message`) returns the card: description, the methods with the important ones first, signatures, one-line description, examples, and for an interface the built-in catalog implementations (`AggregationStrategy` lists the strategies). A script language name (`groovy`, `js`, `python`, `python3`, `quickjs`, `java`/`joor`, `template` for velocity/freemarker/mustache/...) returns the variables that script binds and how to reach a registry bean, hand-written per language since each binds its own set; the language doc of those languages carries the same `scriptVariables`. An older catalog (`camelVersion=...`) without the reference answers from the CLI's own catalog. A miss with `kind=api` lists the cards that exist. - **docs**: `camel-jbang-mcp.adoc` tool table. ### Catalog layout note The comment on the JIRA says `org/apache/camel/catalog/api/`; I used the plural `apis/` + `apis.properties` to match `beans/`, `components/`, `dataformats/` etc. ### Size 10 cards, 28 KB of JSON in total; a single card is ~700–1100 tokens (AggregationStrategy with its 12 implementations: ~700). The `camel_catalog_doc` `kind` description now names the classes and script languages the reference covers, which pushed the TUI full-prefix guard (`AiPanelPromptBudgetTest`) from ~8470 to ~8540 tokens, so its budget is raised 8500 → 8700 with the reason in the test, as with the earlier bumps; the core prefix stays within its budget. ### Tests - `GenerateApiReferenceMojoTest`: signatures read like source (generics, bounds, varargs, throws, simple type names). - `JsonMapperTest`: `ApiReferenceModel` round trip. - `CamelCatalogTest`: names, `Exchange` card (Camel 4 note, overloads from the compiled class, no deprecated `getOut`), `AggregationStrategy` first-call rule, `Registry` inherits `lookupByName`. - `CatalogDocsTest`: `kind=api` and auto-detection, important-first order, implementations, qualified and lower-case names, misses; the script cards and their aliases; the language doc carries `scriptVariables`; a drift test of the groovy and template cards against `ExchangeHelper.populateVariableMap`. - Ran: camel-catalog (1047 tests), camel-jbang-core `commands.ai` (140), camel-jbang-mcp (425), the TUI prompt budget test, and the whole `core` reactor with `-Dquickly` (no extra regenerated files). ### Follow-ups (as listed in the JIRA) The CAMEL-24698 hints in `JavaChecks` (`exchange.setHeader`), camel-groovy (bean name as variable: its current hint also lists a `message` variable groovy does not bind) and the POJO aggregation strategy message can point to `camel_catalog_doc kind=api` instead of restating the API. _Claude Code on behalf of davsclaus_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
