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