Class: AskService

Defined in: server/insights/services/ask-service.ts:92

Turn a natural-language question into a VALIDATED ReportDefinition.

Three properties this class exists to guarantee:

1. Nothing a model says is trusted. Every draft is re-parsed with reportDefinitionSchema (structure, discriminated operator/value shapes, filter depth/leaf caps) AND re-checked with validateDefinition (subject and field existence, per-field capabilities, operator/type compatibility, enum allowlists, column/sort resolution) against the CURRENT model. A drafted subject or field that does not exist in the registry — a hallucinated key, a physical table name, an injected select … from users — cannot survive that pass.
2. Exactly one bounded retry — and a refusal is not retried. If the first draft fails structurally or semantically, the issues are fed back once and the second answer is final. This is straight-line code, not a loop: an adversarial or confused model cannot cost more than two provider calls. A deliberate refusal (ASK_ISSUE_CODES.unanswerable) is TERMINAL — see isDeliberateRefusal.
3. The request's temporal frame wins. The definition's timezone is pinned to the resolved request timezone, so it can never disagree with the today the model was given — see AskService.validate.
4. It never executes anything. There is no QueryService, no Prisma client, and no runner on AskServiceDeps. Running a drafted definition is the caller's explicit second step (queryService.run), so a human can see the definition before it touches the database.

Rate limiting is deliberately absent — it belongs on the consumer's router, where the session, plan, and quota live.

ConstructorsCopy Anchor Link

ConstructorCopy Anchor Link

new AskService(deps: AskServiceDeps): AskService;

Defined in: server/insights/services/ask-service.ts:98

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

AskService

MethodsCopy Anchor Link

draft()Copy Anchor Link

draft(prompt: string, ctx: AskContext): Promise<AskDraftResult>;

Defined in: server/insights/services/ask-service.ts:116

Draft a report definition for prompt.

Resolves to { ok: true, definition } only when the draft passed both validators; otherwise { ok: false, issues } with every problem from the FINAL attempt. A returned definition always carries the resolved request timezone, and an explicit refusal is returned as-is after ONE attempt. Provider transport failures (auth, rate limit, timeout) propagate as thrown errors so a consumer's router can map their status codes — they are not folded into issues.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<AskDraftResult>