--- id: IOP-PFM-LLM-002 title: Query Refinement Through Jazz AI product_area: platform module: llm revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: react-console: baf6dae382d6f41dce976c7f848667ccc37e076f services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 ai_task: queries.generate_query provider: anthropic model: claude-sonnet-5-5 reasoning_effort: medium called_by: - SVC-PFM-LLM-llm - WF-PFM-LLM-001 - WF-PFM-LLM-014 - SCR-PFM-LLM-001 - SCR-PFM-LLM-002 realises: - CAP-PFM-LLM-020 smoke_suite: 'services-platform:modules/queries/tests/live/generate-query/smoke.js' evaluation_suite: 'services-platform:modules/queries/tests/live/generate-query/evaluate.js' lifecycle_suite: 'services-platform:modules/llm/tests/integration/lifecycle/run-operation.integration.spec.js' related_decisions: - ADR-PFM-LLM-001 - ADR-PFM-LLM-002 - ADR-PFM-LLM-003 evidence: - 'react-console:components/queries/query-workspace.tsx:refine' - 'react-console:lib/queries/client.ts:interpret' - 'react-console:lib/queries/platform/client-live.ts:liveInterpret' - 'react-console:lib/queries/platform/client-live.ts:currentRequestFor' - 'react-console:lib/api/generate-query.ts:queryGenerationEnabled' - 'react-console:lib/api/generate-query.ts:GENERATE_TIMEOUT_MS' - 'services-platform:modules/llm/catalog/llm-operations.ts:LLM_OPERATION_DEFINITIONS' - 'services-platform:modules/llm/prompts/queries/generate-query.md' - 'services-platform:modules/queries/services/generate/run-generation.ts:runGeneration' - 'services-platform:modules/queries/tests/live/generate-query/smoke.js' controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, 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-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, 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-VEN-001, TC-VEN-002, TC-VEN-003] --- # Query Refinement Through Jazz AI ## 1. Purpose A person describes a change to the query on screen, and Jazz AI consumes query generation to propose revised criteria, columns or sorting. The same model task also drafts new queries. This artifact describes the refinement caller; Queries owns the broader generation contract, and duplicate task documentation across modules remains a finding. ## 2. Application and Model Responsibilities The console identifies the current dataset and query and sends the description without a page cursor. Queries constructs permission-filtered context and checks submitted output against schema, grants and compilation, allowing bounded repair. The model proposes a query, asks for clarification or reports unsupported work. The console preserves record type, context and prior column order, appends new columns and applies accepted results without saving. Message persistence and Undo remain application actions; model output does not select a stage or independently persist anything. ## 3. Inputs and Context Inputs include the versioned query instruction, permitted dataset vocabulary, the description and the current request. Prior generation can supply clarification context. The stable dictionary is supplied as cacheable context. Discovery and test-run tools return bounded authorized summaries rather than unrestricted record contents. The Jazz AI message history itself is not included in the generation request. ## 4. Output Contract A successful result contains a validated query, derived metadata, assumptions, warnings and any explanation. Alternative outcomes include clarification, unsupported work or stable failure. The live client maps query fields into workspace state and uses the summary as its reply. A clarification or failure does not silently become a persisted query. Directory assistance is a separate local path and has no model output contract. ## 5. Model and Provider The pinned declaration uses Anthropic Claude Sonnet 5.5 with medium effort, eight thousand output tokens per turn and prompt revision six. Platform resolves published routing and prices, records attempts and produces the metered request result. Provider substitution is not configured. ## 6. Prompt Contract The query instruction explains the language and dictionary, discovery and test-run tools, accepted final-answer tools and preservation of unchanged query parts. Stable content precedes volatile description and current-request context. The consumer validates answers; the generic runtime does not decide whether a query is meaningful. ## 7. Validation, Failure and Fallback Schema, permission and compiler checks can reject an answer and return repair feedback within the configured budget. Exhausted validation does not relax requested criteria. The live console switch defaults to unavailable unless explicitly enabled, while demonstration mode uses local interpretation. Customer-readable messages describe allowance, concurrency and disabled-operation refusals. Polling starts at one and a half seconds, grows to five and checks a ninety-second deadline between awaited calls; it does not impose an independent timeout on every transport call. Failure leaves visible query state unchanged, but a later conversation write can fail after an accepted change is applied. ## 8. Smoke Tests The shared smoke suite checks new-query generation and accounting, not refinement. These existing scenario identifiers therefore describe proposed refinement proof. ### IOS-PFM-LLM-002-01 — Retain Existing Criteria While Narrowing Input: a contacts query with existing criteria and columns, followed by an Ohio-only description. Expected: add the state condition while retaining earlier criteria and column order. A wrong result silently drops earlier restrictions. ### IOS-PFM-LLM-002-02 — Append a Requested Column Input: an existing query and a request to include email. Expected: append that column while preserving existing order. A wrong result removes or reorders unrelated columns. ### IOS-PFM-LLM-002-03 — Leave Work Unchanged After Admission Refusal Input: a refinement whose estimate exceeds remaining capacity. Expected: a readable allowance reply, no applied query change and refused request bookkeeping. A wrong result applies work or leaves an unexplained hold. ## 9. Evaluation Corpus The shared evaluation executes new-query results against fixtures and compares their record sets. It does not establish refinement preservation. A refinement corpus needs narrowing, widening, column and sort changes, clarification and conflicting instructions with expectations about retained state. ## 10. Call Shape and Batching Live refinement starts one asynchronous generation and polls its outcome. The normal worker opens one task and calls one metered model operation, which can make multiple provider requests. Configured budgets are eight turns, sixteen tool calls, two repairs, three attempts per turn, forty-five seconds per attempt, two minutes total and six thousand declared ceiling credits. The reservation calculated from the pinned estimate is five thousand four hundred and forty credits. Final acceptance precedes some runtime budget checks, and tool and validation handlers lack enforced deadlines, so these settings are not absolute usage bounds. ## 11. Controls Platform admission, concurrency, AI and operation switches, redacted capture and metering apply to live generation. Query tools use the caller’s dataset authority. The empty numbered-controls list does not mean those checks are absent. Prototype conversation storage still provides no authenticated-person or workspace isolation. ## 12. Open Design Decisions Choose one authoritative task-level inference contract across Queries, Metadata and this caller facet. Product must also resolve whether history should link to its metered request and whether more conversation context should guide refinement. These caller decisions do not authorize changes to the already recorded provider boundary.