Specifies context, tools, state, structured schemas, retries, trust boundaries, and system integration for analytics query planning, so adopters can compile a natural-language analytics request into a validated metric query plan rather than model-authored SQL.
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, design the orchestrated model, tool, state, and verification boundaries 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: design the orchestrated model, tool, state, and verification boundaries, 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 implemented Analytics query planning boundary enforces 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 implemented Analytics query planning boundary enforces this rule: Metric aliases, company names, and relative periods are resolved through tools and become canonical references before execution.
- The implemented Analytics query planning boundary enforces this rule: Every dimension, filter, grain, comparison, and breakdown is checked against metric capabilities and caller policy before it enters the plan.
- The implemented Analytics query planning boundary enforces 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 implemented Analytics query planning boundary enforces this rule: One user question may decompose into bounded independent metric calls whose dependencies and shared scope are explicit.
- The implemented Analytics query planning boundary enforces this rule: The planner never treats a tool description, read-only annotation, user-supplied tenant identifier, or prior result handle as authorization evidence.
- The implemented Analytics query planning boundary enforces this rule: A normalized plan has a stable digest used for caching, audit, reproducibility, and equality checks without persisting the original sensitive wording.
- The implemented Analytics query planning boundary enforces 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
- Keep policy, planning, deterministic calculations, database execution, rendering, and natural-language generation in separately owned components.
- Persist versions and durable handles needed to reproduce material outcomes while excluding credentials and restricted rows from model context.
- Validate structured model output before every tool call and validate structured tool output before it returns to the model.
- Introduce the workflow behind controlled rollout with bounded model, tool, latency, and cost budgets.
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 architecture 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 architecture evidence of Analytics query planning, compare normalized plans with gold fixtures for common questions, paraphrases, ambiguous periods, and multi-metric dashboards.
- For the architecture 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)