trowel 0.1.0

Premium excavation report drafting tool for CRM archaeologists

Trowel ⛏

The archaeologist's essential tool for careful finishing work.

A premium desktop application that transforms digital excavation data into compliance-ready archaeological reports. Upload context records, finds catalogues, and sample logs — get a professionally structured draft report built to national heritage standards in seconds.

No GPU required. No cloud dependency. Your data never leaves your machine.

---

What Trowel Does

Commercial archaeologists spend up to 40% of project budgets on post-excavation report writing. SHPO rejections from boiler-plated text are common. Grey literature backlogs are massive. Trowel fixes this by:

• Auto-generating prose from structured field data using deterministic Natural Language Generation — no LLM hallucinations in your stratigraphy
• Building compliance-ready reports for UK (CIfA/MoRPHE), US (Section 106/NHPA), Australia (NSW Heritage), and generic frameworks
• Producing editable DOCX for Principal Investigator review, plus archival PDF/A-2b and plain Markdown
• Validating stratigraphic logic — flags missing context references, cut/fill inconsistencies, impossible relationships, and empty or meaningless datasets before they reach the SHPO

Quick Start

# Desktop app (recommended)
pip install -e .
python3 -m src.main

# Or web UI
pip install -e ".[web]"
streamlit run src/app.py

Load sample_data/contexts.csv to see it work in under a minute.

Features

Dual Interface

• Desktop (PyQt6): Native file dialogs, wizard-style workflow, dark Fusion theme, live Markdown preview — the primary experience for daily CRM use
• Web (Streamlit): Browser-based alternative, deployable as a team tool, premium CSS design

Data Ingestion

• CSV and Excel parsing with 70+ auto-detected column names (UK and US conventions)
• Validates stratigraphic logic: missing references, self-references, cut/fill consistency
• Background-thread parsing keeps the UI responsive

Report Generation

• Deterministic NLG — no LLM API calls, no GPU required
• ROMFA inclusion scale — frequent charcoal, occasional CBM, rare flecks, all correctly expanded
• Soil texture vocabulary — silty clay ≠ clayey silt (geologically precise, never treated as synonyms)
• Controlled period labels — Iron Age, Romano-British, post-medieval, etc.
• Section-by-section preview — toggle sections on/off, see live updates

Jurisdiction Templates

Jurisdiction	Standard	Key Sections
UK	CIfA Standard & Guidance / MoRPHE	Non-technical summary (NGR/OASIS), MoLAS recording methodology, Type 2 Appraisal with UPD, AAF-compliant archive deposition
US	Section 106 (NHPA) / SHPO	SHPO cover page with legal description, NRHP eligibility evaluation (criteria A-D + integrity), shovel test methodology, 36 CFR 79 curation
Australia	NSW Heritage Guidelines	Burra Charter-aligned significance assessment, graded zones, five prescribed management outcomes, Aboriginal cultural heritage acknowledgement

Export Formats

• Editable DOCX — your company template, ready for PI review
• Archival PDF/A-2b — ready for HER deposition
• Plain Markdown — version-control friendly, universal
• Harris Matrix SVG — auto-generated from context relationships
• Empty-project guard — when a CSV lacks recognisable context records, Trowel shows a clear error instead of generating a fake-looking report
• Quality gate — detects when >90% of parsed contexts have no archaeological data and warns the user before generation

Keyboard Shortcuts

Shortcut	Action
Ctrl+O	Open .trowel project file
Ctrl+Shift+O	Import CSV/Excel data
Ctrl+S	Save project
Ctrl+Shift+S	Save project as...
Ctrl+N	New project (clear session)
Ctrl+Q	Quit

---

The StratiGraph Ecosystem

Trowel is part of a suite of open-source tools for digital heritage and archaeology:

Tool	Repository	Role
Trowel	(this repo)	Report drafting from digital field data
HOARD	Heritage Observation And Report Drafter	Paper + photo digitisation pipeline (OCR, VLM captioning, spatial reconstruction). Use when starting from raw scans and handwritten sheets.
StratiGraph	Harris Matrix generator	Interactive DAG editor for stratigraphic sequences. Exports EEDP paths for hallucination-free AI report generation.
Libby	Radiocarbon calibration	Bayesian age-depth modelling, calibration curve rendering, marine reservoir correction.
Paleo	Palaeontology AI platform	Fossil identification, paleoclimate reconstruction, palaeogeographic mapping.
dibble	Lithic analysis	Automated 3D stone tool measurement, photogrammetry pipeline, AI classification.
Fritts	Dendrochronology	Tree-ring cross-dating, master chronology building, image ring measurement.

How Trowel Integrates

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   HOARD      │────▶│    Trowel    │────▶│ StratiGraph  │
│ paper→digital│     │ digital→draft│     │ strat→DAG    │
└──────────────┘     └──────┬───────┘     └──────┬───────┘
                            │                    │
                     ┌──────▼───────┐     ┌──────▼───────┐
                     │    Libby     │     │    Trowel    │
                     │  C14 dates   │     │  EEDP paths  │
                     └──────────────┘     └──────────────┘

• HOARD → Trowel: Share context-sheet-v1.json schema. HOARD digitises paper; Trowel picks up the structured JSON and generates the report.
• Trowel → StratiGraph: Share the same context data model. StratiGraph visualises the matrix; Trowel consumes EEDP paths for deterministic stratigraphic narratives.
• Libby → Trowel: Radiocarbon dates from Libby flow into Trowel's dating sections and specialist appendices.
• Trowel's HOARD integration: When hoard-erd is installed, Trowel uses HOARD's premium docx_writer (cover pages, styled headings, appendix tables), pdf_writer (PDF/A-2b archival format), and harris.py (matrix SVG generation). Falls back gracefully when HOARD is absent.

---

Architecture

src/
├── models.py          # Context, Find, Sample, ProjectData dataclasses
├── ingest.py           # CSV/Excel parsing, 70+ column aliases, validation
├── vocabulary.py       # ROMFA scale, soil textures, controlled terminology
├── nlg.py              # Deterministic NLG engine + Jinja2 section templates
├── export.py           # Markdown, DOCX (HOARD or fallback), PDF/A, Harris Matrix
├── eedp.py             # StratiGraph EEDP integration for strat narratives
├── images.py           # Photo plate discovery, Markdown plates, DOCX embedding
├── main.py             # PyQt6 desktop entry point
├── app.py              # Streamlit web entry point
├── ui/                 # PyQt6 desktop UI package
│   ├── theme.py        # Dark Fusion theme (QPalette + stylesheet)
│   ├── session.py      # Reactive QObject-based data store
│   ├── main_window.py  # QMainWindow shell with QStackedWidget
│   ├── import_page.py  # File selection + project metadata form
│   └── preview_page.py # Section toggles + live Markdown preview
├── templates/          # Jinja2 report section templates
│   ├── generic/        # 6 sections, adaptable structure
│   ├── uk/             # CIfA/MoRPHE overrides
│   ├── us/             # Section 106 overrides
│   └── au/             # NSW Heritage overrides
sample_data/            # Example CSVs (synthetic 37-ctx + original 12-ctx) + EEDP JSON
tests/                  # 21 unit tests

Sample Data

Two example datasets are provided in sample_data/:

Synthetic dataset (recommended for first use): synthetic_contexts.csv — 37 contexts across 5 phases, designed to exercise all jurisdiction templates and edge cases:

Phase	Features
Phase 1 — Natural	River terrace gravels
Phase 2 — Iron Age (800 BC–AD 43)	Enclosure ditch with 3 fills, roundhouse ring-groove, central posthole with in-situ burning, occupation layer
Phase 3 — Roman (AD 43–410)	Stone building with opus signinum floor, limestone walls, clay floor, hearth, demolition layer, quarry pit with 3 fills, inhumation burial
Phase 4 — Medieval (1066–1550)	Cultivation horizon, drainage ditch, rubbish pit with dense artefact assemblage
Phase 5 — Post-Med/Modern	Ploughsoil, modern topsoil with 20th-century inclusions

Plus edge cases: context with interpretation only (998), completely empty context (999), finds referencing non-existent contexts. Also includes synthetic_finds.csv (28 finds) and synthetic_samples.csv (10 samples).

Quick demo: Load sample_data/synthetic_contexts.csv, add the finds and samples files, select UK jurisdiction, and preview all sections.

Original demo: contexts.csv — 12-context Iron Age / Roman site with 12 finds and 5 samples.

---

Requirements

• Python 3.11+
• PyQt6 (desktop UI)
• pandas, openpyxl, jinja2, python-docx (core engine)
• Streamlit (web UI, optional)
• hoard-erd (premium DOCX/PDF export, optional)

Running Tests

pip install -e ".[dev]"
pytest

Packaging (Standalone Executable)

Trowel can be packaged as a standalone executable so users don't need Python installed.

pip install pyinstaller
make build          # Linux
make build-windows  # on Windows
make build-macos    # on macOS

The output is in dist/Trowel/ — a single folder you can zip and distribute. Double-click Trowel (or Trowel.exe on Windows) to launch.

GitHub Actions automatically builds packages for Linux, Windows, and macOS on every push to master. Download the artifacts from the Actions tab.

Project File Format

Trowel saves and loads projects in .trowel format — a JSON file containing all excavation data and UI state. Use File → Save (Ctrl+S) and File → Open (Ctrl+O) to persist your work.

License

MIT — use it, modify it, ship it. Archaeology deserves better tools, and they should be free.