---
name: construction-takeoff
description: Automated construction quantity surveying from PDF plans using AI. Processes construction drawings, extracts quantities/materials, analyzes competitor solutions via Firecrawl, calculates costs, and generates Excel-based takeoff reports for stakeholder collaboration.
---

# Construction Takeoff Agent

Agentic AI system for automated construction quantity surveying from PDF construction plans.

## Overview

The Construction Takeoff Agent is a specialized LangGraph orchestration that processes PDF construction plans (site plans, floor plans, elevations, details) to extract quantities, materials, and measurements. It integrates competitive intelligence via Firecrawl API and generates comprehensive Excel workbooks suitable for stakeholder collaboration.

## Core Capabilities

### 1. PDF Plan Analysis
- Processes construction plans using Claude's native vision capabilities
- Supports multiple drawing types: site plans, floor plans, elevations, details
- Extracts drawing scale, dimensions, annotations, and specifications
- Handles multi-page PDFs with page-by-page analysis

### 2. Quantity Extraction
- Identifies and quantifies construction materials
- Categorizes items by CSI MasterFormat divisions:
  - Earthwork (excavation, grading, fill)
  - Concrete (slabs, footings, walls, columns)
  - Masonry (brick, block, stone)
  - Metals (structural steel, rebar)
  - Wood & Plastics (framing, joists, decking)
  - Finishes (drywall, paint, flooring, tile)
  - Site Work (paving, curbs, landscaping, utilities)
  - Mechanical/Electrical/Plumbing systems
- Measures areas, linear dimensions, and volumes
- Counts discrete items (doors, windows, fixtures)

### 3. Competitor Analysis (via Firecrawl)
- Scrapes leading construction takeoff solutions:
  - PlanSwift
  - Bluebeam Revu
  - On-Screen Takeoff
  - STACK Construction Technologies
- Extracts competitor features and automation capabilities
- Identifies best practices and differentiators
- Incorporates insights into report generation

### 4. Cost Estimation
- Calculates material costs using Florida market unit prices (2025)
- Estimates labor hours per construction task
- Applies labor rates ($75/hour for Florida construction)
- Provides detailed cost breakdown by category
- Generates total project estimate (materials + labor)

### 5. Excel Report Generation
- Creates multi-sheet workbook:
  - **Project Summary:** Overview, cost totals, labor hours
  - **Detailed Takeoff:** Line-item quantities with unit costs
  - **Materials List:** Categorized materials with specifications
  - **Competitor Insights:** Features and best practices discovered
- Professional formatting with headers, colors, borders
- Currency and number formatting
- Auto-sized columns for readability

### 6. Supabase Integration
- Logs all takeoff results to `insights` table
- Category: `spd_construction_takeoff`
- Stores project metadata, costs, report paths
- Enables historical analysis and reporting

## Workflow Stages

```
1. PDF Processing → Analyze construction plans with Claude Vision
2. Quantity Extraction → Structure quantities using AI
3. Competitor Analysis → Scrape competitors via Firecrawl
4. Cost Calculation → Apply unit costs and labor rates
5. Report Generation → Create Excel workbook
6. Supabase Logging → Store results for tracking
```

## Usage

### Via GitHub Actions (Recommended)

Trigger the workflow from GitHub Actions UI or API:

```bash
curl -X POST \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/breverdbidder/spd-site-plan-dev/actions/workflows/construction_takeoff_workflow.yml/dispatches \
  -d '{
    "ref": "main",
    "inputs": {
      "pdf_url": "https://example.com/construction_plan.pdf",
      "project_name": "Bliss Palm Bay Phase 2",
      "project_id": "SPD-2025-003"
    }
  }'
```

### Via Python API

```python
from construction_takeoff_agent import run_construction_takeoff

result = run_construction_takeoff(
    pdf_path="/path/to/construction_plan.pdf",
    project_name="Bliss Palm Bay Phase 2",
    project_id="SPD-2025-003"
)

print(f"Total Cost: ${result['total_estimated_cost']:,.2f}")
print(f"Excel Report: {result['excel_path']}")
```

### CLI Usage

```bash
python construction_takeoff_agent.py \
  /path/to/construction_plan.pdf \
  "Bliss Palm Bay Phase 2" \
  "SPD-2025-003"
```

## Configuration

### Environment Variables

Required:
- `ANTHROPIC_API_KEY` - Claude API for PDF analysis and quantity extraction
- `SUPABASE_SERVICE_ROLE_KEY` - Database logging

Optional:
- `FIRECRAWL_API_KEY` - Competitor analysis (skipped if not provided)

### Unit Cost Database

The agent includes Florida construction market unit costs (2025). Modify `UNIT_COSTS` dictionary in the agent file to update:

```python
UNIT_COSTS = {
    "excavation": {"unit": "CY", "cost": 12.50, "labor_hours": 0.05},
    "concrete_slab": {"unit": "CY", "cost": 150.00, "labor_hours": 0.75},
    # ... add more items
}
```

### Competitor Targets

Configure competitor sites to analyze in `COMPETITOR_TARGETS`:

```python
COMPETITOR_TARGETS = [
    {
        "name": "PlanSwift",
        "url": "https://www.planswift.com",
        "focus": "Digital takeoff and estimating software"
    },
    # ... add more competitors
]
```

## Output Format

### Excel Workbook Structure

**Sheet 1: Project Summary**
- Project metadata (name, ID, date, drawing type, scale)
- Cost summary (materials, labor, total)

**Sheet 2: Detailed Takeoff**
| Item | Quantity | Unit | Unit Cost | Total Cost | Labor Hours | Category |
|------|----------|------|-----------|------------|-------------|----------|
| Excavation | 250 | CY | $12.50 | $3,125.00 | 12.5 | earthwork |
| Concrete Slab | 50 | CY | $150.00 | $7,500.00 | 37.5 | concrete |

**Sheet 3: Materials List**
| Material | Quantity | Unit | Category | Specification |
|----------|----------|------|----------|---------------|
| 3000 PSI Concrete | 50 | CY | concrete | Ready-mix |

**Sheet 4: Competitor Insights**
- Features by competitor
- Best practices identified
- Automation capabilities

## Integration with API Mega Library

The agent references the API mega library located at:
- Repository: `breverdbidder/life-os`
- Path: `docs/API_MEGA_LIBRARY.md`
- Contains 10,498+ APIs including construction, estimation, and automation tools

The agent can be extended with additional APIs from the mega library:
- **Construction APIs:** Procore, Buildertrend, CoConstruct
- **Estimation APIs:** HCSS HeavyBid, B2W Estimate
- **Document Processing:** Adobe PDF Services, DocParser
- **Computer Vision:** Google Cloud Vision, AWS Textract

## Best Practices Cloned from Competitors

Based on Firecrawl analysis, the agent incorporates:

1. **Auto-scaling from drawings** (PlanSwift pattern)
2. **Multi-trade categorization** (Bluebeam approach)
3. **Assembly-based costing** (On-Screen Takeoff method)
4. **Real-time collaboration** (STACK model)
5. **Cloud-based storage** (Industry standard)

## Performance Metrics

- **PDF Processing:** ~30 seconds per page (Claude Vision)
- **Competitor Scraping:** ~20 seconds per site (Firecrawl)
- **Cost Calculation:** <5 seconds
- **Excel Generation:** <10 seconds
- **Total Workflow:** ~2-5 minutes for typical single-page plan

## Limitations & Future Enhancements

### Current Limitations
- Manual PDF upload required (no automatic discovery)
- Single drawing analysis (batch processing not yet implemented)
- Static unit cost database (not market-integrated)
- Limited to PDF format (no DWG/DXF CAD files)

### Planned Enhancements
- Integration with RSMeans cost database
- CAD file format support (DWG, DXF, RVT)
- Machine learning for quantity prediction
- Historical project comparison
- Multi-project batch processing
- Real-time collaboration features
- Mobile app for field verification

## Cost Analysis

### Per-Takeoff Costs
- Claude API (PDF analysis): ~$0.15-0.30 per page
- Firecrawl (competitor scraping): ~$0.03 per site
- Supabase (logging): <$0.01
- GitHub Actions (compute): Free tier

**Total per takeoff:** ~$0.20-0.50

### ROI Calculation
Traditional manual takeoff: 4-8 hours @ $75/hour = $300-600
Automated takeoff: 5 minutes + $0.50 = ~$10-20 equivalent

**Time savings:** 95-98%
**Cost savings:** 95-97%

## Repository Structure

```
spd-site-plan-dev/
├── agents/
│   └── orchestrator/
│       └── construction_takeoff_agent.py    # Main agent
├── .github/
│   └── workflows/
│       └── construction_takeoff_workflow.yml # GitHub Actions
├── skills/
│   └── construction-takeoff/
│       └── SKILL.md                         # This file
├── reports/
│   └── takeoff_reports/                     # Generated Excel reports
└── docs/
    └── CONSTRUCTION_TAKEOFF.md              # Extended documentation
```

## Supabase Schema

The agent logs to the `insights` table:

```sql
{
  "category": "spd_construction_takeoff",
  "insight_type": "takeoff_report",
  "insight_data": {
    "project_id": "SPD-2025-003",
    "project_name": "Bliss Palm Bay Phase 2",
    "drawing_type": "site_plan",
    "total_quantities": 45,
    "total_materials": 32,
    "total_cost": 125000.00,
    "labor_hours": 520.5,
    "competitors_analyzed": ["PlanSwift", "Bluebeam Revu"],
    "excel_report": "/tmp/spd_takeoff_reports/takeoff_SPD-2025-003_20251219_143022.xlsx",
    "status": "completed",
    "timestamp": "2025-12-19T14:30:22Z"
  }
}
```

## Support & Troubleshooting

### Common Issues

**Issue:** PDF processing fails with "invalid format"
**Solution:** Ensure PDF is not password-protected or corrupted

**Issue:** Firecrawl returns 401 Unauthorized
**Solution:** Verify `FIRECRAWL_API_KEY` environment variable is set

**Issue:** Unit costs seem inaccurate
**Solution:** Update `UNIT_COSTS` dictionary with current market rates

**Issue:** Excel report missing competitor insights
**Solution:** Verify Firecrawl API key and check rate limits

### Debug Mode

Enable verbose logging:

```python
import logging
logging.basicConfig(level=logging.DEBUG)

result = run_construction_takeoff(pdf_path, project_name)
```

## Security Considerations

- PDF files may contain sensitive project information
- Store reports in secure locations
- Rotate API keys regularly
- Use Supabase Row Level Security (RLS) for insights table
- Sanitize file paths to prevent directory traversal

## License & Attribution

- Agent: Everest Capital USA / BidDeed.AI
- LangGraph: LangChain Inc.
- Claude API: Anthropic
- Firecrawl: Mendable AI
- OpenPyXL: Open source (MIT)

## Changelog

### v1.0.0 (2025-12-19)
- Initial release
- PDF construction plan processing
- Automated quantity extraction
- Competitor analysis via Firecrawl
- Excel report generation
- Supabase integration
- GitHub Actions workflow

---

**Maintained by:** Claude Sonnet 4.5 (AI Architect)
**Repository:** github.com/breverdbidder/spd-site-plan-dev
**Stack:** LangGraph + Anthropic Claude + Firecrawl + OpenPyXL + Supabase