trowel 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- trowel-0.1.0/PKG-INFO +237 -0
- trowel-0.1.0/README.md +202 -0
- trowel-0.1.0/pyproject.toml +71 -0
- trowel-0.1.0/setup.cfg +4 -0
- trowel-0.1.0/src/__init__.py +1 -0
- trowel-0.1.0/src/app.py +446 -0
- trowel-0.1.0/src/eedp.py +194 -0
- trowel-0.1.0/src/export.py +288 -0
- trowel-0.1.0/src/images.py +179 -0
- trowel-0.1.0/src/ingest.py +479 -0
- trowel-0.1.0/src/main.py +44 -0
- trowel-0.1.0/src/models.py +314 -0
- trowel-0.1.0/src/nlg.py +440 -0
- trowel-0.1.0/src/trowel_io.py +112 -0
- trowel-0.1.0/src/ui/__init__.py +8 -0
- trowel-0.1.0/src/ui/import_page.py +319 -0
- trowel-0.1.0/src/ui/main_window.py +254 -0
- trowel-0.1.0/src/ui/preview_page.py +371 -0
- trowel-0.1.0/src/ui/session.py +119 -0
- trowel-0.1.0/src/ui/theme.py +223 -0
- trowel-0.1.0/src/vocabulary.py +293 -0
- trowel-0.1.0/tests/test_models.py +134 -0
- trowel-0.1.0/trowel.egg-info/PKG-INFO +237 -0
- trowel-0.1.0/trowel.egg-info/SOURCES.txt +26 -0
- trowel-0.1.0/trowel.egg-info/dependency_links.txt +1 -0
- trowel-0.1.0/trowel.egg-info/entry_points.txt +2 -0
- trowel-0.1.0/trowel.egg-info/requires.txt +15 -0
- trowel-0.1.0/trowel.egg-info/top_level.txt +1 -0
trowel-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: trowel
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Premium excavation report drafting tool for CRM archaeologists
|
|
5
|
+
Author-email: Marcus Quinn <marcus@example.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: homepage, https://github.com/mabo-du/trowel
|
|
8
|
+
Project-URL: repository, https://github.com/mabo-du/trowel
|
|
9
|
+
Project-URL: documentation, https://github.com/mabo-du/trowel/blob/master/docs/USER_GUIDE.md
|
|
10
|
+
Project-URL: changelog, https://github.com/mabo-du/trowel/commits/master
|
|
11
|
+
Keywords: archaeology,excavation,report,crm,heritage,stratigraphy,harris-matrix,cultural-resource-management,digital-heritage
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering
|
|
20
|
+
Classifier: Topic :: Text Processing :: Markup :: Markdown
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
Requires-Dist: pandas>=2.0
|
|
24
|
+
Requires-Dist: openpyxl>=3.1
|
|
25
|
+
Requires-Dist: jinja2>=3.1
|
|
26
|
+
Requires-Dist: python-docx>=1.0
|
|
27
|
+
Requires-Dist: PyQt6>=6.6
|
|
28
|
+
Provides-Extra: web
|
|
29
|
+
Requires-Dist: streamlit>=1.40; extra == "web"
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
32
|
+
Requires-Dist: ruff>=0.8; extra == "dev"
|
|
33
|
+
Provides-Extra: hoard
|
|
34
|
+
Requires-Dist: hoard-erd; extra == "hoard"
|
|
35
|
+
|
|
36
|
+
# Trowel ⛏
|
|
37
|
+
|
|
38
|
+
> The archaeologist's essential tool for careful finishing work.
|
|
39
|
+
|
|
40
|
+
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.
|
|
41
|
+
|
|
42
|
+
**No GPU required. No cloud dependency. Your data never leaves your machine.**
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## What Trowel Does
|
|
47
|
+
|
|
48
|
+
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:
|
|
49
|
+
|
|
50
|
+
- **Auto-generating prose** from structured field data using deterministic Natural Language Generation — no LLM hallucinations in your stratigraphy
|
|
51
|
+
- **Building compliance-ready reports** for UK (CIfA/MoRPHE), US (Section 106/NHPA), Australia (NSW Heritage), and generic frameworks
|
|
52
|
+
- **Producing editable DOCX** for Principal Investigator review, plus archival PDF/A-2b and plain Markdown
|
|
53
|
+
- **Validating stratigraphic logic** — flags missing context references, cut/fill inconsistencies, impossible relationships, and empty or meaningless datasets before they reach the SHPO
|
|
54
|
+
|
|
55
|
+
## Quick Start
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Desktop app (recommended)
|
|
59
|
+
pip install -e .
|
|
60
|
+
python3 -m src.main
|
|
61
|
+
|
|
62
|
+
# Or web UI
|
|
63
|
+
pip install -e ".[web]"
|
|
64
|
+
streamlit run src/app.py
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Load `sample_data/contexts.csv` to see it work in under a minute.
|
|
68
|
+
|
|
69
|
+
## Features
|
|
70
|
+
|
|
71
|
+
### Dual Interface
|
|
72
|
+
- **Desktop (PyQt6):** Native file dialogs, wizard-style workflow, dark Fusion theme, live Markdown preview — the primary experience for daily CRM use
|
|
73
|
+
- **Web (Streamlit):** Browser-based alternative, deployable as a team tool, premium CSS design
|
|
74
|
+
|
|
75
|
+
### Data Ingestion
|
|
76
|
+
- CSV and Excel parsing with 70+ auto-detected column names (UK and US conventions)
|
|
77
|
+
- Validates stratigraphic logic: missing references, self-references, cut/fill consistency
|
|
78
|
+
- Background-thread parsing keeps the UI responsive
|
|
79
|
+
|
|
80
|
+
### Report Generation
|
|
81
|
+
- **Deterministic NLG** — no LLM API calls, no GPU required
|
|
82
|
+
- **ROMFA inclusion scale** — frequent charcoal, occasional CBM, rare flecks, all correctly expanded
|
|
83
|
+
- **Soil texture vocabulary** — silty clay ≠ clayey silt (geologically precise, never treated as synonyms)
|
|
84
|
+
- **Controlled period labels** — Iron Age, Romano-British, post-medieval, etc.
|
|
85
|
+
- **Section-by-section preview** — toggle sections on/off, see live updates
|
|
86
|
+
|
|
87
|
+
### Jurisdiction Templates
|
|
88
|
+
|
|
89
|
+
| Jurisdiction | Standard | Key Sections |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| **UK** | CIfA Standard & Guidance / MoRPHE | Non-technical summary (NGR/OASIS), MoLAS recording methodology, Type 2 Appraisal with UPD, AAF-compliant archive deposition |
|
|
92
|
+
| **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 |
|
|
93
|
+
| **Australia** | NSW Heritage Guidelines | Burra Charter-aligned significance assessment, graded zones, five prescribed management outcomes, Aboriginal cultural heritage acknowledgement |
|
|
94
|
+
|
|
95
|
+
### Export Formats
|
|
96
|
+
- **Editable DOCX** — your company template, ready for PI review
|
|
97
|
+
- **Archival PDF/A-2b** — ready for HER deposition
|
|
98
|
+
- **Plain Markdown** — version-control friendly, universal
|
|
99
|
+
- **Harris Matrix SVG** — auto-generated from context relationships
|
|
100
|
+
- **Empty-project guard** — when a CSV lacks recognisable context records, Trowel shows a clear error instead of generating a fake-looking report
|
|
101
|
+
- **Quality gate** — detects when >90% of parsed contexts have no archaeological data and warns the user before generation
|
|
102
|
+
|
|
103
|
+
### Keyboard Shortcuts
|
|
104
|
+
|
|
105
|
+
| Shortcut | Action |
|
|
106
|
+
|----------|--------|
|
|
107
|
+
| `Ctrl+O` | Open .trowel project file |
|
|
108
|
+
| `Ctrl+Shift+O` | Import CSV/Excel data |
|
|
109
|
+
| `Ctrl+S` | Save project |
|
|
110
|
+
| `Ctrl+Shift+S` | Save project as... |
|
|
111
|
+
| `Ctrl+N` | New project (clear session) |
|
|
112
|
+
| `Ctrl+Q` | Quit |
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## The StratiGraph Ecosystem
|
|
117
|
+
|
|
118
|
+
Trowel is part of a suite of open-source tools for digital heritage and archaeology:
|
|
119
|
+
|
|
120
|
+
| Tool | Repository | Role |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| **Trowel** | *(this repo)* | Report drafting from digital field data |
|
|
123
|
+
| **[HOARD](https://github.com/mabo-du/HOARD)** | Heritage Observation And Report Drafter | Paper + photo digitisation pipeline (OCR, VLM captioning, spatial reconstruction). Use when starting from raw scans and handwritten sheets. |
|
|
124
|
+
| **[StratiGraph](https://github.com/mabo-du/stratigraph)** | Harris Matrix generator | Interactive DAG editor for stratigraphic sequences. Exports EEDP paths for hallucination-free AI report generation. |
|
|
125
|
+
| **[Libby](https://github.com/mabo-du/libby)** | Radiocarbon calibration | Bayesian age-depth modelling, calibration curve rendering, marine reservoir correction. |
|
|
126
|
+
| **[Paleo](https://github.com/mabo-du/paleo)** | Palaeontology AI platform | Fossil identification, paleoclimate reconstruction, palaeogeographic mapping. |
|
|
127
|
+
| **[dibble](https://github.com/mabo-du/dibble)** | Lithic analysis | Automated 3D stone tool measurement, photogrammetry pipeline, AI classification. |
|
|
128
|
+
| **[Fritts](https://github.com/mabo-du/fritts)** | Dendrochronology | Tree-ring cross-dating, master chronology building, image ring measurement. |
|
|
129
|
+
|
|
130
|
+
### How Trowel Integrates
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
134
|
+
│ HOARD │────▶│ Trowel │────▶│ StratiGraph │
|
|
135
|
+
│ paper→digital│ │ digital→draft│ │ strat→DAG │
|
|
136
|
+
└──────────────┘ └──────┬───────┘ └──────┬───────┘
|
|
137
|
+
│ │
|
|
138
|
+
┌──────▼───────┐ ┌──────▼───────┐
|
|
139
|
+
│ Libby │ │ Trowel │
|
|
140
|
+
│ C14 dates │ │ EEDP paths │
|
|
141
|
+
└──────────────┘ └──────────────┘
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- **HOARD → Trowel:** Share `context-sheet-v1.json` schema. HOARD digitises paper; Trowel picks up the structured JSON and generates the report.
|
|
145
|
+
- **Trowel → StratiGraph:** Share the same context data model. StratiGraph visualises the matrix; Trowel consumes EEDP paths for deterministic stratigraphic narratives.
|
|
146
|
+
- **Libby → Trowel:** Radiocarbon dates from Libby flow into Trowel's dating sections and specialist appendices.
|
|
147
|
+
- **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.
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Architecture
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
src/
|
|
155
|
+
├── models.py # Context, Find, Sample, ProjectData dataclasses
|
|
156
|
+
├── ingest.py # CSV/Excel parsing, 70+ column aliases, validation
|
|
157
|
+
├── vocabulary.py # ROMFA scale, soil textures, controlled terminology
|
|
158
|
+
├── nlg.py # Deterministic NLG engine + Jinja2 section templates
|
|
159
|
+
├── export.py # Markdown, DOCX (HOARD or fallback), PDF/A, Harris Matrix
|
|
160
|
+
├── eedp.py # StratiGraph EEDP integration for strat narratives
|
|
161
|
+
├── images.py # Photo plate discovery, Markdown plates, DOCX embedding
|
|
162
|
+
├── main.py # PyQt6 desktop entry point
|
|
163
|
+
├── app.py # Streamlit web entry point
|
|
164
|
+
├── ui/ # PyQt6 desktop UI package
|
|
165
|
+
│ ├── theme.py # Dark Fusion theme (QPalette + stylesheet)
|
|
166
|
+
│ ├── session.py # Reactive QObject-based data store
|
|
167
|
+
│ ├── main_window.py # QMainWindow shell with QStackedWidget
|
|
168
|
+
│ ├── import_page.py # File selection + project metadata form
|
|
169
|
+
│ └── preview_page.py # Section toggles + live Markdown preview
|
|
170
|
+
├── templates/ # Jinja2 report section templates
|
|
171
|
+
│ ├── generic/ # 6 sections, adaptable structure
|
|
172
|
+
│ ├── uk/ # CIfA/MoRPHE overrides
|
|
173
|
+
│ ├── us/ # Section 106 overrides
|
|
174
|
+
│ └── au/ # NSW Heritage overrides
|
|
175
|
+
sample_data/ # Example CSVs (synthetic 37-ctx + original 12-ctx) + EEDP JSON
|
|
176
|
+
tests/ # 21 unit tests
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Sample Data
|
|
180
|
+
|
|
181
|
+
Two example datasets are provided in `sample_data/`:
|
|
182
|
+
|
|
183
|
+
**Synthetic dataset** (recommended for first use): `synthetic_contexts.csv` — 37 contexts across 5 phases, designed to exercise all jurisdiction templates and edge cases:
|
|
184
|
+
|
|
185
|
+
| Phase | Features |
|
|
186
|
+
|---|---|
|
|
187
|
+
| Phase 1 — Natural | River terrace gravels |
|
|
188
|
+
| Phase 2 — Iron Age (800 BC–AD 43) | Enclosure ditch with 3 fills, roundhouse ring-groove, central posthole with in-situ burning, occupation layer |
|
|
189
|
+
| 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 |
|
|
190
|
+
| Phase 4 — Medieval (1066–1550) | Cultivation horizon, drainage ditch, rubbish pit with dense artefact assemblage |
|
|
191
|
+
| Phase 5 — Post-Med/Modern | Ploughsoil, modern topsoil with 20th-century inclusions |
|
|
192
|
+
|
|
193
|
+
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).
|
|
194
|
+
|
|
195
|
+
**Quick demo:** Load `sample_data/synthetic_contexts.csv`, add the finds and samples files, select UK jurisdiction, and preview all sections.
|
|
196
|
+
|
|
197
|
+
**Original demo:** `contexts.csv` — 12-context Iron Age / Roman site with 12 finds and 5 samples.
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Requirements
|
|
202
|
+
|
|
203
|
+
- Python 3.11+
|
|
204
|
+
- PyQt6 (desktop UI)
|
|
205
|
+
- pandas, openpyxl, jinja2, python-docx (core engine)
|
|
206
|
+
- Streamlit (web UI, optional)
|
|
207
|
+
- hoard-erd (premium DOCX/PDF export, optional)
|
|
208
|
+
|
|
209
|
+
## Running Tests
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
pip install -e ".[dev]"
|
|
213
|
+
pytest
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Packaging (Standalone Executable)
|
|
217
|
+
|
|
218
|
+
Trowel can be packaged as a standalone executable so users don't need Python installed.
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
pip install pyinstaller
|
|
222
|
+
make build # Linux
|
|
223
|
+
make build-windows # on Windows
|
|
224
|
+
make build-macos # on macOS
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
The output is in `dist/Trowel/` — a single folder you can zip and distribute. Double-click `Trowel` (or `Trowel.exe` on Windows) to launch.
|
|
228
|
+
|
|
229
|
+
GitHub Actions automatically builds packages for Linux, Windows, and macOS on every push to `master`. Download the artifacts from the Actions tab.
|
|
230
|
+
|
|
231
|
+
## Project File Format
|
|
232
|
+
|
|
233
|
+
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.
|
|
234
|
+
|
|
235
|
+
## License
|
|
236
|
+
|
|
237
|
+
MIT — use it, modify it, ship it. Archaeology deserves better tools, and they should be free.
|
trowel-0.1.0/README.md
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# Trowel ⛏
|
|
2
|
+
|
|
3
|
+
> The archaeologist's essential tool for careful finishing work.
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
**No GPU required. No cloud dependency. Your data never leaves your machine.**
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## What Trowel Does
|
|
12
|
+
|
|
13
|
+
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:
|
|
14
|
+
|
|
15
|
+
- **Auto-generating prose** from structured field data using deterministic Natural Language Generation — no LLM hallucinations in your stratigraphy
|
|
16
|
+
- **Building compliance-ready reports** for UK (CIfA/MoRPHE), US (Section 106/NHPA), Australia (NSW Heritage), and generic frameworks
|
|
17
|
+
- **Producing editable DOCX** for Principal Investigator review, plus archival PDF/A-2b and plain Markdown
|
|
18
|
+
- **Validating stratigraphic logic** — flags missing context references, cut/fill inconsistencies, impossible relationships, and empty or meaningless datasets before they reach the SHPO
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# Desktop app (recommended)
|
|
24
|
+
pip install -e .
|
|
25
|
+
python3 -m src.main
|
|
26
|
+
|
|
27
|
+
# Or web UI
|
|
28
|
+
pip install -e ".[web]"
|
|
29
|
+
streamlit run src/app.py
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Load `sample_data/contexts.csv` to see it work in under a minute.
|
|
33
|
+
|
|
34
|
+
## Features
|
|
35
|
+
|
|
36
|
+
### Dual Interface
|
|
37
|
+
- **Desktop (PyQt6):** Native file dialogs, wizard-style workflow, dark Fusion theme, live Markdown preview — the primary experience for daily CRM use
|
|
38
|
+
- **Web (Streamlit):** Browser-based alternative, deployable as a team tool, premium CSS design
|
|
39
|
+
|
|
40
|
+
### Data Ingestion
|
|
41
|
+
- CSV and Excel parsing with 70+ auto-detected column names (UK and US conventions)
|
|
42
|
+
- Validates stratigraphic logic: missing references, self-references, cut/fill consistency
|
|
43
|
+
- Background-thread parsing keeps the UI responsive
|
|
44
|
+
|
|
45
|
+
### Report Generation
|
|
46
|
+
- **Deterministic NLG** — no LLM API calls, no GPU required
|
|
47
|
+
- **ROMFA inclusion scale** — frequent charcoal, occasional CBM, rare flecks, all correctly expanded
|
|
48
|
+
- **Soil texture vocabulary** — silty clay ≠ clayey silt (geologically precise, never treated as synonyms)
|
|
49
|
+
- **Controlled period labels** — Iron Age, Romano-British, post-medieval, etc.
|
|
50
|
+
- **Section-by-section preview** — toggle sections on/off, see live updates
|
|
51
|
+
|
|
52
|
+
### Jurisdiction Templates
|
|
53
|
+
|
|
54
|
+
| Jurisdiction | Standard | Key Sections |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| **UK** | CIfA Standard & Guidance / MoRPHE | Non-technical summary (NGR/OASIS), MoLAS recording methodology, Type 2 Appraisal with UPD, AAF-compliant archive deposition |
|
|
57
|
+
| **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 |
|
|
58
|
+
| **Australia** | NSW Heritage Guidelines | Burra Charter-aligned significance assessment, graded zones, five prescribed management outcomes, Aboriginal cultural heritage acknowledgement |
|
|
59
|
+
|
|
60
|
+
### Export Formats
|
|
61
|
+
- **Editable DOCX** — your company template, ready for PI review
|
|
62
|
+
- **Archival PDF/A-2b** — ready for HER deposition
|
|
63
|
+
- **Plain Markdown** — version-control friendly, universal
|
|
64
|
+
- **Harris Matrix SVG** — auto-generated from context relationships
|
|
65
|
+
- **Empty-project guard** — when a CSV lacks recognisable context records, Trowel shows a clear error instead of generating a fake-looking report
|
|
66
|
+
- **Quality gate** — detects when >90% of parsed contexts have no archaeological data and warns the user before generation
|
|
67
|
+
|
|
68
|
+
### Keyboard Shortcuts
|
|
69
|
+
|
|
70
|
+
| Shortcut | Action |
|
|
71
|
+
|----------|--------|
|
|
72
|
+
| `Ctrl+O` | Open .trowel project file |
|
|
73
|
+
| `Ctrl+Shift+O` | Import CSV/Excel data |
|
|
74
|
+
| `Ctrl+S` | Save project |
|
|
75
|
+
| `Ctrl+Shift+S` | Save project as... |
|
|
76
|
+
| `Ctrl+N` | New project (clear session) |
|
|
77
|
+
| `Ctrl+Q` | Quit |
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## The StratiGraph Ecosystem
|
|
82
|
+
|
|
83
|
+
Trowel is part of a suite of open-source tools for digital heritage and archaeology:
|
|
84
|
+
|
|
85
|
+
| Tool | Repository | Role |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| **Trowel** | *(this repo)* | Report drafting from digital field data |
|
|
88
|
+
| **[HOARD](https://github.com/mabo-du/HOARD)** | Heritage Observation And Report Drafter | Paper + photo digitisation pipeline (OCR, VLM captioning, spatial reconstruction). Use when starting from raw scans and handwritten sheets. |
|
|
89
|
+
| **[StratiGraph](https://github.com/mabo-du/stratigraph)** | Harris Matrix generator | Interactive DAG editor for stratigraphic sequences. Exports EEDP paths for hallucination-free AI report generation. |
|
|
90
|
+
| **[Libby](https://github.com/mabo-du/libby)** | Radiocarbon calibration | Bayesian age-depth modelling, calibration curve rendering, marine reservoir correction. |
|
|
91
|
+
| **[Paleo](https://github.com/mabo-du/paleo)** | Palaeontology AI platform | Fossil identification, paleoclimate reconstruction, palaeogeographic mapping. |
|
|
92
|
+
| **[dibble](https://github.com/mabo-du/dibble)** | Lithic analysis | Automated 3D stone tool measurement, photogrammetry pipeline, AI classification. |
|
|
93
|
+
| **[Fritts](https://github.com/mabo-du/fritts)** | Dendrochronology | Tree-ring cross-dating, master chronology building, image ring measurement. |
|
|
94
|
+
|
|
95
|
+
### How Trowel Integrates
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
99
|
+
│ HOARD │────▶│ Trowel │────▶│ StratiGraph │
|
|
100
|
+
│ paper→digital│ │ digital→draft│ │ strat→DAG │
|
|
101
|
+
└──────────────┘ └──────┬───────┘ └──────┬───────┘
|
|
102
|
+
│ │
|
|
103
|
+
┌──────▼───────┐ ┌──────▼───────┐
|
|
104
|
+
│ Libby │ │ Trowel │
|
|
105
|
+
│ C14 dates │ │ EEDP paths │
|
|
106
|
+
└──────────────┘ └──────────────┘
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
- **HOARD → Trowel:** Share `context-sheet-v1.json` schema. HOARD digitises paper; Trowel picks up the structured JSON and generates the report.
|
|
110
|
+
- **Trowel → StratiGraph:** Share the same context data model. StratiGraph visualises the matrix; Trowel consumes EEDP paths for deterministic stratigraphic narratives.
|
|
111
|
+
- **Libby → Trowel:** Radiocarbon dates from Libby flow into Trowel's dating sections and specialist appendices.
|
|
112
|
+
- **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.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Architecture
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
src/
|
|
120
|
+
├── models.py # Context, Find, Sample, ProjectData dataclasses
|
|
121
|
+
├── ingest.py # CSV/Excel parsing, 70+ column aliases, validation
|
|
122
|
+
├── vocabulary.py # ROMFA scale, soil textures, controlled terminology
|
|
123
|
+
├── nlg.py # Deterministic NLG engine + Jinja2 section templates
|
|
124
|
+
├── export.py # Markdown, DOCX (HOARD or fallback), PDF/A, Harris Matrix
|
|
125
|
+
├── eedp.py # StratiGraph EEDP integration for strat narratives
|
|
126
|
+
├── images.py # Photo plate discovery, Markdown plates, DOCX embedding
|
|
127
|
+
├── main.py # PyQt6 desktop entry point
|
|
128
|
+
├── app.py # Streamlit web entry point
|
|
129
|
+
├── ui/ # PyQt6 desktop UI package
|
|
130
|
+
│ ├── theme.py # Dark Fusion theme (QPalette + stylesheet)
|
|
131
|
+
│ ├── session.py # Reactive QObject-based data store
|
|
132
|
+
│ ├── main_window.py # QMainWindow shell with QStackedWidget
|
|
133
|
+
│ ├── import_page.py # File selection + project metadata form
|
|
134
|
+
│ └── preview_page.py # Section toggles + live Markdown preview
|
|
135
|
+
├── templates/ # Jinja2 report section templates
|
|
136
|
+
│ ├── generic/ # 6 sections, adaptable structure
|
|
137
|
+
│ ├── uk/ # CIfA/MoRPHE overrides
|
|
138
|
+
│ ├── us/ # Section 106 overrides
|
|
139
|
+
│ └── au/ # NSW Heritage overrides
|
|
140
|
+
sample_data/ # Example CSVs (synthetic 37-ctx + original 12-ctx) + EEDP JSON
|
|
141
|
+
tests/ # 21 unit tests
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Sample Data
|
|
145
|
+
|
|
146
|
+
Two example datasets are provided in `sample_data/`:
|
|
147
|
+
|
|
148
|
+
**Synthetic dataset** (recommended for first use): `synthetic_contexts.csv` — 37 contexts across 5 phases, designed to exercise all jurisdiction templates and edge cases:
|
|
149
|
+
|
|
150
|
+
| Phase | Features |
|
|
151
|
+
|---|---|
|
|
152
|
+
| Phase 1 — Natural | River terrace gravels |
|
|
153
|
+
| Phase 2 — Iron Age (800 BC–AD 43) | Enclosure ditch with 3 fills, roundhouse ring-groove, central posthole with in-situ burning, occupation layer |
|
|
154
|
+
| 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 |
|
|
155
|
+
| Phase 4 — Medieval (1066–1550) | Cultivation horizon, drainage ditch, rubbish pit with dense artefact assemblage |
|
|
156
|
+
| Phase 5 — Post-Med/Modern | Ploughsoil, modern topsoil with 20th-century inclusions |
|
|
157
|
+
|
|
158
|
+
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).
|
|
159
|
+
|
|
160
|
+
**Quick demo:** Load `sample_data/synthetic_contexts.csv`, add the finds and samples files, select UK jurisdiction, and preview all sections.
|
|
161
|
+
|
|
162
|
+
**Original demo:** `contexts.csv` — 12-context Iron Age / Roman site with 12 finds and 5 samples.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Requirements
|
|
167
|
+
|
|
168
|
+
- Python 3.11+
|
|
169
|
+
- PyQt6 (desktop UI)
|
|
170
|
+
- pandas, openpyxl, jinja2, python-docx (core engine)
|
|
171
|
+
- Streamlit (web UI, optional)
|
|
172
|
+
- hoard-erd (premium DOCX/PDF export, optional)
|
|
173
|
+
|
|
174
|
+
## Running Tests
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
pip install -e ".[dev]"
|
|
178
|
+
pytest
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Packaging (Standalone Executable)
|
|
182
|
+
|
|
183
|
+
Trowel can be packaged as a standalone executable so users don't need Python installed.
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
pip install pyinstaller
|
|
187
|
+
make build # Linux
|
|
188
|
+
make build-windows # on Windows
|
|
189
|
+
make build-macos # on macOS
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The output is in `dist/Trowel/` — a single folder you can zip and distribute. Double-click `Trowel` (or `Trowel.exe` on Windows) to launch.
|
|
193
|
+
|
|
194
|
+
GitHub Actions automatically builds packages for Linux, Windows, and macOS on every push to `master`. Download the artifacts from the Actions tab.
|
|
195
|
+
|
|
196
|
+
## Project File Format
|
|
197
|
+
|
|
198
|
+
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.
|
|
199
|
+
|
|
200
|
+
## License
|
|
201
|
+
|
|
202
|
+
MIT — use it, modify it, ship it. Archaeology deserves better tools, and they should be free.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=64", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "trowel"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Premium excavation report drafting tool for CRM archaeologists"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = {text = "MIT"}
|
|
12
|
+
authors = [
|
|
13
|
+
{name = "Marcus Quinn", email = "marcus@example.com"},
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"archaeology", "excavation", "report", "crm", "heritage",
|
|
17
|
+
"stratigraphy", "harris-matrix", "cultural-resource-management",
|
|
18
|
+
"digital-heritage",
|
|
19
|
+
]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Development Status :: 4 - Beta",
|
|
22
|
+
"Intended Audience :: Science/Research",
|
|
23
|
+
"License :: OSI Approved :: MIT License",
|
|
24
|
+
"Operating System :: OS Independent",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Topic :: Scientific/Engineering",
|
|
29
|
+
"Topic :: Text Processing :: Markup :: Markdown",
|
|
30
|
+
]
|
|
31
|
+
dependencies = [
|
|
32
|
+
"pandas>=2.0",
|
|
33
|
+
"openpyxl>=3.1",
|
|
34
|
+
"jinja2>=3.1",
|
|
35
|
+
"python-docx>=1.0",
|
|
36
|
+
"PyQt6>=6.6",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[project.optional-dependencies]
|
|
40
|
+
web = [
|
|
41
|
+
"streamlit>=1.40",
|
|
42
|
+
]
|
|
43
|
+
dev = [
|
|
44
|
+
"pytest>=8.0",
|
|
45
|
+
"ruff>=0.8",
|
|
46
|
+
]
|
|
47
|
+
hoard = [
|
|
48
|
+
"hoard-erd",
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
[project.urls]
|
|
52
|
+
homepage = "https://github.com/mabo-du/trowel"
|
|
53
|
+
repository = "https://github.com/mabo-du/trowel"
|
|
54
|
+
documentation = "https://github.com/mabo-du/trowel/blob/master/docs/USER_GUIDE.md"
|
|
55
|
+
changelog = "https://github.com/mabo-du/trowel/commits/master"
|
|
56
|
+
|
|
57
|
+
[project.scripts]
|
|
58
|
+
trowel = "src.main:main"
|
|
59
|
+
|
|
60
|
+
[tool.ruff]
|
|
61
|
+
target-version = "py311"
|
|
62
|
+
line-length = 100
|
|
63
|
+
|
|
64
|
+
[tool.setuptools]
|
|
65
|
+
packages = ["src", "src.ui"]
|
|
66
|
+
|
|
67
|
+
[tool.ruff.lint]
|
|
68
|
+
select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
|
|
69
|
+
|
|
70
|
+
[tool.pytest.ini_options]
|
|
71
|
+
testpaths = ["tests"]
|
trowel-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Trowel — premium report generation for CRM archaeologists."""
|