docs: karpathy-pattern wiki built from the spec, plan, design contract and decisions ledger
kb/ is its own wiki root: 34 pages across 7 categories, index.md catalog, log.md, AGENTS.md schema layer, and raw/ holding copies of README, the spec, the 13-task plan, the design master and the SDD ledger. Every page cross-references 3 to 6 others and all 107 wikilinks resolve except two [["list"]] artefacts inside JSON snippets in the copied plan. Kept separate from the repository root on purpose: its generated graph lands in kb/.ua/ instead of overwriting the code graph. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
ahmed mohammed
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
735a57bfd6
commit
8b42a0931c
@@ -0,0 +1,114 @@
|
||||
# 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**.
|
||||
|
||||
### Getting the input, and the two keys
|
||||
|
||||
The portal cannot reach the SQL Server. The user brings the plan XML, and the app must say so in the run screen:
|
||||
SSMS → **Ctrl+M** (include actual execution plan) → run the query → save the Execution Plan tab as `.sqlplan`, or
|
||||
copy the Showplan XML cell; without SSMS, prefix the batch with `SET STATISTICS XML ON;` and copy the XML result
|
||||
cell. A `.sqlplan` file can be dropped in (SSMS writes UTF-16 with a BOM; decode both) or pasted.
|
||||
|
||||
Both model credentials are typed by the logged-in user in `/setup` or `/settings` — never server config, so every
|
||||
user brings their own analyst endpoint and their own TypeSafe/Jev key (`console.typesafe.ai/keys`). Stored keys come
|
||||
back masked, and a blank field means keep the stored one. Nothing leaves the container except the digest, and only
|
||||
to the endpoints that user configured.
|
||||
|
||||
## 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.
|
||||
|
||||
## Acceptance
|
||||
|
||||
What has to be true before this counts as done, and how each part is proven:
|
||||
|
||||
- **Offline unit suites** (`npm test`, no keys, no network): a real ShowPlan digests to the right numbers; input
|
||||
that is not a plan is refused with a named reason; analyst output is schema-checked and 2–4 options are enforced;
|
||||
Jev's scores rank, an unknown Jev label cannot lead, and a silent Jev degrades to a labelled composite order;
|
||||
credentials seal/open/mask and a blank field never wipes a stored key.
|
||||
- **One live run** against the user's real analyst endpoint and a real Jev key: every SSE stage fires, several
|
||||
candidates come back, Jev returns a verdict with confidence, and OpenUI Lang arrives in deltas.
|
||||
- **Browser QA** (Chromium): signup → guide → settings → run → rendered report; Copy puts SQL on the clipboard;
|
||||
print emulation flips to paper and hides the rail and buttons; rename sticks and delete confirms first; no
|
||||
horizontal scroll from 320 px up.
|
||||
- **A smoke script** (`scripts/smoke.sh`) that a container or a plain `npm start` both pass: health, auth pages,
|
||||
signed-out redirect, and `/api/analyze` refusing an anonymous caller.
|
||||
- **A goal gate**: Jev scores the written plan against the goal in this document and answers the named-gap question
|
||||
with `nothing` before implementation starts.
|
||||
Reference in New Issue
Block a user