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 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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ """Trowel — premium report generation for CRM archaeologists."""