Feature: implementation of classification and decision service contracts

[jimador]

Related: #2049, #2050, #2051, #2052, #2057, https://github.com/embabel/embabel-agent-experimental/issues/42. This splits the contract work out of prototype #2059 and precedes #2061.

This prototype implementation adds classification and decision service contracts for Java and Kotlin consumers. The TypeSafe integration in #2061 will implement these interfaces.

Classification answers which declared category applies. Categories have stable identifiers and descriptions, and callers can map the result to an enum or an application type without asking the provider to construct an object. No match, an inconclusive assessment and a provider failure are separate outcomes. Provider confidence stays optional. A supplied map determines category order; use an ordered map when that order matters.

DecisionService adds proposition assessment and also supports classification. Its model family remains DECISION when it is used as a classifier. A false proposition answer is a successful assessment. The application decides what to do with it.

flowchart LR
    Consumer[Java or Kotlin consumer] --> Mapping[Typed category mapping]
    Mapping --> Request[Provider-neutral request]
    Request --> Service[ClassificationService]
    Decision[DecisionService] -->|classification capability| Service
    Decision --> Assessment[Proposition assessment]
    Service --> Result[Selected / no match / inconclusive / failure]
    Result --> Mapping
    Mapping --> Policy[Application policy]
    Service -.-> Metadata[Pure model metadata snapshot]
    Adapter[TypeSafe adapter in follow-up PR] -.-> Decision

Loading

The new CLASSIFICATION and DECISION model families require consumers with exhaustive ModelType switches to handle those cases.

The contracts live beside embedding services in embabel-agent-ai. There is no new Maven module or provider SDK dependency. The guide covers typed categories, result semantics, metadata snapshots and observations. Services support ordinary dependency injection. Model registry selection, role defaults, BYOK and provider autoconfiguration follow with the adapter.

[igordayen]

@jimador - few comments, thank you.

[igordayen]

although embeddingservice and its impl reside in the same package, I would recommend moving the Observed services into sub-package.
Looping in @azanux to review observability integration

[igordayen]

Would be resolved by doc build?

[igordayen]

@jimador - one more comment, thanks

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud