Feature: typed decision specs, results and Jackson bindings

[jimador]

This PR adds typed decision specs. A spec holds one or more named questions, and a DecisionRequest pairs it with the input they are asked about. A spec is built in Java or Kotlin, validated when it is built, written and read with Jackson, and its responses are read back as typed results.

The PR covers the spec, the request and the results. #2080 runs a spec against a decision service, and #2076 selects and registers services.

Building a spec

Java uses nested customizers. Each callback gets a builder for its question kind, so only a choice takes options and only a rating takes levels.

var triage = DecisionSpec.builder()
    .proposition("is_urgent", question -> question
        .asking("Does this convey urgency?"))
    .choice("department", question -> question
        .asking("Which team should handle this?")
        .option("billing", "Payments, invoicing, refunds")
        .option("technical", "Bugs, outages, integrations")
        .option("sales", "Pricing, upgrades, new accounts"))
    .rating("frustration", question -> question
        .asking("How frustrated is the customer?")
        .level("Calm")
        .level("Frustrated")
        .level("Very angry"))
    .build();

Named questions are reusable handles for typed results:

var urgent = Questions.named("is_urgent")
    .proposition("Does this convey urgency?")
    .build();

var department = Questions.named("department")
    .choice("Which team should handle this?")
    .option("billing", "Payments, invoicing, refunds")
    .option("technical", "Bugs, outages, integrations")
    .option("sales", "Pricing, upgrades, new accounts")
    .build();

var frustration = Questions.named("frustration")
    .rating("How frustrated is the customer?")
    .level("Calm")
    .level("Frustrated")
    .level("Very angry")
    .build();

var triage = DecisionSpec.of(urgent, department, frustration);
var request = DecisionRequest.of(ticketText, triage);

Kotlin gets a receiver DSL over the same builders. It builds a spec equal to the Java one.

val triage = decisionSpec {
    proposition("is_urgent") {
        asking("Does this convey urgency?")
    }
    choice("department") {
        asking("Which team should handle this?")
        option("billing", "Payments, invoicing, refunds")
        option("technical", "Bugs, outages, integrations")
        option("sales", "Pricing, upgrades, new accounts")
    }
    rating("frustration") {
        asking("How frustrated is the customer?")
        level("Calm")
        level("Frustrated")
        level("Very angry")
    }
}

A spec is an immutable value, so it can be built once and shared:

@Configuration(proxyBeanMethods = false)
class SupportDecisionConfiguration {

    @Bean
    DecisionSpec supportTriageSpec() {
        return DecisionSpec.builder()
            .proposition("is_urgent", question -> question
                .asking("Does this convey urgency?"))
            .choice("department", question -> question
                .asking("Which team should handle this?")
                .option("billing", "Payments, invoicing, refunds")
                .option("technical", "Bugs, outages, integrations"))
            .build();
    }
}

Reading a response

Typed lookup returns the result type for the question's kind. It checks the answer's name, kind, and options or levels against the question, so a changed choice or rating question, or an edited response, is caught. Answers carry no instructions, so a reworded question is not detected:

PropositionResult urgency = response.answer(urgent);
ClassificationResult team = response.answer(department);
RatingResult anger = response.answer(frustration);

A reader that only has a name uses the sealed answer types:

String route = switch (response.answer("department")) {
    case DecisionAnswer.Choice choice
        when choice.getOutcome() instanceof ClassificationResult.Selected selected -> selected.getCategoryId();
    case DecisionAnswer.Choice choice -> "triage-queue";
    case DecisionAnswer.Proposition proposition -> "not a choice";
    case DecisionAnswer.Rating rating -> "not a choice";
};

Jackson

JsonMapper mapper = JsonMapper.builder().build();

String specJson = mapper.writeValueAsString(triage);
DecisionSpec specRead = mapper.readValue(specJson, DecisionSpec.class);

String responseJson = mapper.writeValueAsString(response);
DecisionResponse responseRead = mapper.readValue(responseJson, DecisionResponse.class);
ClassificationResult team = responseRead.answer(department);

Any Jackson 3 mapper reads and writes the decision types through annotations on the types, with no module to register. The result types, ClassificationResult, PropositionResult, RatingResult, FailureReason and ModelProvenance, carry the same annotations, so they write the same JSON on their own as inside a response. Spec JSON carries the instructions. Response JSON lists the answers as an array in spec order, so a store that reorders object keys can't break it. Each answer carries its name, kind, option or level ids and descriptions, and outcome, and leaves out the input and the instructions. Trimmed to one answer:

{
  "answers": [
    {
      "name": "department",
      "kind": "choice",
      "options": [{ "id": "billing", "description": "Payments, invoicing, refunds" }, ...],
      "outcome": { "status": "selected", "categoryId": "billing", "provenance": { "modelName": "jev-latest", "provider": "typesafe" } }
    }
  ]
}

A request-level failure from DecisionResponse.failed(spec, reason) adds "requestFailure" and gives every answer a failure outcome with that reason.

An unknown member fails the read on every mapper, including one with FAIL_ON_UNKNOWN_PROPERTIES turned off, as Spring Boot's is. Reading a spec or question runs the same validation as the builders, so unknown kinds, repeated question names and invalid scales fail. A response is checked answer by answer when it is read. response.requireMatches(spec) checks it against a spec: answers that are missing, extra, reordered, of the wrong kind, or with changed options or levels fail with a message naming each one. Specs and questions compare by value, so a response written on one node reads the same on another. The golden files under src/test/resources/decision/golden pin the spec, request, response, failed response and capabilities JSON.

Application types

A Spring Converter handles each outcome itself:

static class SupportRouteConverter implements Converter<DecisionResponse, SupportRoute> {

    private final PropositionQuestionSpec urgent;
    private final ChoiceQuestionSpec department;

    SupportRouteConverter(PropositionQuestionSpec urgent, ChoiceQuestionSpec department) {
        this.urgent = urgent;
        this.department = department;
    }

    @Override
    public SupportRoute convert(DecisionResponse response) {
        boolean isUrgent = switch (response.answer(urgent)) {
            case PropositionResult.Answered answered -> answered.getAnswer();
            case PropositionResult.Inconclusive inconclusive -> true;
            case PropositionResult.Failure failure -> true;
        };
        String team = switch (response.answer(department)) {
            case ClassificationResult.Selected selected -> selected.getCategoryId();
            case ClassificationResult.NoMatch noMatch -> "general";
            case ClassificationResult.Inconclusive inconclusive -> "triage-queue";
            case ClassificationResult.Failure failure -> "triage-queue";
        };
        return new SupportRoute(isUrgent, team);
    }
}

DecisionProjection maps answered values onto a record or a generic type. It refuses any answer that is inconclusive, failed, no-match, or a rating with no selected level, and a record component with no answer. The exception lists the refused questions in getQuestions().

record SupportRoute(boolean is_urgent, String department) {}

var projection = DecisionProjection.of(response, SupportRoute.class);
SupportRoute route = projection.getValue();

Classification is a decision

A classification is a decision with one choice question. ClassificationSpec in com.embabel.common.ai.classification extends DecisionSpec and holds exactly one ChoiceQuestionSpec. The builder takes asking and category, and names the question classification. ClassificationSpec.of(question) wraps a choice question you already have and keeps its name. getQuestion() returns it, and selected(...) and validate(result) check a selection against the spec's categories.

ClassificationSpec departments = ClassificationSpec.builder()
    .asking("Which team should handle this?")
    .category("billing", "Payments, invoicing, refunds")
    .category("technical", "Bugs, outages, integrations")
    .build();

Kotlin has classificationSpec { }:

val departments = classificationSpec {
    asking("Which team should handle this?")
    category("billing", "Payments, invoicing, refunds")
    category("technical", "Bugs, outages, integrations")
}

ClassificationService.classify(input, spec) is a default method that calls classify(ClassificationRequest.of(input, spec)):

record TicketRouter(ClassificationService classifier, ClassificationSpec departments) {
    String route(String ticketText) {
        ClassificationResult team = classifier.classify(ticketText, departments);
        return switch (team) {
            case ClassificationResult.Selected selected -> selected.getCategoryId();
            case ClassificationResult.NoMatch noMatch -> "triage";
            case ClassificationResult.Inconclusive inconclusive -> "triage";
            case ClassificationResult.Failure failure -> "retry-later";
        };
    }
}

A decision service answers it too, since a classification spec is a decision spec and a ClassificationRequest is a DecisionRequest. response.answer(spec.getQuestion()) returns the ClassificationResult.

• ClassificationRequest extends DecisionRequest and is built with ClassificationRequest.of(input, spec). The public constructor is gone. This changes the request shape Feature: implementation of classification and decision service contracts #2062 introduced.
• CategoryMapping takes (instructions, values), and fromEnum(type, instructions, describe) takes the instructions too. spec() returns the ClassificationSpec built from them.
• Providers pass the instructions through. Jev puts them in its Choice in place of a fixed sentence, and the prompted classifier adds a Question: line before the categories.
• A classification spec or request writes the same JSON as the equivalent decision spec or request. That JSON reads back as either type when it holds one choice question. Reading any other shape as a ClassificationSpec fails.
• DecisionSpec and DecisionRequest are now open with internal constructors, so only the classification types extend them. equals and hashCode are final, so a classification spec equals a DecisionSpec holding the same question.

Types

classDiagram
    class Question~R~ {
        <<sealed>>
        name
        instructions
    }
    Question <|.. PropositionQuestionSpec : PropositionResult
    Question <|.. ChoiceQuestionSpec : ClassificationResult
    Question <|.. RatingQuestionSpec : RatingResult
    DecisionSpec o-- Question
    DecisionRequest --> DecisionSpec
    DecisionSpec <|-- ClassificationSpec
    DecisionRequest <|-- ClassificationRequest
    DecisionResponse o-- DecisionAnswer
    DecisionAnswer <|.. Proposition
    DecisionAnswer <|.. Choice
    DecisionAnswer <|.. Rating

Loading

• RatingResult holds the evidence a provider reports: a selected level, a distribution over the levels, and a score with its statistic named. Each part is present only when the provider reports it.
• DecisionCapabilities describes what a service supports: the question kinds it answers, and the most questions and input characters it accepts, each null when unknown.
• DecisionResponse.builder(spec) has one typed answer(...) overload per question kind. Passing the wrong outcome type is a compile error.
• Existing source changes are limited to opening DecisionSpec and DecisionRequest, the classification types, ClassificationService, the observed classification and decision services (which observe classify(input, spec) too), and the Jev and prompted classifiers. reference.adoc gains one include for the new page, and the classification page covers ClassificationSpec. The pom adds two test-scoped dependencies: the Kotlin compiler for the compile checks and Spring Boot's Jackson support for the mapper test.

The API is experimental. The reference page covers construction, identity, the wire format, reading JSON and projection.

Stacked on #2074, which sits on #2061 and #2062.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud