--- id: IOP-PFM-MTD-001 title: Record List Query Generation product_area: platform module: metadata revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f ai_task: queries.generate_query provider: anthropic model: claude-sonnet-5-5 reasoning_effort: medium called_by: [SCR-PFM-MTD-014] realises: [CAP-PFM-MTD-010] smoke_suite: services-platform:modules/queries/tests/live/generate-query/smoke.js evaluation_suite: services-platform:modules/queries/tests/live/generate-query/evaluate.js evidence: - 'react-console:components/record-explorer/use-recipe-explorer.ts' - 'react-console:lib/record-explorer/ask.ts' - 'react-console:lib/record-explorer/generated-filters.ts' - 'react-console:lib/api/generate-query.ts' - 'services-platform:modules/queries/services/generate/generation-runner.ts:GENERATE_QUERY_OPERATION_KEY' - 'services-platform:modules/queries/services/generate/run-generation.ts:runGeneration' - 'services-platform:modules/queries/services/generate/generate-query-context.ts' - 'services-platform:modules/queries/services/generate/generate-query-tools.ts' - 'services-platform:modules/queries/services/generate/validate-generated-query.ts' - 'services-platform:modules/llm/catalog/llm-operations.ts' - 'services-platform:modules/queries/tests/live/generate-query/smoke.js' - 'services-platform:modules/queries/tests/live/generate-query/evaluate.js' controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-006, TC-AI-007, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Record List Query Generation ## 1. Purpose Staff describe which custom records they want to find, and Ask turns their words into filters the list can display. This contract documents the inference consumed by the metadata screen; Queries owns generation and the LLM foundation owns provider execution. ## 2. Application and Model Responsibilities The application resolves the caller's current grants, builds the permitted dictionary, supplies default columns, validates and compiles candidate queries, and decides whether a result can become list filters. The model proposes a query, asks for clarification or reports an unsupported request. A model answer cannot choose a workflow stage or save a business record; the application stores a generation outcome and applies only representable filters. ## 3. Inputs and Context The request contains a dataset and trimmed description of at most two thousand characters. Refinement may include the previous generation and the current query. The context includes permitted datasets, fields, relationships, configuration choices and the workspace date. Test-run tools return bounded summaries under the caller's grants, rather than unrestricted record contents. ## 4. Output Contract A successful generation contains a validated query, application-derived metadata and warnings, plus model assumptions and an optional explanation. Other completed outcomes request clarification with possible interpretations or explain unsupported work. Explorer maps representable criteria and sorting into its own controls; a valid query that the list cannot represent produces a notice rather than partially applying its conditions. ## 5. Model and Provider The pinned operation declaration selects Anthropic, Claude Sonnet 5.5 and medium effort. The LLM foundation resolves the published routing configuration and records the actual model, prompt version, usage and cost. This consumed contract does not give the metadata services a provider connection. ## 6. Prompt Contract The versioned prompt defines the query language, dictionary conventions, permitted tool use and final-answer shapes. A cacheable dictionary prefix precedes request-specific context. Refinements instruct the model to preserve parts the person did not ask to change. Prompt text is maintained by Queries and passed through the foundation's operation declaration. ## 7. Validation, Failure and Fallback Every submitted query is checked against the schema, grants and compiler after application defaults are filled. Invalid drafts share a two-repair budget; exhausted repairs fail rather than weakening criteria. Settlement changes a working generation once, so a late worker cannot overwrite reconciliation. Provider, allowance and configuration failures become stable codes and user-facing messages. Generation requires the explicit live flag; otherwise Ask uses its local parser. The console polls from a one-and-a-half-second interval up to five seconds and stops waiting after ninety seconds. ## 8. Smoke Tests The existing shared smoke suite uses contacts as its fixture. It checks executable output, metered invocation and attempt records, positive cost and release of reservations; these checks establish the consumed pipeline, but do not prove custom-object-specific filter quality. ### IOS-PFM-MTD-001-01 — Generate a Simple Filter Input: inactive contacts. Expected: a successful query the execute route accepts. A failure is an invalid query, unsuccessful generation or missing metering; semantic accuracy is assessed by evaluation. ### IOS-PFM-MTD-001-02 — Preserve Registered Default Columns Input: all our contacts. Expected: a runnable query using application defaults when the request names no columns. A failed generation or unrunnable result fails the smoke check; the evaluation suite examines whether the selected columns are correct. ### IOS-PFM-MTD-001-03 — Generate a Permitted Relationship Join Input: contacts with the name of their organization. Expected: a successful, executable relationship query. A nonexistent field, refused query or missing accounting fails the check. ### IOS-PFM-MTD-001-04 — Generate a Missing-Collection Condition Input: contacts with no addresses. Expected: an executable query capable of expressing absence. A refused result fails smoke; choosing an inner join that excludes the intended records is a semantic error for evaluation. ## 9. Evaluation Corpus The shared evaluation corpus covers filtering, joins, absence, grouping, relative dates, custom fields, ambiguity, unsupported requests, permissions and adversarial input. Its live runner evaluates generated answers against fixtures. A dedicated custom-object Explorer corpus is not established by this examination and should be considered before expanding the feature. ## 10. Call Shape and Batching One generation opens one execution and a bounded tool conversation. The pinned limits allow eight turns, sixteen tool calls, discovery depth three, two repairs, three attempts, a forty-five-second attempt timeout, a two-minute total duration and six thousand credits per call. The foundation controls retries and metering. Explorer starts and polls an asynchronous generation instead of batching record questions in a save. ## 11. Controls The operation is subject to foundation allowance, in-flight, feature enablement, budget and provider-circuit checks. Dataset grants are refreshed for the person who asked, and tool reads remain within those grants. No separately approved control identifiers are attached here. ## 12. Open Design Decisions Queries should remain the home for the generation behavior when its design layer is authored; this artifact makes the current metadata screen's dependency explicit. Andrew should decide whether custom-object list questions need a focused evaluation corpus before wider use.