From 188429fa07e17f78e5cc9f065f123e1b4c88e171 Mon Sep 17 00:00:00 2001 From: Chuck Meyer Date: Wed, 26 Aug 2026 21:12:35 -0400 Subject: [PATCH] docs: correct the searchControls constraint and exposed claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two contradictions introduced by #21, both found in review. The prose claimed constraint appears only on the numeric parameters while the table listed it for attributesToRetrieve and responseFields as well. That conflated "the key exists" with "it carries a {min, max} shape". Re-derived from 21 indices across the 12 live agents: four parameters carry a constraint key — hitsPerPage, page, attributesToRetrieve, responseFields — and only hitsPerPage was ever observed with one populated. merge was null in every record, so neither its purpose nor the constraint shape on those two parameters is known. `exposed: true` was described as varying the value "within its constraint", but distinct and facets have no constraint key at all. Reworded so the constraint is only mentioned where one is present. The unconfirmed list now covers merge and any constraint beyond hitsPerPage, rather than implying the rest is settled. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 42da4be..8a13c24 100644 --- a/README.md +++ b/README.md @@ -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.