[
https://issues.apache.org/jira/browse/CAMEL-25669?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Work on CAMEL-25669 started by Luigi De Masi.
---------------------------------------------
> 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
>
> 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)
