Chance Electro — AI Project Advisor

Google × Kaggle Vibe Coding Capstone — Track: Agents for Business

A photo of a hand-drawn plan from a job site becomes a complete estimate package — commercial proposal, invoice, shop order, and a GO / NO-GO profitability verdict — in about 15 minutes instead of 2–3 days of manual work.

Before: 2–3 days of on-site manual take-off and pricing. After: ~15 minutes — one napkin photo → proposal + invoice + shop order + GO/NO-GO.

Chance Electro is a fictional US electrical contractor, but the workflow is real — it models how a small contracting business actually estimates: a US-market-calibrated price list, a crew cost model, and a margin target the owner manages to. Cost and revenue are on the line on every job: misprice one cable gauge and the margin is gone.

---

Architecture

Three specialized agents talk over the open A2A protocol (HTTP). Agents 2 and 3 run in parallel. Every priced number comes from an MCP server, so proposal and margin can never drift apart. A security layer wraps every LLM call and every A2A boundary.

<details> <summary>Text version of the diagram</summary>

  napkin photo /          ┌───────────────────────────────┐
  PDF / text /   ───────▶ │   Web UI  ·  Orchestrator      │   A2A client
  voice / XLSX·DOCX       └───────────────┬───────────────┘
                                          │  A2A (HTTP)
                          ┌───────────────▼───────────────┐
                          │  Agent 1 · Project Analyst     │   Claude vision
                          │  (Agent Skill: cable sizing)   │   + gap-filling quiz
                          └───────────────┬───────────────┘
                                structured project
                          ┌───────────────┴───────────────┐
                          ▼  (A2A · in parallel)           ▼
             ┌────────────────────────┐      ┌────────────────────────┐
             │ Agent 2 · Document      │      │ Agent 3 · Profitability │
             │ Factory                 │      │ Advisor                 │
             └───────────┬─────────────┘      └────────────┬───────────┘
                         │  MCP tool call                   │  MCP tool call
                         └────────────────┬─────────────────┘
                             ┌────────────▼─────────────┐
                             │  MCP Pricing Server        │  price_estimate ·
                             │  (price list + economics + │  compute_margin ·
                             │   NEC cable standards)     │  recommend_cable ·
                             └────────────────────────────┘

  Guardrails wrap every LLM call and A2A border:
  input validation + magic-bytes · prompt-injection (multilingual, Unicode-normalised) ·
  output schema + prompt-leak screen · budget / kill-switch · audit trail

</details>

---

The six course concepts (this project uses five)

Concept	Where	How
Multi-agent system	code	3 independent A2A HTTP servers with agent cards; orchestrator/web are A2A clients; agents 2 & 3 run in parallel (agents/, serve.py, orchestrator.py)
MCP Server	code	mcp_server.py exposes the pricing/economics engine as MCP tools; all three agents are MCP clients at runtime (mcp_client.py) — no agent imports the engine directly; mcp_demo.py proves a standalone client↔server round trip
Agent Skills	code	skills/registry.py discovers skills on disk, selects by trigger, loads the body progressively, and invokes the skill's executable check (skills/electrical-estimating/), which drives a self-correction round in the analyst
Security features	code	guardrails.py — input + magic-byte validation, multilingual prompt-injection screen, output schema + prompt-leak screen, budget + kill-switch, and an audit trail; refusals return a clean HTTP 400
Deployability	video + code	Live on a VPS: 3 agents + MCP server + web, behind systemd + Caddy (HTTPS); shown in the video, reproducible from deploy/
Antigravity	—	not used (deliberate)

On the multi-agent stack: the agents interoperate over the open A2A (Agent2Agent) protocol — Google's cross-framework agent-interoperability standard, the same protocol ADK agents use to talk to agents built on other stacks. Each agent publishes a standard agent card at /.well-known/agent-card.json, and the orchestrator and web UI are plain A2A clients — so an ADK agent could discover and call these agents unchanged.

---

Economics (deterministic — no LLM)

Revenue comes from the price list; crew cost comes from one of two selectable models, so the GO/NO-GO verdict is exact and reproducible and the sandbox sliders recompute instantly (catalog.py::compute_economics):

• shares — by project value: R split into crew / foreman / overhead / subcontractor shares.
• hourly — by fully-burdened hourly rates × hours/day × days on site, plus a reverse calc ("max days on site that still keep the margin at target").
• GO/NO-GO = gross margin ≥ a configurable target (default 60%).

Cable pricing is gauge-accurate: the analyst classifies each circuit's load and picks the code-correct gauge (an oven feed gets 10 AWG (3×4mm²), not the default 12 AWG (3×2.5mm²)), which changes both the material spec and the labor price — an NEC-aligned estimating heuristic, not a stamped design.

---

Run it

Python 3.11.

python3.11 -m venv .venv
.venv/bin/pip install -r requirements.txt      # or: uv venv && uv pip install -r requirements.txt

# Web UI (recommended) — open http://localhost:8080
./web.sh
# Dry run, no Claude calls, deterministic (for graders — costs nothing):
CAPSTONE_MOCK=1 ./web.sh

# CLI end-to-end:
./run_all.sh --napkin napkin.jpg
CAPSTONE_MOCK=1 ./run_all.sh --text "kitchen, electric oven, 6 sockets" --mode hourly --days 2

# MCP client↔server proof (no LLM needed):
python mcp_demo.py

Deploying to a server (systemd + Caddy/HTTPS) — see deploy/DEPLOY.md. The web UI vendors its CSS/icon libraries under web/vendor/, so it stays fully functional offline (the Google-hosted display font degrades to system fonts if unreachable).

CAPSTONE_MOCK=1 runs the whole A2A pipeline with deterministic mocks — a grader can reproduce the demo without an API key or any spend. For live runs, copy .env.example to .env and set ANTHROPIC_API_KEY (never committed — .env is git-ignored).

The launchers start the MCP pricing server first, then the three agents (they are its clients), then the web UI, freeing their ports first so a stale process can't answer.

Observability: GET /ops aggregates each agent's LLM budget (calls, tokens, ~cost) and guardrail audit trail; the UI shows a "Run stats" line under the margin sandbox after a build.

---

Plug the pricing server into your own Claude (MCP)

The same MCP server the agents use plugs into Claude Desktop, Claude Code or Cursor over stdio — so you can price electrical work by just asking Claude. Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "chance-electro-pricing": {
      "command": "/absolute/path/to/chance-electro-capstone/.venv/bin/python",
      "args": ["/absolute/path/to/chance-electro-capstone/mcp_server.py"]
    }
  }
}

Then ask: "Which cable gauge does an electric oven feed need, and what does the run cost per foot?" — Claude calls list_load_categories → recommend_cable and answers from the price list instead of guessing. No API key is needed on the server side (the tools are deterministic); mcp_demo.py scripts the same round trip if you'd rather see it in a terminal.

---

Code map

agents/       base.py · analyst.py · document_factory.py · profitability.py  (A2A executors)
mcp_server.py    pricing/economics engine exposed as MCP tools
mcp_client.py    in-app MCP client — how the agents call the tools
catalog.py       price list + sandbox + deterministic economics (behind the MCP server)
guardrails.py    security layer (input / injection / output / budget / audit)
skills/          registry.py (skill runtime) + electrical-estimating/ (SKILL.md + scripts/)
schemas.py       JSON contracts + deterministic mocks
web/             app.py (A2A client) + index.html (6-step estimator wizard, US documents)
features/        Gherkin BDD spec (behavior, written before the code)
data/            price_list.json · sandbox.json · electrical_standards.json
                 (demos.json is created at runtime when you save a project in the UI)
run_all.sh · web.sh   launchers (MCP server + agents + orchestrator / web)
deploy/          systemd unit · Caddyfile example · DEPLOY.md
docs/            architecture.svg (rendered architecture diagram)
web/vendor/      vendored Tailwind + lucide (UI runs offline)

---

Known limitations

• Vision non-determinism — Claude vision can vary the scope it reads from one napkin; the estimate is a starting point a human confirms (HITL before anything is sent to a client).
• Wire-gauge notation — lengths and pricing are in US units (linear feet, USD) and wire gauges are AWG-first with the metric cross-section alongside — "12 AWG (3×2.5mm²)". The AWG mapping is ampacity-based, since the underlying price list is metric-derived.
• Estimating heuristic, not a stamped design — cable sizing is NEC-aligned for estimating, not a substitute for a licensed load calculation on large feeders.