Prototype: read decision specs from annotated records

[jimador]

Prototype. This PR adds an opt-in module, embabel-agent-decision-annotations, that reads a decision spec from an annotated record or class and projects a response back into it. It's here for evaluation. The module sets maven.deploy.skip; keeping it off Maven Central still needs confirming (condition 1).

Declaring a spec

A record with question annotations declares the same spec as the builder:

enum Department {
    @Described("Payments, invoicing, refunds")
    BILLING,
    @Described("Bugs, outages, integrations")
    TECHNICAL,
}

enum Severity {
    LOW,
    @Described("Work is blocked for one customer")
    HIGH,
    @Described("Work is blocked for many customers")
    CRITICAL,
}

record Triage(
    @PropositionQuestion(asking = "Does this ticket convey urgency?") boolean urgent,
    @ChoiceQuestion(asking = "Which team should handle this?") Department department,
    @RatingQuestion(asking = "How severe is the impact?") Severity severity) {
}

AnnotatedDecision<Triage> triage = AnnotatedDecisions.defaults().of(Triage.class);
DecisionSpec spec = triage.spec();   // equal to the builder's spec

DecisionResponse response = service.ask(ticket, spec);
Triage value = triage.project(response).getValue();

Enum constants become options or levels, and @Described sets their descriptions. Question names come from Jackson, so @JsonProperty and the mapper's naming strategy apply. AnnotatedDecisions.using(mapper) reads with an application's own mapper.

Projection checks the response against the type's spec with requireMatches, then refuses an answer that is inconclusive, failed, no-match, or a rating with no selected level, as DecisionProjection does. project(response) refuses a type with properties that aren't questions. project(response, otherProperties) fills those, such as an id, and returns T.

Classification

An enum annotated with @Classification reads as a CategoryMapping:

@Classification(asking = "Which team should handle this ticket?")
enum Department {
    @Described("Payments, invoicing, refunds")
    BILLING,
    @Described("Bugs, outages, integrations")
    TECHNICAL,
}

CategoryMapping<Department> departments = AnnotatedDecisions.classification(Department.class);
ClassificationResult result = service.classify(ticket, departments.spec());
MappedClassificationResult<Department> mapped = departments.map(result);

Category ids are the constant names. A constant without @Described is an error, as it is for a choice option. A decision type whose only question is a choice reads as a ClassificationSpec, even with other properties such as an id, so its spec also goes to classify.

Errors

The parser reports every problem on a type in one AnnotatedDecisionException, each with its member, or the type when the problem is the whole type, and the fix. For example, a Kotlin @field: annotation on a data class:

FieldSiteTriage.urgent: carries @PropositionQuestion but Jackson leaves this field out of the property "urgent". Move the annotation to creator parameter urgent or getter getUrgent(). In Kotlin, write the annotation with @get: or with no use-site target.

The reference page has a table of the parser's messages and their fixes.

Kotlin

The Kotlin tests read through using(mapper) with jackson-module-kotlin 3.1 on Kotlin 2.2. No test covers defaults() with a Kotlin class.

Placement	Reads
No use-site target	Yes
@param:	Yes
@get:	Yes
@param: and @field: together (the placement a later Kotlin default site produces)	Yes
@field: alone	No. Rejected with the members to use instead
@property:	Does not compile

Recommendation

Keep it as an opt-in prototype, unpublished until this recommendation is accepted. It produces specs equal to the builder's, projects into the declaring type after checking the response against its spec, and names the member and fix for every problem. Drop it if no consumer application adopts it by the release that promotes the decision types.

Conditions for accepting it:

1. Exclude the module from Maven Central publication and confirm that in a release dry run. The module sets maven.deploy.skip, but the Central plugin lives in the build parent.
2. Review the Jackson introspection calls against the Jackson version the release uses.
3. Add a public factory to DecisionProjection so project(response, otherProperties) can return DecisionProjection<T> instead of T.
4. Name an owner and a consumer application, as the decision types require for promotion.

Values in otherProperties are coerced leniently by Jackson: "3" and 3.0 fill an int, and "true" fills a boolean. No test pins this. A stricter rule would need its own decision.

The parser's cache doesn't hold classes alive. Jackson's own caches in the defaults() mapper can still hold a projected type, so an application that reloads classes should pass its own mapper with using(mapper).

Size and removal

	Lines
Main code, ten Java files	2,015 (1,003 non-blank, outside comments)
DecisionTypeParser	1,239
Tests	2,951

No other module refers to it. Removal is the module directory, its <module> line, the reference page and its include:: line.

Stacked on #2076.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud