# AMDEP Demo Methodology And Deployment Path

This document is the operator-facing explanation for the AMDEP demo. It is written so a GC operator can explain what the demo is doing, why the synthetic packet is realistic enough to evaluate the workflow, what is actually machine learning, and how the product should be deployed after the demo.

## The Short Explanation

AMDEP is a project-staff deployment review system for commercial builders.

The demo loads a synthetic GC portfolio, shows the current staff plan, runs a constrained ML-assisted staffing review, then shows the recommended go-forward plan and the modeled economic impact. The point is not that the sample company is real. The point is that the workflow is real: ingest a staffing packet, validate it, score deployment risk, run a constraint-aware optimizer, produce recommendations, and keep every move in an operations approval queue before anything goes back into the systems of record.

The demo is built around a common GC problem: qualified staff get assigned based on incomplete information, habit, urgency, or whoever happens to be available in the meeting. That creates travel burden, superintendent and PM overload, retention risk, coverage gaps, QA/QC drag, safety-certification gaps, punch and closeout noise, change-order follow-up friction, and margin fade.

AMDEP makes those leaks visible, then gives operations a better staffing plan they can approve, override, or export.

## What The Current Demo Shows

The live packet is a deterministic synthetic portfolio.

- Personnel pool: 200 project staff profiles.
- Jobsites: 55 active commercial projects.
- Baseline assignments shown in the demo: 118.
- Optimized recommendation queue: 41 proposed moves.
- Top conflict findings: 66.
- Region model: Southwest Florida and Gulf Coast clusters.
- Horizon: 18 months.
- Current modeled 18-month impact: about $13.46 million.
- Annualized value-protection run-rate: about $8.97 million.
- Route capacity recovered: about 167 staff travel hours per day.
- Expected key-staff quits avoided in the sample: about 11.4.
- Current long-haul key-staff exposures: 27.
- Optimized long-haul key-staff exposures: 0.

Those values are calculated from the synthetic before and after packet. They are not customer ROI claims. In a real pilot, the same model structure would be calibrated against the customer's assignment history, job-cost data, actual outcomes, and operator overrides.

## How The Synthetic Sample Was Created

The sample is generated by `amdep/synthetic_data.py` using a fixed random seed, `DEFAULT_SEED = 1776`, so the demo is repeatable. It is randomized enough to feel messy, but structured enough to resemble a real regional commercial GC or CM operation.

The personnel data includes:

- names and roles;
- home region and coordinates;
- supervisor and crew mapping;
- skills such as project executive, senior PM, PM, APM, superintendent, assistant superintendent, project engineer, safety manager, quality manager, MEP coordinator, scheduler, closeout manager, and self-perform lead;
- certifications such as OSHA 30, First Aid/CPR, ICRA awareness, LEED AP, stormwater inspector, fall protection, safety trained supervisor, MEP coordination, permit coordination, quality management, and closeout documentation;
- hourly rate, fatigue base, reliability score, overtime history, long-haul assignment history, crew affinity, and preferred regions.

The jobsite data includes:

- region and coordinates;
- project type, including healthcare, hospitality, multifamily, education, municipal, office renovation, industrial, clubhouse/amenity, adaptive reuse, and commercial interiors;
- project phase, including preconstruction handoff, mobilization, foundations, structure, MEP rough-in, interiors, inspection readiness, closeout, turnover, and warranty;
- required headcount;
- required skills and certifications;
- urgency, weather risk, schedule volatility, inspection need, change-order exposure, and job status.

The baseline assignment layer intentionally uses an imperfect staffing heuristic. It creates the type of ad hoc assignment pattern that happens when the operation is busy: some people are sent too far, some roles are imperfectly matched, some certification coverage is weak, some jobs are short of coverage, and some project leaders absorb too much burden.

That creates a realistic starting point for the demo: not cartoonishly broken, but clearly full of avoidable leakage.

## What The ML Layer Does

AMDEP does not use an LLM to randomly invent staffing moves. The decision layer is structured.

The current demo has three parts:

1. Pair-feature generation.

   AMDEP builds candidate worker-to-job pairs and calculates features such as commute time, region match, skill fit, certification match, job urgency, overtime load, fatigue, crew compatibility, supervisor pressure, project phase, inspection need, schedule volatility, and robotics suitability.

2. Synthetic risk scoring.

   The demo trains synthetic models to prove the architecture for risk scoring. The implemented model families include logistic regression, random forest classifiers, and histogram gradient boosting classifiers. The demo model outputs include attrition and burden risk, delay risk, no-show risk, crew compatibility cost, and robotics suitability reward.

   These models prove the pipeline mechanics. They do not claim real-world predictive accuracy until trained on customer outcomes.

3. Constrained optimization.

   The optimizer is the core decision engine. It uses OR-Tools CP-SAT when available, with a deterministic greedy fallback if OR-Tools is unavailable.

   Hard constraints include:

   - one assignment per person per day;
   - required certification coverage;
   - project staffing targets;
   - supervisor capacity pressure.

   Soft costs include:

   - commute burden;
   - skill mismatch;
   - certification mismatch;
   - attrition and retention burden;
   - no-show and fatigue risk;
   - crew compatibility;
   - project urgency;
   - schedule delay exposure;
   - robotics or remote-capture suitability.

The optimizer is what turns the messy current plan into an operations review queue. The ML risk scores help the optimizer understand risk. The final answer is still constraint checked and review first.

## What The Calibration Gym Does

The calibration gym tests different policy weights on the synthetic portfolio. It changes how strongly the optimizer values travel reduction, skill fit, certification strictness, superintendent balance, retention protection, crew continuity, overtime reduction, robotics utilization, and job urgency.

In the demo, those weights are selected from synthetic trials. In production, weights should be learned and governed through a combination of:

- historical outcomes;
- executive policy preferences;
- operator overrides;
- region-specific constraints;
- project type and phase;
- seasonality;
- observed downstream effects.

The right production approach is not "one magic model." It is a governed decision stack:

- constrained optimizer for assignment decisions;
- calibrated predictive models for risk terms;
- transparent explanations for operators;
- override capture so the system learns how the company actually works.

## How The Economic Impact Is Modeled

The economic model is intentionally broader than route savings. Route savings alone would understate the value for a GC.

AMDEP models value leakage across ten buckets:

- retention and rehiring;
- management capacity;
- coverage gaps;
- role and OSHA/certification fit;
- schedule variance;
- QA, rework, punch, and closeout;
- change-order and admin drag;
- margin fade;
- admin bandwidth;
- compounding downstream effects.

The demo uses an 18-month horizon because staff deployment decisions do not only affect one week of driving. Bad deployment decisions compound across project cycles through burnout, missed coverage, PM and superintendent distraction, rework, turnover, rehiring, ramp-up, and job-cost drift.

The compounding term is capped. It exists because a staffing mistake is rarely isolated. A burned-out superintendent, an uncovered QA/QC need, or a two-hour daily commute can create second-order waste: missed handoffs, slower RFI and submittal follow-up, weaker closeout discipline, avoidable site trips, change-order lag, and preventable replacement hiring.

For a real customer, this model should be recalibrated against:

- assignment history;
- actual drive time or home-to-job geography;
- overtime;
- staffing gaps;
- turnover and quit dates;
- rehiring and ramp-up cost;
- job-cost history;
- schedule movement;
- RFIs, submittals, PCOs, CORs, and change orders;
- punch, closeout, warranty, and rework records;
- operator overrides and reasons.

## Why The Number Can Be Material

For a regional commercial builder, a few million dollars can be material if it protects senior staff, reduces avoidable admin load, and improves margin discipline. The demo's current 18-month value-protection figure is about $13.46 million for a synthetic peer-scale portfolio. That is large, but the premise is not just mileage. It includes key-staff retention, rehiring, ramp-up, management capacity, schedule leakage, QA/rework, closeout drag, admin load, and margin fade.

The correct way to present it:

"This is the synthetic midcase impact from the demo packet. The workflow is live. The dollar value becomes customer-specific after we calibrate it against their historical assignments, job-cost records, outcomes, and override history."

## What To Say To A GC Executive

Use this talk track:

"This is not another dashboard. It is a staffing review layer above the systems you already use. We import the current staff plan, jobsites, skills, certifications, project phase, urgency, and burden signals. Then AMDEP runs a constraint-checked review and gives operations a queue of recommended moves. Nothing writes back blindly. Your team approves, rejects, or overrides each move, and those overrides become training data.

The first win is visibility. The second win is better deployment decisions. The long-term win is a company-specific staffing intelligence layer that learns which assignments protect margin, retention, project coverage, and field execution."

## Pilot Posture

For a real organization, the first pilot should be read-only and review-first. AMDEP should accept the customer's existing staffing exports, spreadsheets, project lists, and roster files as they are, normalize them into the AMDEP ontology, and generate a recommendation queue. No approved customer system should be updated until an operator reviews the recommendation and records an approval or override.

The demo proves the staffing-review workflow. A pilot proves whether the customer's available data is strong enough to support calibrated deployment decisions.

## Production Data Needed

Minimum useful data:

- personnel roster;
- role, skills, certifications, supervisor, crew;
- home ZIP, depot, region, or coordinates;
- jobsite locations;
- project type, phase, urgency, required skills, and required certifications;
- current and historical assignments;
- basic schedule and staffing targets.

High-value calibration data:

- actual start and end times;
- overtime;
- no-shows and late arrivals;
- missed coverage;
- delays and constraint issues;
- callbacks, rework, punch, warranty, and closeout events;
- turnover, quit dates, and replacement cost;
- project financials, CTC movement, gross margin, PCO/COR/CO logs;
- dispatcher overrides and reasons.

The override trail matters. It teaches the system the difference between a mathematically clean answer and a field-practical answer.

## Security And Governance

The safest production posture is:

- read-only integration first;
- human approval before writeback;
- explicit override reasons;
- role-based access control;
- audit logs for every recommendation and action;
- customer-owned data;
- no private data in public repos;
- model versioning;
- time-based validation;
- drift monitoring;
- clear separation between demo weights and customer-calibrated weights.

The AI assistant can explain and navigate. The optimizer should decide only within approved constraints. Humans should retain authority for deployment changes.

## Research Basis

The demo's vocabulary and modeling choices are grounded in construction operations, project controls, productivity, and enterprise AI deployment patterns. Useful references:

- McKinsey on construction productivity and project delivery: https://www.mckinsey.com/capabilities/operations/our-insights/delivering-on-construction-productivity-is-no-longer-optional
- FMI / PlanGrid on disconnected construction work and non-optimal activity: https://pg.plangrid.com/rs/572-JSV-775/images/Construction_Disconnected.pdf
- BLS construction manager wage context: https://www.bls.gov/ooh/management/construction-managers.htm
- CMAA construction management functions: https://www.cmaanet.org/outline-cm-functions
- Lean Construction Institute planning standards: https://leanconstruction.org/
- Anthropic MCP documentation: https://docs.anthropic.com/en/docs/mcp
- Microsoft 365 Copilot connectors: https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/
- Google Gemini Enterprise connectors and data stores: https://cloud.google.com/agentspace/docs/introduction-to-connectors-and-data-stores

## Bottom Line

Ship the demo as a browser-based command center, not a native app. Use the public demo as proof of workflow. Use a private pilot to ingest real customer data. Package the production product as a review-first staffing intelligence layer plus enterprise AI skill pack. Add MCP and connector support so the system becomes the contractor's first useful AI operating workflow, not another disconnected app.