Build a Reclaimed Building Material Marketplace Matcher — implementation

## Build
Evaluate demolition salvage manifests against architectural specifications to match reclaimed structural timber and fixtures. Quantify embodied carbon savings and verify dimensional allowances.

## User
Circular Economy Procurement Specialist

## Workflow
1. Ingest reclaimed inventory logs with material grade, dimensions, and salvage conditions.
2. Parse proposed building bill of materials to identify candidate replacement elements.
3. Calculate dimensional fit within allowable tolerances and estimated carbon offset.
4. Emit structured reuse substitution proposal for architect and structural engineer approval.

## Interface
Material pairing interface showing dimension deltas, grade matches, and carbon savings counters.

## Data
Use mock salvage records patterned on open circular construction logs from urban deconstruction projects.
Starter examples below are synthetic. They are not downloaded records.

## Source
[IfcOpenShell](https://raw.githubusercontent.com/IfcOpenShell/IfcOpenShell/v0.8.0/README.md)
Employs IfcOpenShell ifc5d concepts for material quantity extraction and inventory cost/carbon tracking.

## Tools
dspy, pandas, fastapi.
DSPy systematically optimizes the few-shot prompting required to match heterogeneous material grade descriptions.
Instruction-tuned model with consistent quantitative calculation and string normalization.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Rejects salvage items failing minimum required architectural length or structural grade.
- Emits carbon savings based on virgin steel or timber displacement factors.
- Produces line-item substitution table ready for procurement review.

## Starter Examples
```json
[
  {
    "input": {
      "demand_item": {
        "item_id": "BEAM-REQ-01",
        "material": "Glulam Timber",
        "min_length_m": 4.5,
        "min_depth_mm": 240,
        "min_grade": "GL24"
      },
      "salvage_item": {
        "salvage_id": "DEMO-TIMB-88",
        "material": "Glulam Timber",
        "length_m": 4.8,
        "depth_mm": 240,
        "grade": "GL28",
        "embodied_carbon_saved_kgco2e": 320
      }
    },
    "expected_output": {
      "match_status": "ACCEPTED",
      "trimming_waste_m": 0.3,
      "carbon_offset_kgco2e": 320,
      "substitution_approved_for_review": true
    }
  },
  {
    "input": {
      "demand_item": {
        "item_id": "STEEL-REQ-04",
        "material": "Structural Steel I-Beam",
        "min_length_m": 6,
        "min_depth_mm": 300,
        "min_grade": "S355"
      },
      "salvage_item": {
        "salvage_id": "DEMO-STL-12",
        "material": "Structural Steel I-Beam",
        "length_m": 5.2,
        "depth_mm": 300,
        "grade": "S355",
        "embodied_carbon_saved_kgco2e": 450
      }
    },
    "expected_output": {
      "match_status": "REJECTED",
      "reason": "Insufficient salvage length (5.2m < required 6.0m)",
      "carbon_offset_kgco2e": 0,
      "substitution_approved_for_review": false
    }
  }
]
```

## Safety
All material substitutions are provisional and require destructive or non-destructive certified laboratory testing.
Use mock external writes. Require human review before any real deployment.