Classify Intent
POST /api/divinity/intent/classify
Classify a free-text query into top-K agent + handler routes.
Returns 429 when another classify call is already in-flight for the same session — the frontend treats this as “leave the prior prediction in place” so rapid keystroke triggers don’t queue overlapping inference.
Returns 503 when the intent classifier service has not been
constructed (typically: the bundled prototypes file is missing
because scripts/train_intent_classifier.py has not been run
yet).
Request Body required
Section titled “Request Body required ”Request body for POST /api/divinity/intent/classify.
The optional context slot is reserved for M11.1’s
context-aware re-ranker. M11 ignores it; defining the field now
keeps the wire shape forward-compatible so M11.1 lands without a
schema migration.
Responses
Section titled “ Responses ”Successful Response
Response body for POST /api/divinity/intent/classify.
object
One classifier prediction returned to a caller.
confidence is the calibrated, normalized score in [0, 1].
raw_cosine is the underlying cosine similarity preserved for
debugging and to let the UI render alternative-confidence bars
based on the unbounded raw value when desired. handler_id is
null for no-route intents — see :class:IntentDefinition.
Three-knob disambiguation echo per M11 plan §1.4a.
There are three threshold-like values interacting: the UI gate
(user_threshold), the handler/strictness floor
(handler_min_confidence), and the per-intent model calibration
that produced the raw and normalized scores. Surfacing all three in
every response lets callers (and future bug reports) see why a
prediction was kept, dropped, or suppressed without reverse-
engineering from summary strings.
object
Validation Error