Blame for data/docs/deployment.html

<h2>Local (supported)</h2>
<p>Artifex is designed to run locally. After the pipeline has been run (see README.md):</p>
<pre><code class="language-bash">streamlit run app/main.py
</code></pre>
<p>The app listens on <a href="http://localhost:8501">http://localhost:8501</a>. Settings in <code>.streamlit/config.toml</code>:</p>
<ul>
<li><code>browser.gatherUsageStats = false</code> — Streamlit's usage telemetry is disabled.</li>
<li><code>server.maxUploadSize = 20</code> — upload limit in MB (the analyser also enforces <code>configs/preprocessing.yaml</code>).</li>
<li><code>client.showErrorDetails = false</code> — tracebacks (which can contain local paths) are not shown to visitors.</li>
</ul>
<h3>Resource requirements</h3>
<table>
<thead>
<tr>
<th>Resource</th>
<th>Requirement</th>
</tr>
</thead>
<tbody>
<tr>
<td>Python</td>
<td>3.10–3.12 (developed on 3.12)</td>
</tr>
<tr>
<td>RAM</td>
<td>≈1.1 GB resident for the analyser on CPU (DINOv2-B + reference index), measured on the development machine with an earlier 5,000-record index; the 10,084-record index adds ≈ 60 MB of embeddings; allow 2 GB for the app as a whole</td>
</tr>
<tr>
<td>GPU</td>
<td>optional; CUDA is used automatically if available. Measured on the development machine (AMD Ryzen 7 5800HS, CPU only): ≈0.2 s per analysis after a ≈10 s one-time model load. Embedding extraction for the whole collection: ≈25–40 s on an RTX 3050 Laptop GPU (4 GB).</td>
</tr>
<tr>
<td>Disk</td>
<td>~0.4 GB model cache (<code>models/hf</code>), plus downloaded images and thumbnails (see the dataset card for the current size)</td>
</tr>
</tbody>
</table>
<h3>Upload handling</h3>
<p>Streamlit keeps uploaded files in memory (its upload manager does not write them to disk). Artifex decodes the bytes
in memory, never saves them, and holds at most the current analysis result in the user's session; closing the tab or
pressing <em>Remove image</em> discards it. No cached uploads exist, so there is nothing to purge. If a future version caches
uploads, it must provide a purge command and document it here.</p>
<h2>In-browser edition (static website)</h2>
<p><strong>Deployed:</strong> <a href="https://sucksome-artifex.static.hf.space">https://sucksome-artifex.static.hf.space</a> (Hugging Face Space
<a href="https://huggingface.co/spaces/SuckSome/artifex"><code>SuckSome/artifex</code></a>, static SDK, public), 22 October 2026, model
<code>artifex-0.1-e94d93bf34</code>, dataset <code>0.1+5cc3c8d20c19</code> (redeployed the same day after the grouping correction). Verified after each upload: the isolation headers are served, the large
files (redirected to Hugging Face's CDN) arrive with CORS headers, every page loads without script errors at 1440 px and
390 px in headless Chromium, and a held-out test image analysed on the live site gave the same region, period, tradition
and abstention results as the Python application.</p>
<p><em>Content blockers.</em> The first upload named the analysis page module <code>analyse.js</code>; EasyPrivacy (used by Opera's built-in
blocker, uBlock Origin and others) blocks any file of that name, so the Analyse page failed in those browsers while
passing in a plain headless browser. The module is now <code>workspace.js</code>, a test keeps site file names clear of common
blocklist names, and the deployed site was re-checked in headless Chromium with all EasyList and EasyPrivacy rules that
apply to first-party resources enforced (nothing blocked; analysis completed).</p>
<p>The hosted edition is a static website that runs the deployed model <strong>in the visitor's browser</strong>. There is no Artifex
server: uploads are decoded and analysed on the visitor's device and never transmitted. It can be hosted anywhere that
serves static files, including free static Hugging Face Spaces. (Hugging Face requires a paid plan for Docker Spaces; see
the next section for the server-side alternative.)</p>
<pre><code class="language-bash">python scripts/export_browser_model.py   # ONNX export of the encoder + comparison of weight formats (build/browser_model/)
python scripts/build_static_site.py      # site in build/static/ (web/ + exported data + vendored libraries + thumbnails)
python scripts/validate_browser.py       # end-to-end comparison with the Python application (headless Chromium)
python scripts/build_static_site.py --no-thumbnails   # include the comparison result in the site
python scripts/serve_static.py           # local preview at http://localhost:8600
</code></pre>
<p>What the site contains (≈ 490 MB):</p>
<table>
<thead>
<tr>
<th>Part</th>
<th>Source</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>model/dinov2b_fp16w.onnx</code> (≈ 174 MB)</td>
<td><code>export_browser_model.py</code></td>
<td>DINOv2-B at the pinned commit, CLS + mean-patch pooling and L2 normalisation inside the graph; weights stored in float16, cast to float32 when the session is created. Downloaded on the first analysis and kept in the browser's Cache Storage.</td>
</tr>
<tr>
<td><code>data/embeddings.f16</code> (≈ 31 MB)</td>
<td>deployed embeddings</td>
<td>Reference embeddings in float16.</td>
</tr>
<tr>
<td><code>data/model.json</code></td>
<td><code>heads.pkl</code>, <code>model_card.json</code></td>
<td>Scaler means/scales, logistic-regression coefficients, temperatures, abstention thresholds, OOD threshold, test recall of the evaluated model.</td>
</tr>
<tr>
<td><code>data/records.json</code>, <code>vocab.json</code></td>
<td>manifest, splits, configs</td>
<td>Metadata shown on the site, in embedding order.</td>
</tr>
<tr>
<td><code>data/run/</code></td>
<td>latest evaluation run</td>
<td><code>metrics.json</code>, <code>failures.json</code>, <code>report.md</code>, <code>predictions.csv</code>, copied verbatim.</td>
</tr>
<tr>
<td><code>thumbnails/</code> (≈ 270 MB)</td>
<td>CC0 thumbnails</td>
<td>384-px copies; record views link to the museum for full images.</td>
</tr>
<tr>
<td><code>vendor/</code></td>
<td>npm <code>onnxruntime-web@1.30.0</code>, <code>plotly.js-cartesian-dist-min@4.1.1</code></td>
<td>Served from the site itself; the page requests nothing from third parties (on Hugging Face, large files are delivered through Hugging Face's own CDN).</td>
</tr>
</tbody>
</table>
<p><strong>Measured fidelity.</strong> Weight formats, compared on 300 held-out test images with the stored reference embeddings:
float32 and float16-stored weights both give cosine ≥ 0.99997 and identical region and period predictions for every
image; dynamic int8 quantisation (92 MB) destroys the representation (median cosine 0.13, 7 % region agreement) and is
not used. End to end (<code>validate_browser.py</code>, 200 held-out test images, headless Chromium): the preprocessed model input
is identical to Python's for every image (the JavaScript resize is a port of Pillow's fixed-point bicubic resampler), and
region and period predictions, abstention decisions and result status agree for every image; the top-5 similar works
agreed exactly for 99–100 % of images in the two builds measured (an ordering difference between near-tied works can
come from the float16 reference embeddings). The exact
figures of the deployed build are shown on the site's Methodology page (<code>data/browser_validation.json</code>).</p>
<p><strong>Requirements.</strong> A browser with WebAssembly (all current browsers). The first analysis downloads ≈ 205 MB. ONNX Runtime holds the
encoder weights in float32 (≈ 350 MB) plus activations, which may not fit on phones with little memory — the page then
shows an error and no result. With the <code>cross-origin-*</code> headers set in the Space configuration, the page is cross-origin isolated and ONNX
Runtime uses up to 4 threads; inside the Hugging Face page frame it falls back to one thread (slower, same results).</p>
<h2>Server-side alternative: Docker (Hugging Face paid tier or any container host)</h2>
<p><code>scripts/prepare_space.py</code> assembles a Docker bundle of the Streamlit application in <code>build/space/</code>. Hugging Face
refused to create a Docker Space on a free account ("requires a PRO subscription", October 2026), so this route is
prepared and tested locally but not deployed:</p>
<ul>
<li>code (<code>src/</code>, <code>app/</code>, <code>configs/</code>, <code>.streamlit/</code>), docs and screenshots;</li>
<li>the artefacts the website reads: manifest, splits, default-variant embeddings, deployed classifiers, the latest
  evaluation run (≈ 65 MB);</li>
<li>the CC0 thumbnails of all usable records, zipped (≈ 250 MB) and unpacked when the image is built. Full-size images, raw
  API responses, ablation embeddings and the model cache are <strong>not</strong> included; record detail views fall back to the
  384-px thumbnail;</li>
<li>a <code>Dockerfile</code> (Python 3.12, CPU-only PyTorch, exact package versions of the development environment because the
  classifiers are pickled scikit-learn objects) that downloads the pinned DINOv2 checkpoint at build time and then sets
  <code>HF_HUB_OFFLINE=1</code>, so the running app makes no calls to the Hub;</li>
<li>a <code>README.md</code> with the Space metadata followed by this project's README.</li>
</ul>
<pre><code class="language-bash">python scripts/prepare_space.py --source-url https://huggingface.co/spaces/&lt;user&gt;/artifex/tree/main
hf auth login                      # write token
hf upload &lt;user&gt;/artifex build/space . --repo-type space
</code></pre>
<p>Hosted-mode settings (environment variables in the Dockerfile):</p>
<table>
<thead>
<tr>
<th>Variable</th>
<th>Effect</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>ARTIFEX_HOST</code></td>
<td>Privacy statements say uploads are analysed "on the server hosting this site (…)" instead of "on this machine"; the About page adds a note on the host's network path.</td>
</tr>
<tr>
<td><code>ARTIFEX_SOURCE_URL</code></td>
<td>Footer links to the published source.</td>
</tr>
<tr>
<td><code>ARTIFEX_ROOT</code></td>
<td>Project root inside the container.</td>
</tr>
</tbody>
</table>
<p>The container binds <code>0.0.0.0:7860</code> (the local default stays <code>localhost</code>) and runs with
<code>--server.enableXsrfProtection=false</code>: Streamlit's XSRF cookie is blocked inside the Hugging Face iframe, which breaks
uploads. Artifex has no accounts or stored state for a forged request to act on.</p>
<p>Before publishing the bundle was tested by unpacking it, running it with the hosted settings on CPU only
(<code>CUDA_VISIBLE_DEVICES=""</code>, <code>HF_HUB_OFFLINE=1</code>) and analysing a test image: scores matched the GPU run to two decimals.</p>
<h3>Checklist for any other host</h3>
<ol>
<li><strong>Host capacity.</strong> DINOv2-B needs ≈ 1.5 GB RAM with PyTorch, plus the reference index; Streamlit Community Cloud's
   ≈ 1 GB limit is not enough. DINOv2-S (<code>dinov2s_letterbox_rgb</code>) is a smaller fallback, but the deployed model must
   then be retrained and re-evaluated for it.</li>
<li><strong>Model download.</strong> Confirm the host permits downloading from the Hugging Face Hub, or bundle the pinned checkpoint.</li>
<li><strong>Images.</strong> All reference images are CC0 and may be redistributed; do not commit them to Git.</li>
<li><strong>Privacy.</strong> Review the host's request logging and temporary-file behaviour so that uploads are not persisted. Serve
   over HTTPS.</li>
<li><strong>Abuse limits.</strong> Keep the upload size and pixel limits; consider rate limiting at the proxy.</li>
<li><strong>Unavailable state.</strong> If the host cannot run inference, the analysis page shows a "model or dataset unavailable"
   state — never substitute precomputed or fake predictions.</li>
</ol>
<p>No API keys or secrets are needed for any part of Artifex at runtime; publishing a Space needs the publisher's own
Hugging Face write token, which stays on their machine.</p>