Remove .gitattributes and README copy files; enhance app.py for HuggingFace Spaces compatibility and session cookie handling in proxy environments. Update Dockerfile for improved deployment instructions and user permissions.

.gitattributes copy

@@ -1,2 +0,0 @@
-# Auto detect text files and perform LF normalization
-* text=auto

Dockerfile

@@ -1,49 +1,80 @@
-# ── Scripture Detector ────────────────────────────────────────────────────────
+# ── Scripture Detector — HuggingFace Spaces compatible Dockerfile ─────────────
 #
-# Build:
-#   docker build -t scripture-detector .
+# Usage on HuggingFace Spaces
+# ───────────────────────────
+# 1. Push this repo to a HF Space (Docker SDK).
+# 2. Add the following secrets in Space Settings → Variables and secrets:
+#      SD_SECRET_KEY   →  any long random string, e.g. `openssl rand -hex 32`
+#      GEMINI_API_KEY  →  your Google AI Studio key (optional; can be set in-app)
 #
-# Run (ephemeral in-memory database — data resets on container restart):
-#   docker run -p 5001:5001 scripture-detector
+# Local usage (standard)
+# ──────────────────────
+#   docker build -t scripture-detector .
+#   docker run -p 7860:7860 scripture-detector
 #
-# Run (persistent database — mount a host directory):
-#   docker run -p 5001:5001 \
-#     -v "$(pwd)/data_volume:/app/db" \
+# Local usage with a persistent database (mount a host directory)
+# ───────────────────────────────────────────────────────────────
+#   docker run -p 7860:7860 \
+#     -v "$(pwd)/db_volume:/app/db" \
 #     -e SD_DB_DIR=/app/db \
-#     -e GEMINI_API_KEY=your_key_here \
-#     scripture-detector python app.py
-#
-# The default CMD uses --cache-db (in-memory SQLite) which is ideal for
-# workshops and demos where persistence across restarts is not needed.
+#     -e SCRIPTURE_DETECTOR_CACHE_DB=0 \
+#     scripture-detector
 # ─────────────────────────────────────────────────────────────────────────────
 
 FROM python:3.12-slim
 
-# Install git (required by Hugging Face Spaces build system) and uv
-RUN apt-get update && apt-get install -y --no-install-recommends git \
+# ── System dependencies ───────────────────────────────────────────────────────
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git curl \
     && rm -rf /var/lib/apt/lists/*
-RUN pip install --no-cache-dir uv
 
+# ── Non-root user (required by HuggingFace Spaces) ───────────────────────────
+RUN useradd -m -u 1000 user
 WORKDIR /app
 
+# ── Install uv (fast Python package manager) ─────────────────────────────────
+RUN pip install --no-cache-dir uv
 
-# Copy dependency manifest first to leverage Docker layer caching.
-# Dependencies are only re-installed when pyproject.toml / uv.lock changes.
-COPY pyproject.toml uv.lock* ./
-
-# Sync dependencies (no dev extras)
+# ── Dependencies (cached layer — only re-runs when pyproject.toml changes) ───
+COPY --chown=user:user pyproject.toml uv.lock* ./
 RUN uv sync --no-dev --frozen || uv sync --no-dev
 
-# Copy application source
-COPY . .
+# ── Application source ────────────────────────────────────────────────────────
+COPY --chown=user:user . .
 
-# Bind to all interfaces inside the container
+# ── Runtime environment ───────────────────────────────────────────────────────
+# Per-user in-memory database (each browser session gets its own isolated DB).
+ENV SCRIPTURE_DETECTOR_CACHE_DB=1
+
+# Tell Flask/app.py to configure SameSite=None; Secure cookies so they work
+# inside HuggingFace's iframe embedding.
+ENV SD_BEHIND_PROXY=1
+
+# Bind to all interfaces; HF Spaces expects port 7860.
 ENV SD_HOST=0.0.0.0
 ENV SD_PORT=7860
 
-# Expose the Flask port
+# SD_SECRET_KEY should be set as a HF Space Secret (not hardcoded here).
+# If absent, a random key is generated at startup — sessions reset on redeploy.
+
+# Gunicorn needs to see the app module
+ENV PYTHONUNBUFFERED=1
+
+# ── Non-root user ─────────────────────────────────────────────────────────────
+USER user
+
 EXPOSE 7860
 
-# Default: run with --cache-db (in-memory database, no volume needed).
-# To use a persistent database instead, override CMD and set SD_DB_DIR.
-CMD ["uv", "run", "python", "app.py", "--cache-db"]
+# ── Start gunicorn ──────────────────────────────────��─────────────────────────
+# Single worker: the per-session in-memory databases live in one process.
+# More than one worker would mean different workers have different session stores,
+# causing "I added a source but now it's gone" bugs.
+CMD ["uv", "run", "gunicorn", \
+     "--worker-class", "gthread", \
+     "--workers", "1", \
+     "--threads", "4", \
+     "--bind", "0.0.0.0:7860", \
+     "--timeout", "120", \
+     "--access-logfile", "-", \
+     "--error-logfile", "-", \
+     "app:app"]

README copy.md

@@ -1,180 +0,0 @@
-# Scripture Detector
-
-> **AI-powered detection and analysis of biblical quotations, paraphrases, and allusions in historical texts.**
-
-![Sources page](static/screenshots/sources.png)
-
-Developed by **Dr. William J.B. Mattingly**, Cultural Heritage Data Scientist at Yale University.
-
-Built for the international workshop **[Ruse of Reuse: Detecting Text-similarity with AI in Historical Sources](https://www.oeaw.ac.at/en/imafo/events/event-details/ruse-of-reuse)** — held **March 5–6, 2026** at the Austrian Academy of Sciences, Vienna.
-
----
-
-## Overview
-
-Scripture Detector is a local web application that uses Google Gemini to automatically find, classify, and annotate every biblical reference in any text you provide — from full verbatim quotations to subtle allusions. It renders an interactive, color-coded view of the source text with side-by-side Bible verse lookup, distribution charts, and a manual annotation editor.
-
-**The only external dependency is a free Gemini API key** from [Google AI Studio](https://aistudio.google.com/apikey). No cloud account, credit card, or additional infrastructure is required.
-
----
-
-## Screenshots
-
-### Sources Page — with Advanced Search
-Manage all your text sources. Use the search bar to search source content in real time, or open the **Advanced** panel to stack filters by Bible book, chapter, or verse with AND / OR logic. Match evidence appears directly on each result card.
-
-![Sources page](static/screenshots/sources.png)
-
-### Text Viewer
-Color-coded annotations appear directly in the text. Click any highlighted passage to see the matched Bible verse(s) in the panel on the right.
-
-![Viewer page](static/screenshots/viewer.png)
-
-### Analytics Dashboard
-Explore scripture distribution across all sources — broken down by Bible book, testament, and quote type.
-
-![Dashboard](static/screenshots/dashboard.png)
-
-### Settings
-Configure your Gemini API key or Google Vertex AI credentials, and select which Gemini model to use.
-
-![Settings page](static/screenshots/settings.png)
-
-### About Page
-Full documentation of the application, its features, and how it works.
-
-![About page](static/screenshots/about.png)
-
----
-
-## Features
-
-- **Full-document AI analysis** — send any text to Gemini and receive a structured list of every scripture reference with verse citations and classification types.
-- **Four classification types**: Full, Partial, Paraphrase, and Allusion.
-- **Color-coded in-text highlighting** — each type is rendered in a distinct color directly within the source text.
-- **Click-to-explore interactivity** — click a highlighted passage to highlight the corresponding annotation card, and vice versa.
-- **Selection-based re-analysis** — highlight any portion of the text to re-run AI detection on just that selection.
-- **Manual annotation editor** with an integrated Bible verse picker (book → chapter → verse).
-- **Advanced search** — real-time multi-filter search across all sources by text content, Bible book, chapter, or verse; filters stack with AND / OR logic and matched evidence appears inline on each result card.
-- **Distribution charts** per source and across all sources (by Bible book, testament, and type).
-- **Global analytics dashboard** aggregating data across all sources.
-- **Model switching** — choose between available Gemini model versions in the UI.
-- **Runs entirely locally** — your texts are never transmitted anywhere except for the Gemini API call itself.
-
----
-
-## Advanced Search
-
-The Sources page includes a real-time multi-filter search system:
-
-| Filter Type | What it matches |
-|---|---|
-| **Text Content** | Any source whose full text contains the search string |
-| **Bible Book** | Any source with at least one reference to the chosen book |
-| **Chapter** | Any source with a reference to the chosen chapter (e.g. Psalms 23) |
-| **Verse** | Any source with a reference to the exact chosen verse (e.g. John 3:16) |
-
-Filters can be stacked in any combination. The **AND** mode requires a source to satisfy *every* filter; **OR** mode returns sources satisfying *any* filter. Results update within ~350 ms of each keystroke or dropdown change. Matched text snippets and verse citations appear as inline evidence on each result card.
-
----
-
-## Quick Start
-
-### 1. Prerequisites
-
-- Python 3.10+
-- [uv](https://docs.astral.sh/uv/) (recommended) or pip
-- A free **Gemini API key** from [Google AI Studio](https://aistudio.google.com/apikey)
-
-### 2. Install & Run
-
-```bash
-git clone <repo-url>
-cd scripture-detector
-
-# Using uv (recommended)
-uv run python app.py
-
-# Or using pip
-pip install -e .
-python app.py
-```
-
-The app starts at **http://127.0.0.1:5001**.
-
-### 3. Configure API Key
-
-1. Open [http://127.0.0.1:5001/settings](http://127.0.0.1:5001/settings)
-2. Select **Gemini API** as the provider
-3. Paste your API key from [Google AI Studio](https://aistudio.google.com/apikey)
-4. Click **Save Settings**
-
-### 4. Analyze a Text
-
-1. Go to the **Sources** page and click **Add Source**
-2. Give your source a name and paste in the text to analyze
-3. Click **View** to open the text viewer
-4. Click **Process with AI** — Gemini will detect all scripture references within seconds
-5. Click any highlighted passage to explore the matched Bible verses
-
----
-
-## Quote Classification
-
-| Type | Description |
-|---|---|
-| **Full** | A complete or near-complete verse quoted verbatim |
-| **Partial** | A recognizable portion of a verse with minor variation or truncation |
-| **Paraphrase** | Biblical content restated in different words, preserving the meaning |
-| **Allusion** | A brief phrase, thematic echo, or indirect reference to a specific verse |
-
----
-
-## Project Structure
-
-```
-scripture-detector/
-├── app.py              # Flask application and API routes
-├── database.py         # SQLite database layer
-├── main.py             # CLI batch evaluation script
-├── data/
-│   ├── bible.tsv       # Full Bible verse database (35,000+ verses)
-│   └── book_mapping.tsv
-├── templates/
-│   ├── sources.html    # Sources listing page
-│   ├── viewer.html     # Annotated text viewer
-│   ├── dashboard.html  # Global analytics dashboard
-│   ├── settings.html   # API configuration
-│   └── about.html      # About / documentation page
-└── static/
-    ├── style.css        # Yale color palette stylesheet
-    ├── logo.svg         # Application logo
-    └── favicon.svg      # Browser tab icon
-```
-
----
-
-## API Providers
-
-### Gemini API (Free Tier)
-The simplest option. Get a free key at [Google AI Studio](https://aistudio.google.com/apikey) — no billing required. Select **Gemini API** in Settings and paste your key.
-
-### Google Vertex AI
-For enterprise use or higher rate limits. Requires a Google Cloud project with Vertex AI enabled. Select **Vertex AI** in Settings and enter your project ID and location.
-
----
-
-## About
-
-**Developer:** Dr. William J.B. Mattingly  
-**Affiliation:** Yale University, Cultural Heritage Data Scientist  
-**Workshop:** [Ruse of Reuse: Detecting Text-similarity with AI in Historical Sources](https://www.oeaw.ac.at/en/imafo/events/event-details/ruse-of-reuse)  
-**Workshop Dates:** March 5–6, 2026  
-**Workshop Venue:** Austrian Academy of Sciences, PSK Georg-Coch-Platz 2, 1010 Vienna  
-**Organisers:** Digital Lab, Institute for Medieval Research, Austrian Academy of Sciences & [SOLEMNE](https://canones.org/), Radboud University  
-
----
-
-## License
-
-MIT

README.md

@@ -1,10 +1,180 @@
+# Scripture Detector
+
+> **AI-powered detection and analysis of biblical quotations, paraphrases, and allusions in historical texts.**
+
+![Sources page](static/screenshots/sources.png)
+
+Developed by **Dr. William J.B. Mattingly**, Cultural Heritage Data Scientist at Yale University.
+
+Built for the international workshop **[Ruse of Reuse: Detecting Text-similarity with AI in Historical Sources](https://www.oeaw.ac.at/en/imafo/events/event-details/ruse-of-reuse)** — held **March 5–6, 2026** at the Austrian Academy of Sciences, Vienna.
+
+---
+
+## Overview
+
+Scripture Detector is a local web application that uses Google Gemini to automatically find, classify, and annotate every biblical reference in any text you provide — from full verbatim quotations to subtle allusions. It renders an interactive, color-coded view of the source text with side-by-side Bible verse lookup, distribution charts, and a manual annotation editor.
+
+**The only external dependency is a free Gemini API key** from [Google AI Studio](https://aistudio.google.com/apikey). No cloud account, credit card, or additional infrastructure is required.
+
+---
+
+## Screenshots
+
+### Sources Page — with Advanced Search
+Manage all your text sources. Use the search bar to search source content in real time, or open the **Advanced** panel to stack filters by Bible book, chapter, or verse with AND / OR logic. Match evidence appears directly on each result card.
+
+![Sources page](static/screenshots/sources.png)
+
+### Text Viewer
+Color-coded annotations appear directly in the text. Click any highlighted passage to see the matched Bible verse(s) in the panel on the right.
+
+![Viewer page](static/screenshots/viewer.png)
+
+### Analytics Dashboard
+Explore scripture distribution across all sources — broken down by Bible book, testament, and quote type.
+
+![Dashboard](static/screenshots/dashboard.png)
+
+### Settings
+Configure your Gemini API key or Google Vertex AI credentials, and select which Gemini model to use.
+
+![Settings page](static/screenshots/settings.png)
+
+### About Page
+Full documentation of the application, its features, and how it works.
+
+![About page](static/screenshots/about.png)
+
+---
+
+## Features
+
+- **Full-document AI analysis** — send any text to Gemini and receive a structured list of every scripture reference with verse citations and classification types.
+- **Four classification types**: Full, Partial, Paraphrase, and Allusion.
+- **Color-coded in-text highlighting** — each type is rendered in a distinct color directly within the source text.
+- **Click-to-explore interactivity** — click a highlighted passage to highlight the corresponding annotation card, and vice versa.
+- **Selection-based re-analysis** — highlight any portion of the text to re-run AI detection on just that selection.
+- **Manual annotation editor** with an integrated Bible verse picker (book → chapter → verse).
+- **Advanced search** — real-time multi-filter search across all sources by text content, Bible book, chapter, or verse; filters stack with AND / OR logic and matched evidence appears inline on each result card.
+- **Distribution charts** per source and across all sources (by Bible book, testament, and type).
+- **Global analytics dashboard** aggregating data across all sources.
+- **Model switching** — choose between available Gemini model versions in the UI.
+- **Runs entirely locally** — your texts are never transmitted anywhere except for the Gemini API call itself.
+
+---
+
+## Advanced Search
+
+The Sources page includes a real-time multi-filter search system:
+
+| Filter Type | What it matches |
+|---|---|
+| **Text Content** | Any source whose full text contains the search string |
+| **Bible Book** | Any source with at least one reference to the chosen book |
+| **Chapter** | Any source with a reference to the chosen chapter (e.g. Psalms 23) |
+| **Verse** | Any source with a reference to the exact chosen verse (e.g. John 3:16) |
+
+Filters can be stacked in any combination. The **AND** mode requires a source to satisfy *every* filter; **OR** mode returns sources satisfying *any* filter. Results update within ~350 ms of each keystroke or dropdown change. Matched text snippets and verse citations appear as inline evidence on each result card.
+
+---
+
+## Quick Start
+
+### 1. Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- A free **Gemini API key** from [Google AI Studio](https://aistudio.google.com/apikey)
+
+### 2. Install & Run
+
+```bash
+git clone <repo-url>
+cd scripture-detector
+
+# Using uv (recommended)
+uv run python app.py
+
+# Or using pip
+pip install -e .
+python app.py
+```
+
+The app starts at **http://127.0.0.1:5001**.
+
+### 3. Configure API Key
+
+1. Open [http://127.0.0.1:5001/settings](http://127.0.0.1:5001/settings)
+2. Select **Gemini API** as the provider
+3. Paste your API key from [Google AI Studio](https://aistudio.google.com/apikey)
+4. Click **Save Settings**
+
+### 4. Analyze a Text
+
+1. Go to the **Sources** page and click **Add Source**
+2. Give your source a name and paste in the text to analyze
+3. Click **View** to open the text viewer
+4. Click **Process with AI** — Gemini will detect all scripture references within seconds
+5. Click any highlighted passage to explore the matched Bible verses
+
+---
+
+## Quote Classification
+
+| Type | Description |
+|---|---|
+| **Full** | A complete or near-complete verse quoted verbatim |
+| **Partial** | A recognizable portion of a verse with minor variation or truncation |
+| **Paraphrase** | Biblical content restated in different words, preserving the meaning |
+| **Allusion** | A brief phrase, thematic echo, or indirect reference to a specific verse |
+
+---
+
+## Project Structure
+
+```
+scripture-detector/
+├── app.py              # Flask application and API routes
+├── database.py         # SQLite database layer
+├── main.py             # CLI batch evaluation script
+├── data/
+│   ├── bible.tsv       # Full Bible verse database (35,000+ verses)
+│   └── book_mapping.tsv
+├── templates/
+│   ├── sources.html    # Sources listing page
+│   ├── viewer.html     # Annotated text viewer
+│   ├── dashboard.html  # Global analytics dashboard
+│   ├── settings.html   # API configuration
+│   └── about.html      # About / documentation page
+└── static/
+    ├── style.css        # Yale color palette stylesheet
+    ├── logo.svg         # Application logo
+    └── favicon.svg      # Browser tab icon
+```
+
+---
+
+## API Providers
+
+### Gemini API (Free Tier)
+The simplest option. Get a free key at [Google AI Studio](https://aistudio.google.com/apikey) — no billing required. Select **Gemini API** in Settings and paste your key.
+
+### Google Vertex AI
+For enterprise use or higher rate limits. Requires a Google Cloud project with Vertex AI enabled. Select **Vertex AI** in Settings and enter your project ID and location.
+
 ---
-title: Scripture Detector
-emoji: 👀
-colorFrom: red
-colorTo: indigo
-sdk: docker
-pinned: false
+
+## About
+
+**Developer:** Dr. William J.B. Mattingly  
+**Affiliation:** Yale University, Cultural Heritage Data Scientist  
+**Workshop:** [Ruse of Reuse: Detecting Text-similarity with AI in Historical Sources](https://www.oeaw.ac.at/en/imafo/events/event-details/ruse-of-reuse)  
+**Workshop Dates:** March 5–6, 2026  
+**Workshop Venue:** Austrian Academy of Sciences, PSK Georg-Coch-Platz 2, 1010 Vienna  
+**Organisers:** Digital Lab, Institute for Medieval Research, Austrian Academy of Sciences & [SOLEMNE](https://canones.org/), Radboud University  
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## License
+
+MIT

app.py

@@ -2,10 +2,11 @@ import os
 import sys
 
 # ── parse custom flags BEFORE importing database (which reads env vars) ───────
+# The --cache-db CLI flag sets the env var so gunicorn deployments can instead
+# set SCRIPTURE_DETECTOR_CACHE_DB=1 in their environment directly.
 _argv = sys.argv[1:]
 if "--cache-db" in _argv:
     os.environ["SCRIPTURE_DETECTOR_CACHE_DB"] = "1"
-# Remove our custom flags so Flask/werkzeug doesn't choke on them
 sys.argv = [sys.argv[0]] + [a for a in _argv if a != "--cache-db"]
 
 import csv
@@ -18,6 +19,7 @@ from datetime import date
 from pathlib import Path
 
 from flask import Flask, render_template, jsonify, request, redirect, url_for, Response, session
+from werkzeug.middleware.proxy_fix import ProxyFix
 from google import genai
 
 import database   # imported as module so we can write to database.session_local
@@ -34,11 +36,30 @@ from tei import source_to_tei, tei_to_source_data
 
 app = Flask(__name__)
 
-# Flask sessions need a secret key for signing the session cookie.
-# In production set SD_SECRET_KEY in the environment; otherwise a random
-# key is generated at startup (sessions survive only while the server runs).
+# Trust the X-Forwarded-* headers from reverse proxies (HuggingFace, nginx…).
+# This lets Flask see the real HTTPS scheme so secure cookies work correctly.
+app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1, x_prefix=1)
+
+# ── Secret key ────────────────────────────────────────────────────────────────
+# Set SD_SECRET_KEY in the environment (HF Spaces → Settings → Secrets) so
+# sessions survive server restarts.  A random key is used as a safe fallback
+# (sessions reset whenever the server restarts).
 app.secret_key = os.environ.get("SD_SECRET_KEY") or os.urandom(32)
 
+# ── Session cookie settings ───────────────────────────────────────────────────
+# HuggingFace Spaces embeds the app inside an <iframe>.  Browsers block
+# SameSite=Lax cookies in cross-site iframes, which would create a new session
+# on every request and make the per-user database invisible.
+# SameSite=None + Secure=True is the correct fix for iframe deployments.
+# We detect HTTPS via the ProxyFix-corrected request scheme at runtime so
+# that local HTTP development still works without secure cookies.
+_BEHIND_PROXY = bool(os.environ.get("SD_BEHIND_PROXY") or
+                     os.environ.get("SCRIPTURE_DETECTOR_CACHE_DB"))
+
+if _BEHIND_PROXY:
+    app.config["SESSION_COOKIE_SAMESITE"] = "None"
+    app.config["SESSION_COOKIE_SECURE"]   = True
+
 _CACHE_MODE = bool(os.environ.get("SCRIPTURE_DETECTOR_CACHE_DB"))
 
 
@@ -49,7 +70,7 @@ def _bind_session_db():
         return
     if "_db_sid" not in session:
         session["_db_sid"] = str(uuid.uuid4())
-        session.permanent = True           # honour PERMANENT_SESSION_LIFETIME
+        session.permanent = True
     database.session_local.session_id = session["_db_sid"]
 
 PROJECT_ROOT = Path(__file__).resolve().parent