58 lines
2.9 KiB
Markdown
58 lines
2.9 KiB
Markdown
# User guide: from question to validated SQL
|
||
|
||
This guide is for a reviewer using a configured ThothII installation. Installation, workspace
|
||
publication, preprocessing, and database administration are separate paths; links to them are at
|
||
the end of this page.
|
||
|
||
## Before creating a session
|
||
|
||
An administrator must have selected a workspace and configured the installation-wide provider,
|
||
model, and thinking settings. The New session form deliberately asks only for the question.
|
||
|
||
The workspace is a pinned Git revision. A subsequent workspace update cannot alter a session
|
||
already created from an earlier revision. If a workspace cannot reach its configured runtime DWH,
|
||
new sessions are refused before any session state is written.
|
||
|
||
## Create and review a session
|
||
|
||
1. Sign in and select **New session**.
|
||
2. Enter a precise business question, including the relevant time period and desired output. For
|
||
example: “List patients discharged in the last 30 days, with ward and discharge date.”
|
||
3. Review each gate and make the decision requested by the widget. A choice with a decision payload
|
||
can persist immediately; a multi-choice widget records each selected decision; a confirmation
|
||
widget approves an artifact or phase.
|
||
4. Inspect the generated artifacts, especially schema linking, CTEs, and final SQL. The final SQL is
|
||
available only after the F7 review gate.
|
||
5. At F8, decide whether a datamart is requested. This is distinct from approving the SQL.
|
||
|
||
The workflow phases are fixed:
|
||
|
||
| Phase | What is reviewed |
|
||
| --- | --- |
|
||
| F1–F3 | clarification, reusable Memory, and the rewritten question |
|
||
| F4–F5 | proposed tables, columns, Evidence, then their summary |
|
||
| F6 | a CTE plan or an explicit skip |
|
||
| F7 | `sql_final.sql` |
|
||
| F8 | the datamart request or refusal |
|
||
|
||
## Resume, archive, and the meaning of saved state
|
||
|
||
The sidebar lists sessions and their current lifecycle. Resuming returns to the last incomplete
|
||
phase. A finalized or archived session cannot be resumed.
|
||
|
||
The source of truth is the workspace session directory: `session_manifest.yaml`, phase artifacts,
|
||
and `review_decisions.jsonl`. The visible activity stream is rebuilt from live SSE events and is
|
||
not a transcript store. Therefore a decision or artifact that has not been persisted did not
|
||
happen from the workflow’s point of view.
|
||
|
||
## Choose the correct neighbouring path
|
||
|
||
- To prepare, update, validate, or preprocess a workspace, use
|
||
[Workspace operations](operations/workspaces.md).
|
||
- To create a database configuration, refresh its physical schema, or generate catalog
|
||
descriptions, use [Database management](operations/database-management.md).
|
||
- To author material the workflow can retrieve, use [Evidence](evidence.md). A proposal from a
|
||
session does not become Evidence automatically: a curator must review and publish it in Git.
|
||
- For login and access recovery, use [local authentication](install/authentication-local.md) or
|
||
[OIDC authentication](install/authentication-oidc.md).
|