Appendix B — AI Tuning Parameters
Complete reference for all parameters that affect AI-driven matching, enrichment, and URA generation. Parameters that default to off or to their legacy values do not change behaviour until explicitly adjusted.
Matching weights
Stored in the project's matcher_profile. All three must sum to 100%.
| Parameter | Default | Effect when increased |
|---|---|---|
| Leaf weight | 55% | More emphasis on the item's own description words |
| Ancestor weight | 25% | More emphasis on the heading hierarchy |
| Spec weight | 20% | More emphasis on extracted numeric specs (grades, dimensions) |
Scoring flags
Stored in the project's matcher_profile. All default to off.
| Flag | Default | When to enable |
|---|---|---|
fold_keywords (Keyword enrichment) | OFF | Flat or template-derived rate tables; BOQ has grade/element in headings |
overlap_leaf (Overlap scorer) | OFF | Combine with Keyword enrichment; when token-count asymmetry is large |
reweight_thin_ancestors (Reweight flat tables) | OFF | Flat rate tables; safe to leave on for all table types |
use_facets (Facet matching) | OFF | After sandbox validation confirms facets are populated on both sides |
AI tiebreaker thresholds
Hard-coded. Require a code change to adjust.
| Parameter | Default | Condition that fires the tiebreaker |
|---|---|---|
| Score gap threshold | 0.15 | Top two candidates within this gap |
| Confidence threshold | 0.55 | Top score below this value |
Increasing the score gap makes the tiebreaker fire more often (more AI calls, more conservative). Decreasing the confidence threshold raises the bar for auto-acceptance.
Template generation thresholds
Stored in the settings table. Editable in Settings without a code change.
| Key | Default | Tier boundary |
|---|---|---|
template_match_threshold | 0.65 | Baseline vs Starting-point |
template_reference_floor | 0.30 | Starting-point vs Cold |
Jaccard score ≥ 0.65 → Baseline: AI adjusts quantities only
0.30 ≤ score < 0.65 → Starting point: AI modifies the recipe
score < 0.30 → Cold: AI generates from scratch
score = 1.0 (provenance) → Definitive: template adopted verbatim (no AI)
Coverage thresholds
Hard-coded. Require a code change to adjust.
| Signal | Method | Threshold |
|---|---|---|
| Cluster category name vs template name | Jaccard | 0.45 |
| Representative BOQ description vs template keywords + name | Overlap coefficient | 0.55 |
A cluster is covered if either signal exceeds its threshold. Raising either threshold produces more "needs template" rows (stricter coverage).
Parameter storage summary
| Parameter | Location | Default | Edit via |
|---|---|---|---|
| Leaf / Ancestor / Spec weights | Project profile | 55 / 25 / 20% | Matcher Weight Tuning panel |
fold_keywords | Project profile | OFF | Matcher Weight Tuning panel |
overlap_leaf | Project profile | OFF | Matcher Weight Tuning panel |
reweight_thin_ancestors | Project profile | OFF | Matcher Weight Tuning panel |
use_facets | Project profile | OFF | Matcher Weight Tuning panel (greyed; test in sandbox first) |
| Tiebreaker score gap | Code | 0.15 | Code change |
| Tiebreaker confidence | Code | 0.55 | Code change |
template_match_threshold | Settings table | 0.65 | Settings page |
template_reference_floor | Settings table | 0.30 | Settings page |
| Coverage Jaccard threshold | Code | 0.45 | Code change |
| Coverage overlap threshold | Code | 0.55 | Code change |