Chance Electro Pricing

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, contract, invoice, shop order, and a GO / NO-GO profitability verdict — in about 10 minutes instead of 2–3 days of manual work.

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

The solution is real and in use: it was built for a real small electrical contractor and runs in their process. "Chance Electro" is its US-localized presentation for this capstone — names, currency (USD), units (feet / AWG) and the price list are calibrated to the US market so graders can evaluate it in familiar terms. Cost and revenue are on the line on every job.

---

Architecture

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

  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

---

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). Plus adk_orchestrator.py — a Google ADK agent that drives the same pipeline (ADK↔A2A) and reads the pricing tools via ADK McpToolset (ADK↔MCP)
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	Live at https://electro.team247.online: 3 agents + MCP server + web, behind systemd + Caddy (HTTPS); reproduced from deploy/. Shown in the demo video
Antigravity	—	not used (deliberate)

---

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 cross-section (an oven feed gets 3×4, not a default 3×2.5), which changes both the material spec and the labor price — an NEC-aligned estimating heuristic, not a stamped design.

---

Run it

Python 3.11, dependencies via uv:

git clone https://github.com/barmanoff/chance-electro-capstone.git
cd chance-electro-capstone
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 plan.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

# Google ADK proof — an ADK agent drives the same A2A pipeline + reads the MCP tools (keyless):
uv pip install -r requirements-adk.txt   # optional extra; the core pipeline does not need it
CAPSTONE_MOCK=1 ./web.sh &               # bring the MCP server + 3 agents up first
python adk_orchestrator.py

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 public demo at https://electro.team247.online runs the real pipeline behind a small spend ceiling (the budget guardrail). If the ceiling is ever hit you'll get a clean HTTP 400 refusal — that guardrail working as designed; the keyless mock run above reproduces everything locally at zero cost.

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.

---

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
adk_orchestrator.py   Google ADK agent that orchestrates the A2A pipeline + MCP (ADK proof)
run_all.sh · web.sh   launchers (MCP server + agents + orchestrator / web)

---

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).
• Cable spec is an estimating localization — cross-sections are shown AWG-first (US) with the metric mm² equivalence alongside; pricing is US-calibrated. A deliberate, consistent choice.
• Estimating heuristic, not a stamped design — cable sizing is NEC-aligned for estimating, not a substitute for a licensed load calculation on large feeders.