230 lines
11 KiB
HTML
230 lines
11 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
|
||
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
|
||
<link rel="canonical" href="https://git.tylconsulting.it/thothii-docs/guida-utente/">
|
||
<link rel="shortcut icon" href="../img/favicon.ico">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" />
|
||
<title>User guide - ThothII Docs</title>
|
||
<link href="../css/bootstrap-3.3.7.min.css" rel="stylesheet">
|
||
<link href="../css/font-awesome-4.7.0.css" rel="stylesheet">
|
||
<link href="../css/base.css" rel="stylesheet">
|
||
<link rel="stylesheet" href="../css/highlight.css">
|
||
<link href="../stylesheets/extra.css" rel="stylesheet">
|
||
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
|
||
<!--[if lt IE 9]>
|
||
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
|
||
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
|
||
<![endif]-->
|
||
|
||
<script src="../js/jquery-3.2.1.min.js"></script>
|
||
<script src="../js/bootstrap-3.3.7.min.js"></script>
|
||
<script src="../js/highlight.pack.js"></script>
|
||
|
||
<base target="_top">
|
||
<script>
|
||
var base_url = '..';
|
||
var is_top_frame = false;
|
||
|
||
var pageToc = [
|
||
{title: "User guide: from question to validated SQL", url: "#_top", children: [
|
||
{title: "Standalone or inside Omics", url: "#standalone-or-inside-omics" },
|
||
{title: "Before creating a session", url: "#before-creating-a-session" },
|
||
{title: "Create and review a session", url: "#create-and-review-a-session" },
|
||
{title: "Resume, archive, and the meaning of saved state", url: "#resume-archive-and-the-meaning-of-saved-state" },
|
||
{title: "Choose the correct neighbouring path", url: "#choose-the-correct-neighbouring-path" },
|
||
]},
|
||
];
|
||
|
||
</script>
|
||
<script src="../js/base.js"></script>
|
||
<script src="../javascripts/layout-init.js"></script>
|
||
</head>
|
||
|
||
<body>
|
||
<script>
|
||
if (is_top_frame) { $('body').addClass('wm-top-page'); }
|
||
</script>
|
||
|
||
|
||
|
||
<div class="container-fluid wm-page-content">
|
||
<a name="_top"></a>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
|
||
|
||
<div class="wm-article-nav pull-right">
|
||
<a href="../install/first-start/" class="btn btn-xs btn-default pull-right">
|
||
Next
|
||
<i class="fa fa-chevron-right" aria-hidden="true"></i>
|
||
</a>
|
||
<a href="../install/first-start/" class="btn btn-xs btn-link">
|
||
Start here
|
||
</a>
|
||
</div>
|
||
|
||
<div class="wm-article-nav">
|
||
<a href="../skills/" class="btn btn-xs btn-default pull-left">
|
||
<i class="fa fa-chevron-left" aria-hidden="true"></i>
|
||
Previous</a><a href="../skills/" class="btn btn-xs btn-link">
|
||
Reviewed workflow
|
||
</a>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
<h1 id="user-guide-from-question-to-validated-sql">User guide: from question to validated SQL<a class="headerlink" href="#user-guide-from-question-to-validated-sql" title="Permanent link">¶</a></h1>
|
||
<p>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.</p>
|
||
<h2 id="standalone-or-inside-omics">Standalone or inside Omics<a class="headerlink" href="#standalone-or-inside-omics" title="Permanent link">¶</a></h2>
|
||
<p>In <strong>full</strong> 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.</p>
|
||
<p>In <strong>embedded</strong> mode, first sign in to Omics and choose <strong>Datamart Builder</strong> 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.</p>
|
||
<p>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.</p>
|
||
<h2 id="before-creating-a-session">Before creating a session<a class="headerlink" href="#before-creating-a-session" title="Permanent link">¶</a></h2>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
<h2 id="create-and-review-a-session">Create and review a session<a class="headerlink" href="#create-and-review-a-session" title="Permanent link">¶</a></h2>
|
||
<ol>
|
||
<li>Sign in and select <strong>Session</strong> (<strong>Sessione</strong> 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.</li>
|
||
<li>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.”</li>
|
||
<li>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.</li>
|
||
<li>Inspect the generated artifacts, especially schema linking, CTEs, and final SQL. The final SQL is
|
||
available only after the F7 review gate.</li>
|
||
<li>At F8, decide whether a datamart is requested. This is distinct from approving the SQL.</li>
|
||
</ol>
|
||
<p>The workflow phases are fixed:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Phase</th>
|
||
<th>What is reviewed</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>F1–F3</td>
|
||
<td>clarification, reusable Memory, and the rewritten question</td>
|
||
</tr>
|
||
<tr>
|
||
<td>F4–F5</td>
|
||
<td>proposed tables, columns, Evidence, then their summary</td>
|
||
</tr>
|
||
<tr>
|
||
<td>F6</td>
|
||
<td>a CTE plan or an explicit skip</td>
|
||
</tr>
|
||
<tr>
|
||
<td>F7</td>
|
||
<td><code>sql_final.sql</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>F8</td>
|
||
<td>the datamart request or refusal</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h2 id="resume-archive-and-the-meaning-of-saved-state">Resume, archive, and the meaning of saved state<a class="headerlink" href="#resume-archive-and-the-meaning-of-saved-state" title="Permanent link">¶</a></h2>
|
||
<p>In Administration, the dot beside <strong>Workspace</strong> 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.</p>
|
||
<p>The session sidebar has two accordion sections: <strong>Active sessions</strong> and
|
||
<strong>Archive</strong>, both initially closed. Only their headers appear below the scope tabs.
|
||
Inside each nonempty list, <strong>Select all</strong> 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.</p>
|
||
<p>The sidebar lists sessions and their current lifecycle. Resuming returns to the last incomplete
|
||
phase. A finalized or archived session cannot be resumed.</p>
|
||
<p>The source of truth is the workspace session directory: <code>session_manifest.yaml</code>, phase artifacts,
|
||
and <code>review_decisions.jsonl</code>. 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.</p>
|
||
<h2 id="choose-the-correct-neighbouring-path">Choose the correct neighbouring path<a class="headerlink" href="#choose-the-correct-neighbouring-path" title="Permanent link">¶</a></h2>
|
||
<ul>
|
||
<li>To prepare, update, validate, or preprocess a workspace, use
|
||
<a href="../operations/workspaces/">Workspace operations</a>.</li>
|
||
<li>To create a database configuration, refresh its physical schema, or generate catalog
|
||
descriptions, use <a href="../operations/database-management/">Database management</a>.</li>
|
||
<li>To author material the workflow can retrieve, use <a href="../evidence/">Evidence</a>. A proposal from a
|
||
session does not become Evidence automatically: a curator must review and publish it in Git.</li>
|
||
<li>For login and access recovery, use <a href="../install/authentication-local/">local authentication</a> or
|
||
<a href="../install/authentication-oidc/">OIDC authentication</a> for full, or contact the
|
||
portal administrator for <a href="../install/shell-and-language/">embedded/upstream access</a>.</li>
|
||
</ul>
|
||
|
||
<br>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
|
||
|
||
<div class="wm-article-nav pull-right">
|
||
<a href="../install/first-start/" class="btn btn-xs btn-default pull-right">
|
||
Next
|
||
<i class="fa fa-chevron-right" aria-hidden="true"></i>
|
||
</a>
|
||
<a href="../install/first-start/" class="btn btn-xs btn-link">
|
||
Start here
|
||
</a>
|
||
</div>
|
||
|
||
<div class="wm-article-nav">
|
||
<a href="../skills/" class="btn btn-xs btn-default pull-left">
|
||
<i class="fa fa-chevron-left" aria-hidden="true"></i>
|
||
Previous</a><a href="../skills/" class="btn btn-xs btn-link">
|
||
Reviewed workflow
|
||
</a>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<br>
|
||
</div>
|
||
|
||
<footer class="container-fluid wm-page-content">
|
||
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a> using <a href="https://github.com/gristlabs/mkdocs-windmill">Windmill</a> theme by Grist Labs.</p>
|
||
</footer>
|
||
|
||
</body>
|
||
</html> |