--- id: IOP-PFM-QRY-001 title: Query Drafting From a Written Request product_area: platform module: queries revision: 1 status: draft design_intent: confirmed 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: - SVC-PFM-QRY-queries - WF-PFM-QRY-004 - SCR-PFM-QRY-003 - SCR-PFM-QRY-004 realises: - CAP-PFM-QRY-003 smoke_suite: 'services-platform:modules/queries/tests/live/generate-query/smoke.js' evaluation_suite: >- services-platform:modules/queries/tests/live/generate-query/evaluate.js (scenarios in modules/queries/tests/evaluation/generate-query/scenarios) lifecycle_suite: >- services-platform:modules/queries/tests/integration/services/generate/start-and-reconcile-generations.integration.spec.js; run-generation.integration.spec.js; modules/queries/tests/e2e/generate-query.e2e.spec.js related_decisions: - ADR-PFM-QRY-015 - ADR-PFM-QRY-003 - ADR-PFM-QRY-004 evidence: - >- services-platform:modules/llm/catalog/llm-operations.ts:LLM_OPERATION_DEFINITIONS (queries.generate_query, prompt version 6) - 'services-platform:modules/queries/services/generate/run-generation.ts' - 'services-platform:modules/queries/services/generate/generate-query-tools.ts' - 'services-platform:modules/queries/services/generate/generate-query-context.ts' - 'services-platform:modules/queries/services/generate/query-dictionary.ts' - 'services-platform:modules/queries/services/generate/validate-generated-query.ts' - 'services-platform:modules/queries/services/generate/generated-query-outcome.ts' - 'services-platform:modules/queries/services/generate/generation-problem-codes.ts' - 'services-platform:modules/llm/prompts/queries/generate-query.md' - 'services-platform:docs/llm/llm-foundation-and-generate-query.md#10. Revision 4' - 'services-platform:docs/compliance/control-coverage.md#Component: queries-generate' - 'react-console:components/queries/ai-prompt-bar.tsx; lib/queries/platform/generate-interpret.ts' controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, TC-AI-006, TC-AI-007, TC-AVL-001, 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-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-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Query drafting from a written request ## 1. Purpose Translate a person’s description of the records they need into an editable query over their selected dataset. The model can instead ask for clarification or explain that the available language cannot express the request. ## 2. Application and Model Responsibilities The application selects permitted metadata, supplies the workspace date, checks allowance and invocation limits, applies query defaults and validates executable output. The model chooses fields, comparisons, relationships and presentation that express the request. Its tools can perform bounded read-only tests through application handlers, but the model does not select execution authority or write records directly. The final query becomes a proposal in the designer for the person to inspect and run. ## 3. Inputs and Context Context includes the static instructions, selected base dataset, permitted dictionary, current local date and written request. Refinement can include the previous request and outcome or the query already open. The dictionary starts with permitted datasets and, when the character budget is exceeded, retains whole datasets nearest to the base; a base context that still cannot fit is refused. Fenced context is treated as data rather than instruction. Bounded test tools return counts and configured summaries, never sample rows. Summaries allow selected scalar types and text fields whose final field segment names an allowed geographic address component, including city, state and postal code. They return at most ten common values per eligible filtered field. This classification limits exposure without proving that every allowed value is free of personal information. Hidden or unauthorized vocabulary, unrestricted record text, SQL and credentials are excluded. ## 4. Output Contract The final tool submits a query with assumptions and optional explanation, asks a question with interpretation options, or returns an unsupported reason and optional missing-capability description. Successful query storage includes validated defaulted request content, application warnings, used metadata and the dictionary digest. Clarification, assumptions and unsupported explanation remain model-authored content; they are not deterministic application facts. Failure storage uses a declared code rather than provider error text. ## 5. Model and Provider The pinned catalog selects Anthropic Claude Sonnet 5.5 with medium reasoning effort and prompt version six. The generation worker invokes the LLM foundation, which retains the selected operation, model, prompt, routing and rate versions on its usage records. The accepted mechanism record supports this configuration without approving the entire assisted-authoring product outcome. ## 6. Prompt Contract A reusable system instruction block is followed by a user message split into a cacheable dictionary prefix and changing request context. The compact dictionary shares type defaults and overlays field-specific metadata. Instructions explain relationships, collection existence checks, uncertain stored-value testing, empty-value behavior and the treatment of fenced content. Tool schemas restrict generated requests further than the general query language, including cursor and group-negation restrictions. ## 7. Validation, Failure and Fallback Application validation applies deterministic defaults before schema checking, generation-specific checks and compilation under the requester context. The checks constrain the base dataset, visibility, output column count and unsupported request constructs. Invalid validation, test or submission requests share a two-repair budget; exhausted repair or unacceptable final output settles with the appropriate failure code. Provider timeout, refusal, unavailability, circuit state, operation configuration, foundation budgets, allowance and concurrent-call limits use their declared outcomes. There is no fallback model. The person can refine the request or return to manual authoring. The summaries configuration deliberately rejects sample-row visibility rather than offering it as an enabled option. ## 8. Smoke Tests The live smoke suite uses four prompts. For each, its executable assertion requires a successful query outcome that the ordinary executor accepts, a settled invocation matching the published task, model and prompt version, positive charged credits and reported usage. It also checks that no reservation remains after the run. It does not assert the semantic query shapes below; those are additional quality expectations and remain a recorded proof gap. ### IOS-PFM-QRY-001-01 — Simple filter Input: “inactive contacts.” The intended answer selects inactive contacts rather than treating the phrase as a free-text name search. An omitted or unrelated status restriction is wrong, even if that query executes successfully. The existing smoke assertion only establishes executability and accounting. ### IOS-PFM-QRY-001-02 — Default columns Input: “all our contacts.” The intended answer uses registered default columns when none are requested, without inventing unsupported fields. Empty or unrelated selected columns are wrong. The smoke suite does not compare the stored columns with those defaults. ### IOS-PFM-QRY-001-03 — Related organization Input: “contacts together with the name of the organization they belong to.” The intended answer uses a permitted relationship or pick to include the organization name. An unsupported response or unrelated field fails that expectation. The existing smoke suite does not inspect the chosen relationship. ### IOS-PFM-QRY-001-04 — No related addresses Input: “contacts who have no addresses at all.” The intended answer preserves contacts without address records through a suitable absence condition. An inner join that requires an address is wrong. The smoke suite does not compare the resulting population with that intended absence condition. ## 9. Evaluation Corpus The fixture-backed evaluation corpus covers filters, nesting, option values, relationships, custom fields, dates, absence, ordering, columns, joins, repeated records, grouping, ambiguity, unsupported requests, permission limits and adversarial input. Deterministic fixture checks first establish the expected population; model quality is then assessed by executing its output and comparing results rather than requiring identical query text. Reports retain category accuracy, clarification behavior, latency and usage. The examined scripts and historical reports are evidence of a proof mechanism, not a new passing live run at these revisions. ## 10. Call Shape and Batching A generation uses one metered conversation with at most eight turns, sixteen tool calls, discovery depth three and three bounded test executions. Provider requests have a forty-five-second attempt limit, at most three attempts and a two-minute total operation budget inside the 150-second worker. Output is capped at eight thousand tokens and the call credit cap is six thousand. Reservation estimates account for the permitted conversation and settle to actual usage; reconciliation handles interrupted work. The dictionary prefix can be cached, but its size varies with the permitted workspace metadata rather than a fixed token count. ## 11. Controls Route and dataset checks determine what the requester may use. Workspace-scoped context and outcomes restrict access, application handlers validate model proposals, and the foundation records usage and attempts. Output rejection protects executable query storage; it does not remove every explanatory model string from a successful outcome. Summary classification and count limits constrain provider-visible record information without treating permitted metadata as trusted instructions. ## 12. Open Design Decisions The complete assisted-authoring outcome remains proposed despite acceptance of its foundation mechanism. Semantic smoke assertions need stronger proof than the current execution and accounting checks. Any future widening from counts and summaries to sample records requires a deliberate product and privacy decision; it is disabled in the examined implementation.