# WP20 attribute ontology — every attribute carries: evidence class, source(s), extraction method, allowed values,
# confidence handling, expected effect in the cost model, validation source, known error modes.
# Evidence classes: ADMIN (verified administrative record: assessment roll), VISUAL (directly observable in photos),
# PROXY (inferred visual proxy for a latent construct), TEXT (claimed in listing text or broker fields), LATENT (not
# observable from listings; never inferred, always treated as unknown / scenario).
version: 1.0
attributes:
  # ---------------- ADMIN (assessment roll, MAMH open data via Vrai Prix copy) ----------------
  year_built:         {class: ADMIN, source: roll.annee_construction, method: lookup, values: integer year, confidence: certain, cost_effect: chronological age → physical depreciation, validation: listing/broker year (agreement 95% ±1y), errors: renovation year sometimes recorded instead of original}
  floor_area_m2:      {class: ADMIN, source: roll.aire_etages_m2, method: lookup, values: m² (sum of floor areas above grade per MEFQ), confidence: certain, cost_effect: RCN quantity, validation: broker building dimensions (DuProprio/Sutton) when present, errors: definition differs from "superficie habitable" in listings}
  lot_area_m2:        {class: ADMIN, source: roll.superficie_terrain_m2, method: lookup, values: m², confidence: certain, cost_effect: none (land valued separately), validation: listing lot_sqft, errors: none known}
  storeys_roll:       {class: ADMIN, source: roll.nb_etages, method: lookup, values: {1, 1.5, 2, 2.5, 3}, confidence: certain, cost_effect: storey multiplier on RCN, validation: visual storeys, errors: half-storeys coded inconsistently across municipalities}
  land_value_roll:    {class: ADMIN, source: roll.valeur_terrain, method: lookup, values: CAD at roll market date (LFM art. 46), confidence: assessor judgment, cost_effect: L term (indexed to valuation date), validation: none independent, errors: roll date 2022–2024, mass-appraisal land model}
  building_value_roll: {class: ADMIN, source: roll.valeur_batiment, method: lookup, values: CAD at roll market date, confidence: assessor judgment (cost-based mass appraisal), cost_effect: benchmark for RCN − D (not an input), validation: n/a, errors: smoothing within neighbourhood units}
  # ---------------- VISUAL (per image, then aggregated) ----------------
  scene:              {class: VISUAL, source: image, method: VLM classification, values: [exterior_front, exterior_rear_or_side, exterior_aerial_or_street, kitchen, bathroom, living_or_dining, bedroom, basement, garage, mechanical_or_utility, yard_pool_or_deck, floor_plan_or_document, other, unusable], confidence: per-image 0–1, cost_effect: routes attributes, validation: RE/MAX file-name room codes (pri/cui/sal/sdb/cha/sou/fac), errors: open-plan rooms, staged basements}
  storeys_visible:    {class: VISUAL, source: exterior images, method: VLM, values: ['1', '1.5', '2', '2.5', '3+', not_visible], confidence: 0–1, cost_effect: cross-check of storeys_roll, validation: roll nb_etages, errors: split-levels, walk-out basements counted as storeys}
  building_type_visual: {class: VISUAL, source: exterior images, method: VLM, values: [detached, semi_detached, row_or_townhouse, other, not_visible], confidence: 0–1, cost_effect: party-wall adjustment to RCN, validation: listing property_type, errors: tight framing hides neighbours}
  cladding:           {class: VISUAL, source: exterior images, method: VLM (up to 3 materials), values: [brick, stone, vinyl, wood, aluminum_or_steel, stucco_or_acrylic, fiber_cement, other, not_visible], confidence: 0–1, cost_effect: exterior-wall unit cost (brick/stone > fiber cement > wood > vinyl), validation: broker field "Revêtement", errors: brick veneer vs full brick indistinguishable; fiber cement vs wood}
  roof_form:          {class: VISUAL, source: exterior images, method: VLM, values: [gable, hip, flat_or_low_slope, mansard, mixed_or_other, not_visible], confidence: 0–1, cost_effect: roof unit cost, validation: none, errors: snow cover}
  roof_covering:      {class: VISUAL, source: exterior images, method: VLM, values: [asphalt_shingle, metal, membrane_flat, other, not_visible], confidence: 0–1, cost_effect: roof covering unit cost, validation: broker field "Toiture", errors: membranes not visible from the street}
  garage_visible:     {class: VISUAL, source: exterior images, method: VLM, values: [attached, detached, carport, none_visible, not_visible], confidence: 0–1, cost_effect: garage add-on, validation: broker field "Garage"/"Stationnement", errors: garage behind the house}
  exterior_condition: {class: PROXY, source: exterior images, method: VLM 1–5 anchored scale (1 = severe visible deterioration, 5 = like new), confidence: 0–1, cost_effect: effective age (physical depreciation), validation: none (proposed expert panel), errors: fresh paint hides deterioration; photo editing}
  visible_defects:    {class: VISUAL, source: all images, method: VLM multi-label, values: [water_staining, cracking, mold_like_staining, peeling_paint_or_finish, worn_roof, damaged_cladding, sagging_or_unevenness, none_visible], confidence: 0–1, cost_effect: curable physical deterioration flag (scenario only), validation: none, errors: shadows read as stains}
  kitchen_grade:      {class: PROXY, source: kitchen images, method: VLM 4-level grade with observable anchors (counters, cabinets, appliances, layout), values: [basic, standard, upgraded, luxury, not_visible], confidence: 0–1, cost_effect: finish-grade multiplier on RCN, validation: broker field "Cuisine" (counter/cabinet material), errors: staging and wide-angle lenses inflate grade}
  kitchen_counters:   {class: VISUAL, source: kitchen images, method: VLM, values: [laminate, quartz_granite_or_stone, wood_or_butcher_block, other, not_visible], confidence: 0–1, cost_effect: finish-grade input, validation: broker field "Cuisine", errors: quartz vs laminate look-alikes}
  kitchen_cabinets:   {class: VISUAL, source: kitchen images, method: VLM, values: [melamine_or_laminate, painted_or_thermofoil, wood, modern_high_gloss, other, not_visible], confidence: 0–1, cost_effect: finish-grade input, validation: broker field "Cuisine" (e.g. "Armoires en mélamine"), errors: painted wood vs MDF}
  bathroom_grade:     {class: PROXY, source: bathroom images, method: VLM 4-level grade, values: [basic, standard, upgraded, luxury, not_visible], confidence: 0–1, cost_effect: finish-grade multiplier, validation: broker field "Salle de bains", errors: powder room vs full bath}
  flooring_main:      {class: VISUAL, source: living/bedroom/kitchen images, method: VLM (dominant), values: [hardwood, laminate_or_vinyl_plank, ceramic_or_porcelain, carpet, concrete_or_other, not_visible], confidence: 0–1, cost_effect: finish unit cost, validation: room list "revêtement" field (RE/MAX), errors: laminate vs hardwood}
  interior_condition: {class: PROXY, source: interior images, method: VLM 1–5 anchored scale, confidence: 0–1, cost_effect: effective age, validation: none (expert panel proposed), errors: staging, lighting}
  interior_finish_quality: {class: PROXY, source: interior images, method: VLM 1–5, confidence: 0–1, cost_effect: finish-grade multiplier (with kitchen/bath), validation: none, errors: taste vs quality}
  basement_finish:    {class: VISUAL, source: basement images, method: VLM, values: [finished, partially_finished, unfinished, not_visible], confidence: 0–1, cost_effect: basement finish add-on, validation: broker field "Sous-sol", errors: no basement photo ≠ unfinished (MNAR)}
  renovation_evidence: {class: PROXY, source: all images, method: VLM, values: [none_apparent, partial, extensive, unsure], confidence: 0–1, cost_effect: effective-age reduction, validation: text renovation claims, errors: new-build vs renovated}
  photo_quality:      {class: VISUAL, source: each image, method: VLM 1–5 technical quality, confidence: n/a, cost_effect: none (moderator), validation: none, errors: n/a}
  staging_or_rendering: {class: VISUAL, source: each image, method: VLM, values: [none_apparent, staged, virtually_staged_or_rendered, unsure], confidence: 0–1, cost_effect: down-weights interior grades, validation: none, errors: tasteful furnishing vs staging}
  # ---------------- TEXT (claimed by seller/broker; structured fields or free text) ----------------
  text_claims:        {class: TEXT, source: description + features + broker details (price, taxes and assessment fields masked), method: LLM structured extraction, values: see schema text_property, confidence: per field, cost_effect: B1/B3 inputs and reconciliation, validation: images and roll, errors: marketing language, omissions, price leakage (masked)}
  # ---------------- LATENT (never inferred) ----------------
  foundation_integrity: {class: LATENT, note: not inferable from listing media; treated as unknown; scenario analysis only}
  hidden_moisture_or_mold: {class: LATENT, note: same}
  structural_soundness: {class: LATENT, note: same}
  code_compliance_permits: {class: LATENT, note: same}
  legal_tenure_servitudes: {class: LATENT, note: same}
  exact_area_from_images: {class: LATENT, note: never estimated from photos; floor area comes from the roll (ADMIN)}