315 lines
21 KiB
HTML
315 lines
21 KiB
HTML
<!DOCTYPE html>
|
|
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<meta content="IE=edge" http-equiv="X-UA-Compatible"/>
|
|
<meta content="width=device-width, initial-scale=1.0" name="viewport"/>
|
|
<link href="https://git.tylconsulting.it/thothii-docs/evidence/" rel="canonical"/>
|
|
<link href="../img/favicon.ico" rel="shortcut icon"/>
|
|
<meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport"/>
|
|
<title>Evidence - 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 href="../css/highlight.css" rel="stylesheet"/>
|
|
<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: "Evidence: sources, preparation, and review", url: "#_top", children: [
|
|
{title: "Editable local Evidence", url: "#editable-local-evidence" },
|
|
{title: "Existing repository publication path", url: "#existing-repository-publication-path" },
|
|
{title: "Where the original source belongs", url: "#where-the-original-source-belongs" },
|
|
{title: "What an editable curated unit contains", url: "#what-an-editable-curated-unit-contains" },
|
|
{title: "Legacy v3 representation", url: "#legacy-v3-representation" },
|
|
{title: "Preparation: from source to active generation", url: "#preparation-from-source-to-active-generation" },
|
|
{title: "Author responsibilities", url: "#author-responsibilities" },
|
|
{title: "Reviewer responsibilities", url: "#reviewer-responsibilities" },
|
|
{title: "Available commands", url: "#available-commands" },
|
|
{title: "Formulas and session proposals", url: "#formulas-and-session-proposals" },
|
|
{title: "Contract references", url: "#contract-references" },
|
|
]},
|
|
];
|
|
|
|
</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 aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
|
|
<div class="wm-article-nav pull-right">
|
|
<a class="btn btn-xs btn-default pull-right" href="../usage/memory/">
|
|
Next
|
|
<i aria-hidden="true" class="fa fa-chevron-right"></i>
|
|
</a>
|
|
<a class="btn btn-xs btn-link" href="../usage/memory/">
|
|
Memory
|
|
</a>
|
|
</div>
|
|
<div class="wm-article-nav">
|
|
<a class="btn btn-xs btn-default pull-left" href="../operations/sensitivity-analysis/">
|
|
<i aria-hidden="true" class="fa fa-chevron-left"></i>
|
|
Previous</a><a class="btn btn-xs btn-link" href="../operations/sensitivity-analysis/">
|
|
Sensitive columns
|
|
</a>
|
|
</div>
|
|
</div>
|
|
<h1 id="evidence-sources-preparation-and-review">Evidence: sources, preparation, and review<a class="headerlink" href="#evidence-sources-preparation-and-review" title="Permanent link">¶</a></h1>
|
|
<p>This page describes the complete workspace Evidence lifecycle: where original material lives, how curated units are produced, when they become available at runtime, and what the author and reviewer are responsible for.</p>
|
|
<h2 id="editable-local-evidence">Editable local Evidence<a class="headerlink" href="#editable-local-evidence" title="Permanent link">¶</a></h2>
|
|
<p>E1 adds <a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/curated-evidence-v4.md">Curated Evidence v4 and a persistent local archive</a>.
|
|
The visible title and payload fields are authoritative Markdown. New manual units need no
|
|
external source; consolidation records their curator and distinguishes later corrections
|
|
from original documentary provenance. The core archive API creates immutable candidates
|
|
and advances its active pointer only after successful indexing.</p>
|
|
<p>E2 adds <strong>Administration → Evidence management</strong>, actual host file paths, complete
|
|
browsing and filtering, and the installed <code>tht workspace evidence consolidate
|
|
--workspace <id></code> command. Edit files externally, consolidate to activate them, then
|
|
review and run Git manually. Runtime consumes only the active local snapshot.
|
|
The <a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/curated-evidence-v4.md#administration-and-installed-command">v4 contract</a>
|
|
describes host mounting, first conversion, failure recovery and Clear behavior.
|
|
The local PSD preview has 35 converted and indexed units. E3 adds explicit import/refresh
|
|
from local drafts and configured HTTP/S3 sources, durable current/proposed comparisons,
|
|
and keep/replace decisions with activation and retry. See
|
|
<a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/curated-evidence-v4.md#import-drafts-and-refresh-sources">Import drafts and refresh sources</a>.
|
|
Workflow gate corrections remain the subsequent shared increment, X1.</p>
|
|
<h2 id="existing-repository-publication-path">Existing repository publication path<a class="headerlink" href="#existing-repository-publication-path" title="Permanent link">¶</a></h2>
|
|
<p>The remainder describes the legacy, uninitialized repository source path. Initialized
|
|
v4 local archives use the lifecycle above; manual declarations need no source document.</p>
|
|
<p>The workspace repository is the versioned source. ThothII reads it, validates it, and publishes an atomic generation. It does not modify, commit, or push the author's repository.</p>
|
|
<p>Evidence becomes available to the workflow only when:</p>
|
|
<ol>
|
|
<li>the original material is in <code>source/</code>;</li>
|
|
<li>the derived unit is in <code>curated/</code>;</li>
|
|
<li>the manifest links the unit, source, and hash;</li>
|
|
<li>validation finds no errors or unresolved review items;</li>
|
|
<li>preprocessing builds and activates an indexed generation.</li>
|
|
</ol>
|
|
<p>A proposal generated during a session is not automatically published Evidence. The model may propose a formula or explanation, but a curator must import, review, and publish it in the repository before another session can retrieve it.</p>
|
|
<h2 id="where-the-original-source-belongs">Where the original source belongs<a class="headerlink" href="#where-the-original-source-belongs" title="Permanent link">¶</a></h2>
|
|
<p>For filesystem Evidence v2, the authoritative original source must be in the <code>source/</code> directory of the workspace repository. <code>curated/</code> contains the reviewed and indexed result, not the original material.</p>
|
|
<pre class="highlight"><code class="language-text"><workspace-repository>/
|
|
├── source/ # materiale originale, preservato
|
|
│ └── <domain>/<file>.md
|
|
├── curated/ # reviewed Evidence Units
|
|
│ └── <domain>/<unit>.md
|
|
├── manifest.yaml # preparation links, hashes, and metadata
|
|
└── example/ # examples and supporting material</code></pre>
|
|
<p>The workspace descriptor must declare <code>evidence.schema_version: 2</code> and use exactly this configuration for a filesystem source:</p>
|
|
<pre class="highlight"><code class="language-yaml">evidence:
|
|
schema_version: 2
|
|
source:
|
|
type: filesystem
|
|
uri: "<workspace.id>/evidence"
|
|
patterns:
|
|
- "curated/**/*.md"</code></pre>
|
|
<p>The legacy configuration may expose <code>source_root</code>, such as <code>${THT_DOCS_ROOT}</code> or <code>/data</code>. For the v2 structure, the runtime pattern must select only <code>curated/**/*.md</code>. Do not index <code>source/</code> directly, mix <code>source/</code> and <code>curated/</code>, use broader globs, or include non-Markdown files.</p>
|
|
<p>HTTP and S3 are separate adapters. They do not use the filesystem structure <code>source/</code> and <code>curated/</code>, but they must still provide stable provenance, without credentials in URIs, under the adapter-specific contract.</p>
|
|
<h2 id="what-an-editable-curated-unit-contains">What an editable curated unit contains<a class="headerlink" href="#what-an-editable-curated-unit-contains" title="Permanent link">¶</a></h2>
|
|
<p>New preparation produces unit schema v4. The first H1 contains its title; documented H2
|
|
sections contain the typed payload. A minimal manual unit is:</p>
|
|
<pre class="highlight"><code class="language-markdown">---
|
|
schema_version: 4
|
|
id: evidence:order-key
|
|
kind: domain
|
|
language: en
|
|
purposes: [sql_generation]
|
|
---
|
|
|
|
# Order key
|
|
|
|
## Rule
|
|
|
|
Join orders using the order number, financial year and company.</code></pre>
|
|
<p>Use <code>tht evidence migrate <workspace-root></code> for deterministic legacy conversion. The
|
|
conversion preserves typed content and initializes an archive baseline; it does not
|
|
activate the local corpus. See the <a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/curated-evidence-v4.md">v4 contract</a> for
|
|
all eight kinds, provenance, file layout and the E1/E2 boundary.</p>
|
|
<h2 id="legacy-v3-representation">Legacy v3 representation<a class="headerlink" href="#legacy-v3-representation" title="Permanent link">¶</a></h2>
|
|
<p>Canonical Curated Evidence v3 hides canonical machine metadata in an HTML comment and renders the
|
|
whole review surface as real Markdown. GitHub therefore shows no frontmatter table. The body layout
|
|
is deterministic for each Evidence kind: prose uses sections and paragraphs, scopes and enum values
|
|
use wrapping lists, formulas use fenced SQL, supporting excerpts use blockquotes, and unresolved
|
|
review items use dedicated blocks. Long domain rules are split into readable paragraphs, labelled
|
|
subsections, and lists at existing semicolon boundaries. Their exact original text remains canonical
|
|
in an invisible marker, so the formatting cannot change their meaning or bytes.</p>
|
|
<p>Preprocessing parses the unit first and builds semantic chunks from the typed payload. The vector
|
|
store therefore receives the original rule text and not headings, list markers, or invisible
|
|
presentation metadata.</p>
|
|
<pre class="highlight"><code class="language-markdown"><!-- tht:metadata:<canonical metadata> -->
|
|
# Fascia pediatrica
|
|
|
|
> **Dominio** · Italiano
|
|
>
|
|
> **Scopi:** Disambiguazione
|
|
|
|
## Ambito di applicazione
|
|
|
|
### Concetti
|
|
|
|
- fascia pediatrica
|
|
|
|
## Regola
|
|
|
|
La fascia pediatrica comprende i pazienti con età inferiore a 18 anni.
|
|
|
|
## Estratti di supporto
|
|
|
|
> I pazienti sotto i 18 anni sono pediatrici.
|
|
|
|
<details>
|
|
<summary>Dettagli tecnici e provenienza</summary>
|
|
|
|
- **ID:** `evidence:fascia-pediatrica`
|
|
- **File sorgente:** `source/domain/paziente.md`
|
|
|
|
</details></code></pre>
|
|
<p>The actual files contain invisible <code>tht:</code> comments for canonical metadata and typed-field
|
|
boundaries. Removing, duplicating, or desynchronizing them makes validation fail closed instead of
|
|
silently ignoring content. Unit schemas v1 and v2 remain readable for compatibility, but newly
|
|
prepared units use v4. Unit v3 remains readable as a conversion input.</p>
|
|
<p>Curated units must be atomic, readable by a second reviewer, and supported by the source.
|
|
Provenance references must lead back to the original file and the passage that supports the claim.
|
|
Do not put secrets, tokens, passwords, or credentials in metadata or URIs.</p>
|
|
<p>The modern canonical form also stores the Evidence kind, provenance, supporting excerpts, <code>source_file</code>, and <code>source_sha256</code>. The canonical contract rejects unknown fields, mutable metadata, and URIs containing credentials. Identifiers must remain stable even when a unit's kind changes.</p>
|
|
<h2 id="preparation-from-source-to-active-generation">Preparation: from source to active generation<a class="headerlink" href="#preparation-from-source-to-active-generation" title="Permanent link">¶</a></h2>
|
|
<div class="mermaid">flowchart TD
|
|
SRC["source/DOMAIN/*.md\noriginal material"] --> PREP["tht evidence prepare\ncandidate preparation"]
|
|
PREP --> CAND["curated/DOMAIN/*.md\nproposed or updated units"]
|
|
CAND --> VAL["tht evidence validate\nstructure and link checks"]
|
|
VAL -->|errors or review items| FIX["Author corrections\nand review"]
|
|
FIX --> PREP
|
|
VAL -->|publishable| COMMIT["Commit del repository\nauthoring clone"]
|
|
COMMIT --> ING["tht workspace preprocess run\nnormalization and chunking"]
|
|
ING --> BM25["BM25 index"]
|
|
ING --> VEC["Embeddings and vector store"]
|
|
BM25 --> GEN["Candidate generation"]
|
|
VEC --> GEN
|
|
GEN --> ACT["Replace active Evidence slice"]
|
|
ACT --> RUNTIME["Evidence retrieval in the workflow"]
|
|
</div>
|
|
<p>Preparation can restructure changed sources, but it does not publish by itself. <code>prepare</code> produces a proposal and can identify the document involved in an error. <code>validate</code> does not write or publish. The curator publishes the revision. The complete workspace preprocessing command reads that exact revision and replaces the active Evidence slice. There is no application-level rollback; rerun complete preprocessing after correcting a failure.</p>
|
|
<p>Runtime retrieval is hybrid. The dense branch uses embeddings, the BM25 branch uses lexical search,
|
|
and deterministic fusion orders the results. Evidence fragments live in the workspace <code>reference</code>
|
|
collection together with Schema and relationships; runtime Memory and solved questions live in a
|
|
separate <code>memory</code> collection. The published unit keeps its provenance, which the model must cite when
|
|
it uses the Evidence.</p>
|
|
<h2 id="author-responsibilities">Author responsibilities<a class="headerlink" href="#author-responsibilities" title="Permanent link">¶</a></h2>
|
|
<p>The author prepares the material and makes every unit verifiable. The author must:</p>
|
|
<ul>
|
|
<li>put the original material in <code>source/</code> without changing its meaning during curation;</li>
|
|
<li>split the content into atomic units, with one rule or definition per unit when possible;</li>
|
|
<li>assign a stable identifier and a clear title;</li>
|
|
<li>provide provenance, tables, and related concepts when known;</li>
|
|
<li>keep the text in the workspace language;</li>
|
|
<li>separate facts, rules, examples, formulas, and limits;</li>
|
|
<li>include excerpts that support the unit without extending the conclusion beyond the source;</li>
|
|
<li>run <code>tht evidence prepare</code> and <code>tht evidence validate</code>;</li>
|
|
<li>resolve every error and review item before proposing a commit;</li>
|
|
<li>give the reviewer the necessary context, including source changes and the reason for any rename or retirement.</li>
|
|
</ul>
|
|
<p>The author must not:</p>
|
|
<ul>
|
|
<li>write directly to the active production corpus;</li>
|
|
<li>treat a model proposal as a verified fact;</li>
|
|
<li>delete an unsupported unit without recording its retirement or relink;</li>
|
|
<li>put credentials in metadata, files, or provenance URLs;</li>
|
|
<li>manually change manifests, hashes, or generations to make validation pass.</li>
|
|
</ul>
|
|
<h2 id="reviewer-responsibilities">Reviewer responsibilities<a class="headerlink" href="#reviewer-responsibilities" title="Permanent link">¶</a></h2>
|
|
<p>The reviewer does not approve text merely because it is clear. The reviewer checks the relationship between source, unit, and intended use. For each unit, the reviewer must check:</p>
|
|
<ol>
|
|
<li>the cited source exists in the reviewed revision;</li>
|
|
<li>the excerpt actually supports the claim;</li>
|
|
<li>the unit does not combine incompatible rules or independent concepts;</li>
|
|
<li>tables, columns, and concepts are identified correctly;</li>
|
|
<li>the identifier is stable and does not duplicate another unit;</li>
|
|
<li>the text distinguishes the definition, condition, exception, and example;</li>
|
|
<li>it contains no sensitive information or details absent from the source;</li>
|
|
<li>retrieval evaluation covers relevant queries and does not hide empty results.</li>
|
|
</ol>
|
|
<p>The reviewer can approve, request changes, reject, retire, or relink a unit to a new source. Retirement must be explicit. A relink must name the new file and leave a verifiable record of the decision. Approval does not publish immediately: the repository must pass validation and the generation must pass evaluation before activation.</p>
|
|
<h2 id="available-commands">Available commands<a class="headerlink" href="#available-commands" title="Permanent link">¶</a></h2>
|
|
<p>Authoring commands operate on the workspace repository and do not publish directly.</p>
|
|
<pre class="highlight"><code class="language-bash"># Prepare changed sources. Does not commit or publish.
|
|
tht evidence prepare <workspace-root>
|
|
|
|
# Reprocess all sources with the installed pipeline.
|
|
tht evidence prepare <workspace-root> --upgrade
|
|
|
|
# Rewrite legacy v1/v2 units as table-free v3 Markdown without model calls.
|
|
tht evidence migrate <workspace-root>
|
|
|
|
# Validate structure, manifest, links, and review items.
|
|
tht evidence validate <workspace-root>
|
|
|
|
# Return JSON for CI or automated tools.
|
|
tht evidence validate <workspace-root> --json
|
|
|
|
# Evaluate retrieval on a generation or the active generation.
|
|
tht evidence evaluate <workspace-root> --config <workspace-config>
|
|
tht evidence evaluate <workspace-root> --config <workspace-config> --generation <id> --json
|
|
|
|
# Resolve a unit without publishing: retire it or link it to a new source.
|
|
tht evidence resolve <workspace-root> evidence:<id> --retire
|
|
tht evidence resolve <workspace-root> evidence:<id> --source source/domain/nuovo.md
|
|
|
|
# Materialize Catalog-derived schema/LSH and the revision-pinned Evidence in one run.
|
|
tht --installation <absolute>/thothii-installation.yaml \
|
|
workspace preprocess run --workspace <workspace-id></code></pre>
|
|
<p><code>evidence prepare</code>, <code>evidence migrate</code>, <code>evidence validate</code>, and <code>evidence resolve</code> are authoring
|
|
operations and require the repository path. Runtime publication is available only through the
|
|
complete host-side <code>workspace preprocess run</code>; there is no public Evidence-only preprocessing
|
|
command.</p>
|
|
<p>Exit codes are part of the operating contract: <code>evidence validate</code> returns <code>0</code> when the corpus is publishable, <code>1</code> for validation errors, and <code>3</code> when only review items or orphaned units remain. With <code>--json</code>, stdout must contain valid JSON only.</p>
|
|
<h2 id="formulas-and-session-proposals">Formulas and session proposals<a class="headerlink" href="#formulas-and-session-proposals" title="Permanent link">¶</a></h2>
|
|
<p>Formulas use a format distinct from document Evidence. A formula proposed during a session may be cited in the current proposal, but it does not enter the runtime corpus, receive a usable <code>evidence:</code> ID, or write to the repository. To become published, it must follow the same import, review, and preprocessing path as other units.</p>
|
|
<h2 id="contract-references">Contract references<a class="headerlink" href="#contract-references" title="Permanent link">¶</a></h2>
|
|
<ul>
|
|
<li><a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/workspace-evidence-v3.md">Workspace Evidence v3 contract</a></li>
|
|
<li><a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/contracts/workspace-preprocessing-cli.md">Preprocessing CLI contract</a></li>
|
|
</ul>
|
|
<br/>
|
|
<div aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
|
|
<div class="wm-article-nav pull-right">
|
|
<a class="btn btn-xs btn-default pull-right" href="../usage/memory/">
|
|
Next
|
|
<i aria-hidden="true" class="fa fa-chevron-right"></i>
|
|
</a>
|
|
<a class="btn btn-xs btn-link" href="../usage/memory/">
|
|
Memory
|
|
</a>
|
|
</div>
|
|
<div class="wm-article-nav">
|
|
<a class="btn btn-xs btn-default pull-left" href="../operations/sensitivity-analysis/">
|
|
<i aria-hidden="true" class="fa fa-chevron-left"></i>
|
|
Previous</a><a class="btn btn-xs btn-link" href="../operations/sensitivity-analysis/">
|
|
Sensitive columns
|
|
</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>
|
|
<script type="module">import mermaid from "https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs";
|
|
mermaid.initialize({});</script></body>
|
|
</html> |