85 lines
4.1 KiB
Markdown
85 lines
4.1 KiB
Markdown
# SQL Server qAI — Spec
|
||
|
||
**Date:** 2026-09-21
|
||
**Owner:** ahmedmohammed
|
||
**Status:** agreed in chat, this file is the spec of record
|
||
|
||
## Goal (verbatim from the owner)
|
||
|
||
> portal that take xml of sql server query plan and use power of generative ai to
|
||
> analysis provide multiple action steps, multiple query rewrite if possible,
|
||
> Jev then rank and decide.
|
||
|
||
## What it is
|
||
|
||
A containerised web tool. A DBA or consultant logs in, pastes a SQL Server
|
||
execution plan (Showplan XML, or a `.sqlplan` file), and gets back:
|
||
|
||
1. What the plan says is wrong (bottleneck, missing indexes, spills, bad row guesses).
|
||
2. **Multiple** candidate action plans — several different remediations, not one.
|
||
3. **Multiple** candidate SQL rewrites where a rewrite is possible.
|
||
4. A **Jev**-ranked verdict: which candidate to run first, with typed probabilities
|
||
and confidence, and why.
|
||
5. One final "best fast path": the recommended SQL and the steps to apply it.
|
||
6. The result rendered as **structured UI elements** (OpenUI Lang → React), not a
|
||
wall of markdown. Export to PDF, copy to clipboard.
|
||
|
||
The demo value is Jev as the decision-maker: the generative model proposes,
|
||
**Jev disposes**. Every ranking number on screen is a typed judgment from
|
||
`POST /v1/systemone`, not a string the LLM wrote.
|
||
|
||
## Product surface
|
||
|
||
| Screen | Job |
|
||
| --- | --- |
|
||
| `/signup`, `/login` | Email + password. Nothing else. |
|
||
| `/setup` | First-run guide: 3 steps — analyst model, Jev, done. |
|
||
| `/app` | Left rail = previous analyses (rename, delete). Main = paste plan → run → live report. |
|
||
| `/settings` | Update analyst model (base URL, key, model, extra params), Jev (key, model), email/password, history. |
|
||
|
||
Report actions: **Export to PDF**, **Copy**. History actions: **rename**, **delete**.
|
||
|
||
## Actors (two models, strict roles)
|
||
|
||
- **Analyst** — any OpenAI-compatible endpoint the user configures (`base_url`,
|
||
`key`, `model`, extra params). Generates: candidate action plans, candidate SQL
|
||
rewrites, and the final OpenUI Lang report. Text in, text out.
|
||
- **Jev** — TypeSafe System One (`@typesafe-ai/sdk`, model `jev-latest`). Never
|
||
generates prose. Answers typed questions (`score`, `choice`, `noul`) about each
|
||
candidate and returns probabilities + confidence. Code combines them.
|
||
|
||
## Requirements
|
||
|
||
1. Auth: signup, login, logout, session survives reload. Per-user data isolation.
|
||
2. Credentials at rest are encrypted (AES-256-GCM, `APP_SECRET` env). Never echoed
|
||
to the browser — masked (`••••1234`).
|
||
3. Plan input: paste XML, or drop/select a `.sqlplan`/`.xml` file. Clear inline
|
||
error if it is not a ShowPlanXML document.
|
||
4. Deterministic digest first, model second: parse the XML in code (operators,
|
||
costs, missing indexes, warnings, waits, spills, estimate vs actual). The model
|
||
sees the digest, never 40 MB of XML.
|
||
5. 2–4 candidates per run. Each candidate: diagnosis, ordered actions with effort
|
||
and change-control flag, optional rewrite SQL, expected effect.
|
||
6. Jev judges every candidate in parallel on 4 dimensions, then a second call picks
|
||
`first_to_run` across all candidates. Composite weights live in code, visible in UI.
|
||
7. Safety gate: a candidate Jev rates as semantically unsafe is never presented as
|
||
the recommended path without a visible "verify results before deploying" flag.
|
||
8. History: every run persisted (input digest, candidates, Jev verdict, rendered
|
||
report). Reopening a history item replays the stored report — zero model calls.
|
||
9. Streaming: stage indicator while digesting/proposing/judging, then the report
|
||
renders token-by-token. No spinner-for-30-seconds.
|
||
10. Single container: `docker compose up` → one image, one `/data` volume, no
|
||
external DB, no queue, no Redis.
|
||
|
||
## Non-goals
|
||
|
||
- No live connection to SQL Server. No plan-from-cache lookup. No automatic index
|
||
creation. No multi-user teams, roles, or sharing. No billing. No mobile app.
|
||
No markdown editor. No prompt marketplace. No agentic loop with tool calls.
|
||
|
||
## Success looks like
|
||
|
||
Paste a real slow-query plan → under 60 s → a ranked set of remediations where the
|
||
top pick is defensible because Jev's probabilities are on screen, and the winning
|
||
SQL is one click from the clipboard.
|