Skip to content

docs: correct the searchControls constraint and exposed claims #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chuckmeyer merged 1 commit into from
Aug 27, 2026
Merged

docs: correct the searchControls constraint and exposed claims #22

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,25 +213,30 @@ and the instructions file in a single pass — missing vars are reported togethe
one block is applied to **every** index (primary + replicas); the service itself stores
them per index, so a native config from `snapshot` can differ index by index.

Set `exposed: true` to let the LLM vary the value within its constraint; `exposed: false`
to fix it.
`exposed: true` lets the LLM choose the value at query time; `exposed: false` fixes it at
`default`. Where a `constraint` is present and set, it bounds what the LLM may choose.

The parameters do **not** share one shape — `constraint` appears only on the numeric
ones, `merge` only on the list-valued ones:
The parameters do **not** share one shape:

| Parameter | Sub-fields | What it does |
|---|---|---|
| `hitsPerPage` | `exposed`, `default`, `constraint: {min, max}` | Limit result count. Set `constraint.max` to cap it. |
| `page` | `exposed`, `default`, `constraint: {min, max}` | Limit pagination depth. |
| `hitsPerPage` | `exposed`, `default`, `constraint` | Limit result count. Set `constraint.max` to cap it. |
| `page` | `exposed`, `default`, `constraint` | Limit pagination depth. |
| `attributesToRetrieve` | `exposed`, `default: []`, `constraint`, `merge` | Restrict which attributes each hit returns — useful for trimming the LLM payload. |
| `responseFields` | `exposed`, `default: []`, `constraint`, `merge` | Restrict which top-level response fields are returned. |
| `distinct` | `exposed`, `default` (boolean) | De-duplicate results. No `constraint`. |
| `facets` | `exposed`, `default: []` | Control which facet attributes the response returns. No `constraint`. |
| `query` | — | Present in the API's representation but not observed carrying a value. |
| `custom` | — | Present in the API's representation but not observed carrying a value. |
| `distinct` | `exposed`, `default` (boolean) | De-duplicate results. No `constraint`, no `merge`. |
| `facets` | `exposed`, `default: []` | Control which facet attributes the response returns. No `constraint`, no `merge`. |
| `query` | — | Present in the API's representation, not observed carrying a value. |
| `custom` | — | Present in the API's representation, not observed carrying a value. |

Four parameters carry a `constraint` key, but only `hitsPerPage` was ever observed with
one populated, as `{min, max}`. `attributesToRetrieve` and `responseFields` additionally
carry `merge`, which was `null` in every record inspected — so its purpose and shape are
unknown, and `constraint` on those two may not take the `{min, max}` form.

This table was derived by inspecting live agents rather than from a published schema, so
treat `query`, `custom` and the semantics of `merge` as unconfirmed. The service returns
treat `query`, `custom`, `merge`, and any `constraint` beyond `hitsPerPage` as
unconfirmed. The service returns
all eight keys with `null` for anything unset, and it expands the ones you do send with
its own defaults — which is why `--dry-run` compares only the keys your config actually
specifies.
Expand Down
Loading