Package ai.confiqure

Annotation Type Confiqure

@Target(TYPE)
@Retention(RUNTIME)
public @interface Confiqure

Marks a class as a confiqure.ai configuration target. The confiqure CLI scans source files for this annotation and uploads them; the confiqure backend AI parses the annotated class and generates the chat playbook.

 @Confiqure(
     end       = "/notifications",
     type      = Confiqure.Type.SINGLE,
     scope     = Confiqure.Scope.LIMITED,
     dataScope = Confiqure.DataScope.ORG,
     tools     = {"SEND_TEST_NOTIFICATION"}
 )
 public class Notifications { ... }
 

Tools come in two kinds, both declared once as a Confiqure.Tool-annotated method and referenced by name in tools():

• Server-side (serverSide=true, the default) — a real controller method confiqure invokes over HTTP. Returns data or performs a backend action; no UI.
• Frontend (serverSide=false) — a contract-stub method (body never runs on the backend) whose handler runs in the host's browser via the embed SDK. Use for anything needing a UI (OAuth, a picker, rendering a view). The method signature still carries the I/O contract: its @RequestBody DTO is the input, its return type the output. Example:

         @Confiqure.Tool(name = "show_report", serverSide = false)
         public String showReport(@RequestBody StockFilterData filter) { return null; }
         

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static @interface	Confiqure.Consent	Verbatim, auditable consent capture on a Boolean field.
static enum	Confiqure.DataScope	Ownership of a saved configuration: shared across an organization, or private to each end user.
static @interface	Confiqure.DefaultCallbackHook	Marks a controller method as the workspace's default callback hook.
static @interface	Confiqure.Gate	Declarative flow gate on a single field: the confiqure conversation may only WRITE this field when the Confiqure.Gate.requires() predicate is true over the root instance's current values.
static @interface	Confiqure.Protect	Opts a type = MULTI configuration class OUT of chat deletion.
static enum	Confiqure.Scope
static @interface	Confiqure.Secret	Classifies a String field as a secret (password, API token, TOTP seed, …).
static enum	Confiqure.SecretKind	The kinds of secret a Confiqure.Secret field can hold.
static @interface	Confiqure.SectionGate	Declarative flow gate on a whole nested section: ANY write at or under this field's path is only permitted while the Confiqure.SectionGate.requires() predicate is true over the root instance's current values.
static @interface	Confiqure.SystemOnly	Marks a field as engine- or tool-populated ONLY: every conversation-proposed write to it (or to any field beneath it) is rejected.
static @interface	Confiqure.Tool	Marks a method as a tool the chat agent can invoke during a session.
static @interface	Confiqure.ToolGate	Declarative flow gate on a host tool, declared on the endpoint (root) class: the named tool is only dispatchable while the Confiqure.ToolGate.requires() predicate is true over the bound instance's current values.
static @interface	Confiqure.ToolGates	Container for repeated Confiqure.ToolGate declarations on one endpoint class.
static enum	Confiqure.Type

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	callback	ONLY meaningful with type = Confiqure.Type.FACTS: the relative path of the GET endpoint in YOUR application that returns the current facts for one end user.
Confiqure.DataScope	dataScope	Who a saved configuration belongs to.
String	end	Chat endpoint segment.
Confiqure.Scope	scope	Chat context scope: LIMITED (this endpoint only) or UNLIMITED (can navigate all endpoints).
String[]	tools	Names of @Confiqure.Tool methods this endpoint can invoke during chat.
Confiqure.Type	type	What this class is: SINGLE (one configuration record per user), MULTI (a table of records), or Confiqure.Type.FACTS — not a configuration at all, but the read-only user-facts contract your application serves back to confiqure (see callback()).

Element Details

end

String end

Chat endpoint segment. Defaults to snake_case of the class name when blank.

Default:

""

type

Confiqure.Type type

What this class is: SINGLE (one configuration record per user), MULTI (a table of records), or Confiqure.Type.FACTS — not a configuration at all, but the read-only user-facts contract your application serves back to confiqure (see callback()).

Default:

SINGLE

callback

String callback

ONLY meaningful with type = Confiqure.Type.FACTS: the relative path of the GET endpoint in YOUR application that returns the current facts for one end user. confiqure calls hostBaseUrl + callback with the user's handle and binds the JSON response into this class.

 @Confiqure(type = Confiqure.Type.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 comment is what tells the model what the fact MEANS. Ignored on SINGLE/MULTI classes (lifecycle callbacks stay workspace-level via Confiqure.DefaultCallbackHook).

Default:

""

scope

Confiqure.Scope scope

Chat context scope: LIMITED (this endpoint only) or UNLIMITED (can navigate all endpoints).

Default:

LIMITED

tools

String[] tools

Names of @Confiqure.Tool methods this endpoint can invoke during chat.

Default:

{}

dataScope

Confiqure.DataScope dataScope

Who a saved configuration belongs to. ORG (default) — the record is shared across everyone in the end user's organization: when the host mints an embed token carrying an organizationId, all members of that org see and edit ONE shared instance (suppliers, business model, repricer settings — anything org-wide). USER opts a genuinely personal endpoint out, so each end user gets their own private record even within an org (personal credentials, individual preferences).

Org sharing activates only when the host's token mint sends organizationId; an org-less host, or a token without one, behaves exactly as a per-user endpoint. Declared, never inferred — like type()/scope(), this is read straight from the annotation.

Default:

ORG