224 lines
10 KiB
HTML
224 lines
10 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/operations/workspaces/">
|
|
<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>Workspaces - 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: "Workspace operations", url: "#_top", children: [
|
|
{title: "Roles and ownership", url: "#roles-and-ownership" },
|
|
{title: "Operator sequence", url: "#operator-sequence" },
|
|
{title: "Transport and revision rules", url: "#transport-and-revision-rules" },
|
|
]},
|
|
];
|
|
|
|
</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="../database-management/" class="btn btn-xs btn-default pull-right">
|
|
Next
|
|
<i class="fa fa-chevron-right" aria-hidden="true"></i>
|
|
</a>
|
|
<a href="../database-management/" class="btn btn-xs btn-link">
|
|
Databases and descriptions
|
|
</a>
|
|
</div>
|
|
|
|
<div class="wm-article-nav">
|
|
<a href="../../general/pi-configuration/" class="btn btn-xs btn-default pull-left">
|
|
<i class="fa fa-chevron-left" aria-hidden="true"></i>
|
|
Previous</a><a href="../../general/pi-configuration/" class="btn btn-xs btn-link">
|
|
Model configuration
|
|
</a>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<h1 id="workspace-operations">Workspace operations<a class="headerlink" href="#workspace-operations" title="Permanent link">¶</a></h1>
|
|
<p>A workspace is curator-owned Git content plus installation-local runtime bindings. It is the
|
|
boundary between what can be published and what can be used by an installation.</p>
|
|
<h2 id="roles-and-ownership">Roles and ownership<a class="headerlink" href="#roles-and-ownership" title="Permanent link">¶</a></h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Role</th>
|
|
<th>Owns</th>
|
|
<th>Does not own</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>Curator</td>
|
|
<td><code>thoth-workspaces.yaml</code>, <code><id>/workspace.yaml</code>, and Evidence</td>
|
|
<td>database metadata, installation secrets, or active runtime bindings</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Installation operator</td>
|
|
<td>Git source, selected workspace, write-only runtime secrets, validation, connectivity, and preprocessing</td>
|
|
<td>commits or pushes to the workspace repository</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Reviewer</td>
|
|
<td>NL→SQL decisions in a pinned session</td>
|
|
<td>workspace publication or preprocessing</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<!-- non-workspace-migration:start -->
|
|
<p>The root catalog has <code>schema_version: 1</code> and an ordered list of workspace identities.</p>
|
|
<!-- non-workspace-migration:end -->
|
|
|
|
<!-- workspace-descriptor-contract:start -->
|
|
<p>Schema v4 is the only accepted workspace descriptor. Schema v1, v2, and v3 workspace descriptors
|
|
are rejected before activation. Each catalog entry must have a matching descriptor at
|
|
<code><id>/workspace.yaml</code> in the same Git commit. The application validates a complete candidate
|
|
revision and activates it atomically; invalid content leaves the preceding active revision in
|
|
place. A v4 descriptor contains only workspace identity and optional Evidence configuration; it
|
|
does not contain a database or database metadata.</p>
|
|
<!-- workspace-descriptor-contract:end -->
|
|
|
|
<!-- non-workspace-migration:start -->
|
|
<p>Create a clean v4 descriptor with <code>workspace</code> and optional <code>evidence</code>. Do not import the old DWH,
|
|
diagnostics, annotation, <code>llm_policy</code>, or <code>semantic_index</code> blocks. Configure the database in
|
|
Database Management. ThothII never rewrites the curator-owned repository during pull.</p>
|
|
<!-- non-workspace-migration:end -->
|
|
|
|
<h2 id="operator-sequence">Operator sequence<a class="headerlink" href="#operator-sequence" title="Permanent link">¶</a></h2>
|
|
<ol>
|
|
<li>Curate and push a complete repository revision. Do not put DWH passwords, API keys, private
|
|
keys, or signed URLs in this repository.</li>
|
|
<li>In the application, update the workspace repository. This fetches and validates the candidate;
|
|
it never edits the remote repository.</li>
|
|
<li>Select the workspace. Supply or replace its write-only Evidence runtime secrets, configure its
|
|
database in <strong>Database Management</strong>, then run <strong>Validate workspace source</strong> and <strong>Test workspace
|
|
connections</strong>. The workspace connection test uses that same current database configuration for
|
|
DWH connectivity and also checks the workspace Evidence and installation semantic services.</li>
|
|
<li>Select it as the installation workspace before creating sessions.</li>
|
|
<li>Expand <strong>Administration</strong> in the right sidebar and run <strong>Preprocessing</strong>. The button is available
|
|
when all prerequisites are satisfied: it shows <strong>Run</strong> when preprocessing is required,
|
|
<strong>Run again</strong> when the workspace is already current, and <strong>Retry</strong> after a failure. The same
|
|
operation is available from the host CLI for unattended administration. <strong>Clear</strong>, immediately
|
|
to the left, removes only replaceable Schema/Evidence vectors, LSH, corpus, and checkpoints after
|
|
an inline confirmation; it preserves Memory and solved questions. <code>--json</code> keeps CLI stdout
|
|
machine-readable.</li>
|
|
</ol>
|
|
<pre class="highlight"><code class="language-sh">INSTALLATION=/absolute/path/thothii-installation.yaml
|
|
WORKSPACE=example-workspace
|
|
|
|
tht --installation "$INSTALLATION" workspace inspect --workspace "$WORKSPACE" --json
|
|
tht --installation "$INSTALLATION" workspace preprocess run --workspace "$WORKSPACE" --json
|
|
tht --installation "$INSTALLATION" workspace preprocess clear --workspace "$WORKSPACE" --json</code></pre>
|
|
<p>The command snapshots tables, columns, descriptions, sensitivity, and active relationships from
|
|
PostgreSQL, samples eligible DWH values for LSH, and replaces the schema/Evidence vector slices.
|
|
It is rerunnable but not resumable and has no rollback. Catalog sync and description generation
|
|
remain separate operations and must already be complete.</p>
|
|
<p>After clear, the sidebar reports <strong>Required</strong> and the core rejects new sessions until a complete run
|
|
succeeds. Clear can be repeated safely: an already absent reference collection or derived path is a
|
|
no-op, and the separate Memory collection is never a cleanup target.</p>
|
|
<p>The sidebar retains no run history. If the current prerequisite blocks a start, it explains what
|
|
must be completed and correctly reports that there is no run log. If the last run failed, it shows
|
|
only that run's safe stage, error code, and finish time; use <code>docker compose logs core</code> for the
|
|
corresponding service log.</p>
|
|
<p>The contract gives exact validation, exit code, and JSON rules in
|
|
<a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/workspace-preprocessing-cli.md">Workspace preprocessing CLI</a>. For Evidence source
|
|
forms and the schema-v4 descriptor contract, see
|
|
<a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/workspace-evidence-v3.md">Workspace Evidence v3</a>.</p>
|
|
<h2 id="transport-and-revision-rules">Transport and revision rules<a class="headerlink" href="#transport-and-revision-rules" title="Permanent link">¶</a></h2>
|
|
<p>Runtime sessions support direct PostgreSQL and REST bindings. SSH tunnel bindings are diagnostic
|
|
only for this path, so they cannot admit an NL→SQL session. Database Management and <strong>Test
|
|
workspace connections</strong> share the current database binding, including its strict known-host SSH
|
|
path; the remaining workspace diagnostics cover Evidence and installation semantic services.</p>
|
|
<p>Every new session pins the active Git revision. Snapshot cleanup retains revisions still
|
|
referenced by unarchived sessions. A later pull can prepare a future session but cannot alter a
|
|
resume.</p>
|
|
|
|
<br>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
|
|
|
|
<div class="wm-article-nav pull-right">
|
|
<a href="../database-management/" class="btn btn-xs btn-default pull-right">
|
|
Next
|
|
<i class="fa fa-chevron-right" aria-hidden="true"></i>
|
|
</a>
|
|
<a href="../database-management/" class="btn btn-xs btn-link">
|
|
Databases and descriptions
|
|
</a>
|
|
</div>
|
|
|
|
<div class="wm-article-nav">
|
|
<a href="../../general/pi-configuration/" class="btn btn-xs btn-default pull-left">
|
|
<i class="fa fa-chevron-left" aria-hidden="true"></i>
|
|
Previous</a><a href="../../general/pi-configuration/" class="btn btn-xs btn-link">
|
|
Model configuration
|
|
</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> |