Initial commit: FDAM AI Pipeline v4.0.1

- Gradio-based fire damage assessment application
- Qwen3-VL vision model integration (mock + real)
- RAG-based knowledge retrieval with ChromaDB
- FDAM-compliant calculations (ACH, sample density)
- PDF generation with WeasyPrint
- Session persistence via localStorage
- 151 passing tests

Ready for HuggingFace Spaces deployment on 4xL4 (96GB VRAM)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,14 @@
+# FDAM AI Pipeline Environment Configuration
+
+# Set to true for local development with mock models (RTX 4090)
+# Set to false for production with real models (HuggingFace 4xL4)
+MOCK_MODELS=true
+
+# Server configuration (0.0.0.0 required for WSL)
+SERVER_HOST=0.0.0.0
+SERVER_PORT=7860
+
+# Optional: Override model paths
+# VISION_MODEL=Qwen/Qwen3-VL-30B-A3B-Instruct
+# EMBEDDING_MODEL=Qwen/Qwen3-VL-Embedding-8B
+# RERANKER_MODEL=Qwen/Qwen3-VL-Reranker-8B

.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+
+# Environment
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Generated
+chroma_db/
+outputs/
+*.pdf
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# HuggingFace
+*.safetensors
+*.bin
+*.pt
+*.ckpt
+
+# Claude Code
+.claude/

CLAUDE.md

@@ -0,0 +1,174 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**FDAM AI Pipeline** - Fire Damage Assessment Methodology v4.0.1 implementation. An AI-powered system that generates professional Cleaning Specifications / Scope of Work documents for fire damage restoration.
+
+- **Deployment**: HuggingFace Spaces with Nvidia 4xL4 (96GB VRAM total, 24GB per GPU)
+- **Local Dev**: RTX 4090 (24GB) - insufficient for full model stack; use mock models locally
+- **Spec Document**: `FDAM_AI_Pipeline_Technical_Spec.md` is the authoritative technical reference
+
+## Critical Constraints
+
+1. **No External API Calls** - 100% locally-owned models only (no Claude/OpenAI APIs)
+2. **Memory Budget** - 4xL4 96GB total: ~58GB vision (30B BF16) + ~16GB embedding + ~16GB reranker (~90GB used, ~6GB headroom)
+3. **Processing Time** - 60-90 seconds per assessment is acceptable
+4. **MVP Scope** - Phase 1 (PRE) and Phase 2 (PRA) only; no lab results processing yet
+5. **Static RAG** - Knowledge base is pre-indexed; no user document uploads
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| UI Framework | Gradio 4.x |
+| Vision/Generation | Qwen3-VL-30B-A3B-Instruct |
+| Embeddings | Qwen3-VL-Embedding-8B |
+| Reranker | Qwen3-VL-Reranker-8B |
+| Vector Store | ChromaDB 0.4.x |
+| Validation | Pydantic 2.x |
+| PDF Generation | Pandoc 3.x |
+| Package Manager | pip + requirements.txt |
+
+## Development Commands
+
+```sh
+# Install dependencies
+pip install -r requirements.txt
+
+# Run locally with mock models
+MOCK_MODELS=true python app.py
+
+# Run with real models (HuggingFace only - requires A100)
+python app.py
+
+# Recommended tooling (install as dev dependencies)
+ruff check .              # Linting
+ruff format .             # Formatting
+pytest tests/ -v          # Testing
+mypy .                    # Type checking
+```
+
+## Architecture
+
+### 6-Stage Processing Pipeline
+1. **Input Validation** - Pydantic schema validation (schemas/input.py)
+2. **Vision Analysis** - Per-image zone/material/condition detection (pipeline/vision.py)
+3. **RAG Retrieval** - Disposition lookup, thresholds, methods (rag/retriever.py)
+4. **FDAM Logic** - Disposition matrix application (pipeline/main.py)
+5. **Calculations** - Surface areas, ACH, labor estimates (pipeline/calculations.py)
+6. **Document Generation** - SOW, sampling plan, confidence report (pipeline/generator.py)
+
+### Target Project Structure
+```
+├── app.py                 # Gradio entry point
+├── config/                # Inference and app settings
+├── models/                # Model loading (mock vs real)
+├── rag/                   # Chunking, vectorstore, retrieval
+├── schemas/               # Pydantic input/output models
+├── pipeline/              # Main processing logic
+├── ui/                    # Gradio UI components
+├── RAG-KB/                # Knowledge base source files
+├── chroma_db/             # ChromaDB persistence (generated)
+└── tests/
+```
+
+## Domain Knowledge
+
+### Zone Classifications
+- **Burn Zone**: Direct fire involvement, structural char, exposed/damaged elements
+- **Near-Field**: Adjacent to burn zone, heavy smoke/heat exposure, visible contamination
+- **Far-Field**: Smoke migration only, light deposits, no structural damage
+
+### Condition Levels
+- **Background**: No visible contamination
+- **Light**: Faint discoloration, minimal deposits
+- **Moderate**: Visible film/deposits, surface color altered
+- **Heavy**: Thick deposits, surface texture obscured
+- **Structural Damage**: Physical damage requiring repair before cleaning
+
+### Dispositions (FDAM §4.3)
+- **No Action**: Document only
+- **Clean**: Standard cleaning protocol
+- **Evaluate**: Requires professional judgment
+- **Remove**: Material must be removed
+- **Remove/Repair**: Remove and repair/replace
+
+### Facility Classifications (affects thresholds)
+- **Operational**: Active workplace (higher thresholds: 500 µg/100cm² lead)
+- **Non-Operational**: Unoccupied (lower thresholds: 22 µg/100cm² lead)
+- **Public/Childcare**: Most stringent (EPA/HUD Oct 2024: 0.54 µg/100cm² floors)
+
+### Key Calculations
+- **ACH Formula**: `Units = (Volume × 4) / (CFM × 60)` per NADCA ACR 2021
+- **Sample Density**: Varies by area size per FDAM §2.3
+- **Ceiling Deck**: Enhanced sampling (1 per 2,500 SF per FDAM §4.5)
+
+## RAG Knowledge Base
+
+Source documents in `/RAG-KB/`:
+- FDAM v4.0.1 methodology (primary reference)
+- BNL SOP IH75190 (metals clearance thresholds)
+- IICRC/RIA/CIRI Technical Guide (wildfire restoration)
+- Lab method guides (PLM, ICP-MS)
+
+**Chunking rules:**
+- Keep tables intact (never split markdown tables)
+- Preserve headers with content
+- Include metadata (source, category, section)
+
+## Confidence Framework
+
+| Score | Level | Action |
+|-------|-------|--------|
+| ≥90% | Very High | Accept without review |
+| 70-89% | High | Accept, note in report |
+| 50-69% | Moderate | Flag for human review |
+| <50% | Low | Require human verification |
+
+## Multi-GPU Model Loading
+
+The 4xL4 setup requires models to be distributed across GPUs. Use `device_map="auto"` in transformers:
+
+```python
+model = AutoModel.from_pretrained(
+    "Qwen/Qwen3-VL-30B-A3B-Instruct",
+    torch_dtype=torch.bfloat16,
+    device_map="auto",  # Automatically distributes across available GPUs
+    trust_remote_code=True
+)
+```
+
+Expected distribution (BF16, ~90GB total):
+- Vision model (30B): ~58GB spread across GPUs via device_map="auto"
+- Embedding model (8B): ~16GB
+- Reranker model (8B): ~16GB
+- Headroom: ~6GB for KV cache
+
+**Fallback**: If VRAM issues arise, use `Qwen/Qwen3-VL-8B-Instruct` (~16GB) instead of 30B
+
+## Local Development Strategy
+
+The RTX 4090 (24GB VRAM) cannot run the full model stack (~90GB required). Use this workflow:
+
+1. Set `MOCK_MODELS=true` environment variable
+2. Mock responses return realistic JSON matching vision output schema
+3. Test pipeline logic, UI, calculations without real inference
+4. Deploy to HuggingFace Spaces for real model testing
+5. Request build logs after deployment to confirm success
+
+## Code Style
+
+- Use `Literal["a", "b", "c"]` unions instead of Enum for simple string choices
+- Pydantic models for all input/output validation
+- Explicit return types on public functions
+- Result types or explicit error returns over thrown exceptions
+- Group imports: stdlib → third-party → local
+
+## WSL Note
+
+Dev servers must be exposed for WSL access. Use `--host 0.0.0.0` with Gradio:
+```python
+app.launch(server_name="0.0.0.0", server_port=7860)
+```

RAG-KB/FDAM_v4_METHODOLOGY.md

@@ -0,0 +1,994 @@
+# FDAM: Fire Damage Assessment Methodology
+
+## A Systematic Framework for Fire Restoration Industrial Hygiene Documentation
+
+**Version 4.0.1 | January 2026**
+
+**Developed in partnership:** IHC and GVO  
+**Empirical Validation Analysis:** January 2026 (QVC Distribution Center March 2023, Our Lady of Victory February 2025)
+
+---
+
+## Document Control
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 3.0 | January 2026 | Standards verification; ACH revised to 4 minimum per NADCA ACR 2021; metals aligned with BNL SOP IH75190; Public/Childcare lead updated to EPA/HUD October 2024 |
+| 4.0 | January 2026 | Empirical validation integration; dual lab format support; regulatory justification blocks; ceiling deck protocols; reclean/retest procedures; deliverable consolidation; appendix restructure |
+| 4.0.1 | January 2026 | EAA Method Guide integration: combustion particle definitions (soot/char/ash); qualitative observation checklist; unit conversion reference (cts/mm² to cts/cm²); EAA classification cross-reference |
+
+---
+
+## Executive Summary
+
+FDAM is a systematic framework for assessing fire-damaged properties and generating scientifically defensible restoration documentation. The methodology synthesizes regulatory standards, industry guidance, and empirical field data from IHC fire restoration projects.
+
+**FDAM produces three deliverables:**
+
+1. **Cleaning Specification / Scope of Work** — Scope, methods, labor, equipment, and acceptance criteria
+2. **Results Interpretation** — Threshold justification, regulatory basis, and pass/fail determination
+3. **Executive Summary Report** — Completion verification and compliance documentation
+
+**Standards Basis:**
+- Metals clearance: BNL SOP IH75190 (Rev23, 06/23/17)
+- Non-Operational alternative: Army/Air Force National Guard Indoor Firing Range Guidelines (200 µg/ft²)
+- Air filtration: NADCA ACR 2021 (4 ACH minimum)
+- Zone framework: IICRC/RIA/CIRI Technical Guide (December 2025)
+- Particulate clearance: IHC professional judgment with empirical validation
+
+---
+
+## Part 1: Methodology Foundation
+
+### 1.1 Scientific Basis
+
+FDAM synthesizes:
+
+- **Regulatory frameworks:** OSHA Technical Manual, NIOSH sampling methods, EPA clearance standards
+- **Industry standards:** IICRC S700/S760, IICRC/RIA/CIRI Technical Guide, NADCA ACR, RIA Fire & Smoke Damage Repair
+- **Published guidance:** BNL SOP IH75190, AIHA Technical Guide for Wildfire Impact Assessments
+- **Empirical validation:** IHC field data from commercial fire restoration projects (see Appendix B)
+
+### 1.2 Regulatory Framework
+
+| Source | Application | Status |
+|--------|-------------|--------|
+| BNL SOP IH75190 (Rev23) | Surface wipe clearance for metals | **Primary - verified** |
+| Army/Air Force National Guard Guidelines | Non-Operational lead alternative (200 µg/ft²) | **Primary - verified** |
+| EPA/HUD Lead Dust Hazard Standards (October 2024) | Public/Childcare lead clearance | **Primary - verified** |
+| OSHA Technical Manual, Section II Ch. 2 | Surface contaminant methodology, facility classification | Referenced |
+| NIOSH Method 9100 | Surface wipe sampling procedures | Referenced |
+| 29 CFR 1910.1025 | Lead housekeeping requirements | Referenced |
+| 29 CFR 1910.1018 | Arsenic housekeeping requirements | Referenced |
+| 29 CFR 1910.1027 | Cadmium housekeeping requirements | Referenced |
+| NADCA ACR 2021 | Air filtration requirements | **Primary - verified** |
+| IICRC/RIA/CIRI Technical Guide (Dec 2025) | Zone-based assessment | **Primary - verified** |
+| IICRC S520 | Mold remediation (cross-reference for fungal co-occurrence) | Referenced |
+
+### 1.3 Threshold Classification
+
+**Standards-Based Thresholds:** Values from published, peer-reviewed, or regulatory sources with explicit citations.
+
+**Professional Judgment Thresholds:** Values developed through field experience where no published standards exist. Explicitly labeled with empirical validation data where available.
+
+### 1.4 Metals Clearance Thresholds
+
+**Source:** BNL SOP IH75190, Attachment 9.3 (Rev23, 06/23/17)
+
+| Metal | Non-Operational | Operational | Unit | Regulatory Basis |
+|-------|-----------------|-------------|------|------------------|
+| Lead (Pb) | 22 | 500 | µg/100cm² | 29 CFR 1910.1025 |
+| Cadmium (Cd) | 3.3 | 50 | µg/100cm² | 29 CFR 1910.1027 |
+| Arsenic (As) | 6.7 | 100 | µg/100cm² | 29 CFR 1910.1018 |
+
+**Unit Conversions:**
+- µg/100cm² × 9.29 = µg/ft²
+- Lead Non-Op: 22 µg/100cm² ≈ 204 µg/ft²
+
+**Alternative Non-Operational Reference:**
+Army and Air Force National Guard "Guidelines and Procedures for Rehabilitation and Conversion of Indoor Firing Ranges" establishes 200 µg/ft² as acceptable surface contamination for spaces converted to general use. This is consistent with BNL Non-Operational threshold (22 µg/100cm² ≈ 204 µg/ft²).
+
+**Public/Childcare Thresholds (EPA/HUD October 2024):**
+
+| Surface | Threshold | Unit |
+|---------|-----------|------|
+| Floors | 0.54 | µg/100cm² |
+| Window Sills | 4.3 | µg/100cm² |
+| Window Troughs | 4.3 | µg/100cm² |
+
+### 1.5 Combustion Particle Definitions
+
+Fire/combustion residue particles are classified into three categories based on combustion process:
+
+| Category | Definition | Morphology |
+|----------|------------|------------|
+| **Soot** | Residues from combustion of organic resins and compounds | Aciniform (grape-like clusters); fine spherical particles; optically opaque |
+| **Char** | Incomplete combustion of cellulose/vegetation material | Irregular angular fragments; carbonized plant structure visible; variable size |
+| **Ash** | Residual mineral elements remaining after complete combustion (Ca, Na, Mg, K salts) | Irregular crystalline; often white/gray; variable opacity |
+
+Source: Environmental Analysis Associates, Air-O-Cell Method Guide & Particle Atlas (2018)
+
+**Laboratory Reporting Note:** Some laboratories report "Ash and Char" as a combined category. When combined reporting is used, interpret results against the Ash/Char threshold. When separated, sum the values for threshold comparison unless laboratory provides specific guidance.
+
+### 1.6 Particulate Clearance Thresholds
+
+**Classification:** Professional Judgment with Empirical Validation
+
+| Analyte | Clearance Threshold | Unit | Validation Status |
+|---------|---------------------|------|-------------------|
+| Ash and Char (combined) | < 150 | particles/cm² | Validated (97.8% pass rate, n=45) |
+| Aciniform Soot | < 500 | particles/cm² | Validated (91.1% pass rate, n=45) |
+| Cellulose/Synthetic Fibers | < 500 | particles/cm² | Professional judgment |
+| Silicates | < 1,500 | particles/cm² | Professional judgment |
+
+**Laboratory Reference Comparison:**
+
+| Particle Type | Lab "Normal" Range | FDAM Clearance | Position |
+|---------------|-------------------|----------------|----------|
+| Ash/Char | 0-300/cm² | < 150/cm² | 50% of upper normal |
+| Aciniform Soot | 0-800/cm² | < 500/cm² | 62.5% of upper normal |
+
+Source: Hayes Microbial Consulting, Estimated Normal Ranges based on ASTM D6602
+
+FDAM clearance thresholds are set below laboratory "normal" ranges to ensure post-restoration surfaces are demonstrably cleaner than typical unaffected environments.
+
+**Empirical Validation Summary:**
+- Dataset: 45 post-restoration samples (QVC Distribution Center, March 2023)
+- Pass rate at current thresholds: 93.3%
+- Typical achievable post-cleaning levels: 5-15/cm² (both particle types)
+- See Appendix B for complete analysis
+
+**Application:**
+- Evaluate in conjunction with visual inspection and odor assessment
+- Compare to control/background samples from unaffected areas
+- Results interpreted by qualified industrial hygienist
+
+---
+
+## Part 2: Assessment Workflow
+
+### 2.1 Project Phases
+
+```
+PHASE 1: PRE (Pre-Restoration Evaluation)
+├── Site inspection and documentation
+├── Contamination mapping
+├── Material inventory
+├── Zone classification (Burn/Near-Field/Far-Field)
+└── Output: Preliminary findings, PRA recommendation
+
+PHASE 2: PRA (Pre-Restoration Assessment)
+├── Sampling plan development
+├── Tape lift and surface wipe collection
+├── Laboratory analysis
+├── Results interpretation
+└── Output: CLEANING SPECIFICATION / SCOPE OF WORK
+
+PHASE 3: RESTORATION (Contractor Execution)
+├── Work performed per specification
+└── Output: Completion notification
+
+PHASE 4: PRV (Post-Restoration Verification)
+├── Verification sampling
+├── Laboratory analysis
+├── Pass/fail determination
+├── Reclean/retest if required
+└── Output: EXECUTIVE SUMMARY REPORT
+```
+
+### 2.2 Phase 1: Pre-Restoration Evaluation (PRE)
+
+**Field Activities:**
+
+| Activity | Method | Data Captured |
+|----------|--------|---------------|
+| Site walk-through | Visual inspection | Affected areas, impact severity by zone |
+| Odor assessment | Sensory | Presence/intensity/location of smoke odor |
+| White wipe test | Clean cloth on surfaces | Preliminary contamination indicator |
+| Photo documentation | Camera/device | Conditions, damage, access constraints |
+| Material inventory | Visual identification | Surface types, quantities, restorability |
+| Dimensional survey | Manual measurement | Room dimensions, surface areas |
+| Zone classification | Distance from fire origin | Burn Zone / Near-Field / Far-Field |
+
+**PRE Decision Logic:**
+
+```
+IF visible contamination is widespread
+   OR odor is significant
+   OR white wipe test shows deposits
+   OR materials of concern present
+   OR property is in Burn Zone or Near-Field Zone
+THEN → Recommend PRA (laboratory assessment)
+
+IF contamination is superficial
+   AND limited to small area
+   AND no materials of concern
+   AND Far-Field Zone only
+THEN → May proceed directly to cleaning specification
+```
+
+### 2.3 Phase 2: Pre-Restoration Assessment (PRA)
+
+**Sampling Protocol:**
+
+*Tape Lift Samples (Particulate Identification):*
+- Minimum 1 per distinct surface type per zone
+- Additional samples at contamination gradients
+- Control samples from unaffected areas (recommended)
+- Analysis: Polarized light microscopy (PLM)
+
+*Surface Wipe Samples (Metals Quantification):*
+- Per NIOSH Method 9100 / BNL SOP IH75190
+- 100 cm² sample area (10cm × 10cm template)
+- Ghost Wipes or equivalent pre-moistened media
+- Analysis: ICP-MS or ICP-OES at AIHA-accredited laboratory
+
+**Sample Density Guidelines:**
+
+| Area Size | Tape Lifts | Surface Wipes |
+|-----------|------------|---------------|
+| < 5,000 SF | 3-5 per surface type | 3-5 per surface type |
+| 5,000 - 25,000 SF | 5-10 per surface type | 5-10 per surface type |
+| 25,000 - 100,000 SF | 10-20 per surface type | 10-15 per surface type |
+| > 100,000 SF | 20+ per surface type | 15-25 per surface type |
+
+**Ceiling Deck Sample Density (Enhanced):**
+Empirical data indicates ceiling deck surfaces exhibit higher post-cleaning contamination rates (82.4% pass rate vs 95%+ for other structural surfaces). For ceiling decks:
+- Increase sample density by 50% above standard guidelines
+- Minimum 1 sample per 2,500 SF (vs standard 1 per 5,000 SF)
+
+**Qualitative Observation Checklist:**
+
+Document the following at each sample location:
+
+| Observation | Response | Notes |
+|-------------|----------|-------|
+| Smoke/fire odor present? | Yes / No | Intensity if present |
+| Visible soot deposits? | Yes / No | Describe pattern |
+| Large char particles observed? | Yes / No | Estimated density |
+| Ash-like residue present? | Yes / No | Color, texture |
+| Surface discoloration? | Yes / No | Describe |
+| Dust loading or interference? | Yes / No | May affect lab accuracy |
+| Burned soil/pollen/vegetation indicators? | Yes / No | Wildfire indicator |
+
+This checklist supports visual-to-lab correlation and identifies potential analytical interferences.
+
+### 2.4 Phase 4: Post-Restoration Verification (PRV)
+
+**Verification Protocol:**
+1. Visual inspection for dust-free surfaces
+2. Odor assessment (no detectable fire/smoke odor)
+3. Verification sampling (same methods as PRA)
+4. Laboratory analysis
+5. Results comparison to clearance criteria
+6. Pass/fail determination by area
+
+**PRV Decision Logic:**
+
+```
+IF all samples pass clearance thresholds
+   AND visual inspection confirms dust-free
+   AND no detectable odor
+THEN → Issue clearance, generate Executive Summary
+
+IF any samples exceed thresholds
+THEN → Execute Reclean/Retest Protocol (Section 5.4)
+```
+
+---
+
+## Part 3: Facility Classification
+
+### 3.1 Classification Categories
+
+| Classification | Definition | Lead Threshold | Applicable Standards |
+|----------------|------------|----------------|---------------------|
+| Operational | OSHA regulated substance used; workers trained; hygiene controls in place | 500 µg/100cm² | BNL SOP IH75190 Operational |
+| Non-Operational | No regulated substance use; workers not trained; eating/drinking permitted | 22 µg/100cm² | BNL SOP IH75190 Non-Operational |
+| Public-Childcare | Schools, daycare, child-occupied facilities | 0.54 µg/100cm² (floors) | EPA/HUD October 2024 |
+
+### 3.2 Classification Determination
+
+Facility classification is a professional judgment decision documented in the Results Interpretation deliverable. The determination considers:
+
+- Facility use and occupancy type
+- Presence of OSHA regulated substances
+- Worker training status
+- Personal hygiene controls (eating/drinking restrictions, handwashing requirements)
+- Occupant populations (children, general public, trained workers)
+
+### 3.3 Regulatory Justification Blocks
+
+**Non-Operational Commercial/Industrial:**
+
+> The indoor environment within [FACILITY] is comparable to the definition of a "Non-Operational Area" per OSHA Technical Manual Section II Chapter 2: an area where an OSHA Regulated Substance is not used and where workers are not trained in hazards and controls. Personal hygiene control practices are not in place (hand washing is not expected on exiting the area) and eating & drinking are permitted.
+>
+> The applicable standard for measuring cleaning performance is derived from BNL SOP IH75190 "Surface Wipe Sampling for Metals" (Rev23, 06/23/17), which establishes 22 µg/100cm² (≈204 µg/ft²) for Non-Operational areas. This threshold is consistent with the Army and Air Force National Guard "Guidelines and Procedures for Rehabilitation and Conversion of Indoor Firing Ranges" which establishes 200 µg/ft² as acceptable for spaces converted to general use.
+>
+> OSHA housekeeping provisions (29 CFR 1910.1025, 1910.1018, 1910.1027) require surfaces be maintained "as free as practicable" of accumulations of regulated metals.
+
+**Operational Industrial:**
+
+> [FACILITY] meets the definition of an "Operational Area" per OSHA Technical Manual Section II Chapter 2: an area where workers are routinely in the presence of an OSHA Regulated Substance as part of their work activity. Workers who handle the substance have been trained in hazards and controls. Substances are routinely used, handled or stored and personal hygiene control practices are in place.
+>
+> The applicable standard is BNL SOP IH75190 Operational threshold of 500 µg/100cm² for lead.
+
+**Public-Childcare:**
+
+> [FACILITY] is classified as a child-occupied facility subject to EPA/HUD Lead Dust Hazard Standards (October 2024). These standards establish protective thresholds for environments where children may be present.
+>
+> Applicable thresholds: 0.54 µg/100cm² (floors), 4.3 µg/100cm² (window sills and troughs).
+
+---
+
+## Part 4: Surface Assessment
+
+### 4.1 Zone Classification
+
+**Source:** IICRC/RIA/CIRI Technical Guide for Wildfire Restoration (December 2025)
+
+| Zone | Definition | Typical Characteristics |
+|------|------------|------------------------|
+| Burn Zone | Direct fire involvement | Structural damage, char, complete combustion |
+| Near-Field | Adjacent to burn zone, heavy smoke/heat exposure | Heavy soot deposits, heat damage, strong odor |
+| Far-Field | Smoke migration without direct heat exposure | Light to moderate deposits, odor, no structural damage |
+
+### 4.2 Condition Scale
+
+| Condition | Visual Indicators |
+|-----------|-------------------|
+| Background | No visible contamination; equivalent to unaffected areas |
+| Light | Faint discoloration; minimal deposits visible on white wipe |
+| Moderate | Visible film or deposits; clear contamination on white wipe |
+| Heavy | Thick deposits; surface texture obscured; strong odor |
+| Structural Damage | Physical damage requiring repair before cleaning |
+
+### 4.3 Disposition Matrix
+
+**Non-Porous Surfaces (Steel, Concrete, Glass, Metal):**
+
+| Zone | Condition | Disposition | Protocol |
+|------|-----------|-------------|----------|
+| Any | Background | No action | Document only |
+| Far-Field | Light | Clean | Standard protocol |
+| Far-Field | Moderate | Clean | Full protocol |
+| Near-Field | Light | Clean | Full protocol |
+| Near-Field | Moderate | Clean | Aggressive protocol, multiple passes |
+| Near-Field | Heavy | Clean | Aggressive protocol with verification sampling |
+| Burn Zone | Any restorable | Clean | Post-structural repair; aggressive protocol |
+| Any | Structural Damage | Remove/Repair | Beyond cleaning scope |
+
+**Porous/Semi-Porous Surfaces (Drywall, Carpet, Insulation, Acoustic Tile):**
+
+| Zone | Condition | Disposition | Rationale |
+|------|-----------|-------------|-----------|
+| Far-Field | Background | Evaluate | May clean if truly superficial |
+| Far-Field | Light | Evaluate/Clean | Assessment determines restorability |
+| Far-Field | Moderate+ | Remove | Porous materials absorb contaminants |
+| Near-Field | Light+ | Remove | Porous materials absorb contaminants and VOCs |
+| Burn Zone | Any | Remove | Cannot effectively decontaminate |
+
+### 4.4 Material Disposition Categories
+
+**Tier 1: Generally Replace When Fire/Smoke Affected**
+
+| Material | Rationale |
+|----------|-----------|
+| Fiberglass insulation | Absorbs particulates and VOCs into fiber matrix |
+| Flexible ductwork | Interior lining absorbs contaminants; cannot effectively clean |
+| HVAC duct interior insulation | Porous material in air pathway; recontamination risk |
+| Mattresses and bedding | Multi-layer foam construction; deep penetration |
+
+**Tier 2: Assess Based on Condition**
+
+| Material | Clean When | Remove When |
+|----------|------------|-------------|
+| Carpet and pad | Far-Field, Light | Near-Field, Moderate+ |
+| Drop ceiling tile | Far-Field, Light, smooth | Near-Field, or textured/acoustic |
+| Drywall (painted) | Far-Field, Light | Near-Field Moderate+, or unpainted |
+| Upholstered furniture | Far-Field, Light, high value | Near-Field, or low value |
+
+**Tier 3: Generally Cleanable**
+
+| Material | Standard Protocol |
+|----------|-------------------|
+| Structural steel | HEPA vac → wet wipe → rinse |
+| Concrete (sealed) | Scrubber or power wash |
+| Metal doors/frames | Wet wipe → rinse |
+| Glass/windows | Wet wipe → squeegee |
+| Smooth rigid ductwork | Per NADCA ACR |
+
+### 4.5 Ceiling Deck Protocol
+
+Empirical data indicates ceiling deck surfaces require enhanced attention:
+
+**Finding:** 82.4% pass rate for ceiling decks vs 95%+ for other structural surfaces (n=45, QVC dataset)
+
+**Requirements:**
+- Increase PRV sample density by 50%
+- Consider additional cleaning pass before PRV
+- Document access method and cleaning thoroughness
+- Priority surface for reclean if failures occur
+
+### 4.6 Secondary Contamination
+
+If fungal/mold growth is identified during fire damage assessment:
+- Document presence, type, and extent
+- Cross-reference IICRC S520 for remediation protocols
+- Address fire damage and biological contamination as separate scopes
+- Sequential remediation may be required (mold first if active growth)
+
+---
+
+## Part 5: Cleaning Protocol Framework
+
+### 5.1 Standard Cleaning Sequence
+
+```
+Step 1: HEPA Vacuum
+        └── Remove loose particulate from all surfaces
+        
+Step 2: Dry Sponge (if needed)
+        └── Chemical sponge for char/soot on non-porous surfaces
+        
+Step 3: Wet Wipe - Alkaline Detergent
+        └── pH 10-12 solution for chemical residue removal
+        
+Step 4: Rinse Wipe
+        └── Clean water to remove detergent residue
+        
+Step 5: Degreaser (if needed)
+        └── For stubborn residues not removed by standard protocol
+```
+
+**Sequencing Rule:** Clean top-down (roof deck → structure → walls → floor) to prevent recontamination.
+
+### 5.2 Surface-Specific Methods
+
+| Surface Type | Standard Method |
+|--------------|-----------------|
+| Steel roof deck | HEPA vac → Wet wipe → Rinse |
+| Steel joists/beams | HEPA vac → Wet wipe → Rinse |
+| Steel columns | HEPA vac → Wet wipe → Rinse |
+| Concrete floor | Scrubber machine + alkaline |
+| CMU walls | HEPA vac → Wet wipe OR power wash |
+| Metal doors | Wet wipe → Rinse |
+| Rigid ductwork | Per NADCA ACR |
+
+### 5.3 Air Filtration Requirements
+
+**Source:** NADCA ACR 2021 Edition, Section 3.6
+
+**Minimum Requirement:** 4 air changes per hour (ACH)
+
+**Calculation:**
+```
+Units Required = (Volume CF × 4 ACH) / (Unit CFM × 60)
+
+Where:
+  Volume CF = Area SF × Ceiling Height FT
+  Unit CFM = Rated capacity of air scrubber
+```
+
+**Example:**
+```
+Work Area: 50,000 SF × 30 FT = 1,500,000 CF
+Units = (1,500,000 × 4) / (2,000 CFM × 60) = 50 units
+```
+
+### 5.4 Reclean/Retest Protocol
+
+When PRV samples exceed clearance thresholds:
+
+**Step 1: Identify Deficient Areas**
+- Map failed sample locations
+- Determine surface types affected
+- Assess pattern (localized vs widespread)
+
+**Step 2: Reclean Specification**
+```
+Failed surfaces at [SAMPLE LOCATIONS] require additional cleaning:
+- [SURFACE TYPE]: Execute [PROTOCOL] with additional pass
+- Extend cleaning 10 feet beyond failed sample locations
+- Document cleaning date, method, and personnel
+```
+
+**Step 3: Retest Protocol**
+- Resample at original failed locations
+- Add samples at adjacent locations if pattern suggests broader issue
+- Same laboratory and analytical methods as original PRV
+
+**Step 4: Documentation**
+- Reference original sample numbers and results
+- Document reclean activities
+- Report retest results with comparison to original
+
+**Iteration:** Repeat until all samples pass clearance thresholds.
+
+---
+
+## Part 6: Documentation Outputs
+
+### 6.1 Deliverable 1: Cleaning Specification / Scope of Work
+
+**Purpose:** Define scope, methods, labor, equipment, and acceptance criteria for contractor execution.
+
+**Required Sections:**
+
+| Section | Content |
+|---------|---------|
+| Project Identification | Facility, address, contact, dates |
+| Scope Summary | Affected areas, zone classifications, total SF by disposition |
+| Surface Inventory | Itemized surfaces by type, area, condition, disposition |
+| Work Area Preparation | Containment, air filtration calculations (4 ACH minimum) |
+| Surface-Specific Procedures | Cleaning methods by surface type |
+| Removal Scope | Materials requiring removal with quantities |
+| Labor Estimate | Hours by task, production rates applied |
+| Equipment Requirements | Air scrubbers, lifts, supplies with quantities |
+| Quality Assurance Criteria | Pass/fail thresholds for PRV |
+| Worker Protection | PPE, safety protocols |
+
+**Ceiling Deck Emphasis:** When ceiling decks are in scope, include:
+- Note regarding enhanced sample density at PRV
+- Recommendation for additional cleaning pass
+- Access method requirements
+
+### 6.2 Deliverable 2: Results Interpretation
+
+**Purpose:** Establish applicable thresholds with regulatory justification and determine pass/fail status.
+
+**Required Sections:**
+
+| Section | Content |
+|---------|---------|
+| Purpose Statement | Why interpretation needed, specific questions addressed |
+| Facility Classification | Operational / Non-Operational / Public-Childcare determination |
+| Regulatory Framework | Applicable standards with citations |
+| Regulatory Justification | Justification block per Section 3.3 |
+| Recommended Thresholds | Specific values with source citations |
+| Results Comparison | Actual data vs thresholds |
+| Pass/Fail Determination | By sample, by area, overall |
+| Reclean Requirements | If applicable, per Section 5.4 |
+| Response to Inquiries | Address specific stakeholder questions if applicable |
+
+**Standards Basis Statement (Required):**
+> Metals thresholds are standards-based per BNL SOP IH75190. Particulate thresholds represent professional judgment with empirical validation (see FDAM Appendix B).
+
+### 6.3 Deliverable 3: Executive Summary Report
+
+**Purpose:** Document completion and compliance for closeout.
+
+**Required Sections:**
+
+| Section | Content |
+|---------|---------|
+| Project Summary | Identification, scope performed, conclusions |
+| Clearance Confirmation | Statement that all areas passed clearance criteria |
+| Discussion of Results | Testing summary, any reclean/retest activities |
+| Threshold Reference | Thresholds applied with regulatory basis |
+| Chronology | Timeline of assessment, cleaning, verification |
+| Appendices | Lab reports, photos, field documentation |
+| Standard of Care | Professional limitations |
+| Standards Basis Statement | Per Section 6.2 |
+
+---
+
+## Part 7: Validation Requirements
+
+### 7.1 Threshold Validation Status
+
+| Category | Status | Source | Validation |
+|----------|--------|--------|------------|
+| Metals (Pb, Cd, As) | **Verified** | BNL SOP IH75190 | Standards-based |
+| Particulates | **Validated** | IHC + empirical data | 93.3% pass rate (n=45) |
+| ACH requirements | **Verified** | NADCA ACR 2021 | Standards-based |
+| Sample density | Professional Judgment | Internal guidance | Ongoing refinement |
+
+### 7.2 Validation Criteria
+
+Thresholds are validated when:
+- >90% first-pass clearance rate with proper cleaning
+- <5% false negatives
+- Correlation with absence of occupant complaints post-restoration
+
+### 7.3 Ongoing Data Collection
+
+For threshold refinement, collect:
+- Condition assessment + lab result + clearance outcome (paired)
+- Surface type performance data
+- Reclean frequency by surface type
+- Control/background sample baselines
+
+---
+
+## Part 8: System Architecture
+
+### 8.1 SmokeScan Implementation
+
+```
+FIELD DEVICE
+├── Project/building/zone/room hierarchy
+├── Zone classification with distance documentation
+├── Surface inventory (type, material, condition, area)
+├── Photo capture with metadata
+├── Sample location documentation
+└── Offline capability with sync
+
+CLOUD PLATFORM
+├── Project data management
+├── Lab result entry and threshold comparison
+├── SOW calculations (quantities, labor, equipment)
+├── Document generation
+├── Pass/fail determination with threshold source flagging
+└── Report export
+```
+
+### 8.2 Calculation Engine
+
+**Surface Area Aggregation:**
+```
+Total by Type = Σ(Surface.area) WHERE Surface.type = [type]
+Total by Disposition = Σ(Surface.area) WHERE Surface.disposition = [action]
+```
+
+**Equipment Sizing:**
+```
+Air Scrubbers = (Total Volume × 4 ACH) / (Unit CFM × 60)
+```
+
+**Pass/Fail Determination:**
+```
+FOR each Result:
+  Threshold = Lookup(Analyte, Classification)
+  ThresholdSource = Lookup(Analyte, Source)
+  IF Result < Threshold THEN Pass ELSE Fail
+  FLAG if ThresholdSource = "Professional Judgment"
+```
+
+---
+
+## Part 9: Future Research
+
+### 9.1 Field Screening Methods
+
+**Optical Density Approach:**
+Develop calibrated visual assessment correlating reflectance measurements to contamination levels.
+
+**Research Questions:**
+- Can OD measurements correlate with tape lift particle counts?
+- What calibration protocol provides reliable results?
+
+### 9.2 Control Sample Protocol
+
+**Decision Required:** Determine whether control/background samples should be mandatory for relative comparison, or if absolute thresholds are sufficient.
+
+**Options:**
+- A: Mandatory control sample with relative pass/fail logic
+- B: Control samples recommended but absolute thresholds authoritative
+- C: Control samples required only for disputed results
+
+### 9.3 Surface-Specific Threshold Refinement
+
+With additional data collection, evaluate whether surface-specific thresholds are warranted (e.g., tighter thresholds for ceiling decks given higher failure rates).
+
+---
+
+## Appendix A: Lab Result Interpretation Framework
+
+### A.1 Supported Laboratory Formats
+
+FDAM supports two primary laboratory reporting formats:
+
+**Format 1: Quantitative (particles/cm²)**
+- Labs: Hayes Microbial, EMSL, others
+- Direct comparison to FDAM thresholds
+- Preferred format for pass/fail determination
+
+**Format 2: Semi-Quantitative (% particles per field at 400x)**
+- Labs: N.G. Carlson Analytical, EAA Baxter methodology
+- Requires interpretation guidance
+- Methodological differences from Format 1
+
+### A.2 Format 1: Quantitative Interpretation
+
+Direct threshold comparison:
+
+| Analyte | Result | Threshold | Determination |
+|---------|--------|-----------|---------------|
+| Ash/Char | [value]/cm² | < 150/cm² | PASS if < 150 |
+| Aciniform Soot | [value]/cm² | < 500/cm² | PASS if < 500 |
+
+### A.3 Format 2: Semi-Quantitative Interpretation
+
+**Source:** EAA Air-O-Cell Method Guide & Particle Atlas (2018); EMSL Fire & Smoke Damage Guide 2021
+
+| % per Field (400x) | Lab Interpretation | FDAM Guidance |
+|--------------------|-------------------|---------------|
+| < 1% | Typical low | Presumed PASS - consistent with clearance |
+| < 3% | Upper background | Presumed PASS - within acceptable range |
+| 3-10% | Moderate impact | Professional judgment required |
+| > 10% | Significant impact | Presumed FAIL - additional cleaning likely required |
+
+**Methodological Caveat:**
+Percentage-per-field and particles/cm² are fundamentally different analytical approaches. The guidance above represents professional correlation, not mathematical conversion. When results fall in the 3-10% range, consider:
+- Visual condition at sample location
+- Comparison to control samples
+- Overall project context
+- Retesting with quantitative methodology if determination is critical
+
+### A.4 Decision Logic
+
+```
+INPUT: Lab Result + Format + Facility Classification
+
+STEP 1: Identify Format
+  IF particles/cm² → Use A.2 direct comparison
+  IF % per field → Use A.3 interpretation guidance
+
+STEP 2: Determine Threshold
+  Metals → Per Facility Classification (Section 3.1)
+  Particulates → Standard thresholds (Section 1.6)
+
+STEP 3: Compare and Determine
+  IF Result < Threshold → PASS
+  IF Result > Threshold → FAIL
+  IF Semi-quantitative in judgment range → Flag for professional review
+
+STEP 4: Document
+  Record result, threshold, source, determination
+  Flag professional judgment thresholds
+```
+
+### A.5 Laboratory Selection Guidance
+
+When selecting laboratories:
+- Confirm reporting format before submission
+- Request particles/cm² format when available
+- Ensure consistent methodology across PRA and PRV sampling
+- Request differentiation notes if atypical particles observed
+
+### A.6 Unit Conversion Reference
+
+Laboratories may report surface particle concentrations in different units. Use the following conversions:
+
+**Area Conversions:**
+```
+1 cm² = 100 mm²
+cts/mm² × 100 = cts/cm²
+cts/cm² ÷ 100 = cts/mm²
+```
+
+**Common Laboratory Unit Formats:**
+
+| Lab Format | Unit | Conversion to FDAM (cts/cm²) |
+|------------|------|------------------------------|
+| Hayes Microbial | cts/cm² | Direct comparison |
+| EAA | cts/mm² | Multiply by 100 |
+| N.G. Carlson | % per field | Use Appendix A.3 guidance |
+
+**Example Conversion:**
+- EAA reports: 5.0 cts/mm² fire residue
+- FDAM equivalent: 5.0 × 100 = 500 cts/cm²
+- Threshold comparison: 500 cts/cm² vs <150 (Ash/Char) = FAIL
+
+**EAA Classification to FDAM Threshold Comparison:**
+
+| EAA Classification | EAA (cts/mm²) | Converted (cts/cm²) | FDAM Status |
+|--------------------|---------------|---------------------|-------------|
+| Low | <1.0 | <100 | PASS |
+| Typical-low | 1.0-5.0 | 100-500 | Evaluate vs threshold |
+| Low-moderate | 5.0-10 | 500-1,000 | Likely FAIL |
+| Moderate | 10-50 | 1,000-5,000 | FAIL |
+| High | >50 | >5,000 | FAIL |
+
+FDAM clearance thresholds (150 cts/cm² ash/char, 500 cts/cm² aciniform) fall within or at the upper boundary of EAA's "Typical-low" classification (100-500 cts/cm²), confirming FDAM thresholds are appropriately conservative for post-restoration clearance.
+
+---
+
+## Appendix B: Empirical Validation Data
+
+### B.1 QVC Distribution Center Dataset
+
+**Project:** QVC Outbound Fire Loss Restoration  
+**Location:** Rocky Mount, NC  
+**Date:** March 2023  
+**Sample Type:** Post-Restoration Verification (PRV)  
+**Sample Count:** 45 Bio-Tape samples (1.00 cm²)  
+**Laboratory:** Hayes Microbial Consulting  
+**Facility Classification:** Non-Operational Commercial
+
+### B.2 Results Summary
+
+**Aciniform-like Soot:**
+
+| Statistic | Value |
+|-----------|-------|
+| Non-Detect | 21 samples (46.7%) |
+| Range (detected) | 1 - 2,200/cm² |
+| Median (detected) | 4.5/cm² |
+| 90th Percentile | 65/cm² |
+| Pass Rate | 91.1% (41/45) |
+
+**Ash and Char:**
+
+| Statistic | Value |
+|-----------|-------|
+| Non-Detect | 2 samples (4.4%) |
+| Range (detected) | 1 - 440/cm² |
+| Median (detected) | 5/cm² |
+| 90th Percentile | 60/cm² |
+| Pass Rate | 97.8% (44/45) |
+
+**Combined Pass/Fail:**
+
+| Status | Count | Percentage |
+|--------|-------|------------|
+| Both Pass | 42 | 93.3% |
+| Any Fail | 3 | 6.7% |
+
+### B.3 Surface Type Analysis
+
+| Surface Type | Samples | Pass Rate |
+|--------------|---------|-----------|
+| Ceiling Deck (CD) | 17 | 82.4% |
+| Ceiling Joist (CJ) | 20 | 95.0% |
+| Beam | 6 | 100% |
+| Column | 1 | 100% |
+| Pipe | 1 | 100% |
+
+**Finding:** Ceiling decks exhibit significantly lower pass rates, driving the ceiling deck emphasis protocol in Section 4.5.
+
+### B.4 Failed Sample Analysis
+
+| Sample | Location | Aciniform | Ash/Char | Failure |
+|--------|----------|-----------|----------|---------|
+| 02 | B2-C2 Grid - Ceiling Deck | 2,200/cm² | 4/cm² | Aciniform |
+| 06 | D2-E2 Grid - Ceiling Deck | 1,320/cm² | 15/cm² | Aciniform |
+| 12 | E3-F3 Grid - CJ Horizontal | 8/cm² | 440/cm² | Ash/Char |
+
+All failures were addressed through reclean/retest protocol and subsequently passed.
+
+### B.5 Laboratory Reference Ranges
+
+**Source:** Hayes Microbial Consulting, based on ASTM D6602
+
+| Particle Type | Normal Surface Range |
+|---------------|---------------------|
+| Ash/Char | 0-300/cm² |
+| Aciniform Soot | 0-800/cm² |
+| Cellulose Fibers | 0-1,600/cm² |
+| Synthetic Fibers | 0-1,600/cm² |
+| Silicates | 0-2,800/cm² |
+
+These ranges represent typical environments, not post-fire clearance criteria. FDAM thresholds are set below these ranges to ensure demonstrably clean post-restoration conditions.
+
+### B.6 Our Lady of Victory Dataset
+
+**Project:** Our Lady of Victory (Catholic School)  
+**Location:** Minnesota  
+**Date:** February 2025  
+**Sample Type:** Assessment  
+**Sample Count:** 55 tease-tape samples  
+**Laboratory:** N.G. Carlson Analytical  
+**Facility Classification:** Public-Childcare
+
+**Methodology:** Semi-quantitative (% particles per field at 400x)
+
+**Distribution by Impact Level:**
+
+| Impact Level | Samples | Percentage |
+|--------------|---------|------------|
+| No Char/No Soot | 14 | 27% |
+| Typical Low (<1%) | 25 | 48% |
+| Upper Background (<3%) | 7 | 13% |
+| Moderate (3-10%) | 5 | 10% |
+| Significant (>10%) | 1 | 2% |
+
+**Pattern Observation:** Basement and lower-level areas showed higher contamination, consistent with smoke stratification.
+
+---
+
+## Appendix C: Deliverable Templates
+
+### C.1 Cleaning Specification / SOW - Key Language Blocks
+
+**Scope Statement:**
+> [FACILITY] sustained fire damage on [DATE]. Industrial Hygiene Consulting, Corp. (IHC) conducted Pre-Restoration Assessment on [DATE]. Based on laboratory analysis and field assessment, the following cleaning specification establishes scope, methods, and acceptance criteria for fire residue restoration.
+
+**Zone Summary Table:**
+```
+| Zone | Area (SF) | Condition | Disposition |
+|------|-----------|-----------|-------------|
+| [Zone ID] | [SF] | [Condition] | Clean/Remove |
+```
+
+**Air Filtration Calculation:**
+> Work area volume: [SF] × [Height] = [CF]  
+> Required ACH: 4 (NADCA ACR 2021)  
+> Air scrubber capacity: [CFM] per unit  
+> Units required: ([CF] × 4) / ([CFM] × 60) = [Units]
+
+**Acceptance Criteria:**
+> Post-restoration verification sampling will be conducted per FDAM methodology. Clearance thresholds:
+> - Ash and Char: < 150 particles/cm²
+> - Aciniform Soot: < 500 particles/cm²
+> - Lead: [Threshold] µg/100cm² per [Classification] standards
+>
+> Surfaces exceeding thresholds require reclean and retest until passing.
+
+### C.2 Results Interpretation - Key Language Blocks
+
+**Purpose Statement:**
+> IHC provides this results interpretation to establish applicable clearance thresholds for [FACILITY] based on facility classification and regulatory framework.
+
+**Classification Determination:**
+> [Insert applicable regulatory justification block from Section 3.3]
+
+**Threshold Table:**
+```
+| Analyte | Threshold | Unit | Source |
+|---------|-----------|------|--------|
+| Lead | [value] | µg/100cm² | [BNL/EPA-HUD] |
+| Ash/Char | 150 | particles/cm² | IHC/FDAM |
+| Aciniform | 500 | particles/cm² | IHC/FDAM |
+```
+
+**Pass/Fail Summary:**
+> Of [N] samples collected, [X] passed all clearance thresholds. [Y] samples exceeded thresholds and require reclean/retest per Section 5.4.
+
+**Standards Basis Statement:**
+> Metals thresholds are standards-based per BNL SOP IH75190 (Rev23, 06/23/17). Particulate thresholds represent professional judgment developed through IHC field experience with empirical validation (93.3% pass rate, n=45).
+
+### C.3 Executive Summary - Key Language Blocks
+
+**Clearance Statement:**
+> Based on post-restoration verification testing conducted [DATE], all tested surfaces within [FACILITY] meet applicable clearance criteria. The fire residue restoration is complete and the facility is cleared for reoccupancy.
+
+**Testing Summary:**
+> [N] tape lift samples and [N] surface wipe samples were collected from [AREAS]. All results were below applicable thresholds.
+
+**Threshold Reference:**
+> Clearance thresholds applied:
+> - Lead: [value] µg/100cm² (BNL SOP IH75190, Non-Operational)
+> - Particulates: < 150/cm² ash/char, < 500/cm² aciniform (IHC/FDAM professional judgment with empirical validation)
+
+---
+
+## Appendix D: Reference Standards Compendium
+
+### D.1 Primary Standards (Verified)
+
+| Standard | Title | Version | Application |
+|----------|-------|---------|-------------|
+| BNL SOP IH75190 | Surface Wipe Sampling for Metals | Rev23, 06/23/17 | Metals clearance thresholds |
+| EPA/HUD Lead Dust Hazard Standards | Lead Dust Hazard Standards | October 2024 | Public-Childcare lead thresholds |
+| NADCA ACR | Assessment, Cleaning and Restoration of HVAC Systems | 2021 Edition | Air filtration requirements |
+| IICRC/RIA/CIRI Technical Guide | Technical Guide for Wildfire Restoration | December 2025 | Zone framework |
+| Army/Air Force National Guard | Guidelines for Indoor Firing Range Rehabilitation | Current | Non-Operational lead alternative |
+
+### D.2 Referenced Standards
+
+| Standard | Application |
+|----------|-------------|
+| OSHA 29 CFR 1910.1025 | Lead housekeeping requirements |
+| OSHA 29 CFR 1910.1018 | Arsenic housekeeping requirements |
+| OSHA 29 CFR 1910.1027 | Cadmium housekeeping requirements |
+| OSHA Technical Manual Section II Ch. 2 | Surface contaminant methodology |
+| NIOSH Method 9100 | Surface wipe sampling procedures |
+| IICRC S700 | Standard for Fire and Smoke Damage Restoration |
+| IICRC S520 | Standard for Mold Remediation |
+| ASTM D6602 | Sampling and Testing of Carbon Black |
+
+### D.3 Laboratory References
+
+| Reference | Application |
+|-----------|-------------|
+| Environmental Analysis Associates (EAA) Air-O-Cell Method Guide & Particle Atlas (2018) | Combustion particle definitions; classification ranges; unit conversion reference; semi-quantitative interpretation |
+| EMSL Fire & Smoke Damage Guide 2021 | Sampling procedures |
+| Hayes Microbial Normal Ranges | Reference comparison (ASTM D6602 based) |
+
+**Note on EAA:** Environmental Analysis Associates, founded by Daniel Baxter (inventor of the Air-O-Cell sampler), maintains 30+ years of indoor air quality data. Their classification system provides independent validation of FDAM threshold positioning. EAA reports in cts/mm² (convert to cts/cm² by multiplying by 100).
+
+---
+
+*FDAM v4.0.1 — End of Document*

RAG-KB/Fire Remediation Processes and Methodologies_ A Review of Industry-Endorsed Standards.md

@@ -0,0 +1,86 @@
+# Fire Remediation Processes and Methodologies: A Review of Industry-Endorsed Standards
+
+**Author:** Manus AI
+**Date:** January 8, 2026
+
+## 1. Introduction
+
+This report provides a comprehensive overview of industry-endorsed and published sources of domain knowledge for fire remediation processes and methodologies. The research project focused on identifying key standards, guidelines, and technical publications from major standards organizations, government agencies, and industry associations. The findings are intended to serve as a foundational resource for professionals in the fire restoration, insurance, and environmental health and safety sectors.
+
+The fire and smoke damage restoration industry relies on a robust framework of standards and best practices to ensure that remediation work is performed safely, effectively, and in a scientifically defensible manner. This report synthesizes information from a wide range of sources, including the Institute of Inspection, Cleaning and Restoration Certification (IICRC), the National Fire Protection Association (NFPA), ASTM International, the Restoration Industry Association (RIA), the U.S. Environmental Protection Agency (EPA), and the Occupational Safety and Health Administration (OSHA).
+
+## 2. Key Standards and Guidelines
+
+The following sections detail the most relevant standards and guidelines from leading organizations in the field of fire and smoke damage restoration.
+
+### 2.1. Institute of Inspection, Cleaning and Restoration Certification (IICRC)
+
+The IICRC is a key standards-setting body for the restoration industry. Its standards are ANSI-accredited and internationally recognized as best practices.
+
+**ANSI/IICRC S700: Standard for Professional Fire and Smoke Damage Restoration** [1]
+
+This is the cornerstone standard for the fire and smoke damage restoration industry. It provides a comprehensive framework for the assessment and remediation of fire and smoke damage in buildings. The S700 standard covers the principles, processes, and procedures for assessing fire residues and odors, and for the cleaning and restoration of building systems, structures, and contents. It is important to note that the S700 standard is currently under revision, with a new version expected in the near future.
+
+**ANSI/IICRC S590: Standard for Professional Assessment of HVAC Systems Following a Water, Fire, or Mold Damage Event** [2]
+
+This standard focuses specifically on the assessment of HVAC systems after a fire or other damaging event. It provides detailed procedures for inspecting and evaluating HVAC systems to determine the extent of damage and to develop a restoration plan. The S590 standard is critical for ensuring that HVAC systems are properly cleaned and decontaminated to prevent the spread of contaminants throughout a building.
+
+**IICRC/RIA/CIRI Technical Guide for Wildfire Restoration** [3]
+
+Published in December 2025, this technical guide provides a science-based framework for the restoration of properties impacted by wildfires. It was developed in collaboration with the Restoration Industry Association (RIA) and the Cleaning Industry Research Institute (CIRI). The guide outlines a four-step process for wildfire restoration, including pre-restoration evaluation, pre-restoration assessment, the restoration phase, and project completion.
+
+### 2.2. National Fire Protection Association (NFPA)
+
+The NFPA is a global nonprofit organization devoted to eliminating death, injury, property, and economic loss due to fire, electrical, and related hazards. The NFPA develops and publishes more than 300 consensus codes and standards intended to minimize the risk and effects of fire.
+
+**NFPA 921: Guide for Fire and Explosion Investigations** [4]
+
+NFPA 921 is the primary guide for the scientific investigation of fire and explosion incidents. It establishes a systematic, scientific method for fire investigation that is widely accepted in the legal and insurance communities. The guide provides detailed information on fire dynamics, evidence collection and preservation, and the analysis of fire patterns.
+
+**NFPA 1033: Standard for Professional Qualifications for Fire Investigator** [5]
+
+This standard establishes the minimum job performance requirements for fire investigators. It is a critical standard for ensuring that fire investigations are conducted by qualified professionals with the necessary knowledge, skills, and abilities.
+
+### 2.3. ASTM International
+
+ASTM International is a globally recognized leader in the development and delivery of voluntary consensus standards. ASTM standards are used around the world to improve product quality, enhance health and safety, strengthen market access and trade, and build consumer confidence.
+
+**ASTM E119: Standard Test Methods for Fire Tests of Building Construction and Materials** [6]
+
+This standard is used to evaluate the fire-resistance of building materials and assemblies. It provides a standardized method for testing how long building elements can withstand a fire and continue to perform their structural function.
+
+**ASTM C856: Standard Practice for Petrographic Examination of Hardened Concrete** [7]
+
+This standard is used to assess the condition of concrete after a fire. It provides a method for examining the microstructure of concrete to determine the extent of damage and to guide repair and restoration efforts.
+
+## 3. Government Agencies
+
+Government agencies such as the EPA and OSHA also play a role in the fire restoration industry by providing guidelines and regulations related to environmental protection and worker safety.
+
+### 3.1. U.S. Environmental Protection Agency (EPA)
+
+The EPA provides guidance on the cleanup of hazardous materials after a fire, as well as on the management of debris and waste from fire-damaged buildings. The EPA's guidelines are designed to protect human health and the environment from the potential hazards associated with fire and smoke damage.
+
+### 3.2. Occupational Safety and Health Administration (OSHA)
+
+OSHA sets and enforces standards to ensure safe and healthful working conditions for working men and women. OSHA's regulations cover a wide range of workplace hazards, including those associated with fire and smoke damage restoration. These regulations include requirements for personal protective equipment (PPE), respiratory protection, and hazard communication.
+
+## 4. Conclusion
+
+The fire remediation industry is governed by a complex and evolving set of standards, guidelines, and best practices. This report has provided an overview of the key organizations and documents that shape the industry. It is essential for professionals in the field to stay current with these standards to ensure that they are providing the highest quality of service to their clients and to protect the health and safety of workers and the public.
+
+## 5. References
+
+[1] Institute of Inspection, Cleaning and Restoration Certification. (n.d.). *ANSI/IICRC S700 Standard for Professional Fire and Smoke Damage Restoration*. Retrieved from https://iicrc.org/s700/
+
+[2] Institute of Inspection, Cleaning and Restoration Certification. (n.d.). *ANSI/IICRC S590 Standard for Professional Assessment of HVAC Systems Following a Water, Fire, or Mold Damage Event*. Retrieved from https://iicrc.org/s590/
+
+[3] IICRC, RIA, & CIRI. (2025, December). *Technical Guide for Wildfire Restoration*. Retrieved from https://iicrc.org/wp-content/uploads/2025/12/IICRC.RIA_.CIRI-Technical-Guide-for-Wildfire-Restoration-V2-Final-2025-12.09.pdf
+
+[4] National Fire Protection Association. (n.d.). *NFPA 921: Guide for Fire and Explosion Investigations*. Retrieved from https://www.nfpa.org/codes-and-standards/nfpa-921-standard-development/921
+
+[5] National Fire Protection Association. (n.d.). *NFPA 1033: Standard for Professional Qualifications for Fire Investigator*. Referenced in industry documentation.
+
+[6] ASTM International. (2020). *ASTM E119-20: Standard Test Methods for Fire Tests of Building Construction and Materials*. Retrieved from https://www.astm.org/e0119-20.html
+
+[7] ASTM International. (n.d.). *ASTM C856: Standard Practice for Petrographic Examination of Hardened Concrete*. Referenced in industry practice.

RAG-KB/Industrial Hygiene Lab Services Guide.md

@@ -0,0 +1,369 @@
+# Industrial Hygiene Lab Services Guide
+
+**EMSL Analytical, Inc. - 2023 Edition**
+
+*Methods and Threshold Values Reference*
+
+---
+
+## Table of Contents
+
+1. [About EMSL Analytical, Inc.](#about-emsl-analytical-inc)
+2. [EMSL Diamond Standard](#emsl-diamond-standard)
+3. [Locations and Network](#locations-and-network)
+4. [Industrial Hygiene Testing Services](#industrial-hygiene-testing-services)
+5. [Comprehensive Analyte List (A-Z)](#comprehensive-analyte-list-a-z)
+6. [Group Profiles](#group-profiles)
+7. [Rental Equipment](#rental-equipment)
+
+---
+
+## About EMSL Analytical, Inc.
+
+EMSL Analytical, Inc. has been providing quality analytical services since 1981 as the nation's leading environmental testing firm. The company offers a wide array of analytical testing services to support environmental investigations focused on asbestos, microbiology, lead paint, environmental chemistry, indoor air quality, industrial hygiene and food testing. Additionally, EMSL provides materials testing, characterization, and forensic laboratory services for a wide range of commercial, industrial, regulatory, and law enforcement clients.
+
+The company's unmatched capacity coupled with a company-wide focus on customer satisfaction makes no project too large or too small. EMSL's corporate research and development capabilities allow them to bring new methodologies online quickly to meet new industry challenges and client needs. In recruiting and retaining talented and motivated scientists on a national scope, their expertise is marshaled throughout a nationwide network of analytical laboratories. EMSL is committed to providing reliable, defensible data in a standardized and user-friendly format. Rapid turnaround and competitive prices make the dependable results clients get that much more valuable.
+
+**Mission Statement:** "We're much more than another testing laboratory. We are your project partner!"
+
+### Overview of EMSL Service Divisions
+
+#### Asbestos
+- Asbestos analysis of air, water, bulk, soil and/or dust samples
+- Various methodologies including NIOSH, EPA, OSHA, ASTM, etc.
+- Utilizing PCM, PLM, TEM, SEM, XRD, and STEM
+
+#### Lead and Metals
+- Testing services include Flame AA, Graphite Furnace, and ICP
+- Lead testing in paint chips, soil, wipes, drinking water, waste water, and air
+
+#### Microbiology
+- Analysis of fungi (mold), bacteria (Legionella, E. coli, Salmonella, Listeria, etc.)
+- Mycotoxins, endotoxins, allergens, pollen testing
+- Particulates in air, swab, water, soil, bulk, dust, wipe, food, and consumer products
+
+#### Industrial Hygiene
+- Testing services for air, wipe, and bulk matrices
+- Extensive list of NIOSH, OSHA, ASTM, and EPA methods
+
+#### Environmental Chemistry
+- Instrumental and classical wet chemistry
+- ICP spectroscopy, microscopy, SEM and EDS analysis
+- FTIR analysis and more
+
+#### Materials Science
+- Materials testing, characterization, and forensic laboratory services
+- Support for commercial, industrial, regulatory, and law enforcement clients
+- Solutions for manufacturing challenges, quality assurance, and research and development
+
+#### Food
+- Microbiology analysis, nutritional analysis
+- Various food chemistry analysis
+- Allergens, toxins, and adulteration analysis
+
+#### Radiochemistry
+- Analysis of various matrices including food, water, soil, vegetation
+- Other unique sample types for radioactivity
+- Liberal radioactive materials license for most environmental radioactive needs
+
+#### Air Toxics
+- Testing services for VOCs in air, water and soil
+- Consumer products testing
+- Chamber studies for consumer product off-gassing analyses
+- Understanding what products are emitting and comply with regulations
+
+#### Pharmaceutical
+- Microbiology testing services through MPL Laboratories
+- Pharmaceutical, medical device, cosmetic, personal care, and food industries
+- ISO/IEC 17025 accredited by PJLA, FDA and DEA registered, and NJDEP certified
+
+#### PCR-DNA
+- DNA and PCR laboratory services
+- Bacteria, ERMI, fungi, and mold testing
+- Scientific, ecological, research, biological, microbiological, environmental, food, and botanical professionals
+
+#### Training
+- Array of training including online educational courses
+- Various laboratory services sampling videos
+- In-person training
+
+#### Products
+- Environmental products, equipment, and supplies for the field
+- Support for each company division
+
+#### Legal Services
+- Highly qualified and experienced professionals
+- Chemists, geologists, physicists, mycologists, microbiologists, biologists, materials scientists, and industrial hygienists
+- Available as-needed for legal support and expert witness testimony
+
+---
+
+## EMSL Diamond Standard
+
+EMSL's diverse staff of approximately 1,000 employees possess a wide range of expertise, educational background, and capabilities. These dedicated employees follow the lead and standard of care demonstrated by the owner and founder of the company, Dr. Peter Frasca, who, as a hands-on owner maintains daily involvement in laboratory operations, and assures work is consistent with the **EMSL Diamond Standard**.
+
+### The Diamond Standard Includes:
+
+#### Quality Data
+Track, manage, report, and verify that the data from all accredited testing services are accurate and reliable through quality programs and regulatory requirements.
+
+#### Customer Dedication
+EMSL strives to create lasting, mutually beneficial relationships with all clients. The company solicits feedback from clients and is committed to responding quickly to any questions or concerns that may arise before, during, or after an assignment.
+
+#### Analytical Expertise
+EMSL employs highly qualified and experienced chemists, geologists, physicists, mycologists, microbiologists, biologists, materials scientists, and industrial hygienists to enhance analytical abilities and expertise.
+
+#### Integrity and Ethics
+EMSL insists that employees uphold the highest standard of ethics. The company maintains a "no-compromise" policy as it pertains to any ethical issue.
+
+#### Responsiveness
+EMSL recognizes that the timeliness of a report is as important as the quality of the data. The company will not however, allow deadlines or the rush needs of a project to adversely impact quality objectives.
+
+#### Technology
+EMSL recognizes the importance of new technology to better enable improved services. Online access to data, customized reports, sample control/processing through the Laboratory Information Management System (LIMS), and analytical instrumentation are continuously upgraded to enable continuous improvement of services and capabilities.
+
+#### Value
+EMSL believes that a business relationship provides clients with excellent value. The company provides a complete value package that includes all the components of the EMSL Diamond Standard.
+
+---
+
+## Locations and Network
+
+### Locally Focused, Nationally Recognized
+
+**Unmatched capacity from the collective strength of nationwide locations.**
+
+EMSL Analytical, Inc. has been fortunate to be able to maintain a solid history of stable growth and viability for over 40 years with a current network consisting of **48 laboratories and 2 service centers** across the United States and Canada.
+
+**Corporate Headquarters:** Cinnaminson, NJ USA (also home to LA Testing)
+
+---
+
+## Industrial Hygiene Testing Services
+
+EMSL Analytical, Inc. provides Industrial Hygiene (IH) Laboratory Services for air, wipe, and bulk matrices on an extensive list of NIOSH, OSHA, ASTM, and EPA test methods, boasting five IH laboratory locations within North America:
+
+- **EMSL's Corporate Laboratory** - Cinnaminson, NJ
+- **Indianapolis, IN**
+- **Charlotte, NC**
+- **Huntington Beach, CA** (LA Testing)
+- **Toronto, ON** (Canadian location)
+
+### Professional Team
+
+The team of qualified and experienced professionals includes board-certified Industrial Hygienists (CIH), as well as highly trained project managers and analysts that welcome client interaction at project inception to ensure the laboratory data will meet all of the intended goals of the event, as well as communication during and after the event, as well as while samples are in-house. EMSL believes clear and concise communication is imperative to each project's success.
+
+### Accreditation and Certifications
+
+EMSL maintains **AIHA accreditation** for tests performed by the IH laboratories, which includes:
+- On-site laboratory audits
+- Formal document review program
+- Staff experience and education criteria
+- Proficiency Testing Program as part of the Accreditation process
+
+Additionally, as required by various states, EMSL IH laboratories hold most applicable state certifications for fields of testing for air samples.
+
+### Equipment and Quality Control
+
+EMSL has state of the art equipment within each of the five IH laboratory locations, including:
+- GC-ECD/GC-FID/GC-MS
+- LC, MS, MS/HPLC/LC/MS/IC/XRD/UV-VIS/ICP-AES
+- OES/ICP-MS
+- And more
+
+The analysis and reporting of each individual sample includes analysis of Quality Control (QC) samples, programs such as:
+- Instrument QC controls
+- Calibration standard checks
+- Spiked media
+- Reporting limit controls
+
+All to ensure the confidence limits of the data are within the acceptable range as specified by the method requirements and Quality Control Program.
+
+### Turnaround Times (TATs)
+
+Labs maintain normal business day operational hours with weekend scheduling availability as needed for critical response situations. Samples are received during regular business hours and turnaround times (TATs) are tracked on business days.
+
+**Available TATs:**
+- Same day or next day
+- 2 day
+- 3 day
+- 4 day
+- 1 week
+- 2 week Standard TATs
+
+Costs/rates are based on the TAT requested with the 2 week TAT rates being the most economically cost-effective for customers.
+
+### Laboratory Information Management System (LIMS)
+
+Sample control/processing (log-in, results data-entry, reporting) is facilitated by the Laboratory Information Management System (LIMS) which tracks the sample job (batch) and provides the laboratory with work log (due dates) to help ensure all the work is organized and processed in accordance with the client's needs.
+
+The LIMS includes security controls to ensure that information is controlled (locked) once the data has been documented and entered by the bench chemists. Reports are delivered at the choice of the customer which would include email, hard-copy regular mail, or both.
+
+Additionally, EMSL can provide:
+- Electronic Data Deliverables (EDD)
+- Various QC Data Packages (contact for package pricing)
+
+### Sampling Media and Pumps
+
+Regarding media and pumps, EMSL offers a **"free IH sampling pump program"** for clients, provided the analysis is performed by one of the IH laboratories. An extensive list of products and media for sale is available, including: pumps, badges, field equipment/monitors, etc., all of which can be viewed via the website.
+
+### Key Tests Available
+
+The following is a summary of key tests (but are not limited to):
+
+#### NIOSH Methods
+- NIOSH 0500, 0600, 1003M, 1005M, 1007, 1013, 1019, 1024, 1300, 1301, 1400M, 1401, 1402, 1403, 1405, 1450, 1453, 1457, 1500M, 1501M, 1550M, 1603M
+- NIOSH 1604, 1606M, 1610, 1612, 1615, 1616, 2000M, 2016M, 2500M, 2532, 2537, 2546M, 2551M, 3500, 5008M, 5026, 5040, 5041, 5042M, 5503M, 5506M, 5510M, 5523, 5524
+- NIOSH 5600, 5601M, 6004M, 6009M, 6010M, 6011, 6013, 6014, 6016, 7082, 7401, 7500, 7501, 7600, 7602, 7906, 7907, 7908, 7908M, 9111M
+
+#### OSHA Methods
+- OSHA 42/47M, OSHA 5002M, OSHA 56, OSHA 58M, OSHA 64, OSHA 80, OSHA 83M, OSHA 91, OSHA 99M, OSHA 104, OSHA 109, OSHA 1007, OSHA 1008, OSHA 1010 V2, OSHA 1014, OSHA 1018, OSHA 1019, OSHA 103M, OSHA 5001, OSHA ID-113, OSHA ID-140
+- OSHA ID-145, OSHA ID-165SG, OSHA ID-182, OSHA ID-188M, OSHA ID-190, OSHA ID-214, OSHA ID-215 V2, OSHA PV2061, OSHA PV2111, OSHA PV2119
+
+#### Other Methods
+- 40CFR50, Appendix B
+- 40CFR50, Appendix J
+- 40CFR50, Appendix L
+- AssayTech LP 575
+- ASTM D5504
+- EPA IP-10A
+- EMSL In-House Methods
+
+**Note:** If you are looking for a method that is not listed, please contact EMSL immediately to confirm if they can perform. The list of services is being expanded regularly.
+
+*For a full list of tests offered and for pricing, call for details.*
+
+---
+
+## Comprehensive Analyte List (A-Z)
+
+This section contains detailed information about each analyte tested by EMSL's Industrial Hygiene laboratories. The list includes CAS numbers, test methods, synonyms, sampling instructions, flow rates, media types, and occupational exposure limits (OELs) from various regulatory agencies.
+
+### Understanding the Analyte Table Columns
+
+- **CAS Number:** Chemical Abstracts Service registry number for unique identification
+- **Test:** Common name of the analyte
+- **Test Method:** Specific NIOSH, OSHA, ASTM, or EPA method used
+- **Synonym(s):** Alternative names for the chemical
+- **Test Code:** EMSL internal test identification code
+- **OSHA PEL or Other Value:** Occupational Safety and Health Administration Permissible Exposure Limit or other regulatory values
+- **Most Relevant OEL (Value):** Most applicable Occupational Exposure Limit with value
+- **Default Reporting Limit:** Minimum detection limit for the test
+- **Sampling Instructions:** Special handling or storage requirements
+- **Flow Rate (lpm):** Liters per minute for air sampling
+- **Volume (L):** Total air volume to be sampled
+- **Media:** Collection media types (filters, sorbent tubes, etc.)
+- **Pump Kit ID:** EMSL equipment identification numbers
+
+### Sample Analytes (Alphabetical)
+
+| CAS Number | Analyte | Test Method | Synonym(s) | Key OEL |
+|:-----------|:--------|:------------|:-----------|:--------|
+| 83-32-9 | Acenaphthene | NIOSH 5506M | Dihydroacenaphthylene | 0.2 mg/m³ OSHA PEL TWA |
+| 208-96-8 | Acenaphthylene | NIOSH 5506M | Acenaphthalene | 0.2 mg/m³ OSHA PEL TWA |
+| 75-07-0 | Acetaldehyde | NIOSH 2016M | Acetic Aldehyde; Ethyl Aldehyde | 200 ppm OSHA PEL TWA |
+| 64-19-7 | Acetic Acid | NIOSH 1603M | Ethanoic Acid | 10 ppm OSHA PEL TWA |
+| 513-86-0 | Acetoin | NIOSH 2558 | 3-Hydroxy-2-Butanone | Not Established |
+| 67-64-1 | Acetone | NIOSH 2016M | Dimethyl Ketone | 1000 ppm OSHA PEL TWA |
+
+*Note: This is a representative sample. The complete guide contains hundreds of analytes from A-Z with full technical specifications, sampling parameters, and regulatory threshold values. Contact EMSL for the complete analyte database or specific chemical information.*
+
+### Special Notes for Sampling
+
+Many analytes require specific handling:
+- **Light-sensitive compounds:** Protect from light and heat, wrap in foil
+- **Volatile compounds:** Store in freezer, ship cold (5°C)
+- **Temperature-sensitive:** Ship refrigerated (0°C)
+- **Reactive compounds:** Special storage and shipping requirements noted
+
+---
+
+## Group Profiles
+
+EMSL offers pre-configured test packages for common industrial hygiene scenarios. These group profiles streamline the testing process for frequently requested analyte combinations.
+
+*Detailed group profile information is available on pages 59-61 of the complete guide.*
+
+Common group profiles may include:
+- **Volatile Organic Compounds (VOCs)** - Common workplace air contaminants
+- **Metals Panel** - Comprehensive metals analysis for industrial settings
+- **Welding Fumes** - Specific metals and compounds from welding operations
+- **Solvent Mixtures** - Common solvent combinations in manufacturing
+- **Diesel Particulate Matter** - Complete diesel exhaust characterization
+- **Pharmaceutical Compounds** - Active pharmaceutical ingredients (APIs)
+
+Contact EMSL for current group profile offerings and pricing.
+
+---
+
+## Rental Equipment
+
+EMSL offers a comprehensive rental program for industrial hygiene sampling equipment. This program supports clients who need temporary access to professional-grade sampling equipment.
+
+*Detailed rental equipment information is available on pages 62-63 of the complete guide.*
+
+### Available Equipment Categories
+
+- **Air Sampling Pumps** - Personal and area sampling pumps
+- **Calibration Equipment** - Flow calibrators and verification devices
+- **Monitoring Instruments** - Real-time detection and monitoring
+- **Sample Collection Media** - Filters, cassettes, sorbent tubes, badges
+- **Field Equipment** - Tripods, stands, and mounting accessories
+- **Specialized Instruments** - Thermal imaging, particle counters, gas detectors
+
+### Free IH Sampling Pump Program
+
+EMSL offers a **"free IH sampling pump program"** for clients when the analysis is performed by one of EMSL's IH laboratories. This program provides access to calibrated sampling pumps without rental fees, making it easier and more cost-effective to conduct industrial hygiene sampling.
+
+---
+
+## Contact Information
+
+For more information about EMSL Analytical, Inc. and their Industrial Hygiene Laboratory Services:
+
+- **Website:** Visit EMSL's website for the most current information
+- **Phone:** Contact your nearest EMSL laboratory location
+- **Email:** Reach out to customer service for quotes and technical support
+
+**Corporate Headquarters:**  
+EMSL Analytical, Inc.  
+Cinnaminson, NJ USA
+
+---
+
+## Document Information
+
+- **Title:** Industrial Hygiene Lab Services Guide
+- **Edition:** 2023
+- **Focus:** Methods and Threshold Values
+- **Publisher:** EMSL Analytical, Inc.
+- **Pages:** 63 pages (original document)
+- **Format:** Reference guide for industrial hygiene professionals
+
+---
+
+## Navigation Tips for LLM Agents
+
+This document is structured to facilitate easy navigation and information retrieval:
+
+1. **Use the Table of Contents** to jump to major sections
+2. **Section headers** use standard Markdown hierarchy (##, ###, ####)
+3. **Tables** organize complex data for easy parsing
+4. **Bold text** highlights key terms and important information
+5. **Lists** break down complex information into digestible items
+6. **CAS numbers** provide unique identifiers for chemical lookups
+7. **Cross-references** link related information throughout the document
+
+### Key Search Terms
+
+When searching this document, use these terms:
+- Analyte names (e.g., "Acetone", "Benzene")
+- CAS numbers (e.g., "67-64-1")
+- Test methods (e.g., "NIOSH 2016M", "OSHA PV2119")
+- Regulatory terms (e.g., "PEL", "TWA", "STEL", "Ceiling")
+- Service types (e.g., "air sampling", "wipe sampling", "bulk analysis")
+- Equipment (e.g., "pump", "media", "calibration")
+
+---
+
+*This Markdown document was created from the EMSL Analytical, Inc. Industrial Hygiene Lab Services Guide (2023 Edition) to facilitate LLM agent navigation and information retrieval.*

RAG-KB/Metals clearance criteria-QVC.md

@@ -0,0 +1,622 @@
+# BROOKHAVEN NATIONAL LABORATORY
+
+**Safety & Health Services Division - Industrial Hygiene Group**  
+**Standard Operating Procedure**
+
+| | |
+|---|---|
+| Number | IH75190 |
+| Revision | Rev23 |
+| Date | 06/23/17 |
+| Page | 1 OF 16 |
+
+**Subject: Surface Wipe Sampling for Metals**
+
+---
+
+*The only official copy is on-line at the SHSD website.*  
+*Before using a printed copy, verify that it is current by checking the document issue date on the website.*
+
+---
+
+# IH75190
+# Surface Wipe Sampling for Metals
+
+## 1.0 Purpose & Scope
+
+This document describes a field procedure for taking wipe samples for metals on surfaces. It is based on methodology described in NIOSH 9100 "Lead in Surface Wipe Samples" of the NIOSH Manual of Analytical Methods.
+
+The goal of the procedure is to provide a uniform methodology to collect representative samples. Using this method will ensure repeatability between various sampling personnel and between surface configurations. It is used for characterizing surface levels for the following reasons:
+
+- Decommissioning operational areas
+- Evaluating the effectiveness of clean-up of a spill
+- Evaluating compliance with housekeeping levels in operational areas
+- Characterizing a piece of equipment for release.
+
+## 2.0 Responsibilities
+
+**2.1 Demonstrated Competency:** This procedure is administered through persons who have demonstrated competency in performing this procedure in accordance with Section 7 are qualified to use this procedure.
+
+**2.2 Chain of Custody procedures:** The qualified sampler is responsible for samples until they have been properly transferred to the IH Group laboratory using the *IH51200 IH Laboratory Equipment & Sample Processing* procedure.
+
+**2.3 Hazard Analysis of the Sampling Task:** It is the responsibility of persons using this method and their supervisors to:
+
+- Use appropriate personal protective equipment; see section 5.3.
+- Obtain required training and qualification for hazards in areas.
+- Comply with all work planning and work permit system requirements.
+
+## 3.0 Definitions
+
+**Surface Wipe-** a technique for the determination of metal on surfaces conducted by wiping the loose dust from the surface with a cloth/paper media and analysis of the metal on the media by laboratory or XRF measurement.
+
+Definitions associated with surface wipe criteria are cited in Attachment 9.3
+
+## 4.0 Prerequisites
+
+**Area Access:**
+
+4.1 Training for hazards may be needed for entry into areas with hazards, such as radiological areas..
+
+4.2 Contact the appropriate Facility Support Representative or Technician to obtain approval to enter radiological areas.
+
+4.3 Review and sign the Work Permit or Radiological Work Permit if needed.
+
+4.4 Use appropriate PPE for area.
+
+## 5.0 Precautions
+
+**5.1 Hazard assessment:** Taking surface wipe samples may cause some exposure to health risks. Sampling may be performed in areas with metal, chemical or radiological contamination. These hazards must be assessed on a case-by-case basis by a competent individual knowledgeable of the hazards of the area.
+
+**5.2 Job Risk Assessment:** Consult the Job Risk Assessment SHSD-JRA-05 for the risk analysis of this operation based on the hazards and controls of this SOP.
+
+**5.3 Personal Protective Equipment:** Use appropriate personal protective equipment when implementing this procedure.
+
+- **Hand:** Use gloves in areas of known or suspected metal, chemical or radiological contamination. Exam-style, splash gloves are acceptable. Acceptable polymers are: Nitrile, PVC, and Natural Rubber. The gloves must have sufficient impermeability to the surface contaminant and solvent used on the collection media to allow safe handling. See Table 1.
+- **Body:** Use a disposable suit if contact of the body with contaminated surfaces is anticipated. Acceptable chemical protective equipment materials include: Tyvek®, KleenGuard®, and cotton. Contact the ECR for disposable of garments. If personal clothing items become contaminated, they must be surrender for BNL cleaning or disposal.
+- **Foot:** Use disposable shoe coverings, boots or booties if contact of the feet with contaminated surfaces is anticipated. Acceptable material include: Tyvek®, KleenGuard®, and rubber. If personal shoes become contaminated, they must be surrendered for BNL cleaning or disposal.
+- **Respiratory:** Under normal use, respiratory protection is not required. Use a respirator in an area with the potential to exceed the OSHA, ACGIH, or DOE standards. The person collecting using respiratory protection must comply with the BNL Respiratory Protection Program.
+- **Eye:** Use safety glasses with side shields in laboratories, construction, and general industry areas.
+
+**5.4 Radioactive Concerns:** It is possible that some surfaces to be tested may have radioactive contamination. In these cases, personal protective equipment and administrative controls must be implemented for the radiological contaminant hazard.
+
+In addition, the collected sample must be analyzed for the radiological hazard before it can be submitted to the IH Group for analysis. The radiological contamination must be below the permissible release limits to the general public.
+
+**5.5 Work Planning:** All requirements of work permits and work planning system reviews must be met in performing this procedure.
+
+**5.6 Personal Hygiene:** Remove PPE and wash hands after sampling and before eating or drinking.
+
+**5.7 Environmental Impact and Waste Disposal:** This technique does not have adverse impact on the environment. Based on WMD testing of similar PPE material, the templates and gloves can be disposed as normal trash. See Attachment 9.4.
+
+## 6.0 Procedure
+
+### 6.1 Equipment
+
+| Item | Description |
+|------|-------------|
+| **Sample container (either):** | Bag, plastic, sealable with "zip" type seal. |
+| | Vial, glass or plastic. (Glass is needed for hexane solvents based samples). |
+| **Sample media (any of these):** | Gauze: 2" x 2" or 4" x 4" cotton gauze |
+| | Paper: Ashless quantitative filter paper (typical diameter is 1.5 to 4 inches) |
+| | Pre-moistened wipe: manufacturer foil wrapped, solvent soaked disposable cloths (such as GhostWipes or LeadWipe |
+| | • The type of wipe is dependent on the lab to be used. Check with the lab for appropriate media for the metals to be analyzed. |
+| | • For multiple metals, check with the lab to ensure they can all be done on a single wipe |
+| **Gloves** | Appropriate for contaminant and solvent (see Table 1) and site hazards. |
+| **Solvent** | Distilled water, Isopropanol, ethanol, methanol, n-hexane, or pre-moistened. See Table 1 for recommended solvent for each contaminant. |
+| **Template** | Plastic sheet or cardboard: See Table 1 for size needed |
+| | • 100cm2: 10 cm x 10 cm square –or- circle of 11.24 cm diameter. |
+| | • 1ft2: 1foot x 1 foot, or other shape totaling 144 in2. |
+
+### 6.2. Wipe Technique
+
+BNL SHSD IH Group has selected the NIOSH method of collecting wipe samples. For uniformity, this method should be used for all sampling surface to be sampled (Visually depicted in Figure A)
+
+**Figure A: NIOSH Surface Wipe Method**
+
+[Figure shows three-step wiping process: 1. First Wipe using whole pad in S-pattern, 2. Second Wipe using half pad (folded) in S-pattern at right angles, 3. Third Wipe using quarter pad (folded again) in S-pattern. With each step, fold the exposed surface inward. Final step 4 shows folding to put in bag/bottle with label.]
+
+**6.2.1** Use a moistened sample media or pre-moistened wipe (e.g. GhostWipe™). Apply only enough solvent to moisten approximately 80% of the area of the media. Avoid excess solvent on the filter or pad as it may cause drips and running on the surface thus diluting the sample.
+
+### Table 1
+
+| Contaminant | Media(1) | Solvent(2) | PPE Glove(2) Disposable Style | Sample Size |
+|-------------|----------|------------|-------------------------------|-------------|
+| **Lead** | Gauze or Filter | 1 -2 ml Distilled Water | Natural Latex Rubber, Nitrile, PVC, or Polyethylene | 1 square foot, 100 cm2 requires advanced approval by IH professional verifying that sensitivity is adequate |
+| | Pre-moistened Wipe (should be cut in half) (3) | n/a | | |
+| **Beryllium** | Gauze or Filter | 1 - 2 ml Distilled Water Isopropanol, Methanol, Ethanol | Natural Latex Rubber, Nitrile, PVC, or Polyethylene | 1 square foot minimum needed always |
+| | Pre-moistened Wipe (should be cut in half) (4) | n/a | | |
+| **Arsenic, Cadmium** | Gauze or Filter | 1-2 ml of Distilled Water | Natural Latex Rubber, Nitrile, PVC, or Polyethylene | 100 cm2 typically acceptable |
+| | Pre-moistened Wipe (should be cut in half) (4) | n/a | | |
+| **Hexavalent Chromium** | Preferred Medias: See Attachment 9.2 | None: For chrome plating operations, see stabilizing solution in Attachment 9.2. | Powderless: Natural Latex Rubber, Nitrile, PVC, or Polyethylene | 100 cm2 typically acceptable |
+
+**Notes for Table 1:**
+
+(1) Some pre-moistened media may not be compatible is certain laboratory analytical equipment. Check with the laboratory analyzing the samples prior to sampling to ensure the brand of media is compatible.
+
+(2) Solvent: The solvent is not critical for lead, beryllium, and most heavy metals such as cadmium, nickel, and chromium. In doing wipes for these compounds, it is allowable to choose the solvent that will have the least impact (residues) on the owner of the equipment being sampled (i.e. some equipment is sensitive to water residues and an alcohol or other solvent may be preferred by the equipment owner.)
+
+(3) Selection criteria: Breakthrough time greater than 1 hour of continuous contact. Source of data is DOE Guidelines for the Selection of Chemical Protective Clothing, 1991.
+
+(4) The use of full size pre-moistened may cause the sample not to meet the minimum level of detection. To increase sensitivity, cut wipe in half to reduce the size of the wipe.
+
+**6.2.2** Place the template over the area to be sampled or measure out 1 ft2 or 100-cm2 surface area, as per Table 1. If the object has a total surface area of less than 1 ft2 or 100 cm2, sample the whole surface area, if possible, and record the surface area. If the surface does not allow the use of a template, carefully determine the dimensions that will equal 1 ft2 or 100 cm2.
+
+**6.2.3** Wipe the surface with firm pressure, using "S" strokes, covering the entire surface (edge to edge). If the surface is very rough (such as concrete), a dabbing action may be substituted for the full contact pressure rubbing of the media across the surface. When dabbing, make sure to completely cover the same area as in the S-stroke wipe. Indicate dabbing done on sample form.
+
+Fold the exposed side of the pad or filter inward (i.e. fold in half).
+
+**6.2.4** Using the once-folded media, wipe the same area S-strokes (see Figure A), starting at right angles to the first wipe. Fold the exposed side of the pad or filter inward.
+
+**6.2.5** Using the twice-folded media, wipe with S-strokes (see Figure A) starting at the original point and wipe in the same direction. Fold the exposed side of the pad or filter in.
+
+**6.2.6** Place the media in a plastic bag or vial. Seal the zip lock or vial. Record the sample identification on the bag or vial.
+
+**6.2.7** Thoroughly clean reusable templates or discard paper templates in preparation of the next sample. Based on WMD testing of similar material, templates can be disposed as normal trash.
+
+**6.2.8** Remove gloves by pulling them off inside-out and discard appropriately before handling the next filter or pad.
+
+**6.2.9** Record the sample identification, surface area sampled, and description of the sample and surface on the sample form (Attachment 9.5) in the electronic SHSD forms page Surface Wipe (Metals)- Field Sampling Records & Chain of Custody.
+
+**6.2.10** Include 1 blank filter or pad (moisten and placed in bags or vials) with each set of samples (provide 1 blank per 6 samples).
+
+### 6.3 Surface Wipe Technique for Hexavalent Chromium
+
+See Attachment 9.2.
+
+### 6.4 Determine HOW MANY samples to take
+
+It is not possible to provide definitive guidance on the number of samples to be taken in every case. Table 2 provides general guidance on which to base professional judgment determining the number of samples. Factors that should be considered in selecting the number of samples include: the size of the area to be tested, the predicted uniformity of contamination over the surface area, and the eventual fate of the surface area (disposal, remediation, background measurement, etc.)
+
+If more than six (6) samples are to be taken, it is suggested that at least one (1) duplicate sample be taken in close proximity to one other to verify the precision (repeatability) of the sampling.
+
+### Table 2: Statistical sampling plan
+
+| Surface Configuration | Minimum Number of Samples | Qualifier |
+|-----------------------|---------------------------|-----------|
+| Entire Surface is less than 100 cm2 (example: a small article) | 1 | If possible, sample the whole item, one sample is usually sufficient. |
+| Surface Area of object or area is greater than 100 cm2 but only a few square feet (example: table top on which a process is done) | 1 | If only one sample is taken, select the area with highest potential contamination |
+| Surface Area of object or area is greater than a few square feet (example: floor or wall of a room) | 1 - 3 | Ideally three samples are taken, but fewer samples may be taken depending on the purpose for sampling |
+| Multiple surfaces in a large area with the same exposure potential to source (example, many rooms in a building with a common source such as the HVAC system) | 1 – 3 for each surface, 6 or more for the whole area | Assumes all the surfaces have similar exposure potential, else treat each area separately. |
+
+### 6.5 Determine WHAT KIND of samples (LOCATION)
+
+Consider these locations when characterizing levels of surface metals:
+
+- surfaces that are frequently accessed,
+- surfaces that hazardous metal object rest on,
+- surfaces that are infrequently cleaned or disturbed (such as top of cabinets or high shelves)
+- sources of the contamination (such as process equipment, lab apparatus, site of known spills),
+- areas where contamination is not expected (these serve as a control), and
+- areas where contamination would not be permissible (such as lunch rooms).
+
+### 6.6 Results interpretation
+
+Normalize the units of sampling results from the laboratory to the base units of the Surface Level Criteria Requirements & Recommendations listed in Attachment 9.3.
+
+Conversion of data between various laboratory reporting units of measures: Data can be converted from the various regulatory reporting and laboratory reporting units of measure based on the following values: 1 sq.ft. = 929 cm2 1 mg = 1000 ug
+
+| Convert form: | Multiply by |
+|--------------|-------------|
+| ug/100 cm2 to ug/sq. ft | 9.29 |
+| ug/sq. ft to ug/100 cm2 | 0.1076 |
+
+### 6.7 Posting equipment or areas
+
+Consult with Attachment 9.1 for recommended wording to be used for labelling equipment or areas when a warning is needed for toxic metal hazards.
+
+### 6.8 Reporting results
+
+Convey the assessment of results to the requestor of the sampling, in a written analysis documenting: sampling and analysis methods, contamination levels measured, compliance with regulatory and recommended levels, and recommended corrective actions (if necessary).
+
+## 7.0 Implementation and Training
+
+**Qualification Criteria:** Use of this SOP is limited to persons who have demonstrated the competency to satisfactorily use the procedure, as evidenced by experience and training. All persons must have demonstrated competency in the qualification criteria set in the Job Performance Measure (Attachment 9.6.) or e-Exam IH75190. Qualification on this JPM is required on a 3 year basis.
+
+## 8.0 References
+
+8.1 ACGIH: Threshold Limit Values 2005
+
+8.2 DOE: 10CFR 850 Chronic Beryllium Disease Prevention Program
+
+8.3 EPA: Toxic Substance Control Act (TSCA) 40CFR745.227
+
+8.4 Ness, S.A.; Surface and Dermal Monitoring for Toxic Exposures, Van Nostrand Reinhold, 1994.
+
+8.5 NIOSH: Manual of Analytical Method, Method 9100: Lead in Surface Wipe Samples.
+
+8.6 OSHA: 29CFR1910.1000 Table Z1, Z2; and 1910.1027.
+
+8.7 OSHA: Technical Manual Section II, Chapter 2.
+
+## 9.0 Attachments
+
+9.1 Sample of Signs for Areas and Equipment
+
+9.2 Wipe Sampling Technique for Hexavalent Chromium
+
+9.3 Surface Wipe Criteria Requirements & Recommendations
+
+9.4 Environmental Evaluation of Surface Wipe Sampling
+
+9.5 Sample of Surface Contamination Sampling Form
+
+9.6 SHSD Job Performance Measure (JPM) Completion Certificate
+
+## 10.0 Procedure Documentation
+
+**ISM Review - Hazard Categorization:** High; Moderate; Low/Skill of the craft
+
+**Validation:** Formal Walkthrough   Desk Top Review   SME Review
+
+### Revision Log
+
+| Rev | Description |
+|-----|-------------|
+| 0 | New document. Prepared By R. Selvey, CIH 02/25/2000; Technical Reviewed By: N. Bernholc, CIH 02/27/00; RCD Facility Support Approved By: 04/22/01 N. Foster Procedure Committee Review; QA Review : E. Tucker; SHSD Approved By: R. Selvey 03/02/2000 |
+| 1 | Revised for minor correction noted in training classes. Reviewed By: R. Selvey 10/6/00 |
+| 2 | Added new format, SBMS header and reviewed sections on Hazard assessment, PPE. Added Waste Disposal and Environmental Impact text. Reviewed By: R. Selvey 02/05/01 |
+| 3 | Minor format change. Converted SOP number from IH-FP-3.2 to new system IH75190. Reviewed By: R. Selvey 03/09/01 |
+| 4 | Revised to include RCD Facility Support Procedure Committee Review comments. Reviewed By: R. Selvey 04/22/01 |
+| 5 | Updated Table 1 adding Arsenic and Cadmium Media. Update Table 3 with Arsenic and Cadmium Release Criteria and update EPA Lead Criteria. Reviewed By: R. Selvey 04/10/02 |
+| 6 | Updated Table 1 to correct error in lead criteria. Insert Section 7 and transfer information from section 4. Renumbered attachments. Reviewed By: R. Selvey 4/17/02 |
+| 7 | Added Best Management Practice release criteria for Arsenic and Cadmium to Table 3. Reviewed By R. Selvey 08/16/02: |
+| 8 | Added Best Management Practice release criteria for Nickel to Table 3. Reviewed By: R. Selvey 10/17/02 |
+| 9 | Full review of SOP. Significant text changes. Deleted OSHA Method for procedure & PCB criteria. Updated Attachments 9.1 and 9.2. Added Attachment 9.3. Reviewed By: R. Selvey 05/21/04 |
+| 10 | Added reference and link to JRA-05 in 5.1. Added text to 6.2.2 to clarify using Table 1 to determine 100cm2 versus 1 sq ft. Changed "S-stroke" wording in 6.2.3.through 6.2.5 to avoid confusion with the S-stroke used the Health Physics terminology. The two patterns are different. Changed the qualification criteria in Section 7 to reflect the unified qualification policy. Updated the Sample form (Attachment 9.1) to reflect the Compliance Suite order of sample numbering. Reviewed By: R. Selvey 02/21/06 |
+| 11 | Reworded the "S-stroke" wording in 6.2.3.through 6.2.5 to avoid confusion with the S-stroke used the Health Physics terminology. Passage on "dabbing" was modified to indicate that the dabbing action replacing pulling the media, but does not replace the S-pattern. Minor typo corrections in Section 5 and 6. Reviewed By: R. Selvey 02/21/06 |
+| 12 | Section 6.3 was added with a reference to new Attachment 9.4; Table 1: was updated to include hexavalent chromium. Attachment 9.4 was added to include Liberty Mutual Wipe Sample Method. Liberty Mutual method was added. Section 8 References and Attachment 9.4 was added and included in Section 9.0 Attachments. Reviewed By: J. Peters 11/28/06; Reviewed By: R. Selvey 12/05/06 |
+| 13 | Added Section 4.1, 4.2 and 5.6. Revised 5.2. Added document control to attachment 9.3 and 9.4. Reviewed By: R. Selvey 05/23/07 |
+| 14 | Table 3: Updated to include Cobalt and description of calculation. Changed IH training link in Step 7.1. Reviewed By: M.Chuc 09/22/08 Reviewed By: R. Selvey 10/13/08 |
+| 15 | Added Attachment 9.5. Reviewed By: R. Selvey 02/09/09 |
+| 16 | Edited section 4.0 and 5.2 for brevity. Added definition for Release and Housekeeping Criteria. Changed Cr6 release level based on OSHA recommendation. Added ANSI Caution to Attachment 9.1 sign. Revised directions in Attachment 9.2. Reviewed By: R. Selvey 03/21/11 |
+| 17 | Full review of steps 1 to 7. Expanded and revised Release and Housekeeping Criteria definitions in Section 3 and in Table3. Reviewed By: R. Selvey 04/27/11 |
+| 18 | Corrected error in units in section 3: mg/100cm2 to ug/100 cm2. Reviewed By: R. Selvey 05/10/11 |
+| 19 | Edited Section s 2 and 7 to remove reference to rescinded HP65100. Changed format of Section 9. Reviewer: R. Selvey 03/04/14 |
+| 20 | Total review and revision. Replaced Table 3 with Appendix 9.3 and added OSHA Technical Manual ratio. Removed criteria for Al, Ba, Co, Cu, Hf, In, Mn, Mo, Pt, Rh, Se, Ag, Ta, Te, Tl, Sn, W, Y, Yt, and Zr. Added link to e-Exam and e-form. Added short-life disclaimer to Cr6 in Attachment 9.2. Revised by: R. Selvey 06/13/8/16 |
+| 21 | Revised Attachment 9.3 to correct Cr+6. Added column for ug/sq ft. Corrected error in Table 1 Attachment 3. Revised by; R. Selvey 09/13/16. |
+| 22 | Revised Attachment 9.3 to remove no-regulated Nickel and CrIII and adjusted values for Arsenic and CrVI to match OSHA Housekeeping philosophy. Added proposed changes for all release criteria to allow comments on impact. Revised by; R. Selvey 05/01/17. |
+| 23 | Team reviewed revision to Attachment 9.3. Values aligned with OSHA, EPA/HUD and DOE policies. Approved by: R. Selvey 06/23/17 |
+
+---
+
+# Attachment 9.1
+## Samples of Signs for Areas and Equipment
+
+---
+
+### CAUTION
+
+**Cadmium Surface Contamination**
+
+Some surfaces in this area have Cadmium levels above BNL Guidelines
+
+- Do NOT perform operations that causes the dust to become airborne (such as using an air hose to clean surfaces or dry sweeping)
+- Contact SHSD IH Group x-7475 prior to Building Renovations or Demolition
+- Wash hands prior to eating, drinking, chewing gum, or smoking
+- Do not eat or drink in this area.
+
+---
+
+### CLEAN
+
+The material on this pallet is below (i.e. cleaner than) the SHSD Best Management Practice Surface Release Guidelines for Lead and Cadmium
+
+It is appropriate to be released and used anywhere at BNL without any specific precautions.
+
+---
+
+### Exceeds Guidelines for Lead or Cadmium
+
+The material on this pallet is above (i.e. not cleaner than) the SHSD Best Management Practice Surface Release Guidelines for Lead and/or Cadmium
+
+Specific precautions are needed in areas where this material is used or stored.
+
+- No operations that cause airborne dust (such as air hoses, blowers, or dry sweeping)
+- Wash hands prior to eating, drinking, chewing gums, or smoking.
+- Do not eat or drink in this area.
+- Notify occupants of the area of the presence of Lead/Cadmium on these surfaces.
+
+---
+
+# Attachment 9.2
+## WIPE SAMPLING TECHNIQUE FOR HEXAVALENT CHROMIUM
+
+**Note:** Hexavalent Chromium has a short life on surfaces. Sampling and analyzed needs to be completed within a few days of generation. For sampling of long term dust accumulations, use Cr3 sampling.
+
+### Materials supplied by the lab:
+
+**Sampling media:**
+
+- For chrome plating: PVC or binderless quartz filter. All other operations:
+  - 5 um, 37-mm PVC filter for smooth surfaces
+  - 0.45 mm thick 37-or 47-mm binderless quartz fiber filter for rough surfaces (preferred media for both smooth and rough surfaces)
+- Immediately after sampling, place the filter sample in a vial containing 10% Na2CO3 with 2% NaHCO3 to stabilize the Cr+6.
+- Do not use Ghost wipe®, Whatman, mixed cellulose ester (MCE) or glass fiber filter as they convert Cr+6 to Cr+3.
+
+**Additional materials:**
+
+- Template (10 cm x 10 cm)
+- Teflon coated or plastic tweezers
+- Empty glass vials
+- Glass vials containing 5 ml aqueous solution of 10% Na2CO3 with 2% NaHCO3 for chrome plating samples
+- Powderless gloves
+
+### Sampling Technique:
+
+1. Prepare a sufficient number of vials, each labeled with a unique number.
+
+2. Sketch a diagram of the room or area to be sampled.
+
+3. Wear a new pair of clean gloves for each sample. DO NOT use powdered gloves.
+
+4. Record the sample vial number and location where the sample is taken.
+
+5. Remove the filter from the carrying container with a clean PTFE-coated tweezers or plastic tweezers. DO NOT use metal tweezers to handle the filters, as they could deposit Cr+6 onto the filters.
+
+   **Note:** Surfaces should not be wetted with water as the water will allow any metal interference to interact with Cr+6 thereby affecting the results.
+
+6. Use firm pressure when wiping the surface. Start at the one corner moving to the opposite side then upward one wipe width and wipe back to the starting side. Repeat to cover the whole surface area. Fold inward and repeat wiping the entire surface again. Fold in and repeat a third time.
+
+7. After wiping, fold the filter with the contaminant side inward. Place the filter immediately in the sample vial and cap. Filter samples taken in chrome plating operation must be placed in a vial containing 10% Na2CO3 with 2% NaHCO3 to stabilize the Cr+6.
+
+8. Submit at least one blank wipe filter, treated in the same fashion, but without wiping.
+
+9. Sample results will be reported as ug/100cm2. OSHA's target concentration is 0.050ug/100 cm2.
+
+10. Ship samples immediately. If unable to ship immediately, keep cold then ship next day air to the lab.
+
+---
+
+# Attachment 9.3
+## Required and Recommended Surface Wipe Criteria
+### 06/26/17
+
+| Compound | Criteria | | Criteria type | OSHA PEL |
+|----------|----------|---|---------------|----------|
+| | ug/100cm2 | ug/ft2 | R = Requirement; G= Guidance, Recommended, Non-regulatory | ug/m3 |
+| **Arsenic (As) 29CFR1910.1018** | | | | |
+| | 100 | 929 | G OSHA Regulated Areas [AFAP] & Operational Areas: Floors & accessible surfaces | 10 ug/m3 |
+| | 6.7 | 62 | G Non-Operational Areas: Floors & accessible surfaces | |
+| **Beryllium (Be) 10CFR850** | | | | |
+| | 3.0 | 28 | R DOE Regulated Areas & Be Operational Areas: Floors & accessible surfaces [Housekeeping] | 2 ug/m3 |
+| | 0.2 | 1.9 | G Non-Operational Areas & Public Areas: Floors & accessible surfaces | |
+| | 3.0 | 28 | R Equipment Release to Be Operational Areas | |
+| | 0.2 | 1.9 | R Equipment Release to Non-beryllium Area of a DOE facility & Public | |
+| **Cadmium (Cd) 29CFR1910.1027** | | | | |
+| | 50 | 465 | G OSHA Regulated Areas [AFAP] & Operational Areas: Floors & accessible surfaces | 5 ug/m3 [.1027] |
+| | 3.3 | 31 | G Non-Operational Areas: Floors & accessible surfaces | 200 ug/m3 [Z.2] |
+| **Chromium, hexavalent (Cr) VI 29CFR1910.1026** | | | | |
+| | 50 | 465 | G OSHA Regulated Areas [AFAP] & Operational Areas: Floors & accessible surfaces | 5 ug/m3 |
+| | 3.3 | 31 | G Non-Operational Areas: Floors & accessible surfaces | |
+| **Lead (Pb) 29CFR1910.1025** | | | | |
+| | 500 | 4645 | G Accelerator Operational Areas & OSHA Regulated Areas [AFAP]: Floors & accessible surfaces | 50 ug/m3 |
+| | 50 | 465 | G Laboratory Operational Areas: Floors & accessible surfaces | |
+| | 22 | 200 | G Non-Operational Areas: Floors & accessible surfaces | |
+| | 22 | 200 | G OSHA 1926.62 Construction Sites: change areas, storage facilities, & lunchrooms [Housekeeping] | |
+| | 4.3 | 40 | G Eating & food prep surfaces | |
+| | 43 | 400 | G Public/Lodging/Childcare- Window troughs | |
+| | 27 | 250 | G Public/Lodging/Childcare- Window sills | |
+| | 4.3 | 40 | G Public/Lodging/Childcare- Floors, Eating & food prep surfaces | |
+| **Acrylonitrile 29CFR1910.1045** | | | | |
+| | 43 | 400 | G OSHA Regulated Areas [AFAP] & Operational Areas: Floors & accessible surfaces | [2 ppm] 4.3 ug/m3 |
+| **Dibromodicloropropane 29CFR1910.1044** | | | | |
+| | 1.0 | 9.3 | G OSHA Regulated Areas [AFAP] & Operational Areas: Floors & accessible surfaces | [1 ppb] 0.01 ug/m3 |
+| **Methylenedianiline 29CFR1910.1050** | | | | |
+| | 0.8 | 7.5 | G OSHA Regulated Areas [AFAP] & Operational Areas: Floors & accessible surfaces | [10 ppb] 0.08 ug/m3 |
+
+### Definition (for purposes of the table above):
+
+**AFAP:** As Free As Practicable; Housekeeping- All surfaces shall be maintained as free as practicable of accumulations of [OSHA Regulated Substances]: Arsenic: 1910.1018(k); Cadmium: 1910.1027(k); Chromium: 1910.1026(j); Lead: 1910.1025(h); Acrylonitrile: 1910.1045(k) DBCP: 1910.1044(k); MDA: 1910.1050(l).
+
+The enumerated guidance criteria level is based on: OSHA Technical Manual; Section II: Chapter 2 Surface Contaminants, Skin Exposure, Biological Monitoring and Other Analyses; III. Wipe Sampling, Field Portable X-Ray Fluorescence Sampling, Dermal Sampling and Biological Monitoring; A. Surface Wipe Sampling.
+
+**Accessible surfaces:** Surfaces that can reasonably be expected to be contacted during typical operations. This would include table tops, desks tops, and other surfaces where contact with hands, arms and body are likely. [BNL]
+
+**Eating & Food Prep Surfaces** = Surfaces on which food preparation, eating & drinking are done. This includes lunchroom counters/tables; kitchen counter tops, stove tops; water cooler surfaces; and tables/desks in offices/conference rooms where food and beverage consumption is permitted. [BNL]
+
+**Equipment Release to Operational Area [Beryllium]** = Maximum removable contamination on equipment that is being released to a facility using the beryllium. Equipment must be labeled and sealed in impermeable bag or container. [DOE 10CFR850.31]
+
+**Equipment Release to Operational Area [OSHA Regulated Substance]** = Maximum removable contamination on equipment that is being released to a facility using the regulated substance. [BNL]
+
+**Equipment Release to Non-Operational Area or Public [Beryllium]** = Maximum removable contamination on equipment that is being released to the general public or to a non-beryllium area of a DOE facility. Equipment release is conditioned on the recipient's commitment to implement controls that will prevent foreseeable beryllium exposure, considering the nature of the equipment or item and its future use and the nature of the beryllium contamination. [DOE 10CFR850.31]
+
+**Equipment Release to Non-Operational Area or Public [OSHA Regulated Substance]** = Maximum removable contamination on equipment that is being released to the general public or to a Non-Operational Area. [BNL]
+
+**Housekeeping** = Maximum level allowed on accessible surfaces in Operational Areas during Non-Operational periods. Surfaces contaminated with dusts and waste must not exceed a removable contamination level criterion during Non-Operational periods. This sampling would not include the interior of installed closed systems such as enclosures, glove boxes, chambers, or ventilation systems. [DOE 10CFR850.30]
+
+**Non-Beryllium Area** = Area where beryllium is not used in a DOE facility. [DOE 10CFR 850.31]
+
+**Non-Operational Area [Beryllium]** = Area where beryllium is not used and where workers are not trained in hazards and controls. Personal hygiene control practices are not in place (hand washing is not expected on exiting the area) and eating & drinking are permitted. [BNL]
+
+**Non-Operational Area [OSHA Regulated Substance]** = Area where an OSHA Regulated Substance is not used and where workers are not trained in hazards and controls. Personal hygiene control practices are not in place (hand washing is not expected on exiting the area) and eating & drinking are permitted. [BNL]
+
+**Operational Area [Beryllium]** = Area where workers are routinely in the presence of beryllium as part of their work activity. [DOE 10CFR850.3]
+
+**Operational Area [OSHA Regulated Substance]** = Area where workers are routinely in the presence of an OSHA Regulated Substance as part of their work activity. Workers who handle the substance have been trained in hazards and controls. Substances are routinely used, handled or stored and personal hygiene control practices are in place (e.g. eating, drinking are prohibited in the area; hand washing is expected on exiting the area). Examples: lead shielding blocks, shops, and accelerator areas using organic and inorganic metallic compounds. [BNL]
+
+**OSHA Regulated Substance** = A substance regulated in 29CFR1910.1003-1054 in the expanded health standards:
+
+- **Metals:**
+  - Arsenic 29CFR1910.1018;
+  - Cadmium 29CFR1910.1027;
+  - Chromium, hexavalent 29CFR1910.1026;
+  - Lead 29CFR1910.1025
+
+- **Chemicals:**
+  - Acrylonitrile 29CFR1910.1045;
+  - Benzene 29CFR1910.1028;
+  - Dibromodicloro- propane 29CFR1910.1044;
+  - Formaldehyde 29CFR1910.1048;
+  - Methylenedianiline 29CFR1910.1050;
+  - Methylene Chloride 29CFR1910.1052;
+
+- **OSHA 13 carcinogens** = 4-Nitrobiphenyl, Chemical Abstracts Service Register Number (CAS No.) 92933; alpha-Naphthylamine, CAS No. 134327; methyl chloromethyl ether, CAS No. 107302; 3,3'-Dichlorobenzidine (and its salts) CAS No. 91941; bis-Chloromethyl ether, CAS No. 542881; beta-Naphthylamine, CAS No. 91598; Benzidine, CAS No. 92875; 4-Aminodiphenyl, CAS No. 92671; Ethyleneimine, CAS No. 151564; beta-Propiolactone, CAS No. 57578; 2-Acetylaminofluorene, CAS No. 53963; 4-Dimethylaminoazo-benzene, CAS No. 60117; and N-Nitrosodimethylamine, CAS No. 62759. [OSHA]
+
+**Public** = Persons who are not: DOE employees, BSA employees, contractors, sub-contractors, and persons with Student, Intern, User or Guest appointments. The public includes visitors and family members living in residence at Upton. They are not trained by BNL in hazards and controls of toxic substances. [BNL]
+
+**Public/ Lodging/Childcare Areas** = Area open to the public for periods longer than short visits or tours or areas intended for frequent access by visitors and/or family members. Eating and drinking is allowed in public areas. Occupants are not trained in the hazards of the metal or control measures. Hand washing is not expected on exit of the area. Public areas include: Science Museum (935), Coin Laundry (363), Berkner Hall (388), Swimming Pool (462), Gymnasium (461), Brookhaven Center (30), Research Support Building (400), BNL Upton on-site housing: Cavendish (153), Compton (170), Curie (258), Fleming (180), Guest House (257), Danish House (388), Apartments, Efficiencies; and areas with high occupancy by children: Child Development Center (370), Recreation Hall (317), School House (373) [BNL]
+
+**Regulated Area [Beryllium]** = Area demarcated by the responsible employer in which the airborne concentration of beryllium exceeds, or can reasonably be expected to exceed, the action level. [DOE 10CFR850.3]
+
+**Regulated Area [OSHA Regulated Substance]** = Area where an OSHA Regulated Substance is used in a manner that airborne exposure levels exceed the Permissible Exposure Limit. Area is formally demarcated and access to the area is controlled to those meeting the entry requirements in the OSHA regulation. Personal hygiene control practices are in place; eating and drinking are prohibited; hand washing is expected on exiting the area. OSHA standards require these areas to be "As Free As Practicable". The OSHA Technical Manual (G1) provides a recommended method to enumerate AFAP [BNL]
+
+---
+
+# IH 75190 Attachment 9.4
+## Environmental Evaluation of Surface Wipe Sampling for Chemicals/Metals
+
+**Operation Description:** Field samples for potential metals or chemicals are collected on pre-moistened pads. This process concentrates toxic substances on the media. The wipes are either sent off-site for analysis or in some instances are analyzed at BNL by the IH Group using direct reading meters.
+
+**Frequency of Operation:** 10 to 20 times per year.
+
+**Environmental impact:**
+
+- The wipes sampled at BNL are consumed in the analysis at the end of test by the off-site lab. Conformance with proper wipe disposal by the off-site vendor laboratory is validated to BNL IH Group's satisfaction in the AHIA Accreditation process.
+- PPE used during sampling and the paper templates are disposed of at the direction of the EPD ECR. The current policy is for disposal as non-hazardous waste. This is justified because the concentration is too low to be of concern (a few micrograms per wipe surface).
+
+**Waste Disposal:**
+
+- PPE and paper templates are disposed of as non-hazardous waste, unless otherwise directed by EPD.
+
+---
+
+# Brookhaven National Laboratory
+## Safety & Health Service Division
+## Industrial Hygiene Group
+
+# Surface Contamination Sampling Form
+
+**BNL-IH75190 Attachment 9.5 Sample- Do not use**
+
+**Analyte:**
+
+_____ LEAD
+
+_____ BERYLLIUM
+
+_____ CADMIUM
+
+_____ Other:
+
+**DEPT:**
+
+**BUILDING:**
+
+**LOCATION NAME, ROOM NUMBER & DESCRIPTION:**
+
+---
+
+**Sample Media:** | **Solvent:** | **Surface Area Measurement:**
+
+_____ Ghost Wipe | _____ Pre-Moistened | _____ Template
+
+_____ Cotton Gauze | _____ Distilled Water | _____ Measured Area
+
+Size: | _____ Hexane | _____ Estimated Area
+
+_____ Filter Paper | _____ Isopropanol | Other:
+
+Type & Size: | _____ Other:
+
+_____ Other:
+
+**REASON FOR SAMPLING:**
+
+_____ Area Characterization
+
+_____ Pre-Remediation
+
+_____ Post Remediation
+
+Other:
+
+---
+
+### Sample Identification
+
+| Sample Number | Sample Location | Surface Type | Surface Area |
+|---------------|-----------------|--------------|--------------|
+| Bldg# MMDDYY Analyte Symbol Sample # | | Metal / Plastic / Glass /Painted Wood / Wood / Painted Concrete / Concrete | _____ 1 ft2 |
+| | | | _____ 100 cm2 |
+| | | | other: _____________________________ |
+| | | | _____ 1 ft2 |
+| | | | _____ 100 cm2 |
+| | | | other: _____________________________ |
+| | | | _____ 1 ft2 |
+| | | | _____ 100 cm2 |
+| | | | other: _____________________________ |
+| | | | _____ 1 ft2 |
+| | | | _____ 100 cm2 |
+| | | | other: _____________________________ |
+
+_____ Additional Samples next page
+
+**Total Number of Samples:** ___________________
+
+| SAMPLE DATE: | RELINQUISHED TO SHSD IH LAB BY: (SIGNATURE): | DATE /TIME: |
+|--------------|---------------------------------------------|-------------|
+| | | / |
+
+| SAMPLES TAKEN BY: (Print Name and Signature) | RECEIVED BY SHSD IH LAB EMPLOYEE (SIGNATURE): | DATE /TIME: |
+|---------------------------------------------|----------------------------------------------|-------------|
+| / | | / |
+
+*Sample of online form*
+*Use e-Forms from SHSD web page current version*
+
+---
+
+# IH75190 Attachment 9.6
+
+## HP-IHP-75190
+
+**Environmental, Safety, Health & Quality Directorate**  
+**SHSD Industrial Hygiene**
+
+# Surface Wipe Sampling for Metals
+## Job Performance Measure (JPM) Completion Certificate
+
+| Candidate's Name | Life Number: | Qualification Number: |
+|------------------|--------------|----------------------|
+| | | HP-IHP- 75190 |
+
+---
+
+### Knowledge of the Principles of Surface Wipe Sampling - Demonstrated by Written Exam
+
+| Criteria | Qualifying Standard |
+|----------|---------------------|
+| **Hazard Analysis** | Understands the need to perform a hazard analysis of the sampling area and potential exposure to the sampler. |
+| **Personal Protective Equipment** | Understands the need to be aware of the potential surface contamination and airborne levels of contaminants and knows how to determine the need for PPE. |
+| **Sampling Protocol** | Understands the exposure monitoring logic necessary to appropriately select sampling locations to accurately measure worker, public and environmental exposure potential. |
+| **Analysis of data** | Understands the need to perform analysis on the sampling data to assess potential exposure to the sampler, worker, public and environment, and to recommend corrective actions as necessary. |
+
+---
+
+### Practical Skill Evaluation: Demonstration of Surface Wipe Methodology
+
+| Criteria | Qualifying Performance Standard | Unsat. | Recov. | Satisf. |
+|----------|--------------------------------|--------|--------|---------|
+| **Sampling Equipment** | Knows where equipment needed for the procedure is located and how to properly sign it out. | | | |
+| **Moistening Media** | a. Filter/gauze: Moistens media with the appropriate solvent. Applies solvent to moisten approximately 80% of the area of the media. Does not over moisten. b. For pre-moistened media, shows reduction in size of wipe. | | | |
+| **Size of Area & Use of Template** | Understands the importance of quantifying the area sampled. Demonstrates placing template on surface or measuring the surface area. | | | |
+| **Folding Media at each wipe step** | Demonstrates the inward folding of media after each wipe and placement of media into container so that surfaces loaded in the wiping are not exposed. | | | |
+| **NIOSH Method wipe pattern** | Demonstrates the technique of three passes of wiping in "S" pattern, changing the direction on second pass, original direction on third pass. | | | |
+| **Choose correct solvent** | Knows how to select correct solvent from Table 1. | | | |
+| **Select the correct number of samples** | Knows how to choose the appropriate numbers of samples based on Table 2. | | | |
+| **Record forms** | Shows how to correctly and completely fill all forms associated with this SOP. | | | |
+
+---
+
+I accept the responsibility for performing this task as demonstrated within this JPM and the corresponding SOP.
+
+| Candidate Signature: | Date: |
+|---------------------|-------|
+| | |
+
+I certify the candidate has satisfactorily performed each of the above listed steps and is capable of performing the task unsupervised.
+
+| Evaluator Signature: | Date: |
+|---------------------|-------|
+| | |
+
+*SOP-IH75190 JPM Form (Revision Date: 06/13/16)*

RAG-KB/Technical Guide for Wildfire Restoration - Key Information.md

@@ -0,0 +1,79 @@
+# Technical Guide for Wildfire Restoration - Key Information
+
+**Source:** IICRC/RIA/CIRI Technical Guide for Wildfire Restoration
+**Version:** Version 2, December 9th 2025
+**URL:** https://iicrc.org/wp-content/uploads/2025/12/IICRC.RIA_.CIRI-Technical-Guide-for-Wildfire-Restoration-V2-Final-2025-12.09.pdf
+**Organizations:** Institute of Inspection, Cleaning, and Restoration Certification (IICRC), Restoration Industry Association (RIA), Cleaning Industry Research Institute (CIRI)
+
+## Purpose and Scope
+
+This technical guide presents current and common methodology of prudent wildfire restoration practices. It represents thousands of restoration companies and professionals who have returned families to their homes safely using proven, science-based methodologies in accordance with peer-reviewed industry standards.
+
+## Key Message
+
+The guide addresses a growing unfounded sentiment that homes affected by wildfire smoke and its byproducts are categorically uncleanable and unrestorable. The guide emphasizes that:
+- Wildfire smoke damage is a superficial occurrence that can generally be cleaned
+- Specialized cleaning methodologies have been successfully used for decades
+- Professional restoration is science-based and proven
+- Categorical disposal of all materials and structures is inconsistent with science and industry standards
+
+## Four Core Procedural Principles
+
+### 1. Pre-Restoration Evaluation (PRE)
+- Critical first step performed by the restorer
+- Establishes degree of impact from wildfire event
+- Goal: identify presence of wildfire-related combustion byproducts through visual and sensory inspection
+- Identifies key risk factors
+- Determines whether restoration can begin immediately or if formal assessment is needed
+
+### 2. Pre-Restoration Assessment (PRA)
+- Formal, third-party process
+- Typically performed by Industrial Hygienist (IH) or qualified OEHS professional
+- Triggered by specific findings in PRE, stakeholder request, or AHJ requirements
+- Uses scientific sampling and laboratory analysis
+- Definitively characterizes type and extent of combustion byproducts
+- Establishes data-driven, defensible scope of work
+
+### 3. The Restoration Phase
+- Physical process of removing wildfire-related combustion byproducts
+- Goal: return structure, systems, and contents to clean, safe, odor-free condition
+- Includes detailed source-removal cleaning
+- Indoor air quality management
+- Proper documentation and disposal of non-salvageable items
+
+### 4. Project Completion
+- Final critical phase
+- Establishes success of restoration efforts
+- Collects evidence that combustion byproducts have been effectively removed
+- Two components:
+  - **Restoration Completion Evaluation (RCE)**: conducted by restorer
+  - **Post Restoration Verification (PRV)**: performed by independent third party when necessary
+
+## Key Terminology
+
+**Combustion By-Products (CBP):** Resulting substances (char, ash, smoke) created from a fire event
+
+**Combustion Byproducts of Concern (CBC):** Wildfire-related combustion byproducts that can pose potential for continued damage or elevated human health risks
+
+**Burn Zone:** Wildfire impact zone with direct flame impingement or significant radiant heat
+
+**Near-Field Zone:** Extends from fire perimeter to approximately 1-10 kilometers (0.6 to 6.2 miles); affected by hot, turbulent smoke plume forcing particulates and gaseous combustion byproducts (VOCs) into building envelope
+
+**Far-Field Zone:** Extends beyond Near-Field Zone, potentially for hundreds of miles; primary impact is infiltration of fine particulate matter (PM2.5); impact is often surface-level and highly correctable
+
+## Document Structure
+
+The guide includes:
+- Introduction
+- Combustion Byproducts of Concern (CBC)
+- Impact Zones
+- Pre-Restoration Evaluation and Assessment
+- The Restoration Phase (health/safety, procedures, removal of unrestorable goods)
+- Project Completion
+- Glossary of Terms
+- References
+
+## Related Reference
+
+The guide references the **AIHA Technical Guide for Wildfire Impact Assessments for the OEHS Professional**, 2nd edition (2025) for more information on assessment processes.
+

RAG-KB/wildfire_soot_particulate_removal_full_text_extraction.md

@@ -0,0 +1,134 @@
+SOOT PARTICLES:
+A Procedural Guide for Containing and Removing Wildfire-Caused Soot in Buildings
+
+By Patrick J. Moffett, REA, CHMM
+Environmental Management & Engineering, Inc.
+Huntington Beach, California
+
+Copyright © 1997, 2002, 2008
+All Rights Reserved
+
+
+SOOT PARTICLES:
+A Procedural Guide for Containing and Removing Wildfire-Caused Soot in Buildings
+
+By Patrick J. Moffett, REA, CHMM
+Environmental Management & Engineering, Inc.
+Huntington Beach, California
+
+Copyright © 1997, 2002, 2008
+All Rights Reserved
+
+
+COMMENTARY
+
+The purpose of this paper is to provide a procedural guide for the restoration of buildings and contents contaminated with wildfire-caused soot. This paper was written primarily for restorers, insurance adjusters, and building owners who are dealing with extensive wildfire-caused soot contamination. This paper is not intended to be a comprehensive restoration manual for all smoke and soot contamination conditions. This paper focuses on wildfire-caused soot, ash, and odor contamination, and addresses worker and occupant safety and health issues; and in 2008, the paper was updated to address new concerns regarding ultrafine particles.
+
+Worker Safety
+
+In recent years, many restoration workers have been involved in cleaning wildfire-caused soot contamination. During these projects, workers often were observed wearing little or no respiratory protection. In some cases, workers were observed wearing simple dust masks or N95 respirators while performing soot cleaning activities. In other cases, workers were observed wearing N100 respirators or half-face respirators equipped with HEPA cartridges. In some cases, workers were observed wearing full-face respirators equipped with HEPA and organic vapor cartridges.
+
+The question arises: What type of respiratory protection is appropriate for wildfire soot cleanup? In order to answer this question, it is important to understand the nature of wildfire-caused soot, including the size of the soot particles, the chemical composition of the soot, and the potential health hazards associated with exposure to soot.
+
+PART I
+Particles and Chemicals in Smoke and Soot
+
+Wildfire Smoke
+
+Smoke is a complex mixture of gases and particles produced by the incomplete combustion of organic materials. Wildfire smoke contains numerous chemicals, including carbon monoxide, nitrogen oxides, hydrocarbons, aldehydes, ketones, alcohols, benzo[a]pyrene, and organic acids. The composition of wildfire smoke varies depending on the type of fuel burned, the combustion temperature, and the availability of oxygen.
+
+Hot, flaming combustion tends to produce black smoke composed primarily of elemental carbon particles. Cooler, smoldering combustion tends to produce white or gray smoke composed of incompletely combusted organic materials.
+
+Soot
+
+Soot is composed primarily of carbon particles produced by incomplete combustion. Soot particles are often coated with organic chemicals, including polycyclic aromatic hydrocarbons (PAHs) and other combustion byproducts. The chemical composition of soot varies depending on the type of fuel burned.
+
+Vegetation fires tend to produce gray or light-colored ash and soot composed primarily of inorganic ash and partially combusted organic materials. Fires involving petroleum products, plastics, roofing materials, and synthetic furnishings tend to produce black, oily soot composed primarily of carbon black.
+
+Particle Size
+
+Soot particles vary widely in size. Candle soot particles typically range from approximately 0.06 to 0.1 micrometers (µm) in diameter. Wildfire-caused soot particles may range from less than 0.1 µm to more than 30 µm in diameter. Larger particles, including embers, may be several inches in diameter.
+
+Particle Deposition
+
+Soot particles may be deposited on building surfaces by a variety of mechanisms, including gravity settling, impaction, diffusion, thermophoresis, and electrostatic attraction. Thermophoresis causes particles to move from warmer air toward cooler surfaces. Electrostatic attraction causes charged particles to be attracted to oppositely charged surfaces.
+
+As a result of these mechanisms, soot often deposits preferentially on cooler surfaces, such as exterior walls, window frames, and surfaces near air leaks. Moist surfaces also tend to attract soot particles.
+
+Firestorms and Convection
+
+Large wildfires can generate intense convection currents, sometimes referred to as firestorms. These convection currents can create strong winds, dust devils, and fire whirls that carry smoke, ash, and soot over long distances. Buildings located near wildfires may be subjected to complex airflow patterns that influence the deposition of soot on interior and exterior surfaces.
+
+PART II
+Environmental and Human Health Concerns
+
+Chemical Composition
+
+Soot typically contains approximately 60 percent carbon by weight. The remaining portion consists of a complex mixture of organic and inorganic chemicals, including PAHs and heavy metals such as arsenic, cadmium, chromium, and nickel. Thousands of individual compounds may be present in soot, many of which can be identified only by gas chromatography/mass spectrometry (GC/MS) analysis.
+
+Health Hazards
+
+Soot has been recognized as a human carcinogen. Occupational exposure to soot has been associated with an increased risk of skin cancer, lung cancer, and other health effects. Historically, chimney sweeps were known to suffer high rates of cancer due to soot exposure.
+
+Workers involved in wildfire soot cleanup may be exposed to high concentrations of soot particles and associated chemicals. In some cases, these exposures may be comparable to or greater than those experienced by chimney sweeps and other workers historically exposed to soot.
+
+Ultrafine Particles
+
+In recent years, increased attention has been focused on ultrafine particles (particles smaller than 0.1 µm). Ultrafine particles are capable of penetrating deep into the lungs and entering the bloodstream. These particles may cause inflammation, oxidative stress, and other adverse health effects.
+
+Wildfire smoke and soot contain large numbers of ultrafine particles. As a result, wildfire soot cleanup workers may be at risk of exposure to ultrafine particles unless appropriate respiratory protection is used.
+
+Respiratory Protection
+
+Respiratory protection for wildfire soot cleanup should be selected based on the size of the particles present and the presence of gaseous contaminants. Simple dust masks and N95 respirators are not adequate to protect against fine and ultrafine soot particles.
+
+P100 respirators provide a minimum filtration efficiency of 99.97 percent for oil-based particles and are suitable for protection against fine and ultrafine soot particles. However, P100 particulate filters do not provide protection against gaseous contaminants such as carbon monoxide and organic vapors.
+
+In situations where organic vapors or other gases are present, respirators equipped with both P100 particulate filters and organic vapor cartridges may be required. Full-face respirators provide additional protection for the eyes and face.
+
+PART III
+Procedures for Removing Wildfire Soot from Contents
+
+General Principles
+
+The removal of wildfire-caused soot from contents should be approached systematically to minimize the spread of contamination and protect workers and occupants. Contents should be evaluated to determine whether they can be cleaned or must be discarded.
+
+Dry Cleaning Methods
+
+Dry cleaning methods are often preferred for removing soot from contents because they minimize the spread of contamination and reduce the risk of driving soot deeper into porous materials. Examples of dry cleaning methods include HEPA vacuuming, dry sponging, and the use of specialized dry cleaning compounds.
+
+Wet Cleaning Methods
+
+Wet cleaning methods may be used when dry methods are not effective. Wet cleaning should be performed carefully to avoid spreading contamination. Detergents and cleaning agents should be selected based on the type of material being cleaned and the nature of the soot.
+
+Electronics
+
+Electronics contaminated with wildfire soot require special handling. Soot particles can cause corrosion and electrical shorts. In many cases, electronics should be evaluated by qualified technicians and may require specialized cleaning or replacement.
+
+PART IV
+Procedures for Removing Wildfire Soot from Buildings
+
+Containment
+
+Containment is critical to prevent the spread of soot during cleaning activities. Affected areas should be isolated using plastic sheeting and negative air pressure where feasible.
+
+Surface Cleaning
+
+Building surfaces should be cleaned using methods appropriate for the type of surface and the degree of contamination. Dry cleaning methods should be used whenever possible. Wet cleaning may be used when necessary, with care taken to avoid spreading soot.
+
+HVAC Systems
+
+Heating, ventilation, and air conditioning (HVAC) systems can become contaminated with wildfire soot. HVAC systems should be inspected and cleaned as necessary to prevent the redistribution of soot throughout the building.
+
+Post-Cleaning Verification
+
+After cleaning, surfaces should be inspected to verify that soot has been removed. In some cases, surface sampling or air monitoring may be used to confirm the effectiveness of cleaning.
+
+Author
+
+Patrick J. Moffett, REA, CHMM, is the principal of Environmental Management & Engineering, Inc., based in Huntington Beach, California. He has extensive experience in environmental health and safety, industrial hygiene, and hazardous materials management.
+
+References
+
+[References as listed in the original document]
+

README.md

@@ -0,0 +1,70 @@
+---
+title: FDAM AI Pipeline
+emoji: "\U0001F525"
+colorFrom: red
+colorTo: yellow
+sdk: gradio
+sdk_version: "6.3.0"
+app_file: app.py
+pinned: false
+suggested_hardware: l4x4
+---
+
+# FDAM AI Pipeline
+
+**Fire Damage Assessment Methodology v4.0.1** - An AI-powered system that generates professional Cleaning Specifications / Scope of Work documents for fire damage restoration.
+
+## Features
+
+- **AI-Powered Image Analysis**: Uses Qwen3-VL vision model to detect fire damage zones, conditions, and materials
+- **FDAM Compliant**: Implements Fire Damage Assessment Methodology v4.0.1 standards
+- **Automated Calculations**: Air filtration, sample density, labor estimates per FDAM formulas
+- **Professional PDF Output**: Generates ready-to-use Scope of Work documents
+- **Session Persistence**: Save and resume assessments via browser localStorage
+
+## How to Use
+
+1. **Project Info**: Enter project details, facility classification, and assessor information
+2. **Building/Rooms**: Add rooms with dimensions (length, width, ceiling height)
+3. **Images**: Upload fire damage photos and associate with rooms
+4. **Observations**: Record qualitative observations (odor, soot, char, etc.)
+5. **Generate**: Click "Generate Assessment" to run AI analysis and produce documents
+
+## Technical Details
+
+### Model Stack (~90GB VRAM)
+- **Vision**: Qwen3-VL-30B-A3B-Instruct (~58GB)
+- **Embeddings**: Qwen3-VL-Embedding-8B (~16GB)
+- **Reranker**: Qwen3-VL-Reranker-8B (~16GB)
+
+### Zone Classifications
+- **Burn Zone**: Direct fire involvement, structural damage
+- **Near-Field**: Adjacent to burn zone, heavy smoke/heat exposure
+- **Far-Field**: Smoke migration only, light deposits
+
+### Condition Levels
+- **Background**: No visible contamination
+- **Light**: Faint discoloration, minimal deposits
+- **Moderate**: Visible film/deposits
+- **Heavy**: Thick deposits, surface texture obscured
+- **Structural Damage**: Physical damage requiring repair
+
+## Development
+
+```bash
+# Local development (mock models)
+MOCK_MODELS=true python app.py
+
+# Run tests
+pytest tests/ -v
+```
+
+## Requirements
+
+- Python 3.10+
+- 96GB GPU memory for real model inference (4x L4 or equivalent)
+- See `requirements.txt` for full dependencies
+
+## License
+
+Proprietary - For authorized use only.

app.py

@@ -0,0 +1,428 @@
+"""FDAM AI Pipeline - Fire Damage Assessment Methodology v4.0.1
+
+Main Gradio application entry point with session state and tab validation.
+"""
+
+import gradio as gr
+
+from config.settings import settings
+from models.loader import get_models
+from ui.state import SessionState, create_new_session, session_to_json, session_from_json
+from ui.storage import get_head_html
+from ui.tabs import project, rooms, images, observations, results
+
+
+def create_app() -> gr.Blocks:
+    """Create the main Gradio application."""
+
+    # Initialize models at startup
+    model_stack = get_models()
+
+    # Note: head parameter moved to launch() in Gradio 6.0
+    # localStorage JS will be injected there
+    with gr.Blocks(
+        title="FDAM AI Pipeline - Fire Damage Assessment",
+    ) as app:
+        # Session state (stored in Gradio State component)
+        session_state = gr.State(value=create_new_session())
+
+        # Header
+        gr.Markdown(
+            """
+            # FDAM AI Pipeline
+            ## Fire Damage Assessment Methodology v4.0.1
+
+            Upload images and project information to generate a professional
+            Cleaning Specification / Scope of Work.
+            """
+        )
+
+        # Mode indicator
+        if settings.mock_models:
+            gr.Markdown(
+                """
+                > **Development Mode**: Using mock models for testing.
+                > Set `MOCK_MODELS=false` for production inference.
+                """
+            )
+
+        # Tab navigation
+        with gr.Tabs() as tabs:
+            # Tab 1: Project Information
+            with gr.Tab("1. Project Info", id=0):
+                tab1 = project.create_tab()
+
+            # Tab 2: Building/Rooms
+            with gr.Tab("2. Building/Rooms", id=1):
+                tab2 = rooms.create_tab()
+
+            # Tab 3: Images
+            with gr.Tab("3. Images", id=2):
+                tab3 = images.create_tab()
+
+            # Tab 4: Observations
+            with gr.Tab("4. Observations", id=3):
+                tab4 = observations.create_tab()
+
+            # Tab 5: Generate Results
+            with gr.Tab("5. Generate Results", id=4):
+                tab5 = results.create_tab()
+
+        # --- Event Handlers ---
+
+        # Tab 1: Project Info
+        tab1["validate_btn"].click(
+            fn=project.validate_and_continue,
+            inputs=[
+                session_state,
+                tab1["project_name"],
+                tab1["address"],
+                tab1["city"],
+                tab1["state"],
+                tab1["zip_code"],
+                tab1["client_name"],
+                tab1["fire_date"],
+                tab1["assessment_date"],
+                tab1["facility_classification"],
+                tab1["construction_era"],
+                tab1["assessor_name"],
+                tab1["assessor_credentials"],
+            ],
+            outputs=[
+                session_state,
+                tab1["validation_status"],
+                tabs,
+            ],
+        )
+
+        # Tab 2: Building/Rooms
+        tab2["add_room_btn"].click(
+            fn=rooms.add_room,
+            inputs=[
+                session_state,
+                tab2["room_name"],
+                tab2["room_floor"],
+                tab2["room_length"],
+                tab2["room_width"],
+                tab2["room_height"],
+            ],
+            outputs=[
+                session_state,
+                tab2["rooms_table"],
+                tab2["validation_status"],
+                tab2["room_count"],
+                tab2["total_area"],
+                tab2["total_volume"],
+                tab2["room_name"],
+                tab2["room_floor"],
+                tab2["room_length"],
+                tab2["room_width"],
+                tab2["room_height"],
+            ],
+        )
+
+        tab2["clear_form_btn"].click(
+            fn=lambda: ("", "", None, None, None),
+            outputs=[
+                tab2["room_name"],
+                tab2["room_floor"],
+                tab2["room_length"],
+                tab2["room_width"],
+                tab2["room_height"],
+            ],
+        )
+
+        tab2["remove_last_btn"].click(
+            fn=rooms.remove_last_room,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab2["rooms_table"],
+                tab2["validation_status"],
+                tab2["room_count"],
+                tab2["total_area"],
+                tab2["total_volume"],
+            ],
+        )
+
+        tab2["clear_all_btn"].click(
+            fn=rooms.clear_all_rooms,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab2["rooms_table"],
+                tab2["validation_status"],
+                tab2["room_count"],
+                tab2["total_area"],
+                tab2["total_volume"],
+            ],
+        )
+
+        tab2["validate_btn"].click(
+            fn=rooms.validate_and_continue,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab2["validation_status"],
+                tabs,
+            ],
+        )
+
+        tab2["back_btn"].click(
+            fn=lambda: 0,
+            outputs=[tabs],
+        )
+
+        # Tab 3: Images
+        # Update room dropdown when entering tab
+        tabs.select(
+            fn=lambda session, selected: (
+                images.update_room_choices(session) if selected == 2 else gr.update()
+            ),
+            inputs=[session_state, tabs],
+            outputs=[tab3["room_select"]],
+        )
+
+        tab3["add_image_btn"].click(
+            fn=images.add_image,
+            inputs=[
+                session_state,
+                tab3["image_upload"],
+                tab3["room_select"],
+                tab3["image_description"],
+            ],
+            outputs=[
+                session_state,
+                tab3["images_gallery"],
+                tab3["validation_status"],
+                tab3["image_count"],
+                tab3["image_upload"],
+                tab3["image_description"],
+                tab3["room_select"],
+            ],
+        )
+
+        tab3["clear_upload_btn"].click(
+            fn=lambda: (None, ""),
+            outputs=[
+                tab3["image_upload"],
+                tab3["image_description"],
+            ],
+        )
+
+        tab3["remove_last_btn"].click(
+            fn=images.remove_last_image,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab3["images_gallery"],
+                tab3["validation_status"],
+                tab3["image_count"],
+            ],
+        )
+
+        tab3["clear_all_btn"].click(
+            fn=images.clear_all_images,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab3["images_gallery"],
+                tab3["validation_status"],
+                tab3["image_count"],
+            ],
+        )
+
+        tab3["validate_btn"].click(
+            fn=images.validate_and_continue,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab3["validation_status"],
+                tabs,
+            ],
+        )
+
+        tab3["back_btn"].click(
+            fn=lambda: 1,
+            outputs=[tabs],
+        )
+
+        # Tab 4: Observations
+        tab4["validate_btn"].click(
+            fn=observations.validate_and_continue,
+            inputs=[
+                session_state,
+                tab4["smoke_odor"],
+                tab4["odor_intensity"],
+                tab4["visible_soot"],
+                tab4["soot_description"],
+                tab4["large_char"],
+                tab4["char_density"],
+                tab4["ash_residue"],
+                tab4["ash_description"],
+                tab4["surface_discoloration"],
+                tab4["discoloration_description"],
+                tab4["dust_interference"],
+                tab4["dust_notes"],
+                tab4["wildfire_indicators"],
+                tab4["wildfire_notes"],
+                tab4["additional_notes"],
+            ],
+            outputs=[
+                session_state,
+                tab4["validation_status"],
+                tabs,
+            ],
+        )
+
+        tab4["back_btn"].click(
+            fn=lambda: 2,
+            outputs=[tabs],
+        )
+
+        # Tab 5: Generate Results
+        # Update preflight check when entering tab
+        tabs.select(
+            fn=lambda session, selected: (
+                results.check_preflight(session) if selected == 4 else ""
+            ),
+            inputs=[session_state, tabs],
+            outputs=[tab5["preflight_status"]],
+        )
+
+        tab5["generate_btn"].click(
+            fn=results.generate_assessment,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab5["processing_status"],
+                tab5["progress_html"],
+                tab5["annotated_gallery"],
+                tab5["stats_output"],
+                tab5["sow_output"],
+                tab5["download_md"],
+                tab5["download_pdf"],
+            ],
+        )
+
+        tab5["regenerate_btn"].click(
+            fn=results.generate_assessment,
+            inputs=[session_state],
+            outputs=[
+                session_state,
+                tab5["processing_status"],
+                tab5["progress_html"],
+                tab5["annotated_gallery"],
+                tab5["stats_output"],
+                tab5["sow_output"],
+                tab5["download_md"],
+                tab5["download_pdf"],
+            ],
+        )
+
+        tab5["back_btn"].click(
+            fn=lambda: 3,
+            outputs=[tabs],
+        )
+
+        # --- Session Resume Handlers ---
+        # Load form data when navigating to tabs
+
+        # Tab 1 (Project): Load project form fields
+        tabs.select(
+            fn=lambda session, selected: (
+                project.load_form_from_session(session) if selected == 0
+                else tuple([gr.update()] * 12)
+            ),
+            inputs=[session_state, tabs],
+            outputs=[
+                tab1["project_name"],
+                tab1["address"],
+                tab1["city"],
+                tab1["state"],
+                tab1["zip_code"],
+                tab1["client_name"],
+                tab1["fire_date"],
+                tab1["assessment_date"],
+                tab1["facility_classification"],
+                tab1["construction_era"],
+                tab1["assessor_name"],
+                tab1["assessor_credentials"],
+            ],
+        )
+
+        # Tab 2 (Rooms): Load room table and stats
+        tabs.select(
+            fn=lambda session, selected: (
+                rooms.load_from_session(session) if selected == 1
+                else (gr.update(), gr.update(), gr.update(), gr.update())
+            ),
+            inputs=[session_state, tabs],
+            outputs=[
+                tab2["rooms_table"],
+                tab2["room_count"],
+                tab2["total_area"],
+                tab2["total_volume"],
+            ],
+        )
+
+        # Tab 3 (Images): Load gallery and count (room dropdown already handled above)
+        tabs.select(
+            fn=lambda session, selected: (
+                images.load_from_session(session) if selected == 2
+                else (gr.update(), gr.update(), gr.update())
+            ),
+            inputs=[session_state, tabs],
+            outputs=[
+                tab3["images_gallery"],
+                tab3["image_count"],
+                tab3["resume_warning"],
+            ],
+        )
+
+        # Tab 4 (Observations): Load observation form fields
+        tabs.select(
+            fn=lambda session, selected: (
+                observations.load_form_from_session(session) if selected == 3
+                else tuple([gr.update()] * 15)
+            ),
+            inputs=[session_state, tabs],
+            outputs=[
+                tab4["smoke_odor"],
+                tab4["odor_intensity"],
+                tab4["visible_soot"],
+                tab4["soot_description"],
+                tab4["large_char"],
+                tab4["char_density"],
+                tab4["ash_residue"],
+                tab4["ash_description"],
+                tab4["surface_discoloration"],
+                tab4["discoloration_description"],
+                tab4["dust_interference"],
+                tab4["dust_notes"],
+                tab4["wildfire_indicators"],
+                tab4["wildfire_notes"],
+                tab4["additional_notes"],
+            ],
+        )
+
+    return app
+
+
+def main():
+    """Entry point for the application."""
+    print(f"Starting FDAM AI Pipeline...")
+    print(f"Mock models: {settings.mock_models}")
+    print(f"Server: {settings.server_host}:{settings.server_port}")
+
+    app = create_app()
+    app.launch(
+        server_name=settings.server_host,
+        server_port=settings.server_port,
+        share=False,
+        head=get_head_html(),  # Inject localStorage JavaScript
+    )
+
+
+if __name__ == "__main__":
+    main()

config/inference.py

@@ -0,0 +1,34 @@
+"""Model inference configuration parameters."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class VisionInferenceConfig:
+    """Configuration for vision model inference."""
+
+    max_new_tokens: int = 4096
+    temperature: float = 0.1
+    top_p: float = 0.9
+    do_sample: bool = True
+
+
+@dataclass
+class EmbeddingConfig:
+    """Configuration for embedding model."""
+
+    embedding_dimension: int = 768
+    normalize: bool = True
+
+
+@dataclass
+class RerankerConfig:
+    """Configuration for reranker model."""
+
+    top_k: int = 5
+
+
+# Default configurations
+vision_config = VisionInferenceConfig()
+embedding_config = EmbeddingConfig()
+reranker_config = RerankerConfig()

config/settings.py

@@ -0,0 +1,45 @@
+"""Application settings with environment variable support."""
+
+from typing import Literal
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """FDAM AI Pipeline configuration."""
+
+    # Environment
+    environment: Literal["development", "production"] = "development"
+
+    # Model loading - set MOCK_MODELS=true for local dev on RTX 4090
+    mock_models: bool = True
+
+    # Model paths (for production on HuggingFace Spaces)
+    vision_model: str = "Qwen/Qwen3-VL-30B-A3B-Instruct"
+    embedding_model: str = "Qwen/Qwen3-VL-Embedding-8B"
+    reranker_model: str = "Qwen/Qwen3-VL-Reranker-8B"
+
+    # Fallback vision model if VRAM issues
+    vision_model_fallback: str = "Qwen/Qwen3-VL-8B-Instruct"
+
+    # ChromaDB
+    chroma_persist_dir: str = "./chroma_db"
+
+    # Knowledge base
+    knowledge_base_dir: str = "./RAG-KB"
+
+    # Gradio server (0.0.0.0 required for WSL)
+    server_host: str = "0.0.0.0"
+    server_port: int = 7860
+
+    # Assessment limits
+    max_images_per_assessment: int = 20
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="",
+        case_sensitive=False,
+    )
+
+
+# Singleton instance
+settings = Settings()

models/loader.py

@@ -0,0 +1,37 @@
+"""Model loading with mock/real switching based on environment."""
+
+from typing import Union
+
+from config.settings import settings
+
+# Type alias for model stack
+ModelStack = Union["MockModelStack", "RealModelStack"]  # noqa: F821
+
+# Lazy singleton
+_model_stack: ModelStack | None = None
+
+
+def get_model_stack() -> ModelStack:
+    """Get model stack based on environment configuration."""
+    if settings.mock_models:
+        from models.mock import MockModelStack
+
+        return MockModelStack().load_all()
+    else:
+        from models.real import RealModelStack
+
+        return RealModelStack().load_all()
+
+
+def get_models() -> ModelStack:
+    """Get or create the singleton model stack."""
+    global _model_stack
+    if _model_stack is None:
+        _model_stack = get_model_stack()
+    return _model_stack
+
+
+def reset_models() -> None:
+    """Reset the model stack (useful for testing)."""
+    global _model_stack
+    _model_stack = None

models/mock.py

@@ -0,0 +1,157 @@
+"""Mock model implementations for local development on RTX 4090."""
+
+import random
+from typing import Any
+from PIL import Image
+
+
+class MockVisionModel:
+    """Mock vision model that returns realistic JSON responses."""
+
+    ZONES = ["burn", "near-field", "far-field"]
+    CONDITIONS = ["background", "light", "moderate", "heavy", "structural-damage"]
+    MATERIALS = [
+        {"type": "steel", "category": "non-porous"},
+        {"type": "concrete", "category": "non-porous"},
+        {"type": "glass", "category": "non-porous"},
+        {"type": "cmu", "category": "non-porous"},
+        {"type": "drywall-painted", "category": "semi-porous"},
+        {"type": "wood-sealed", "category": "semi-porous"},
+        {"type": "drywall-unpainted", "category": "porous"},
+        {"type": "carpet", "category": "porous"},
+        {"type": "insulation-fiberglass", "category": "porous"},
+        {"type": "acoustic-tile", "category": "porous"},
+        {"type": "ductwork-rigid", "category": "hvac"},
+        {"type": "ductwork-flexible", "category": "hvac"},
+    ]
+
+    def analyze_image(self, image: Image.Image, context: str = "") -> dict[str, Any]:
+        """Return mock vision analysis matching the spec schema."""
+        selected_zone = random.choice(self.ZONES)
+        selected_condition = random.choice(self.CONDITIONS)
+
+        # Generate 2-4 random materials
+        num_materials = random.randint(2, 4)
+        materials = []
+        for _ in range(num_materials):
+            mat = random.choice(self.MATERIALS).copy()
+            mat.update(
+                {
+                    "confidence": round(random.uniform(0.75, 0.95), 2),
+                    "location_description": "Visible in image",
+                    "bounding_box": {
+                        "x": round(random.uniform(0.1, 0.3), 2),
+                        "y": round(random.uniform(0.1, 0.3), 2),
+                        "width": round(random.uniform(0.2, 0.5), 2),
+                        "height": round(random.uniform(0.2, 0.5), 2),
+                    },
+                }
+            )
+            materials.append(mat)
+
+        soot_visible = random.choice([True, False])
+        char_visible = random.choice([True, False])
+        ash_visible = random.choice([True, False])
+
+        return {
+            "zone": {
+                "classification": selected_zone,
+                "confidence": round(random.uniform(0.7, 0.95), 2),
+                "reasoning": f"Mock analysis detected {selected_zone} zone characteristics based on visible damage patterns",
+            },
+            "condition": {
+                "level": selected_condition,
+                "confidence": round(random.uniform(0.65, 0.90), 2),
+                "reasoning": f"Surface shows {selected_condition} contamination levels",
+            },
+            "materials": materials,
+            "combustion_indicators": {
+                "soot_visible": soot_visible,
+                "soot_pattern": "Visible deposition on horizontal surfaces"
+                if soot_visible
+                else None,
+                "char_visible": char_visible,
+                "char_description": "Angular black particles visible"
+                if char_visible
+                else None,
+                "ash_visible": ash_visible,
+                "ash_description": "Gray powdery residue on surfaces"
+                if ash_visible
+                else None,
+            },
+            "structural_concerns": [],
+            "access_issues": [],
+            "recommended_sampling_locations": [
+                {
+                    "description": "Center of visible contamination",
+                    "sample_type": "tape_lift",
+                    "priority": "high",
+                },
+                {
+                    "description": "Comparison area with less contamination",
+                    "sample_type": "surface_wipe",
+                    "priority": "medium",
+                },
+            ],
+            "flags_for_review": [],
+        }
+
+
+class MockEmbeddingModel:
+    """Mock embedding model that returns random vectors."""
+
+    def __init__(self, dimension: int = 768):
+        self.dimension = dimension
+
+    def embed(self, text: str) -> list[float]:
+        """Return mock embedding vector."""
+        # Use hash of text for reproducibility
+        random.seed(hash(text) % (2**32))
+        embedding = [random.uniform(-1, 1) for _ in range(self.dimension)]
+        random.seed()  # Reset seed
+        return embedding
+
+    def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Return mock embeddings for a batch of texts."""
+        return [self.embed(text) for text in texts]
+
+
+class MockRerankerModel:
+    """Mock reranker that returns random scores."""
+
+    def rerank(self, query: str, documents: list[str]) -> list[float]:
+        """Return mock reranking scores."""
+        # Higher scores for documents that share more words with query
+        scores = []
+        query_words = set(query.lower().split())
+        for doc in documents:
+            doc_words = set(doc.lower().split())
+            overlap = len(query_words & doc_words)
+            base_score = overlap / max(len(query_words), 1)
+            noise = random.uniform(-0.1, 0.1)
+            scores.append(min(1.0, max(0.0, base_score + noise)))
+        return scores
+
+
+class MockModelStack:
+    """Mock model stack for local development."""
+
+    def __init__(self):
+        self.vision = MockVisionModel()
+        self.embedding = MockEmbeddingModel()
+        self.reranker = MockRerankerModel()
+        self.loaded = False
+
+    def load_all(self) -> "MockModelStack":
+        """Simulate model loading."""
+        print("[MOCK] Loading mock models for local development...")
+        print("[MOCK] Vision model: MockVisionModel")
+        print("[MOCK] Embedding model: MockEmbeddingModel")
+        print("[MOCK] Reranker model: MockRerankerModel")
+        self.loaded = True
+        print("[MOCK] All mock models loaded successfully.")
+        return self
+
+    def is_loaded(self) -> bool:
+        """Check if models are loaded."""
+        return self.loaded

models/real.py

@@ -0,0 +1,439 @@
+"""Real model loading for production (HuggingFace Spaces with 4xL4 GPUs).
+
+This module loads the actual Qwen3-VL models for production use.
+Requires ~90GB VRAM (4xL4 with 96GB total).
+"""
+
+import json
+import logging
+import re
+import torch
+from typing import Any
+from PIL import Image
+
+from config.settings import settings
+
+logger = logging.getLogger(__name__)
+
+
+class RealModelStack:
+    """Real model stack for production on HuggingFace Spaces."""
+
+    def __init__(self):
+        self.models: dict[str, Any] = {}
+        self.processors: dict[str, Any] = {}
+        self.loaded = False
+
+    def load_all(self) -> "RealModelStack":
+        """Load all models with device_map='auto' for multi-GPU distribution."""
+        from transformers import AutoModel, AutoProcessor
+
+        print(f"Loading models on {'cuda' if torch.cuda.is_available() else 'cpu'}...")
+
+        # Vision model (~58GB in BF16)
+        print(f"Loading vision model: {settings.vision_model}...")
+        try:
+            from transformers import Qwen3VLMoeForConditionalGeneration
+
+            self.models["vision"] = Qwen3VLMoeForConditionalGeneration.from_pretrained(
+                settings.vision_model,
+                torch_dtype=torch.bfloat16,
+                device_map="auto",
+                trust_remote_code=True,
+            )
+            self.processors["vision"] = AutoProcessor.from_pretrained(
+                settings.vision_model,
+                trust_remote_code=True,
+            )
+        except Exception as e:
+            print(f"Failed to load 30B vision model: {e}")
+            print(f"Falling back to {settings.vision_model_fallback}...")
+            self.models["vision"] = Qwen3VLMoeForConditionalGeneration.from_pretrained(
+                settings.vision_model_fallback,
+                torch_dtype=torch.bfloat16,
+                device_map="auto",
+                trust_remote_code=True,
+            )
+            self.processors["vision"] = AutoProcessor.from_pretrained(
+                settings.vision_model_fallback,
+                trust_remote_code=True,
+            )
+
+        # Embedding model (~16GB in BF16)
+        print(f"Loading embedding model: {settings.embedding_model}...")
+        self.models["embedding"] = AutoModel.from_pretrained(
+            settings.embedding_model,
+            torch_dtype=torch.bfloat16,
+            device_map="auto",
+            trust_remote_code=True,
+        )
+        self.processors["embedding"] = AutoProcessor.from_pretrained(
+            settings.embedding_model,
+            trust_remote_code=True,
+        )
+
+        # Reranker model (~16GB in BF16)
+        print(f"Loading reranker model: {settings.reranker_model}...")
+        self.models["reranker"] = AutoModel.from_pretrained(
+            settings.reranker_model,
+            torch_dtype=torch.bfloat16,
+            device_map="auto",
+            trust_remote_code=True,
+        )
+        self.processors["reranker"] = AutoProcessor.from_pretrained(
+            settings.reranker_model,
+            trust_remote_code=True,
+        )
+
+        self.loaded = True
+        print("All models loaded successfully.")
+        return self
+
+    def is_loaded(self) -> bool:
+        """Check if models are loaded."""
+        return self.loaded
+
+
+class RealVisionModel:
+    """Wrapper for real vision model inference."""
+
+    # Analysis prompt template for FDAM fire damage assessment
+    ANALYSIS_PROMPT = """Analyze this fire damage image and return a JSON response with the following structure:
+
+{
+    "zone": {
+        "classification": "burn" | "near-field" | "far-field",
+        "confidence": 0.0-1.0,
+        "reasoning": "explanation"
+    },
+    "condition": {
+        "level": "background" | "light" | "moderate" | "heavy" | "structural-damage",
+        "confidence": 0.0-1.0,
+        "reasoning": "explanation"
+    },
+    "materials": [
+        {
+            "type": "material type (e.g., drywall, concrete, steel, wood)",
+            "category": "non-porous" | "semi-porous" | "porous" | "hvac",
+            "confidence": 0.0-1.0,
+            "location_description": "where in image",
+            "bounding_box": {"x": 0.0-1.0, "y": 0.0-1.0, "width": 0.0-1.0, "height": 0.0-1.0}
+        }
+    ],
+    "combustion_indicators": {
+        "soot_visible": true/false,
+        "soot_pattern": "description or null",
+        "char_visible": true/false,
+        "char_description": "description or null",
+        "ash_visible": true/false,
+        "ash_description": "description or null"
+    },
+    "structural_concerns": ["list of structural issues if any"],
+    "access_issues": ["list of access problems if any"],
+    "recommended_sampling_locations": [
+        {
+            "description": "where to sample",
+            "sample_type": "tape_lift" | "surface_wipe" | "air_sample",
+            "priority": "high" | "medium" | "low"
+        }
+    ],
+    "flags_for_review": ["any items requiring human review"]
+}
+
+Zone definitions:
+- burn: Direct fire involvement, visible charring, structural damage
+- near-field: Adjacent to burn zone, heavy smoke/heat exposure, discoloration
+- far-field: Smoke migration only, light deposits, no structural damage
+
+Condition definitions:
+- background: No visible contamination
+- light: Faint discoloration, minimal deposits
+- moderate: Visible film/deposits, surface color altered
+- heavy: Thick deposits, surface texture obscured
+- structural-damage: Physical damage requiring repair before cleaning
+
+IMPORTANT: Return ONLY valid JSON, no additional text."""
+
+    def __init__(self, model, processor):
+        self.model = model
+        self.processor = processor
+
+    def analyze_image(self, image: Image.Image, context: str = "") -> dict[str, Any]:
+        """Analyze an image and return structured results."""
+        try:
+            from qwen_vl_utils import process_vision_info
+        except ImportError:
+            logger.warning("qwen_vl_utils not available, using basic processing")
+            process_vision_info = None
+
+        # Build the analysis prompt
+        prompt = self.ANALYSIS_PROMPT
+        if context:
+            prompt = f"Context: {context}\n\n{prompt}"
+
+        # Prepare messages in Qwen-VL format
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": prompt},
+                ],
+            }
+        ]
+
+        try:
+            # Apply chat template
+            text = self.processor.apply_chat_template(
+                messages, tokenize=False, add_generation_prompt=True
+            )
+
+            # Process vision info if available
+            if process_vision_info:
+                image_inputs, video_inputs = process_vision_info(messages)
+                inputs = self.processor(
+                    text=[text],
+                    images=image_inputs,
+                    videos=video_inputs,
+                    return_tensors="pt",
+                    padding=True,
+                )
+            else:
+                # Fallback: basic image processing
+                inputs = self.processor(
+                    text=[text],
+                    images=[image],
+                    return_tensors="pt",
+                    padding=True,
+                )
+
+            # Move inputs to model device
+            inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
+
+            # Generate response
+            with torch.no_grad():
+                outputs = self.model.generate(
+                    **inputs,
+                    max_new_tokens=2048,
+                    do_sample=False,
+                    temperature=None,
+                    top_p=None,
+                )
+
+            # Decode response
+            response_text = self.processor.decode(
+                outputs[0], skip_special_tokens=True
+            )
+
+            # Parse JSON from response
+            return self._parse_vision_response(response_text)
+
+        except Exception as e:
+            logger.error(f"Vision analysis failed: {e}")
+            return self._get_fallback_response(str(e))
+
+    def _parse_vision_response(self, response: str) -> dict[str, Any]:
+        """Parse JSON response from vision model."""
+        try:
+            # Try to extract JSON from response
+            # Look for JSON block in various formats
+            json_match = re.search(r'\{[\s\S]*\}', response)
+            if json_match:
+                json_str = json_match.group()
+                return json.loads(json_str)
+            else:
+                logger.warning("No JSON found in vision response")
+                return self._get_fallback_response("No JSON in response")
+        except json.JSONDecodeError as e:
+            logger.warning(f"Failed to parse vision JSON: {e}")
+            return self._get_fallback_response(f"JSON parse error: {e}")
+
+    def _get_fallback_response(self, reason: str) -> dict[str, Any]:
+        """Return fallback response when analysis fails."""
+        return {
+            "zone": {
+                "classification": "far-field",
+                "confidence": 0.3,
+                "reasoning": f"Fallback due to: {reason}",
+            },
+            "condition": {
+                "level": "light",
+                "confidence": 0.3,
+                "reasoning": f"Fallback due to: {reason}",
+            },
+            "materials": [
+                {
+                    "type": "general-surface",
+                    "category": "semi-porous",
+                    "confidence": 0.3,
+                    "location_description": "Unable to determine",
+                    "bounding_box": {"x": 0.0, "y": 0.0, "width": 1.0, "height": 1.0},
+                }
+            ],
+            "combustion_indicators": {
+                "soot_visible": False,
+                "soot_pattern": None,
+                "char_visible": False,
+                "char_description": None,
+                "ash_visible": False,
+                "ash_description": None,
+            },
+            "structural_concerns": [],
+            "access_issues": [],
+            "recommended_sampling_locations": [],
+            "flags_for_review": [f"Analysis failed: {reason}"],
+            "_fallback_used": True,
+        }
+
+
+class RealEmbeddingModel:
+    """Wrapper for real embedding model inference."""
+
+    def __init__(self, model, processor):
+        self.model = model
+        self.processor = processor
+
+    def embed(self, text: str) -> list[float]:
+        """Generate embedding for text using mean pooling."""
+        try:
+            # Tokenize input
+            inputs = self.processor(
+                text,
+                return_tensors="pt",
+                padding=True,
+                truncation=True,
+                max_length=512,
+            )
+
+            # Move to model device
+            inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
+
+            # Generate embeddings
+            with torch.no_grad():
+                outputs = self.model(**inputs)
+
+                # Use mean pooling over sequence dimension
+                # outputs.last_hidden_state shape: (batch, seq_len, hidden_dim)
+                attention_mask = inputs.get("attention_mask")
+                if attention_mask is not None:
+                    # Mask-weighted mean pooling
+                    mask_expanded = attention_mask.unsqueeze(-1).expand(
+                        outputs.last_hidden_state.size()
+                    ).float()
+                    sum_embeddings = torch.sum(
+                        outputs.last_hidden_state * mask_expanded, dim=1
+                    )
+                    sum_mask = torch.clamp(mask_expanded.sum(dim=1), min=1e-9)
+                    embeddings = sum_embeddings / sum_mask
+                else:
+                    # Simple mean if no attention mask
+                    embeddings = outputs.last_hidden_state.mean(dim=1)
+
+                # Normalize
+                embeddings = torch.nn.functional.normalize(embeddings, p=2, dim=1)
+
+            return embeddings[0].cpu().tolist()
+
+        except Exception as e:
+            logger.error(f"Embedding generation failed: {e}")
+            # Return zero vector as fallback
+            hidden_size = getattr(self.model.config, "hidden_size", 4096)
+            return [0.0] * hidden_size
+
+    def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for a batch of texts."""
+        return [self.embed(text) for text in texts]
+
+
+class RealRerankerModel:
+    """Wrapper for real reranker model inference."""
+
+    def __init__(self, model, processor):
+        self.model = model
+        self.processor = processor
+
+    def rerank(self, query: str, documents: list[str]) -> list[float]:
+        """Rerank documents by relevance to query.
+
+        Returns a list of relevance scores for each document.
+        Higher scores indicate more relevant documents.
+        """
+        if not documents:
+            return []
+
+        scores = []
+        for doc in documents:
+            try:
+                score = self._score_pair(query, doc)
+                scores.append(score)
+            except Exception as e:
+                logger.warning(f"Reranking failed for document: {e}")
+                scores.append(0.0)
+
+        return scores
+
+    def _score_pair(self, query: str, document: str) -> float:
+        """Score a single query-document pair."""
+        # Format as query-document pair for cross-encoder
+        # Truncate document if too long
+        max_doc_len = 400
+        if len(document) > max_doc_len:
+            document = document[:max_doc_len] + "..."
+
+        pair_text = f"Query: {query}\n\nDocument: {document}"
+
+        try:
+            inputs = self.processor(
+                pair_text,
+                return_tensors="pt",
+                padding=True,
+                truncation=True,
+                max_length=512,
+            )
+
+            # Move to model device
+            inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
+
+            with torch.no_grad():
+                outputs = self.model(**inputs)
+
+                # Use CLS token representation for scoring
+                # Take mean of last hidden state as a simple relevance score
+                cls_embedding = outputs.last_hidden_state[:, 0, :]
+
+                # Normalize and take mean as score
+                score = cls_embedding.norm(dim=-1).mean().item()
+
+                # Normalize score to 0-1 range (approximate)
+                # This is heuristic; actual reranker models have specific score heads
+                score = min(1.0, max(0.0, score / 100.0))
+
+            return score
+
+        except Exception as e:
+            logger.error(f"Reranker scoring failed: {e}")
+            return 0.0
+
+    def rerank_with_indices(
+        self, query: str, documents: list[str], top_k: int = None
+    ) -> list[tuple[int, float]]:
+        """Rerank and return sorted (index, score) tuples.
+
+        Args:
+            query: The search query
+            documents: List of documents to rerank
+            top_k: Optional limit on number of results
+
+        Returns:
+            List of (original_index, score) tuples, sorted by score descending
+        """
+        scores = self.rerank(query, documents)
+
+        # Create (index, score) pairs and sort by score descending
+        indexed_scores = list(enumerate(scores))
+        indexed_scores.sort(key=lambda x: x[1], reverse=True)
+
+        if top_k is not None:
+            indexed_scores = indexed_scores[:top_k]
+
+        return indexed_scores

pipeline/__init__.py

@@ -0,0 +1,23 @@
+"""FDAM Pipeline - Fire Damage Assessment Processing.
+
+This module provides the core processing pipeline for generating
+fire damage assessment reports using AI vision analysis and
+RAG-enhanced methodology lookup.
+"""
+
+from .calculations import FDAMCalculator
+from .dispositions import DispositionEngine
+from .generator import DocumentGenerator
+from .main import FDAMPipeline, PipelineResult
+from .pdf_generator import PDFGenerator, PDFResult, generate_sow_pdf
+
+__all__ = [
+    "FDAMCalculator",
+    "DispositionEngine",
+    "DocumentGenerator",
+    "FDAMPipeline",
+    "PipelineResult",
+    "PDFGenerator",
+    "PDFResult",
+    "generate_sow_pdf",
+]

pipeline/calculations.py

@@ -0,0 +1,325 @@
+"""FDAM Calculations Module.
+
+Implements deterministic calculations from FDAM v4.0.1:
+- Air filtration requirements (ACH per NADCA ACR 2021)
+- Sample density guidelines
+- Regulatory flags
+- Metals thresholds lookup
+"""
+
+import math
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+from ui.state import SessionState
+
+
+@dataclass
+class AirFiltrationResult:
+    """Air filtration calculation results."""
+
+    total_volume_cf: float
+    required_ach: int
+    unit_cfm: int
+    units_required: int
+    calculation_notes: str
+
+
+@dataclass
+class SampleDensityResult:
+    """Sample density calculation results."""
+
+    total_area_sf: float
+    tape_lifts_min: int
+    tape_lifts_max: int
+    surface_wipes_min: int
+    surface_wipes_max: int
+    ceiling_deck_samples: int
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class RegulatoryFlags:
+    """Regulatory requirements based on building characteristics."""
+
+    lbp_survey_required: bool = False
+    acm_survey_required: bool = False
+    acm_survey_recommended: bool = False
+    enhanced_childcare_thresholds: bool = False
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class MetalsThresholds:
+    """Metals clearance thresholds for a facility type."""
+
+    lead_ug_100cm2: float
+    cadmium_ug_100cm2: float
+    arsenic_ug_100cm2: float
+    chromium_vi_ug_100cm2: float
+    beryllium_ug_100cm2: float
+    facility_type: str
+    source: str = "BNL SOP IH75190, Attachment 9.3"
+
+
+# Threshold lookup tables from BNL SOP IH75190
+METALS_THRESHOLDS = {
+    "non-operational": MetalsThresholds(
+        lead_ug_100cm2=22.0,
+        cadmium_ug_100cm2=3.3,
+        arsenic_ug_100cm2=6.7,
+        chromium_vi_ug_100cm2=3.3,
+        beryllium_ug_100cm2=0.2,
+        facility_type="Non-Operational",
+    ),
+    "operational": MetalsThresholds(
+        lead_ug_100cm2=500.0,
+        cadmium_ug_100cm2=50.0,
+        arsenic_ug_100cm2=100.0,
+        chromium_vi_ug_100cm2=50.0,
+        beryllium_ug_100cm2=3.0,
+        facility_type="Operational",
+    ),
+    "public-childcare": MetalsThresholds(
+        lead_ug_100cm2=4.3,  # EPA/HUD October 2024 for floors
+        cadmium_ug_100cm2=3.3,  # Use non-operational as baseline
+        arsenic_ug_100cm2=6.7,
+        chromium_vi_ug_100cm2=3.3,
+        beryllium_ug_100cm2=0.2,
+        facility_type="Public/Childcare",
+        source="EPA/HUD October 2024 + BNL SOP IH75190",
+    ),
+}
+
+# Particulate thresholds from EAA Method Guide
+PARTICULATE_THRESHOLDS = {
+    "ash_char": {
+        "clearance": 150,  # cts/cm²
+        "unit": "cts/cm²",
+        "source": "EAA Method Guide / FDAM §1.5",
+    },
+    "aciniform_soot": {
+        "clearance": 500,  # cts/cm²
+        "unit": "cts/cm²",
+        "source": "EAA Method Guide / FDAM §1.5",
+    },
+}
+
+
+class FDAMCalculator:
+    """Calculator for FDAM deterministic formulas."""
+
+    # Default air scrubber specifications
+    DEFAULT_UNIT_CFM = 2000
+    DEFAULT_ACH = 4  # Per NADCA ACR 2021
+
+    def calculate_air_filtration(
+        self,
+        total_area_sf: float,
+        avg_ceiling_height_ft: float,
+        unit_cfm: int = DEFAULT_UNIT_CFM,
+        required_ach: int = DEFAULT_ACH,
+    ) -> AirFiltrationResult:
+        """Calculate air filtration requirements per NADCA ACR 2021.
+
+        Formula: Units = (Volume CF × ACH) / (Unit CFM × 60)
+
+        Args:
+            total_area_sf: Total floor area in square feet
+            avg_ceiling_height_ft: Average ceiling height in feet
+            unit_cfm: CFM rating of air scrubber units (default 2000)
+            required_ach: Required air changes per hour (default 4)
+
+        Returns:
+            AirFiltrationResult with calculation details
+        """
+        total_volume_cf = total_area_sf * avg_ceiling_height_ft
+
+        # Formula from FDAM §5.3
+        units_required = math.ceil(
+            (total_volume_cf * required_ach) / (unit_cfm * 60)
+        )
+
+        # Minimum 1 unit
+        units_required = max(1, units_required)
+
+        calculation_notes = (
+            f"({total_volume_cf:,.0f} CF × {required_ach} ACH) / "
+            f"({unit_cfm} CFM × 60) = {units_required} units"
+        )
+
+        return AirFiltrationResult(
+            total_volume_cf=total_volume_cf,
+            required_ach=required_ach,
+            unit_cfm=unit_cfm,
+            units_required=units_required,
+            calculation_notes=calculation_notes,
+        )
+
+    def calculate_sample_density(
+        self,
+        total_area_sf: float,
+        has_ceiling_deck: bool = True,
+        surface_types_count: int = 3,
+    ) -> SampleDensityResult:
+        """Calculate sample density per FDAM §2.3.
+
+        Args:
+            total_area_sf: Total floor area in square feet
+            has_ceiling_deck: Whether ceiling deck surfaces are present
+            surface_types_count: Number of distinct surface types
+
+        Returns:
+            SampleDensityResult with recommended sample counts
+        """
+        notes = []
+
+        # Base sample density by area size
+        if total_area_sf < 5000:
+            tape_min, tape_max = 3, 5
+            wipe_min, wipe_max = 3, 5
+            notes.append("Small area (<5,000 SF): standard sampling density")
+        elif total_area_sf <= 25000:
+            tape_min, tape_max = 5, 10
+            wipe_min, wipe_max = 5, 10
+            notes.append("Medium area (5,000-25,000 SF): moderate sampling density")
+        else:
+            # Scale for larger areas
+            tape_min, tape_max = 10, 15
+            wipe_min, wipe_max = 10, 15
+            notes.append("Large area (>25,000 SF): enhanced sampling density")
+
+        # Multiply by surface types
+        tape_min *= surface_types_count
+        tape_max *= surface_types_count
+        wipe_min *= surface_types_count
+        wipe_max *= surface_types_count
+
+        # Ceiling deck enhanced sampling (1 per 2,500 SF per FDAM §4.5)
+        ceiling_deck_samples = 0
+        if has_ceiling_deck:
+            ceiling_deck_samples = max(1, math.ceil(total_area_sf / 2500))
+            notes.append(
+                f"Ceiling deck: {ceiling_deck_samples} samples "
+                f"(1 per 2,500 SF per FDAM §4.5)"
+            )
+
+        return SampleDensityResult(
+            total_area_sf=total_area_sf,
+            tape_lifts_min=tape_min,
+            tape_lifts_max=tape_max,
+            surface_wipes_min=wipe_min,
+            surface_wipes_max=wipe_max,
+            ceiling_deck_samples=ceiling_deck_samples,
+            notes=notes,
+        )
+
+    def get_regulatory_flags(
+        self,
+        construction_era: Literal["pre-1980", "1980-2000", "post-2000"],
+        facility_classification: Literal["operational", "non-operational", "public-childcare"],
+    ) -> RegulatoryFlags:
+        """Determine regulatory requirements based on building characteristics.
+
+        Args:
+            construction_era: Building construction era
+            facility_classification: Facility type
+
+        Returns:
+            RegulatoryFlags with applicable requirements
+        """
+        flags = RegulatoryFlags()
+
+        # Lead-based paint (pre-1978)
+        if construction_era == "pre-1980":
+            flags.lbp_survey_required = True
+            flags.notes.append("LBP survey required (pre-1978 construction)")
+
+        # Asbestos (pre-1980 required, 1980-2000 recommended)
+        if construction_era == "pre-1980":
+            flags.acm_survey_required = True
+            flags.notes.append("ACM survey required (pre-1980 construction)")
+        elif construction_era == "1980-2000":
+            flags.acm_survey_recommended = True
+            flags.notes.append("ACM survey recommended (1980-2000 construction)")
+
+        # Enhanced thresholds for public/childcare
+        if facility_classification == "public-childcare":
+            flags.enhanced_childcare_thresholds = True
+            flags.notes.append(
+                "Enhanced lead thresholds apply (EPA/HUD October 2024): "
+                "4.3 µg/100cm² for floors"
+            )
+
+        return flags
+
+    def get_metals_thresholds(
+        self,
+        facility_classification: Literal["operational", "non-operational", "public-childcare"],
+    ) -> MetalsThresholds:
+        """Get metals clearance thresholds for facility type.
+
+        Args:
+            facility_classification: Facility type
+
+        Returns:
+            MetalsThresholds with applicable limits
+        """
+        return METALS_THRESHOLDS.get(
+            facility_classification,
+            METALS_THRESHOLDS["non-operational"],
+        )
+
+    def calculate_from_session(self, session: SessionState) -> dict:
+        """Run all calculations from a session state.
+
+        Args:
+            session: Current session state with rooms and project info
+
+        Returns:
+            Dictionary with all calculation results
+        """
+        # Calculate totals from rooms
+        total_area = sum(r.length_ft * r.width_ft for r in session.rooms)
+        total_volume = sum(
+            r.length_ft * r.width_ft * r.ceiling_height_ft
+            for r in session.rooms
+        )
+        avg_ceiling = (
+            total_volume / total_area if total_area > 0 else 10.0
+        )
+
+        # Air filtration
+        air_filtration = self.calculate_air_filtration(
+            total_area_sf=total_area,
+            avg_ceiling_height_ft=avg_ceiling,
+        )
+
+        # Sample density
+        sample_density = self.calculate_sample_density(
+            total_area_sf=total_area,
+            has_ceiling_deck=True,  # Assume present
+            surface_types_count=3,  # Default assumption
+        )
+
+        # Regulatory flags
+        regulatory = self.get_regulatory_flags(
+            construction_era=session.project.construction_era or "post-2000",
+            facility_classification=session.project.facility_classification or "non-operational",
+        )
+
+        # Metals thresholds
+        thresholds = self.get_metals_thresholds(
+            facility_classification=session.project.facility_classification or "non-operational",
+        )
+
+        return {
+            "total_area_sf": total_area,
+            "total_volume_cf": total_volume,
+            "avg_ceiling_height_ft": avg_ceiling,
+            "air_filtration": air_filtration,
+            "sample_density": sample_density,
+            "regulatory_flags": regulatory,
+            "metals_thresholds": thresholds,
+            "particulate_thresholds": PARTICULATE_THRESHOLDS,
+        }

pipeline/dispositions.py

@@ -0,0 +1,364 @@
+"""FDAM Dispositions Module.
+
+Determines cleaning dispositions based on zone classification,
+condition level, and RAG-retrieved methodology context.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+from rag import FDAMRetriever, ChromaVectorStore
+
+logger = logging.getLogger(__name__)
+
+
+# Disposition matrix from FDAM §4.3
+DISPOSITION_MATRIX = {
+    # (zone, condition) -> (disposition, protocol)
+    ("any", "background"): ("no-action", "Document only"),
+    ("far-field", "light"): ("clean", "Standard protocol"),
+    ("far-field", "moderate"): ("clean", "Full protocol"),
+    ("far-field", "heavy"): ("clean", "Aggressive protocol"),
+    ("near-field", "light"): ("clean", "Full protocol"),
+    ("near-field", "moderate"): ("clean", "Aggressive protocol, multiple passes"),
+    ("near-field", "heavy"): ("clean", "Aggressive protocol with verification sampling"),
+    ("burn-zone", "light"): ("clean", "Post-structural repair; full protocol"),
+    ("burn-zone", "moderate"): ("clean", "Post-structural repair; aggressive protocol"),
+    ("burn-zone", "heavy"): ("clean", "Post-structural repair; aggressive protocol"),
+    ("any", "structural-damage"): ("remove-repair", "Beyond cleaning scope"),
+}
+
+# Protocol details
+CLEANING_PROTOCOLS = {
+    "standard": {
+        "name": "Standard Protocol",
+        "steps": [
+            "HEPA vacuum all surfaces",
+            "Wet wipe with appropriate cleaner",
+            "Allow to dry",
+            "Visual inspection",
+        ],
+        "passes": 1,
+    },
+    "full": {
+        "name": "Full Protocol",
+        "steps": [
+            "HEPA vacuum all surfaces (2 passes)",
+            "Wet wipe with degreaser/cleaner",
+            "Rinse wipe",
+            "Allow to dry",
+            "Visual inspection",
+            "Verification sampling if required",
+        ],
+        "passes": 2,
+    },
+    "aggressive": {
+        "name": "Aggressive Protocol",
+        "steps": [
+            "HEPA vacuum all surfaces (minimum 3 passes)",
+            "Apply cleaning solution, allow dwell time",
+            "Agitate with appropriate brush/pad",
+            "Wet wipe extraction",
+            "Rinse wipe",
+            "Repeat cleaning cycle if needed",
+            "Verification sampling required",
+        ],
+        "passes": 3,
+    },
+}
+
+
+@dataclass
+class DispositionResult:
+    """Result of disposition determination."""
+
+    zone: str
+    condition: str
+    disposition: Literal["no-action", "clean", "evaluate", "remove", "remove-repair"]
+    protocol: str
+    protocol_details: Optional[dict] = None
+    confidence: float = 1.0
+    rag_context: Optional[str] = None
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SurfaceDisposition:
+    """Disposition for a specific surface."""
+
+    surface_type: str
+    room_name: str
+    zone: str
+    condition: str
+    disposition: str
+    cleaning_method: str
+    notes: list[str] = field(default_factory=list)
+
+
+class DispositionEngine:
+    """Determines cleaning dispositions using FDAM methodology and RAG."""
+
+    def __init__(self, retriever: Optional[FDAMRetriever] = None):
+        """Initialize disposition engine.
+
+        Args:
+            retriever: Optional RAG retriever. If None, uses default.
+        """
+        self._retriever = retriever
+
+    @property
+    def retriever(self) -> FDAMRetriever:
+        """Get or create RAG retriever."""
+        if self._retriever is None:
+            try:
+                vs = ChromaVectorStore(persist_directory="chroma_db")
+                self._retriever = FDAMRetriever(vectorstore=vs)
+            except Exception as e:
+                # Fall back to in-memory if no persistent store
+                logger.warning(f"ChromaDB init failed, using fallback retriever: {e}")
+                self._retriever = FDAMRetriever()
+        return self._retriever
+
+    def determine_disposition(
+        self,
+        zone: Literal["burn-zone", "near-field", "far-field"],
+        condition: Literal["background", "light", "moderate", "heavy", "structural-damage"],
+        surface_type: Optional[str] = None,
+        use_rag: bool = True,
+    ) -> DispositionResult:
+        """Determine disposition for a zone/condition combination.
+
+        Args:
+            zone: Zone classification
+            condition: Condition level
+            surface_type: Optional surface type for specific guidance
+            use_rag: Whether to retrieve additional context from RAG
+
+        Returns:
+            DispositionResult with disposition and protocol
+        """
+        notes = []
+
+        # Handle background condition (any zone)
+        if condition == "background":
+            return DispositionResult(
+                zone=zone,
+                condition=condition,
+                disposition="no-action",
+                protocol="Document only",
+                confidence=1.0,
+                notes=["No visible contamination - document and proceed"],
+            )
+
+        # Handle structural damage (any zone)
+        if condition == "structural-damage":
+            return DispositionResult(
+                zone=zone,
+                condition=condition,
+                disposition="remove-repair",
+                protocol="Beyond cleaning scope",
+                confidence=1.0,
+                notes=["Structural damage requires repair before cleaning assessment"],
+            )
+
+        # Look up in disposition matrix
+        key = (zone, condition)
+        if key in DISPOSITION_MATRIX:
+            disposition, protocol = DISPOSITION_MATRIX[key]
+        else:
+            # Fallback for unexpected combinations
+            disposition = "evaluate"
+            protocol = "Professional judgment required"
+            notes.append("Combination not in standard matrix - requires evaluation")
+
+        # Determine protocol details
+        protocol_details = None
+        if "standard" in protocol.lower():
+            protocol_details = CLEANING_PROTOCOLS["standard"]
+        elif "aggressive" in protocol.lower():
+            protocol_details = CLEANING_PROTOCOLS["aggressive"]
+        elif "full" in protocol.lower():
+            protocol_details = CLEANING_PROTOCOLS["full"]
+
+        # Get RAG context if enabled
+        rag_context = None
+        if use_rag:
+            try:
+                results = self.retriever.retrieve_disposition(
+                    zone=zone,
+                    condition=condition,
+                    material_type=surface_type,
+                )
+                if results:
+                    rag_context = results[0].text[:500]  # First result, truncated
+                    notes.append(f"RAG context from: {results[0].source}")
+            except Exception as e:
+                notes.append(f"RAG lookup unavailable: {e}")
+
+        return DispositionResult(
+            zone=zone,
+            condition=condition,
+            disposition=disposition,
+            protocol=protocol,
+            protocol_details=protocol_details,
+            confidence=0.9 if disposition != "evaluate" else 0.6,
+            rag_context=rag_context,
+            notes=notes,
+        )
+
+    def get_cleaning_method(
+        self,
+        surface_type: str,
+        condition: Literal["light", "moderate", "heavy"],
+        use_rag: bool = True,
+    ) -> dict:
+        """Get recommended cleaning method for a surface type.
+
+        Args:
+            surface_type: Type of surface (e.g., "drywall", "concrete")
+            condition: Contamination level
+            use_rag: Whether to retrieve from RAG
+
+        Returns:
+            Dictionary with cleaning method details
+        """
+        # Default cleaning methods by surface type (from FDAM §5.2)
+        default_methods = {
+            "drywall": "HEPA vacuum → Dry sponge OR wet wipe",
+            "painted-drywall": "HEPA vacuum → Wet wipe with degreaser",
+            "concrete": "Scrubber machine + alkaline cleaner",
+            "concrete-floor": "Scrubber machine + alkaline cleaner",
+            "cmu": "HEPA vacuum → Wet wipe OR power wash",
+            "cmu-walls": "HEPA vacuum → Wet wipe OR power wash",
+            "metal": "Wet wipe → Rinse",
+            "metal-doors": "Wet wipe → Rinse",
+            "wood": "HEPA vacuum → Appropriate wood cleaner",
+            "glass": "Glass cleaner with lint-free cloth",
+            "carpet": "HEPA vacuum → Hot water extraction",
+            "hvac-ductwork": "Per NADCA ACR standards",
+            "ceiling-deck": "HEPA vacuum → Wet wipe (enhanced sampling required)",
+        }
+
+        # Normalize surface type
+        surface_lower = surface_type.lower().replace(" ", "-")
+
+        # Find best match
+        method = None
+        for key, value in default_methods.items():
+            if key in surface_lower or surface_lower in key:
+                method = value
+                break
+
+        if method is None:
+            method = "HEPA vacuum → Wet wipe (consult IH professional)"
+
+        # Enhance method based on condition
+        if condition == "heavy":
+            method = f"{method} (multiple passes, verification sampling)"
+        elif condition == "moderate":
+            method = f"{method} (consider additional pass)"
+
+        result = {
+            "surface_type": surface_type,
+            "condition": condition,
+            "method": method,
+            "source": "FDAM §5.2",
+        }
+
+        # Get RAG context for additional detail
+        if use_rag:
+            try:
+                rag_results = self.retriever.retrieve_cleaning_method(
+                    surface_type=surface_type,
+                    condition=condition,
+                )
+                if rag_results:
+                    result["rag_context"] = rag_results[0].text[:300]
+                    result["rag_source"] = rag_results[0].source
+            except Exception as e:
+                logger.warning(f"RAG retrieval failed for cleaning method: {e}")
+
+        return result
+
+    def process_vision_results(
+        self,
+        vision_results: dict,
+        room_mapping: dict,
+    ) -> list[SurfaceDisposition]:
+        """Process vision analysis results into surface dispositions.
+
+        Args:
+            vision_results: Dictionary of image_id -> vision result
+            room_mapping: Dictionary of image_id -> room info
+
+        Returns:
+            List of SurfaceDisposition for each analyzed surface
+        """
+        dispositions = []
+
+        for image_id, result in vision_results.items():
+            room_info = room_mapping.get(image_id, {})
+            room_name = room_info.get("name", "Unknown Room")
+
+            # Extract zone and condition with fallback tracking
+            zone_data = result.get("zone", {})
+            zone = zone_data.get("classification") if zone_data else None
+            condition_data = result.get("condition", {})
+            condition = condition_data.get("level") if condition_data else None
+
+            # Track if fallbacks were used (affects confidence scoring)
+            fallback_used = False
+            if zone is None:
+                zone = "far-field"
+                fallback_used = True
+                logger.warning(f"Image {image_id}: Using fallback zone 'far-field'")
+            if condition is None:
+                condition = "light"
+                fallback_used = True
+                logger.warning(f"Image {image_id}: Using fallback condition 'light'")
+
+            # Flag for confidence scoring
+            if fallback_used:
+                result["_fallback_used"] = True
+
+            # Get materials detected
+            materials = result.get("materials", [])
+            if not materials:
+                materials = [{"type": "general-surface", "confidence": 0.8}]
+                result["_fallback_used"] = True
+
+            for material in materials:
+                material_type = material.get("type", "unknown")
+
+                # Get disposition
+                disp_result = self.determine_disposition(
+                    zone=zone,
+                    condition=condition,
+                    surface_type=material_type,
+                    use_rag=True,
+                )
+
+                # Get cleaning method
+                if condition != "background" and disp_result.disposition == "clean":
+                    method_info = self.get_cleaning_method(
+                        surface_type=material_type,
+                        condition=condition,
+                    )
+                    cleaning_method = method_info["method"]
+                else:
+                    cleaning_method = disp_result.protocol
+
+                dispositions.append(
+                    SurfaceDisposition(
+                        surface_type=material_type,
+                        room_name=room_name,
+                        zone=zone,
+                        condition=condition,
+                        disposition=disp_result.disposition,
+                        cleaning_method=cleaning_method,
+                        notes=disp_result.notes,
+                    )
+                )
+
+        return dispositions

pipeline/generator.py

@@ -0,0 +1,466 @@
+"""FDAM Document Generator.
+
+Generates Cleaning Specification / Scope of Work documents
+with RAG-enhanced content from the FDAM knowledge base.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+from ui.state import SessionState
+from rag import FDAMRetriever, ChromaVectorStore
+from .calculations import FDAMCalculator, AirFiltrationResult, SampleDensityResult, RegulatoryFlags
+from .dispositions import DispositionEngine, SurfaceDisposition
+
+
+@dataclass
+class GeneratedDocument:
+    """A generated assessment document."""
+
+    markdown: str
+    title: str
+    generated_at: str
+    word_count: int
+    sections: list[str]
+
+
+class DocumentGenerator:
+    """Generates FDAM assessment documents with RAG enhancement."""
+
+    def __init__(
+        self,
+        calculator: Optional[FDAMCalculator] = None,
+        disposition_engine: Optional[DispositionEngine] = None,
+        retriever: Optional[FDAMRetriever] = None,
+    ):
+        """Initialize document generator.
+
+        Args:
+            calculator: FDAM calculator instance
+            disposition_engine: Disposition engine instance
+            retriever: RAG retriever instance
+        """
+        self.calculator = calculator or FDAMCalculator()
+        self.disposition_engine = disposition_engine or DispositionEngine()
+        self._retriever = retriever
+
+    @property
+    def retriever(self) -> FDAMRetriever:
+        """Get or create RAG retriever."""
+        if self._retriever is None:
+            try:
+                vs = ChromaVectorStore(persist_directory="chroma_db")
+                self._retriever = FDAMRetriever(vectorstore=vs)
+            except Exception:
+                self._retriever = FDAMRetriever()
+        return self._retriever
+
+    def generate_sow(
+        self,
+        session: SessionState,
+        vision_results: dict,
+        surface_dispositions: list[SurfaceDisposition],
+        calculations: dict,
+    ) -> GeneratedDocument:
+        """Generate Scope of Work document.
+
+        Args:
+            session: Current session state
+            vision_results: Vision analysis results by image ID
+            surface_dispositions: List of surface dispositions
+            calculations: Calculation results from FDAMCalculator
+
+        Returns:
+            GeneratedDocument with markdown content
+        """
+        sections = []
+
+        # Header
+        header = self._generate_header(session)
+        sections.append(header)
+
+        # Project Information
+        project_info = self._generate_project_info(session)
+        sections.append(project_info)
+
+        # Scope Summary
+        scope_summary = self._generate_scope_summary(session, calculations)
+        sections.append(scope_summary)
+
+        # Room Inventory
+        room_inventory = self._generate_room_inventory(session)
+        sections.append(room_inventory)
+
+        # Vision Analysis Summary
+        vision_summary = self._generate_vision_summary(session, vision_results)
+        sections.append(vision_summary)
+
+        # Field Observations
+        observations = self._generate_observations(session)
+        sections.append(observations)
+
+        # Disposition Summary
+        disposition_summary = self._generate_disposition_summary(surface_dispositions)
+        sections.append(disposition_summary)
+
+        # Cleaning Specifications
+        cleaning_specs = self._generate_cleaning_specs(surface_dispositions, calculations)
+        sections.append(cleaning_specs)
+
+        # Air Filtration Requirements
+        air_filtration = self._generate_air_filtration(calculations)
+        sections.append(air_filtration)
+
+        # Sampling Plan
+        sampling_plan = self._generate_sampling_plan(calculations, session)
+        sections.append(sampling_plan)
+
+        # Regulatory Requirements
+        regulatory = self._generate_regulatory_section(calculations)
+        sections.append(regulatory)
+
+        # Clearance Thresholds
+        thresholds = self._generate_thresholds_section(calculations)
+        sections.append(thresholds)
+
+        # Disclaimer and Footer
+        footer = self._generate_footer()
+        sections.append(footer)
+
+        # Combine all sections
+        markdown = "\n\n---\n\n".join(sections)
+
+        return GeneratedDocument(
+            markdown=markdown,
+            title=f"SOW - {session.project.project_name}",
+            generated_at=datetime.now().isoformat(),
+            word_count=len(markdown.split()),
+            sections=[
+                "Header", "Project Info", "Scope Summary", "Room Inventory",
+                "Vision Analysis", "Observations", "Dispositions",
+                "Cleaning Specs", "Air Filtration", "Sampling Plan",
+                "Regulatory", "Thresholds", "Footer"
+            ],
+        )
+
+    def _generate_header(self, session: SessionState) -> str:
+        """Generate document header."""
+        return f"""# Cleaning Specification / Scope of Work
+
+**Project:** {session.project.project_name}
+**Prepared For:** {session.project.client_name}
+**Date:** {datetime.now().strftime('%B %d, %Y')}
+**Document Version:** FDAM v4.0.1"""
+
+    def _generate_project_info(self, session: SessionState) -> str:
+        """Generate project information section."""
+        p = session.project
+        return f"""## Project Information
+
+| Field | Value |
+|-------|-------|
+| **Project Name** | {p.project_name} |
+| **Address** | {p.address}, {p.city}, {p.state} {p.zip_code} |
+| **Client** | {p.client_name} |
+| **Fire Date** | {p.fire_date} |
+| **Assessment Date** | {p.assessment_date} |
+| **Facility Classification** | {p.facility_classification or 'Not specified'} |
+| **Construction Era** | {p.construction_era or 'Not specified'} |
+| **Assessor** | {p.assessor_name} {p.assessor_credentials or ''} |"""
+
+    def _generate_scope_summary(self, session: SessionState, calculations: dict) -> str:
+        """Generate scope summary section."""
+        air = calculations.get("air_filtration")
+        sample = calculations.get("sample_density")
+
+        return f"""## Scope Summary
+
+| Metric | Value |
+|--------|-------|
+| **Total Rooms/Areas** | {len(session.rooms)} |
+| **Total Floor Area** | {calculations['total_area_sf']:,.0f} SF |
+| **Total Volume** | {calculations['total_volume_cf']:,.0f} CF |
+| **Images Analyzed** | {len(session.images)} |
+| **Air Scrubbers Required** | {air.units_required if air else 'N/A'} units |
+| **Est. Tape Lifts** | {sample.tape_lifts_min}-{sample.tape_lifts_max if sample else 'N/A'} |
+| **Est. Surface Wipes** | {sample.surface_wipes_min}-{sample.surface_wipes_max if sample else 'N/A'} |"""
+
+    def _generate_room_inventory(self, session: SessionState) -> str:
+        """Generate room inventory table."""
+        lines = ["## Room Inventory", ""]
+        lines.append("| Room/Area | Dimensions | Area (SF) | Volume (CF) |")
+        lines.append("|-----------|------------|-----------|-------------|")
+
+        for room in session.rooms:
+            area = room.length_ft * room.width_ft
+            volume = area * room.ceiling_height_ft
+            lines.append(
+                f"| {room.name} | {room.length_ft:.0f}' × {room.width_ft:.0f}' × "
+                f"{room.ceiling_height_ft:.0f}' | {area:,.0f} | {volume:,.0f} |"
+            )
+
+        return "\n".join(lines)
+
+    def _generate_vision_summary(self, session: SessionState, vision_results: dict) -> str:
+        """Generate AI vision analysis summary."""
+        lines = ["## AI Vision Analysis Summary", ""]
+
+        if not vision_results:
+            lines.append("*No images analyzed.*")
+            return "\n".join(lines)
+
+        lines.append("| Image | Zone | Condition | Confidence |")
+        lines.append("|-------|------|-----------|------------|")
+
+        for img_meta in session.images:
+            result = vision_results.get(img_meta.id, {})
+            zone = result.get("zone", {})
+            condition = result.get("condition", {})
+
+            zone_class = zone.get("classification", "N/A")
+            zone_conf = zone.get("confidence", 0)
+            cond_level = condition.get("level", "N/A")
+            cond_conf = condition.get("confidence", 0)
+
+            lines.append(
+                f"| {img_meta.filename} | {zone_class} ({zone_conf:.0%}) | "
+                f"{cond_level} ({cond_conf:.0%}) | {(zone_conf + cond_conf) / 2:.0%} |"
+            )
+
+        return "\n".join(lines)
+
+    def _generate_observations(self, session: SessionState) -> str:
+        """Generate field observations section."""
+        obs = session.observations
+        lines = ["## Field Observations", ""]
+
+        items = []
+        if obs.smoke_fire_odor:
+            items.append(f"- **Smoke/Fire Odor:** {obs.odor_intensity or 'Present'}")
+        if obs.visible_soot_deposits:
+            items.append(f"- **Visible Soot:** {obs.soot_pattern_description or 'Present'}")
+        if obs.large_char_particles:
+            items.append(f"- **Char Particles:** {obs.char_density_estimate or 'Present'}")
+        if obs.ash_like_residue:
+            items.append(f"- **Ash Residue:** {obs.ash_color_texture or 'Present'}")
+        if obs.surface_discoloration:
+            items.append(f"- **Discoloration:** {obs.discoloration_description or 'Present'}")
+        if obs.wildfire_indicators:
+            items.append(f"- **Wildfire Indicators:** {obs.wildfire_notes or 'Present'}")
+        if obs.dust_loading_interference:
+            items.append(f"- **Dust/Debris:** {obs.dust_notes or 'Present'}")
+        if obs.additional_notes:
+            items.append(f"- **Additional Notes:** {obs.additional_notes}")
+
+        if items:
+            lines.extend(items)
+        else:
+            lines.append("*No significant observations noted.*")
+
+        return "\n".join(lines)
+
+    def _generate_disposition_summary(self, dispositions: list[SurfaceDisposition]) -> str:
+        """Generate disposition summary table."""
+        lines = ["## Disposition Summary", ""]
+
+        if not dispositions:
+            lines.append("*No dispositions determined.*")
+            return "\n".join(lines)
+
+        lines.append("| Room | Surface | Zone | Condition | Disposition |")
+        lines.append("|------|---------|------|-----------|-------------|")
+
+        for disp in dispositions:
+            lines.append(
+                f"| {disp.room_name} | {disp.surface_type} | {disp.zone} | "
+                f"{disp.condition} | {disp.disposition.upper()} |"
+            )
+
+        return "\n".join(lines)
+
+    def _generate_cleaning_specs(
+        self,
+        dispositions: list[SurfaceDisposition],
+        calculations: dict,
+    ) -> str:
+        """Generate cleaning specifications section."""
+        lines = ["## Cleaning Specifications", ""]
+
+        # Group by disposition
+        by_disposition = {}
+        for disp in dispositions:
+            key = disp.disposition
+            if key not in by_disposition:
+                by_disposition[key] = []
+            by_disposition[key].append(disp)
+
+        for disposition, items in by_disposition.items():
+            lines.append(f"### {disposition.upper().replace('-', ' ')} Surfaces")
+            lines.append("")
+
+            for item in items:
+                lines.append(f"**{item.room_name} - {item.surface_type}:**")
+                lines.append(f"- Method: {item.cleaning_method}")
+                if item.notes:
+                    lines.append(f"- Notes: {'; '.join(item.notes)}")
+                lines.append("")
+
+        return "\n".join(lines)
+
+    def _generate_air_filtration(self, calculations: dict) -> str:
+        """Generate air filtration requirements section."""
+        air: AirFiltrationResult = calculations.get("air_filtration")
+
+        if not air:
+            return "## Air Filtration Requirements\n\n*Calculation unavailable.*"
+
+        return f"""## Air Filtration Requirements
+
+Per NADCA ACR 2021, Section 3.6:
+
+| Parameter | Value |
+|-----------|-------|
+| **Required ACH** | {air.required_ach} air changes per hour |
+| **Total Volume** | {air.total_volume_cf:,.0f} CF |
+| **Unit Capacity** | {air.unit_cfm:,} CFM |
+| **Units Required** | {air.units_required} |
+
+**Calculation:** {air.calculation_notes}
+
+**Placement Notes:**
+- Distribute units evenly throughout work area
+- Ensure adequate negative air pressure
+- Exhaust to exterior when possible"""
+
+    def _generate_sampling_plan(self, calculations: dict, session: SessionState) -> str:
+        """Generate sampling plan section."""
+        sample: SampleDensityResult = calculations.get("sample_density")
+
+        if not sample:
+            return "## Sampling Plan\n\n*Calculation unavailable.*"
+
+        lines = ["## Sampling Plan", ""]
+        lines.append("### Pre-Cleaning Characterization")
+        lines.append("")
+        lines.append("| Sample Type | Quantity | Notes |")
+        lines.append("|-------------|----------|-------|")
+        lines.append(
+            f"| Tape Lifts | {sample.tape_lifts_min}-{sample.tape_lifts_max} | "
+            "Per surface type, per room"
+        )
+        lines.append(
+            f"| Surface Wipes | {sample.surface_wipes_min}-{sample.surface_wipes_max} | "
+            "Metals analysis"
+        )
+        if sample.ceiling_deck_samples > 0:
+            lines.append(
+                f"| Ceiling Deck | {sample.ceiling_deck_samples} | "
+                "Enhanced per FDAM §4.5"
+            )
+        lines.append("")
+
+        if sample.notes:
+            lines.append("**Notes:**")
+            for note in sample.notes:
+                lines.append(f"- {note}")
+            lines.append("")
+
+        lines.append("### Post-Cleaning Verification (PRV)")
+        lines.append("")
+        lines.append("PRV sampling locations should mirror pre-cleaning characterization.")
+        lines.append("Minimum 50% of original sample locations for initial clearance attempt.")
+
+        return "\n".join(lines)
+
+    def _generate_regulatory_section(self, calculations: dict) -> str:
+        """Generate regulatory requirements section."""
+        flags: RegulatoryFlags = calculations.get("regulatory_flags")
+
+        lines = ["## Regulatory Requirements", ""]
+
+        if not flags or not flags.notes:
+            lines.append("*No specific regulatory flags identified.*")
+            return "\n".join(lines)
+
+        for note in flags.notes:
+            lines.append(f"- {note}")
+
+        if flags.lbp_survey_required:
+            lines.append("")
+            lines.append(
+                "**Lead-Based Paint:** Per 29 CFR 1926.62, LBP survey must be completed "
+                "prior to disturbance of painted surfaces in pre-1978 construction."
+            )
+
+        if flags.acm_survey_required or flags.acm_survey_recommended:
+            lines.append("")
+            action = "required" if flags.acm_survey_required else "recommended"
+            lines.append(
+                f"**Asbestos:** ACM survey {action} per NESHAP regulations. "
+                "No disturbance of suspect materials until survey complete."
+            )
+
+        return "\n".join(lines)
+
+    def _generate_thresholds_section(self, calculations: dict) -> str:
+        """Generate clearance thresholds section."""
+        thresholds = calculations.get("metals_thresholds")
+        particulates = calculations.get("particulate_thresholds", {})
+
+        lines = ["## Clearance Thresholds", ""]
+        lines.append(f"**Facility Type:** {thresholds.facility_type if thresholds else 'N/A'}")
+        lines.append("")
+
+        if thresholds:
+            lines.append("### Metals (Surface Wipe)")
+            lines.append("")
+            lines.append("| Metal | Threshold | Unit |")
+            lines.append("|-------|-----------|------|")
+            lines.append(f"| Lead (Pb) | {thresholds.lead_ug_100cm2} | µg/100cm² |")
+            lines.append(f"| Cadmium (Cd) | {thresholds.cadmium_ug_100cm2} | µg/100cm² |")
+            lines.append(f"| Arsenic (As) | {thresholds.arsenic_ug_100cm2} | µg/100cm² |")
+            lines.append(f"| Chromium VI | {thresholds.chromium_vi_ug_100cm2} | µg/100cm² |")
+            lines.append(f"| Beryllium (Be) | {thresholds.beryllium_ug_100cm2} | µg/100cm² |")
+            lines.append("")
+            lines.append(f"*Source: {thresholds.source}*")
+            lines.append("")
+
+        if particulates:
+            lines.append("### Particulates (Tape Lift)")
+            lines.append("")
+            lines.append("| Particle Type | Threshold | Unit |")
+            lines.append("|---------------|-----------|------|")
+            ash_char = particulates.get("ash_char", {})
+            soot = particulates.get("aciniform_soot", {})
+            lines.append(
+                f"| Ash/Char | <{ash_char.get('clearance', 150)} | "
+                f"{ash_char.get('unit', 'cts/cm²')} |"
+            )
+            lines.append(
+                f"| Aciniform Soot | <{soot.get('clearance', 500)} | "
+                f"{soot.get('unit', 'cts/cm²')} |"
+            )
+            lines.append("")
+            lines.append(f"*Source: {ash_char.get('source', 'FDAM §1.5')}*")
+
+        return "\n".join(lines)
+
+    def _generate_footer(self) -> str:
+        """Generate document footer with disclaimer."""
+        return f"""## Disclaimer
+
+This document was generated using AI-assisted analysis per the Fire Damage Assessment
+Methodology (FDAM) v4.0.1. All recommendations should be reviewed by a qualified
+industrial hygienist before implementation.
+
+**Important Notes:**
+- Visual assessments require laboratory confirmation for definitive particle identification
+- Threshold values are subject to regulatory updates
+- Site-specific conditions may require deviation from standard protocols
+- Reclean/retest procedures apply per FDAM §4.7 if clearance is not achieved
+
+---
+
+*Generated by FDAM AI Pipeline v4.0.1*
+*{datetime.now().strftime('%Y-%m-%d %H:%M')}*"""

pipeline/main.py

@@ -0,0 +1,334 @@
+"""FDAM Pipeline Orchestrator.
+
+Coordinates the 6-stage processing pipeline:
+1. Input Validation
+2. Vision Analysis
+3. RAG Retrieval
+4. FDAM Logic (Dispositions)
+5. Calculations
+6. Document Generation
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Callable, Optional
+from PIL import Image
+import io
+
+from ui.state import SessionState
+from ui.components import image_store
+from models.loader import get_models
+
+logger = logging.getLogger(__name__)
+from rag import FDAMRetriever, ChromaVectorStore
+
+from .calculations import FDAMCalculator
+from .dispositions import DispositionEngine, SurfaceDisposition
+from .generator import DocumentGenerator, GeneratedDocument
+
+
+@dataclass
+class PipelineProgress:
+    """Progress information for pipeline execution."""
+
+    stage: int
+    total_stages: int
+    stage_name: str
+    percent: float
+    message: str
+
+
+@dataclass
+class VisionResult:
+    """Result from vision analysis of a single image."""
+
+    image_id: str
+    filename: str
+    room_id: str
+    zone: dict
+    condition: dict
+    materials: list[dict]
+    bounding_boxes: list[dict]
+    raw_response: dict
+
+
+@dataclass
+class PipelineResult:
+    """Complete result from pipeline execution."""
+
+    success: bool
+    session: SessionState
+    vision_results: dict[str, VisionResult]
+    dispositions: list[SurfaceDisposition]
+    calculations: dict
+    document: Optional[GeneratedDocument]
+    annotated_images: list[tuple]  # (PIL.Image, caption)
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    execution_time_seconds: float = 0.0
+
+
+ProgressCallback = Callable[[PipelineProgress], None]
+
+
+class FDAMPipeline:
+    """Main FDAM processing pipeline."""
+
+    STAGES = [
+        "Validating inputs",
+        "Analyzing images",
+        "Retrieving context",
+        "Applying FDAM logic",
+        "Running calculations",
+        "Generating documents",
+    ]
+
+    def __init__(
+        self,
+        calculator: Optional[FDAMCalculator] = None,
+        disposition_engine: Optional[DispositionEngine] = None,
+        generator: Optional[DocumentGenerator] = None,
+        retriever: Optional[FDAMRetriever] = None,
+    ):
+        """Initialize pipeline with optional component overrides.
+
+        Args:
+            calculator: FDAM calculator instance
+            disposition_engine: Disposition engine instance
+            generator: Document generator instance
+            retriever: RAG retriever instance
+        """
+        self.calculator = calculator or FDAMCalculator()
+        self._retriever = retriever
+        self.disposition_engine = disposition_engine or DispositionEngine(
+            retriever=self._retriever
+        )
+        self.generator = generator or DocumentGenerator(
+            calculator=self.calculator,
+            disposition_engine=self.disposition_engine,
+            retriever=self._retriever,
+        )
+
+    @property
+    def retriever(self) -> FDAMRetriever:
+        """Get or create RAG retriever."""
+        if self._retriever is None:
+            try:
+                vs = ChromaVectorStore(persist_directory="chroma_db")
+                self._retriever = FDAMRetriever(vectorstore=vs)
+            except Exception as e:
+                logger.warning(f"ChromaDB init failed, using fallback retriever: {e}")
+                self._retriever = FDAMRetriever()
+        return self._retriever
+
+    def execute(
+        self,
+        session: SessionState,
+        progress_callback: Optional[ProgressCallback] = None,
+    ) -> PipelineResult:
+        """Execute the full FDAM pipeline.
+
+        Args:
+            session: Session state with all input data
+            progress_callback: Optional callback for progress updates
+
+        Returns:
+            PipelineResult with all outputs
+        """
+        start_time = datetime.now()
+        errors = []
+        warnings = []
+
+        def report_progress(stage: int, message: str = ""):
+            if progress_callback:
+                progress_callback(
+                    PipelineProgress(
+                        stage=stage,
+                        total_stages=len(self.STAGES),
+                        stage_name=self.STAGES[stage - 1] if stage > 0 else "Starting",
+                        percent=stage / len(self.STAGES),
+                        message=message,
+                    )
+                )
+
+        # Stage 1: Input Validation
+        report_progress(1, "Validating inputs...")
+        can_generate, validation_errors = session.can_generate()
+
+        # Check images in store
+        expected_ids = [img.id for img in session.images]
+        missing_ids = image_store.get_missing_ids(expected_ids)
+
+        if not can_generate or missing_ids:
+            errors.extend(validation_errors)
+            if missing_ids:
+                errors.append(f"{len(missing_ids)} image(s) need to be re-uploaded")
+
+            return PipelineResult(
+                success=False,
+                session=session,
+                vision_results={},
+                dispositions=[],
+                calculations={},
+                document=None,
+                annotated_images=[],
+                errors=errors,
+                execution_time_seconds=(datetime.now() - start_time).total_seconds(),
+            )
+
+        # Stage 2: Vision Analysis
+        report_progress(2, "Analyzing images with AI...")
+        model_stack = get_models()
+        vision_results = {}
+        annotated_images = []
+        room_mapping = {}
+
+        for i, img_meta in enumerate(session.images):
+            img_bytes = image_store.get(img_meta.id)
+            if not img_bytes:
+                warnings.append(f"Image {img_meta.filename} not found in store")
+                continue
+
+            try:
+                pil_image = Image.open(io.BytesIO(img_bytes))
+
+                # Run vision analysis
+                result = model_stack.vision.analyze_image(
+                    pil_image,
+                    img_meta.description or "",
+                )
+
+                vision_result = VisionResult(
+                    image_id=img_meta.id,
+                    filename=img_meta.filename,
+                    room_id=img_meta.room_id,
+                    zone=result.get("zone", {}),
+                    condition=result.get("condition", {}),
+                    materials=result.get("materials", []),
+                    bounding_boxes=result.get("bounding_boxes", []),
+                    raw_response=result,
+                )
+                vision_results[img_meta.id] = vision_result
+
+                # Build room mapping
+                room_info = next(
+                    (r for r in session.rooms if r.id == img_meta.room_id),
+                    None,
+                )
+                room_mapping[img_meta.id] = {
+                    "name": room_info.name if room_info else "Unknown",
+                    "id": img_meta.room_id,
+                }
+
+                # Create annotated image caption
+                zone_class = result.get("zone", {}).get("classification", "N/A")
+                zone_conf = result.get("zone", {}).get("confidence", 0)
+                caption = f"{img_meta.filename}\nZone: {zone_class} ({zone_conf:.0%})"
+                annotated_images.append((pil_image, caption))
+
+                report_progress(
+                    2,
+                    f"Analyzed {i + 1}/{len(session.images)}: {img_meta.filename}",
+                )
+
+            except Exception as e:
+                warnings.append(f"Error analyzing {img_meta.filename}: {e}")
+
+        # Stage 3: RAG Retrieval
+        report_progress(3, "Retrieving FDAM methodology context...")
+        # RAG is integrated into disposition engine, just verify connection
+        try:
+            _ = self.retriever.retrieve("test connection", top_k=1)
+        except Exception as e:
+            warnings.append(f"RAG retrieval unavailable: {e}")
+
+        # Stage 4: FDAM Logic (Dispositions)
+        report_progress(4, "Applying disposition logic...")
+
+        # Convert vision results to dict format for disposition engine
+        vision_dict = {
+            img_id: {
+                "zone": vr.zone,
+                "condition": vr.condition,
+                "materials": vr.materials,
+            }
+            for img_id, vr in vision_results.items()
+        }
+
+        dispositions = self.disposition_engine.process_vision_results(
+            vision_results=vision_dict,
+            room_mapping=room_mapping,
+        )
+
+        # Stage 5: Calculations
+        report_progress(5, "Running FDAM calculations...")
+        calculations = self.calculator.calculate_from_session(session)
+
+        # Stage 6: Document Generation
+        report_progress(6, "Generating documents...")
+        document = self.generator.generate_sow(
+            session=session,
+            vision_results=vision_dict,
+            surface_dispositions=dispositions,
+            calculations=calculations,
+        )
+
+        # Update session
+        session.has_results = True
+        session.results_generated_at = datetime.now().isoformat()
+        session.update_timestamp()
+
+        execution_time = (datetime.now() - start_time).total_seconds()
+
+        return PipelineResult(
+            success=True,
+            session=session,
+            vision_results=vision_results,
+            dispositions=dispositions,
+            calculations=calculations,
+            document=document,
+            annotated_images=annotated_images,
+            errors=errors,
+            warnings=warnings,
+            execution_time_seconds=execution_time,
+        )
+
+    def generate_stats_dict(self, result: PipelineResult) -> dict:
+        """Generate statistics dictionary for UI display.
+
+        Args:
+            result: Pipeline execution result
+
+        Returns:
+            Dictionary with stats for JSON display
+        """
+        calc = result.calculations
+        air = calc.get("air_filtration")
+        sample = calc.get("sample_density")
+        reg = calc.get("regulatory_flags")
+        thresholds = calc.get("metals_thresholds")
+
+        # Count dispositions by type
+        disp_counts = {}
+        for d in result.dispositions:
+            disp_counts[d.disposition] = disp_counts.get(d.disposition, 0) + 1
+
+        return {
+            "project_name": result.session.project.project_name,
+            "facility_classification": result.session.project.facility_classification,
+            "construction_era": result.session.project.construction_era,
+            "total_rooms": len(result.session.rooms),
+            "total_images": len(result.session.images),
+            "images_analyzed": len(result.vision_results),
+            "total_floor_area_sf": f"{calc.get('total_area_sf', 0):,.0f}",
+            "total_volume_cf": f"{calc.get('total_volume_cf', 0):,.0f}",
+            "air_scrubbers_required": air.units_required if air else 0,
+            "tape_lifts_recommended": f"{sample.tape_lifts_min}-{sample.tape_lifts_max}" if sample else "N/A",
+            "surface_wipes_recommended": f"{sample.surface_wipes_min}-{sample.surface_wipes_max}" if sample else "N/A",
+            "disposition_counts": disp_counts,
+            "regulatory_flags": reg.notes if reg else [],
+            "lead_threshold": f"{thresholds.lead_ug_100cm2} µg/100cm²" if thresholds else "N/A",
+            "execution_time": f"{result.execution_time_seconds:.1f}s",
+            "warnings": result.warnings,
+        }

pipeline/pdf_generator.py

@@ -0,0 +1,315 @@
+"""PDF Generator using WeasyPrint.
+
+Converts Markdown SOW documents to professional PDF format.
+Uses markdown → HTML → PDF pipeline with WeasyPrint.
+"""
+
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+import markdown
+
+
+@dataclass
+class PDFResult:
+    """Result of PDF generation."""
+
+    success: bool
+    pdf_path: Optional[str]
+    error_message: Optional[str] = None
+    file_size_bytes: int = 0
+
+
+# Professional CSS styling for SOW documents
+SOW_CSS = """
+@page {
+    size: letter;
+    margin: 0.75in;
+    @top-center {
+        content: "FDAM Assessment Report";
+        font-size: 9pt;
+        color: #666;
+    }
+    @bottom-center {
+        content: "Page " counter(page) " of " counter(pages);
+        font-size: 9pt;
+        color: #666;
+    }
+}
+
+body {
+    font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+    font-size: 11pt;
+    line-height: 1.5;
+    color: #333;
+}
+
+h1 {
+    font-size: 20pt;
+    color: #1a1a1a;
+    border-bottom: 2px solid #0066cc;
+    padding-bottom: 8px;
+    margin-top: 0;
+}
+
+h2 {
+    font-size: 14pt;
+    color: #0066cc;
+    margin-top: 20px;
+    border-bottom: 1px solid #ddd;
+    padding-bottom: 4px;
+}
+
+h3 {
+    font-size: 12pt;
+    color: #333;
+    margin-top: 15px;
+}
+
+table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 15px 0;
+    font-size: 10pt;
+}
+
+th {
+    background-color: #0066cc;
+    color: white;
+    padding: 8px 10px;
+    text-align: left;
+    font-weight: bold;
+}
+
+td {
+    padding: 6px 10px;
+    border-bottom: 1px solid #ddd;
+}
+
+tr:nth-child(even) {
+    background-color: #f8f9fa;
+}
+
+tr:hover {
+    background-color: #e9ecef;
+}
+
+ul, ol {
+    margin: 10px 0;
+    padding-left: 25px;
+}
+
+li {
+    margin: 4px 0;
+}
+
+strong {
+    color: #1a1a1a;
+}
+
+code {
+    background-color: #f4f4f4;
+    padding: 2px 5px;
+    border-radius: 3px;
+    font-size: 10pt;
+}
+
+hr {
+    border: none;
+    border-top: 1px solid #ddd;
+    margin: 20px 0;
+}
+
+.disclaimer {
+    background-color: #fff3cd;
+    border: 1px solid #ffc107;
+    padding: 12px;
+    border-radius: 4px;
+    font-size: 10pt;
+    margin-top: 20px;
+}
+
+em {
+    color: #666;
+}
+"""
+
+
+class PDFGenerator:
+    """Generates PDF documents from Markdown using WeasyPrint."""
+
+    def __init__(self, custom_css: Optional[str] = None):
+        """Initialize PDF generator.
+
+        Args:
+            custom_css: Optional custom CSS to override default styling
+        """
+        self.css = custom_css or SOW_CSS
+        self._weasyprint_available = None
+
+    @property
+    def weasyprint_available(self) -> bool:
+        """Check if WeasyPrint is available."""
+        if self._weasyprint_available is None:
+            try:
+                from weasyprint import HTML
+                self._weasyprint_available = True
+            except ImportError:
+                self._weasyprint_available = False
+        return self._weasyprint_available
+
+    def markdown_to_html(self, markdown_content: str) -> str:
+        """Convert Markdown to HTML with styling.
+
+        Args:
+            markdown_content: Markdown text
+
+        Returns:
+            Complete HTML document with CSS
+        """
+        # Convert markdown to HTML
+        md = markdown.Markdown(
+            extensions=[
+                "tables",
+                "fenced_code",
+                "toc",
+            ]
+        )
+        html_body = md.convert(markdown_content)
+
+        # Wrap in complete HTML document with CSS
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <style>
+{self.css}
+    </style>
+</head>
+<body>
+{html_body}
+</body>
+</html>"""
+        return html
+
+    def generate_pdf(
+        self,
+        markdown_content: str,
+        output_path: Optional[str] = None,
+    ) -> PDFResult:
+        """Generate PDF from Markdown content.
+
+        Args:
+            markdown_content: Markdown text to convert
+            output_path: Optional output file path. If None, uses temp file.
+
+        Returns:
+            PDFResult with success status and file path
+        """
+        if not self.weasyprint_available:
+            return PDFResult(
+                success=False,
+                pdf_path=None,
+                error_message="WeasyPrint is not installed. Run: pip install weasyprint",
+            )
+
+        try:
+            from weasyprint import HTML
+
+            # Convert markdown to styled HTML
+            html_content = self.markdown_to_html(markdown_content)
+
+            # Determine output path
+            if output_path is None:
+                output_file = tempfile.NamedTemporaryFile(
+                    suffix=".pdf",
+                    delete=False,
+                    prefix="SOW_",
+                )
+                output_path = output_file.name
+                output_file.close()
+
+            # Generate PDF
+            HTML(string=html_content).write_pdf(output_path)
+
+            # Verify file was created
+            pdf_path = Path(output_path)
+            if not pdf_path.exists():
+                return PDFResult(
+                    success=False,
+                    pdf_path=None,
+                    error_message="PDF file was not created",
+                )
+
+            return PDFResult(
+                success=True,
+                pdf_path=str(pdf_path),
+                file_size_bytes=pdf_path.stat().st_size,
+            )
+
+        except Exception as e:
+            return PDFResult(
+                success=False,
+                pdf_path=None,
+                error_message=f"PDF generation failed: {str(e)}",
+            )
+
+    def generate_html(
+        self,
+        markdown_content: str,
+        output_path: Optional[str] = None,
+    ) -> tuple[bool, Optional[str], Optional[str]]:
+        """Generate HTML from Markdown (fallback if PDF fails).
+
+        Args:
+            markdown_content: Markdown text
+            output_path: Optional output path
+
+        Returns:
+            Tuple of (success, file_path, error_message)
+        """
+        try:
+            html_content = self.markdown_to_html(markdown_content)
+
+            if output_path is None:
+                output_file = tempfile.NamedTemporaryFile(
+                    mode="w",
+                    suffix=".html",
+                    delete=False,
+                    prefix="SOW_",
+                    encoding="utf-8",
+                )
+                output_path = output_file.name
+                output_file.write(html_content)
+                output_file.close()
+            else:
+                with open(output_path, "w", encoding="utf-8") as f:
+                    f.write(html_content)
+
+            return True, output_path, None
+
+        except Exception as e:
+            return False, None, str(e)
+
+
+def generate_sow_pdf(
+    markdown_content: str,
+    project_name: str,
+    output_path: Optional[str] = None,
+) -> PDFResult:
+    """Convenience function to generate SOW PDF.
+
+    Args:
+        markdown_content: SOW markdown content
+        project_name: Project name for filename
+        output_path: Optional output path
+
+    Returns:
+        PDFResult with success status
+    """
+    generator = PDFGenerator()
+    return generator.generate_pdf(
+        markdown_content=markdown_content,
+        output_path=output_path,
+    )

rag/__init__.py

@@ -0,0 +1,16 @@
+"""RAG (Retrieval Augmented Generation) module for FDAM AI Pipeline.
+
+This module provides document chunking, vector storage, and retrieval
+for the FDAM knowledge base.
+"""
+
+from .chunker import SemanticChunker, Chunk
+from .vectorstore import ChromaVectorStore
+from .retriever import FDAMRetriever
+
+__all__ = [
+    "SemanticChunker",
+    "Chunk",
+    "ChromaVectorStore",
+    "FDAMRetriever",
+]

rag/chunker.py

@@ -0,0 +1,432 @@
+"""Semantic chunker with table preservation for FDAM knowledge base.
+
+Chunking rules:
+- Keep markdown tables intact (never split)
+- Preserve headers with content for context
+- Target 400-600 tokens per chunk
+- Include metadata (source, category, section, priority)
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+from pathlib import Path
+
+
+@dataclass
+class Chunk:
+    """A chunk of text with metadata for RAG indexing."""
+
+    id: str
+    text: str
+    source: str  # Filename
+    category: Literal[
+        "methodology",
+        "thresholds",
+        "lab-methods",
+        "cleaning-procedures",
+        "wildfire",
+        "safety",
+    ]
+    section: str  # Section header path (e.g., "4.1 Zone Classification")
+    priority: Literal["primary", "reference-threshold", "reference-narrative"]
+    content_type: Literal["narrative", "table", "list", "mixed"]
+    keywords: list[str] = field(default_factory=list)
+
+    def to_metadata(self) -> dict:
+        """Convert to metadata dict for ChromaDB."""
+        return {
+            "source": self.source,
+            "category": self.category,
+            "section": self.section,
+            "priority": self.priority,
+            "content_type": self.content_type,
+            "keywords": ",".join(self.keywords),
+        }
+
+
+class SemanticChunker:
+    """Chunks markdown documents while preserving tables and semantic structure."""
+
+    # Approximate tokens per character (conservative estimate)
+    CHARS_PER_TOKEN = 4
+    TARGET_MIN_TOKENS = 400
+    TARGET_MAX_TOKENS = 600
+
+    def __init__(self):
+        self.target_min_chars = self.TARGET_MIN_TOKENS * self.CHARS_PER_TOKEN
+        self.target_max_chars = self.TARGET_MAX_TOKENS * self.CHARS_PER_TOKEN
+
+    def chunk_document(
+        self,
+        text: str,
+        source: str,
+        category: Literal[
+            "methodology",
+            "thresholds",
+            "lab-methods",
+            "cleaning-procedures",
+            "wildfire",
+            "safety",
+        ],
+        priority: Literal["primary", "reference-threshold", "reference-narrative"],
+    ) -> list[Chunk]:
+        """Chunk a markdown document into semantic units.
+
+        Args:
+            text: Full document text (markdown format)
+            source: Source filename
+            category: Document category
+            priority: Document priority level
+
+        Returns:
+            List of Chunk objects ready for indexing
+        """
+        # Split into sections by headers
+        sections = self._split_by_headers(text)
+
+        chunks = []
+        chunk_counter = 0
+
+        # Accumulator that persists across sections
+        current_chunk_text = ""
+        current_content_types: set[str] = set()
+        current_section = "Introduction"  # Track primary section for metadata
+
+        for section_header, section_content in sections:
+            # Split section into blocks (paragraphs, tables, lists)
+            blocks = self._split_into_blocks(section_content)
+
+            for block_text, block_type in blocks:
+                block_len = len(block_text)
+
+                # Tables are never split - flush current and add table as own chunk
+                if block_type == "table":
+                    # Flush current chunk if it meets minimum size
+                    if current_chunk_text.strip() and len(current_chunk_text) >= self.target_min_chars:
+                        chunks.append(
+                            self._create_chunk(
+                                chunk_id=f"{source}_{chunk_counter}",
+                                text=current_chunk_text.strip(),
+                                source=source,
+                                category=category,
+                                section=current_section,
+                                priority=priority,
+                                content_types=current_content_types,
+                            )
+                        )
+                        chunk_counter += 1
+                        current_chunk_text = ""
+                        current_content_types = set()
+                        current_section = section_header
+                    elif current_chunk_text.strip():
+                        # Below minimum - prepend to table context
+                        pass  # Keep accumulating, table will have its own chunk
+
+                    # Add table as its own chunk (tables always standalone)
+                    table_text = f"{section_header}\n\n{block_text}".strip()
+                    # If we have small accumulated content, prepend it to give context
+                    if current_chunk_text.strip() and len(current_chunk_text) < self.target_min_chars:
+                        table_text = current_chunk_text.strip() + "\n\n" + table_text
+                        current_chunk_text = ""
+                        current_content_types = set()
+
+                    chunks.append(
+                        self._create_chunk(
+                            chunk_id=f"{source}_{chunk_counter}",
+                            text=table_text,
+                            source=source,
+                            category=category,
+                            section=section_header,
+                            priority=priority,
+                            content_types={"table"},
+                        )
+                    )
+                    chunk_counter += 1
+                    current_section = section_header
+                    continue
+
+                # Check if adding this block exceeds target max
+                potential_len = len(current_chunk_text) + block_len + len(section_header) + 4
+
+                if potential_len > self.target_max_chars and len(current_chunk_text) >= self.target_min_chars:
+                    # Flush current chunk - it's large enough
+                    chunks.append(
+                        self._create_chunk(
+                            chunk_id=f"{source}_{chunk_counter}",
+                            text=current_chunk_text.strip(),
+                            source=source,
+                            category=category,
+                            section=current_section,
+                            priority=priority,
+                            content_types=current_content_types,
+                        )
+                    )
+                    chunk_counter += 1
+                    # Start new chunk with section header
+                    current_chunk_text = f"{section_header}\n\n"
+                    current_content_types = set()
+                    current_section = section_header
+
+                # Add section header if starting fresh or new section
+                if not current_chunk_text.strip():
+                    current_chunk_text = f"{section_header}\n\n"
+                    current_section = section_header
+                elif section_header != current_section and section_header not in current_chunk_text:
+                    # Add new section header inline for context
+                    current_chunk_text += f"\n{section_header}\n\n"
+
+                current_chunk_text += block_text + "\n\n"
+                current_content_types.add(block_type)
+
+        # Flush remaining content (regardless of size - it's the end)
+        if current_chunk_text.strip():
+            chunks.append(
+                self._create_chunk(
+                    chunk_id=f"{source}_{chunk_counter}",
+                    text=current_chunk_text.strip(),
+                    source=source,
+                    category=category,
+                    section=current_section,
+                    priority=priority,
+                    content_types=current_content_types,
+                )
+            )
+
+        return chunks
+
+    def _split_by_headers(self, text: str) -> list[tuple[str, str]]:
+        """Split document by markdown headers (## and ###).
+
+        Returns list of (header, content) tuples.
+        """
+        # Match ## or ### headers
+        header_pattern = r"^(#{2,3}\s+.+)$"
+        lines = text.split("\n")
+
+        sections = []
+        current_header = "Introduction"
+        current_content = []
+
+        for line in lines:
+            if re.match(header_pattern, line):
+                # Save previous section
+                if current_content:
+                    sections.append((current_header, "\n".join(current_content)))
+                current_header = line.strip()
+                current_content = []
+            else:
+                current_content.append(line)
+
+        # Save final section
+        if current_content:
+            sections.append((current_header, "\n".join(current_content)))
+
+        return sections
+
+    def _split_into_blocks(self, text: str) -> list[tuple[str, str]]:
+        """Split section content into blocks (paragraphs, tables, lists).
+
+        Returns list of (block_text, block_type) tuples.
+        """
+        blocks = []
+        lines = text.split("\n")
+        current_block = []
+        current_type = "narrative"
+        in_table = False
+
+        for line in lines:
+            # Detect table start/end
+            if line.strip().startswith("|") and "|" in line[1:]:
+                if not in_table:
+                    # Flush current block
+                    if current_block:
+                        block_text = "\n".join(current_block).strip()
+                        if block_text:
+                            blocks.append((block_text, current_type))
+                        current_block = []
+                    in_table = True
+                    current_type = "table"
+                current_block.append(line)
+            elif in_table:
+                # Table ended
+                block_text = "\n".join(current_block).strip()
+                if block_text:
+                    blocks.append((block_text, "table"))
+                current_block = [line] if line.strip() else []
+                in_table = False
+                current_type = "narrative"
+            elif line.strip().startswith(("- ", "* ", "1. ", "2. ", "3. ")):
+                # List item
+                if current_type != "list" and current_block:
+                    block_text = "\n".join(current_block).strip()
+                    if block_text:
+                        blocks.append((block_text, current_type))
+                    current_block = []
+                current_type = "list"
+                current_block.append(line)
+            elif line.strip() == "" and current_block:
+                # Paragraph break
+                if not in_table:
+                    block_text = "\n".join(current_block).strip()
+                    if block_text:
+                        blocks.append((block_text, current_type))
+                    current_block = []
+                    current_type = "narrative"
+            else:
+                if current_type == "list" and not line.strip().startswith(
+                    ("- ", "* ", "  ")
+                ):
+                    # End of list
+                    block_text = "\n".join(current_block).strip()
+                    if block_text:
+                        blocks.append((block_text, "list"))
+                    current_block = []
+                    current_type = "narrative"
+                current_block.append(line)
+
+        # Flush remaining
+        if current_block:
+            block_text = "\n".join(current_block).strip()
+            if block_text:
+                blocks.append((block_text, current_type))
+
+        return blocks
+
+    def _create_chunk(
+        self,
+        chunk_id: str,
+        text: str,
+        source: str,
+        category: str,
+        section: str,
+        priority: str,
+        content_types: set[str],
+    ) -> Chunk:
+        """Create a Chunk object with extracted keywords."""
+        # Determine primary content type
+        if "table" in content_types:
+            content_type = "table"
+        elif "list" in content_types and "narrative" in content_types:
+            content_type = "mixed"
+        elif "list" in content_types:
+            content_type = "list"
+        else:
+            content_type = "narrative"
+
+        # Extract keywords from text
+        keywords = self._extract_keywords(text)
+
+        return Chunk(
+            id=chunk_id,
+            text=text,
+            source=source,
+            category=category,
+            section=section,
+            priority=priority,
+            content_type=content_type,
+            keywords=keywords,
+        )
+
+    def _extract_keywords(self, text: str) -> list[str]:
+        """Extract relevant keywords from chunk text."""
+        # Domain-specific keywords to look for
+        domain_terms = [
+            # Zone classifications
+            "burn zone",
+            "near-field",
+            "far-field",
+            # Condition levels
+            "background",
+            "light",
+            "moderate",
+            "heavy",
+            "structural damage",
+            # Dispositions
+            "no action",
+            "clean",
+            "evaluate",
+            "remove",
+            "remove/repair",
+            # Materials
+            "soot",
+            "char",
+            "ash",
+            "particulate",
+            "aciniform",
+            # Thresholds
+            "lead",
+            "cadmium",
+            "arsenic",
+            "metals",
+            "µg/100cm²",
+            "cts/cm²",
+            # Facility types
+            "operational",
+            "non-operational",
+            "public",
+            "childcare",
+            # Standards
+            "ach",
+            "nadca",
+            "epa",
+            "hud",
+            "osha",
+            # Sampling
+            "sampling",
+            "wipe",
+            "bulk",
+            "air",
+            "clearance",
+            # Lab methods
+            "plm",
+            "icp-ms",
+            "xrf",
+            "tapelift",
+            # Actions
+            "hepa",
+            "vacuum",
+            "deodorization",
+            "encapsulation",
+        ]
+
+        text_lower = text.lower()
+        found_keywords = []
+
+        for term in domain_terms:
+            if term in text_lower:
+                found_keywords.append(term)
+
+        return found_keywords[:10]  # Limit to top 10
+
+
+def chunk_file(
+    filepath: Path,
+    category: Literal[
+        "methodology",
+        "thresholds",
+        "lab-methods",
+        "cleaning-procedures",
+        "wildfire",
+        "safety",
+    ],
+    priority: Literal["primary", "reference-threshold", "reference-narrative"],
+) -> list[Chunk]:
+    """Convenience function to chunk a markdown file.
+
+    Args:
+        filepath: Path to markdown file
+        category: Document category
+        priority: Document priority level
+
+    Returns:
+        List of Chunk objects
+    """
+    chunker = SemanticChunker()
+    text = filepath.read_text(encoding="utf-8")
+    return chunker.chunk_document(
+        text=text,
+        source=filepath.name,
+        category=category,
+        priority=priority,
+    )

rag/index_builder.py

@@ -0,0 +1,187 @@
+"""Index builder for FDAM RAG knowledge base.
+
+Processes markdown documents from RAG-KB/ and indexes them in ChromaDB.
+
+Usage:
+    python -m rag.index_builder [--rebuild]
+"""
+
+import argparse
+from pathlib import Path
+
+from rag.chunker import SemanticChunker, Chunk
+from rag.vectorstore import ChromaVectorStore
+
+
+# Document configuration: filename -> (category, priority)
+DOCUMENT_CONFIG = {
+    # PRIMARY - FDAM Methodology (authoritative source)
+    "FDAM_v4_METHODOLOGY.md": ("methodology", "primary"),
+    # REFERENCE - Threshold Tables (critical for metals clearance)
+    "Metals clearance criteria-QVC.md": ("thresholds", "reference-threshold"),
+    # REFERENCE - Narrative (supporting documentation)
+    "air-o-cell-method-guide-atlas.md": ("lab-methods", "reference-narrative"),
+    "Industrial Hygiene Lab Services Guide.md": ("lab-methods", "reference-narrative"),
+    "Fire Remediation Processes and Methodologies_ A Review of Industry-Endorsed Standards.md": (
+        "cleaning-procedures",
+        "reference-narrative",
+    ),
+    "Technical Guide for Wildfire Restoration - Key Information.md": (
+        "wildfire",
+        "reference-narrative",
+    ),
+    "wildfire_soot_particulate_removal_full_text_extraction.md": (
+        "wildfire",
+        "reference-narrative",
+    ),
+}
+
+# Files to skip (per user decision)
+SKIP_FILES = {
+    "Lead Contamination in Indoor Firing_Gun Ranges _ Atlantic Environmental.pdf",
+}
+
+
+def get_rag_kb_path() -> Path:
+    """Get path to RAG-KB directory."""
+    # Try relative to this file first
+    this_dir = Path(__file__).parent
+    rag_kb = this_dir.parent / "RAG-KB"
+    if rag_kb.exists():
+        return rag_kb
+
+    # Try from current working directory
+    rag_kb = Path("RAG-KB")
+    if rag_kb.exists():
+        return rag_kb
+
+    raise FileNotFoundError("Could not find RAG-KB directory")
+
+
+def get_chroma_path() -> Path:
+    """Get path to ChromaDB persistence directory."""
+    this_dir = Path(__file__).parent
+    chroma_path = this_dir.parent / "chroma_db"
+    return chroma_path
+
+
+def build_index(rebuild: bool = False) -> dict:
+    """Build the RAG index from RAG-KB documents.
+
+    Args:
+        rebuild: If True, clear existing index before building
+
+    Returns:
+        Statistics about the indexing operation
+    """
+    rag_kb_path = get_rag_kb_path()
+    chroma_path = get_chroma_path()
+
+    print(f"RAG-KB path: {rag_kb_path}")
+    print(f"ChromaDB path: {chroma_path}")
+
+    # Initialize components
+    chunker = SemanticChunker()
+    vectorstore = ChromaVectorStore(persist_directory=str(chroma_path))
+
+    if rebuild:
+        print("Rebuilding index - clearing existing data...")
+        vectorstore.clear()
+
+    stats = {
+        "documents_processed": 0,
+        "documents_skipped": 0,
+        "chunks_created": 0,
+        "errors": [],
+    }
+
+    # Process markdown files
+    for md_file in rag_kb_path.glob("*.md"):
+        filename = md_file.name
+
+        # Skip files not in config or in skip list
+        if filename in SKIP_FILES:
+            print(f"Skipping (excluded): {filename}")
+            stats["documents_skipped"] += 1
+            continue
+
+        if filename not in DOCUMENT_CONFIG:
+            print(f"Skipping (not configured): {filename}")
+            stats["documents_skipped"] += 1
+            continue
+
+        category, priority = DOCUMENT_CONFIG[filename]
+        print(f"Processing: {filename} ({category}, {priority})")
+
+        try:
+            # Read and chunk document
+            text = md_file.read_text(encoding="utf-8")
+            chunks = chunker.chunk_document(
+                text=text,
+                source=filename,
+                category=category,
+                priority=priority,
+            )
+
+            # Check if source already indexed (for incremental updates)
+            existing_count = vectorstore.delete_by_source(filename)
+            if existing_count > 0:
+                print(f"  Replaced {existing_count} existing chunks")
+
+            # Add to vectorstore
+            added = vectorstore.add_chunks(chunks)
+            print(f"  Added {added} chunks")
+
+            stats["documents_processed"] += 1
+            stats["chunks_created"] += added
+
+        except Exception as e:
+            error_msg = f"Error processing {filename}: {e}"
+            print(f"  ERROR: {e}")
+            stats["errors"].append(error_msg)
+
+    # Report on PDFs that need conversion
+    for pdf_file in rag_kb_path.glob("*.pdf"):
+        if pdf_file.name not in SKIP_FILES:
+            print(f"Note: PDF needs conversion to .md: {pdf_file.name}")
+
+    # Print summary
+    print("\n" + "=" * 50)
+    print("Index Build Complete")
+    print("=" * 50)
+    print(f"Documents processed: {stats['documents_processed']}")
+    print(f"Documents skipped: {stats['documents_skipped']}")
+    print(f"Total chunks created: {stats['chunks_created']}")
+
+    if stats["errors"]:
+        print(f"Errors: {len(stats['errors'])}")
+        for err in stats["errors"]:
+            print(f"  - {err}")
+
+    # Print collection stats
+    collection_stats = vectorstore.get_stats()
+    print(f"\nCollection stats:")
+    print(f"  Total chunks in DB: {collection_stats['total_chunks']}")
+    print(f"  Categories: {collection_stats['categories']}")
+    print(f"  Priorities: {collection_stats['priorities']}")
+
+    return stats
+
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Build FDAM RAG knowledge base index"
+    )
+    parser.add_argument(
+        "--rebuild",
+        action="store_true",
+        help="Clear existing index and rebuild from scratch",
+    )
+    args = parser.parse_args()
+
+    build_index(rebuild=args.rebuild)
+
+
+if __name__ == "__main__":
+    main()

rag/retriever.py

@@ -0,0 +1,380 @@
+"""FDAM retriever with priority weighting and reranking.
+
+Implements tiered retrieval:
+1. Vector similarity search
+2. Priority weighting (primary > reference-threshold > reference-narrative)
+3. Optional reranking for production
+"""
+
+from typing import Optional
+from dataclasses import dataclass
+
+from config.settings import settings
+from .vectorstore import ChromaVectorStore
+
+
+@dataclass
+class RetrievalResult:
+    """A single retrieval result with relevance score."""
+
+    chunk_id: str
+    text: str
+    source: str
+    category: str
+    section: str
+    priority: str
+    content_type: str
+    keywords: list[str]
+    similarity_score: float  # 0-1, higher is better
+    weighted_score: float  # After priority weighting
+    final_score: float  # After reranking (if applied)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "chunk_id": self.chunk_id,
+            "text": self.text,
+            "source": self.source,
+            "category": self.category,
+            "section": self.section,
+            "priority": self.priority,
+            "content_type": self.content_type,
+            "keywords": self.keywords,
+            "similarity_score": self.similarity_score,
+            "weighted_score": self.weighted_score,
+            "final_score": self.final_score,
+        }
+
+
+class MockReranker:
+    """Mock reranker for local development.
+
+    Simply returns scores based on keyword overlap.
+    """
+
+    def rerank(
+        self,
+        query: str,
+        documents: list[str],
+    ) -> list[float]:
+        """Score documents based on keyword overlap with query.
+
+        Args:
+            query: Query text
+            documents: List of document texts
+
+        Returns:
+            List of scores (0-1) for each document
+        """
+        query_words = set(query.lower().split())
+        scores = []
+
+        for doc in documents:
+            doc_words = set(doc.lower().split())
+            # Jaccard-like overlap score
+            overlap = len(query_words & doc_words)
+            total = len(query_words | doc_words)
+            score = overlap / total if total > 0 else 0.0
+            scores.append(score)
+
+        return scores
+
+
+class RealReranker:
+    """Real reranker using Qwen3-VL-Reranker-8B.
+
+    Loaded on-demand when MOCK_MODELS=false.
+    """
+
+    def __init__(self):
+        self.model = None
+        self.tokenizer = None
+
+    def _load_model(self):
+        """Lazy load the reranker model."""
+        if self.model is not None:
+            return
+
+        import torch
+        from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+        model_name = "Qwen/Qwen3-VL-Reranker-8B"
+        print(f"Loading reranker model: {model_name}")
+
+        self.tokenizer = AutoTokenizer.from_pretrained(
+            model_name,
+            trust_remote_code=True,
+        )
+        self.model = AutoModelForSequenceClassification.from_pretrained(
+            model_name,
+            torch_dtype=torch.bfloat16,
+            device_map="auto",
+            trust_remote_code=True,
+        )
+        self.model.eval()
+
+    def rerank(
+        self,
+        query: str,
+        documents: list[str],
+    ) -> list[float]:
+        """Score documents using the reranker model.
+
+        Args:
+            query: Query text
+            documents: List of document texts
+
+        Returns:
+            List of scores for each document
+        """
+        self._load_model()
+
+        import torch
+
+        scores = []
+        with torch.no_grad():
+            for doc in documents:
+                inputs = self.tokenizer(
+                    query,
+                    doc,
+                    return_tensors="pt",
+                    truncation=True,
+                    max_length=512,
+                    padding=True,
+                )
+                inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
+
+                outputs = self.model(**inputs)
+                # Sigmoid to get 0-1 score
+                score = torch.sigmoid(outputs.logits).squeeze().item()
+                scores.append(score)
+
+        return scores
+
+
+def get_reranker():
+    """Get appropriate reranker based on settings."""
+    if settings.mock_models:
+        return MockReranker()
+    return RealReranker()
+
+
+class FDAMRetriever:
+    """FDAM-specific retriever with priority weighting.
+
+    Priority weights:
+    - primary: 1.0 (FDAM methodology)
+    - reference-threshold: 0.9 (Threshold tables)
+    - reference-narrative: 0.8 (Supporting documentation)
+    """
+
+    PRIORITY_WEIGHTS = {
+        "primary": 1.0,
+        "reference-threshold": 0.9,
+        "reference-narrative": 0.8,
+    }
+
+    def __init__(
+        self,
+        vectorstore: Optional[ChromaVectorStore] = None,
+        reranker=None,
+        use_reranking: bool = True,
+    ):
+        """Initialize retriever.
+
+        Args:
+            vectorstore: ChromaDB vector store instance.
+                        If None, creates default instance.
+            reranker: Reranker instance. If None, uses appropriate default.
+            use_reranking: Whether to apply reranking step.
+        """
+        self.vectorstore = vectorstore or ChromaVectorStore()
+        self.reranker = reranker if reranker is not None else get_reranker()
+        self.use_reranking = use_reranking
+
+    def retrieve(
+        self,
+        query: str,
+        top_k: int = 5,
+        category_filter: Optional[str] = None,
+        priority_filter: Optional[str] = None,
+        include_scores: bool = True,
+    ) -> list[RetrievalResult]:
+        """Retrieve relevant chunks for a query.
+
+        Args:
+            query: Query text
+            top_k: Number of results to return
+            category_filter: Optional category to filter by
+            priority_filter: Optional priority to filter by
+            include_scores: Whether to include score details
+
+        Returns:
+            List of RetrievalResult objects, sorted by final_score descending
+        """
+        # Build metadata filter
+        where_filter = None
+        if category_filter or priority_filter:
+            where_filter = {}
+            if category_filter:
+                where_filter["category"] = category_filter
+            if priority_filter:
+                where_filter["priority"] = priority_filter
+
+        # Fetch more results than needed for reranking
+        fetch_k = top_k * 3 if self.use_reranking else top_k
+
+        # Query vector store
+        raw_results = self.vectorstore.query(
+            query_text=query,
+            n_results=fetch_k,
+            where=where_filter,
+        )
+
+        if not raw_results:
+            return []
+
+        # Convert to RetrievalResult objects with priority weighting
+        results = []
+        for r in raw_results:
+            # Convert distance to similarity (cosine distance: 0 = identical)
+            similarity = 1.0 - r["distance"]
+
+            # Apply priority weight
+            priority = r["metadata"].get("priority", "reference-narrative")
+            weight = self.PRIORITY_WEIGHTS.get(priority, 0.8)
+            weighted_score = similarity * weight
+
+            # Parse keywords
+            keywords_str = r["metadata"].get("keywords", "")
+            keywords = keywords_str.split(",") if keywords_str else []
+
+            results.append(
+                RetrievalResult(
+                    chunk_id=r["id"],
+                    text=r["document"],
+                    source=r["metadata"].get("source", "unknown"),
+                    category=r["metadata"].get("category", "unknown"),
+                    section=r["metadata"].get("section", "unknown"),
+                    priority=priority,
+                    content_type=r["metadata"].get("content_type", "narrative"),
+                    keywords=keywords,
+                    similarity_score=similarity,
+                    weighted_score=weighted_score,
+                    final_score=weighted_score,  # Will be updated by reranking
+                )
+            )
+
+        # Apply reranking if enabled
+        if self.use_reranking and results:
+            documents = [r.text for r in results]
+            rerank_scores = self.reranker.rerank(query, documents)
+
+            # Combine weighted score with rerank score
+            # Final = 0.6 * weighted + 0.4 * rerank
+            for i, result in enumerate(results):
+                rerank_score = rerank_scores[i]
+                result.final_score = 0.6 * result.weighted_score + 0.4 * rerank_score
+
+        # Sort by final score (descending) and take top_k
+        results.sort(key=lambda x: x.final_score, reverse=True)
+        return results[:top_k]
+
+    def retrieve_for_context(
+        self,
+        query: str,
+        top_k: int = 5,
+    ) -> str:
+        """Retrieve and format chunks as context string for LLM.
+
+        Args:
+            query: Query text
+            top_k: Number of chunks to include
+
+        Returns:
+            Formatted context string with source citations
+        """
+        results = self.retrieve(query, top_k=top_k)
+
+        if not results:
+            return "No relevant context found."
+
+        context_parts = []
+        for i, r in enumerate(results, 1):
+            context_parts.append(
+                f"[{i}] Source: {r.source} | Section: {r.section}\n{r.text}"
+            )
+
+        return "\n\n---\n\n".join(context_parts)
+
+    def retrieve_thresholds(
+        self,
+        material_type: str,
+        facility_type: str,
+    ) -> list[RetrievalResult]:
+        """Retrieve threshold values for a specific material and facility type.
+
+        Convenience method for threshold lookups.
+
+        Args:
+            material_type: Type of material (e.g., "lead", "soot", "char")
+            facility_type: Facility classification
+
+        Returns:
+            Relevant threshold results
+        """
+        query = f"{material_type} threshold {facility_type} clearance criteria"
+        return self.retrieve(
+            query=query,
+            top_k=3,
+            category_filter="thresholds",
+        )
+
+    def retrieve_disposition(
+        self,
+        zone: str,
+        condition: str,
+        material_type: Optional[str] = None,
+    ) -> list[RetrievalResult]:
+        """Retrieve disposition guidance for zone/condition combination.
+
+        Convenience method for disposition lookups.
+
+        Args:
+            zone: Zone classification (burn-zone, near-field, far-field)
+            condition: Condition level (background, light, moderate, heavy, structural-damage)
+            material_type: Optional material type for specific guidance
+
+        Returns:
+            Relevant disposition results
+        """
+        query = f"disposition {zone} {condition}"
+        if material_type:
+            query += f" {material_type}"
+        query += " cleaning recommendation"
+
+        return self.retrieve(
+            query=query,
+            top_k=5,
+            priority_filter="primary",  # Prefer FDAM methodology
+        )
+
+    def retrieve_cleaning_method(
+        self,
+        surface_type: str,
+        condition: str,
+    ) -> list[RetrievalResult]:
+        """Retrieve cleaning method recommendations.
+
+        Args:
+            surface_type: Type of surface (e.g., "drywall", "concrete", "metal")
+            condition: Condition level
+
+        Returns:
+            Relevant cleaning method results
+        """
+        query = f"cleaning method {surface_type} {condition} procedure hepa"
+        return self.retrieve(
+            query=query,
+            top_k=5,
+        )

rag/vectorstore.py

@@ -0,0 +1,287 @@
+"""ChromaDB vector store for FDAM knowledge base.
+
+Provides embedding and storage with metadata support.
+Uses mock embeddings when MOCK_MODELS=true for local development.
+"""
+
+import hashlib
+from typing import Optional
+from pathlib import Path
+
+import chromadb
+from chromadb.config import Settings
+
+from config.settings import settings
+from .chunker import Chunk
+
+
+class MockEmbeddingFunction:
+    """Mock embedding function for local development.
+
+    Generates deterministic pseudo-embeddings based on text hash.
+    Produces 384-dimensional vectors (matches common embedding models).
+    """
+
+    EMBEDDING_DIM = 384
+
+    def __call__(self, input: list[str]) -> list[list[float]]:
+        """Generate mock embeddings for a list of texts."""
+        return [self._embed_text(text) for text in input]
+
+    def _embed_text(self, text: str) -> list[float]:
+        """Generate a deterministic pseudo-embedding from text.
+
+        Uses SHA-256 hash expanded to fill embedding dimensions.
+        Not semantically meaningful but provides consistent behavior.
+        """
+        # Hash the text
+        text_hash = hashlib.sha256(text.encode("utf-8")).digest()
+
+        # Expand hash to fill embedding dimensions
+        embedding = []
+        for i in range(self.EMBEDDING_DIM):
+            # Use hash bytes cyclically, normalized to [-1, 1]
+            byte_val = text_hash[i % len(text_hash)]
+            normalized = (byte_val / 127.5) - 1.0
+            embedding.append(normalized)
+
+        return embedding
+
+
+class RealEmbeddingFunction:
+    """Real embedding function using Qwen3-VL-Embedding-8B.
+
+    Loaded on-demand when MOCK_MODELS=false.
+    """
+
+    EMBEDDING_DIM = 4096  # Qwen embedding dimension
+
+    def __init__(self):
+        self.model = None
+        self.tokenizer = None
+
+    def _load_model(self):
+        """Lazy load the embedding model."""
+        if self.model is not None:
+            return
+
+        import torch
+        from transformers import AutoModel, AutoTokenizer
+
+        model_name = "Qwen/Qwen3-VL-Embedding-8B"
+        print(f"Loading embedding model: {model_name}")
+
+        self.tokenizer = AutoTokenizer.from_pretrained(
+            model_name,
+            trust_remote_code=True,
+        )
+        self.model = AutoModel.from_pretrained(
+            model_name,
+            torch_dtype=torch.bfloat16,
+            device_map="auto",
+            trust_remote_code=True,
+        )
+        self.model.eval()
+
+    def __call__(self, input: list[str]) -> list[list[float]]:
+        """Generate embeddings for a list of texts."""
+        self._load_model()
+
+        import torch
+
+        embeddings = []
+        with torch.no_grad():
+            for text in input:
+                inputs = self.tokenizer(
+                    text,
+                    return_tensors="pt",
+                    truncation=True,
+                    max_length=512,
+                    padding=True,
+                )
+                inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
+
+                outputs = self.model(**inputs)
+                # Use mean pooling over sequence
+                embedding = outputs.last_hidden_state.mean(dim=1).squeeze()
+                embeddings.append(embedding.cpu().float().tolist())
+
+        return embeddings
+
+
+def get_embedding_function():
+    """Get appropriate embedding function based on settings."""
+    if settings.mock_models:
+        return MockEmbeddingFunction()
+    return RealEmbeddingFunction()
+
+
+class ChromaVectorStore:
+    """ChromaDB-based vector store for FDAM knowledge base."""
+
+    COLLECTION_NAME = "fdam_knowledge_base"
+
+    def __init__(
+        self,
+        persist_directory: Optional[str] = None,
+        embedding_function=None,
+    ):
+        """Initialize vector store.
+
+        Args:
+            persist_directory: Directory for ChromaDB persistence.
+                             If None, uses in-memory storage.
+            embedding_function: Custom embedding function.
+                              If None, uses appropriate default.
+        """
+        self.persist_directory = persist_directory
+
+        # Initialize ChromaDB client
+        if persist_directory:
+            persist_path = Path(persist_directory)
+            persist_path.mkdir(parents=True, exist_ok=True)
+            self.client = chromadb.PersistentClient(
+                path=str(persist_path),
+                settings=Settings(anonymized_telemetry=False),
+            )
+        else:
+            self.client = chromadb.Client(
+                settings=Settings(anonymized_telemetry=False),
+            )
+
+        # Set up embedding function
+        self.embedding_function = embedding_function or get_embedding_function()
+
+        # Get or create collection
+        self.collection = self.client.get_or_create_collection(
+            name=self.COLLECTION_NAME,
+            metadata={"hnsw:space": "cosine"},
+        )
+
+    def add_chunks(self, chunks: list[Chunk]) -> int:
+        """Add chunks to the vector store.
+
+        Args:
+            chunks: List of Chunk objects to add
+
+        Returns:
+            Number of chunks added
+        """
+        if not chunks:
+            return 0
+
+        ids = [chunk.id for chunk in chunks]
+        documents = [chunk.text for chunk in chunks]
+        metadatas = [chunk.to_metadata() for chunk in chunks]
+
+        # Generate embeddings
+        embeddings = self.embedding_function(documents)
+
+        # Add to collection
+        self.collection.add(
+            ids=ids,
+            embeddings=embeddings,
+            documents=documents,
+            metadatas=metadatas,
+        )
+
+        return len(chunks)
+
+    def query(
+        self,
+        query_text: str,
+        n_results: int = 5,
+        where: Optional[dict] = None,
+        where_document: Optional[dict] = None,
+    ) -> list[dict]:
+        """Query the vector store.
+
+        Args:
+            query_text: Query text to search for
+            n_results: Number of results to return
+            where: Metadata filter (e.g., {"priority": "primary"})
+            where_document: Document content filter
+
+        Returns:
+            List of result dicts with keys: id, document, metadata, distance
+        """
+        # Generate query embedding
+        query_embedding = self.embedding_function([query_text])[0]
+
+        # Query collection
+        results = self.collection.query(
+            query_embeddings=[query_embedding],
+            n_results=n_results,
+            where=where,
+            where_document=where_document,
+            include=["documents", "metadatas", "distances"],
+        )
+
+        # Format results
+        formatted = []
+        if results["ids"] and results["ids"][0]:
+            for i, chunk_id in enumerate(results["ids"][0]):
+                formatted.append(
+                    {
+                        "id": chunk_id,
+                        "document": results["documents"][0][i],
+                        "metadata": results["metadatas"][0][i],
+                        "distance": results["distances"][0][i],
+                    }
+                )
+
+        return formatted
+
+    def get_stats(self) -> dict:
+        """Get collection statistics."""
+        count = self.collection.count()
+
+        # Get category distribution
+        categories = {}
+        priorities = {}
+
+        if count > 0:
+            # Sample all documents to get metadata distribution
+            all_results = self.collection.get(include=["metadatas"])
+            for metadata in all_results["metadatas"]:
+                cat = metadata.get("category", "unknown")
+                pri = metadata.get("priority", "unknown")
+                categories[cat] = categories.get(cat, 0) + 1
+                priorities[pri] = priorities.get(pri, 0) + 1
+
+        return {
+            "total_chunks": count,
+            "categories": categories,
+            "priorities": priorities,
+            "collection_name": self.COLLECTION_NAME,
+            "persist_directory": self.persist_directory,
+        }
+
+    def clear(self):
+        """Clear all data from the collection."""
+        self.client.delete_collection(self.COLLECTION_NAME)
+        self.collection = self.client.get_or_create_collection(
+            name=self.COLLECTION_NAME,
+            metadata={"hnsw:space": "cosine"},
+        )
+
+    def delete_by_source(self, source: str) -> int:
+        """Delete all chunks from a specific source.
+
+        Args:
+            source: Source filename to delete
+
+        Returns:
+            Number of chunks deleted
+        """
+        # Get IDs of chunks from this source
+        results = self.collection.get(
+            where={"source": source},
+            include=[],
+        )
+
+        if results["ids"]:
+            self.collection.delete(ids=results["ids"])
+            return len(results["ids"])
+
+        return 0

requirements.txt

@@ -0,0 +1,31 @@
+# Core ML/AI
+torch
+transformers>=4.57.0
+accelerate
+qwen-vl-utils>=0.0.14
+torchvision
+
+# UI
+gradio
+
+# RAG/Vector Store
+chromadb
+
+# Data Validation
+pydantic
+pydantic-settings
+
+# Image Processing
+pillow
+
+# PDF Processing
+pdfplumber
+weasyprint>=60.0
+markdown>=3.5
+
+# Utilities
+numpy
+
+# Testing
+pytest
+pytest-asyncio

schemas/__init__.py

@@ -0,0 +1,109 @@
+"""FDAM AI Pipeline Pydantic schemas.
+
+Exports all input and output models for convenient imports.
+"""
+
+from .input import (
+    # Type definitions
+    FacilityClassification,
+    ConstructionEra,
+    ZoneType,
+    ConditionLevel,
+    MaterialType,
+    MaterialCategory,
+    Disposition,
+    OdorIntensity,
+    CharDensity,
+    SampleType,
+    Priority,
+    # Helper functions
+    get_material_category,
+    # Input models
+    ProjectInfo,
+    Dimensions,
+    Surface,
+    Room,
+    BoundingBox,
+    ImageAnnotation,
+    ImageMetadata,
+    QualitativeObservations,
+    AssessmentInput,
+)
+
+from .output import (
+    # Vision analysis
+    ZoneAnalysis,
+    ConditionAnalysis,
+    DetectedMaterial,
+    CombustionIndicators,
+    SamplingRecommendation,
+    VisionAnalysisResult,
+    # Calculations
+    RoomAreaSummary,
+    SurfaceAreas,
+    AirFiltration,
+    SampleDensity,
+    LaborEstimate,
+    EquipmentRequirements,
+    RegulatoryFlag,
+    RegulatoryFlags,
+    CalculationResults,
+    # Documents
+    GeneratedDocuments,
+    # Confidence
+    FlaggedItem,
+    ConfidenceReport,
+    # Final output
+    AssessmentOutput,
+)
+
+__all__ = [
+    # Type definitions
+    "FacilityClassification",
+    "ConstructionEra",
+    "ZoneType",
+    "ConditionLevel",
+    "MaterialType",
+    "MaterialCategory",
+    "Disposition",
+    "OdorIntensity",
+    "CharDensity",
+    "SampleType",
+    "Priority",
+    # Helper functions
+    "get_material_category",
+    # Input models
+    "ProjectInfo",
+    "Dimensions",
+    "Surface",
+    "Room",
+    "BoundingBox",
+    "ImageAnnotation",
+    "ImageMetadata",
+    "QualitativeObservations",
+    "AssessmentInput",
+    # Vision analysis
+    "ZoneAnalysis",
+    "ConditionAnalysis",
+    "DetectedMaterial",
+    "CombustionIndicators",
+    "SamplingRecommendation",
+    "VisionAnalysisResult",
+    # Calculations
+    "RoomAreaSummary",
+    "SurfaceAreas",
+    "AirFiltration",
+    "SampleDensity",
+    "LaborEstimate",
+    "EquipmentRequirements",
+    "RegulatoryFlag",
+    "RegulatoryFlags",
+    "CalculationResults",
+    # Documents
+    "GeneratedDocuments",
+    # Confidence
+    "FlaggedItem",
+    "ConfidenceReport",
+    # Final output
+    "AssessmentOutput",
+]

schemas/input.py

@@ -0,0 +1,255 @@
+"""Pydantic input models for FDAM AI Pipeline.
+
+Uses Literal unions instead of Enums per project code style.
+"""
+
+from datetime import date
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+# --- Type Definitions (Literal unions) ---
+
+FacilityClassification = Literal["operational", "non-operational", "public-childcare"]
+ConstructionEra = Literal["pre-1980", "1980-2000", "post-2000"]
+ZoneType = Literal["burn", "near-field", "far-field"]
+ConditionLevel = Literal["background", "light", "moderate", "heavy", "structural-damage"]
+
+# Material categories
+MaterialType = Literal[
+    # Non-porous
+    "steel",
+    "concrete",
+    "glass",
+    "metal",
+    "cmu",
+    # Semi-porous
+    "drywall-painted",
+    "drywall-unpainted",
+    "wood-sealed",
+    "wood-unsealed",
+    # Porous
+    "carpet",
+    "carpet-pad",
+    "insulation-fiberglass",
+    "insulation-other",
+    "acoustic-tile",
+    "upholstery",
+    # HVAC
+    "ductwork-rigid",
+    "ductwork-flexible",
+    "hvac-interior-insulation",
+]
+
+MaterialCategory = Literal["non-porous", "semi-porous", "porous", "hvac"]
+
+Disposition = Literal["no-action", "clean", "evaluate", "remove", "remove-repair"]
+
+OdorIntensity = Literal["none", "faint", "moderate", "strong"]
+CharDensity = Literal["sparse", "moderate", "dense"]
+SampleType = Literal["tape_lift", "surface_wipe", "both"]
+Priority = Literal["high", "medium", "low"]
+
+
+# --- Helper Functions ---
+
+def get_material_category(material: MaterialType) -> MaterialCategory:
+    """Get the category for a material type."""
+    non_porous = {"steel", "concrete", "glass", "metal", "cmu"}
+    semi_porous = {"drywall-painted", "drywall-unpainted", "wood-sealed", "wood-unsealed"}
+    porous = {"carpet", "carpet-pad", "insulation-fiberglass", "insulation-other", "acoustic-tile", "upholstery"}
+    hvac = {"ductwork-rigid", "ductwork-flexible", "hvac-interior-insulation"}
+
+    if material in non_porous:
+        return "non-porous"
+    elif material in semi_porous:
+        return "semi-porous"
+    elif material in porous:
+        return "porous"
+    elif material in hvac:
+        return "hvac"
+    else:
+        return "porous"  # Conservative default
+
+
+# --- Project Level ---
+
+class ProjectInfo(BaseModel):
+    """Project-level information."""
+
+    project_name: str = Field(..., min_length=1, description="Project or facility name")
+    address: str = Field(..., min_length=1, description="Full street address")
+    city: str = Field(..., min_length=1)
+    state: str = Field(..., min_length=2, max_length=2)
+    zip_code: str = Field(..., min_length=5)
+
+    client_name: str = Field(..., min_length=1)
+    client_contact: Optional[str] = None
+    client_email: Optional[str] = None
+    client_phone: Optional[str] = None
+
+    fire_date: date = Field(..., description="Date of fire incident")
+    assessment_date: date = Field(..., description="Date of assessment")
+
+    facility_classification: FacilityClassification
+    construction_era: ConstructionEra
+
+    assessor_name: str = Field(..., min_length=1, description="Industrial hygienist name")
+    assessor_credentials: Optional[str] = Field(None, description="CIH, CSP, etc.")
+
+
+# --- Room/Area Level ---
+
+class Dimensions(BaseModel):
+    """Room dimensions for calculations."""
+
+    length_ft: float = Field(..., gt=0, le=10000, description="Length in feet")
+    width_ft: float = Field(..., gt=0, le=10000, description="Width in feet")
+    ceiling_height_ft: float = Field(..., gt=0, le=500, description="Ceiling height in feet")
+
+    @property
+    def area_sf(self) -> float:
+        """Calculate floor area in square feet."""
+        return self.length_ft * self.width_ft
+
+    @property
+    def volume_cf(self) -> float:
+        """Calculate volume in cubic feet."""
+        return self.area_sf * self.ceiling_height_ft
+
+
+class Surface(BaseModel):
+    """Individual surface within a room."""
+
+    id: str = Field(..., min_length=1, description="Unique surface identifier")
+    material: MaterialType = Field(..., description="Material type")
+    description: str = Field(..., min_length=1, description="e.g., 'North wall drywall'")
+    area_sf: float = Field(..., gt=0, description="Surface area in square feet")
+
+    zone: Optional[ZoneType] = Field(None, description="Can be set by AI or user")
+    condition: Optional[ConditionLevel] = Field(None, description="Can be set by AI or user")
+    disposition: Optional[Disposition] = Field(None, description="Calculated by system")
+
+    ai_detected: bool = Field(False, description="Was this detected by AI from images?")
+    confidence: Optional[float] = Field(None, ge=0, le=1, description="AI confidence score")
+
+    @property
+    def category(self) -> MaterialCategory:
+        """Get the material category."""
+        return get_material_category(self.material)
+
+
+class Room(BaseModel):
+    """Room or area within the building."""
+
+    id: str = Field(..., min_length=1, description="Unique room identifier")
+    name: str = Field(..., min_length=1, description="e.g., 'Warehouse Bay A'")
+    floor: Optional[str] = Field(None, description="e.g., 'Ground Floor'")
+
+    dimensions: Dimensions
+
+    zone_classification: Optional[ZoneType] = Field(None, description="AI-determined or user override")
+    zone_confidence: Optional[float] = Field(None, ge=0, le=1)
+    zone_user_override: bool = Field(False)
+
+    surfaces: list[Surface] = Field(default_factory=list)
+    image_ids: list[str] = Field(default_factory=list, description="Associated image IDs")
+
+
+# --- Image Level ---
+
+class BoundingBox(BaseModel):
+    """Bounding box for detected elements in an image."""
+
+    x: float = Field(..., ge=0, le=1, description="X coordinate (normalized 0-1)")
+    y: float = Field(..., ge=0, le=1, description="Y coordinate (normalized 0-1)")
+    width: float = Field(..., gt=0, le=1, description="Width (normalized 0-1)")
+    height: float = Field(..., gt=0, le=1, description="Height (normalized 0-1)")
+
+
+class ImageAnnotation(BaseModel):
+    """Annotation for a detected element in an image."""
+
+    label: str
+    bounding_box: BoundingBox
+    confidence: Optional[float] = Field(None, ge=0, le=1)
+
+
+class ImageMetadata(BaseModel):
+    """Metadata for uploaded image."""
+
+    id: str = Field(..., min_length=1)
+    filename: str = Field(..., min_length=1)
+    room_id: str = Field(..., min_length=1, description="Associated room ID")
+    description: Optional[str] = Field(None, description="User description of image")
+
+    # AI-populated fields
+    detected_materials: list[MaterialType] = Field(default_factory=list)
+    detected_zone: Optional[ZoneType] = None
+    zone_confidence: Optional[float] = Field(None, ge=0, le=1)
+    detected_condition: Optional[ConditionLevel] = None
+    condition_confidence: Optional[float] = Field(None, ge=0, le=1)
+
+    # Bounding box annotations (for UI overlay)
+    annotations: list[ImageAnnotation] = Field(default_factory=list)
+
+    analysis_complete: bool = Field(False)
+
+
+# --- Qualitative Observations ---
+
+class QualitativeObservations(BaseModel):
+    """Qualitative observation checklist per FDAM 2.3."""
+
+    smoke_fire_odor: bool = Field(..., description="Smoke/fire odor present?")
+    odor_intensity: Optional[OdorIntensity] = None
+
+    visible_soot_deposits: bool = Field(..., description="Visible soot deposits?")
+    soot_pattern_description: Optional[str] = None
+
+    large_char_particles: bool = Field(..., description="Large char particles observed?")
+    char_density_estimate: Optional[CharDensity] = None
+
+    ash_like_residue: bool = Field(..., description="Ash-like residue present?")
+    ash_color_texture: Optional[str] = None
+
+    surface_discoloration: bool = Field(..., description="Surface discoloration?")
+    discoloration_description: Optional[str] = None
+
+    dust_loading_interference: bool = Field(..., description="Dust loading or interference?")
+    dust_notes: Optional[str] = None
+
+    wildfire_indicators: bool = Field(..., description="Burned soil/pollen/vegetation indicators?")
+    wildfire_notes: Optional[str] = None
+
+    additional_notes: Optional[str] = None
+
+
+# --- Complete Assessment Input ---
+
+class AssessmentInput(BaseModel):
+    """Complete input for FDAM AI assessment."""
+
+    project: ProjectInfo
+    rooms: list[Room] = Field(..., min_length=1)
+    images: list[ImageMetadata] = Field(default_factory=list, max_length=20)
+    observations: QualitativeObservations
+
+    @field_validator("rooms")
+    @classmethod
+    def validate_room_ids(cls, rooms: list[Room]) -> list[Room]:
+        """Ensure room IDs are unique."""
+        ids = [r.id for r in rooms]
+        if len(ids) != len(set(ids)):
+            raise ValueError("Room IDs must be unique")
+        return rooms
+
+    @model_validator(mode="after")
+    def validate_image_rooms(self) -> "AssessmentInput":
+        """Ensure all images reference valid room IDs."""
+        room_ids = {r.id for r in self.rooms}
+        for img in self.images:
+            if img.room_id not in room_ids:
+                raise ValueError(f"Image {img.id} references unknown room {img.room_id}")
+        return self

schemas/output.py

@@ -0,0 +1,238 @@
+"""Pydantic output models for FDAM AI Pipeline.
+
+Contains vision analysis results, calculation outputs, and final assessment output.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from .input import (
+    AssessmentInput,
+    BoundingBox,
+    ConditionLevel,
+    MaterialCategory,
+    MaterialType,
+    Priority,
+    SampleType,
+    ZoneType,
+)
+
+
+# --- Vision Analysis Output ---
+
+class ZoneAnalysis(BaseModel):
+    """Zone classification from vision analysis."""
+
+    classification: ZoneType
+    confidence: float = Field(..., ge=0, le=1)
+    reasoning: str
+
+
+class ConditionAnalysis(BaseModel):
+    """Condition assessment from vision analysis."""
+
+    level: ConditionLevel
+    confidence: float = Field(..., ge=0, le=1)
+    reasoning: str
+
+
+class DetectedMaterial(BaseModel):
+    """Material detected in image by vision model."""
+
+    type: MaterialType
+    category: MaterialCategory
+    confidence: float = Field(..., ge=0, le=1)
+    location_description: Optional[str] = None
+    bounding_box: Optional[BoundingBox] = None
+
+
+class CombustionIndicators(BaseModel):
+    """Combustion particle indicators from vision analysis."""
+
+    soot_visible: bool = False
+    soot_pattern: Optional[str] = None
+    char_visible: bool = False
+    char_description: Optional[str] = None
+    ash_visible: bool = False
+    ash_description: Optional[str] = None
+
+
+class SamplingRecommendation(BaseModel):
+    """Recommended sampling location from vision analysis."""
+
+    description: str
+    sample_type: SampleType
+    priority: Priority
+
+
+class VisionAnalysisResult(BaseModel):
+    """Complete vision analysis result for a single image.
+
+    Matches the VISION_OUTPUT_SCHEMA from the technical spec.
+    """
+
+    zone: ZoneAnalysis
+    condition: ConditionAnalysis
+    materials: list[DetectedMaterial] = Field(default_factory=list)
+    combustion_indicators: CombustionIndicators
+    structural_concerns: list[str] = Field(default_factory=list)
+    access_issues: list[str] = Field(default_factory=list)
+    recommended_sampling_locations: list[SamplingRecommendation] = Field(default_factory=list)
+    flags_for_review: list[str] = Field(default_factory=list)
+
+
+# --- Calculation Results ---
+
+class RoomAreaSummary(BaseModel):
+    """Area summary for a single room."""
+
+    floor_area: float
+    surface_area: float
+    volume: float
+
+
+class SurfaceAreas(BaseModel):
+    """Surface area calculations by various groupings."""
+
+    by_type: dict[str, float] = Field(default_factory=dict)
+    by_disposition: dict[str, float] = Field(default_factory=dict)
+    by_zone: dict[str, float] = Field(default_factory=dict)
+    by_room: dict[str, RoomAreaSummary] = Field(default_factory=dict)
+    total_floor_sf: float = 0
+    total_surface_sf: float = 0
+    total_volume_cf: float = 0
+
+
+class AirFiltration(BaseModel):
+    """Air filtration calculation results per NADCA ACR 2021."""
+
+    total_volume_cf: float
+    required_ach: int = 4
+    unit_cfm: int = 2000
+    units_required: int
+    calculation: str
+    standard_reference: str = "NADCA ACR 2021, Section 3.6"
+
+
+class SampleDensity(BaseModel):
+    """Sample density recommendations per FDAM 2.3."""
+
+    total_sf: float
+    size_category: str
+    surface_types_count: int
+    surface_types: list[str] = Field(default_factory=list)
+    tape_lifts_per_type: str
+    surface_wipes_per_type: str
+    recommended_tape_lifts: int
+    recommended_surface_wipes: int
+    ceiling_deck_note: Optional[str] = None
+    control_samples_recommended: bool = True
+    control_sample_note: str = "Control samples from unaffected areas recommended for baseline comparison"
+
+
+class LaborEstimate(BaseModel):
+    """Labor hour estimates by task."""
+
+    hepa_vacuum: float = 0
+    wet_wipe: float = 0
+    dry_sponge: float = 0
+    power_wash: float = 0
+    scrubber: float = 0
+    removal: float = 0
+    hvac_cleaning: float = 0
+    total_hours: float = 0
+
+
+class EquipmentRequirements(BaseModel):
+    """Equipment requirements for the project."""
+
+    air_scrubbers: int = 0
+    hepa_vacuums: int = 0
+    negative_air_machines: int = 0
+    dehumidifiers: int = 0
+    notes: list[str] = Field(default_factory=list)
+
+
+class RegulatoryFlag(BaseModel):
+    """Regulatory flag for potential hazards."""
+
+    flag_type: str
+    description: str
+    recommendation: str
+    reference: str
+
+
+class RegulatoryFlags(BaseModel):
+    """Regulatory flags based on construction era and facility type."""
+
+    lead_paint_flag: Optional[RegulatoryFlag] = None
+    acm_flag: Optional[RegulatoryFlag] = None
+    other_flags: list[RegulatoryFlag] = Field(default_factory=list)
+
+
+class CalculationResults(BaseModel):
+    """All calculation results from FDAM logic engine."""
+
+    surface_areas: SurfaceAreas
+    air_filtration: AirFiltration
+    sample_density: SampleDensity
+    labor_estimate: LaborEstimate
+    equipment: EquipmentRequirements
+    regulatory_flags: RegulatoryFlags
+
+
+# --- Document Output ---
+
+class GeneratedDocuments(BaseModel):
+    """Generated document outputs."""
+
+    cleaning_specification_md: str = Field(..., description="Cleaning Specification / SOW in Markdown")
+    sampling_plan_md: Optional[str] = Field(None, description="Sampling plan recommendations in Markdown")
+    confidence_report_md: Optional[str] = Field(None, description="Confidence report in Markdown")
+
+
+# --- Confidence Report ---
+
+class FlaggedItem(BaseModel):
+    """Item flagged for professional review."""
+
+    type: str
+    room: Optional[str] = None
+    surface: Optional[str] = None
+    image_id: Optional[str] = None
+    confidence: Optional[float] = None
+    recommendation: str
+
+
+class ConfidenceReport(BaseModel):
+    """Confidence report for assessment."""
+
+    flagged_items: list[FlaggedItem] = Field(default_factory=list)
+    overall_confidence: float = Field(..., ge=0, le=1)
+    review_required: bool = False
+
+
+# --- Complete Assessment Output ---
+
+class AssessmentOutput(BaseModel):
+    """Complete output from FDAM AI assessment pipeline."""
+
+    # Original input (with AI-enriched fields)
+    input: AssessmentInput
+
+    # Vision analysis results (by image ID)
+    vision_results: dict[str, VisionAnalysisResult] = Field(default_factory=dict)
+
+    # Calculation results
+    calculations: CalculationResults
+
+    # Generated documents
+    documents: GeneratedDocuments
+
+    # Confidence report
+    confidence_report: ConfidenceReport
+
+    # Processing metadata
+    processing_time_seconds: Optional[float] = None
+    model_versions: dict[str, str] = Field(default_factory=dict)

tests/test_pdf_generator.py

@@ -0,0 +1,246 @@
+"""Tests for PDF generation module."""
+
+import pytest
+import tempfile
+from pathlib import Path
+
+from pipeline.pdf_generator import PDFGenerator, PDFResult, generate_sow_pdf, SOW_CSS
+
+
+class TestPDFGenerator:
+    """Test PDF generator functionality."""
+
+    @pytest.fixture
+    def generator(self):
+        """Create PDF generator instance."""
+        return PDFGenerator()
+
+    @pytest.fixture
+    def sample_markdown(self):
+        """Sample markdown for testing."""
+        return """# Test Document
+
+## Section One
+
+This is a test paragraph with **bold** and *italic* text.
+
+| Column A | Column B |
+|----------|----------|
+| Value 1  | Value 2  |
+| Value 3  | Value 4  |
+
+## Section Two
+
+- Bullet point one
+- Bullet point two
+- Bullet point three
+
+---
+
+*Generated by test*
+"""
+
+    def test_weasyprint_available(self, generator):
+        """Test that WeasyPrint is detected as available."""
+        assert generator.weasyprint_available is True
+
+    def test_markdown_to_html(self, generator, sample_markdown):
+        """Test markdown to HTML conversion."""
+        html = generator.markdown_to_html(sample_markdown)
+
+        assert "<!DOCTYPE html>" in html
+        assert "<html>" in html
+        assert "<style>" in html
+        # Note: markdown library adds id attribute to headers (from TOC extension)
+        assert "<h1" in html and "Test Document</h1>" in html
+        assert "<table>" in html
+        assert "<strong>bold</strong>" in html
+
+    def test_markdown_to_html_includes_css(self, generator, sample_markdown):
+        """Test that HTML includes CSS styling."""
+        html = generator.markdown_to_html(sample_markdown)
+
+        # Check key CSS rules are included
+        assert "font-family" in html
+        assert "border-collapse" in html
+        assert "@page" in html
+
+    def test_generate_pdf_success(self, generator, sample_markdown):
+        """Test successful PDF generation."""
+        result = generator.generate_pdf(sample_markdown)
+
+        assert isinstance(result, PDFResult)
+        assert result.success is True
+        assert result.pdf_path is not None
+        assert result.error_message is None
+        assert result.file_size_bytes > 0
+
+        # Verify file exists
+        pdf_path = Path(result.pdf_path)
+        assert pdf_path.exists()
+        assert pdf_path.suffix == ".pdf"
+
+        # Clean up
+        pdf_path.unlink()
+
+    def test_generate_pdf_with_custom_path(self, generator, sample_markdown):
+        """Test PDF generation with custom output path."""
+        with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as f:
+            output_path = f.name
+
+        result = generator.generate_pdf(sample_markdown, output_path=output_path)
+
+        assert result.success is True
+        assert result.pdf_path == output_path
+
+        # Clean up
+        Path(output_path).unlink()
+
+    def test_generate_pdf_empty_content(self, generator):
+        """Test PDF generation with empty content."""
+        result = generator.generate_pdf("")
+
+        # Should still succeed with empty content
+        assert result.success is True
+        assert result.pdf_path is not None
+
+        # Clean up
+        Path(result.pdf_path).unlink()
+
+    def test_generate_pdf_complex_tables(self, generator):
+        """Test PDF with complex table content."""
+        markdown = """# Thresholds
+
+| Metal | Non-Operational | Operational | Unit |
+|-------|-----------------|-------------|------|
+| Lead | 22 | 500 | µg/100cm² |
+| Cadmium | 3.3 | 50 | µg/100cm² |
+| Arsenic | 6.7 | 100 | µg/100cm² |
+
+## Notes
+
+Special characters: µ, °, ², ™
+"""
+        result = generator.generate_pdf(markdown)
+
+        assert result.success is True
+        assert result.file_size_bytes > 0
+
+        # Clean up
+        Path(result.pdf_path).unlink()
+
+    def test_generate_html_fallback(self, generator, sample_markdown):
+        """Test HTML generation as fallback."""
+        success, html_path, error = generator.generate_html(sample_markdown)
+
+        assert success is True
+        assert html_path is not None
+        assert error is None
+
+        # Verify file exists and contains HTML
+        html_path = Path(html_path)
+        assert html_path.exists()
+        content = html_path.read_text()
+        assert "<html>" in content
+
+        # Clean up
+        html_path.unlink()
+
+    def test_custom_css(self):
+        """Test PDF generator with custom CSS."""
+        custom_css = """
+        body { font-family: monospace; }
+        h1 { color: red; }
+        """
+        generator = PDFGenerator(custom_css=custom_css)
+
+        html = generator.markdown_to_html("# Test")
+        assert "font-family: monospace" in html
+        assert "color: red" in html
+
+
+class TestGenerateSowPdf:
+    """Test the convenience function."""
+
+    def test_generate_sow_pdf(self):
+        """Test generate_sow_pdf convenience function."""
+        markdown = """# Scope of Work
+
+## Project: Test Fire
+
+| Field | Value |
+|-------|-------|
+| Client | ACME Corp |
+| Date | 2024-01-15 |
+
+## Recommendations
+
+- Clean all surfaces
+- HEPA vacuum required
+"""
+        result = generate_sow_pdf(
+            markdown_content=markdown,
+            project_name="Test Fire",
+        )
+
+        assert result.success is True
+        assert result.pdf_path is not None
+
+        # Clean up
+        Path(result.pdf_path).unlink()
+
+
+class TestSOWCSS:
+    """Test CSS styling constants."""
+
+    def test_sow_css_exists(self):
+        """Test that SOW_CSS is defined."""
+        assert SOW_CSS is not None
+        assert len(SOW_CSS) > 0
+
+    def test_sow_css_has_page_settings(self):
+        """Test that CSS includes page settings."""
+        assert "@page" in SOW_CSS
+        assert "margin" in SOW_CSS
+
+    def test_sow_css_has_table_styling(self):
+        """Test that CSS includes table styling."""
+        assert "table" in SOW_CSS
+        assert "border-collapse" in SOW_CSS
+        assert "th" in SOW_CSS
+        assert "td" in SOW_CSS
+
+    def test_sow_css_has_header_styling(self):
+        """Test that CSS includes header styling."""
+        assert "h1" in SOW_CSS
+        assert "h2" in SOW_CSS
+
+
+class TestPDFResultDataclass:
+    """Test PDFResult dataclass."""
+
+    def test_pdf_result_success(self):
+        """Test PDFResult with success."""
+        result = PDFResult(
+            success=True,
+            pdf_path="/tmp/test.pdf",
+            file_size_bytes=1000,
+        )
+
+        assert result.success is True
+        assert result.pdf_path == "/tmp/test.pdf"
+        assert result.error_message is None
+        assert result.file_size_bytes == 1000
+
+    def test_pdf_result_failure(self):
+        """Test PDFResult with failure."""
+        result = PDFResult(
+            success=False,
+            pdf_path=None,
+            error_message="Something went wrong",
+        )
+
+        assert result.success is False
+        assert result.pdf_path is None
+        assert result.error_message == "Something went wrong"
+        assert result.file_size_bytes == 0

tests/test_pipeline.py

@@ -0,0 +1,525 @@
+"""Tests for FDAM Pipeline components."""
+
+import pytest
+from PIL import Image
+import io
+
+from pipeline.calculations import (
+    FDAMCalculator,
+    AirFiltrationResult,
+    SampleDensityResult,
+    RegulatoryFlags,
+    MetalsThresholds,
+    METALS_THRESHOLDS,
+    PARTICULATE_THRESHOLDS,
+)
+from pipeline.dispositions import (
+    DispositionEngine,
+    DispositionResult,
+    SurfaceDisposition,
+    DISPOSITION_MATRIX,
+    CLEANING_PROTOCOLS,
+)
+from pipeline.generator import DocumentGenerator, GeneratedDocument
+from pipeline.main import FDAMPipeline, PipelineResult, PipelineProgress
+
+from ui.state import SessionState, RoomFormData, ImageFormData
+from ui.components import image_store
+
+
+class TestFDAMCalculator:
+    """Test FDAM calculations."""
+
+    @pytest.fixture
+    def calculator(self):
+        return FDAMCalculator()
+
+    def test_air_filtration_basic(self, calculator):
+        """Test basic air filtration calculation."""
+        result = calculator.calculate_air_filtration(
+            total_area_sf=10000,
+            avg_ceiling_height_ft=10,
+        )
+
+        assert isinstance(result, AirFiltrationResult)
+        assert result.total_volume_cf == 100000
+        assert result.required_ach == 4
+        assert result.unit_cfm == 2000
+        # (100000 * 4) / (2000 * 60) = 3.33 -> 4 units
+        assert result.units_required == 4
+
+    def test_air_filtration_large_space(self, calculator):
+        """Test air filtration for large space."""
+        result = calculator.calculate_air_filtration(
+            total_area_sf=50000,
+            avg_ceiling_height_ft=30,
+        )
+
+        # 1,500,000 CF * 4 ACH / (2000 * 60) = 50 units
+        assert result.units_required == 50
+        assert result.total_volume_cf == 1500000
+
+    def test_air_filtration_minimum_one_unit(self, calculator):
+        """Test minimum 1 unit is required."""
+        result = calculator.calculate_air_filtration(
+            total_area_sf=100,
+            avg_ceiling_height_ft=8,
+        )
+
+        assert result.units_required >= 1
+
+    def test_sample_density_small_area(self, calculator):
+        """Test sample density for small area."""
+        result = calculator.calculate_sample_density(
+            total_area_sf=3000,
+            surface_types_count=3,
+        )
+
+        assert isinstance(result, SampleDensityResult)
+        assert result.tape_lifts_min == 9  # 3 * 3
+        assert result.tape_lifts_max == 15  # 5 * 3
+
+    def test_sample_density_medium_area(self, calculator):
+        """Test sample density for medium area."""
+        result = calculator.calculate_sample_density(
+            total_area_sf=15000,
+            surface_types_count=3,
+        )
+
+        assert result.tape_lifts_min == 15  # 5 * 3
+        assert result.tape_lifts_max == 30  # 10 * 3
+
+    def test_sample_density_ceiling_deck(self, calculator):
+        """Test ceiling deck enhanced sampling."""
+        result = calculator.calculate_sample_density(
+            total_area_sf=10000,
+            has_ceiling_deck=True,
+        )
+
+        # 1 per 2,500 SF = 4 samples
+        assert result.ceiling_deck_samples == 4
+
+    def test_regulatory_flags_pre_1980(self, calculator):
+        """Test regulatory flags for pre-1980 construction."""
+        flags = calculator.get_regulatory_flags(
+            construction_era="pre-1980",
+            facility_classification="non-operational",
+        )
+
+        assert isinstance(flags, RegulatoryFlags)
+        assert flags.lbp_survey_required is True
+        assert flags.acm_survey_required is True
+        assert flags.acm_survey_recommended is False
+
+    def test_regulatory_flags_1980_2000(self, calculator):
+        """Test regulatory flags for 1980-2000 construction."""
+        flags = calculator.get_regulatory_flags(
+            construction_era="1980-2000",
+            facility_classification="operational",
+        )
+
+        assert flags.lbp_survey_required is False
+        assert flags.acm_survey_required is False
+        assert flags.acm_survey_recommended is True
+
+    def test_regulatory_flags_childcare(self, calculator):
+        """Test regulatory flags for public/childcare."""
+        flags = calculator.get_regulatory_flags(
+            construction_era="post-2000",
+            facility_classification="public-childcare",
+        )
+
+        assert flags.enhanced_childcare_thresholds is True
+
+    def test_metals_thresholds_non_operational(self, calculator):
+        """Test metals thresholds for non-operational facility."""
+        thresholds = calculator.get_metals_thresholds("non-operational")
+
+        assert isinstance(thresholds, MetalsThresholds)
+        assert thresholds.lead_ug_100cm2 == 22.0
+        assert thresholds.cadmium_ug_100cm2 == 3.3
+        assert thresholds.arsenic_ug_100cm2 == 6.7
+
+    def test_metals_thresholds_operational(self, calculator):
+        """Test metals thresholds for operational facility."""
+        thresholds = calculator.get_metals_thresholds("operational")
+
+        assert thresholds.lead_ug_100cm2 == 500.0
+        assert thresholds.cadmium_ug_100cm2 == 50.0
+
+    def test_metals_thresholds_childcare(self, calculator):
+        """Test metals thresholds for childcare facility."""
+        thresholds = calculator.get_metals_thresholds("public-childcare")
+
+        # EPA/HUD October 2024 for floors
+        assert thresholds.lead_ug_100cm2 == 4.3
+
+    def test_particulate_thresholds_exist(self):
+        """Test particulate thresholds are defined."""
+        assert "ash_char" in PARTICULATE_THRESHOLDS
+        assert "aciniform_soot" in PARTICULATE_THRESHOLDS
+        assert PARTICULATE_THRESHOLDS["ash_char"]["clearance"] == 150
+        assert PARTICULATE_THRESHOLDS["aciniform_soot"]["clearance"] == 500
+
+
+class TestDispositionEngine:
+    """Test disposition determination."""
+
+    @pytest.fixture
+    def engine(self):
+        return DispositionEngine()
+
+    def test_disposition_background(self, engine):
+        """Test disposition for background condition."""
+        result = engine.determine_disposition(
+            zone="far-field",
+            condition="background",
+            use_rag=False,
+        )
+
+        assert isinstance(result, DispositionResult)
+        assert result.disposition == "no-action"
+        assert result.confidence == 1.0
+
+    def test_disposition_structural_damage(self, engine):
+        """Test disposition for structural damage."""
+        result = engine.determine_disposition(
+            zone="burn-zone",
+            condition="structural-damage",
+            use_rag=False,
+        )
+
+        assert result.disposition == "remove-repair"
+        assert result.confidence == 1.0
+
+    def test_disposition_far_field_light(self, engine):
+        """Test disposition for far-field light condition."""
+        result = engine.determine_disposition(
+            zone="far-field",
+            condition="light",
+            use_rag=False,
+        )
+
+        assert result.disposition == "clean"
+        assert "standard" in result.protocol.lower()
+
+    def test_disposition_near_field_heavy(self, engine):
+        """Test disposition for near-field heavy condition."""
+        result = engine.determine_disposition(
+            zone="near-field",
+            condition="heavy",
+            use_rag=False,
+        )
+
+        assert result.disposition == "clean"
+        assert "aggressive" in result.protocol.lower()
+
+    def test_cleaning_method_drywall(self, engine):
+        """Test cleaning method for drywall."""
+        method = engine.get_cleaning_method(
+            surface_type="drywall",
+            condition="moderate",
+            use_rag=False,
+        )
+
+        assert "HEPA" in method["method"]
+        assert method["surface_type"] == "drywall"
+
+    def test_cleaning_method_concrete(self, engine):
+        """Test cleaning method for concrete."""
+        method = engine.get_cleaning_method(
+            surface_type="concrete-floor",
+            condition="heavy",
+            use_rag=False,
+        )
+
+        assert "scrubber" in method["method"].lower()
+        assert "multiple passes" in method["method"].lower()
+
+    def test_disposition_matrix_completeness(self):
+        """Test disposition matrix covers expected combinations."""
+        # Key combinations should be in matrix
+        assert ("far-field", "light") in DISPOSITION_MATRIX
+        assert ("near-field", "moderate") in DISPOSITION_MATRIX
+        assert ("burn-zone", "heavy") in DISPOSITION_MATRIX
+        assert ("any", "background") in DISPOSITION_MATRIX
+        assert ("any", "structural-damage") in DISPOSITION_MATRIX
+
+    def test_cleaning_protocols_exist(self):
+        """Test cleaning protocols are defined."""
+        assert "standard" in CLEANING_PROTOCOLS
+        assert "full" in CLEANING_PROTOCOLS
+        assert "aggressive" in CLEANING_PROTOCOLS
+
+        for protocol in CLEANING_PROTOCOLS.values():
+            assert "name" in protocol
+            assert "steps" in protocol
+            assert len(protocol["steps"]) > 0
+
+
+class TestDocumentGenerator:
+    """Test document generation."""
+
+    @pytest.fixture
+    def generator(self):
+        return DocumentGenerator()
+
+    @pytest.fixture
+    def sample_session(self):
+        session = SessionState()
+        session.project.project_name = "Test Fire Project"
+        session.project.address = "123 Main St"
+        session.project.city = "Springfield"
+        session.project.state = "IL"
+        session.project.zip_code = "62701"
+        session.project.client_name = "Test Client"
+        session.project.fire_date = "2024-01-01"
+        session.project.assessment_date = "2024-01-15"
+        session.project.facility_classification = "non-operational"
+        session.project.construction_era = "pre-1980"
+        session.project.assessor_name = "John Doe"
+        session.project.assessor_credentials = "CIH"
+
+        session.rooms.append(
+            RoomFormData(
+                id="room-001",
+                name="Main Hall",
+                length_ft=50,
+                width_ft=30,
+                ceiling_height_ft=12,
+            )
+        )
+        return session
+
+    @pytest.fixture
+    def sample_calculations(self):
+        calc = FDAMCalculator()
+        return {
+            "total_area_sf": 1500,
+            "total_volume_cf": 18000,
+            "avg_ceiling_height_ft": 12,
+            "air_filtration": calc.calculate_air_filtration(1500, 12),
+            "sample_density": calc.calculate_sample_density(1500),
+            "regulatory_flags": calc.get_regulatory_flags("pre-1980", "non-operational"),
+            "metals_thresholds": calc.get_metals_thresholds("non-operational"),
+            "particulate_thresholds": PARTICULATE_THRESHOLDS,
+        }
+
+    def test_generate_sow_basic(self, generator, sample_session, sample_calculations):
+        """Test basic SOW generation."""
+        doc = generator.generate_sow(
+            session=sample_session,
+            vision_results={},
+            surface_dispositions=[],
+            calculations=sample_calculations,
+        )
+
+        assert isinstance(doc, GeneratedDocument)
+        assert "Test Fire Project" in doc.markdown
+        assert "Cleaning Specification" in doc.markdown
+        assert doc.word_count > 0
+
+    def test_generate_sow_sections(self, generator, sample_session, sample_calculations):
+        """Test SOW contains required sections."""
+        doc = generator.generate_sow(
+            session=sample_session,
+            vision_results={},
+            surface_dispositions=[],
+            calculations=sample_calculations,
+        )
+
+        # Check for key sections
+        assert "## Project Information" in doc.markdown
+        assert "## Scope Summary" in doc.markdown
+        assert "## Room Inventory" in doc.markdown
+        assert "## Air Filtration Requirements" in doc.markdown
+        assert "## Regulatory Requirements" in doc.markdown
+        assert "## Clearance Thresholds" in doc.markdown
+
+    def test_generate_sow_with_dispositions(self, generator, sample_session, sample_calculations):
+        """Test SOW generation with dispositions."""
+        dispositions = [
+            SurfaceDisposition(
+                surface_type="drywall",
+                room_name="Main Hall",
+                zone="near-field",
+                condition="moderate",
+                disposition="clean",
+                cleaning_method="HEPA vacuum → Wet wipe",
+            )
+        ]
+
+        doc = generator.generate_sow(
+            session=sample_session,
+            vision_results={},
+            surface_dispositions=dispositions,
+            calculations=sample_calculations,
+        )
+
+        assert "drywall" in doc.markdown.lower()
+        assert "CLEAN" in doc.markdown
+
+
+class TestFDAMPipeline:
+    """Test full pipeline execution."""
+
+    @pytest.fixture
+    def pipeline(self):
+        return FDAMPipeline()
+
+    @pytest.fixture
+    def valid_session(self):
+        """Create a valid session for pipeline testing."""
+        session = SessionState()
+        session.project.project_name = "Pipeline Test"
+        session.project.address = "456 Oak Ave"
+        session.project.city = "Chicago"
+        session.project.state = "IL"
+        session.project.zip_code = "60601"
+        session.project.client_name = "Test Corp"
+        session.project.fire_date = "2024-06-01"
+        session.project.assessment_date = "2024-06-15"
+        session.project.facility_classification = "operational"
+        session.project.construction_era = "post-2000"
+        session.project.assessor_name = "Jane Smith"
+
+        session.rooms.append(
+            RoomFormData(
+                id="room-001",
+                name="Office A",
+                length_ft=20,
+                width_ft=15,
+                ceiling_height_ft=10,
+            )
+        )
+
+        # Add image metadata
+        img_id = "test-img-001"
+        session.images.append(
+            ImageFormData(
+                id=img_id,
+                filename="test.jpg",
+                room_id="room-001",
+            )
+        )
+
+        # Store actual image bytes
+        test_image = Image.new("RGB", (100, 100), color="red")
+        img_bytes = io.BytesIO()
+        test_image.save(img_bytes, format="PNG")
+        image_store.store(img_id, img_bytes.getvalue())
+
+        yield session
+
+        # Cleanup
+        image_store.clear()
+
+    def test_pipeline_execute_success(self, pipeline, valid_session):
+        """Test successful pipeline execution."""
+        progress_updates = []
+
+        def progress_callback(prog):
+            progress_updates.append(prog)
+
+        result = pipeline.execute(
+            session=valid_session,
+            progress_callback=progress_callback,
+        )
+
+        assert isinstance(result, PipelineResult)
+        assert result.success is True
+        assert result.document is not None
+        assert len(result.annotated_images) > 0
+        assert result.execution_time_seconds > 0
+        assert len(progress_updates) > 0
+
+    def test_pipeline_execute_missing_project_name(self, pipeline):
+        """Test pipeline fails with missing project name."""
+        session = SessionState()
+        # No project name set
+
+        result = pipeline.execute(session=session)
+
+        assert result.success is False
+        assert len(result.errors) > 0
+        assert any("project" in e.lower() for e in result.errors)
+
+    def test_pipeline_execute_missing_images(self, pipeline):
+        """Test pipeline fails with missing image bytes."""
+        session = SessionState()
+        session.project.project_name = "Test"
+        session.project.address = "123 Main"
+        session.project.city = "City"
+        session.project.state = "ST"
+        session.project.zip_code = "12345"
+        session.project.client_name = "Client"
+        session.project.fire_date = "2024-01-01"
+        session.project.assessment_date = "2024-01-02"
+        session.project.assessor_name = "Assessor"
+
+        session.rooms.append(
+            RoomFormData(id="r1", name="Room", length_ft=10, width_ft=10, ceiling_height_ft=10)
+        )
+        session.images.append(
+            ImageFormData(id="missing-img", filename="missing.jpg", room_id="r1")
+        )
+        # Don't store image bytes
+
+        result = pipeline.execute(session=session)
+
+        assert result.success is False
+        assert any("image" in e.lower() or "upload" in e.lower() for e in result.errors)
+
+    def test_pipeline_generates_stats(self, pipeline, valid_session):
+        """Test pipeline generates stats dictionary."""
+        result = pipeline.execute(session=valid_session)
+
+        stats = pipeline.generate_stats_dict(result)
+
+        assert "project_name" in stats
+        assert "total_rooms" in stats
+        assert "air_scrubbers_required" in stats
+        assert "execution_time" in stats
+
+    def test_pipeline_progress_stages(self, pipeline, valid_session):
+        """Test pipeline reports all 6 stages."""
+        stages_seen = set()
+
+        def progress_callback(prog):
+            stages_seen.add(prog.stage)
+
+        pipeline.execute(
+            session=valid_session,
+            progress_callback=progress_callback,
+        )
+
+        # Should see stages 1-6
+        assert len(stages_seen) >= 5  # At least most stages
+
+
+class TestIntegration:
+    """Integration tests for pipeline with RAG."""
+
+    def test_calculator_with_session(self):
+        """Test calculator with real session data."""
+        session = SessionState()
+        session.project.facility_classification = "non-operational"
+        session.project.construction_era = "pre-1980"
+        session.rooms.append(
+            RoomFormData(
+                id="r1",
+                name="Room 1",
+                length_ft=100,
+                width_ft=50,
+                ceiling_height_ft=15,
+            )
+        )
+
+        calc = FDAMCalculator()
+        results = calc.calculate_from_session(session)
+
+        assert results["total_area_sf"] == 5000
+        assert results["total_volume_cf"] == 75000
+        assert results["air_filtration"].units_required > 0
+        assert results["regulatory_flags"].lbp_survey_required is True
+        assert results["metals_thresholds"].lead_ug_100cm2 == 22.0

tests/test_rag.py

@@ -0,0 +1,536 @@
+"""Tests for RAG (Retrieval Augmented Generation) components."""
+
+import pytest
+from pathlib import Path
+import tempfile
+import shutil
+
+from rag.chunker import SemanticChunker, Chunk, chunk_file
+from rag.vectorstore import ChromaVectorStore, MockEmbeddingFunction
+from rag.retriever import FDAMRetriever, MockReranker, RetrievalResult
+
+
+class TestSemanticChunker:
+    """Test semantic chunker with table preservation."""
+
+    def test_chunk_simple_document(self):
+        """Test chunking a simple markdown document."""
+        text = """## Introduction
+
+This is the introduction paragraph with some content.
+
+## Section One
+
+This section contains important information about the topic.
+It has multiple sentences to form a proper paragraph.
+
+## Section Two
+
+Another section with different content here.
+"""
+        chunker = SemanticChunker()
+        chunks = chunker.chunk_document(
+            text=text,
+            source="test.md",
+            category="methodology",
+            priority="primary",
+        )
+
+        assert len(chunks) >= 1
+        assert all(isinstance(c, Chunk) for c in chunks)
+        assert all(c.source == "test.md" for c in chunks)
+        assert all(c.category == "methodology" for c in chunks)
+        assert all(c.priority == "primary" for c in chunks)
+
+    def test_preserve_tables(self):
+        """Test that tables are kept intact and not split."""
+        text = """## Thresholds
+
+| Material | Threshold | Unit |
+|----------|-----------|------|
+| Lead | 22 | µg/100cm² |
+| Cadmium | 3.3 | µg/100cm² |
+| Arsenic | 6.7 | µg/100cm² |
+
+## Next Section
+
+Some content after the table.
+"""
+        chunker = SemanticChunker()
+        chunks = chunker.chunk_document(
+            text=text,
+            source="thresholds.md",
+            category="thresholds",
+            priority="reference-threshold",
+        )
+
+        # Find the table chunk
+        table_chunks = [c for c in chunks if c.content_type == "table"]
+        assert len(table_chunks) >= 1
+
+        # Table should be complete
+        table_chunk = table_chunks[0]
+        assert "Lead" in table_chunk.text
+        assert "Cadmium" in table_chunk.text
+        assert "Arsenic" in table_chunk.text
+        assert "|" in table_chunk.text
+
+    def test_extract_keywords(self):
+        """Test keyword extraction from text."""
+        text = """## Zone Classification
+
+The burn zone shows heavy soot deposits and structural damage.
+Lead contamination requires HEPA vacuum cleaning per OSHA standards.
+"""
+        chunker = SemanticChunker()
+        chunks = chunker.chunk_document(
+            text=text,
+            source="zones.md",
+            category="methodology",
+            priority="primary",
+        )
+
+        # Should extract relevant keywords
+        all_keywords = []
+        for chunk in chunks:
+            all_keywords.extend(chunk.keywords)
+
+        # Check for expected domain keywords
+        keyword_set = set(all_keywords)
+        assert "burn zone" in keyword_set or "heavy" in keyword_set
+        assert "soot" in keyword_set or "structural damage" in keyword_set
+
+    def test_chunk_metadata(self):
+        """Test chunk metadata conversion."""
+        chunk = Chunk(
+            id="test_001",
+            text="Test content",
+            source="test.md",
+            category="methodology",
+            section="## Section 1",
+            priority="primary",
+            content_type="narrative",
+            keywords=["lead", "soot"],
+        )
+
+        metadata = chunk.to_metadata()
+
+        assert metadata["source"] == "test.md"
+        assert metadata["category"] == "methodology"
+        assert metadata["priority"] == "primary"
+        assert metadata["content_type"] == "narrative"
+        assert "lead" in metadata["keywords"]
+        assert "soot" in metadata["keywords"]
+
+    def test_split_by_headers(self):
+        """Test section splitting by markdown headers."""
+        text = """## Section One
+
+Content one.
+
+### Subsection A
+
+Content A.
+
+## Section Two
+
+Content two.
+"""
+        chunker = SemanticChunker()
+        sections = chunker._split_by_headers(text)
+
+        # Should have at least 3 sections (Introduction + 2 main + 1 sub)
+        assert len(sections) >= 2
+        headers = [s[0] for s in sections]
+        assert any("Section One" in h for h in headers)
+        assert any("Section Two" in h for h in headers)
+
+
+class TestMockEmbeddingFunction:
+    """Test mock embedding function."""
+
+    def test_embedding_dimension(self):
+        """Test that embeddings have correct dimension."""
+        mock = MockEmbeddingFunction()
+        embeddings = mock(["test text"])
+
+        assert len(embeddings) == 1
+        assert len(embeddings[0]) == mock.EMBEDDING_DIM
+
+    def test_deterministic_embeddings(self):
+        """Test that same text produces same embedding."""
+        mock = MockEmbeddingFunction()
+        text = "This is a test sentence."
+
+        emb1 = mock([text])[0]
+        emb2 = mock([text])[0]
+
+        assert emb1 == emb2
+
+    def test_different_texts_different_embeddings(self):
+        """Test that different texts produce different embeddings."""
+        mock = MockEmbeddingFunction()
+
+        emb1 = mock(["First text"])[0]
+        emb2 = mock(["Second text"])[0]
+
+        assert emb1 != emb2
+
+    def test_batch_embeddings(self):
+        """Test embedding multiple texts at once."""
+        mock = MockEmbeddingFunction()
+        texts = ["Text one", "Text two", "Text three"]
+
+        embeddings = mock(texts)
+
+        assert len(embeddings) == 3
+        assert all(len(e) == mock.EMBEDDING_DIM for e in embeddings)
+
+
+class TestChromaVectorStore:
+    """Test ChromaDB vector store."""
+
+    @pytest.fixture
+    def temp_dir(self):
+        """Create a temporary directory for ChromaDB."""
+        temp = tempfile.mkdtemp()
+        yield temp
+        shutil.rmtree(temp)
+
+    @pytest.fixture
+    def vectorstore(self, temp_dir):
+        """Create a test vector store."""
+        return ChromaVectorStore(
+            persist_directory=temp_dir,
+            embedding_function=MockEmbeddingFunction(),
+        )
+
+    @pytest.fixture
+    def sample_chunks(self):
+        """Create sample chunks for testing."""
+        return [
+            Chunk(
+                id="chunk_001",
+                text="Lead threshold for non-operational facilities is 22 µg/100cm².",
+                source="fdam.md",
+                category="thresholds",
+                section="## 1.4 Thresholds",
+                priority="primary",
+                content_type="narrative",
+                keywords=["lead", "non-operational"],
+            ),
+            Chunk(
+                id="chunk_002",
+                text="Burn zone requires structural assessment before cleaning.",
+                source="fdam.md",
+                category="methodology",
+                section="## 4.1 Zone Classification",
+                priority="primary",
+                content_type="narrative",
+                keywords=["burn zone", "structural damage"],
+            ),
+            Chunk(
+                id="chunk_003",
+                text="HEPA vacuum is required for soot removal.",
+                source="cleaning.md",
+                category="cleaning-procedures",
+                section="## 3.2 Methods",
+                priority="reference-narrative",
+                content_type="narrative",
+                keywords=["hepa", "vacuum", "soot"],
+            ),
+        ]
+
+    def test_add_chunks(self, vectorstore, sample_chunks):
+        """Test adding chunks to vector store."""
+        count = vectorstore.add_chunks(sample_chunks)
+        assert count == 3
+
+        stats = vectorstore.get_stats()
+        assert stats["total_chunks"] == 3
+
+    def test_query_returns_results(self, vectorstore, sample_chunks):
+        """Test querying the vector store."""
+        vectorstore.add_chunks(sample_chunks)
+
+        results = vectorstore.query("lead threshold", n_results=2)
+
+        assert len(results) <= 2
+        assert all("id" in r for r in results)
+        assert all("document" in r for r in results)
+        assert all("metadata" in r for r in results)
+        assert all("distance" in r for r in results)
+
+    def test_query_with_metadata_filter(self, vectorstore, sample_chunks):
+        """Test querying with metadata filter."""
+        vectorstore.add_chunks(sample_chunks)
+
+        results = vectorstore.query(
+            "cleaning method",
+            n_results=5,
+            where={"priority": "primary"},
+        )
+
+        # All results should have primary priority
+        for r in results:
+            assert r["metadata"]["priority"] == "primary"
+
+    def test_clear_collection(self, vectorstore, sample_chunks):
+        """Test clearing the collection."""
+        vectorstore.add_chunks(sample_chunks)
+        assert vectorstore.get_stats()["total_chunks"] == 3
+
+        vectorstore.clear()
+        assert vectorstore.get_stats()["total_chunks"] == 0
+
+    def test_delete_by_source(self, vectorstore, sample_chunks):
+        """Test deleting chunks by source."""
+        vectorstore.add_chunks(sample_chunks)
+
+        deleted = vectorstore.delete_by_source("fdam.md")
+        assert deleted == 2  # Two chunks from fdam.md
+
+        stats = vectorstore.get_stats()
+        assert stats["total_chunks"] == 1
+
+    def test_get_stats(self, vectorstore, sample_chunks):
+        """Test getting collection statistics."""
+        vectorstore.add_chunks(sample_chunks)
+
+        stats = vectorstore.get_stats()
+
+        assert stats["total_chunks"] == 3
+        assert "thresholds" in stats["categories"]
+        assert "methodology" in stats["categories"]
+        assert "primary" in stats["priorities"]
+        assert "reference-narrative" in stats["priorities"]
+
+
+class TestMockReranker:
+    """Test mock reranker."""
+
+    def test_rerank_returns_scores(self):
+        """Test that reranker returns scores."""
+        reranker = MockReranker()
+        query = "lead threshold contamination"
+        documents = [
+            "Lead threshold for facilities is 22 µg/100cm².",
+            "The weather is nice today.",
+            "Contamination levels require assessment.",
+        ]
+
+        scores = reranker.rerank(query, documents)
+
+        assert len(scores) == 3
+        assert all(0 <= s <= 1 for s in scores)
+
+    def test_relevant_doc_higher_score(self):
+        """Test that more relevant docs get higher scores."""
+        reranker = MockReranker()
+        query = "lead threshold"
+        documents = [
+            "Lead threshold is 22 µg.",  # Very relevant
+            "Weather forecast for tomorrow.",  # Not relevant
+        ]
+
+        scores = reranker.rerank(query, documents)
+
+        # First doc should have higher score (shares more words)
+        assert scores[0] > scores[1]
+
+
+class TestFDAMRetriever:
+    """Test FDAM retriever with priority weighting."""
+
+    @pytest.fixture
+    def temp_dir(self):
+        """Create a temporary directory."""
+        temp = tempfile.mkdtemp()
+        yield temp
+        shutil.rmtree(temp)
+
+    @pytest.fixture
+    def retriever(self, temp_dir):
+        """Create a test retriever with sample data."""
+        vectorstore = ChromaVectorStore(
+            persist_directory=temp_dir,
+            embedding_function=MockEmbeddingFunction(),
+        )
+
+        # Add sample chunks
+        chunks = [
+            Chunk(
+                id="primary_001",
+                text="Lead threshold for non-operational is 22 µg/100cm² per FDAM.",
+                source="fdam.md",
+                category="thresholds",
+                section="## Thresholds",
+                priority="primary",
+                content_type="narrative",
+                keywords=["lead", "threshold", "non-operational"],
+            ),
+            Chunk(
+                id="ref_001",
+                text="Lead clearance levels from BNL SOP.",
+                source="bnl.md",
+                category="thresholds",
+                section="## Attachment 9.3",
+                priority="reference-threshold",
+                content_type="table",
+                keywords=["lead", "clearance"],
+            ),
+            Chunk(
+                id="ref_002",
+                text="General cleaning procedures for soot removal.",
+                source="cleaning.md",
+                category="cleaning-procedures",
+                section="## Methods",
+                priority="reference-narrative",
+                content_type="narrative",
+                keywords=["cleaning", "soot"],
+            ),
+        ]
+        vectorstore.add_chunks(chunks)
+
+        return FDAMRetriever(
+            vectorstore=vectorstore,
+            reranker=MockReranker(),
+            use_reranking=True,
+        )
+
+    def test_retrieve_returns_results(self, retriever):
+        """Test basic retrieval."""
+        results = retriever.retrieve("lead threshold", top_k=3)
+
+        assert len(results) <= 3
+        assert all(isinstance(r, RetrievalResult) for r in results)
+
+    def test_priority_weighting(self, retriever):
+        """Test that primary sources get higher weight."""
+        results = retriever.retrieve("lead threshold", top_k=3)
+
+        # Find primary and reference results
+        primary_results = [r for r in results if r.priority == "primary"]
+        ref_results = [r for r in results if r.priority != "primary"]
+
+        if primary_results and ref_results:
+            # Primary should have higher weighted score (before reranking)
+            # Note: final_score includes reranking which may change order
+            primary = primary_results[0]
+            ref = ref_results[0]
+
+            # With similar similarity, primary weight (1.0) > ref weight (0.8-0.9)
+            # This test validates the weighting is applied
+            assert primary.weighted_score > 0
+
+    def test_category_filter(self, retriever):
+        """Test filtering by category."""
+        results = retriever.retrieve(
+            "cleaning method",
+            top_k=5,
+            category_filter="cleaning-procedures",
+        )
+
+        for r in results:
+            assert r.category == "cleaning-procedures"
+
+    def test_priority_filter(self, retriever):
+        """Test filtering by priority."""
+        results = retriever.retrieve(
+            "threshold",
+            top_k=5,
+            priority_filter="primary",
+        )
+
+        for r in results:
+            assert r.priority == "primary"
+
+    def test_retrieve_for_context(self, retriever):
+        """Test context string generation."""
+        context = retriever.retrieve_for_context("lead threshold", top_k=2)
+
+        assert isinstance(context, str)
+        assert "Source:" in context or "No relevant context" in context
+
+    def test_retrieve_thresholds(self, retriever):
+        """Test threshold-specific retrieval."""
+        results = retriever.retrieve_thresholds(
+            material_type="lead",
+            facility_type="non-operational",
+        )
+
+        assert len(results) <= 3
+        # Should filter to thresholds category
+        for r in results:
+            assert r.category == "thresholds"
+
+    def test_retrieve_disposition(self, retriever):
+        """Test disposition-specific retrieval."""
+        results = retriever.retrieve_disposition(
+            zone="burn-zone",
+            condition="heavy",
+        )
+
+        # Should prefer primary sources
+        if results:
+            assert results[0].priority == "primary"
+
+    def test_result_to_dict(self, retriever):
+        """Test RetrievalResult to_dict method."""
+        results = retriever.retrieve("test", top_k=1)
+
+        if results:
+            result_dict = results[0].to_dict()
+            assert "chunk_id" in result_dict
+            assert "text" in result_dict
+            assert "source" in result_dict
+            assert "similarity_score" in result_dict
+            assert "final_score" in result_dict
+
+    def test_empty_query_handling(self, retriever):
+        """Test handling of query with no good matches."""
+        results = retriever.retrieve(
+            "completely unrelated xyz123",
+            top_k=5,
+            category_filter="thresholds",
+        )
+
+        # Should still return results (just lower scores)
+        assert isinstance(results, list)
+
+
+class TestChunkFile:
+    """Test the chunk_file convenience function."""
+
+    @pytest.fixture
+    def temp_md_file(self):
+        """Create a temporary markdown file."""
+        temp = tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=".md",
+            delete=False,
+            encoding="utf-8",
+        )
+        temp.write("""## Test Document
+
+This is test content for chunking.
+
+| Column A | Column B |
+|----------|----------|
+| Value 1 | Value 2 |
+""")
+        temp.close()
+        yield Path(temp.name)
+        Path(temp.name).unlink()
+
+    def test_chunk_file(self, temp_md_file):
+        """Test chunking a file directly."""
+        chunks = chunk_file(
+            filepath=temp_md_file,
+            category="methodology",
+            priority="primary",
+        )
+
+        assert len(chunks) >= 1
+        assert all(c.source == temp_md_file.name for c in chunks)
+        assert all(c.category == "methodology" for c in chunks)

tests/test_schemas.py

@@ -0,0 +1,459 @@
+"""Tests for FDAM AI Pipeline Pydantic schemas."""
+
+from datetime import date
+
+import pytest
+from pydantic import ValidationError
+
+from schemas import (
+    # Input models
+    AssessmentInput,
+    Dimensions,
+    ImageMetadata,
+    ProjectInfo,
+    QualitativeObservations,
+    Room,
+    Surface,
+    get_material_category,
+    # Output models
+    AirFiltration,
+    CalculationResults,
+    CombustionIndicators,
+    ConditionAnalysis,
+    ConfidenceReport,
+    DetectedMaterial,
+    EquipmentRequirements,
+    GeneratedDocuments,
+    LaborEstimate,
+    RegulatoryFlags,
+    SampleDensity,
+    SamplingRecommendation,
+    SurfaceAreas,
+    VisionAnalysisResult,
+    ZoneAnalysis,
+)
+
+
+# --- Input Schema Tests ---
+
+
+class TestMaterialCategory:
+    """Test material category helper function."""
+
+    def test_non_porous_materials(self):
+        assert get_material_category("steel") == "non-porous"
+        assert get_material_category("concrete") == "non-porous"
+        assert get_material_category("glass") == "non-porous"
+        assert get_material_category("metal") == "non-porous"
+        assert get_material_category("cmu") == "non-porous"
+
+    def test_semi_porous_materials(self):
+        assert get_material_category("drywall-painted") == "semi-porous"
+        assert get_material_category("drywall-unpainted") == "semi-porous"
+        assert get_material_category("wood-sealed") == "semi-porous"
+        assert get_material_category("wood-unsealed") == "semi-porous"
+
+    def test_porous_materials(self):
+        assert get_material_category("carpet") == "porous"
+        assert get_material_category("carpet-pad") == "porous"
+        assert get_material_category("insulation-fiberglass") == "porous"
+        assert get_material_category("acoustic-tile") == "porous"
+        assert get_material_category("upholstery") == "porous"
+
+    def test_hvac_materials(self):
+        assert get_material_category("ductwork-rigid") == "hvac"
+        assert get_material_category("ductwork-flexible") == "hvac"
+        assert get_material_category("hvac-interior-insulation") == "hvac"
+
+
+class TestDimensions:
+    """Test Dimensions model."""
+
+    def test_valid_dimensions(self):
+        dims = Dimensions(length_ft=100, width_ft=50, ceiling_height_ft=20)
+        assert dims.area_sf == 5000
+        assert dims.volume_cf == 100000
+
+    def test_invalid_zero_dimension(self):
+        with pytest.raises(ValidationError):
+            Dimensions(length_ft=0, width_ft=50, ceiling_height_ft=20)
+
+    def test_invalid_negative_dimension(self):
+        with pytest.raises(ValidationError):
+            Dimensions(length_ft=-10, width_ft=50, ceiling_height_ft=20)
+
+    def test_dimension_exceeds_max(self):
+        with pytest.raises(ValidationError):
+            Dimensions(length_ft=20000, width_ft=50, ceiling_height_ft=20)
+
+
+class TestSurface:
+    """Test Surface model."""
+
+    def test_valid_surface(self):
+        surface = Surface(
+            id="surf-001",
+            material="steel",
+            description="North wall steel panel",
+            area_sf=500,
+        )
+        assert surface.category == "non-porous"
+        assert surface.zone is None
+        assert surface.ai_detected is False
+
+    def test_surface_with_zone_and_condition(self):
+        surface = Surface(
+            id="surf-002",
+            material="carpet",
+            description="Main floor carpet",
+            area_sf=2000,
+            zone="near-field",
+            condition="moderate",
+            disposition="remove",
+        )
+        assert surface.category == "porous"
+        assert surface.zone == "near-field"
+        assert surface.condition == "moderate"
+        assert surface.disposition == "remove"
+
+    def test_invalid_material(self):
+        with pytest.raises(ValidationError):
+            Surface(
+                id="surf-003",
+                material="invalid-material",
+                description="Test surface",
+                area_sf=100,
+            )
+
+
+class TestRoom:
+    """Test Room model."""
+
+    def test_valid_room(self):
+        room = Room(
+            id="room-001",
+            name="Warehouse Bay A",
+            dimensions=Dimensions(length_ft=100, width_ft=50, ceiling_height_ft=20),
+        )
+        assert room.zone_classification is None
+        assert len(room.surfaces) == 0
+        assert len(room.image_ids) == 0
+
+    def test_room_with_surfaces(self):
+        room = Room(
+            id="room-002",
+            name="Office Space",
+            floor="Ground Floor",
+            dimensions=Dimensions(length_ft=30, width_ft=20, ceiling_height_ft=10),
+            zone_classification="far-field",
+            zone_confidence=0.85,
+            surfaces=[
+                Surface(
+                    id="surf-001",
+                    material="drywall-painted",
+                    description="North wall",
+                    area_sf=300,
+                ),
+                Surface(
+                    id="surf-002",
+                    material="carpet",
+                    description="Floor carpet",
+                    area_sf=600,
+                ),
+            ],
+        )
+        assert len(room.surfaces) == 2
+        assert room.zone_classification == "far-field"
+
+
+class TestProjectInfo:
+    """Test ProjectInfo model."""
+
+    def test_valid_project_info(self):
+        project = ProjectInfo(
+            project_name="ABC Warehouse Fire",
+            address="123 Main Street",
+            city="Springfield",
+            state="IL",
+            zip_code="62701",
+            client_name="ABC Industries",
+            fire_date=date(2024, 12, 15),
+            assessment_date=date(2024, 12, 20),
+            facility_classification="non-operational",
+            construction_era="post-2000",
+            assessor_name="John Smith",
+            assessor_credentials="CIH",
+        )
+        assert project.project_name == "ABC Warehouse Fire"
+        assert project.facility_classification == "non-operational"
+
+    def test_missing_required_field(self):
+        with pytest.raises(ValidationError):
+            ProjectInfo(
+                project_name="Test Project",
+                # Missing address and other required fields
+            )
+
+
+class TestQualitativeObservations:
+    """Test QualitativeObservations model."""
+
+    def test_minimal_observations(self):
+        obs = QualitativeObservations(
+            smoke_fire_odor=True,
+            visible_soot_deposits=True,
+            large_char_particles=False,
+            ash_like_residue=False,
+            surface_discoloration=True,
+            dust_loading_interference=False,
+            wildfire_indicators=False,
+        )
+        assert obs.smoke_fire_odor is True
+        assert obs.odor_intensity is None
+
+    def test_full_observations(self):
+        obs = QualitativeObservations(
+            smoke_fire_odor=True,
+            odor_intensity="strong",
+            visible_soot_deposits=True,
+            soot_pattern_description="Heavy deposits on ceiling",
+            large_char_particles=True,
+            char_density_estimate="moderate",
+            ash_like_residue=True,
+            ash_color_texture="Gray powdery residue",
+            surface_discoloration=True,
+            discoloration_description="Yellowing on walls",
+            dust_loading_interference=False,
+            wildfire_indicators=False,
+            additional_notes="Structural engineer review recommended",
+        )
+        assert obs.odor_intensity == "strong"
+        assert obs.char_density_estimate == "moderate"
+
+
+class TestAssessmentInput:
+    """Test complete AssessmentInput model."""
+
+    @pytest.fixture
+    def sample_project(self):
+        return ProjectInfo(
+            project_name="Test Project",
+            address="123 Test St",
+            city="TestCity",
+            state="TX",
+            zip_code="12345",
+            client_name="Test Client",
+            fire_date=date(2024, 12, 1),
+            assessment_date=date(2024, 12, 15),
+            facility_classification="operational",
+            construction_era="1980-2000",
+            assessor_name="Test Assessor",
+        )
+
+    @pytest.fixture
+    def sample_room(self):
+        return Room(
+            id="room-001",
+            name="Test Room",
+            dimensions=Dimensions(length_ft=50, width_ft=30, ceiling_height_ft=12),
+        )
+
+    @pytest.fixture
+    def sample_observations(self):
+        return QualitativeObservations(
+            smoke_fire_odor=True,
+            visible_soot_deposits=True,
+            large_char_particles=False,
+            ash_like_residue=False,
+            surface_discoloration=False,
+            dust_loading_interference=False,
+            wildfire_indicators=False,
+        )
+
+    def test_valid_assessment_input(self, sample_project, sample_room, sample_observations):
+        assessment = AssessmentInput(
+            project=sample_project,
+            rooms=[sample_room],
+            observations=sample_observations,
+        )
+        assert len(assessment.rooms) == 1
+        assert len(assessment.images) == 0
+
+    def test_duplicate_room_ids(self, sample_project, sample_room, sample_observations):
+        room2 = Room(
+            id="room-001",  # Same ID as sample_room
+            name="Duplicate Room",
+            dimensions=Dimensions(length_ft=20, width_ft=20, ceiling_height_ft=10),
+        )
+        with pytest.raises(ValidationError) as exc_info:
+            AssessmentInput(
+                project=sample_project,
+                rooms=[sample_room, room2],
+                observations=sample_observations,
+            )
+        assert "Room IDs must be unique" in str(exc_info.value)
+
+    def test_image_references_invalid_room(self, sample_project, sample_room, sample_observations):
+        image = ImageMetadata(
+            id="img-001",
+            filename="test.jpg",
+            room_id="nonexistent-room",
+        )
+        with pytest.raises(ValidationError) as exc_info:
+            AssessmentInput(
+                project=sample_project,
+                rooms=[sample_room],
+                images=[image],
+                observations=sample_observations,
+            )
+        assert "references unknown room" in str(exc_info.value)
+
+    def test_valid_image_reference(self, sample_project, sample_room, sample_observations):
+        image = ImageMetadata(
+            id="img-001",
+            filename="test.jpg",
+            room_id="room-001",
+        )
+        assessment = AssessmentInput(
+            project=sample_project,
+            rooms=[sample_room],
+            images=[image],
+            observations=sample_observations,
+        )
+        assert len(assessment.images) == 1
+
+
+# --- Output Schema Tests ---
+
+
+class TestVisionAnalysisResult:
+    """Test VisionAnalysisResult output model."""
+
+    def test_valid_vision_result(self):
+        result = VisionAnalysisResult(
+            zone=ZoneAnalysis(
+                classification="near-field",
+                confidence=0.85,
+                reasoning="Heavy soot deposits visible on surfaces",
+            ),
+            condition=ConditionAnalysis(
+                level="moderate",
+                confidence=0.80,
+                reasoning="Visible film on surfaces",
+            ),
+            materials=[
+                DetectedMaterial(
+                    type="steel",
+                    category="non-porous",
+                    confidence=0.90,
+                    location_description="Ceiling structure",
+                ),
+            ],
+            combustion_indicators=CombustionIndicators(
+                soot_visible=True,
+                soot_pattern="Heavy deposits on horizontal surfaces",
+                char_visible=False,
+                ash_visible=True,
+                ash_description="Gray powdery residue",
+            ),
+            structural_concerns=["Beam deflection observed"],
+            access_issues=["High ceiling requires lift access"],
+            recommended_sampling_locations=[
+                SamplingRecommendation(
+                    description="Center of contamination",
+                    sample_type="tape_lift",
+                    priority="high",
+                ),
+            ],
+            flags_for_review=["Zone boundary unclear"],
+        )
+        assert result.zone.classification == "near-field"
+        assert len(result.materials) == 1
+        assert result.combustion_indicators.soot_visible is True
+
+
+class TestCalculationResults:
+    """Test CalculationResults output model."""
+
+    def test_valid_calculation_results(self):
+        results = CalculationResults(
+            surface_areas=SurfaceAreas(
+                by_type={"steel": 5000, "carpet": 3000},
+                by_disposition={"clean": 5000, "remove": 3000},
+                total_floor_sf=8000,
+                total_surface_sf=8000,
+                total_volume_cf=160000,
+            ),
+            air_filtration=AirFiltration(
+                total_volume_cf=160000,
+                required_ach=4,
+                unit_cfm=2000,
+                units_required=6,
+                calculation="(160,000 CF x 4 ACH) / (2000 CFM x 60) = 6 units",
+            ),
+            sample_density=SampleDensity(
+                total_sf=8000,
+                size_category="5,000 - 25,000 SF",
+                surface_types_count=2,
+                surface_types=["steel", "carpet"],
+                tape_lifts_per_type="5-10",
+                surface_wipes_per_type="5-10",
+                recommended_tape_lifts=20,
+                recommended_surface_wipes=20,
+            ),
+            labor_estimate=LaborEstimate(
+                hepa_vacuum=10,
+                wet_wipe=25,
+                removal=15,
+                total_hours=50,
+            ),
+            equipment=EquipmentRequirements(
+                air_scrubbers=6,
+                hepa_vacuums=2,
+            ),
+            regulatory_flags=RegulatoryFlags(),
+        )
+        assert results.air_filtration.units_required == 6
+        assert results.labor_estimate.total_hours == 50
+
+
+class TestConfidenceReport:
+    """Test ConfidenceReport output model."""
+
+    def test_high_confidence_report(self):
+        report = ConfidenceReport(
+            flagged_items=[],
+            overall_confidence=0.92,
+            review_required=False,
+        )
+        assert report.review_required is False
+
+    def test_low_confidence_report(self):
+        from schemas import FlaggedItem
+
+        report = ConfidenceReport(
+            flagged_items=[
+                FlaggedItem(
+                    type="zone_classification",
+                    room="Warehouse Bay A",
+                    confidence=0.55,
+                    recommendation="Professional review recommended",
+                ),
+            ],
+            overall_confidence=0.55,
+            review_required=True,
+        )
+        assert report.review_required is True
+        assert len(report.flagged_items) == 1
+
+
+class TestGeneratedDocuments:
+    """Test GeneratedDocuments output model."""
+
+    def test_valid_documents(self):
+        docs = GeneratedDocuments(
+            cleaning_specification_md="# Cleaning Specification\n\n## Scope of Work...",
+            sampling_plan_md="# Sampling Plan\n\n## Recommendations...",
+            confidence_report_md="# Confidence Report\n\n## Summary...",
+        )
+        assert "Cleaning Specification" in docs.cleaning_specification_md

tests/test_tabs.py

@@ -0,0 +1,381 @@
+"""Tests for tab UI modules."""
+
+import pytest
+from PIL import Image
+import io
+
+from ui.state import SessionState, RoomFormData, ImageFormData
+from ui.tabs import project, rooms, images, observations, results
+from ui.components import image_store
+
+
+class TestProjectTab:
+    """Test Tab 1: Project Info."""
+
+    def test_update_session_from_form(self):
+        session = SessionState()
+        session = project.update_session_from_form(
+            session,
+            project_name="Test Project",
+            address="123 Main St",
+            city="Springfield",
+            state="IL",
+            zip_code="62701",
+            client_name="Test Client",
+            fire_date="2024-12-01",
+            assessment_date="2024-12-15",
+            facility_classification="Operational",
+            construction_era="Pre-1980",
+            assessor_name="John Smith",
+            assessor_credentials="CIH",
+        )
+
+        assert session.project.project_name == "Test Project"
+        assert session.project.facility_classification == "operational"
+        assert session.project.construction_era == "pre-1980"
+
+    def test_validate_and_continue_incomplete(self):
+        session = SessionState()
+        session, html, tab_index = project.validate_and_continue(
+            session,
+            project_name="",  # Missing
+            address="123 Main",
+            city="City",
+            state="IL",
+            zip_code="12345",
+            client_name="Client",
+            fire_date="2024-01-01",
+            assessment_date="2024-01-02",
+            facility_classification="Non-Operational",
+            construction_era="Post-2000",
+            assessor_name="Name",
+            assessor_credentials="",
+        )
+
+        assert tab_index == 0  # Stay on tab
+        assert "Project name is required" in html
+        assert session.tab1_complete is False
+
+    def test_validate_and_continue_complete(self):
+        session = SessionState()
+        session, html, tab_index = project.validate_and_continue(
+            session,
+            project_name="Test",
+            address="123 Main",
+            city="City",
+            state="IL",
+            zip_code="12345",
+            client_name="Client",
+            fire_date="2024-01-01",
+            assessment_date="2024-01-02",
+            facility_classification="Non-Operational",
+            construction_era="Post-2000",
+            assessor_name="Name",
+            assessor_credentials="",
+        )
+
+        assert tab_index == 1  # Go to next tab
+        assert "✓" in html
+        assert session.tab1_complete is True
+
+    def test_load_form_from_session(self):
+        session = SessionState()
+        session.project.project_name = "Loaded Project"
+        session.project.facility_classification = "public-childcare"
+        session.project.construction_era = "1980-2000"
+
+        values = project.load_form_from_session(session)
+
+        assert values[0] == "Loaded Project"  # project_name
+        assert values[8] == "Public/Childcare"  # facility_classification (UI value)
+        assert values[9] == "1980-2000"  # construction_era (UI value)
+
+
+class TestRoomsTab:
+    """Test Tab 2: Building/Rooms."""
+
+    def test_add_room_valid(self):
+        session = SessionState()
+
+        result = rooms.add_room(
+            session,
+            name="Room 1",
+            floor="Ground",
+            length=100.0,
+            width=50.0,
+            height=20.0,
+        )
+
+        session = result[0]
+        table_data = result[1]
+        validation_html = result[2]
+
+        assert len(session.rooms) == 1
+        assert session.rooms[0].name == "Room 1"
+        assert "✓" in validation_html
+        assert len(table_data) == 1
+
+    def test_add_room_invalid(self):
+        session = SessionState()
+
+        result = rooms.add_room(
+            session,
+            name="",  # Missing
+            floor="",
+            length=0,  # Invalid
+            width=50.0,
+            height=20.0,
+        )
+
+        session = result[0]
+        validation_html = result[2]
+
+        assert len(session.rooms) == 0
+        assert "Room name is required" in validation_html
+        assert "Length must be greater than 0" in validation_html
+
+    def test_remove_last_room(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(name="Room 1", length_ft=100, width_ft=50, ceiling_height_ft=20))
+        session.rooms.append(RoomFormData(name="Room 2", length_ft=75, width_ft=40, ceiling_height_ft=15))
+
+        session, table_data, html, count, area, volume = rooms.remove_last_room(session)
+
+        assert len(session.rooms) == 1
+        assert session.rooms[0].name == "Room 1"
+        assert "Room 2" in html
+
+    def test_validate_and_continue(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(name="Room 1", length_ft=100, width_ft=50, ceiling_height_ft=20))
+
+        session, html, tab_index = rooms.validate_and_continue(session)
+
+        assert tab_index == 2  # Go to Images tab
+        assert session.tab2_complete is True
+
+
+class TestImagesTab:
+    """Test Tab 3: Images."""
+
+    def test_add_image_valid(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(id="room-001", name="Room 1", length_ft=100, width_ft=50, ceiling_height_ft=20))
+
+        # Create a test image
+        test_image = Image.new("RGB", (100, 100), color="red")
+
+        result = images.add_image(
+            session,
+            image=test_image,
+            room_id="room-001",
+            description="Test image",
+        )
+
+        session = result[0]
+        gallery_data = result[1]
+        validation_html = result[2]
+
+        assert len(session.images) == 1
+        assert session.images[0].room_id == "room-001"
+        assert "✓" in validation_html
+        # Image should be in store
+        assert image_store.get(session.images[0].id) is not None
+
+        # Cleanup
+        image_store.clear()
+
+    def test_add_image_no_room(self):
+        session = SessionState()
+        test_image = Image.new("RGB", (100, 100), color="red")
+
+        result = images.add_image(
+            session,
+            image=test_image,
+            room_id="",  # No room selected
+            description="",
+        )
+
+        session = result[0]
+        validation_html = result[2]
+
+        assert len(session.images) == 0
+        assert "select a room" in validation_html
+
+    def test_validate_missing_images(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(id="room-001", name="Room 1"))
+        # Add image metadata but don't store the actual image
+        session.images.append(ImageFormData(id="img-missing", filename="test.jpg", room_id="room-001"))
+
+        session, html, tab_index = images.validate_and_continue(session)
+
+        assert tab_index == 2  # Stay on Images tab
+        assert "re-uploaded" in html
+
+    def test_update_room_choices(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(id="room-001", name="Room 1"))
+        session.rooms.append(RoomFormData(id="room-002", name="Room 2"))
+
+        update = images.update_room_choices(session)
+
+        assert "choices" in update
+        assert len(update["choices"]) == 2
+
+
+class TestObservationsTab:
+    """Test Tab 4: Observations."""
+
+    def test_update_session_from_form(self):
+        session = SessionState()
+        session = observations.update_session_from_form(
+            session,
+            smoke_odor=True,
+            odor_intensity="Strong",
+            visible_soot=True,
+            soot_description="Heavy on ceiling",
+            large_char=True,
+            char_density="Moderate",
+            ash_residue=False,
+            ash_description="",
+            surface_discoloration=True,
+            discoloration_description="Yellowing",
+            dust_interference=False,
+            dust_notes="",
+            wildfire_indicators=False,
+            wildfire_notes="",
+            additional_notes="Test notes",
+        )
+
+        assert session.observations.smoke_fire_odor is True
+        assert session.observations.odor_intensity == "strong"
+        assert session.observations.char_density_estimate == "moderate"
+        assert session.observations.additional_notes == "Test notes"
+
+    def test_validate_and_continue(self):
+        session = SessionState()
+
+        session, html, tab_index = observations.validate_and_continue(
+            session,
+            smoke_odor=True,
+            odor_intensity="Moderate",
+            visible_soot=True,
+            soot_description="",
+            large_char=False,
+            char_density="None",
+            ash_residue=False,
+            ash_description="",
+            surface_discoloration=False,
+            discoloration_description="",
+            dust_interference=False,
+            dust_notes="",
+            wildfire_indicators=False,
+            wildfire_notes="",
+            additional_notes="",
+        )
+
+        assert tab_index == 4  # Go to Results tab
+        assert session.tab4_complete is True
+
+    def test_load_form_from_session(self):
+        session = SessionState()
+        session.observations.smoke_fire_odor = True
+        session.observations.odor_intensity = "strong"
+        session.observations.char_density_estimate = "dense"
+
+        values = observations.load_form_from_session(session)
+
+        assert values[0] is True  # smoke_odor
+        assert values[1] == "Strong"  # odor_intensity (UI value)
+        assert values[5] == "Dense"  # char_density (UI value)
+
+
+class TestResultsTab:
+    """Test Tab 5: Generate Results."""
+
+    def test_check_preflight_incomplete(self):
+        session = SessionState()
+        # No data added
+
+        html = results.check_preflight(session)
+
+        assert "Cannot Generate" in html
+        assert "Project name is required" in html
+
+    def test_check_preflight_complete(self):
+        session = SessionState()
+        session.project.project_name = "Test"
+        session.project.address = "123 Main"
+        session.project.city = "City"
+        session.project.state = "IL"
+        session.project.zip_code = "12345"
+        session.project.client_name = "Client"
+        session.project.fire_date = "2024-01-01"
+        session.project.assessment_date = "2024-01-02"
+        session.project.assessor_name = "Assessor"
+
+        session.rooms.append(RoomFormData(
+            id="room-001",
+            name="Room 1",
+            length_ft=100,
+            width_ft=50,
+            ceiling_height_ft=20,
+        ))
+
+        # Add image with actual bytes in store
+        img_id = "img-001"
+        session.images.append(ImageFormData(id=img_id, filename="test.jpg", room_id="room-001"))
+        test_image = Image.new("RGB", (100, 100), color="red")
+        img_bytes = io.BytesIO()
+        test_image.save(img_bytes, format="PNG")
+        image_store.store(img_id, img_bytes.getvalue())
+
+        html = results.check_preflight(session)
+
+        assert "Ready to Generate" in html
+        assert "Test" in html  # Project name
+
+        # Cleanup
+        image_store.clear()
+
+    def test_generate_assessment_incomplete(self):
+        session = SessionState()
+        # Missing required data
+
+        result = results.generate_assessment(session)
+
+        session = result[0]
+        status = result[1]
+        sow = result[5]
+
+        assert "Error" in status
+        assert "Error" in sow
+
+
+class TestMapConversions:
+    """Test UI-to-schema value mappings."""
+
+    def test_facility_map(self):
+        assert project.FACILITY_MAP["Non-Operational"] == "non-operational"
+        assert project.FACILITY_MAP["Operational"] == "operational"
+        assert project.FACILITY_MAP["Public/Childcare"] == "public-childcare"
+
+    def test_facility_map_reverse(self):
+        assert project.FACILITY_MAP_REVERSE["non-operational"] == "Non-Operational"
+        assert project.FACILITY_MAP_REVERSE["operational"] == "Operational"
+        assert project.FACILITY_MAP_REVERSE["public-childcare"] == "Public/Childcare"
+
+    def test_era_map(self):
+        assert project.ERA_MAP["Pre-1980"] == "pre-1980"
+        assert project.ERA_MAP["1980-2000"] == "1980-2000"
+        assert project.ERA_MAP["Post-2000"] == "post-2000"
+
+    def test_odor_map(self):
+        assert observations.ODOR_MAP["None"] == "none"
+        assert observations.ODOR_MAP["Strong"] == "strong"
+
+    def test_char_density_map(self):
+        assert observations.CHAR_DENSITY_MAP["None"] is None
+        assert observations.CHAR_DENSITY_MAP["Sparse"] == "sparse"
+        assert observations.CHAR_DENSITY_MAP["Dense"] == "dense"

tests/test_ui_state.py

@@ -0,0 +1,360 @@
+"""Tests for UI state management."""
+
+import json
+import pytest
+
+from ui.state import (
+    SessionState,
+    AssessmentHistory,
+    ProjectFormData,
+    RoomFormData,
+    ImageFormData,
+    ObservationsFormData,
+    create_new_session,
+    session_to_json,
+    session_from_json,
+    history_to_json,
+    history_from_json,
+)
+from ui.components import (
+    create_validation_message,
+    create_room_table_data,
+    create_history_dropdown_choices,
+    create_stats_dict,
+    ImageStore,
+)
+
+
+class TestSessionState:
+    """Test SessionState model."""
+
+    def test_create_new_session(self):
+        session = create_new_session()
+        assert session.session_id is not None
+        assert len(session.session_id) == 32  # UUID hex
+        assert session.tab1_complete is False
+        assert len(session.rooms) == 0
+
+    def test_session_serialization(self):
+        session = SessionState()
+        session.project.project_name = "Test Project"
+        session.rooms.append(RoomFormData(
+            name="Room 1",
+            length_ft=100,
+            width_ft=50,
+            ceiling_height_ft=20,
+        ))
+
+        # Serialize
+        json_str = session_to_json(session)
+        assert "Test Project" in json_str
+        assert "Room 1" in json_str
+
+        # Deserialize
+        loaded = session_from_json(json_str)
+        assert loaded.project.project_name == "Test Project"
+        assert len(loaded.rooms) == 1
+        assert loaded.rooms[0].name == "Room 1"
+
+    def test_session_validation_tab1_incomplete(self):
+        session = SessionState()
+        is_valid, errors = session.validate_tab1()
+        assert is_valid is False
+        assert "Project name is required" in errors
+        assert "Address is required" in errors
+
+    def test_session_validation_tab1_complete(self):
+        session = SessionState()
+        session.project = ProjectFormData(
+            project_name="Test Project",
+            address="123 Main St",
+            city="Springfield",
+            state="IL",
+            zip_code="62701",
+            client_name="Test Client",
+            fire_date="2024-12-01",
+            assessment_date="2024-12-15",
+            assessor_name="John Smith",
+        )
+        is_valid, errors = session.validate_tab1()
+        assert is_valid is True
+        assert len(errors) == 0
+
+    def test_session_validation_tab2_no_rooms(self):
+        session = SessionState()
+        is_valid, errors = session.validate_tab2()
+        assert is_valid is False
+        assert "At least one room is required" in errors
+
+    def test_session_validation_tab2_invalid_dimensions(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(
+            name="Room 1",
+            length_ft=0,  # Invalid
+            width_ft=50,
+            ceiling_height_ft=20,
+        ))
+        is_valid, errors = session.validate_tab2()
+        assert is_valid is False
+        assert any("Length must be greater than 0" in e for e in errors)
+
+    def test_session_validation_tab2_complete(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(
+            name="Room 1",
+            length_ft=100,
+            width_ft=50,
+            ceiling_height_ft=20,
+        ))
+        is_valid, errors = session.validate_tab2()
+        assert is_valid is True
+
+    def test_session_validation_tab3_no_images(self):
+        session = SessionState()
+        is_valid, errors = session.validate_tab3()
+        assert is_valid is False
+        assert "At least one image is required" in errors
+
+    def test_session_validation_tab3_complete(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(id="room-001", name="Room 1"))
+        session.images.append(ImageFormData(
+            filename="test.jpg",
+            room_id="room-001",
+        ))
+        is_valid, errors = session.validate_tab3()
+        assert is_valid is True
+
+    def test_session_can_generate(self):
+        session = SessionState()
+        # Fill all required fields
+        session.project = ProjectFormData(
+            project_name="Test",
+            address="123 Main",
+            city="City",
+            state="IL",
+            zip_code="12345",
+            client_name="Client",
+            fire_date="2024-01-01",
+            assessment_date="2024-01-02",
+            assessor_name="Assessor",
+        )
+        session.rooms.append(RoomFormData(
+            id="room-001",
+            name="Room 1",
+            length_ft=100,
+            width_ft=50,
+            ceiling_height_ft=20,
+        ))
+        session.images.append(ImageFormData(
+            filename="test.jpg",
+            room_id="room-001",
+        ))
+
+        can_gen, errors = session.can_generate()
+        assert can_gen is True
+        assert len(errors) == 0
+
+    def test_session_display_name(self):
+        session = SessionState()
+        # Default name from session ID
+        assert session.session_id[:8] in session.get_display_name()
+
+        # Name from project
+        session.project.project_name = "My Project"
+        assert session.get_display_name() == "My Project"
+
+        # Explicit name takes priority
+        session.name = "Custom Name"
+        assert session.get_display_name() == "Custom Name"
+
+
+class TestAssessmentHistory:
+    """Test AssessmentHistory model."""
+
+    def test_empty_history(self):
+        history = AssessmentHistory()
+        assert len(history.assessments) == 0
+        assert history.current_session_id is None
+
+    def test_add_assessment(self):
+        history = AssessmentHistory()
+        session = SessionState()
+        session.project.project_name = "Test"
+
+        history.add_assessment(session)
+        assert len(history.assessments) == 1
+        assert history.assessments[0].session_id == session.session_id
+
+    def test_add_assessment_updates_existing(self):
+        history = AssessmentHistory()
+        session = SessionState()
+        session.project.project_name = "Original"
+
+        history.add_assessment(session)
+
+        # Update and re-add
+        session.project.project_name = "Updated"
+        history.add_assessment(session)
+
+        # Should still have only 1 entry
+        assert len(history.assessments) == 1
+        assert history.assessments[0].project.project_name == "Updated"
+
+    def test_history_limit(self):
+        history = AssessmentHistory()
+
+        # Add 25 assessments
+        for i in range(25):
+            session = SessionState()
+            session.project.project_name = f"Project {i}"
+            history.add_assessment(session)
+
+        # Should only keep 20
+        assert len(history.assessments) == 20
+        # Most recent should be first
+        assert history.assessments[0].project.project_name == "Project 24"
+
+    def test_get_assessment(self):
+        history = AssessmentHistory()
+        session = SessionState()
+        history.add_assessment(session)
+
+        retrieved = history.get_assessment(session.session_id)
+        assert retrieved is not None
+        assert retrieved.session_id == session.session_id
+
+        # Non-existent
+        assert history.get_assessment("nonexistent") is None
+
+    def test_remove_assessment(self):
+        history = AssessmentHistory()
+        session = SessionState()
+        history.add_assessment(session)
+
+        history.remove_assessment(session.session_id)
+        assert len(history.assessments) == 0
+
+    def test_history_serialization(self):
+        history = AssessmentHistory()
+        session = SessionState()
+        session.project.project_name = "Test Project"
+        history.add_assessment(session)
+
+        json_str = history_to_json(history)
+        loaded = history_from_json(json_str)
+
+        assert len(loaded.assessments) == 1
+        assert loaded.assessments[0].project.project_name == "Test Project"
+
+    def test_history_items(self):
+        history = AssessmentHistory()
+        session = SessionState()
+        session.project.project_name = "Test Project"
+        session.has_results = True
+        history.add_assessment(session)
+
+        items = history.get_history_items()
+        assert len(items) == 1
+        assert items[0]["name"] == "Test Project"
+        assert items[0]["has_results"] is True
+
+
+class TestUIComponents:
+    """Test UI component helpers."""
+
+    def test_validation_message_success(self):
+        msg = create_validation_message(True, [], "All good!")
+        assert "✓" in msg
+        assert "All good!" in msg
+
+    def test_validation_message_failure(self):
+        msg = create_validation_message(False, ["Error 1", "Error 2"])
+        assert "⚠" in msg
+        assert "Error 1" in msg
+        assert "Error 2" in msg
+
+    def test_room_table_data(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(
+            name="Room 1",
+            length_ft=100,
+            width_ft=50,
+            ceiling_height_ft=20,
+        ))
+
+        data = create_room_table_data(session)
+        assert len(data) == 1
+        assert data[0][0] == "Room 1"
+        assert "100 x 50 x 20" in data[0][1]
+        assert "5,000" in data[0][2]  # Area
+        assert "100,000" in data[0][3]  # Volume
+
+    def test_history_dropdown_choices(self):
+        history = AssessmentHistory()
+        session = SessionState()
+        session.project.project_name = "Test Project"
+        history.add_assessment(session)
+
+        choices = create_history_dropdown_choices(history)
+        assert len(choices) == 2  # "New Assessment" + 1 saved
+        assert choices[0][0] == "-- New Assessment --"
+        assert "Test Project" in choices[1][0]
+
+    def test_stats_dict(self):
+        session = SessionState()
+        session.rooms.append(RoomFormData(
+            name="Room 1",
+            length_ft=100,
+            width_ft=50,
+            ceiling_height_ft=20,
+        ))
+        session.images.append(ImageFormData(filename="test.jpg", room_id="room-001"))
+
+        stats = create_stats_dict(session)
+        assert stats["rooms"] == 1
+        assert stats["images"] == 1
+        assert stats["total_floor_area_sf"] == "5,000"
+        assert stats["total_volume_cf"] == "100,000"
+
+
+class TestImageStore:
+    """Test ImageStore for in-memory image storage."""
+
+    def test_store_and_get(self):
+        store = ImageStore()
+        store.store("img-001", b"test image bytes")
+
+        assert store.get("img-001") == b"test image bytes"
+        assert store.get("nonexistent") is None
+
+    def test_remove(self):
+        store = ImageStore()
+        store.store("img-001", b"test")
+        store.remove("img-001")
+
+        assert store.get("img-001") is None
+
+    def test_clear(self):
+        store = ImageStore()
+        store.store("img-001", b"test1")
+        store.store("img-002", b"test2")
+        store.clear()
+
+        assert store.get("img-001") is None
+        assert store.get("img-002") is None
+
+    def test_missing_ids(self):
+        store = ImageStore()
+        store.store("img-001", b"test")
+
+        missing = store.get_missing_ids(["img-001", "img-002", "img-003"])
+        assert missing == ["img-002", "img-003"]
+
+    def test_has_all(self):
+        store = ImageStore()
+        store.store("img-001", b"test1")
+        store.store("img-002", b"test2")
+
+        assert store.has_all(["img-001", "img-002"]) is True
+        assert store.has_all(["img-001", "img-003"]) is False

ui/__init__.py

@@ -0,0 +1,86 @@
+"""UI components for FDAM AI Pipeline."""
+
+from .state import (
+    # Form data models
+    ProjectFormData,
+    RoomFormData,
+    ImageFormData,
+    ObservationsFormData,
+    # Session management
+    SessionState,
+    AssessmentHistory,
+    # Helpers
+    create_new_session,
+    session_to_json,
+    session_from_json,
+    history_to_json,
+    history_from_json,
+)
+
+from .storage import (
+    STORAGE_KEY_SESSION,
+    STORAGE_KEY_HISTORY,
+    LOCALSTORAGE_JS,
+    JS_SAVE_SESSION,
+    JS_LOAD_SESSION,
+    JS_SAVE_HISTORY,
+    JS_LOAD_HISTORY,
+    JS_AUTO_LOAD,
+    get_head_html,
+    create_save_trigger_js,
+)
+
+from .components import (
+    create_validation_message,
+    create_progress_html,
+    create_history_dropdown_choices,
+    create_room_table_data,
+    create_tab_status_indicator,
+    create_stats_dict,
+    format_validation_errors_html,
+    format_success_html,
+    format_warning_html,
+    format_info_html,
+    ImageStore,
+    image_store,
+)
+
+__all__ = [
+    # Form data models
+    "ProjectFormData",
+    "RoomFormData",
+    "ImageFormData",
+    "ObservationsFormData",
+    # Session management
+    "SessionState",
+    "AssessmentHistory",
+    "create_new_session",
+    "session_to_json",
+    "session_from_json",
+    "history_to_json",
+    "history_from_json",
+    # Storage
+    "STORAGE_KEY_SESSION",
+    "STORAGE_KEY_HISTORY",
+    "LOCALSTORAGE_JS",
+    "JS_SAVE_SESSION",
+    "JS_LOAD_SESSION",
+    "JS_SAVE_HISTORY",
+    "JS_LOAD_HISTORY",
+    "JS_AUTO_LOAD",
+    "get_head_html",
+    "create_save_trigger_js",
+    # Components
+    "create_validation_message",
+    "create_progress_html",
+    "create_history_dropdown_choices",
+    "create_room_table_data",
+    "create_tab_status_indicator",
+    "create_stats_dict",
+    "format_validation_errors_html",
+    "format_success_html",
+    "format_warning_html",
+    "format_info_html",
+    "ImageStore",
+    "image_store",
+]

ui/components.py

@@ -0,0 +1,272 @@
+"""Reusable UI components for FDAM AI Pipeline.
+
+Provides helper functions for common Gradio UI patterns.
+"""
+
+import gradio as gr
+from typing import Callable, Optional
+
+from .state import SessionState, AssessmentHistory
+
+
+def create_validation_message(
+    is_valid: bool,
+    errors: list[str],
+    success_msg: str = "All required fields are complete."
+) -> str:
+    """Create a formatted validation message.
+
+    Args:
+        is_valid: Whether validation passed
+        errors: List of validation errors
+        success_msg: Message to show on success
+
+    Returns:
+        Formatted message string
+    """
+    if is_valid:
+        return f"✓ {success_msg}"
+    else:
+        error_list = "\n".join(f"• {e}" for e in errors)
+        return f"⚠ Please fix the following:\n{error_list}"
+
+
+def create_progress_html(
+    current_stage: int,
+    total_stages: int,
+    stage_name: str,
+    percentage: Optional[float] = None
+) -> str:
+    """Create HTML for progress display during processing.
+
+    Args:
+        current_stage: Current stage number (1-indexed)
+        total_stages: Total number of stages
+        stage_name: Name of current stage
+        percentage: Optional percentage override
+
+    Returns:
+        HTML string for progress display
+    """
+    if percentage is None:
+        percentage = (current_stage / total_stages) * 100
+
+    return f"""
+    <div style="margin: 10px 0;">
+        <div style="display: flex; justify-content: space-between; margin-bottom: 5px;">
+            <span><strong>Stage {current_stage}/{total_stages}:</strong> {stage_name}</span>
+            <span>{percentage:.0f}%</span>
+        </div>
+        <div style="background: #e0e0e0; border-radius: 4px; height: 20px; overflow: hidden;">
+            <div style="background: #4CAF50; height: 100%; width: {percentage}%; transition: width 0.3s;"></div>
+        </div>
+    </div>
+    """
+
+
+def create_history_dropdown_choices(history: AssessmentHistory) -> list[tuple[str, str]]:
+    """Create choices for history dropdown.
+
+    Args:
+        history: Assessment history object
+
+    Returns:
+        List of (label, value) tuples for dropdown
+    """
+    choices = [("-- New Assessment --", "new")]
+    for item in history.get_history_items():
+        label = item["name"]
+        if item["has_results"]:
+            label += " ✓"
+        # Format date nicely
+        try:
+            from datetime import datetime
+            dt = datetime.fromisoformat(item["updated"])
+            date_str = dt.strftime("%m/%d %H:%M")
+            label += f" ({date_str})"
+        except Exception:
+            pass
+        choices.append((label, item["id"]))
+    return choices
+
+
+def create_room_table_data(session: SessionState) -> list[list]:
+    """Create data for rooms table display.
+
+    Args:
+        session: Current session state
+
+    Returns:
+        List of rows for dataframe
+    """
+    rows = []
+    for room in session.rooms:
+        area = room.length_ft * room.width_ft
+        volume = area * room.ceiling_height_ft
+        rows.append([
+            room.name,
+            f"{room.length_ft:.0f} x {room.width_ft:.0f} x {room.ceiling_height_ft:.0f}",
+            f"{area:,.0f}",
+            f"{volume:,.0f}",
+        ])
+    return rows
+
+
+def create_tab_status_indicator(
+    tab_number: int,
+    is_complete: bool,
+    is_current: bool = False
+) -> str:
+    """Create a status indicator for tab navigation.
+
+    Args:
+        tab_number: Tab number (1-5)
+        is_complete: Whether tab is complete
+        is_current: Whether this is the current tab
+
+    Returns:
+        Status indicator string
+    """
+    if is_complete:
+        return f"✓ Tab {tab_number}"
+    elif is_current:
+        return f"● Tab {tab_number}"
+    else:
+        return f"○ Tab {tab_number}"
+
+
+def create_stats_dict(session: SessionState) -> dict:
+    """Create statistics dictionary for display.
+
+    Args:
+        session: Current session state
+
+    Returns:
+        Dictionary of statistics
+    """
+    total_area = sum(r.length_ft * r.width_ft for r in session.rooms)
+    total_volume = sum(
+        r.length_ft * r.width_ft * r.ceiling_height_ft
+        for r in session.rooms
+    )
+
+    return {
+        "rooms": len(session.rooms),
+        "images": len(session.images),
+        "total_floor_area_sf": f"{total_area:,.0f}",
+        "total_volume_cf": f"{total_volume:,.0f}",
+        "facility_classification": session.project.facility_classification or "Not set",
+        "construction_era": session.project.construction_era or "Not set",
+    }
+
+
+def format_validation_errors_html(errors: list[str]) -> str:
+    """Format validation errors as HTML list.
+
+    Args:
+        errors: List of error messages
+
+    Returns:
+        HTML string
+    """
+    if not errors:
+        return ""
+
+    items = "".join(f"<li>{e}</li>" for e in errors)
+    return f"""
+    <div style="background: #ffebee; border: 1px solid #ef5350; border-radius: 4px; padding: 10px; margin: 10px 0;">
+        <strong style="color: #c62828;">Please fix the following issues:</strong>
+        <ul style="margin: 5px 0 0 0; padding-left: 20px; color: #c62828;">
+            {items}
+        </ul>
+    </div>
+    """
+
+
+def format_success_html(message: str) -> str:
+    """Format success message as HTML.
+
+    Args:
+        message: Success message
+
+    Returns:
+        HTML string
+    """
+    return f"""
+    <div style="background: #e8f5e9; border: 1px solid #66bb6a; border-radius: 4px; padding: 10px; margin: 10px 0;">
+        <span style="color: #2e7d32;">✓ {message}</span>
+    </div>
+    """
+
+
+def format_warning_html(message: str) -> str:
+    """Format warning message as HTML.
+
+    Args:
+        message: Warning message
+
+    Returns:
+        HTML string
+    """
+    return f"""
+    <div style="background: #fff3e0; border: 1px solid #ffb74d; border-radius: 4px; padding: 10px; margin: 10px 0;">
+        <span style="color: #e65100;">⚠ {message}</span>
+    </div>
+    """
+
+
+def format_info_html(message: str) -> str:
+    """Format info message as HTML.
+
+    Args:
+        message: Info message
+
+    Returns:
+        HTML string
+    """
+    return f"""
+    <div style="background: #e3f2fd; border: 1px solid #64b5f6; border-radius: 4px; padding: 10px; margin: 10px 0;">
+        <span style="color: #1565c0;">ℹ {message}</span>
+    </div>
+    """
+
+
+# Image handling helpers (images stored separately from localStorage)
+
+class ImageStore:
+    """In-memory store for uploaded images.
+
+    Images are too large for localStorage, so they're kept in memory
+    and referenced by ID. Users are prompted to re-upload when resuming.
+    """
+
+    def __init__(self):
+        self._images: dict[str, bytes] = {}
+
+    def store(self, image_id: str, image_bytes: bytes) -> None:
+        """Store image bytes by ID."""
+        self._images[image_id] = image_bytes
+
+    def get(self, image_id: str) -> Optional[bytes]:
+        """Get image bytes by ID."""
+        return self._images.get(image_id)
+
+    def remove(self, image_id: str) -> None:
+        """Remove image by ID."""
+        self._images.pop(image_id, None)
+
+    def clear(self) -> None:
+        """Clear all stored images."""
+        self._images.clear()
+
+    def get_missing_ids(self, expected_ids: list[str]) -> list[str]:
+        """Get list of expected image IDs that are missing."""
+        return [id for id in expected_ids if id not in self._images]
+
+    def has_all(self, expected_ids: list[str]) -> bool:
+        """Check if all expected images are present."""
+        return all(id in self._images for id in expected_ids)
+
+
+# Global image store instance
+image_store = ImageStore()

ui/state.py

@@ -0,0 +1,273 @@
+"""Session state management for FDAM AI Pipeline.
+
+Provides Pydantic models for session state and localStorage persistence.
+Images are stored separately (not in localStorage due to size limits).
+"""
+
+import json
+import uuid
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from schemas.input import (
+    ConstructionEra,
+    FacilityClassification,
+    OdorIntensity,
+    CharDensity,
+)
+
+
+# --- Form Data Models (for localStorage) ---
+
+
+class ProjectFormData(BaseModel):
+    """Form data for Tab 1: Project Info."""
+
+    project_name: str = ""
+    address: str = ""
+    city: str = ""
+    state: str = ""
+    zip_code: str = ""
+    client_name: str = ""
+    fire_date: str = ""  # ISO format string for form compatibility
+    assessment_date: str = ""
+    facility_classification: FacilityClassification = "non-operational"
+    construction_era: ConstructionEra = "post-2000"
+    assessor_name: str = ""
+    assessor_credentials: str = ""
+
+
+class RoomFormData(BaseModel):
+    """Form data for a single room."""
+
+    id: str = Field(default_factory=lambda: f"room-{uuid.uuid4().hex[:8]}")
+    name: str = ""
+    floor: str = ""
+    length_ft: float = 0
+    width_ft: float = 0
+    ceiling_height_ft: float = 0
+
+
+class ImageFormData(BaseModel):
+    """Form data for a single image (metadata only, not bytes)."""
+
+    id: str = Field(default_factory=lambda: f"img-{uuid.uuid4().hex[:8]}")
+    filename: str = ""
+    room_id: str = ""
+    description: str = ""
+    # Image bytes stored separately, referenced by id
+
+
+class ObservationsFormData(BaseModel):
+    """Form data for Tab 4: Observations."""
+
+    smoke_fire_odor: bool = False
+    odor_intensity: OdorIntensity = "none"
+    visible_soot_deposits: bool = False
+    soot_pattern_description: str = ""
+    large_char_particles: bool = False
+    char_density_estimate: Optional[CharDensity] = None
+    ash_like_residue: bool = False
+    ash_color_texture: str = ""
+    surface_discoloration: bool = False
+    discoloration_description: str = ""
+    dust_loading_interference: bool = False
+    dust_notes: str = ""
+    wildfire_indicators: bool = False
+    wildfire_notes: str = ""
+    additional_notes: str = ""
+
+
+class SessionState(BaseModel):
+    """Complete session state for an assessment.
+
+    This model is serialized to localStorage for persistence.
+    Images are stored separately and referenced by ID.
+    """
+
+    # Session metadata
+    session_id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+    created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
+    updated_at: str = Field(default_factory=lambda: datetime.now().isoformat())
+    name: str = ""  # Display name for history list
+
+    # Tab completion status
+    tab1_complete: bool = False
+    tab2_complete: bool = False
+    tab3_complete: bool = False
+    tab4_complete: bool = False
+
+    # Form data by tab
+    project: ProjectFormData = Field(default_factory=ProjectFormData)
+    rooms: list[RoomFormData] = Field(default_factory=list)
+    images: list[ImageFormData] = Field(default_factory=list)
+    observations: ObservationsFormData = Field(default_factory=ObservationsFormData)
+
+    # Results (after generation)
+    has_results: bool = False
+    results_generated_at: Optional[str] = None
+
+    def update_timestamp(self) -> None:
+        """Update the updated_at timestamp."""
+        self.updated_at = datetime.now().isoformat()
+
+    def get_display_name(self) -> str:
+        """Get a display name for the history list."""
+        if self.name:
+            return self.name
+        if self.project.project_name:
+            return self.project.project_name
+        return f"Assessment {self.session_id[:8]}"
+
+    def validate_tab1(self) -> tuple[bool, list[str]]:
+        """Validate Tab 1 (Project Info) is complete."""
+        errors = []
+        p = self.project
+        if not p.project_name:
+            errors.append("Project name is required")
+        if not p.address:
+            errors.append("Address is required")
+        if not p.city:
+            errors.append("City is required")
+        if not p.state:
+            errors.append("State is required")
+        if not p.zip_code:
+            errors.append("ZIP code is required")
+        if not p.client_name:
+            errors.append("Client name is required")
+        if not p.fire_date:
+            errors.append("Fire date is required")
+        if not p.assessment_date:
+            errors.append("Assessment date is required")
+        if not p.assessor_name:
+            errors.append("Assessor name is required")
+        return len(errors) == 0, errors
+
+    def validate_tab2(self) -> tuple[bool, list[str]]:
+        """Validate Tab 2 (Building/Rooms) is complete."""
+        errors = []
+        if not self.rooms:
+            errors.append("At least one room is required")
+        for room in self.rooms:
+            if not room.name:
+                errors.append(f"Room name is required")
+            if room.length_ft <= 0:
+                errors.append(f"Room '{room.name}': Length must be greater than 0")
+            if room.width_ft <= 0:
+                errors.append(f"Room '{room.name}': Width must be greater than 0")
+            if room.ceiling_height_ft <= 0:
+                errors.append(f"Room '{room.name}': Ceiling height must be greater than 0")
+        return len(errors) == 0, errors
+
+    def validate_tab3(self) -> tuple[bool, list[str]]:
+        """Validate Tab 3 (Images) is complete."""
+        errors = []
+        if not self.images:
+            errors.append("At least one image is required")
+        for img in self.images:
+            if not img.room_id:
+                errors.append(f"Image '{img.filename}': Must be associated with a room")
+        return len(errors) == 0, errors
+
+    def validate_tab4(self) -> tuple[bool, list[str]]:
+        """Validate Tab 4 (Observations) is complete."""
+        # Tab 4 has no required fields - all checkboxes default to False
+        return True, []
+
+    def can_generate(self) -> tuple[bool, list[str]]:
+        """Check if assessment can be generated."""
+        all_errors = []
+
+        valid1, errors1 = self.validate_tab1()
+        if not valid1:
+            all_errors.extend(errors1)
+
+        valid2, errors2 = self.validate_tab2()
+        if not valid2:
+            all_errors.extend(errors2)
+
+        valid3, errors3 = self.validate_tab3()
+        if not valid3:
+            all_errors.extend(errors3)
+
+        valid4, errors4 = self.validate_tab4()
+        if not valid4:
+            all_errors.extend(errors4)
+
+        return len(all_errors) == 0, all_errors
+
+
+class AssessmentHistory(BaseModel):
+    """Collection of saved assessments for history list."""
+
+    assessments: list[SessionState] = Field(default_factory=list)
+    current_session_id: Optional[str] = None
+
+    def add_assessment(self, session: SessionState) -> None:
+        """Add or update an assessment in history."""
+        session.update_timestamp()
+        # Remove existing if present
+        self.assessments = [a for a in self.assessments if a.session_id != session.session_id]
+        # Add to front of list
+        self.assessments.insert(0, session)
+        # Keep only last 20 assessments
+        self.assessments = self.assessments[:20]
+
+    def get_assessment(self, session_id: str) -> Optional[SessionState]:
+        """Get an assessment by ID."""
+        for a in self.assessments:
+            if a.session_id == session_id:
+                return a
+        return None
+
+    def remove_assessment(self, session_id: str) -> None:
+        """Remove an assessment from history."""
+        self.assessments = [a for a in self.assessments if a.session_id != session_id]
+
+    def get_history_items(self) -> list[dict]:
+        """Get history items for display in dropdown."""
+        return [
+            {
+                "id": a.session_id,
+                "name": a.get_display_name(),
+                "updated": a.updated_at,
+                "has_results": a.has_results,
+            }
+            for a in self.assessments
+        ]
+
+
+# --- Gradio State Helpers ---
+
+
+def create_new_session() -> SessionState:
+    """Create a new empty session."""
+    return SessionState()
+
+
+def session_to_json(session: SessionState) -> str:
+    """Serialize session to JSON for localStorage."""
+    return session.model_dump_json()
+
+
+def session_from_json(json_str: str) -> SessionState:
+    """Deserialize session from JSON."""
+    try:
+        return SessionState.model_validate_json(json_str)
+    except Exception:
+        return create_new_session()
+
+
+def history_to_json(history: AssessmentHistory) -> str:
+    """Serialize history to JSON for localStorage."""
+    return history.model_dump_json()
+
+
+def history_from_json(json_str: str) -> AssessmentHistory:
+    """Deserialize history from JSON."""
+    try:
+        return AssessmentHistory.model_validate_json(json_str)
+    except Exception:
+        return AssessmentHistory()

ui/storage.py

@@ -0,0 +1,205 @@
+"""localStorage integration for Gradio via JavaScript injection.
+
+Provides JavaScript code that syncs session state with browser localStorage.
+"""
+
+# localStorage keys
+STORAGE_KEY_SESSION = "fdam_current_session"
+STORAGE_KEY_HISTORY = "fdam_assessment_history"
+STORAGE_KEY_IMAGES = "fdam_image_refs"  # References only, not actual bytes
+
+# JavaScript code for localStorage operations
+LOCALSTORAGE_JS = """
+<script>
+(function() {
+    // FDAM localStorage utilities
+    window.fdamStorage = {
+        KEYS: {
+            SESSION: 'fdam_current_session',
+            HISTORY: 'fdam_assessment_history',
+            IMAGE_REFS: 'fdam_image_refs'
+        },
+
+        // Save current session
+        saveSession: function(sessionJson) {
+            try {
+                localStorage.setItem(this.KEYS.SESSION, sessionJson);
+                console.log('[FDAM] Session saved to localStorage');
+                return true;
+            } catch (e) {
+                console.error('[FDAM] Failed to save session:', e);
+                return false;
+            }
+        },
+
+        // Load current session
+        loadSession: function() {
+            try {
+                const data = localStorage.getItem(this.KEYS.SESSION);
+                if (data) {
+                    console.log('[FDAM] Session loaded from localStorage');
+                    return data;
+                }
+            } catch (e) {
+                console.error('[FDAM] Failed to load session:', e);
+            }
+            return null;
+        },
+
+        // Save assessment history
+        saveHistory: function(historyJson) {
+            try {
+                localStorage.setItem(this.KEYS.HISTORY, historyJson);
+                console.log('[FDAM] History saved to localStorage');
+                return true;
+            } catch (e) {
+                console.error('[FDAM] Failed to save history:', e);
+                return false;
+            }
+        },
+
+        // Load assessment history
+        loadHistory: function() {
+            try {
+                const data = localStorage.getItem(this.KEYS.HISTORY);
+                if (data) {
+                    console.log('[FDAM] History loaded from localStorage');
+                    return data;
+                }
+            } catch (e) {
+                console.error('[FDAM] Failed to load history:', e);
+            }
+            return null;
+        },
+
+        // Clear all FDAM data
+        clearAll: function() {
+            try {
+                localStorage.removeItem(this.KEYS.SESSION);
+                localStorage.removeItem(this.KEYS.HISTORY);
+                localStorage.removeItem(this.KEYS.IMAGE_REFS);
+                console.log('[FDAM] All localStorage data cleared');
+                return true;
+            } catch (e) {
+                console.error('[FDAM] Failed to clear storage:', e);
+                return false;
+            }
+        },
+
+        // Get storage usage info
+        getStorageInfo: function() {
+            try {
+                let total = 0;
+                for (let key in localStorage) {
+                    if (key.startsWith('fdam_')) {
+                        total += localStorage.getItem(key).length;
+                    }
+                }
+                return {
+                    used_bytes: total,
+                    used_kb: (total / 1024).toFixed(2),
+                    limit_kb: 5120  // ~5MB typical limit
+                };
+            } catch (e) {
+                return { error: e.message };
+            }
+        }
+    };
+
+    // Expose to global scope for Gradio callbacks
+    window.saveSession = window.fdamStorage.saveSession.bind(window.fdamStorage);
+    window.loadSession = window.fdamStorage.loadSession.bind(window.fdamStorage);
+    window.saveHistory = window.fdamStorage.saveHistory.bind(window.fdamStorage);
+    window.loadHistory = window.fdamStorage.loadHistory.bind(window.fdamStorage);
+
+    console.log('[FDAM] localStorage utilities loaded');
+})();
+</script>
+"""
+
+# JavaScript functions for Gradio event handlers
+JS_SAVE_SESSION = """
+async (sessionJson) => {
+    if (window.fdamStorage) {
+        window.fdamStorage.saveSession(sessionJson);
+    }
+    return sessionJson;
+}
+"""
+
+JS_LOAD_SESSION = """
+async () => {
+    if (window.fdamStorage) {
+        return window.fdamStorage.loadSession() || '{}';
+    }
+    return '{}';
+}
+"""
+
+JS_SAVE_HISTORY = """
+async (historyJson) => {
+    if (window.fdamStorage) {
+        window.fdamStorage.saveHistory(historyJson);
+    }
+    return historyJson;
+}
+"""
+
+JS_LOAD_HISTORY = """
+async () => {
+    if (window.fdamStorage) {
+        return window.fdamStorage.loadHistory() || '{"assessments":[],"current_session_id":null}';
+    }
+    return '{"assessments":[],"current_session_id":null}';
+}
+"""
+
+# JavaScript to auto-load session on page load
+JS_AUTO_LOAD = """
+async () => {
+    // Small delay to ensure Gradio is fully loaded
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    if (window.fdamStorage) {
+        const session = window.fdamStorage.loadSession();
+        const history = window.fdamStorage.loadHistory();
+        return [session || '{}', history || '{"assessments":[],"current_session_id":null}'];
+    }
+    return ['{}', '{"assessments":[],"current_session_id":null}'];
+}
+"""
+
+
+def get_head_html() -> str:
+    """Get HTML to inject into Gradio head for localStorage support."""
+    return LOCALSTORAGE_JS
+
+
+def create_save_trigger_js(field_updates: dict[str, str]) -> str:
+    """Create JavaScript that triggers save after field updates.
+
+    Args:
+        field_updates: Mapping of field name to value expression
+
+    Returns:
+        JavaScript code string
+    """
+    updates = ", ".join(f'"{k}": {v}' for k, v in field_updates.items())
+    return f"""
+async (currentSession, ...values) => {{
+    try {{
+        const session = JSON.parse(currentSession || '{{}}');
+        const updates = {{ {updates} }};
+        Object.assign(session, updates);
+        session.updated_at = new Date().toISOString();
+        const newSession = JSON.stringify(session);
+        if (window.fdamStorage) {{
+            window.fdamStorage.saveSession(newSession);
+        }}
+        return newSession;
+    }} catch (e) {{
+        console.error('[FDAM] Save trigger error:', e);
+        return currentSession;
+    }}
+}}
+"""

ui/tabs/__init__.py

@@ -0,0 +1,15 @@
+"""Tab modules for FDAM AI Pipeline UI."""
+
+from . import project
+from . import rooms
+from . import images
+from . import observations
+from . import results
+
+__all__ = [
+    "project",
+    "rooms",
+    "images",
+    "observations",
+    "results",
+]

ui/tabs/images.py

@@ -0,0 +1,328 @@
+"""Tab 3: Images.
+
+Upload and manage fire damage images for AI analysis.
+"""
+
+import uuid
+import gradio as gr
+from typing import Any, Optional
+from PIL import Image
+import io
+
+from ui.state import SessionState, ImageFormData
+from ui.components import image_store
+from config.settings import settings
+
+
+def create_tab() -> dict[str, Any]:
+    """Create Tab 3 UI components.
+
+    Returns:
+        Dictionary of component references for event wiring.
+    """
+    gr.Markdown("### Fire Damage Images")
+    gr.Markdown(
+        f"*Upload up to {settings.max_images_per_assessment} images for AI analysis. "
+        f"Each image must be associated with a room.*"
+    )
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            image_upload = gr.Image(
+                label="Upload Image",
+                type="pil",
+                sources=["upload"],
+                elem_id="image_upload",
+            )
+            room_select = gr.Dropdown(
+                label="Associate with Room *",
+                choices=[],
+                value=None,
+                elem_id="room_select",
+            )
+            image_description = gr.Textbox(
+                label="Description (optional)",
+                placeholder="e.g., View of ceiling deck from center aisle",
+                elem_id="image_description",
+            )
+
+            with gr.Row():
+                add_image_btn = gr.Button("Add Image", variant="primary")
+                clear_upload_btn = gr.Button("Clear", variant="secondary")
+
+        with gr.Column(scale=3):
+            images_gallery = gr.Gallery(
+                label="Images Added",
+                columns=3,
+                height="auto",
+                elem_id="images_gallery",
+            )
+            with gr.Row():
+                remove_last_btn = gr.Button("Remove Last Image", variant="secondary")
+                clear_all_btn = gr.Button("Clear All Images", variant="stop")
+
+    # Image count and status
+    with gr.Row():
+        image_count = gr.Textbox(
+            label="Images Added",
+            value="0 / 20",
+            interactive=False,
+        )
+
+    # Validation status
+    with gr.Row():
+        validation_status = gr.HTML(
+            value="",
+            elem_id="tab3_validation",
+        )
+
+    # Resume warning (shown when images need re-upload)
+    with gr.Row():
+        resume_warning = gr.HTML(
+            value="",
+            elem_id="resume_warning",
+            visible=False,
+        )
+
+    with gr.Row():
+        back_btn = gr.Button("← Back to Rooms")
+        validate_btn = gr.Button(
+            "Validate & Continue to Observations →",
+            variant="primary",
+        )
+
+    return {
+        "image_upload": image_upload,
+        "room_select": room_select,
+        "image_description": image_description,
+        "add_image_btn": add_image_btn,
+        "clear_upload_btn": clear_upload_btn,
+        "images_gallery": images_gallery,
+        "remove_last_btn": remove_last_btn,
+        "clear_all_btn": clear_all_btn,
+        "image_count": image_count,
+        "validation_status": validation_status,
+        "resume_warning": resume_warning,
+        "back_btn": back_btn,
+        "validate_btn": validate_btn,
+    }
+
+
+def add_image(
+    session: SessionState,
+    image: Optional[Image.Image],
+    room_id: str,
+    description: str,
+) -> tuple[SessionState, list[tuple], str, str, None, None, str]:
+    """Add an image to the session.
+
+    Returns:
+        Tuple of (session, gallery_data, validation_html, image_count,
+                  cleared_image, cleared_description, room_id).
+    """
+    validation_html = ""
+
+    # Validate input
+    errors = []
+    if image is None:
+        errors.append("Please upload an image")
+    if not room_id:
+        errors.append("Please select a room for this image")
+    if len(session.images) >= settings.max_images_per_assessment:
+        errors.append(f"Maximum of {settings.max_images_per_assessment} images allowed")
+
+    if errors:
+        error_items = "".join(f"<li>{e}</li>" for e in errors)
+        validation_html = f"""
+        <div style="background: #ffebee; border: 1px solid #ef5350; border-radius: 4px; padding: 10px;">
+            <ul style="margin: 0; padding-left: 20px; color: #c62828;">
+                {error_items}
+            </ul>
+        </div>
+        """
+        gallery_data = _get_gallery_data(session)
+        count_str = f"{len(session.images)} / {settings.max_images_per_assessment}"
+        return session, gallery_data, validation_html, count_str, image, description, room_id
+
+    # Generate image ID
+    image_id = f"img-{uuid.uuid4().hex[:8]}"
+
+    # Store image bytes in memory
+    img_bytes = io.BytesIO()
+    image.save(img_bytes, format="PNG")
+    image_store.store(image_id, img_bytes.getvalue())
+
+    # Get room name for filename
+    room_name = "unknown"
+    for room in session.rooms:
+        if room.id == room_id:
+            room_name = room.name.replace(" ", "_")[:20]
+            break
+
+    # Add image metadata to session
+    img_meta = ImageFormData(
+        id=image_id,
+        filename=f"{room_name}_{image_id}.png",
+        room_id=room_id,
+        description=description.strip() if description else "",
+    )
+    session.images.append(img_meta)
+    session.update_timestamp()
+
+    # Success message
+    validation_html = f"""
+    <div style="background: #e8f5e9; border: 1px solid #66bb6a; border-radius: 4px; padding: 10px;">
+        <span style="color: #2e7d32;">✓ Image added for room: {room_name}</span>
+    </div>
+    """
+
+    gallery_data = _get_gallery_data(session)
+    count_str = f"{len(session.images)} / {settings.max_images_per_assessment}"
+
+    # Clear form
+    return session, gallery_data, validation_html, count_str, None, "", room_id
+
+
+def remove_last_image(session: SessionState) -> tuple[SessionState, list[tuple], str, str]:
+    """Remove the last image from the session."""
+    validation_html = ""
+
+    if session.images:
+        removed = session.images.pop()
+        image_store.remove(removed.id)
+        session.update_timestamp()
+        validation_html = f"""
+        <div style="background: #fff3e0; border: 1px solid #ffb74d; border-radius: 4px; padding: 10px;">
+            <span style="color: #e65100;">Removed image: {removed.filename}</span>
+        </div>
+        """
+
+    gallery_data = _get_gallery_data(session)
+    count_str = f"{len(session.images)} / {settings.max_images_per_assessment}"
+    return session, gallery_data, validation_html, count_str
+
+
+def clear_all_images(session: SessionState) -> tuple[SessionState, list[tuple], str, str]:
+    """Clear all images from the session."""
+    count = len(session.images)
+
+    # Clear from store
+    for img in session.images:
+        image_store.remove(img.id)
+
+    session.images = []
+    session.update_timestamp()
+
+    validation_html = ""
+    if count > 0:
+        validation_html = f"""
+        <div style="background: #fff3e0; border: 1px solid #ffb74d; border-radius: 4px; padding: 10px;">
+            <span style="color: #e65100;">Cleared {count} image(s)</span>
+        </div>
+        """
+
+    count_str = f"0 / {settings.max_images_per_assessment}"
+    return session, [], validation_html, count_str
+
+
+def validate_and_continue(session: SessionState) -> tuple[SessionState, str, int]:
+    """Validate Tab 3 and proceed to Tab 4.
+
+    Returns:
+        Tuple of (session, validation_html, next_tab_index).
+    """
+    # Check if images need re-upload (session restored but images not in memory)
+    expected_ids = [img.id for img in session.images]
+    missing_ids = image_store.get_missing_ids(expected_ids)
+
+    if missing_ids:
+        missing_count = len(missing_ids)
+        html = f"""
+        <div style="background: #fff3e0; border: 1px solid #ffb74d; border-radius: 4px; padding: 10px;">
+            <strong style="color: #e65100;">⚠ {missing_count} image(s) need to be re-uploaded</strong>
+            <p style="color: #e65100; margin: 5px 0 0 0;">
+                Images are not stored in browser storage. Please re-upload the missing images
+                or clear the image list and start fresh.
+            </p>
+        </div>
+        """
+        return session, html, 2  # Stay on Images tab
+
+    is_valid, errors = session.validate_tab3()
+
+    if is_valid:
+        session.tab3_complete = True
+        session.update_timestamp()
+        html = """
+        <div style="background: #e8f5e9; border: 1px solid #66bb6a; border-radius: 4px; padding: 10px;">
+            <span style="color: #2e7d32;">✓ Images complete. Proceeding to Observations tab...</span>
+        </div>
+        """
+        return session, html, 3  # Go to tab index 3 (Observations)
+    else:
+        session.tab3_complete = False
+        error_items = "".join(f"<li>{e}</li>" for e in errors)
+        html = f"""
+        <div style="background: #ffebee; border: 1px solid #ef5350; border-radius: 4px; padding: 10px;">
+            <strong style="color: #c62828;">Please fix the following:</strong>
+            <ul style="margin: 5px 0 0 0; padding-left: 20px; color: #c62828;">
+                {error_items}
+            </ul>
+        </div>
+        """
+        return session, html, 2  # Stay on current tab
+
+
+def update_room_choices(session: SessionState) -> dict:
+    """Update room dropdown choices.
+
+    Returns:
+        Gradio update dict for Dropdown component.
+    """
+    choices = [(r.name, r.id) for r in session.rooms]
+    # Don't reset value - let user keep their selection when adding multiple images
+    return gr.update(choices=choices)
+
+
+def load_from_session(session: SessionState) -> tuple[list[tuple], str, str]:
+    """Load gallery data and count from session.
+
+    Returns:
+        Tuple of (gallery_data, image_count, resume_warning_html).
+    """
+    gallery_data = _get_gallery_data(session)
+    count_str = f"{len(session.images)} / {settings.max_images_per_assessment}"
+
+    # Check for missing images
+    expected_ids = [img.id for img in session.images]
+    missing_ids = image_store.get_missing_ids(expected_ids)
+
+    resume_html = ""
+    if missing_ids and session.images:
+        resume_html = f"""
+        <div style="background: #fff3e0; border: 1px solid #ffb74d; border-radius: 4px; padding: 10px;">
+            <strong style="color: #e65100;">⚠ {len(missing_ids)} image(s) need to be re-uploaded</strong>
+            <p style="color: #e65100; margin: 5px 0 0 0;">
+                Session restored, but images must be re-uploaded as they are not stored in browser storage.
+            </p>
+        </div>
+        """
+
+    return gallery_data, count_str, resume_html
+
+
+def _get_gallery_data(session: SessionState) -> list[tuple]:
+    """Get gallery data from session images.
+
+    Returns:
+        List of (image, caption) tuples for gallery.
+    """
+    gallery_data = []
+    for img_meta in session.images:
+        img_bytes = image_store.get(img_meta.id)
+        if img_bytes:
+            # Convert bytes to PIL Image for gallery
+            pil_image = Image.open(io.BytesIO(img_bytes))
+            caption = img_meta.description or img_meta.filename
+            gallery_data.append((pil_image, caption))
+    return gallery_data

ui/tabs/observations.py

@@ -0,0 +1,281 @@
+"""Tab 4: Observations.
+
+Qualitative observation checklist per FDAM §2.3.
+"""
+
+import gradio as gr
+from typing import Any
+
+from ui.state import SessionState, ObservationsFormData
+
+
+# Map UI values to schema values
+ODOR_MAP = {
+    "None": "none",
+    "Faint": "faint",
+    "Moderate": "moderate",
+    "Strong": "strong",
+}
+ODOR_MAP_REVERSE = {v: k for k, v in ODOR_MAP.items()}
+
+CHAR_DENSITY_MAP = {
+    "None": None,
+    "Sparse": "sparse",
+    "Moderate": "moderate",
+    "Dense": "dense",
+}
+CHAR_DENSITY_MAP_REVERSE = {v: k for k, v in CHAR_DENSITY_MAP.items()}
+
+
+def create_tab() -> dict[str, Any]:
+    """Create Tab 4 UI components.
+
+    Returns:
+        Dictionary of component references for event wiring.
+    """
+    gr.Markdown("### Qualitative Observations")
+    gr.Markdown("*Document field observations per FDAM §2.3. All fields are optional but recommended.*")
+
+    with gr.Row():
+        with gr.Column():
+            gr.Markdown("#### Odor Assessment")
+            smoke_odor = gr.Checkbox(
+                label="Smoke/fire odor present?",
+                elem_id="smoke_odor",
+            )
+            odor_intensity = gr.Radio(
+                choices=["None", "Faint", "Moderate", "Strong"],
+                label="Odor Intensity",
+                value="None",
+                elem_id="odor_intensity",
+            )
+
+            gr.Markdown("#### Visible Contamination")
+            visible_soot = gr.Checkbox(
+                label="Visible soot deposits?",
+                elem_id="visible_soot",
+            )
+            soot_description = gr.Textbox(
+                label="Soot Pattern Description (optional)",
+                placeholder="e.g., Heavy deposits on ceiling, lighter on walls",
+                elem_id="soot_description",
+            )
+
+            large_char = gr.Checkbox(
+                label="Large char particles observed?",
+                elem_id="large_char",
+            )
+            char_density = gr.Radio(
+                choices=["None", "Sparse", "Moderate", "Dense"],
+                label="Char Density",
+                value="None",
+                elem_id="char_density",
+            )
+
+            ash_residue = gr.Checkbox(
+                label="Ash-like residue present?",
+                elem_id="ash_residue",
+            )
+            ash_description = gr.Textbox(
+                label="Ash Color/Texture (optional)",
+                placeholder="e.g., Gray powdery residue",
+                elem_id="ash_description",
+            )
+
+        with gr.Column():
+            gr.Markdown("#### Surface Conditions")
+            surface_discoloration = gr.Checkbox(
+                label="Surface discoloration?",
+                elem_id="surface_discoloration",
+            )
+            discoloration_description = gr.Textbox(
+                label="Discoloration Description (optional)",
+                placeholder="e.g., Yellowing on painted surfaces",
+                elem_id="discoloration_description",
+            )
+
+            gr.Markdown("#### Environmental Factors")
+            dust_interference = gr.Checkbox(
+                label="Dust loading or interference?",
+                info="Pre-existing dust may affect sample interpretation",
+                elem_id="dust_interference",
+            )
+            dust_notes = gr.Textbox(
+                label="Dust Notes (optional)",
+                placeholder="e.g., Heavy ambient dust from warehouse operations",
+                elem_id="dust_notes",
+            )
+
+            wildfire_indicators = gr.Checkbox(
+                label="Wildfire indicators (burned vegetation/pollen)?",
+                info="May indicate wildfire vs structural fire",
+                elem_id="wildfire_indicators",
+            )
+            wildfire_notes = gr.Textbox(
+                label="Wildfire Notes (optional)",
+                placeholder="e.g., Burned pine pollen visible on surfaces",
+                elem_id="wildfire_notes",
+            )
+
+            gr.Markdown("#### Additional Notes")
+            additional_notes = gr.Textbox(
+                label="Additional Observations",
+                lines=3,
+                placeholder="Any other relevant observations...",
+                elem_id="additional_notes",
+            )
+
+    # Validation status
+    with gr.Row():
+        validation_status = gr.HTML(
+            value="",
+            elem_id="tab4_validation",
+        )
+
+    with gr.Row():
+        back_btn = gr.Button("← Back to Images")
+        validate_btn = gr.Button(
+            "Save & Continue to Generate Results →",
+            variant="primary",
+        )
+
+    return {
+        "smoke_odor": smoke_odor,
+        "odor_intensity": odor_intensity,
+        "visible_soot": visible_soot,
+        "soot_description": soot_description,
+        "large_char": large_char,
+        "char_density": char_density,
+        "ash_residue": ash_residue,
+        "ash_description": ash_description,
+        "surface_discoloration": surface_discoloration,
+        "discoloration_description": discoloration_description,
+        "dust_interference": dust_interference,
+        "dust_notes": dust_notes,
+        "wildfire_indicators": wildfire_indicators,
+        "wildfire_notes": wildfire_notes,
+        "additional_notes": additional_notes,
+        "validation_status": validation_status,
+        "back_btn": back_btn,
+        "validate_btn": validate_btn,
+    }
+
+
+def update_session_from_form(
+    session: SessionState,
+    smoke_odor: bool,
+    odor_intensity: str,
+    visible_soot: bool,
+    soot_description: str,
+    large_char: bool,
+    char_density: str,
+    ash_residue: bool,
+    ash_description: str,
+    surface_discoloration: bool,
+    discoloration_description: str,
+    dust_interference: bool,
+    dust_notes: str,
+    wildfire_indicators: bool,
+    wildfire_notes: str,
+    additional_notes: str,
+) -> SessionState:
+    """Update session state from form values."""
+    session.observations = ObservationsFormData(
+        smoke_fire_odor=smoke_odor or False,
+        odor_intensity=ODOR_MAP.get(odor_intensity, "none"),
+        visible_soot_deposits=visible_soot or False,
+        soot_pattern_description=soot_description or "",
+        large_char_particles=large_char or False,
+        char_density_estimate=CHAR_DENSITY_MAP.get(char_density),
+        ash_like_residue=ash_residue or False,
+        ash_color_texture=ash_description or "",
+        surface_discoloration=surface_discoloration or False,
+        discoloration_description=discoloration_description or "",
+        dust_loading_interference=dust_interference or False,
+        dust_notes=dust_notes or "",
+        wildfire_indicators=wildfire_indicators or False,
+        wildfire_notes=wildfire_notes or "",
+        additional_notes=additional_notes or "",
+    )
+    session.update_timestamp()
+    return session
+
+
+def validate_and_continue(
+    session: SessionState,
+    smoke_odor: bool,
+    odor_intensity: str,
+    visible_soot: bool,
+    soot_description: str,
+    large_char: bool,
+    char_density: str,
+    ash_residue: bool,
+    ash_description: str,
+    surface_discoloration: bool,
+    discoloration_description: str,
+    dust_interference: bool,
+    dust_notes: str,
+    wildfire_indicators: bool,
+    wildfire_notes: str,
+    additional_notes: str,
+) -> tuple[SessionState, str, int]:
+    """Save observations and proceed to Tab 5.
+
+    Returns:
+        Tuple of (session, validation_html, next_tab_index).
+    """
+    # Update session
+    session = update_session_from_form(
+        session,
+        smoke_odor,
+        odor_intensity,
+        visible_soot,
+        soot_description,
+        large_char,
+        char_density,
+        ash_residue,
+        ash_description,
+        surface_discoloration,
+        discoloration_description,
+        dust_interference,
+        dust_notes,
+        wildfire_indicators,
+        wildfire_notes,
+        additional_notes,
+    )
+
+    # Tab 4 has no required fields
+    session.tab4_complete = True
+
+    html = """
+    <div style="background: #e8f5e9; border: 1px solid #66bb6a; border-radius: 4px; padding: 10px;">
+        <span style="color: #2e7d32;">✓ Observations saved. Proceeding to Generate Results...</span>
+    </div>
+    """
+    return session, html, 4  # Go to tab index 4 (Results)
+
+
+def load_form_from_session(session: SessionState) -> tuple:
+    """Load form values from session state.
+
+    Returns:
+        Tuple of form values in component order.
+    """
+    obs = session.observations
+    return (
+        obs.smoke_fire_odor,
+        ODOR_MAP_REVERSE.get(obs.odor_intensity, "None"),
+        obs.visible_soot_deposits,
+        obs.soot_pattern_description,
+        obs.large_char_particles,
+        CHAR_DENSITY_MAP_REVERSE.get(obs.char_density_estimate, "None"),
+        obs.ash_like_residue,
+        obs.ash_color_texture,
+        obs.surface_discoloration,
+        obs.discoloration_description,
+        obs.dust_loading_interference,
+        obs.dust_notes,
+        obs.wildfire_indicators,
+        obs.wildfire_notes,
+        obs.additional_notes,
+    )

ui/tabs/project.py

@@ -0,0 +1,251 @@
+"""Tab 1: Project Information.
+
+Collects project details, client information, and facility classification.
+"""
+
+import gradio as gr
+from typing import Any
+
+from ui.state import SessionState, ProjectFormData
+
+
+# Map UI values to schema values
+FACILITY_MAP = {
+    "Non-Operational": "non-operational",
+    "Operational": "operational",
+    "Public/Childcare": "public-childcare",
+}
+FACILITY_MAP_REVERSE = {v: k for k, v in FACILITY_MAP.items()}
+
+ERA_MAP = {
+    "Pre-1980": "pre-1980",
+    "1980-2000": "1980-2000",
+    "Post-2000": "post-2000",
+}
+ERA_MAP_REVERSE = {v: k for k, v in ERA_MAP.items()}
+
+
+def create_tab() -> dict[str, Any]:
+    """Create Tab 1 UI components.
+
+    Returns:
+        Dictionary of component references for event wiring.
+    """
+    gr.Markdown("### Project Information")
+    gr.Markdown("*Enter project details, client information, and facility classification.*")
+
+    with gr.Row():
+        with gr.Column():
+            project_name = gr.Textbox(
+                label="Project/Facility Name *",
+                placeholder="e.g., ABC Warehouse",
+                elem_id="project_name",
+            )
+            address = gr.Textbox(
+                label="Street Address *",
+                elem_id="address",
+            )
+            with gr.Row():
+                city = gr.Textbox(label="City *", elem_id="city")
+                state = gr.Textbox(
+                    label="State *",
+                    max_lines=1,
+                    elem_id="state",
+                )
+                zip_code = gr.Textbox(
+                    label="ZIP Code *",
+                    max_lines=1,
+                    elem_id="zip_code",
+                )
+
+        with gr.Column():
+            client_name = gr.Textbox(
+                label="Client Name *",
+                elem_id="client_name",
+            )
+            fire_date = gr.Textbox(
+                label="Fire Date *",
+                placeholder="YYYY-MM-DD",
+                elem_id="fire_date",
+            )
+            assessment_date = gr.Textbox(
+                label="Assessment Date *",
+                placeholder="YYYY-MM-DD",
+                elem_id="assessment_date",
+            )
+
+    with gr.Row():
+        facility_classification = gr.Radio(
+            choices=["Non-Operational", "Operational", "Public/Childcare"],
+            label="Facility Classification *",
+            value="Non-Operational",
+            info="Affects clearance thresholds (see FDAM §3.1)",
+            elem_id="facility_classification",
+        )
+        construction_era = gr.Radio(
+            choices=["Pre-1980", "1980-2000", "Post-2000"],
+            label="Construction Era *",
+            value="Post-2000",
+            info="Affects LBP/ACM regulatory flags",
+            elem_id="construction_era",
+        )
+
+    with gr.Row():
+        assessor_name = gr.Textbox(
+            label="Assessor Name *",
+            elem_id="assessor_name",
+        )
+        assessor_credentials = gr.Textbox(
+            label="Credentials (optional)",
+            placeholder="CIH, CSP, etc.",
+            elem_id="assessor_credentials",
+        )
+
+    # Validation status display
+    with gr.Row():
+        validation_status = gr.HTML(
+            value="",
+            elem_id="tab1_validation",
+        )
+
+    with gr.Row():
+        validate_btn = gr.Button(
+            "Validate & Continue to Rooms →",
+            variant="primary",
+        )
+
+    return {
+        "project_name": project_name,
+        "address": address,
+        "city": city,
+        "state": state,
+        "zip_code": zip_code,
+        "client_name": client_name,
+        "fire_date": fire_date,
+        "assessment_date": assessment_date,
+        "facility_classification": facility_classification,
+        "construction_era": construction_era,
+        "assessor_name": assessor_name,
+        "assessor_credentials": assessor_credentials,
+        "validation_status": validation_status,
+        "validate_btn": validate_btn,
+    }
+
+
+def update_session_from_form(
+    session: SessionState,
+    project_name: str,
+    address: str,
+    city: str,
+    state: str,
+    zip_code: str,
+    client_name: str,
+    fire_date: str,
+    assessment_date: str,
+    facility_classification: str,
+    construction_era: str,
+    assessor_name: str,
+    assessor_credentials: str,
+) -> SessionState:
+    """Update session state from form values."""
+    session.project = ProjectFormData(
+        project_name=project_name or "",
+        address=address or "",
+        city=city or "",
+        state=state or "",
+        zip_code=zip_code or "",
+        client_name=client_name or "",
+        fire_date=fire_date or "",
+        assessment_date=assessment_date or "",
+        facility_classification=FACILITY_MAP.get(facility_classification, "non-operational"),
+        construction_era=ERA_MAP.get(construction_era, "post-2000"),
+        assessor_name=assessor_name or "",
+        assessor_credentials=assessor_credentials or "",
+    )
+    session.update_timestamp()
+    return session
+
+
+def validate_and_continue(
+    session: SessionState,
+    project_name: str,
+    address: str,
+    city: str,
+    state: str,
+    zip_code: str,
+    client_name: str,
+    fire_date: str,
+    assessment_date: str,
+    facility_classification: str,
+    construction_era: str,
+    assessor_name: str,
+    assessor_credentials: str,
+) -> tuple[SessionState, str, int]:
+    """Validate Tab 1 and update session.
+
+    Returns:
+        Tuple of (updated session, validation HTML, next tab index).
+    """
+    # Update session first
+    session = update_session_from_form(
+        session,
+        project_name,
+        address,
+        city,
+        state,
+        zip_code,
+        client_name,
+        fire_date,
+        assessment_date,
+        facility_classification,
+        construction_era,
+        assessor_name,
+        assessor_credentials,
+    )
+
+    # Validate
+    is_valid, errors = session.validate_tab1()
+
+    if is_valid:
+        session.tab1_complete = True
+        html = """
+        <div style="background: #e8f5e9; border: 1px solid #66bb6a; border-radius: 4px; padding: 10px;">
+            <span style="color: #2e7d32;">✓ Project information complete. Proceeding to Rooms tab...</span>
+        </div>
+        """
+        return session, html, 1  # Go to tab index 1 (Rooms)
+    else:
+        session.tab1_complete = False
+        error_items = "".join(f"<li>{e}</li>" for e in errors)
+        html = f"""
+        <div style="background: #ffebee; border: 1px solid #ef5350; border-radius: 4px; padding: 10px;">
+            <strong style="color: #c62828;">Please fix the following:</strong>
+            <ul style="margin: 5px 0 0 0; padding-left: 20px; color: #c62828;">
+                {error_items}
+            </ul>
+        </div>
+        """
+        return session, html, 0  # Stay on current tab
+
+
+def load_form_from_session(session: SessionState) -> tuple:
+    """Load form values from session state.
+
+    Returns:
+        Tuple of form values in component order.
+    """
+    p = session.project
+    return (
+        p.project_name,
+        p.address,
+        p.city,
+        p.state,
+        p.zip_code,
+        p.client_name,
+        p.fire_date,
+        p.assessment_date,
+        FACILITY_MAP_REVERSE.get(p.facility_classification, "Non-Operational"),
+        ERA_MAP_REVERSE.get(p.construction_era, "Post-2000"),
+        p.assessor_name,
+        p.assessor_credentials,
+    )