94 lines
5.3 KiB
Markdown
94 lines
5.3 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.
|
||
|
||
## Standalone or inside Omics
|
||
|
||
In **full** mode, ThothII has its own red header. Sign in using the installation's
|
||
local account or the configured identity provider. The header lets you select
|
||
English/Italian, light/dark, and fullscreen; Esc exits fullscreen. Open the user
|
||
name menu to log out of ThothII. OIDC logout does not necessarily log out other
|
||
applications using the same provider.
|
||
|
||
In **embedded** mode, first sign in to Omics and choose **Datamart Builder** in
|
||
its left menu. ThothII opens with that authenticated identity: there is no second
|
||
login or duplicate header. Use Omics's language, theme, fullscreen and logout
|
||
controls. If portal access expires, return to Omics, sign in and reopen the page.
|
||
|
||
The Mac starts in English unless the browser remembers another choice. Changing
|
||
the UI language affects labels, not saved domain content. A new session takes
|
||
the selected language for the model's questions and reviewer choices; an existing
|
||
session retains its saved language when resumed. Omics's language change reloads
|
||
the page: confirm or cancel any unsaved-work warning. Reopening the saved session
|
||
selection shows documents; it does not automatically restart generation.
|
||
|
||
## Before creating a session
|
||
|
||
An administrator must have selected a workspace and configured the installation-wide provider,
|
||
model, and thinking settings. The new-question 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 **Session** (**Sessione** in Italian). If a session is already
|
||
open and unfinished, this returns to it without restarting it. Otherwise it
|
||
opens a new question; no session is created until you submit that question.
|
||
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
|
||
|
||
In Administration, the dot beside **Workspace** is green when readiness is
|
||
confirmed and red otherwise. Hover the button for the exact state; assistive
|
||
technology receives the same description. Select Workspace to inspect preparation.
|
||
|
||
The session sidebar has two accordion sections: **Active sessions** and
|
||
**Archive**, both initially closed. Only their headers appear below the scope tabs.
|
||
Inside each nonempty list, **Select all** selects only that list; its delete action
|
||
also applies only to the selected sessions in that list. The other list's selection
|
||
is preserved. Opening a section closes the other; clicking the open section closes
|
||
it too. Empty lists show only "No sessions yet." Long lists scroll inside
|
||
their own panels. Here active means not archived, not necessarily a running model
|
||
process. Existing groups and session actions remain inside those sections.
|
||
|
||
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) for full, or contact the
|
||
portal administrator for [embedded/upstream access](install/shell-and-language.md).
|