# 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, 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](https://github.com/astral-sh/uv):

```bash
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.