AI-powered platform that ingests construction bid documents (PDFs, DXF/DWG, DOCX, images) and produces quantity takeoffs, cost estimates, and construction schedules — all driven by Anthropic claude-sonnet-4-6.
┌──────────────────────────────────────────────────────────────────┐
│ FastAPI (port 8000) │
│ │
│ /api/v1/auth /api/v1/documents /api/v1/takeoffs │
│ /api/v1/estimates /api/v1/schedules │
│ /api/v1/process-bid /api/v1/analyze-documents /health │
└─────────────────────────────┬────────────────────────────────────┘
│
┌──────────▼──────────┐
│ AICoordinator │
│ (orchestrates all │
│ agents in order) │
└──┬──┬──┬──┬──┬──────┘
│ │ │ │ │
┌───────────┘ │ │ │ └──────────────┐
│ ┌─────┘ └─────┐ │
▼ ▼ ▼ ▼
┌────────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐
│ Document │ │ Utilities │ │ Earthwork │ │ Estimating │
│ Parser │ │ Agent │ │ Agent │ │ Agent │
│(classify + │ │(pipe len, │ │(cut/fill, │ │(RSMeans line │
│ OCR/DXF) │ │ structures│ │ volumes) │ │ items) │
└────────────┘ └───────────┘ └───────────┘ └──────────────┘
│
┌────────▼────────┐
│ Scheduling │
│ Agent │
│(phases, critical │
│ path, CPM) │
└─────────────────┘
│
┌──────────────────────┼───────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PostgreSQL │ │ Redis 7 │ │ Anthropic │
│ 16 + async │ │ (cache / │ │ claude- │
│ SQLAlchemy │ │ sessions) │ │ sonnet-4-6 │
│ + Alembic │ └──────────────┘ └──────────────┘
└──────────────┘
- Docker >= 24 and Docker Compose v2
- An Anthropic API key (
ANTHROPIC_API_KEY) - (Optional) A Sentry DSN for error tracking
# 1. Clone and enter the repo
git clone <repo-url>
cd ai-construction-suite
# 2. Configure environment
cp .env.example .env
# Edit .env — at minimum set ANTHROPIC_API_KEY and JWT_SECRET
# 3. Generate a secure JWT secret
openssl rand -hex 32
# 4. Start all services (API + DB + Redis + frontend)
docker compose up --build
# API: http://localhost:8000
# API docs: http://localhost:8000/docs
# Frontend: http://localhost:5173docker compose exec app alembic upgrade headdocker compose exec app pytest --cov=. tests/All endpoints under /api/v1/ require Authorization: Bearer <token> except the auth routes.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /register |
No | Register a new user, returns JWT |
| POST | /login |
No | Authenticate, returns JWT |
Request body (both):
{ "email": "[email protected]", "password": "secret" }| Method | Path | Description |
|---|---|---|
| POST | /upload |
Upload one or more files to a project |
| GET | /{document_id} |
Retrieve document metadata by ID |
| GET | / |
List documents (optional ?project_id=<uuid>) |
Upload query params: ?project_id=<uuid>
Accepted types: .pdf, .dxf, .dwg, .xlsx, .docx, .png, .jpg, .jpeg
Max file size: configured via MAX_FILE_SIZE_MB (default 50 MB)
| Method | Path | Description |
|---|---|---|
| POST | / |
Run a quantity takeoff on documents |
| GET | /{takeoff_id} |
Retrieve takeoff results |
POST body:
{
"project_id": "<uuid>",
"document_ids": ["<uuid>", "..."],
"discipline": "utilities"
}discipline must be "utilities" or "earthwork".
| Method | Path | Description |
|---|---|---|
| POST | / |
Generate cost estimate from takeoffs |
| GET | /{estimate_id} |
Retrieve estimate details |
POST body:
{
"project_id": "<uuid>",
"takeoff_ids": ["<uuid>", "..."],
"project_details": {}
}| Method | Path | Description |
|---|---|---|
| POST | / |
Generate project schedule from an estimate |
POST body:
{
"project_id": "<uuid>",
"estimate_id": "<uuid>",
"constraints": {}
}| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/v1/process-bid |
Yes | Full pipeline: parse → takeoff → estimate → schedule |
| POST | /api/v1/analyze-documents |
Yes | Classify and extract text from uploaded documents |
| GET | /health |
No | PostgreSQL + Redis health check |
| GET | / |
No | Version info |
Orchestrates the full bid pipeline. Accepts uploaded files, fans out to the document parser and takeoff agents concurrently, then sequences the estimating and scheduling agents. Enforces MAX_CONCURRENT_REQUESTS via an in-process counter. Entry points: process_bid() and analyze_documents().
Extracts text from PDFs (PyMuPDF with pytesseract OCR fallback), images (pytesseract), DXF files (ezdxf), and DOCX files. Calls claude-sonnet-4-6 to classify each document into one of: utility_plans, grading_plans, specifications, bid_forms, general.
Extracts underground utility quantities from classified plan text: pipe lengths by material and diameter, structure counts (manholes, catch basins, cleanouts, fire hydrants). Returns structured JSON with total_pipe_length_ft, total_structures, per-type breakdowns, and a confidence score.
Calculates earthwork volumes from grading plan text: cut CY, fill CY, topsoil CY, import/export volumes, stripping acreage. Returns structured JSON with per-item line entries and a confidence score.
Produces detailed cost estimates from takeoff quantities using RSMeans national average pricing. Returns CSI-coded line items (description, quantity, unit, unit cost, total), a 10% contingency, total project cost (USD), assumptions, and a confidence score.
Generates a construction schedule from an estimate. Outputs phases with durations and resource assignments, predecessor relationships, project milestones, critical path identification, cost allocation percentages, total project duration in calendar days, and a confidence score.
Copy .env.example to .env and fill in required values.
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL |
yes | postgresql+asyncpg://... |
Async PostgreSQL connection string |
REDIS_URL |
yes | redis://localhost:6379/0 |
Redis connection string |
ANTHROPIC_API_KEY |
yes | — | Anthropic API key for all AI agents |
JWT_SECRET |
yes | (insecure placeholder) | Min 32-char random secret — openssl rand -hex 32 |
JWT_ALGORITHM |
no | HS256 |
JWT signing algorithm |
JWT_EXPIRE_MINUTES |
no | 60 |
Token lifetime in minutes |
UPLOAD_DIR |
no | /tmp/uploads |
Directory for uploaded files |
MAX_FILE_SIZE_MB |
no | 50 |
Maximum upload file size per file |
CORS_ORIGINS |
no | ["http://localhost:3000", ...] |
JSON list of allowed CORS origins |
ENVIRONMENT |
no | development |
development or production |
MAX_CONCURRENT_REQUESTS |
no | 10 |
Coordinator concurrency cap |
SENTRY_DSN |
no | (empty) | Sentry DSN for error tracking |
DB_PASSWORD |
no | postgres |
PostgreSQL password (docker-compose only) |
| Layer | Technology |
|---|---|
| API framework | FastAPI + Uvicorn |
| ORM / DB | SQLAlchemy 2 (async) + asyncpg |
| Migrations | Alembic |
| Database | PostgreSQL 16 |
| Cache | Redis 7 |
| AI model | Anthropic claude-sonnet-4-6 |
| Document parsing | PyMuPDF, pytesseract, ezdxf, python-docx |
| Auth | JWT (python-jose) + bcrypt (passlib) |
| Monitoring | Prometheus metrics + optional Sentry |
| Logging | structlog (JSON in production) |
| Containers | Docker Compose |
| Frontend | React 18 + TypeScript + Vite (port 5173) |
ai-construction-suite/
├── api/routes/ # FastAPI route handlers
│ ├── auth.py
│ ├── documents.py
│ ├── estimates.py
│ ├── schedules.py
│ └── takeoffs.py
├── services/ # AI agent implementations
│ ├── coordinator/
│ ├── document_parser/
│ ├── earthwork_agent/
│ ├── estimating_agent/
│ ├── scheduling_agent/
│ └── utilities_agent/
├── shared/
│ ├── models/ # SQLAlchemy ORM models + engine
│ └── utils/ # Auth, config, logging, monitoring, OCR, CAD parsing
├── alembic/ # Database migrations
├── tests/ # pytest test suite
├── frontend/ # React + Vite UI (scaffolded)
├── main.py # Application entry point
├── docker-compose.yml
├── .env.example
└── AUDIT.md # Security and quality audit findings
MIT — see LICENSE.