[jira] [Resolved] (CAMEL-25669) camel-semantic-openai: Add an OpenAI Decisions API expert

["Luigi De Masi (Jira)" <ji...@apache.org>]

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

Luigi De Masi resolved CAMEL-25669.
-----------------------------------
    Resolution: Fixed

Implemented and merged in https://github.com/apache/camel/pull/27850 for Camel 4.24.0. All eight merged commits match the reviewed changes; JDK 17 and JDK 25 builds, documentation, license and dependency checks passed.

AI-generated by OpenAI Codex on behalf of @luigidemasi.

> 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-ai, camel-jbang
>            Reporter: Luigi De Masi
>            Assignee: Luigi De Masi
>            Priority: Major
>             Fix For: 4.24.0
>
>
> 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)