Annotations · 3.0.0

@Confiqure

The confiqure annotation vocabulary. Confiqure itself is a namespace and cannot be applied to anything — use its nested annotations. The confiqure CLI scans your source files for them and pushes the annotated classes; the chat model reads the class source and follows it.

There are three kinds of annotated class: objects (what the end user configures), tool classes (operations the chat can call), and one facts class (what your application already knows about the user).

Objects

A configuration class is an object: something the end user would call "my X". Declare what it is with one of four annotations.

All four take one optional parameter, end: the data-API address of the object (e.g. /listing-repricing). It defaults to the snake_case of the class name when blank. A Setting object's one record is read and edited by the chat; the chat never creates a second one.

@Confiqure.List(end = "/listing-repricing")
public class ListingRepricing {
    @Confiqure.Identity
    private String listingSku;     // identifies the record — a second one with the same SKU is refused
    private Money minPrice;
}

Parts and references

• A part is a class used as a field type inside an object (an address, a schedule). It needs no annotation and has no records of its own.
• A reference is a field whose type is another object class. It is a pointer, never a copy: a reference to a Setting object stores nothing, one to a List record stores its key, and a List<ListObject> stores keys. References are inferred from the field's type — there is no @Confiqure.Ref: an annotated type is a reference, a plain type is a part stored inside.

@Confiqure.Identity

On one field of a List (or User.List) object: the value that identifies a record. Two records of the same owner can never share it — a duplicate save is refused. It is also how the chat binds "the record for this listing". It is usually an id your application owns (a SKU, an order number) that arrives from a tool result the user picked, never a value the chat typed.

Tools

Tools are declared only as tool classes — @Confiqure.Tool on a class, whose Javadoc is the business flow and whose public methods are typed operations. Tool classes are not attached to objects. See Tool Classes.

User facts — @Confiqure.Facts(callback)

Not a configuration, but what your application already knows about an end user (their categories, their counts, their open issues). confiqure GETs your callback — the relative path of an endpoint in your application — for the acting user, binds the JSON into this class, and puts the compact core in front of the model so the chat stops asking for things you already know.

One field name is reserved and read by the engine by name: preferredLanguages — a list of language names in English, most preferred first. It sets the language of the chat's opener and is the list the model checks a message against first when choosing the reply language; the engine appends English when it is missing. Send the user's real preference, not only their UI locale.

@Confiqure.Facts(callback = "/api/confiqure/user-facts")
public class SellerFacts {
    // The product categories this seller actually sells in.
    private List<String> sellingCategories;
    // How many of their listings are currently stranded.
    private Integer strandedCount;
}

• Comment every field. The field comments tell the model what each fact means.
• Read-only and host-owned. The conversation never writes a facts class; it is not an object and holds no records.
• Cached 24 hours, refreshed in the background. A slow or down endpoint never delays a chat — it just serves the last known facts.

The response shape and signing details are in the user-facts contract.

Companion annotations

Optional refinements on objects, their fields and your controllers.

What no longer compiles

The pre-3.0 forms — @Confiqure(end, type, scope, dataScope, tools) on a class and @Confiqure.Tool on a method — do not compile on 3.0. Where each one went:

Installing the Java annotation

It's on Maven Central — no extra repository entry needed.

<dependency>
  <groupId>ai.confiqure</groupId>
  <artifactId>confiqure-annotation-java</artifactId>
  <version>3.1.0</version>
</dependency>

The library ships an annotation processor that injects a backend-managed confiqureKey field (plus getter and setter) into every object class. The Spring Boot guide shows the required maven-compiler-plugin configuration — without it the processor skips injection.

Next: