Core Concepts

Clarifying questions and intent-spec

How question candidates are chosen and exact structured intent schema returned by gate.

Gate response can contain at most three questions. Questions map to highest-risk eligible dimensions.

#Question pipeline

Score request and determine eligible dimensions at tenant threshold.
Compare expected failure regret with asking friction.
Build candidates from scorer output or fixed per-dimension defaults.
Re-score request plus labeled candidate and remove candidates whose dimension

appears covered.

Remove near-duplicate questions above 0.8 fuzzy similarity.
Suppress questions for HOLDOUT experiment arm.

One exact request string gets at most one clarification round per session. clarification_response answers latest unanswered round.

#Intent-spec schema

json

{
  "goal": "Refund order ABC123 to original card",
  "output_format": "unspecified",
  "scope": "specific object named in request",
  "constraints": "provided in request",
  "missing_fields": []
}

Field	Type	Meaning
`goal`	string	Requested outcome.
`output_format`	string	Required response or artifact format.
`scope`	string	Exact item, record, or boundary.
`constraints`	string	Deadlines, limits, policies, or exclusions.
`missing_fields`	string[]	Ambiguous dimensions needing clarification.

#Continue after answer

Send original request, same session ID, and response:

python

clarified = intentlayer.gate(
    "improve the report",
    "session-42",
    clarification_response="Weekly revenue as CSV",
)

Backend appends clarification response to scoring input after redaction and marks latest clarification as answered.

Source truthbackend/app/policy.pybackend/app/schemas.pybackend/app/questions.py