Luigi De Masi created CAMEL-25669:
-------------------------------------
Summary: camel-semantic-openai: Add an OpenAI Decisions API expert
Key: CAMEL-25669
URL: https://issues.apache.org/jira/browse/CAMEL-25669
Project: Camel
Issue Type: New Feature
Components: camel-jbang, camel-ai
Reporter: Luigi De Masi
Assignee: Luigi De Masi
h2. Purpose
Add an OpenAI Decisions expert for the Semantic language, allowing a named
expert to assess text and images through the same typed evaluation contract
used by other experts. The expert supplies an assessment; the Camel route
chooses the application action.
Provide the expert in a new camel-semantic-openai module that reuses Decisions
API support in camel-openai. Keep camel-openai independent of camel-semantic.
h2. Module boundaries
* Add components/camel-ai/camel-semantic-openai, depending on camel-semantic
and camel-openai. Place the SemanticAdapter implementation and its static
expert contract here.
* Extend camel-openai with a Decisions operation and a reusable execution path
for the component producer and Semantic adapter. Authentication,
endpoint/client configuration, timeouts, transport and client lifecycle remain
in camel-openai.
* Keep Semantic-specific types and mapping out of camel-openai. Neither
camel-semantic nor camel-openai depends on camel-semantic-openai.
* Shared input contracts, capability validation and audit representation belong
in camel-semantic; command handling/output belongs in camel-jbang-core and TUI
presentation in camel-jbang-plugin-tui. Tooling must not depend on OpenAI SDK
classes.
* Reuse the configured client infrastructure without introducing tool execution
or unrelated MCP startup for a Decisions-only invocation.
h2. Expert and result contract
Use explicit named expert beans and the static operation metadata established
by merged PR 27791. Adding the artifact must not select a default expert or
trigger inference during capability inspection.
|| Semantic result || Required behavior ||
| BOOLEAN | Return a Java Boolean and retain the provider probability
separately. The Decisions predicate response is a probability, so the adapter
must explicitly declare and document its Boolean conversion policy. Any
threshold parameter and omission behavior belong to this expert's contract, not
a generic Semantic policy. |
| CHOICE | Return a String identifying one of the declared choices. Preserve
descriptions and provider probabilities. Validate compatibility with the
Semantic String result contract instead of silently converting other provider
value types. |
| SCORE | Return a Number on the declared ordered rubric. Preserve the
provider's fractional score; do not round it, normalize it to 0-1, or replace
it with a label. Retain rubric order, labels/descriptions and per-level
probabilities. |
The Decisions score is the probability-weighted average of zero-based rubric
indices. The rubric is the scoring definition; the returned score remains
numeric. Preserve provider probability/confidence values and their meanings. Do
not synthesize a new common uncertainty formula or confidence value. Missing
provider fields remain absent.
Use the existing Semantic result mechanism: the expression returns the typed
value, CamelSemanticResult contains the detailed latest result, and
CamelSemanticResults contains named results for a batch. Include
probabilities/confidence there, rather than adding a parallel provider-specific
Semantic result property. Preserve the established clearing and failure
behavior.
Support provider batching for independent evaluations over shared input.
Validate all declarations and inputs before inference, correlate all answers to
their questions, validate the full response, and publish no partial successful
Semantic batch if any required answer is refused, missing or invalid. Dependent
evaluations remain separate invocations.
h2. Native inputs and capability validation
* Support the input modalities accepted directly by the Decisions endpoint:
currently text, images and ordered combinations of text and images. Preserve
relevant native image options and provider limits.
* Introduce the smallest provider-independent media input representation and
operation-capability extension needed to express and validate those inputs.
Existing String, Map and List application-state behavior must remain available
to experts that support it.
* Validate the selected expert's accepted shapes and modalities before any
provider request/inference. A structured container must not bypass validation
of explicit media parts. Reject unsupported input with a clear validation
exception; do not stringify binary/media objects or silently drop parts.
* TypeSafe continues to accept text and its supported structured application
state; Wolf Defender accepts text only. Do not imply that installing a
multimodal expert makes every expert multimodal. Their explicit validation
requirements are also covered by CAMEL-25668.
* Audio/voice, video, file inputs or other unsupported modalities must be
rejected when not natively supported by Decisions. Do not add transcription,
OCR, speech-service composition, extraction pipelines, or fallback to another
provider to manufacture support.
h2. Failure behavior
* A provider refusal raises a recognizable dedicated exception. It is not
false, zero, an empty result, a fallback category or ordinary uncertainty.
* Infrastructure/service failures use dedicated recognizable exception types
with the cause preserved, so Camel error handling can distinguish refusal,
invalid input/response and transport/service failures.
* Respect timeouts, interruption, concurrency and lifecycle requirements.
Exceptions and diagnostics must not expose credentials or raw submitted media.
h2. Audit, TUI and Camel JBang
* Integrate through existing Semantic events, audit, monitoring and result
rendering. Preserve provider-owned interpretation and the rubric/choice meaning
captured at evaluation time.
* Cover the TUI expert playground and audit detail screen, Camel JBang
evaluation/audit commands, human-readable output, JSON output and explicit
exports. Typed results and probability distributions retain the same meaning
across these surfaces.
* Use a common media-aware representation so image inputs are identifiable and
unsupported/not-captured/omitted states are clear. Do not dump base64 image
payloads into terminal output, audit lists, summaries or monitoring data.
* Preserve bounded, opt-in input capture and redaction. Captured input remains
untrusted data. Display only available, permitted metadata; do not invent
dimensions, size, descriptions or retained content.
* Image viewing is an explicit implementation design point: decide whether the
first delivery exposes media descriptions only, permits deliberate external
viewing, or offers terminal previews. Metadata-only display has not been
accepted as the final requirement. If viewing is provided, define image
retention/reference access and explain whether the displayed content is the
actual captured input. Do not fetch a historical image URL automatically or
claim reproducibility from mutable external content.
h2. API/SDK verification and implementation design points
The [Decisions guide|https://developers.openai.com/api/docs/guides/decisions]
describes the public-beta endpoint and Java SDK 4.78.0 or newer. Verify the
Camel-managed SDK version and upgrade it as needed, checking existing
camel-openai operations for regressions.
At issue preparation, the guide requires inline base64 image data URLs, while
the [create API
reference|https://developers.openai.com/api/reference/resources/decisions/methods/create]
also lists public HTTP(S) image URLs. Resolve this documentation discrepancy
against the supported API/SDK before advertising URL support. Document the
verified input forms and limits.
Finalize the explicit media-input schema, the adapter's Boolean conversion
policy and rich rubric parameter representation before implementation. These
choices must preserve existing Semantic result types and static expert
contracts. Any necessary common metadata/schema extension must remain
provider-independent.
h2. Acceptance criteria
# The Decisions component operation works with camel-openai alone; its
dependency graph contains no camel-semantic dependency.
# camel-semantic-openai supplies an explicitly configured expert with Boolean,
Choice and Score operations and capability metadata available without inference.
# Text, image and combined-input cases work for verified native Decisions
formats; unsupported modalities fail before inference. TypeSafe/Wolf validation
rejects unsupported media without implicit conversion.
# Boolean remains Boolean, Choice remains String and Score remains Number.
Tests include a fractional score and verify the provider
probabilities/confidence, rubric mapping and exchange properties.
# Refusal, invalid response and infrastructure failure tests demonstrate
recognizable exceptions and no fabricated or partially published successful
results.
# Batched evaluations use shared input correctly, validate every answer and
honor provider limits.
# TUI and JBang input handling, audit details, text/JSON output and export
behavior are implemented and documented consistently, including the chosen
image inspection behavior and input capture limits.
# Provider requests/response mapping are covered by deterministic mock-based
tests. Real API tests are opt-in. Existing OpenAI operations and existing
text/structured Semantic workflows continue to pass relevant regression checks.
# Add reactor/dependency-management entries, expert metadata, component/adapter
documentation, examples and required generated catalog artifacts. Add upgrade
guidance only for changes affecting existing users.
h2. Related work and scope
* CAMEL-25668 separately handles extracting camel-semantic-typesafe-ai and
renaming camel-wolf-defender to camel-semantic-wolf-defender. Do not include
those packaging changes in this issue.
* [PR 27791|https://github.com/apache/camel/pull/27791] is merged and provides
the explicit-expert and audit baseline for this work.
* No agent/tool execution, route-action policy engine, derived cross-provider
uncertainty model or audio preprocessing is included.
_AI-generated by Codex on behalf of luigidemasi (Luigi De Masi)._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
