Defines intended behavior, human controls, prohibited authority, clarification, fallback, and evidence requirements for analytics query planning, so adopters can compile a natural-language analytics request into a validated metric query plan rather than mod...
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
For Analytics query planning, define the assistant behavior and authority boundary so adopters can compile a natural-language analytics request into a validated metric query plan rather than model-authored SQL. The planner selects registered semantic operations; the trusted gateway alone compiles and executes database-specific queries. This is a reference contract: database products, numeric budgets, jurisdictions, retention, organizational defaults, and accountable owners remain explicit adoption choices.
Scope
- The Analytics query planning actors, inputs, outputs, states, versions, and externally visible outcomes needed to compile a natural-language analytics request into a validated metric query plan rather than model-authored SQL.
- The role-specific focus of this block: define the assistant behavior and authority boundary, including primary, cached, asynchronous, export, support, and recovery paths where applicable.
- Adoption-specific configuration, ownership, rollout, evidence retention, and review responsibilities needed to use the contract safely.
Outside this block
- The planner selects registered semantic operations; the trusted gateway alone compiles and executes database-specific queries.
- Choosing a universal database, model, renderer, vendor, numeric threshold, retention period, timezone, jurisdiction, or service-level objective.
- Claiming that packaged scenarios ran against a downstream implementation or that this reference grants security, privacy, accessibility, analytical, or legal approval.
Contract
- The declared Analytics query planning contract requires this rule: The planner emits a closed structured schema containing metric IDs and approved operators; free-form SQL, expressions, table names, and column names are forbidden fields.
- The declared Analytics query planning contract requires this rule: Metric aliases, company names, and relative periods are resolved through tools and become canonical references before execution.
- The declared Analytics query planning contract requires this rule: Every dimension, filter, grain, comparison, and breakdown is checked against metric capabilities and caller policy before it enters the plan.
- The declared Analytics query planning contract requires this rule: The plan declares expected result shape, row and series limits, freshness need, precision mode, and cost class so the gateway can reject excessive work early.
- The declared Analytics query planning contract requires this rule: One user question may decompose into bounded independent metric calls whose dependencies and shared scope are explicit.
- The declared Analytics query planning contract requires this rule: The planner never treats a tool description, read-only annotation, user-supplied tenant identifier, or prior result handle as authorization evidence.
- The declared Analytics query planning contract requires this rule: A normalized plan has a stable digest used for caching, audit, reproducibility, and equality checks without persisting the original sensitive wording.
- The declared Analytics query planning contract requires this rule: Plan repair may change only fields identified by structured tool errors and cannot widen subject scope or swap the requested metric silently.
Implementation guidance
- Write representative user questions, ambiguous variants, adversarial requests, and expected abstentions before selecting a model or prompt.
- Separate product defaults from facts the assistant must resolve through trusted tools and name who approves each default.
- Define a non-AI baseline and a safe degraded response for unavailable models, tools, or verification.
- Review outputs with business, data, security, and affected user representatives before broad rollout.
Failure handling and safeguards
- For Analytics query planning, An unresolvable metric, subject, period, dimension, or comparison returns a clarification or unsupported request before database work begins.
- For Analytics query planning, A plan above query, cost, cardinality, or result-size budgets is narrowed with user-visible consequences or denied.
- For Analytics query planning, If multiple metrics match materially different meanings, the planner presents their plain descriptions rather than choosing from abbreviated IDs.
Verification and operations
- For the requirements evidence of Analytics query planning, validate plans against a closed schema and fuzz all strings to prove that SQL fragments cannot become identifiers, filters, or expressions.
- For the requirements evidence of Analytics query planning, compare normalized plans with gold fixtures for common questions, paraphrases, ambiguous periods, and multi-metric dashboards.
- For the requirements evidence of Analytics query planning, verify that repair after every error class preserves caller scope, metric intent, plan budget, and prior approved assumptions.
Adoption assumptions
- The adopting product has authenticated identity, a versioned authorization policy, owned metric definitions, bounded telemetry, and a controlled path for change.
- Names and values in the example are fictional adoption fixtures, not universal defaults, production credentials, performance promises, or business targets.
- Referenced specifications constrain protocol, security, accessibility, or vendor behavior; the adopting team must confirm current applicability before promotion.
The executable-looking examples in this package are fixtures and acceptance contracts. Run the collection validator to check structure and metadata, then translate and execute the scenarios in the target repository before recording implementation evidence.
References
- NIST AI 600-1, Generative AI Profile (applies as of 2026-09-12)
- JSON Schema Core, Draft 2020-12
- Model Context Protocol 2026-07-28, Tools (applies as of 2026-09-12)